/** * Error classification for the CLI API client (split out of api-client.ts, Issue #4058). * api-client.ts re-exports every exported name here; import from there. */ /** * Error result from API operations */ export interface ApiErrorResult { message: string; exitCode: number; } /** * The server's own explanation for a failure, when it sent one worth showing. * * Issue #1637: every 5xx used to be flattened into `Server error. Check server * logs for details.`, which is only useful to someone who has the server logs. * A cold-start `send` failed with an initialization timeout and told the * operator nothing but "go read the logs" — four orchestration runs in a row * then misdiagnosed it as a session-creation race and worked around it by * re-sending. Every route in this codebase already answers `{ error }`, so the * cause was always in the response body; nothing read it. * * Trimmed and length-capped because it is printed to a terminal, and an * unbounded server string is not something a CLI should paste verbatim. */ export declare const MAX_SERVER_ERROR_DETAIL = 2000; /** * What this function knows about the request, beyond its status (Issue #2404). * * `handleApiError` is a pure classifier over `(status, payload)` and has no way * to know which server answered — which is exactly the fact a 404 needs. The * caller's `Resource not found. Check the worktree ID.` sent an agent looking * for a typo in an id that was correct: the CLI was dialling a *different* * CommandMate server than the one that had started its session, and the id it * was asking about lived on the other one. Optional so the two callers that * classify without a client (`ApiClient` in api-client.ts aside, `server-capabilities.ts`) * keep compiling and keep their wording. */ export interface ApiErrorContext { /** The base URL the failing request was actually sent to. */ serverUrl?: string; } /** Append `(server: )` when the caller named one. */ export declare function withServerUrl(message: string, context?: ApiErrorContext): string; /** * The `code` the server sends with the 409 for a tmux session another * CommandMate server created (Issue #2865). Spelled out rather than imported: * the server's constant lives next to the tmux gateway, which the CLI must not * load. `tests/unit/cli/utils/api-client-foreign-session-3334.test.ts` pins the * two to the same string. */ export declare const FOREIGN_SESSION_ERROR_CODE = "session_owned_by_other_server"; /** * Issue #3334: what the operator reads for that 409. It has to say three * things the status alone does not: the session is another CommandMate * server's, this command therefore did nothing to it, and where to go instead. */ export declare function foreignSessionMessage(payload?: ApiErrorPayload): string; /** * The `code` of the 409 for a roster that moved since it was read (Issue #4132). * Spelled out for the reason {@link FOREIGN_SESSION_ERROR_CODE} is: it comes from a route. */ export declare const ROSTER_CHANGED_ERROR_CODE = "ROSTER_CHANGED"; /** * Classify API errors into user-friendly messages and exit codes. * [IA3-09] Covers: ECONNREFUSED, 400, 401/403, 404, 429, 500, timeout * * @param error - Error object or unknown * @param status - HTTP status code if available * @param payload - Parsed error body, when the response carried one (Issue #1637). * Used for 5xx, and for the foreign-session 409 (Issue #3334): the other 4xx * messages below are already specific, and are pinned by tests as the CLI's * own wording. Issue #4149: the roster 409 is told apart by its code too. * @param context - Which server answered, when the caller knows (Issue #2404). * Read by the 404 branch only; the other messages do not send anyone looking * in the wrong place. * @returns User-friendly error message and exit code */ export declare function handleApiError(error: unknown, status?: number, payload?: ApiErrorPayload, context?: ApiErrorContext): ApiErrorResult; /** * Machine-readable part of a failed API response (Issue #1237). * Every Skill route answers `{ error, code }`; the uninstall routes add `blockers`. */ export interface ApiErrorPayload { code?: string; error?: string; blockers?: Array<{ code: string; path: string | null; }>; /** Issue #1544: run already in flight, sent with the verify route's 409. */ runningRunId?: number; /** * Issue #1545: every task-contract violation, sent with the tasks route's 400. * Printed in full so a broken contract is fixed in one pass, not one round * trip per mistake. */ issues?: string[]; /** Issue #2865: sent with the foreign-session 409 (`session_owned_by_other_server`). */ sessionName?: string; sessionPath?: string | null; /** * Issue #3957/#3992: sent with the send route's errors after a bound relay * was reserved — `not_sent`: nothing reached the session, it may be sent * again; `unknown`: it may have, look before resending. Issue #4011: also * on a failure of a send with no bound relay that was recorded as its * attempt (`not-sent` → `not_sent`, otherwise `unknown`; no 400). Mirrors * src/lib/relay/relay-bind.ts RelaySendOutcome (and ChatMessage.sendOutcome). */ sendOutcome?: 'sent' | 'not_sent' | 'unknown'; /** * Issue #4116: the role routes answer `{ success: false, error: , message }`, * so there `error` is the stable code and `message` the sentence. */ success?: boolean; message?: string; /** `role_in_use`: what points at the role. */ references?: unknown; /** `version_conflict`: the version the role is at now. */ currentBodyVersion?: number; /** Issue #4115: a send refused because of its role says whether the setting stayed saved. */ roleSettings?: { saved?: boolean; stored?: unknown; }; /** Issue #4115: why a launch was refused because of its role. */ roleRefusal?: string; } /** * API Error with exit code for CLI process.exit() */ export declare class ApiError extends Error { readonly exitCode: number; readonly statusCode?: number | undefined; /** Typed error body, when the server sent one (Issue #1237). */ readonly payload?: ApiErrorPayload | undefined; /** * The error `fetch` threw, when no HTTP response came back (Issue #3756): * the strict `respond` tells "never connected" (nothing can have been sent) * from "the connection broke" by its `cause.code`. */ readonly transportError?: unknown | undefined; constructor(message: string, exitCode: number, statusCode?: number | undefined, /** Typed error body, when the server sent one (Issue #1237). */ payload?: ApiErrorPayload | undefined, /** * The error `fetch` threw, when no HTTP response came back (Issue #3756): * the strict `respond` tells "never connected" (nothing can have been sent) * from "the connection broke" by its `cause.code`. */ transportError?: unknown | undefined); /** Stable machine code the server assigned to this failure, if any. */ get apiCode(): string | undefined; } //# sourceMappingURL=api-client-errors.d.ts.map