@qodo/sdk 0.13.4 → 2.0.0-next.0

package/dist/client/errors.js

@@ -0,0 +1,921 @@
+/**
+ * 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 class QodoNotImplementedError extends Error {
+    /** Always `'QodoNotImplementedError'`. */
+    name = 'QodoNotImplementedError';
+    /** Human-readable name of the API surface that's not yet implemented. */
+    api;
+    /** Ticket ID that fills this stub. */
+    ticket;
+    constructor(api, ticket) {
+        super(`${api}: Not implemented yet; the API redesign locks the contract here. Implementation lands in ${ticket} and downstream tickets.`);
+        this.api = api;
+        this.ticket = ticket;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class QodoClientOptionsError extends Error {
+    name = 'QodoClientOptionsError';
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class QodoCancelAbortedError extends Error {
+    name = 'QodoCancelAbortedError';
+    taskId;
+    kind;
+    constructor(kind, taskId, reason) {
+        const reasonStr = reason === undefined
+            ? ''
+            : reason instanceof Error
+                ? `: ${reason.message}`
+                : `: ${String(reason)}`;
+        const message = kind === 'pre_aborted'
+            ? `tasks.cancel(${taskId}) — consumer-supplied AbortSignal was ` +
+                `already aborted at the call site${reasonStr}. No wire task.cancel ` +
+                `was emitted; the task is untouched by this call.`
+            : `tasks.cancel(${taskId}) — consumer-supplied AbortSignal fired ` +
+                `before task.done arrived${reasonStr}. The wire task.cancel was ` +
+                `already sent; the underlying task's terminal ack still routes ` +
+                `through its own tasks.start / tasks.continue subscription.`;
+        super(message);
+        this.kind = kind;
+        this.taskId = taskId;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class QodoColdAddressError extends Error {
+    name = 'QodoColdAddressError';
+    kind;
+    addressId;
+    constructor(kind, addressId) {
+        // The cold-address option is named `sessionId` on both
+        // surfaces ({@link TaskOptions} / {@link TaskCancelOptions} /
+        // {@link ResubscribeOptions} for task ops, {@link ToolRespondOptions}
+        // for tool ops). The surface and id-field name differ per kind;
+        // the option name is constant.
+        const surface = kind === 'task'
+            ? 'tasks.cancel / tasks.continue / tasks.resubscribe'
+            : 'tools.respond';
+        super(`No in-memory session for ${kind === 'task' ? 'taskId' : 'tool_call_id'}=${addressId}. ` +
+            `This usually means a cross-process recovery path: the SDK didn't observe ` +
+            `the originating ${kind === 'task' ? 'task.started' : 'tool.request'} envelope ` +
+            `in this process. Hydrate the matching session_id from durable storage and ` +
+            `pass it as the \`sessionId\` option to ${surface}.`);
+        this.kind = kind;
+        this.addressId = addressId;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class QodoIdempotencyKeyValidationError extends Error {
+    name = 'QodoIdempotencyKeyValidationError';
+    reason;
+    codePoints;
+    constructor(reason, codePoints) {
+        const messages = {
+            too_short: `idempotencyKey must be 1–512 Unicode code points; received 0. ` +
+                `Omit the field for the DX-default path (server mints a fresh uuidv7).`,
+            too_long: `idempotencyKey must be 1–512 Unicode code points; received ${codePoints}. ` +
+                `If the natural-identity composition is too long, hash and pass the digest.`,
+            contains_nul: `idempotencyKey must not contain NUL (\\x00); received a key with ${codePoints} ` +
+                `code points including at least one NUL.`,
+        };
+        super(messages[reason]);
+        this.reason = reason;
+        this.codePoints = codePoints;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class RequiredGraphSpecError extends Error {
+    name = 'RequiredGraphSpecError';
+    idempotencyKey;
+    constructor(idempotencyKey) {
+        super(`continueOrStart requires a graphSpec for the fresh-dispatch branch ` +
+            `(idempotencyKey=${idempotencyKey}). Pass the consumer's InlineGraphSpec ` +
+            `or use tasks.continue / tasks.forceResume directly when no graphSpec ` +
+            `is available.`);
+        this.idempotencyKey = idempotencyKey;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class QodoTransportError extends Error {
+    name = 'QodoTransportError';
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class QodoBackpressureError extends Error {
+    name = 'QodoBackpressureError';
+    /** Wire-aligned error code. */
+    code = 'flow_backlog_exceeded';
+    /** How many envelopes were already queued when this call was rejected. */
+    queueSize;
+    /** The configured cap. */
+    queueCap;
+    constructor(queueSize, queueCap) {
+        super(`Outbound rejected: connection is paused and the backpressure queue is full ` +
+            `(${queueSize}/${queueCap}). Wait for flow.resume before sending more, or ` +
+            `raise backpressure.maxPausedQueueSize.`);
+        this.queueSize = queueSize;
+        this.queueCap = queueCap;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class QodoSpecValidationError extends Error {
+    name = 'QodoSpecValidationError';
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class QodoRegistryConflictError extends Error {
+    name = 'QodoRegistryConflictError';
+    /** Which registry the conflict came from. */
+    entity;
+    /** The name the caller tried to register. */
+    entryName;
+    constructor(entity, entryName, message) {
+        super(message);
+        this.entity = entity;
+        this.entryName = entryName;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class QodoWireValidationError extends Error {
+    name = 'QodoWireValidationError';
+    /** Structured drop metadata. Always populated. */
+    context;
+    constructor(message, context = { scope: 'outbound' }) {
+        super(message);
+        this.context = context;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+// ---------------------------------------------------------------------------
+// MCP projection errors — surfaced synchronously by `tasks.startWithAgent`
+// / `tasks.startWithGraph` BEFORE the wire write when the consumer's
+// `mcpTools` selector references unknown MCPs, unknown tools, or unreachable
+// MCPs whose `unavailability` policy is `'fail'`.
+//
+// All three subclass `QodoWireValidationError` so consumers writing a single
+// catch on the wire-validation taxonomy pick them up. Concrete error classes
+// carry typed `names`/`dottedNames` arrays so structured logging and IDE-side
+// remediation can branch on the exact drift without parsing the message text.
+// ---------------------------------------------------------------------------
+/**
+ * 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 class QodoUnknownMcpError extends QodoWireValidationError {
+    name = 'QodoUnknownMcpError';
+    /** Distinct MCP names referenced by `mcpTools` but not present in the registry. */
+    mcpNames;
+    constructor(mcpNames) {
+        super(`Inline AgentSpec.mcpTools references ${mcpNames.length} unregistered MCP ` +
+            `name${mcpNames.length === 1 ? '' : 's'}: ${mcpNames.map((n) => `'${n}'`).join(', ')}. ` +
+            `Register them via client.qar.registerMcp(...) before tasks.start*, or drop ` +
+            `them from the selector.`, { scope: 'outbound' });
+        this.mcpNames = mcpNames;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class QodoUnknownMcpToolError extends QodoWireValidationError {
+    name = 'QodoUnknownMcpToolError';
+    /** Distinct `<mcp>.<tool>` dotted names that don't resolve to a discovered tool. */
+    dottedNames;
+    constructor(dottedNames) {
+        super(`Inline AgentSpec.mcpTools / mcpToolOverrides references ${dottedNames.length} ` +
+            `tool${dottedNames.length === 1 ? '' : 's'} not in the live MCP catalog: ` +
+            `${dottedNames.map((n) => `'${n}'`).join(', ')}. ` +
+            `Use client.qar.listMcpTools('<mcp>') to inspect the current surface; ` +
+            `update the selector after upstream tool renames.`, { scope: 'outbound' });
+        this.dottedNames = dottedNames;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class QodoMcpUnavailableError extends QodoWireValidationError {
+    name = 'QodoMcpUnavailableError';
+    /** Distinct MCP names whose `unavailability` is `'fail'` and whose catalog hasn't populated. */
+    mcpNames;
+    constructor(mcpNames) {
+        super(`${mcpNames.length} registered MCP${mcpNames.length === 1 ? '' : 's'} ` +
+            `unreachable at tasks.start* (cold-start catalog not populated, ` +
+            `unavailability: 'fail'): ${mcpNames.map((n) => `'${n}'`).join(', ')}. ` +
+            `Verify the MCP endpoint is reachable, or register with ` +
+            `{ unavailability: 'warn' } to degrade gracefully.`, { scope: 'outbound' });
+        this.mcpNames = mcpNames;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class QodoInlineGraphValidationError extends Error {
+    name = 'QodoInlineGraphValidationError';
+    /** All failures the validator observed, in stable depth-first order. */
+    failures;
+    constructor(failures) {
+        super(`inline GraphSpec failed ${failures.length} client-side validation rule${failures.length === 1 ? '' : 's'}: ` +
+            failures
+                .map((f) => `[${f.rule_id} @ ${f.path === '' ? '(root)' : f.path}] ${f.message}`)
+                .join('; '));
+        this.failures = failures;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class QodoInlineAgentValidationError extends Error {
+    name = 'QodoInlineAgentValidationError';
+    /** Per-violation breakdown — at least one entry. */
+    issues;
+    constructor(issues) {
+        const head = issues[0];
+        const summary = head !== undefined
+            ? `${head.rule_id} @ ${head.path || '<root>'}: ${head.message}`
+            : 'inline AgentSpec rejected (no issues reported)';
+        const tail = issues.length > 1 ? ` (+${issues.length - 1} more)` : '';
+        super(`Inline AgentSpec rejected at intake — ${summary}${tail}`);
+        this.issues = issues;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class QodoAgentSpecRejectedError extends Error {
+    name = 'QodoAgentSpecRejectedError';
+    /** Wire-aligned error code. */
+    code = 'agent_spec_rejected';
+    /** Per-violation breakdown — at least one entry. */
+    issues;
+    /** Convenience: first issue's `rule_id` (`'D10-R*'` or `'D10-UNSUPPORTED*'`). */
+    rule_id;
+    /** Convenience: first issue's `path` (RFC 6901 JSON Pointer; `""` = root). */
+    path;
+    constructor(issues, message) {
+        const primary = issues[0];
+        if (primary === undefined) {
+            throw new TypeError('QodoAgentSpecRejectedError requires at least one issue (got an empty array)');
+        }
+        const summary = `${primary.rule_id} @ ${primary.path || '<root>'}: ${primary.message}`;
+        const tail = issues.length > 1 ? ` (+${issues.length - 1} more)` : '';
+        super(message ?? `Inline AgentSpec rejected by server — ${summary}${tail}`);
+        this.issues = issues;
+        this.rule_id = primary.rule_id;
+        this.path = primary.path;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class QodoServerError extends Error {
+    /** Wire-level QAR error code. Pinned per subclass. */
+    code;
+    /**
+     * Structured per-rule breakdown, if QAR shipped one on the envelope. Empty
+     * array when the envelope only carried top-level `code` + `message`.
+     */
+    errors;
+    /** `payload.offending_message_id` — useful for tracing the cause envelope. */
+    offendingMessageId;
+    /**
+     * @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, code, message, errors = [], offendingMessageId) {
+        super(message);
+        this.name = name;
+        this.code = code;
+        this.errors = errors;
+        if (offendingMessageId !== undefined)
+            this.offendingMessageId = offendingMessageId;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Cancel routing lookup failed — see QAR `_handle_task_cancel`. */
+export class QodoCancelRoutingFailedError extends QodoServerError {
+    name = 'QodoCancelRoutingFailedError';
+    constructor(message, errors, offendingMessageId) {
+        super('QodoCancelRoutingFailedError', 'cancel_routing_failed', message, errors, offendingMessageId);
+    }
+}
+/** Cancel all-writes-fail — see QAR `_handle_task_cancel`. */
+export class QodoCancelFailedError extends QodoServerError {
+    name = 'QodoCancelFailedError';
+    constructor(message, errors, offendingMessageId) {
+        super('QodoCancelFailedError', 'cancel_failed', message, errors, offendingMessageId);
+    }
+}
+/** Session lookup miss — `cancel`/`continue` against an unknown task. */
+export class QodoTaskNotFoundError extends QodoServerError {
+    name = 'QodoTaskNotFoundError';
+    constructor(message, errors, offendingMessageId) {
+        super('QodoTaskNotFoundError', 'task_not_found', message, errors, offendingMessageId);
+    }
+}
+/** Cancel-on-non-waiting-task — see QAR `_handle_task_cancel` precondition. */
+export class QodoTaskNotWaitingError extends QodoServerError {
+    name = 'QodoTaskNotWaitingError';
+    constructor(message, errors, offendingMessageId) {
+        super('QodoTaskNotWaitingError', 'task_not_waiting', message, errors, offendingMessageId);
+    }
+}
+/** Pod failed to reconstruct the agent for a cross-pod task. */
+export class QodoAgentReconstructionFailedError extends QodoServerError {
+    name = 'QodoAgentReconstructionFailedError';
+    constructor(message, errors, offendingMessageId) {
+        super('QodoAgentReconstructionFailedError', 'agent_reconstruction_failed', message, errors, offendingMessageId);
+    }
+}
+/** Cross-pod resume hook aborted before delivering control. */
+export class QodoCrossPodResumeAbortedError extends QodoServerError {
+    name = 'QodoCrossPodResumeAbortedError';
+    constructor(message, errors, offendingMessageId) {
+        super('QodoCrossPodResumeAbortedError', 'cross_pod_resume_aborted', message, errors, offendingMessageId);
+    }
+}
+/** Deps construction failed during agent dispatch (Pattern A/B/C). */
+export class QodoDepsConstructionFailedError extends QodoServerError {
+    name = 'QodoDepsConstructionFailedError';
+    constructor(message, errors, offendingMessageId) {
+        super('QodoDepsConstructionFailedError', 'deps_construction_failed', message, errors, offendingMessageId);
+    }
+}
+/** Message history load failed during resume / continue. */
+export class QodoMessageHistoryLoadFailedError extends QodoServerError {
+    name = 'QodoMessageHistoryLoadFailedError';
+    constructor(message, errors, offendingMessageId) {
+        super('QodoMessageHistoryLoadFailedError', 'message_history_load_failed', message, errors, offendingMessageId);
+    }
+}
+/** HITL persistence failure — substrate accepted but the row didn't durable. */
+export class QodoHitlPersistFailedError extends QodoServerError {
+    name = 'QodoHitlPersistFailedError';
+    constructor(message, errors, offendingMessageId) {
+        super('QodoHitlPersistFailedError', 'hitl_persist_failed', message, errors, offendingMessageId);
+    }
+}
+/** HITL substrate unavailable — backing store offline / unconfigured. */
+export class QodoHitlSubstrateUnavailableError extends QodoServerError {
+    name = 'QodoHitlSubstrateUnavailableError';
+    constructor(message, errors, offendingMessageId) {
+        super('QodoHitlSubstrateUnavailableError', 'hitl_substrate_unavailable', message, errors, offendingMessageId);
+    }
+}
+/** Caller is not the authorized resolver for the HITL row. */
+export class QodoUnauthorizedResolverError extends QodoServerError {
+    name = 'QodoUnauthorizedResolverError';
+    constructor(message, errors, offendingMessageId) {
+        super('QodoUnauthorizedResolverError', 'unauthorized_resolver', message, errors, offendingMessageId);
+    }
+}
+/** HITL resolution payload failed validation against the prompt's schema. */
+export class QodoInvalidResolutionError extends QodoServerError {
+    name = 'QodoInvalidResolutionError';
+    constructor(message, errors, offendingMessageId) {
+        super('QodoInvalidResolutionError', 'invalid_resolution', message, errors, offendingMessageId);
+    }
+}
+/**
+ * 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 class QodoGraphSpecRejectedError extends QodoServerError {
+    name = 'QodoGraphSpecRejectedError';
+    constructor(message, errors, offendingMessageId) {
+        super('QodoGraphSpecRejectedError', 'graph_spec_rejected', message, errors, offendingMessageId);
+    }
+}
+/**
+ * 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 class QodoSessionMismatchError extends QodoServerError {
+    name = 'QodoSessionMismatchError';
+    constructor(message, errors, offendingMessageId) {
+        super('QodoSessionMismatchError', 'session_mismatch', message, errors, offendingMessageId);
+    }
+}
+/**
+ * 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 class QodoAdmissionStalledError extends QodoServerError {
+    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;
+    constructor(message, errors, offendingMessageId) {
+        super('QodoAdmissionStalledError', 'admission_stalled', message, errors, offendingMessageId);
+    }
+    /** Internal — set by the envelope-to-error helper. Read-once-after-construct. */
+    attachSessionId(sessionId) {
+        if (this.sessionId === undefined)
+            this.sessionId = sessionId;
+    }
+}
+/**
+ * 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 class QodoStreamAbortedError extends Error {
+    name = 'QodoStreamAbortedError';
+    constructor(message) {
+        super(message ??
+            'TaskStartIterable consumer broke the iterator before task.started arrived. ' +
+                'admittedTaskId / sessionId Promises were rejected to prevent indefinite hangs.');
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class QodoAdmissionTimeoutError extends Error {
+    name = 'QodoAdmissionTimeoutError';
+    /** Total wall-clock milliseconds spent retrying before giving up. */
+    elapsedMs;
+    /** Number of `admission_in_progress` envelopes observed before timing out. */
+    attempts;
+    /** Derived `session_id` from the final envelope, if observed. */
+    sessionId;
+    constructor(elapsedMs, attempts, sessionId) {
+        super(`tasks.start admission stayed in 'admission_in_progress' for ${elapsedMs}ms ` +
+            `across ${attempts} retries — exceeded PENDING_ADMISSION_TIMEOUT. Surface to ` +
+            `operators or task.resubscribe against the derived session_id.`);
+        this.elapsedMs = elapsedMs;
+        this.attempts = attempts;
+        if (sessionId !== undefined)
+            this.sessionId = sessionId;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class QodoUnknownServerError extends QodoServerError {
+    name = 'QodoUnknownServerError';
+    constructor(code, message, errors, offendingMessageId) {
+        super('QodoUnknownServerError', code, message, errors, offendingMessageId);
+    }
+}
+/**
+ * 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 function classForServerErrorCode(code) {
+    switch (code) {
+        case 'cancel_routing_failed':
+            return QodoCancelRoutingFailedError;
+        case 'cancel_failed':
+            return QodoCancelFailedError;
+        case 'task_not_found':
+            return QodoTaskNotFoundError;
+        case 'task_not_waiting':
+            return QodoTaskNotWaitingError;
+        case 'agent_reconstruction_failed':
+            return QodoAgentReconstructionFailedError;
+        case 'cross_pod_resume_aborted':
+            return QodoCrossPodResumeAbortedError;
+        case 'deps_construction_failed':
+            return QodoDepsConstructionFailedError;
+        case 'message_history_load_failed':
+            return QodoMessageHistoryLoadFailedError;
+        case 'hitl_persist_failed':
+            return QodoHitlPersistFailedError;
+        case 'hitl_substrate_unavailable':
+            return QodoHitlSubstrateUnavailableError;
+        case 'unauthorized_resolver':
+            return QodoUnauthorizedResolverError;
+        case 'invalid_resolution':
+            return QodoInvalidResolutionError;
+        case 'graph_spec_rejected':
+            return QodoGraphSpecRejectedError;
+        case 'admission_stalled':
+            // Terminal admission failure. The factory signature matches every
+            // other typed-error subclass; the SDK's wrap helpers can construct
+            // one even though `QodoAdmissionStalledError` additionally exposes
+            // `sessionId` — that field is populated separately by
+            // `errorFromServerErrorEnvelope` reading the envelope's inherited
+            // `session_id`.
+            return QodoAdmissionStalledError;
+        case 'session_mismatch':
+            // Server-side wire rejection when the outbound envelope's
+            // `session_id` doesn't match the connection's bound session for
+            // the referenced task. The SDK no longer mints a zero-UUID
+            // sentinel for cold-address calls — the typed `session_mismatch`
+            // now fires only when a consumer-supplied cold-address override
+            // is wrong (stale durable-storage row, deliberate mismatch test).
+            // The dispatch path prunes the polluted `taskSessions` entry on
+            // this code so the next no-override call correctly raises
+            // {@link QodoColdAddressError}.
+            return QodoSessionMismatchError;
+        default:
+            return 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 class QodoMcpClientError extends Error {
+    name = 'QodoMcpClientError';
+    /** Registered MCP name (the `name` argument passed to `qar.registerMcp`). */
+    mcpName;
+    /** Transport discriminator from the failing config. */
+    transport;
+    constructor(mcpName, transport, message, cause) {
+        super(message, cause !== undefined ? { cause } : undefined);
+        this.mcpName = mcpName;
+        this.transport = transport;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class QodoMcpToolError extends Error {
+    name = 'QodoMcpToolError';
+    /** Registered MCP name (the `name` argument passed to `qar.registerMcp`). */
+    mcpName;
+    /** MCP tool name that failed (the `name` field of the `callTool` request). */
+    toolName;
+    /**
+     * MCP envelope when the tool returned `isError: true`. Absent for pure
+     * transport failures (those carry the underlying error on `cause`).
+     */
+    mcpResult;
+    constructor(mcpName, toolName, message, opts) {
+        super(message, opts?.cause !== undefined ? { cause: opts.cause } : undefined);
+        this.mcpName = mcpName;
+        this.toolName = toolName;
+        if (opts?.mcpResult !== undefined)
+            this.mcpResult = opts.mcpResult;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 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 class ToolDeniedError extends Error {
+    name = 'ToolDeniedError';
+    constructor(reason) {
+        super(reason);
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+//# sourceMappingURL=errors.js.map