@qodo/sdk 0.13.4 → 2.0.0-next.1

package/dist/client/errors.d.ts

@@ -0,0 +1,735 @@
+/**
+ * Error classes thrown by the SDK 2.0 client surface.
+ */
+/**
+ * Thrown by API surfaces whose bodies haven't landed yet. Loud-but-typed —
+ * the `ticket` field tells callers which work item fills this method's
+ * body so they can wait for the right milestone.
+ */
+export declare class QodoNotImplementedError extends Error {
+    /** Always `'QodoNotImplementedError'`. */
+    readonly name = "QodoNotImplementedError";
+    /** Human-readable name of the API surface that's not yet implemented. */
+    readonly api: string;
+    /** Ticket ID that fills this stub. */
+    readonly ticket: string;
+    constructor(api: string, ticket: string);
+}
+/**
+ * Thrown when consumer code drives the client into an invalid state at
+ * construction time (bad URL, missing required option). Distinct from
+ * `QodoNotImplementedError` because this is a real validation failure.
+ */
+export declare class QodoClientOptionsError extends Error {
+    readonly name = "QodoClientOptionsError";
+    constructor(message: string);
+}
+/**
+ * Thrown by `tasks.cancel` when the consumer-supplied `AbortSignal`
+ * short-circuits the cancel. Distinct from the generic "connection closed
+ * before task.done arrived" failure shape so consumers can branch on
+ * intentional abort vs. server-side cancel failure.
+ *
+ * `kind` distinguishes two scenarios with materially different wire
+ * effects:
+ *
+ *   - `'pre_aborted'`: signal was already aborted at the call site.
+ *     NO wire `task.cancel` was emitted (and nothing else). The
+ *     consumer can safely treat the task as untouched by this call.
+ *     Because `tasks.cancel` is async, this surfaces as a rejected
+ *     Promise — `try / catch` around `await tasks.cancel(...)` is
+ *     the consumer-side pattern, identical to the post-send-abort
+ *     case below.
+ *
+ *   - `'aborted_after_send'`: the wire `task.cancel` was already on
+ *     the wire when the signal aborted. The server's terminal
+ *     `task.done` still arrives on the task's own subscription
+ *     (initiated by `tasks.start` / `tasks.continue`); only the
+ *     wait inside `tasks.cancel` was abandoned.
+ *
+ * Carries `taskId` so consumers can match the throw against their own
+ * task-id state without parsing the message.
+ */
+export declare class QodoCancelAbortedError extends Error {
+    readonly name = "QodoCancelAbortedError";
+    readonly taskId: string;
+    readonly kind: 'pre_aborted' | 'aborted_after_send';
+    constructor(kind: 'pre_aborted' | 'aborted_after_send', taskId: string, reason?: unknown);
+}
+/**
+ * Thrown synchronously by `tasks.cancel` / `tasks.continue` /
+ * `tasks.resubscribe` / `tools.respond` when the SDK can't determine the
+ * per-Task / per-ToolCall `session_id` locally AND the caller didn't pass
+ * the explicit `sessionId` option.
+ *
+ * Surfaces locally before the wire write so the remediation lands in the
+ * error message rather than in a wire round-trip's
+ * `session_mismatch` rejection:
+ *
+ *   - For cross-process recovery: hydrate `{ taskId, sessionId }` from
+ *     durable storage and pass `sessionId` in the cold-address options.
+ *   - For HITL respond after restart: same shape via
+ *     `client.tools.respond(node, response, { sessionId })`.
+ *
+ * `kind` is a stable discriminator (`'task'` for the three task ongoing
+ * envelopes; `'tool_call'` for `tools.respond`) so consumer logging /
+ * branching can pick the right hydration path without parsing the message.
+ */
+export declare class QodoColdAddressError extends Error {
+    readonly name = "QodoColdAddressError";
+    readonly kind: 'task' | 'tool_call';
+    readonly addressId: string;
+    constructor(kind: 'task' | 'tool_call', addressId: string);
+}
+/**
+ * Client-side `idempotency_key` validation failure.
+ *
+ * Thrown synchronously by `tasks.start` / `tasks.startWithAgent` /
+ * `tasks.startWithGraph` BEFORE the wire write when the consumer-supplied
+ * `idempotencyKey` violates the wire contract (1–512 **Unicode code
+ * points** — counted by `[...str].length`, not UTF-16 code units — and no
+ * NUL byte). Mirrors QAR's Pydantic `Field(min_length=1, max_length=512,
+ * pattern=r"^[^\x00]+$")` on `TaskStartPayload.idempotency_key` so a bad
+ * value fails fast on the SDK side without waiting for the wire round-trip.
+ *
+ * The `reason` field is a stable discriminator (`'too_short'`, `'too_long'`,
+ * `'contains_nul'`) so test assertions and downstream consumer error
+ * handling can branch without parsing the human message.
+ */
+export declare class QodoIdempotencyKeyValidationError extends Error {
+    readonly name = "QodoIdempotencyKeyValidationError";
+    readonly reason: 'too_short' | 'too_long' | 'contains_nul';
+    readonly codePoints: number;
+    constructor(reason: 'too_short' | 'too_long' | 'contains_nul', codePoints: number);
+}
+/**
+ * Thrown synchronously by {@link TaskClient.continueOrStart} when the
+ * `graphSpec` argument is `undefined`. The helper requires a graphSpec
+ * to handle the fresh-dispatch branch; consumers without one on hand
+ * should reach for {@link TaskClient.continue} (if they already have a
+ * `taskId`) or {@link TaskClient.forceResume} (if they only have the
+ * `idempotencyKey` and want stuck-session recovery).
+ *
+ * Carries the rejected `idempotencyKey` so error-handling code can
+ * surface which session-derivation key triggered the throw.
+ */
+export declare class RequiredGraphSpecError extends Error {
+    readonly name = "RequiredGraphSpecError";
+    readonly idempotencyKey: string;
+    constructor(idempotencyKey: string);
+}
+/**
+ * Thrown at the transport seam for inputs that would crash the underlying
+ * WebSocket library. Today this is just the RFC 6455 close-frame reason
+ * cap — a custom caller synthesizing a reason longer than 123 UTF-8
+ * bytes gets a typed SDK error rather than an opaque `ws` crash. The
+ * class is the home for any future transport-seam validation.
+ */
+export declare class QodoTransportError extends Error {
+    readonly name = "QodoTransportError";
+    constructor(message: string);
+}
+/**
+ * Thrown when an outbound `task.start` / `task.continue` is rejected because
+ * the connection is in `flow.pause` state and the paused queue has already
+ * reached its cap. The matching wire-level taxonomy is
+ * `sdk.error { code: 'flow_backlog_exceeded' }`.
+ *
+ * Pathological case: under healthy traffic only one or two envelopes ever
+ * queue before `flow.resume` arrives. Hitting the cap means the consumer is
+ * driving the client far above QAR's per-session in-flight ceiling — backing
+ * off and waiting for `flow.resume` is the correct response.
+ */
+export declare class QodoBackpressureError extends Error {
+    readonly name = "QodoBackpressureError";
+    /** Wire-aligned error code. */
+    readonly code = "flow_backlog_exceeded";
+    /** How many envelopes were already queued when this call was rejected. */
+    readonly queueSize: number;
+    /** The configured cap. */
+    readonly queueCap: number;
+    constructor(queueSize: number, queueCap: number);
+}
+/**
+ * Thrown by `client.specs.validate` when the supplied spec is structurally
+ * unfit to send — most commonly a missing or unknown `kind` discriminator.
+ *
+ * This is a *pre-wire* rejection: the spec never reached QAR. Per-rule
+ * failures (D10-R*, D11-R*) come back from the endpoint in the
+ * `SpecValidateResult.errors` array — those are not exceptions, they're a
+ * normal `valid: false` result.
+ */
+export declare class QodoSpecValidationError extends Error {
+    readonly name = "QodoSpecValidationError";
+    constructor(message: string);
+}
+/**
+ * Thrown by `client.qar.registerAgent` / `client.qar.registerMcp` /
+ * `client.qar.registerA2A` when a name conflicts with an existing
+ * registration (and `replace: true` wasn't passed), or when the supplied
+ * name / endpoint is empty.
+ *
+ * Carries `entity` (`'agent' | 'mcp' | 'a2a'`) and `entryName` so test code
+ * and structured loggers can branch on the specific conflict shape without
+ * parsing the message text. `name` (the standard Error field) is fixed at
+ * `'QodoRegistryConflictError'`.
+ *
+ * **`entity` is open-ended by design.** New register-helpers (S9 added
+ * `'a2a'`; future surfaces will add more) extend this union additively.
+ * Consumers writing exhaustive `switch` / `assertNever` patterns on
+ * `entity` should treat unknown values as "another registry the SDK
+ * grew" — typically by routing through a default arm that surfaces the
+ * raw `entryName` + message. The SDK is on the 2.x major; breaking the
+ * union literally is allowed within the major per the SDK1→2 migration
+ * posture, but each addition lands behind its own feature commit so
+ * consumer code can pin if needed.
+ */
+export declare class QodoRegistryConflictError extends Error {
+    readonly name = "QodoRegistryConflictError";
+    /** Which registry the conflict came from. */
+    readonly entity: 'agent' | 'mcp' | 'a2a';
+    /** The name the caller tried to register. */
+    readonly entryName: string;
+    constructor(entity: 'agent' | 'mcp' | 'a2a', entryName: string, message: string);
+}
+/**
+ * Wire-validation context attached to a `QodoWireValidationError`. Populated
+ * on inbound failures so consumers routing the error into structured
+ * logging / metrics can branch on the exact protocol drift without parsing
+ * the `[@qodo/sdk]` console.error breadcrumb.
+ */
+export interface WireValidationContext {
+    /**
+     * `'outbound'` — thrown synchronously from `client.tools.respond(...)`
+     * when the caller's input violates the wire shape.
+     * `'inbound'` — surfaced (NOT thrown) via
+     * `client.tools.onWireValidationError(...)` when the SDK drops a malformed
+     * `tool.request` arriving from the runtime.
+     */
+    readonly scope: 'outbound' | 'inbound';
+    /** `message_id` of the offending envelope (inbound only). */
+    readonly messageId?: string;
+    /**
+     * `node_name` from the offending envelope, if it was present and well-shaped
+     * (inbound only). Absent for the "missing node_name" violation itself.
+     */
+    readonly nodeName?: string;
+}
+/**
+ * Surfaced when the SDK's tool-tunneling layer encounters an envelope
+ * that violates the parallel-batched wire shape. Two scopes:
+ *
+ *   - **`outbound`** — thrown synchronously from `client.tools.respond(...)`
+ *     when the caller's input is malformed (empty `node_name`, empty
+ *     `responses`). Catches consumer bugs at the call site instead of
+ *     letting them silently ship a malformed envelope onto the wire.
+ *
+ *   - **`inbound`** — NOT thrown (throwing would fail the whole connection
+ *     across every subscription). Surfaced via
+ *     `client.tools.onWireValidationError(handler)` after the
+ *     `[@qodo/sdk]` console.error breadcrumb fires. The SDK has no
+ *     `tool_call_id` to respond against for these envelopes, so consumers
+ *     observe the failure but can't actively recover — QAR's per-task
+ *     tool-response timeout is the wire-side safety net.
+ *
+ * Handler-return shape violations (positional length mismatch from a
+ * `ToolRequestHandler`, malformed `ToolResponseResult`) are NOT surfaced as
+ * `QodoWireValidationError` — they're converted to per-call
+ * `status: 'error'` items on the wire so the agent loop unblocks
+ * deterministically.
+ *
+ * Distinct from `TypeError` because the failure is wire-shape specific;
+ * consumers wanting a broader catch should `instanceof Error`. The
+ * structured `context` field is the preferred branch surface —
+ * `instanceof QodoWireValidationError` then switch on `err.context.scope`.
+ */
+export declare class QodoWireValidationError extends Error {
+    readonly name: string;
+    /** Structured drop metadata. Always populated. */
+    readonly context: WireValidationContext;
+    constructor(message: string, context?: WireValidationContext);
+}
+/**
+ * Thrown by `tasks.startWithAgent` / `tasks.startWithGraph` when the
+ * consumer's `mcpTools` selector references an MCP name that isn't
+ * registered on this client.
+ *
+ * Surface remediation: call `client.qar.registerMcp('<name>', ...)`
+ * before the dispatch, or drop the entry from the `mcpTools` selector.
+ */
+export declare class QodoUnknownMcpError extends QodoWireValidationError {
+    readonly name = "QodoUnknownMcpError";
+    /** Distinct MCP names referenced by `mcpTools` but not present in the registry. */
+    readonly mcpNames: readonly string[];
+    constructor(mcpNames: readonly string[]);
+}
+/**
+ * Thrown by `tasks.startWithAgent` / `tasks.startWithGraph` when the
+ * consumer's `mcpTools` selector — or the sibling `mcpToolOverrides`
+ * map — references a `<mcp>.<tool>` dotted name whose MCP IS registered
+ * but whose live catalog doesn't expose the named tool.
+ *
+ * Catches version drift between consumer code and upstream MCP catalogs
+ * at task.start, not at LLM-call time. Pair with
+ * `client.qar.listMcpTools(name)` during development to see the live
+ * surface.
+ */
+export declare class QodoUnknownMcpToolError extends QodoWireValidationError {
+    readonly name = "QodoUnknownMcpToolError";
+    /** Distinct `<mcp>.<tool>` dotted names that don't resolve to a discovered tool. */
+    readonly dottedNames: readonly string[];
+    constructor(dottedNames: readonly string[]);
+}
+/**
+ * Thrown by `tasks.startWithAgent` / `tasks.startWithGraph` when a
+ * registered MCP whose `unavailability` policy is `'fail'` (the default)
+ * has no cached catalog at projection time — its cold-start
+ * `Client.connect()` + `tools/list` cycle didn't complete inside the
+ * SDK's settle window.
+ *
+ * Indicates a real config / startup bug for local sidecars (typical
+ * fail-mode for `litegit`, `slack`, in-cluster MCPs). For third-party
+ * remote MCPs that flake transiently, register with
+ * `{ unavailability: 'warn' }` to ship without the MCP's tools instead
+ * of failing the task.
+ */
+export declare class QodoMcpUnavailableError extends QodoWireValidationError {
+    readonly name = "QodoMcpUnavailableError";
+    /** Distinct MCP names whose `unavailability` is `'fail'` and whose catalog hasn't populated. */
+    readonly mcpNames: readonly string[];
+    constructor(mcpNames: readonly string[]);
+}
+/**
+ * One pre-wire validation failure on an inline `GraphSpec`. Mirrors QAR's
+ * `SpecValidationError` envelope (rule_id + path + message) so consumers can
+ * use the same branch logic for both client-side rejection (here) and
+ * `client.specs.validate(...)` round-trips.
+ */
+export interface InlineGraphValidationFailure {
+    /** Wire rule identifier (e.g. `'D11-R6'`, `'D11-R9'`, `'D11-R11'`, `'D11-R12'`). */
+    readonly rule_id: string;
+    /** JSON Pointer (RFC 6901) into the offending spec. `""` denotes the root. */
+    readonly path: string;
+    /** Human-readable explanation. */
+    readonly message: string;
+}
+/**
+ * Thrown by `client.tasks.startWithGraph(...)` when the inline `GraphSpec`
+ * fails one of the SDK's pre-wire structural checks against the
+ * GraphSpec safe subset.
+ *
+ * Pre-wire rejection: the envelope never reaches QAR. Same `rule_id` /
+ * `path` / `message` shape as `client.specs.validate(...)` per-rule failures,
+ * so consumers can route both surfaces into the same error handler.
+ *
+ * The SDK enforces the rule subset that doesn't require server-side
+ * state (no tenant lookup, no model-registry probe):
+ *   - `D11-R1..R3` — entry / agents present + named uniquely.
+ *   - `D11-R6..R8` — edges resolve to declared agents, entry resolves.
+ *   - `D11-R9`     — `evaluate` edges only target evaluator-role nodes.
+ *   - `D11-R10`    — graph depth ≤ configured maximum (default 4).
+ *   - `D11-R11`    — evaluator nodes are leaves (no outbound edges).
+ *   - `D11-R12`    — evaluator `output_schema` is shaped like `VerdictResult`.
+ *   - `D11-Rcycle` — acyclicity (the SDK rejects cycles unconditionally; QAR
+ *     surfaces the same rule via `D11-R9` numbering in its own response shape).
+ *
+ * Rules requiring server-side state (AgentSpec composition, alternate
+ * operator-maximum depth) flow through the `client.specs.validate(...)`
+ * opt-in pre-flight instead — see `preflight: true` on `TaskOptions`.
+ */
+export declare class QodoInlineGraphValidationError extends Error {
+    readonly name = "QodoInlineGraphValidationError";
+    /** All failures the validator observed, in stable depth-first order. */
+    readonly failures: readonly InlineGraphValidationFailure[];
+    constructor(failures: readonly InlineGraphValidationFailure[]);
+}
+/**
+ * Per-violation entry carried on `QodoInlineAgentValidationError` and
+ * `QodoAgentSpecRejectedError`. Mirrors the QAR-side `agent_spec_rejected`
+ * error envelope shape so consumers handling both paths can branch on the
+ * same `(rule_id, path, message)` triple.
+ *
+ * `rule_id` is one of the `D10-R*` set (server-side wire validator) or a
+ * `D10-SHAPE-*` synthetic id (SDK-side pre-wire shape check — distinct
+ * prefix so SDK-only ids never collide with QAR's documented ruleset).
+ * `path` is an RFC 6901 JSON Pointer into the spec — `""` denotes the
+ * root.
+ *
+ * Shape parallels `InlineGraphValidationFailure` so consumers can write
+ * one error handler that branches on `instanceof` and reads the same
+ * fields off either error class.
+ */
+export interface InlineAgentSpecIssue {
+    readonly rule_id: string;
+    readonly path: string;
+    readonly message: string;
+}
+/**
+ * Thrown synchronously by `client.tasks.startWithAgent({ agent: spec, ... })`
+ * when the supplied `InlineAgentSpec` violates the data-only safe subset
+ * before the wire write. Carries the structured `issues` array so
+ * structured-logging consumers can branch on `rule_id` / `path` without
+ * parsing the message text.
+ *
+ * **Pre-wire only.** The mirror error for server-rejected specs (after
+ * the wire write, when QAR's validator runs the full ruleset including
+ * registry-dependent rules) is `QodoAgentSpecRejectedError`, surfaced
+ * via the task iterator's `kind: 'error'` envelope.
+ *
+ * Distinct from `QodoSpecValidationError` (which is for
+ * `client.specs.validate` — the pre-flight wrapper around
+ * `POST /v1/specs/validate`); both exist because the pre-flight wrapper
+ * accepts intentionally-invalid shapes (the whole point is to ask the
+ * server "tell me which rule I broke"), while `startWithAgent` rejects
+ * at intake to avoid kicking off server-side work the spec can't possibly
+ * pass.
+ */
+export declare class QodoInlineAgentValidationError extends Error {
+    readonly name = "QodoInlineAgentValidationError";
+    /** Per-violation breakdown — at least one entry. */
+    readonly issues: readonly InlineAgentSpecIssue[];
+    constructor(issues: readonly InlineAgentSpecIssue[]);
+}
+/**
+ * Thrown / surfaced when QAR's `_handle_task_start` rejects the supplied
+ * inline `agent: InlineAgentSpec` (Pattern B) at wire-validation time via
+ * an `error { code: 'agent_spec_rejected' }` envelope. Mirror for the
+ * server-static path doesn't exist — there's no inline-spec to reject for
+ * Pattern A.
+ *
+ * Carries the full `issues` array so consumers can show per-rule messages
+ * in IDE / Studio surfaces. The first issue's `rule_id` is also exposed
+ * at `rule_id` / `path` for the common "just give me the primary failure"
+ * branch.
+ *
+ * Surfaced via the iterator returned by `tasks.startWithAgent`: when the
+ * first inbound envelope is an `error { code: 'agent_spec_rejected' }`,
+ * the iterator rejects with this error (instead of yielding the envelope)
+ * so consumers don't need to defensively type-narrow the error case out
+ * of `TaskEvent.kind`.
+ */
+export declare class QodoAgentSpecRejectedError extends Error {
+    readonly name = "QodoAgentSpecRejectedError";
+    /** Wire-aligned error code. */
+    readonly code = "agent_spec_rejected";
+    /** Per-violation breakdown — at least one entry. */
+    readonly issues: readonly InlineAgentSpecIssue[];
+    /** Convenience: first issue's `rule_id` (`'D10-R*'` or `'D10-UNSUPPORTED*'`). */
+    readonly rule_id: string;
+    /** Convenience: first issue's `path` (RFC 6901 JSON Pointer; `""` = root). */
+    readonly path: string;
+    constructor(issues: readonly InlineAgentSpecIssue[], message?: string);
+}
+/**
+ * One per-rule entry on a server `error` envelope's `payload.errors`, when
+ * the envelope carries the structured array (D15-R*, agent-spec-rejected
+ * shape). Mirrors `InlineAgentSpecIssue` but is the canonical shape across
+ * every typed server-error class — agent-spec rejection still ships its
+ * own `InlineAgentSpecIssue` alias for back-compat with the existing
+ * `QodoAgentSpecRejectedError` consumers.
+ */
+export interface ServerErrorEntry {
+    /** D10/D11/D15 rule identifier or QAR-side code (`'cancel_routing_failed'`, …). */
+    readonly rule_id: string;
+    /** JSON Pointer (RFC 6901) into the offending envelope/spec. `""` denotes the root. */
+    readonly path: string;
+    /** Human-readable explanation. */
+    readonly message: string;
+}
+/**
+ * Base class for every typed server-error class (cancel/resume/HITL/graph
+ * codes). Each concrete subclass pins its `code` to the documented QAR
+ * wire string so consumers can branch on
+ * `instanceof QodoCancelRoutingFailedError` instead of
+ * `err.code === 'cancel_routing_failed'`.
+ *
+ * `QodoAgentSpecRejectedError` predates this base and keeps its own
+ * shape; new error codes here use the unified `QodoServerError` surface
+ * for forward compatibility.
+ */
+export declare class QodoServerError extends Error {
+    /** Wire-level QAR error code. Pinned per subclass. */
+    readonly code: string;
+    /**
+     * Structured per-rule breakdown, if QAR shipped one on the envelope. Empty
+     * array when the envelope only carried top-level `code` + `message`.
+     */
+    readonly errors: readonly ServerErrorEntry[];
+    /** `payload.offending_message_id` — useful for tracing the cause envelope. */
+    readonly offendingMessageId?: string;
+    /**
+     * @param name                 The concrete subclass name (matches `this.name`).
+     * @param code                 Wire-level error code.
+     * @param message              Human-readable summary; mirrored to `Error.message`.
+     * @param errors               Structured breakdown when QAR emitted one. Default `[]`.
+     * @param offendingMessageId   `error.payload.offending_message_id` if present.
+     */
+    constructor(name: string, code: string, message: string, errors?: readonly ServerErrorEntry[], offendingMessageId?: string);
+}
+/** Cancel routing lookup failed — see QAR `_handle_task_cancel`. */
+export declare class QodoCancelRoutingFailedError extends QodoServerError {
+    readonly name = "QodoCancelRoutingFailedError";
+    constructor(message: string, errors?: readonly ServerErrorEntry[], offendingMessageId?: string);
+}
+/** Cancel all-writes-fail — see QAR `_handle_task_cancel`. */
+export declare class QodoCancelFailedError extends QodoServerError {
+    readonly name = "QodoCancelFailedError";
+    constructor(message: string, errors?: readonly ServerErrorEntry[], offendingMessageId?: string);
+}
+/** Session lookup miss — `cancel`/`continue` against an unknown task. */
+export declare class QodoTaskNotFoundError extends QodoServerError {
+    readonly name = "QodoTaskNotFoundError";
+    constructor(message: string, errors?: readonly ServerErrorEntry[], offendingMessageId?: string);
+}
+/** Cancel-on-non-waiting-task — see QAR `_handle_task_cancel` precondition. */
+export declare class QodoTaskNotWaitingError extends QodoServerError {
+    readonly name = "QodoTaskNotWaitingError";
+    constructor(message: string, errors?: readonly ServerErrorEntry[], offendingMessageId?: string);
+}
+/** Pod failed to reconstruct the agent for a cross-pod task. */
+export declare class QodoAgentReconstructionFailedError extends QodoServerError {
+    readonly name = "QodoAgentReconstructionFailedError";
+    constructor(message: string, errors?: readonly ServerErrorEntry[], offendingMessageId?: string);
+}
+/** Cross-pod resume hook aborted before delivering control. */
+export declare class QodoCrossPodResumeAbortedError extends QodoServerError {
+    readonly name = "QodoCrossPodResumeAbortedError";
+    constructor(message: string, errors?: readonly ServerErrorEntry[], offendingMessageId?: string);
+}
+/** Deps construction failed during agent dispatch (Pattern A/B/C). */
+export declare class QodoDepsConstructionFailedError extends QodoServerError {
+    readonly name = "QodoDepsConstructionFailedError";
+    constructor(message: string, errors?: readonly ServerErrorEntry[], offendingMessageId?: string);
+}
+/** Message history load failed during resume / continue. */
+export declare class QodoMessageHistoryLoadFailedError extends QodoServerError {
+    readonly name = "QodoMessageHistoryLoadFailedError";
+    constructor(message: string, errors?: readonly ServerErrorEntry[], offendingMessageId?: string);
+}
+/** HITL persistence failure — substrate accepted but the row didn't durable. */
+export declare class QodoHitlPersistFailedError extends QodoServerError {
+    readonly name = "QodoHitlPersistFailedError";
+    constructor(message: string, errors?: readonly ServerErrorEntry[], offendingMessageId?: string);
+}
+/** HITL substrate unavailable — backing store offline / unconfigured. */
+export declare class QodoHitlSubstrateUnavailableError extends QodoServerError {
+    readonly name = "QodoHitlSubstrateUnavailableError";
+    constructor(message: string, errors?: readonly ServerErrorEntry[], offendingMessageId?: string);
+}
+/** Caller is not the authorized resolver for the HITL row. */
+export declare class QodoUnauthorizedResolverError extends QodoServerError {
+    readonly name = "QodoUnauthorizedResolverError";
+    constructor(message: string, errors?: readonly ServerErrorEntry[], offendingMessageId?: string);
+}
+/** HITL resolution payload failed validation against the prompt's schema. */
+export declare class QodoInvalidResolutionError extends QodoServerError {
+    readonly name = "QodoInvalidResolutionError";
+    constructor(message: string, errors?: readonly ServerErrorEntry[], offendingMessageId?: string);
+}
+/**
+ * Pattern C (inline graph) validator rejection — GraphSpec rule failure
+ * surfaced AFTER the wire. Mirror of `QodoAgentSpecRejectedError` for the
+ * graph path; the `errors[]` array carries each `D11-R*` / `D13-R*`
+ * failure with `rule_id` + `path` + `message`.
+ */
+export declare class QodoGraphSpecRejectedError extends QodoServerError {
+    readonly name = "QodoGraphSpecRejectedError";
+    constructor(message: string, errors?: readonly ServerErrorEntry[], offendingMessageId?: string);
+}
+/**
+ * Typed error for QAR's `session_mismatch` wire rejection. Surfaces when
+ * an outbound ongoing envelope (`task.continue` / `task.cancel` /
+ * `task.resubscribe` / `tool.response`) carries a `session_id` that
+ * doesn't match the connection's bound session for the referenced task.
+ *
+ * The SDK no longer mints a zero-UUID sentinel for cold-address paths —
+ * the missing-session case is caught locally and raised as
+ * {@link QodoColdAddressError} before the wire write. This typed error
+ * fires only when the consumer-supplied `sessionId` override on the
+ * cold-address API doesn't actually match the server's bound session
+ * (stale durable-storage row, deliberate mismatch test).
+ */
+export declare class QodoSessionMismatchError extends QodoServerError {
+    readonly name = "QodoSessionMismatchError";
+    constructor(message: string, errors?: readonly ServerErrorEntry[], offendingMessageId?: string);
+}
+/**
+ * Admission has been pending past the operator timeout
+ * (`PENDING_ADMISSION_TIMEOUT`, server default 5 min). Terminal,
+ * non-retryable. Scoped to the derived `session_id` so the consumer can
+ * `task.resubscribe` if a recovery path exists, but the typical handling
+ * is to surface the failure to the operator — the server's sweeper will
+ * compensate the orphan row on its next sweep cycle.
+ *
+ * The wire envelope carries the derived `session_id` — exposed here as
+ * `sessionId` so consumers don't need to dig through the envelope to
+ * find it. `undefined` only on synthetic / spec-violating envelopes
+ * that omit the field.
+ */
+export declare class QodoAdmissionStalledError extends QodoServerError {
+    readonly name = "QodoAdmissionStalledError";
+    /**
+     * Derived `session_id` from the inbound `admission_stalled` envelope.
+     * Populated by {@link attachSessionId} (called by
+     * `errorFromServerErrorEnvelope` when it has the inherited envelope
+     * field in hand) — the constructor matches the unified server-error
+     * factory signature so the typed-error dispatcher (`classForServerErrorCode`)
+     * can build instances uniformly. `undefined` only on synthetic envelopes
+     * that omit the session_id field.
+     */
+    sessionId?: string;
+    constructor(message: string, errors?: readonly ServerErrorEntry[], offendingMessageId?: string);
+    /** Internal — set by the envelope-to-error helper. Read-once-after-construct. */
+    attachSessionId(sessionId: string): void;
+}
+/**
+ * Client-side terminal when the consumer breaks the `TaskStartIterable`
+ * (via `iter.return()`, `break` inside a `for await`, or `iter.throw()`)
+ * BEFORE the server's `task.started` admission ack arrives.
+ *
+ * Surfaces on `await stream.sessionId` / `await stream.admittedTaskId` so
+ * the caller's pending awaits don't hang forever after they've abandoned
+ * the stream.
+ *
+ * Distinct from `QodoAdmissionTimeoutError` (SDK-side budget exhaustion)
+ * and `QodoAdmissionStalledError` (server-emitted terminal) so consumer
+ * code can branch on the reason — voluntary abort vs. genuine admission
+ * failure.
+ */
+export declare class QodoStreamAbortedError extends Error {
+    readonly name = "QodoStreamAbortedError";
+    constructor(message?: string);
+}
+/**
+ * Client-side terminal after the SDK's `admission_in_progress` retry
+ * loop exhausts its budget without ever seeing a `task.started` ack.
+ *
+ * The SDK honours the server's `retry_after_ms` hint when present and
+ * falls back to exponential backoff with jitter (initial 100 ms, doubling,
+ * capped at `PENDING_ADMISSION_TIMEOUT = 5 min`). Reaching the cap means
+ * the deterministic-key admission contended for the full timeout window
+ * without resolving.
+ *
+ * `sessionId` carries the derived session UUID extracted from the final
+ * `admission_in_progress` envelope so a consumer that wants to
+ * `task.resubscribe` has the address; `undefined` only when no
+ * admission_in_progress envelope was ever observed (transport drop
+ * mid-retry).
+ */
+export declare class QodoAdmissionTimeoutError extends Error {
+    readonly name = "QodoAdmissionTimeoutError";
+    /** Total wall-clock milliseconds spent retrying before giving up. */
+    readonly elapsedMs: number;
+    /** Number of `admission_in_progress` envelopes observed before timing out. */
+    readonly attempts: number;
+    /** Derived `session_id` from the final envelope, if observed. */
+    readonly sessionId?: string;
+    constructor(elapsedMs: number, attempts: number, sessionId?: string);
+}
+/**
+ * Fallback for any unrecognized `error.code` value arriving from QAR.
+ *
+ * The SDK's typed-error catalog tracks the codes QAR's documented contract
+ * surfaces; a new code that hasn't landed in the SDK yet still surfaces
+ * as a typed throw (via this class) so consumers' `catch
+ * (err: QodoServerError)` blocks see structure rather than a yielded
+ * `kind: 'error'` event their type narrows can't account for. Branch on
+ * `err.code` (the raw wire string) until the SDK adds a typed subclass.
+ */
+export declare class QodoUnknownServerError extends QodoServerError {
+    readonly name = "QodoUnknownServerError";
+    constructor(code: string, message: string, errors?: readonly ServerErrorEntry[], offendingMessageId?: string);
+}
+/**
+ * Map a wire `error.code` to its typed `QodoServerError` subclass. Returns
+ * `undefined` for the SDK-side `agent_spec_rejected` code — that case is
+ * intentionally handled by `QodoAgentSpecRejectedError`'s own
+ * `errorFromAgentSpecRejection` parser (it carries an
+ * `InlineAgentSpecIssue[]` shape that predates the unified
+ * `ServerErrorEntry`). All other documented codes route through here.
+ *
+ * Callers needing to wrap an arbitrary error envelope: prefer the
+ * higher-level `errorFromServerErrorEnvelope` helper in `TaskClient.ts` —
+ * it handles the parse-`errors[]` step, the `agent_spec_rejected` carve-
+ * out, and the `QodoUnknownServerError` fallback uniformly.
+ */
+export declare function classForServerErrorCode(code: string): (new (message: string, errors?: readonly ServerErrorEntry[], offendingMessageId?: string) => QodoServerError) | undefined;
+/**
+ * Thrown when the SDK's MCP client pool fails to connect to a registered
+ * remote / stdio MCP server.
+ *
+ * Carries the registered MCP `name` so callers can branch / log without
+ * parsing the message text. `cause` is the underlying transport / protocol
+ * error from `@modelcontextprotocol/sdk` (`McpError`, `StreamableHTTPError`,
+ * `SseError`, plain `Error` from `Client.connect`) — preserved on
+ * `Error.cause` per the standard idiom.
+ *
+ * Distinct from `QodoMcpToolError` so consumer code can branch on
+ * "connection failed" vs. "tool invocation failed" without inspecting
+ * the underlying cause.
+ */
+export declare class QodoMcpClientError extends Error {
+    readonly name = "QodoMcpClientError";
+    /** Registered MCP name (the `name` argument passed to `qar.registerMcp`). */
+    readonly mcpName: string;
+    /** Transport discriminator from the failing config. */
+    readonly transport: string;
+    constructor(mcpName: string, transport: string, message: string, cause?: unknown);
+}
+/**
+ * Thrown when a tool invocation against a registered remote / stdio MCP
+ * fails. Distinct from `QodoMcpClientError` (which is a connection
+ * failure) — this one fires AFTER the MCP `Client` is connected and is
+ * reporting an error from a `callTool` round-trip.
+ *
+ * Two failure shapes both route through this class:
+ *   - **Transport error** — the wire layer (HTTP request, SSE stream, stdio
+ *     pipe) failed during the call. `cause` is the underlying error.
+ *   - **Tool-reported error** — the call succeeded at the transport level
+ *     but the tool result has `isError: true`. The MCP envelope is preserved
+ *     in `mcpResult` so consumers can inspect the per-tool content array.
+ *
+ * `mcpName` and `toolName` are populated so structured logging / metrics
+ * can branch on the exact dispatch coordinates without parsing the message.
+ */
+export declare class QodoMcpToolError extends Error {
+    readonly name = "QodoMcpToolError";
+    /** Registered MCP name (the `name` argument passed to `qar.registerMcp`). */
+    readonly mcpName: string;
+    /** MCP tool name that failed (the `name` field of the `callTool` request). */
+    readonly toolName: string;
+    /**
+     * MCP envelope when the tool returned `isError: true`. Absent for pure
+     * transport failures (those carry the underlying error on `cause`).
+     */
+    readonly mcpResult?: {
+        readonly content: readonly unknown[];
+        readonly isError?: boolean;
+    };
+    constructor(mcpName: string, toolName: string, message: string, opts?: {
+        readonly cause?: unknown;
+        readonly mcpResult?: {
+            readonly content: readonly unknown[];
+            readonly isError?: boolean;
+        };
+    });
+}
+/**
+ * Typed escape path for a tool handler that wants to reject a `tool.request`.
+ *
+ * Throwing `new ToolDeniedError("not allowed")` from a handler registered via
+ * `client.tools.onRequest` maps to a `tool.response { outcome: "denied" }`
+ * envelope on the wire. The reason string is forwarded to QAR (truncated to
+ * keep error payloads bounded) so the model and observability traces see why
+ * the call was rejected.
+ *
+ * Plain `throw new Error(...)` from a handler still works — the SDK maps any
+ * other thrown value to `outcome: "error"`. Use `ToolDeniedError` only when
+ * the rejection is a deliberate policy decision (approval flow rejected the
+ * call, capability lookup denied the tool) rather than an unexpected failure.
+ */
+export declare class ToolDeniedError extends Error {
+    readonly name = "ToolDeniedError";
+    constructor(reason: string);
+}
+//# sourceMappingURL=errors.d.ts.map