@threadplane/chatClassv0.3.4

AgentError

Structured, classified failure surfaced on Agent.error. Extends Error, so existing .message / instanceof Error reads keep working — but adds a machine-readable AgentErrorKind, a retryable flag, an optional HTTP status, and the original cause.

You rarely construct one yourself; adapters normalize raw failures via toAgentError. Read it off the agent to render legible, cause-specific UI:

View source View Markdown

import { AgentError } from '@threadplane/chat';

Declaration

export declare class AgentError extends Error  {
  constructor(init: {
        kind: AgentErrorKind;
        message: string;
        retryable: boolean;
        status?: number;
        cause?: unknown;
        recovery?: AgentRecovery;
        detail?: string;
    });
  readonly cause: unknown;
  readonly detail?: string;
  readonly kind: AgentErrorKind;
  readonly recovery?: AgentRecovery;
  readonly retryable: boolean;
  readonly status?: number;
}

Examples

const err = agent.error();            // AgentError | undefined
if (err) {
  console.warn(err.message);          // legible, per-kind copy
  if (err.kind === 'auth') showApiKeyHelp();
  if (err.retryable) showRetryButton(); // → agent.retry()
}

Members

Constructor · overload 1

Constructs a new instance of the AgentError class

constructor(init: {
        kind: AgentErrorKind;
        message: string;
        retryable: boolean;
        status?: number;
        cause?: unknown;
        recovery?: AgentRecovery;
        detail?: string;
    });

Parameters

init · required: { kind: AgentErrorKind; message: string; retryable: boolean; status?: number; cause?: unknown; recovery?: AgentRecovery; detail?: string; }

cause

The original raw error this was classified from, preserved for debugging/telemetry.

readonly cause: unknown;

detail

A short sentence explaining the uncertainty. Adapters set this whenever recovery is check or none, and leave it undefined otherwise. It is the only thing a caller can show when recovery is check but the agent exposes no checkStatus, so omitting it there leaves the reader with a bare error and no path forward.

readonly detail?: string;

kind

The classified failure type. See AgentErrorKind.

readonly kind: AgentErrorKind;

recovery

The recovery action the adapter can justify. Only set on interrupted errors; always undefined for every other AgentErrorKind.

readonly recovery?: AgentRecovery;

retryable

Whether retrying the same request could plausibly succeed: connection | server (5xx) → true; auth | aborted | non-auth 4xx → false. For interrupted, this tracks AgentRecovery: true only when recovery is retry, because a dispatched request may already have run on the server.

readonly retryable: boolean;

status

The HTTP status code when the failure came from an HTTP response.

readonly status?: number;