errfmt

Documentation

Overview

Package errfmt classifies errors and produces user-facing display text with actionable hints. It is the single seam between raw provider/network errors and the UI — callers pass any error, errfmt decides whether to augment it.

Classification order: most-specific first (local-server auth before generic auth, rate-limit before server-error). Unknown errors return nil from HintsForError and fall through to raw err.Error() in FormatForDisplay.

Index

• func FormatForDisplay(err error) string
• func ToolErr(code ToolErrorCode, summary, hint string) *core.ToolResult
• type AuthDiagnosticCode
• type ErrorHint
  • func HintsForError(err error) *ErrorHint
• type ParsedToolError
  • func ParseToolError(text string) *ParsedToolError
• type ToolErrorCode

Functions

func FormatForDisplay

func FormatForDisplay(err error) string

FormatForDisplay returns a display-ready string. If no hint is found it returns err.Error() unchanged. Otherwise it renders Summary followed by each hint as a bullet.

func ToolErr

func ToolErr(code ToolErrorCode, summary, hint string) *core.ToolResult

ToolErr builds a *core.ToolResult representing a coded tool error. Format (exact):

[error:CODE] <summary>
hint: <hint>        (omitted if hint is empty)

code must be uppercase snake_case (extensions may define custom codes). summary must be non-empty, one line, no trailing period. hint may be empty; when non-empty, it should be an actionable sentence.

Types

type AuthDiagnosticCode

type AuthDiagnosticCode string

AuthDiagnosticCode is a stable string identifier for authentication error subtypes. Extensions may inspect this programmatically.

const (
	AuthMissingAPIKey AuthDiagnosticCode = "auth.missing_api_key"
	AuthLocalServer   AuthDiagnosticCode = "auth.local_server"
	AuthInvalidKey    AuthDiagnosticCode = "auth.invalid_key"
)

type ErrorHint

type ErrorHint struct {
	Summary  string             // one-line description of what went wrong
	Hints    []string           // actionable steps, each a complete sentence or command
	DiagCode AuthDiagnosticCode // empty for non-auth errors
}

ErrorHint describes what went wrong and what the user can do about it.

func HintsForError

func HintsForError(err error) *ErrorHint

HintsForError classifies err and returns a hint. Returns nil for nil errors and for errors that don't match any known pattern.

type ParsedToolError

type ParsedToolError struct {
	Code    ToolErrorCode
	Summary string
	Hint    string
	Body    string // anything after the header+hint (empty for most cases)
}

ParsedToolError holds the fields extracted from a coded tool-error text.

func ParseToolError

func ParseToolError(text string) *ParsedToolError

ParseToolError extracts the code/summary/hint from text produced by ToolErr. Returns nil if text does not start with the "[error:" prefix. Tolerates a trailing body after the hint (or after the header if hint is absent) separated by a blank line.

type ToolErrorCode

type ToolErrorCode string

ToolErrorCode is a stable machine-readable identifier for tool-execution failures. Consumers (LLMs via prefix matching, interceptors via ParseToolError) can branch on these codes to decide whether to retry, reword, or abort.

Extensions may define their own codes — pass any uppercase snake_case string to ToolErr. The core set below covers the compiled-in tools.

const (
	// ToolErrInvalidArgs — required argument missing, wrong type, or empty.
	// Recovery: fix arguments and retry.
	ToolErrInvalidArgs ToolErrorCode = "INVALID_ARGS"

	// ToolErrFileNotFound — path does not exist, or stat failed with ENOENT.
	// Recovery: verify path; consider running `find`/`grep` first.
	ToolErrFileNotFound ToolErrorCode = "FILE_NOT_FOUND"

	// ToolErrFileStale — TOCTOU mtime mismatch between last read and current write.
	// Recovery: re-read the file before writing.
	ToolErrFileStale ToolErrorCode = "FILE_STALE"

	// ToolErrFileTooLarge — file exceeds the tool's size limit.
	// Recovery: use offset/limit, or process in chunks.
	ToolErrFileTooLarge ToolErrorCode = "FILE_TOO_LARGE"

	// ToolErrNotRegularFile — target is a directory, symlink loop, device, etc.
	// Recovery: target a regular file.
	ToolErrNotRegularFile ToolErrorCode = "NOT_REGULAR_FILE"

	// ToolErrPermissionDenied — OS permission error (EACCES).
	// Recovery: cannot be resolved from within the tool — surface to user.
	ToolErrPermissionDenied ToolErrorCode = "PERMISSION_DENIED"

	// ToolErrNotUnique — edit's old_text matched zero or multiple locations.
	// Recovery: add surrounding context to make the match unique.
	ToolErrNotUnique ToolErrorCode = "NOT_UNIQUE"

	// ToolErrTimeout — operation exceeded its deadline (e.g. bash).
	// Recovery: increase timeout or run a narrower command.
	ToolErrTimeout ToolErrorCode = "TIMEOUT"

	// ToolErrExitNonzero — subprocess finished with non-zero exit code.
	// Recovery: inspect stderr; may be expected (grep: no matches).
	ToolErrExitNonzero ToolErrorCode = "EXIT_NONZERO"

	// ToolErrIO — unclassified I/O error (read, write, mkdir).
	// Recovery: inspect message; often transient.
	ToolErrIO ToolErrorCode = "IO_ERROR"

	// ToolErrInternal — bug in the tool itself (panic recovered, invariant broken).
	// Recovery: report; not user-actionable.
	ToolErrInternal ToolErrorCode = "INTERNAL"

	// ToolErrInterrupted — tool execution did not complete because the session was
	// interrupted (crash, kill -9) before the result was recorded.
	// Recovery: the agent will synthesize a placeholder result; retry if needed.
	ToolErrInterrupted ToolErrorCode = "TOOL_INTERRUPTED"

	// ToolErrToolDisabled — tool has been disabled by the circuit breaker after
	// too many consecutive errors.
	// Recovery: fix the tool invocation or /clear to reset the session breaker state.
	ToolErrToolDisabled ToolErrorCode = "TOOL_DISABLED"
)