Reference

Errors

Every error skawld throws extends SkawldError and carries a stable kind discriminator plus a retryable flag. The loop catches recoverable provider errors and retries them internally; what escapes session.run() is something you need to decide about.

errors.ts

import {
  ProviderError,
  PermissionDeniedError,
  AbortError,
  ContextLengthError,
} from "@skawld/agent-sdk";

try {
  for await (const _ of session.run(prompt)) { /* … */ }
} catch (err) {
  if (err instanceof PermissionDeniedError) {
    console.warn("blocked by policy:", err.tool_name, err.reason);
  } else if (err instanceof ProviderError) {
    console.error("provider gave up:", err.status, err.message);
  } else if (err instanceof AbortError) {
    // user pressed Ctrl+C or signal aborted
  } else if (err instanceof ContextLengthError) {
    // compaction couldn't shrink enough
  } else {
    throw err;
  }
}

#Error classes

Error	kind	When thrown
AuthError	auth	API key missing or rejected.
RateLimitError	rate_limit	Provider returned 429. Retryable; carries an optional `retry_after_seconds`.
ContextLengthError	context_length	Compaction couldn’t shrink the conversation enough to fit another turn.
PermissionDeniedError	permission_denied	A tool call was blocked by a deny rule or the `canUseTool` callback. Carries `tool_name` and `reason`.
ToolExecutionError	tool_execution	A tool’s `execute()` threw outside the validated schema path.
AbortError	abort	The run was cancelled via `AbortSignal` or Ctrl+C.
ProviderError	provider	The model API returned a non-recoverable status, or retries were exhausted. Carries an optional `status`.
ConfigError	config	Misconfiguration at Agent construction — missing provider, missing model, invalid retry count.
SkillError	skill	A skill failed to load (bad frontmatter, missing file). Non-fatal; the affected skill is skipped.

#Handling errors

Use instanceof to narrow. The error’s retryable field tells you whether re-running might help — rate limits and 5xxs are retryable, auth failures and config errors aren’t. RateLimitError.retry_after_seconds is the polite delay to honour before retrying.