@qodo/sdk 0.13.4 → 2.0.0-next.0

package/dist/client/TaskClient.js

@@ -0,0 +1,2522 @@
+/**
+ * `TaskClient` — task lifecycle surface, mirroring QAR's `task.*` envelope kinds.
+ */
+import { collectInlineAgentSpecPreWireIssues, normalizeInlineAgentSpec } from '../qar/agentSpec.js';
+import { TaskSubscription } from './connection.js';
+import { AsyncQueue } from './iterator.js';
+import { longestPathFrom, validateInlineGraphSpec, } from './inlineGraph.js';
+import { classForServerErrorCode, QodoAdmissionStalledError, QodoAdmissionTimeoutError, QodoAgentSpecRejectedError, QodoCancelAbortedError, QodoIdempotencyKeyValidationError, QodoInlineAgentValidationError, QodoInlineGraphValidationError, QodoMcpUnavailableError, QodoStreamAbortedError, QodoUnknownMcpError, QodoUnknownMcpToolError, QodoUnknownServerError, RequiredGraphSpecError, } from './errors.js';
+import { McpClientPool } from './mcp/McpClientPool.js';
+import { projectMcpTools } from './mcp/projection.js';
+import { qodoSkillsFunctionToolDefs } from '../skills/mcp/server.js';
+import { asMessageId, asTaskId, uuidv7 } from './uuid.js';
+import { QodoSkillError, SkillAmbiguousPinError, SkillNotFoundError, SkillsBudgetExceededError, } from '../skills/manager.js';
+import { injectIntoAgentSpec, injectIntoGraphSpec, } from '../skills/inject.js';
+import { activationFailureMessage, lookupFromSnapshot, renderActiveSkillsBlock, resolveAllActivations, } from '../skills/activation.js';
+export class TaskClient {
+    resolveConnection;
+    spanRecorder;
+    registry;
+    resolveSpecs;
+    metrics;
+    skills;
+    bindFunctionToolDefs;
+    /**
+     * @param resolveConnection Returns the live `Connection` or throws if the
+     *                          client isn't connected yet.
+     * @param spanRecorder      Recorder for `qar.client.task.*` spans. No-op
+     *                          when OTel isn't configured.
+     * @param registry          Local agent + MCP registries. `tasks.start` reads
+     *                          this to resolve `RegisteredAgentRef` → wire
+     *                          `agent_id`.
+     * @param resolveSpecs      Lazily-resolved `SpecsClient` used by the
+     *                          opt-in `preflight: true` path on
+     *                          `startWithGraph()`. Lazy because `QodoClient`
+     *                          constructs `tasks` before `specs`; defer
+     *                          dereference until the caller actually asks
+     *                          for pre-flight validation.
+     */
+    constructor(resolveConnection, spanRecorder, registry, resolveSpecs, 
+    /**
+     * Transport-metric store passed through to each constructed
+     * `TaskSubscription` so the connection's reconnect/replay path can
+     * increment `replay_envelopes_received_total` /
+     * `replay_anchor_missing_total` against absorbed envelopes. Optional
+     * for back-compat with consumers wiring `TaskClient` directly in
+     * tests; production wires from `QodoClient`.
+     */
+    metrics, 
+    /**
+     * Skills foundation manager. When provided, the `startWithAgent` and
+     * `startWithGraph` paths await the manager's `discover()` (idempotent)
+     * and append the rendered slim index to the spec's `instructions`
+     * before the wire write. Undefined when the consumer didn't pass
+     * `ClientOptions.skills` — those paths stay verbatim.
+     */
+    skills, 
+    /**
+     * `defineFunctionTool` auto-bind hook. Called at every
+     * `startWithAgent` / `startWithGraph` entry point so handlers
+     * attached to `FunctionToolDef` entries (via the helper's
+     * symbol-keyed handler bag) get installed on the `ToolClient`
+     * before the wire `task.start` lands. Optional — when undefined
+     * (e.g. `TaskClient` constructed in isolation in tests), the bind
+     * step is skipped and consumers fall back to manual
+     * `client.tools.onRequest(...)` registration.
+     */
+    bindFunctionToolDefs) {
+        this.resolveConnection = resolveConnection;
+        this.spanRecorder = spanRecorder;
+        this.registry = registry;
+        this.resolveSpecs = resolveSpecs;
+        this.metrics = metrics;
+        this.skills = skills;
+        this.bindFunctionToolDefs = bindFunctionToolDefs;
+    }
+    /**
+     * Send `task.start` and yield the resulting `TaskEvent` stream until `task.done`.
+     *
+     * The iterator is the canonical streaming primitive — consumers `for await` and
+     * `switch (event.kind)` over the QAR discriminator. Breaking the iterator
+     * before `task.done` arrives sends a best-effort `task.cancel` so the runtime
+     * can free its resources promptly.
+     *
+     * `payload.agent_id` accepts either a wire-shape `string` or a
+     * `RegisteredAgentRef` from `client.qar.registerAgent`. Refs are resolved
+     * to `ref.name` for the outgoing envelope; the local agent body never
+     * crosses the wire.
+     */
+    start(payload, opts) {
+        // Validate `idempotencyKey` synchronously before the wire write.
+        // Throws `QodoIdempotencyKeyValidationError` on bad inputs — fail-fast
+        // DX rather than waiting for QAR to round-trip an error envelope.
+        if (opts?.idempotencyKey !== undefined) {
+            validateIdempotencyKey(opts.idempotencyKey);
+        }
+        const resolvedAgentId = this.registry.resolveAgentId(payload.agent_id);
+        const wirePayload = {
+            ...payload,
+            agent_id: resolvedAgentId,
+            // Forward the caller-supplied key under the wire snake_case name.
+            // Strip the field entirely when absent — server treats
+            // `idempotency_key: null` and field-absent identically per the
+            // Pydantic `default=None` semantic, but the SDK keeps the wire
+            // shape minimal so a fresh-eyes diff of the encoded JSON shows
+            // exactly the consumer's intent.
+            ...(opts?.idempotencyKey !== undefined ? { idempotency_key: opts.idempotencyKey } : {}),
+        };
+        // Pre-allocate the root message id at the public-API boundary so the
+        // derived `task_id` (= `task.start.message_id`) is available
+        // synchronously on the returned iterable. The iterable's `taskId`
+        // property lets consumers call `client.tasks.cancel(stream.taskId)`
+        // without waiting for the first inbound envelope.
+        const rootMessageId = asMessageId(uuidv7());
+        const taskId = asTaskId(rootMessageId);
+        // Deferred Promises for the `task.started` admission ack —
+        // `sessionId` for the server-derived session UUID and
+        // `admittedTaskId` for the canonical task_id. Both settle
+        // atomically on the same admission outcome.
+        const sessionIdDeferred = createDeferred();
+        const admittedTaskIdDeferred = createDeferred();
+        const admissionResultDeferred = createDeferred();
+        const ackDeferreds = {
+            sessionIdDeferred,
+            admittedTaskIdDeferred,
+            admissionResultDeferred,
+        };
+        // Closure used by both the single-shot path and the admission
+        // retry wrapper. Each call builds a fresh subscription against the
+        // supplied rootMessageId — on retry the wrapper passes a fresh id so
+        // the duplicate-message-id guard in `Connection.sendEnvelope` stays
+        // happy.
+        const dispatch = (rmid) => this.subscribeAndSend(() => ({ kind: 'task.start', payload: wirePayload, rootMessageId: rmid }), asTaskId(rmid), opts, undefined, (sessionId, messageId) => this.spanRecorder.startTaskStartSpan({
+            sessionId,
+            messageId,
+            agentId: resolvedAgentId,
+            ...(wirePayload.skill !== undefined && wirePayload.skill !== null
+                ? { skillName: wirePayload.skill }
+                : {}),
+        }).lifecycle, rmid, ackDeferreds);
+        // Only the deterministic-key path ever sees `admission_in_progress`
+        // (the omitted-key path mints a fresh uuidv7 server-side per call —
+        // no collisions possible). Wrap with the retry layer when the key is
+        // present; otherwise stay on the existing fast path so the DX
+        // default doesn't pay the extra iterator-wrapping cost. Either way
+        // the first attempt is dispatched eagerly so the wire `task.start`
+        // is in flight before the public method returns (preserves the
+        // `cancel(stream.taskId)` race-free contract).
+        const firstSub = dispatch(rootMessageId);
+        const iter = opts?.idempotencyKey !== undefined
+            ? TaskClient.wrapWithAdmissionRetry(firstSub, dispatch, sessionIdDeferred, admittedTaskIdDeferred, admissionResultDeferred)
+            : // Wrap server errors on the by-id path too. It doesn't have its
+                // own spec rejection but the cancel/resume/HITL families apply
+                // to any running task.
+                TaskClient.wrapServerErrorsIterator(firstSub);
+        return attachTaskId(iter, taskId, admittedTaskIdDeferred.promise, sessionIdDeferred.promise, admissionResultDeferred.promise);
+    }
+    /**
+     * Send `task.start { agent, input }` and yield the resulting `TaskEvent`
+     * stream until `task.done` — inline-AgentSpec dispatch.
+     *
+     * The spec is validated client-side (the SDK-enforceable rule subset,
+     * see `collectInlineAgentSpecPreWireIssues`) BEFORE the envelope hits
+     * the wire. A `QodoInlineAgentValidationError` is thrown when any
+     * forbidden-key or missing-required-field rule fails — the error's
+     * `issues` array carries every violation with a `rule_id` +
+     * JSON-Pointer `path` so consumers can route both client-side and
+     * server-side rejections through the same branch logic.
+     *
+     * Opt into `{ preflight: true }` to additionally call
+     * `client.specs.validate(agent)` (HTTP) before opening the task — that
+     * catches the rules the SDK can't enforce locally (catalog tool
+     * registration, skill version pinning, spawnable `agent_id`
+     * resolution). Default `false`.
+     *
+     * Iterator + early-termination semantics match `start()` — breaking the
+     * iterator before `task.done` arrives sends best-effort `task.cancel`.
+     * Inline-agent spans carry `qar.agent.kind = "inline"` and
+     * `qar.agent_id = "inline:<message_id>"`.
+     *
+     * Server-side rejection: when QAR's `_handle_task_start` emits an
+     * `error { code: 'agent_spec_rejected' }` envelope, the iterator
+     * rejects with `QodoAgentSpecRejectedError` instead of yielding the
+     * envelope as a `kind: 'error'` event — consumers don't need to
+     * defensively narrow the error case out of `TaskEvent.kind`.
+     */
+    startWithAgent(payload, opts) {
+        // Cheap fail-fast `idempotencyKey` check runs BEFORE the agent-spec
+        // validator so a typo'd key surfaces ahead of the
+        // potentially-multi-issue spec validation pass.
+        if (opts?.idempotencyKey !== undefined) {
+            validateIdempotencyKey(opts.idempotencyKey);
+        }
+        // Pre-wire validation — synchronous, no IO, fail fast before either
+        // the optional pre-flight HTTP call or the WS write. Collect-then-throw
+        // so the consumer sees every rule in one go (better for IDE / Studio
+        // surfaces showing multiple diagnostics simultaneously).
+        const preIssues = collectInlineAgentSpecPreWireIssues(payload.agent);
+        if (preIssues.length > 0) {
+            throw new QodoInlineAgentValidationError(preIssues);
+        }
+        // `defineFunctionTool` auto-bind. Any `FunctionToolDef` in the
+        // spec's `tools[]` that carries the SDK-local handler symbol gets
+        // registered with the per-client `FunctionToolRouter` so the
+        // inbound `tool.request` dispatch knows where to route calls. The
+        // wire envelope itself stays unchanged — the handler lives behind a
+        // Symbol that `JSON.stringify` skips.
+        if (this.bindFunctionToolDefs !== undefined && payload.agent.tools != null) {
+            this.bindFunctionToolDefs(payload.agent.tools);
+        }
+        // Pre-allocate root message id at the public-API boundary so `taskId`
+        // is synchronously available on the returned iterable.
+        const rootMessageId = asMessageId(uuidv7());
+        const taskId = asTaskId(rootMessageId);
+        const sessionIdDeferred = createDeferred();
+        const admittedTaskIdDeferred = createDeferred();
+        const admissionResultDeferred = createDeferred();
+        const ackDeferreds = {
+            sessionIdDeferred,
+            admittedTaskIdDeferred,
+            admissionResultDeferred,
+        };
+        // Slim-index injection. When the manager has finished discovery,
+        // inject synchronously — the common case once `client.connect()` has
+        // resolved (connect awaits manager.discover()). When the snapshot
+        // isn't ready yet (consumer called startWithAgent before connect
+        // resolved), fall through to the eager-promise dispatch path so we
+        // await discover() before the wire write.
+        const skillsPinned = opts?.skills;
+        const needsSkillsAwait = this.skills !== undefined && this.skills.currentSnapshot === null;
+        // MCP projection. When the consumer set `mcpTools` (or the sibling
+        // `mcpToolOverrides`), the wire-boundary projection must await the
+        // pool's catalog-settle window — so route through the
+        // eager-promise dispatch path. The sync path stays for the
+        // no-discovery / no-overrides DX-default case.
+        const needsMcpProjection = payload.agent.mcpTools !== undefined ||
+            payload.agent.mcpToolOverrides !== undefined;
+        let agentForWire = normalizeInlineAgentSpec(payload.agent);
+        // Skills inject runs sync ONLY when neither async-path trigger is
+        // armed. `needsMcpProjection` forces the eager-async dispatch
+        // route, and that route re-runs `applyAgentSkillsInjection` inside
+        // `runAgentPreflightAndDispatch`. The slim-index / active-skills
+        // injector is not idempotent (it appends content), so double-
+        // applying duplicates the instruction text. Gate the sync branch
+        // on BOTH `!needsSkillsAwait` AND `!needsMcpProjection`.
+        if (this.skills !== undefined && !needsSkillsAwait && !needsMcpProjection) {
+            agentForWire = this.applyAgentSkillsInjection(agentForWire, skillsPinned, opts?.skillsCurrentFile);
+        }
+        // Auto-include the qodo-skills.* tool surface in the sync-dispatch
+        // path so the `<available_skills>` preamble's instruction ("Use the
+        // qodo-skills.get_skill tool to ...") is actionable. The async
+        // projection path runs the same merge inside
+        // `projectMcpToolsForWire` so callers that DO hit that branch get
+        // the same wire surface. Sync auto-include doesn't need a settle
+        // wait — the 3 tool defs are constants.
+        if (this.skills !== undefined && !needsMcpProjection) {
+            const original = agentForWire.tools ?? [];
+            const merged = mergeQodoSkillsTools(original);
+            if (merged !== original) {
+                agentForWire = { ...agentForWire, tools: merged };
+            }
+        }
+        const wirePayload = {
+            agent: agentForWire,
+            input: payload.input ?? {},
+            ...(payload.skill !== undefined && payload.skill !== null
+                ? { skill: payload.skill }
+                : {}),
+            // Forward the caller-supplied key under the wire snake_case name.
+            // Strip when absent so the encoded JSON matches the DX-default
+            // path one-to-one (server treats absent and `null` identically per
+            // Pydantic, but the SDK keeps the wire minimal for readability).
+            ...(opts?.idempotencyKey !== undefined
+                ? { idempotency_key: opts.idempotencyKey }
+                : {}),
+        };
+        // Pre-flight branch: validate FIRST via `POST /v1/specs/validate`,
+        // and only then call `subscribeAndSend()` to write `task.start` on
+        // the wire. Without this ordering the wire write fires before the
+        // HTTP validate resolves, and a rule-rejected spec would still
+        // start a server task. The non-preflight path stays synchronous so
+        // the common case avoids the async-generator microtask boundary.
+        if (opts?.preflight === true || needsSkillsAwait || needsMcpProjection) {
+            // Kick off preflight + (on success) `subscribeAndSend` eagerly so
+            // the wire `task.start` is in flight by the time the public method
+            // returns. Without this, a consumer that reads `stream.taskId` and
+            // calls `tasks.cancel(stream.taskId)` before iterating would race
+            // the cancel envelope ahead of the (still-deferred) `task.start`.
+            // The iterable then awaits the eager promise and yields from the
+            // resulting subscription.
+            const subPromise = this.runAgentPreflightAndDispatch(wirePayload, opts ?? {}, rootMessageId, taskId, ackDeferreds);
+            // Swallow the unhandled-rejection until the consumer iterates and
+            // we re-throw via `yieldFromPromisedSub`. Without this attach,
+            // Node treats the rejection as "unhandled" during the microtask
+            // window between dispatch failure and consumer iteration.
+            subPromise.catch((err) => {
+                // Surface the preflight failure to anyone awaiting
+                // `stream.sessionId` / `stream.admittedTaskId` so the promises
+                // don't hang.
+                const wrapped = err instanceof Error ? err : new Error(String(err));
+                if (!sessionIdDeferred.settled())
+                    sessionIdDeferred.reject(wrapped);
+                if (!admittedTaskIdDeferred.settled())
+                    admittedTaskIdDeferred.reject(wrapped);
+                if (!admissionResultDeferred.settled())
+                    admissionResultDeferred.reject(wrapped);
+            });
+            return attachTaskId(yieldFromPromisedSub(subPromise, true), taskId, admittedTaskIdDeferred.promise, sessionIdDeferred.promise, admissionResultDeferred.promise);
+        }
+        // Closure used by both single-shot dispatch and the admission retry
+        // wrapper (when `idempotencyKey` is set). Each call builds a fresh
+        // subscription against the supplied rootMessageId.
+        const dispatch = (rmid) => this.subscribeAndSend(() => ({
+            kind: 'task.start',
+            payload: wirePayload,
+            rootMessageId: rmid,
+        }), asTaskId(rmid), opts, undefined, (sessionId, messageId) => this.spanRecorder.startTaskStartSpan({
+            sessionId,
+            messageId,
+            agentId: `inline:${messageId}`,
+            agentKind: 'inline',
+            ...(wirePayload.skill !== undefined && wirePayload.skill !== null
+                ? { skillName: wirePayload.skill }
+                : {}),
+        }).lifecycle, rmid, ackDeferreds);
+        const firstSub = dispatch(rootMessageId);
+        const iter = opts?.idempotencyKey !== undefined
+            ? TaskClient.wrapWithAdmissionRetry(firstSub, dispatch, sessionIdDeferred, admittedTaskIdDeferred, admissionResultDeferred)
+            : TaskClient.wrapServerErrorsIterator(firstSub);
+        return attachTaskId(iter, taskId, admittedTaskIdDeferred.promise, sessionIdDeferred.promise, admissionResultDeferred.promise);
+    }
+    /**
+     * Eagerly run `client.specs.validate(agent)` and, on success, dispatch
+     * the `task.start` envelope via `subscribeAndSend`. Returns a
+     * `Promise<TaskSubscription>` that resolves once the wire write has
+     * happened — kicked off in the public method body so the dispatch is
+     * in flight by the time the consumer can read `stream.taskId`.
+     *
+     * `preflight: true` still means "validate before the wire write" per
+     * the documented contract; we just no longer wait for iteration to
+     * start the validate.
+     *
+     * Server-side rule failures throw `QodoAgentSpecRejectedError` so
+     * consumers route SDK + server rejections through one branch.
+     */
+    async runAgentPreflightAndDispatch(wirePayload, opts, rootMessageId, taskId, 
+    /**
+     * Deferred pair for the `task.started` admission ack (sessionId +
+     * admittedTaskId). Forwarded into the eventual `subscribeAndSend` so
+     * the inbound ack resolves both caller-facing Promises on the
+     * `TaskStartIterable`.
+     */
+    ackDeferreds) {
+        // Await skills discovery (idempotent) and inject before (a) the
+        // optional /v1/specs/validate call, so the validator sees the full
+        // agent spec the consumer will dispatch, and (b) the wire write.
+        let finalPayload = wirePayload;
+        if (this.skills !== undefined) {
+            await this.skills.discover();
+            const injectedAgent = this.applyAgentSkillsInjection(wirePayload.agent, opts.skills, opts.skillsCurrentFile);
+            finalPayload = { ...wirePayload, agent: injectedAgent };
+        }
+        // MCP projection. Runs AFTER skills inject (skills mutate
+        // instructions, never tools) and BEFORE the optional /v1/specs/validate
+        // call so the validator sees the post-projection `tools[]` the wire
+        // envelope will carry. Throws synchronously on unknown / unreachable
+        // MCPs — the caller already wrapped this call in a `.catch` that
+        // settles `sessionId` / `admittedTaskId` deferreds so the thrown
+        // error reaches every consumer await.
+        const projectedAgent = await this.projectMcpToolsForWire(finalPayload.agent);
+        if (projectedAgent !== finalPayload.agent) {
+            finalPayload = { ...finalPayload, agent: projectedAgent };
+        }
+        if (opts.preflight !== true) {
+            // Skills-only async path — no preflight HTTP call. Dispatch now.
+            return this.subscribeAndSend(() => ({
+                kind: 'task.start',
+                payload: finalPayload,
+                rootMessageId,
+            }), taskId, opts, undefined, (sessionId, messageId) => this.spanRecorder.startTaskStartSpan({
+                sessionId,
+                messageId,
+                agentId: `inline:${messageId}`,
+                agentKind: 'inline',
+                ...(finalPayload.skill !== undefined && finalPayload.skill !== null
+                    ? { skillName: finalPayload.skill }
+                    : {}),
+            }).lifecycle, rootMessageId, ackDeferreds);
+        }
+        const resolver = this.resolveSpecs;
+        if (resolver === undefined) {
+            throw new Error("tasks.startWithAgent({ preflight: true }) requires the client's SpecsClient — " +
+                'this TaskClient was constructed without a specs resolver');
+        }
+        const result = await resolver().validate(finalPayload.agent);
+        if (!result.valid) {
+            // `SpecValidateResult` guarantees `errors.length > 0` on the
+            // `valid: false` arm, but a misbehaving server could violate it.
+            // Synthesize a single `preflight_rejected` issue so
+            // `QodoAgentSpecRejectedError`'s constructor invariant always
+            // holds and we surface a readable message rather than crashing
+            // the iterator with a TypeError.
+            const issues = result.errors.length > 0
+                ? result.errors.map((e) => ({
+                    rule_id: e.rule_id,
+                    path: e.path,
+                    message: e.message,
+                }))
+                : [
+                    {
+                        rule_id: 'preflight_rejected',
+                        path: '',
+                        message: 'Pre-flight validation rejected the spec without reporting rule_ids',
+                    },
+                ];
+            const head = issues[0];
+            throw new QodoAgentSpecRejectedError(issues, `Inline AgentSpec rejected by pre-flight (POST /v1/specs/validate): ` +
+                `${head.rule_id} @ ${head.path || '<root>'}: ${head.message}`);
+        }
+        // Pre-flight passed — write `task.start` on the wire now.
+        return this.subscribeAndSend(() => ({
+            kind: 'task.start',
+            payload: finalPayload,
+            rootMessageId,
+        }), taskId, opts, undefined, (sessionId, messageId) => this.spanRecorder.startTaskStartSpan({
+            sessionId,
+            messageId,
+            agentId: `inline:${messageId}`,
+            agentKind: 'inline',
+            ...(finalPayload.skill !== undefined && finalPayload.skill !== null
+                ? { skillName: finalPayload.skill }
+                : {}),
+        }).lifecycle, rootMessageId, ackDeferreds);
+    }
+    /**
+     * Wrap the underlying subscription so a server-side `error { code: ... }`
+     * envelope arriving on the iterator surfaces as a rejected typed error
+     * instead of a yielded `kind: 'error'` event. Covers the documented
+     * typed-error catalog:
+     *
+     *   - `agent_spec_rejected` → `QodoAgentSpecRejectedError`
+     *   - the cancel / resume / HITL / graph code family → the matching
+     *     `QodoServerError` subclass
+     *
+     * Other error envelopes (`replay_anchor_missing`,
+     * `envelope_parse_error`, future codes the SDK hasn't catalogued)
+     * pass through unchanged as `kind: 'error'` iterator events so
+     * existing consumer code reading them keeps working. Callers that
+     * want to convert an arbitrary error envelope into a typed throw
+     * can wrap it themselves with `QodoUnknownServerError` (exposed via
+     * the public surface) or `errorFromServerErrorEnvelope` (internal,
+     * stable across the typed catalog).
+     *
+     * Non-error envelopes pass through unchanged.
+     *
+     * **Why this isn't an `async function*`.** Native async generators don't
+     * propagate `.return()` to the inner iterator until the generator's
+     * body has entered (one `.next()` call has fired). The SDK's
+     * iterator-early-termination contract is that breaking the iterator
+     * BEFORE the first envelope arrives still fires a best-effort
+     * `task.cancel` — that relies on `.return()` reaching `sub.return()`.
+     * The explicit iterator object below forwards every protocol call
+     * straight to the underlying subscription's iterator so the
+     * cancel-on-break path stays intact.
+     */
+    static wrapServerErrorsIterator(inner) {
+        return {
+            [Symbol.asyncIterator]() {
+                const innerIter = inner[Symbol.asyncIterator]();
+                return {
+                    async next() {
+                        const result = await innerIter.next();
+                        if (!result.done && result.value.kind === 'error') {
+                            const code = result.value.payload.code;
+                            if (typeof code === 'string' && isTypedErrorCode(code)) {
+                                // Drain the underlying subscription before throwing — the
+                                // `error` envelope already closed the inner queue on the
+                                // SDK side, but defensive in case a downstream wraps a
+                                // longer-lived iterator.
+                                innerIter.return?.().catch(() => undefined);
+                                throw errorFromServerErrorEnvelope(result.value);
+                            }
+                        }
+                        return result;
+                    },
+                    async return(value) {
+                        if (innerIter.return !== undefined) {
+                            return innerIter.return(value);
+                        }
+                        return { value: value, done: true };
+                    },
+                    async throw(err) {
+                        if (innerIter.throw !== undefined) {
+                            return innerIter.throw(err);
+                        }
+                        throw err instanceof Error ? err : new Error(String(err));
+                    },
+                };
+            },
+        };
+    }
+    /**
+     * Send `task.start { graph, input }` and yield the resulting `TaskEvent`
+     * stream until `task.done` — inline-graph-spec dispatch.
+     *
+     * The graph is validated client-side (the SDK-enforceable rule subset,
+     * see `validateInlineGraphSpec`) BEFORE the envelope hits the wire. A
+     * `QodoInlineGraphValidationError` is thrown when any rule fails — the
+     * error's `failures` array carries every violation with a `rule_id` +
+     * JSON-Pointer `path` so consumers can route both client-side and
+     * server-side rejections through the same branch logic.
+     *
+     * Opt into `{ preflight: true }` to additionally call
+     * `client.specs.validate(graph)` (HTTP) before opening the task — that
+     * catches the rules the SDK can't enforce locally (model registry probes,
+     * AgentSpec composition against the live agent table). Default `false`.
+     *
+     * Iterator + early-termination semantics match `start()` — breaking the
+     * iterator before `task.done` arrives sends best-effort `task.cancel`.
+     * Inline-graph spans carry `qar.graph.entry`, `qar.graph.depth`, and
+     * `qar.agent.kind = "inline"` attrs in addition to the standard
+     * `qar.client.task.start` set.
+     */
+    startWithGraph(payload, opts) {
+        // Cheap fail-fast `idempotencyKey` check runs BEFORE the graph
+        // validator so a typo'd key surfaces immediately, ahead of the
+        // potentially-multi-issue graph validation pass.
+        if (opts?.idempotencyKey !== undefined) {
+            validateIdempotencyKey(opts.idempotencyKey);
+        }
+        // Local validation — synchronous, no IO, fail fast before either the
+        // optional pre-flight HTTP call or the WS write.
+        const validateOpts = opts?.maxDepth !== undefined ? { maxDepth: opts.maxDepth } : undefined;
+        validateInlineGraphSpec(payload.graph, validateOpts);
+        // `defineFunctionTool` auto-bind for graph dispatch — walk every
+        // inline-agent node and bind any handlers attached to their
+        // `tools[]` entries. Static refs (`agent_id`) and nested subgraphs
+        // are handled recursively. Mirrors the matching bind in
+        // `startWithAgent`.
+        if (this.bindFunctionToolDefs !== undefined) {
+            collectGraphFunctionTools(payload.graph, this.bindFunctionToolDefs);
+        }
+        // Compute the graph depth once for the OTel span attr.
+        const depth = TaskClient.computeGraphDepth(payload.graph);
+        // Pre-allocate root message id so `taskId` is synchronously available
+        // on the returned iterable.
+        const rootMessageId = asMessageId(uuidv7());
+        const taskId = asTaskId(rootMessageId);
+        const sessionIdDeferred = createDeferred();
+        const admittedTaskIdDeferred = createDeferred();
+        const admissionResultDeferred = createDeferred();
+        const ackDeferreds = {
+            sessionIdDeferred,
+            admittedTaskIdDeferred,
+            admissionResultDeferred,
+        };
+        // Slim-index injection. Synchronous when the manager's catalog has
+        // already been discovered (the common case post-connect()); falls
+        // through to the eager-promise dispatch path when discovery is still
+        // pending.
+        const skillsPinned = opts?.skills;
+        const needsSkillsAwait = this.skills !== undefined && this.skills.currentSnapshot === null;
+        // MCP projection: any inline-agent node carrying `mcpTools` /
+        // `mcpToolOverrides` triggers the eager-async dispatch path so the
+        // pool catalogs settle before projection.
+        const needsMcpProjection = graphHasMcpProjection(payload.graph);
+        let graphForWire = payload.graph;
+        // Sync inject only when no async-path trigger is armed (see
+        // `startWithAgent`'s matching comment — same idempotency
+        // concern; `applyGraphSkillsInjection` walks every inline-agent
+        // node and would otherwise duplicate per-node instruction text).
+        if (this.skills !== undefined && !needsSkillsAwait && !needsMcpProjection) {
+            graphForWire = this.applyGraphSkillsInjection(graphForWire, skillsPinned, opts?.skillsCurrentFile);
+        }
+        // Auto-include the qodo-skills.* tool surface in every inline-agent
+        // node of the graph when skills are configured. Mirror of the
+        // matching block in `startWithAgent` — the async projection path
+        // runs the same merge per-node inside `projectMcpToolsForGraphWire`
+        // for the eager-dispatch branch.
+        if (this.skills !== undefined && !needsMcpProjection) {
+            graphForWire = mergeQodoSkillsToolsIntoGraph(graphForWire);
+        }
+        const wirePayload = {
+            graph: graphForWire,
+            input: payload.input ?? {},
+            ...(payload.skill !== undefined && payload.skill !== null
+                ? { skill: payload.skill }
+                : {}),
+            // Forward the caller-supplied key when present.
+            ...(opts?.idempotencyKey !== undefined
+                ? { idempotency_key: opts.idempotencyKey }
+                : {}),
+        };
+        // Opt-in pre-flight: the iterator we return is async, so the HTTP call
+        // gets wrapped in an async generator that runs `validate` first, then
+        // delegates to the regular subscription. A `valid: false` result raises
+        // `QodoInlineGraphValidationError` so consumers see the same error shape
+        // whether the SDK or QAR rejected the spec.
+        if (opts?.preflight === true || needsSkillsAwait || needsMcpProjection) {
+            // Eager dispatch — see the matching comment on `startWithAgent`:
+            // the preflight + wire write must run before the consumer can race
+            // a `tasks.cancel(stream.taskId)` against the deferred
+            // `task.start`.
+            const subPromise = this.runGraphPreflightAndDispatch(payload, wirePayload, depth, opts ?? {}, rootMessageId, taskId, ackDeferreds);
+            subPromise.catch((err) => {
+                const wrapped = err instanceof Error ? err : new Error(String(err));
+                if (!sessionIdDeferred.settled())
+                    sessionIdDeferred.reject(wrapped);
+                if (!admittedTaskIdDeferred.settled())
+                    admittedTaskIdDeferred.reject(wrapped);
+                if (!admissionResultDeferred.settled())
+                    admissionResultDeferred.reject(wrapped);
+            });
+            // Wrap server errors on the preflighted graph path so consumers get
+            // typed errors regardless of which dispatch path they invoke.
+            return attachTaskId(yieldFromPromisedSub(subPromise, true), taskId, admittedTaskIdDeferred.promise, sessionIdDeferred.promise, admissionResultDeferred.promise);
+        }
+        // Closure used by both single-shot dispatch and the admission retry
+        // wrapper (when `idempotencyKey` is set). Each call builds a fresh
+        // subscription against the supplied rootMessageId.
+        const dispatch = (rmid) => this.subscribeAndSend(() => ({
+            kind: 'task.start',
+            payload: wirePayload,
+            rootMessageId: rmid,
+        }), asTaskId(rmid), opts, undefined, (sessionId, messageId) => this.spanRecorder.startTaskStartSpan({
+            sessionId,
+            messageId,
+            ...(wirePayload.skill !== undefined && wirePayload.skill !== null
+                ? { skillName: wirePayload.skill }
+                : {}),
+            graphEntry: payload.graph.entry,
+            graphDepth: depth,
+            agentKind: TaskClient.computeAgentKind(payload.graph),
+        }).lifecycle, rmid, ackDeferreds);
+        // Route `error` envelopes through the typed-error wrapper so
+        // `graph_spec_rejected` / `agent_reconstruction_failed` / etc.
+        // surface as typed throws instead of yielded `kind: 'error'` events
+        // on the iterator.
+        const firstSub = dispatch(rootMessageId);
+        const iter = opts?.idempotencyKey !== undefined
+            ? TaskClient.wrapWithAdmissionRetry(firstSub, dispatch, sessionIdDeferred, admittedTaskIdDeferred, admissionResultDeferred)
+            : TaskClient.wrapServerErrorsIterator(firstSub);
+        return attachTaskId(iter, taskId, admittedTaskIdDeferred.promise, sessionIdDeferred.promise, admissionResultDeferred.promise);
+    }
+    /**
+     * Eagerly run `client.specs.validate(graph)` and, on success, dispatch
+     * the `task.start` envelope via `subscribeAndSend`. Returns a
+     * `Promise<TaskSubscription>` that resolves once the wire write has
+     * happened. Validation rejection surfaces as
+     * `QodoInlineGraphValidationError` so consumers don't need a second
+     * `instanceof` branch for `SpecValidateResult` failures.
+     */
+    async runGraphPreflightAndDispatch(inboundPayload, wirePayload, depth, opts, rootMessageId, taskId, 
+    /**
+     * Deferred pair for the `task.started` admission ack (sessionId +
+     * admittedTaskId). Forwarded into the eventual `subscribeAndSend` so
+     * the caller's `TaskStartIterable.sessionId` + `.admittedTaskId`
+     * Promises resolve on the ack.
+     */
+    ackDeferreds) {
+        // Await skills discovery + inject into every inline-agent node before
+        // the validator round-trip and the wire write.
+        let finalPayload = wirePayload;
+        let inboundForSpan = inboundPayload;
+        if (this.skills !== undefined) {
+            await this.skills.discover();
+            const injectedGraph = this.applyGraphSkillsInjection(wirePayload.graph, opts.skills, opts.skillsCurrentFile);
+            finalPayload = { ...wirePayload, graph: injectedGraph };
+            inboundForSpan = { ...inboundPayload, graph: injectedGraph };
+        }
+        // MCP projection across every inline-agent node. Runs AFTER
+        // skills inject (skills mutate instructions; projection mutates
+        // `tools[]`) and BEFORE the optional /v1/specs/validate so the
+        // validator sees the post-projection wire surface.
+        const projectedGraph = await this.projectMcpToolsForGraphWire(finalPayload.graph);
+        if (projectedGraph !== finalPayload.graph) {
+            finalPayload = { ...finalPayload, graph: projectedGraph };
+            inboundForSpan = { ...inboundForSpan, graph: projectedGraph };
+        }
+        if (opts.preflight !== true) {
+            // Skills-only async path — no preflight HTTP call. Dispatch now.
+            return this.subscribeAndSend(() => ({
+                kind: 'task.start',
+                payload: finalPayload,
+                rootMessageId,
+            }), taskId, opts, undefined, (sessionId, messageId) => this.spanRecorder.startTaskStartSpan({
+                sessionId,
+                messageId,
+                ...(finalPayload.skill !== undefined && finalPayload.skill !== null
+                    ? { skillName: finalPayload.skill }
+                    : {}),
+                graphEntry: inboundForSpan.graph.entry,
+                graphDepth: depth,
+                agentKind: TaskClient.computeAgentKind(inboundForSpan.graph),
+            }).lifecycle, rootMessageId, ackDeferreds);
+        }
+        const specsResolver = this.resolveSpecs;
+        if (specsResolver === undefined) {
+            throw new Error("tasks.startWithGraph({ preflight: true }) requires the client's SpecsClient — " +
+                "this TaskClient was constructed without a specs resolver");
+        }
+        const specs = specsResolver();
+        const result = await specs.validate(inboundForSpan.graph);
+        if (!result.valid) {
+            throw new QodoInlineGraphValidationError(result.errors.map((e) => ({
+                rule_id: e.rule_id,
+                path: e.path,
+                message: e.message,
+            })));
+        }
+        return this.subscribeAndSend(() => ({
+            kind: 'task.start',
+            payload: finalPayload,
+            rootMessageId,
+        }), taskId, opts, undefined, (sessionId, messageId) => this.spanRecorder.startTaskStartSpan({
+            sessionId,
+            messageId,
+            ...(finalPayload.skill !== undefined && finalPayload.skill !== null
+                ? { skillName: finalPayload.skill }
+                : {}),
+            graphEntry: inboundForSpan.graph.entry,
+            graphDepth: depth,
+            agentKind: TaskClient.computeAgentKind(inboundForSpan.graph),
+        }).lifecycle, rootMessageId, ackDeferreds);
+    }
+    /**
+     * Compute the longest-path depth (edge count) from `entry` for the
+     * `qar.graph.depth` span attr. Returns 0 when the graph has no edges
+     * (single-node graphs).
+     *
+     * Delegates to the validator's shared `longestPathFrom` so the two call
+     * sites can't drift on cycle handling.
+     */
+    static computeGraphDepth(graph) {
+        return longestPathFrom(graph.entry, graph.edges ?? []);
+    }
+    /**
+     * Return the documented `qar.agent.kind` value for a graph: `"inline"`
+     * when any node carries an inline `AgentSpec` (or a nested `GraphSpec`),
+     * `"agent_id"` when every node is a server-static reference. The
+     * `qar.agent.kind` attribute is documented with the closed value set
+     * `"inline" | "agent_id"` — keep this in sync with
+     * `src/observability/attributes.ts`.
+     */
+    static computeAgentKind(graph) {
+        for (const agent of Object.values(graph.agents ?? {})) {
+            const inner = agent.spec;
+            if (typeof inner === 'object' && inner !== null && 'kind' in inner) {
+                return 'inline';
+            }
+        }
+        return 'agent_id';
+    }
+    /**
+     * Send `task.continue` for an existing `task_id` and yield the resulting `TaskEvent`
+     * stream until `task.done`. Same iterator semantics as `start`.
+     *
+     * Payload shape mirrors QAR's `TaskContinuePayload` minus `task_id` — the id is
+     * already supplied as the first argument. `task.continue` carries no
+     * `agent_id`/`skill` because those are bound at `task.start` time.
+     */
+    continue(taskId, payload, opts) {
+        const fullPayload = { task_id: taskId, ...payload };
+        const sub = this.subscribeAndSend((rootMessageId) => ({ kind: 'task.continue', payload: fullPayload, rootMessageId }), taskId, opts, undefined, (sessionId, messageId) => this.spanRecorder.startTaskContinueSpan({ sessionId, messageId, taskId }).lifecycle);
+        // Typed-error wrap on continue — `task_not_found`,
+        // `cross_pod_resume_aborted`, `agent_reconstruction_failed`,
+        // `message_history_load_failed`, the HITL family, etc. all surface
+        // here when the server rejects the continue.
+        return TaskClient.wrapServerErrorsIterator(sub);
+    }
+    /**
+     * Cold-start helper. Unifies `task.start` and `task.continue` behind
+     * a single call so consumers with deterministic `idempotencyKey`
+     * derivation (Slack bots, CLI tools, IDE plugins, web apps without
+     * server affinity) don't have to track in-memory
+     * `(idempotencyKey → taskId)` mappings across process restarts.
+     *
+     * Behavior, gated on QAR's `task.started` admission response:
+     *
+     *   - **No session yet** (`isNew === true`, no `previousTaskId`) —
+     *     fresh dispatch. The returned handle iterates the newly-started
+     *     task's event stream.
+     *   - **Existing session, `state === 'auto-paused'`** (`isNew === false`) —
+     *     QAR returned the existing `task_id`. The helper auto-emits a
+     *     `tasks.continue(taskId, { input })` to deliver the caller's
+     *     input; the returned handle iterates the continue subscription's
+     *     events.
+     *   - **Existing session, `state === 'running'`** (`isNew === false`) —
+     *     QAR returned the existing `task_id`. Same auto-continue path;
+     *     QAR queues the input until the next auto-pause boundary.
+     *   - **Terminal re-dispatch** (`isNew === true` + `previousTaskId` +
+     *     `previousState`) — QAR created a NEW task on the same
+     *     `session_id`, inheriting the full `session_messages` history
+     *     (B-raw). The handle iterates the new task's stream; consumer
+     *     can read `previousTaskId` + `previousState` to surface
+     *     "this is a new task after a prior failure" UX.
+     *
+     * `graphSpec` is required for the fresh-dispatch branch. On
+     * already-dispatched sessions QAR ignores it (the existing task's
+     * spec is the source of truth). The helper throws
+     * {@link RequiredGraphSpecError} synchronously if `graphSpec` is
+     * `undefined` — consumers who don't have a graphSpec on hand should
+     * call {@link continue} or {@link forceResume} directly.
+     *
+     * Paired with QAR-side idempotent admission. Older QAR builds without
+     * idempotent admission either reject `session_already_dispatched` (the
+     * case this helper fixes) or — for fresh sessions — behave identically
+     * (the helper defaults `isNew` to `true` when the field is absent in
+     * the ack).
+     */
+    async continueOrStart(idempotencyKey, graphSpec, options = {}) {
+        if (graphSpec === undefined) {
+            throw new RequiredGraphSpecError(idempotencyKey);
+        }
+        const stream = this.startWithGraph({
+            graph: graphSpec,
+            ...(options.input !== undefined ? { input: options.input } : {}),
+        }, { idempotencyKey });
+        const admission = await stream.admissionResult;
+        let iter;
+        if (admission.isNew) {
+            iter = stream;
+        }
+        else if (options.input !== undefined) {
+            // Idempotent return — pivot to `task.continue` to deliver the
+            // caller's input. QAR routes the input through the existing
+            // task's queue; the continue subscription owns the event stream
+            // from here.
+            //
+            // The cast widens `QodoTaskStartInput` (the typed `task.start.input`
+            // shape) to `TaskContinuePayload['input']` (codegen's
+            // `{ [k: string]: unknown }`). The runtime values are identical —
+            // QAR consumes the same `user_query` / `deps_overrides` / `metadata`
+            // fields on continue. Without the cast, TypeScript would reject
+            // the assignment because the typed shape lacks the open-shape
+            // index signature codegen emits.
+            iter = this.continue(admission.taskId, {
+                input: options.input,
+            });
+        }
+        else {
+            // is_new=false and no input — the caller just wanted a lookup.
+            // The start stream auto-closed in `TaskSubscription.consider` on
+            // `is_new === false`; expose an immediately-empty iterator.
+            iter = stream;
+        }
+        return {
+            [Symbol.asyncIterator]: () => iter[Symbol.asyncIterator](),
+            taskId: admission.taskId,
+            sessionId: admission.sessionId,
+            isNew: admission.isNew,
+            ...(admission.previousTaskId !== undefined
+                ? { previousTaskId: admission.previousTaskId }
+                : {}),
+            ...(admission.previousState !== undefined
+                ? { previousState: admission.previousState }
+                : {}),
+        };
+    }
+    /**
+     * Explicit stuck-session recovery. Sends `task.forceResume` and
+     * awaits the matching `task.force_resumed` ack.
+     *
+     * Use case: a prior consumer process died mid-tool-call or mid-HITL;
+     * the session is stuck `running` with outstanding `tool_call_id` /
+     * `hitl_id` that will never resolve. `forceResume` triggers QAR to:
+     *
+     *   1. Cancel the in-flight tool call (mirrors the system-cancel
+     *      primitives used by `task.cancel` and the A2A bridge).
+     *   2. Synth-resolve pending HITLs.
+     *   3. Append a `{role: 'system', content: 'process restart — outstanding
+     *      tool call cancelled'}` marker to `session_messages` (audit trail).
+     *   4. Transition the session to `'auto-paused'`.
+     *
+     * If the session is already `auto-paused` or terminal, QAR
+     * passthroughs and reports the actual state.
+     *
+     * Returns `{taskId, state}` — the consumer can then call
+     * `tasks.continue(taskId, { input })` with their next turn's input.
+     */
+    forceResume(idempotencyKey) {
+        // Same wire validation as `task.start.idempotencyKey` — surfaces
+        // bad-input synchronously rather than waiting for a server
+        // round-trip.
+        validateIdempotencyKey(idempotencyKey);
+        const connection = this.resolveConnection();
+        const rootMessageId = asMessageId(uuidv7());
+        const deferred = createDeferred();
+        const sub = new TaskSubscription(rootMessageId, undefined, 
+        // onEarlyReturn — no-op. forceResume is a one-shot async call;
+        // there's no consumer-iterator to break, and a stray `task.cancel`
+        // here would target the wrong task (the recovered session's
+        // taskId isn't known yet).
+        () => undefined, (s) => connection.unsubscribe(s), undefined, this.metrics, false, undefined, {
+            resolve: (args) => deferred.resolve(args),
+            reject: (err) => deferred.reject(err),
+        });
+        connection.subscribe(sub);
+        try {
+            connection.sendEnvelope({
+                kind: 'task.forceResume',
+                payload: { idempotency_key: idempotencyKey },
+            }, { messageId: rootMessageId });
+        }
+        catch (err) {
+            sub.fail(err instanceof Error ? err : new Error(String(err)));
+            throw err;
+        }
+        return deferred.promise.then((args) => ({
+            taskId: args.taskId,
+            state: args.state,
+        }));
+    }
+    /**
+     * Send `task.cancel` and await the matching `task.done { status: "canceled" }`.
+     *
+     * The returned promise resolves once the server confirms the cancel via
+     * `task.done`. If the server reports failure (`task.done { status: "failed" }`)
+     * during cancellation, `status: 'failed'` surfaces here so callers can
+     * distinguish — they didn't ask for it, but it's still a terminal state.
+     *
+     * Cross-process recovery: pass `opts.sessionId` to cancel a task whose
+     * `task_id` was hydrated from durable storage (i.e. the SDK never
+     * observed the originating `task.started` in this process). Without the
+     * override the SDK throws {@link QodoColdAddressError} before the wire
+     * write.
+     *
+     * `opts.signal` semantic: **"signal aborts wait-for-task.done"**. If the
+     * signal fires before `task.done` arrives, `cancel` throws
+     * {@link QodoCancelAbortedError} with the task_id and the abort reason.
+     * The wire `task.cancel` was already sent; the underlying task's
+     * terminal ack still routes through its `tasks.start` /
+     * `tasks.continue` subscription. The signal does NOT cause a second
+     * `task.cancel` (that would be redundant — the consumer's intent is
+     * "stop waiting", not "cancel twice"). Pre-aborted signals throw
+     * synchronously before any wire write.
+     */
+    async cancel(taskId, payload, opts) {
+        const fullPayload = { task_id: taskId, ...(payload ?? {}) };
+        // Pre-aborted signals short-circuit BEFORE any wire write so the
+        // consumer's intent ("don't even bother") is honored without a
+        // server round-trip. `tasks.cancel` is `async`, so the throw
+        // surfaces as a rejected Promise; consumers' `try/catch` around
+        // `await tasks.cancel(...)` catches it identically to the
+        // post-send-abort case below. `kind: 'pre_aborted'` lets consumers
+        // branch on "did any wire traffic happen?" without parsing the
+        // error message.
+        const signal = opts?.signal;
+        if (signal?.aborted === true) {
+            throw new QodoCancelAbortedError('pre_aborted', taskId, signal.reason);
+        }
+        // Cancel is short-lived but distinct from the task's own span: it covers
+        // the WS write + the wait for `task.done(canceled)`. We open it with
+        // `undefined` for the subscription so the wrapped `task.done` doesn't
+        // double-close the task span (the underlying task's span is owned by the
+        // `tasks.start` / `tasks.continue` subscription, not this one).
+        //
+        // The span is created by the buildSpan callback (closing-over the local
+        // `cancelSpan` so we can fail it from the catch arm if `subscribeAndSend`
+        // itself throws — without that, a `Connection.sendEnvelope` failure
+        // before the subscription was returned would leak the span).
+        let cancelSpan;
+        let sub;
+        // Don't forward `signal` to subscribeAndSend — its generic
+        // bindAbort would emit a SECOND `task.cancel` on abort, which is
+        // redundant (we're already cancelling) and would race the user's
+        // payload `reason`. Pass only the cold-address `sessionId` override.
+        const subOpts = opts?.sessionId !== undefined ? { sessionId: opts.sessionId } : undefined;
+        try {
+            sub = this.subscribeAndSend((rootMessageId) => ({ kind: 'task.cancel', payload: fullPayload, rootMessageId }), taskId, subOpts, undefined, (sessionId, messageId) => {
+                cancelSpan = this.spanRecorder.startTaskCancelSpan({ sessionId, messageId, taskId });
+                return undefined;
+            });
+        }
+        catch (err) {
+            cancelSpan?.fail(err);
+            throw err;
+        }
+        // Wire the abort signal to close the subscription locally. The
+        // for-await below exits and falls through to the typed throw.
+        // Cleanup removes the listener so a long-lived signal doesn't leak
+        // references through the subscription closure once the cancel
+        // resolves.
+        //
+        // `abortedDuringWait` is read by the for-await exit branch below;
+        // TS's control-flow analysis narrows `signal.aborted` against the
+        // earlier pre-aborted-check at function entry, so we capture the
+        // late-aborted state in a separate flag.
+        let abortListener;
+        let abortedDuringWait = false;
+        let abortReasonDuringWait;
+        if (signal !== undefined) {
+            abortListener = () => {
+                abortedDuringWait = true;
+                abortReasonDuringWait = signal.reason;
+                sub.close();
+            };
+            signal.addEventListener('abort', abortListener, { once: true });
+        }
+        try {
+            for await (const event of sub) {
+                if (event.kind === 'task.done' && event.payload.task_id === taskId) {
+                    const done = event;
+                    // `done.payload.task_id` arrives from codegen as plain `string` (the
+                    // overlay brands the public `TaskDonePayload` type but the generated
+                    // envelope's `payload` references the unbranded codegen variant).
+                    // We've already matched against `taskId` by equality above, so it is
+                    // the same UUID — re-using the input branded value keeps the cast
+                    // off the boundary.
+                    //
+                    // Surface the server's actual terminal status verbatim — including
+                    // `'completed'`, which means the task finished before our cancel was
+                    // processed (the race the docs promise we'll surface).
+                    if (done.payload.status === 'failed') {
+                        cancelSpan?.fail(new Error(done.payload.error ?? 'cancel returned failed'));
+                    }
+                    else {
+                        cancelSpan?.succeed();
+                    }
+                    return {
+                        task_id: taskId,
+                        status: done.payload.status,
+                        ...(done.payload.error !== undefined && done.payload.error !== null
+                            ? { error: done.payload.error }
+                            : {}),
+                    };
+                }
+                // A server `error` envelope arriving on the cancel iterator
+                // with a documented typed code (e.g. `cancel_routing_failed`,
+                // `cancel_failed`, `task_not_found`, `task_not_waiting`) is
+                // surfaced as a typed throw so consumers can branch on
+                // `instanceof QodoCancelRoutingFailedError` etc. instead of
+                // racing the absent `task.done`. Unrecognized codes continue
+                // to fall through into the "connection closed before
+                // task.done" fallback so we don't change behavior for codes
+                // the SDK hasn't catalogued yet.
+                if (event.kind === 'error') {
+                    const code = event.payload.code;
+                    if (typeof code === 'string' && isTypedErrorCode(code)) {
+                        const err = errorFromServerErrorEnvelope(event);
+                        cancelSpan?.fail(err);
+                        throw err;
+                    }
+                }
+            }
+            // for-await drained without a `task.done` — either the abort
+            // fired (consumer chose not to wait) or the connection closed.
+            if (abortedDuringWait) {
+                const err = new QodoCancelAbortedError('aborted_after_send', taskId, abortReasonDuringWait);
+                cancelSpan?.fail(err);
+                throw err;
+            }
+            cancelSpan?.fail(new Error('connection closed before task.done arrived'));
+            return {
+                task_id: taskId,
+                status: 'failed',
+                error: 'connection closed before task.done arrived',
+            };
+        }
+        catch (err) {
+            cancelSpan?.fail(err);
+            throw err;
+        }
+        finally {
+            if (abortListener !== undefined && signal !== undefined) {
+                signal.removeEventListener('abort', abortListener);
+            }
+        }
+    }
+    /**
+     * Send `task.resubscribe { task_id, since_message_id? }` and yield replayed
+     * `TaskEvent`s from the server-held ring buffer (per-session cap of 1000
+     * envelopes). No client outbox — durability is server-side.
+     *
+     * Use this when you have a `task_id` from a prior connection (e.g. across a
+     * process restart) and want to catch up from a known anchor. For automatic
+     * reconnect-on-drop within a single `connect()` lifetime, the SDK does this
+     * for you transparently — see `qar.client.reconnect*` events on the
+     * canonical iterator.
+     *
+     * If the server's ring buffer has rotated past `sinceMessageId` (very long
+     * disconnects, or a missing/wrong anchor), the server emits an `error`
+     * envelope with a `replay_anchor_missing`-style code; that event surfaces
+     * as the iterator's final value and ends the stream. The consumer can
+     * decide to start the task fresh or surrender.
+     */
+    resubscribe(taskId, opts) {
+        const payload = {
+            task_id: taskId,
+            since_message_id: opts?.sinceMessageId ?? null,
+        };
+        return this.subscribeAndSend((rootMessageId) => ({ kind: 'task.resubscribe', payload, rootMessageId }), taskId, opts, 
+        // Resubscribe is observation, not initiation: breaking the iterator
+        // must NOT cancel the underlying task. The user may still want it
+        // running; they can call `tasks.cancel` separately if not.
+        //
+        // The outbound `task.resubscribe.message_id` is the replay anchor —
+        // every descendant counts as a replay envelope so the SDK can stamp
+        // `replay_envelopes_received_total`.
+        { suppressEarlyReturnCancel: true, rootIsReplayAnchor: true }, (sessionId, messageId) => this.spanRecorder.startTaskResubscribeSpan({
+            sessionId,
+            messageId,
+            taskId,
+            ...(opts?.sinceMessageId !== undefined ? { sinceMessageId: opts.sinceMessageId } : {}),
+        }).lifecycle);
+    }
+    /**
+     * Pre-allocate a `MessageId`, register a `TaskSubscription` against it, then
+     * send the outbound envelope using the same id. Subscribing before sending
+     * eliminates the race where the server's first reply could land before the
+     * subscription is in place.
+     *
+     * Pre-aborted signals short-circuit BEFORE the send so we never start
+     * server-side work the consumer has already given up on.
+     *
+     * `preallocatedRootMessageId` lets the caller mint the root id at the
+     * public-API boundary so it can derive `task_id` synchronously for
+     * `task.start` envelopes (the wire protocol codifies
+     * `task_id == task.start.message_id`). When omitted, we allocate fresh —
+     * the `task.continue` / `task.cancel` / `task.resubscribe` call sites
+     * already carry the task_id as an explicit arg.
+     */
+    subscribeAndSend(buildOutbound, knownTaskId, opts, behavior, 
+    /**
+     * Optional span builder. Returns a `SpanLifecycle` to attach to the
+     * subscription (closed on terminal/fail/early-return), or `undefined`
+     * when the caller manages span lifetime itself (e.g. `tasks.cancel`).
+     * The first arg is the per-Task `session_id` if known (`undefined`
+     * on the `task.start` path before admission completes); the span
+     * recorder treats it as an optional attribute.
+     */
+    buildSpan, preallocatedRootMessageId, 
+    /**
+     * Optional `task.started` admission-ack deferreds wired in by the
+     * `task.start` family (`tasks.start` / `tasks.startWithAgent` /
+     * `tasks.startWithGraph`). The constructed `TaskSubscription`
+     * resolves all three deferreds atomically when `task.started` arrives:
+     * `sessionId` from the envelope's inherited `session_id` field,
+     * `admittedTaskId` from the payload's `task_id` field, and
+     * `admissionResultDeferred` with the full `TaskAdmissionResult`
+     * (idempotent-admission fields `isNew` / `state` / `previousTaskId` /
+     * `previousState`). `undefined` for non-start paths (`task.continue`
+     * / `task.cancel` / `task.resubscribe`) which already know both ids
+     * from a prior admission.
+     */
+    taskStartedDeferred) {
+        const connection = this.resolveConnection();
+        const rootMessageId = preallocatedRootMessageId ?? asMessageId(uuidv7());
+        let onAbortCleanup;
+        const suppressEarlyReturnCancel = behavior?.suppressEarlyReturnCancel === true;
+        // Build the outbound shape NOW (rather than at send time below) so
+        // we can gate `opts.sessionId` span attribution on the kind. On
+        // `task.start` the consumer's `sessionId` is documented as ignored
+        // (admission CREATES the session) — and using it for span
+        // attribution would pollute the span with a caller-supplied value
+        // the wire never sees. Only the ongoing kinds (`task.continue` /
+        // `task.cancel` / `task.resubscribe`) legitimately consume the
+        // override.
+        //
+        // `buildOutbound` is a pure constructor over `rootMessageId` (no
+        // side effects), so calling it twice is safe — but we cache the
+        // result and reuse below to avoid the redundant work.
+        const outbound = buildOutbound(rootMessageId);
+        const isStart = outbound.kind === 'task.start';
+        // No connection-level session_id. For `task.continue` /
+        // `task.cancel` / `task.resubscribe` we already know `knownTaskId`
+        // here and can look up the per-Task session captured from the prior
+        // `task.started`. For `task.start` (knownTaskId === undefined at the
+        // public entry point — derived from the outbound message_id but no
+        // ack yet), the span opens without a session attribute; the
+        // subscription's later `task.started` handler stamps the canonical
+        // id on the lifecycle once admission completes.
+        //
+        // When the consumer passed `opts.sessionId` (the cold-address path),
+        // use that for span attribution on ongoing kinds — the in-memory map
+        // will be empty on cross-process recovery, so the lookup would
+        // return `undefined` and the span would miss its `qar.session_id`
+        // attribute despite the consumer knowing the right value. On
+        // `task.start` we ignore `opts.sessionId` per the contract
+        // documented in `TaskOptions.sessionId`.
+        const knownSessionId = isStart
+            ? undefined
+            : (opts?.sessionId ??
+                (knownTaskId !== undefined ? connection.getSessionForTask(knownTaskId) : undefined));
+        const span = buildSpan?.(knownSessionId, rootMessageId);
+        const sub = new TaskSubscription(rootMessageId, knownTaskId, (taskIdAtCancel) => {
+            // `tasks.resubscribe` is observation-only — breaking the iterator
+            // there must NOT cancel the underlying task (the consumer may still
+            // want it running; they'll call `tasks.cancel` separately if not).
+            if (suppressEarlyReturnCancel)
+                return;
+            const cancelTaskId = taskIdAtCancel ?? knownTaskId;
+            if (cancelTaskId !== undefined && connection.isOpen) {
+                try {
+                    connection.sendEnvelope({
+                        kind: 'task.cancel',
+                        payload: { task_id: cancelTaskId, reason: 'iterator early-termination' },
+                    });
+                }
+                catch {
+                    // Connection may have closed mid-flight; cancel is best-effort.
+                }
+            }
+        }, (s) => {
+            connection.unsubscribe(s);
+            // Retract any throttled frame still sitting in the connection's
+            // backpressure queue. Without this, a queued `task.continue`
+            // would still hit the wire on the next `flow.resume` even though
+            // the consumer has already canceled / aborted / broken the
+            // iterator — producing `cancel → resume → continue` reordering
+            // on the server. No-op if the frame already flushed or never
+            // entered the throttle path.
+            connection.dropQueued(rootMessageId);
+            // Drop the AbortSignal listener so a long-lived signal that's
+            // reused across many tasks doesn't accumulate dead closures
+            // pinning every completed subscription + connection in memory.
+            onAbortCleanup?.();
+            onAbortCleanup = undefined;
+        }, span, this.metrics, behavior?.rootIsReplayAnchor === true, taskStartedDeferred !== undefined
+            ? {
+                resolve: ({ sessionId, taskId: ackTaskId, isNew, state, previousTaskId, previousState, }) => {
+                    taskStartedDeferred.sessionIdDeferred.resolve(sessionId);
+                    taskStartedDeferred.admittedTaskIdDeferred.resolve(ackTaskId);
+                    taskStartedDeferred.admissionResultDeferred.resolve({
+                        taskId: ackTaskId,
+                        sessionId,
+                        isNew,
+                        ...(state !== undefined ? { state } : {}),
+                        ...(previousTaskId !== undefined ? { previousTaskId } : {}),
+                        ...(previousState !== undefined ? { previousState } : {}),
+                    });
+                },
+                reject: (err) => {
+                    taskStartedDeferred.sessionIdDeferred.reject(err);
+                    taskStartedDeferred.admittedTaskIdDeferred.reject(err);
+                    taskStartedDeferred.admissionResultDeferred.reject(err);
+                },
+            }
+            : undefined);
+        if (opts?.signal?.aborted === true) {
+            // Pre-aborted: never send the outbound envelope. For `task.continue`
+            // / `task.resubscribe` / `task.cancel` (we know the id) and the
+            // user wants to give up before we start, emit `task.cancel` so the
+            // running task on the server tears down promptly UNLESS this is a
+            // resubscribe-style observation that mustn't cancel the live task.
+            // For `task.start` (no id yet) there's nothing for the server to
+            // cancel — just close the iterator.
+            if (knownTaskId !== undefined &&
+                connection.isOpen &&
+                !suppressEarlyReturnCancel) {
+                try {
+                    // Forward the cold-address `sessionId` (if supplied) so the
+                    // pre-abort cancel resolves the same session the never-sent
+                    // ongoing envelope would have used. Without this, cold
+                    // continue/resubscribe with a pre-aborted signal would
+                    // silently drop the cancel via the catch below.
+                    connection.sendEnvelope({
+                        kind: 'task.cancel',
+                        payload: { task_id: knownTaskId, reason: 'pre-aborted signal' },
+                    }, opts?.sessionId !== undefined ? { sessionId: opts.sessionId } : undefined);
+                }
+                catch {
+                    // best-effort — common case is cold-`tasks.start` pre-abort,
+                    // where the task was never admitted server-side and there's
+                    // no session to address. `QodoColdAddressError` lands here
+                    // and we silently drop (the server has nothing to cancel).
+                }
+            }
+            sub.close();
+            return sub;
+        }
+        connection.subscribe(sub);
+        // `outbound` was built earlier to gate span sessionId on the kind;
+        // reuse here.
+        try {
+            // Run the outbound `sendEnvelope` inside the SDK span's context.
+            // This is what makes `Connection`'s `TraceContextProvider.current()`
+            // see our SDK span as the active span at envelope-encode time, so
+            // the outbound `traceparent` references the SDK span's id —
+            // letting QAR parent its server-side `qar.protocol.<kind>` span
+            // under ours. Without `withContext`, the active span at send time
+            // would still be the consumer's span (or none), and the SDK span
+            // would be a leaf — breaking the cross-process trace tree.
+            //
+            // The `span` may be undefined when the call site doesn't open one
+            // (e.g. `tasks.cancel` opens its own span out-of-band). Fall
+            // through to the unwrapped path in that case.
+            //
+            // Forward the caller-supplied cold-address `sessionId` (if any)
+            // on the three ongoing kinds. Omitted on `task.start` — that path
+            // doesn't carry a wire `session_id` (admission CREATES the
+            // session). `sendEnvelope`'s `resolveOutboundSessionId` honours
+            // the override first, then falls back to the in-memory map, then
+            // throws `QodoColdAddressError` — so consumers carrying their own
+            // `{ taskId, sessionId }` pair survive the cold-address path
+            // without a wire round-trip.
+            const sessionOverride = opts?.sessionId;
+            const send = () => {
+                switch (outbound.kind) {
+                    case 'task.start':
+                        connection.sendEnvelope({ kind: 'task.start', payload: outbound.payload }, { messageId: rootMessageId });
+                        break;
+                    case 'task.continue':
+                        connection.sendEnvelope({ kind: 'task.continue', payload: outbound.payload }, sessionOverride !== undefined
+                            ? { messageId: rootMessageId, sessionId: sessionOverride }
+                            : { messageId: rootMessageId });
+                        break;
+                    case 'task.cancel':
+                        connection.sendEnvelope({ kind: 'task.cancel', payload: outbound.payload }, sessionOverride !== undefined
+                            ? { messageId: rootMessageId, sessionId: sessionOverride }
+                            : { messageId: rootMessageId });
+                        break;
+                    case 'task.resubscribe':
+                        connection.sendEnvelope({ kind: 'task.resubscribe', payload: outbound.payload }, sessionOverride !== undefined
+                            ? { messageId: rootMessageId, sessionId: sessionOverride }
+                            : { messageId: rootMessageId });
+                        break;
+                }
+            };
+            if (span !== undefined) {
+                span.withContext(send);
+            }
+            else {
+                send();
+            }
+        }
+        catch (err) {
+            sub.fail(err instanceof Error ? err : new Error(String(err)));
+            throw err;
+        }
+        if (opts?.signal !== undefined) {
+            onAbortCleanup = this.bindAbort(connection, sub, opts.signal, opts.sessionId);
+        }
+        return sub;
+    }
+    /**
+     * Retry wrapper for `admission_in_progress` errors.
+     *
+     * When a deterministic-key admission collides with an in-flight admission
+     * on the same `(tenant_id, idempotency_key)`, QAR emits
+     * `error { code: 'admission_in_progress', retry_after_ms? }` instead of
+     * starting work. The SDK MUST retry with the same payload (server
+     * derives the same `session_id`) after the hinted delay — or, if absent,
+     * after exponential backoff with jitter — capped at
+     * `PENDING_ADMISSION_TIMEOUT` (5 min). The wrapper only fires on the
+     * deterministic-key path; the DX-default omitted-key path never sees
+     * `admission_in_progress` (each call mints a fresh `uuidv7` server-side
+     * — no collisions possible).
+     *
+     * Returns an `AsyncIterable<TaskEvent>` that wraps the underlying
+     * subscription. The wrapper:
+     *
+     *   1. Calls `buildAttempt(rootMessageId)` to register a fresh
+     *      `TaskSubscription` and emit the wire `task.start`.
+     *   2. Reads the first event.
+     *   3. If `error { code: 'admission_in_progress' }`: capture the
+     *      scoped `session_id` and `retry_after_ms` hint, sleep, retry
+     *      with a fresh `rootMessageId`. Lifecycle bookkeeping
+     *      (subscription close, span end) flows through the underlying
+     *      subscription's terminal handling on the error envelope.
+     *   4. If `admission_stalled` typed throw arrives via the
+     *      wrap-server-errors layer: propagate (terminal, non-retryable).
+     *   5. Otherwise: yield the first event and pass through every
+     *      subsequent event.
+     *
+     * After {@link PENDING_ADMISSION_TIMEOUT_MS} elapsed wall-clock time
+     * the wrapper throws {@link QodoAdmissionTimeoutError} carrying the
+     * scoped `session_id` so the caller can `task.resubscribe` if a
+     * recovery path exists.
+     */
+    static wrapWithAdmissionRetry(
+    /**
+     * Pre-dispatched first attempt — already subscribed and the wire
+     * `task.start` is in flight before the wrapper is constructed.
+     * Eager dispatch preserves the SDK contract that
+     * `client.tasks.cancel(stream.taskId)` can be called immediately
+     * after `client.tasks.start(...)` returns without iterating the
+     * stream first.
+     */
+    firstSub, buildAttempt, sessionIdDeferred, admittedTaskIdDeferred, admissionResultDeferred) {
+        // The retry loop runs in a **background driver** independent of
+        // consumer iteration. Advancing retries inside `next()` would mean a
+        // caller who awaited `stream.sessionId` BEFORE iterating could hang
+        // forever (the retry would never sleep, never re-dispatch, never
+        // observe `task.started`). Instead the driver:
+        //
+        //   1. Pulls from the current attempt's iterator eagerly.
+        //   2. Detects `admission_in_progress`, sleeps, re-dispatches.
+        //   3. Pushes every other event to a consumer-facing `AsyncQueue`.
+        //   4. Settles `sessionIdDeferred` + `admittedTaskIdDeferred` from
+        //      the inbound `task.started` (resolved by the underlying
+        //      `TaskSubscription`'s resolver path) OR rejects both on
+        //      timeout / typed terminal so the caller's
+        //      `await stream.sessionId` always settles.
+        //
+        // The returned `AsyncIterable` is a thin adapter over the queue —
+        // breaking it early closes the queue, which the driver respects
+        // on its next loop iteration.
+        const consumerQueue = new AsyncQueue();
+        let driverAborted = false;
+        // Hoist the current attempt's subscription reference to the wrapper
+        // scope so the consumer-facing iterator's `return()` / `throw()` can
+        // close the underlying subscription on abort. Without this, the
+        // driver may be blocked inside `await iter.next()` on the AsyncQueue
+        // and never observe `driverAborted` if no envelopes arrive — the
+        // subscription leaks and best-effort cancel never fires.
+        let currentSub = firstSub;
+        const abortFromConsumer = () => {
+            driverAborted = true;
+            // Reject the admission deferreds: without this, `await
+            // stream.sessionId` after an early-break by the consumer would
+            // hang forever. Use a typed `QodoStreamAbortedError` so callers
+            // can branch on voluntary-abort vs. genuine admission failure.
+            const abortErr = new QodoStreamAbortedError();
+            if (!sessionIdDeferred.settled())
+                sessionIdDeferred.reject(abortErr);
+            if (!admittedTaskIdDeferred.settled())
+                admittedTaskIdDeferred.reject(abortErr);
+            // Close the current attempt's subscription. `return()` (vs
+            // `close()`) is the right call: it triggers
+            // `onEarlyReturn` → best-effort `task.cancel` to QAR if we know
+            // the task_id, then closes the queue and unregisters. Closing
+            // the queue is what unblocks the driver's `await iter.next()`
+            // → the driver sees `r.done`, checks `driverAborted`, exits.
+            try {
+                void currentSub.return();
+            }
+            catch {
+                /* best-effort — subscription may already be closed via
+                 * terminal envelope or transport drop */
+            }
+            consumerQueue.close();
+        };
+        const runDriver = async () => {
+            const startedAt = Date.now();
+            let attempt = 0;
+            let lastSessionId;
+            while (true) {
+                if (driverAborted) {
+                    consumerQueue.close();
+                    return;
+                }
+                let admissionInProgress;
+                try {
+                    const wrapped = TaskClient.wrapServerErrorsIterator(currentSub);
+                    const iter = wrapped[Symbol.asyncIterator]();
+                    while (true) {
+                        const r = await iter.next();
+                        if (driverAborted) {
+                            try {
+                                await iter.return?.(undefined);
+                            }
+                            catch {
+                                /* best-effort */
+                            }
+                            consumerQueue.close();
+                            return;
+                        }
+                        if (r.done)
+                            break;
+                        const ev = r.value;
+                        if (ev.kind === 'error') {
+                            const code = ev.payload.code;
+                            if (typeof code === 'string' && code === 'admission_in_progress') {
+                                admissionInProgress = ev;
+                                // Drain the current attempt's iter — its queue was
+                                // closed by the error envelope already; return() is a
+                                // no-op safety net (idempotent per AsyncQueue contract).
+                                try {
+                                    await iter.return?.(undefined);
+                                }
+                                catch {
+                                    /* best-effort */
+                                }
+                                break;
+                            }
+                        }
+                        // Forward non-admission events to the consumer queue.
+                        consumerQueue.push(ev);
+                    }
+                }
+                catch (err) {
+                    // The wrap layer threw a typed `QodoServerError` (e.g.
+                    // `QodoAdmissionStalledError`) — propagate to the consumer
+                    // queue and settle deferreds. Same path covers transport
+                    // failures that surfaced as iterator throws.
+                    const wrapped = err instanceof Error ? err : new Error(String(err));
+                    if (!sessionIdDeferred.settled())
+                        sessionIdDeferred.reject(wrapped);
+                    if (!admittedTaskIdDeferred.settled())
+                        admittedTaskIdDeferred.reject(wrapped);
+                    if (!admissionResultDeferred.settled())
+                        admissionResultDeferred.reject(wrapped);
+                    consumerQueue.fail(wrapped);
+                    return;
+                }
+                if (admissionInProgress === undefined) {
+                    // Clean terminal (task.done) or non-admission error fell
+                    // through. Close the consumer queue.
+                    consumerQueue.close();
+                    return;
+                }
+                // Retry path
+                const sid = admissionInProgress.session_id;
+                if (typeof sid === 'string' && !isZeroUuid(sid))
+                    lastSessionId = sid;
+                const hint = parseRetryAfterMsHint(admissionInProgress);
+                const wait = hint ?? computeAdmissionRetryBackoffMs(attempt);
+                const elapsed = Date.now() - startedAt;
+                if (elapsed + wait > PENDING_ADMISSION_TIMEOUT_MS) {
+                    const timeoutErr = new QodoAdmissionTimeoutError(elapsed, attempt + 1, lastSessionId);
+                    if (!sessionIdDeferred.settled())
+                        sessionIdDeferred.reject(timeoutErr);
+                    if (!admittedTaskIdDeferred.settled())
+                        admittedTaskIdDeferred.reject(timeoutErr);
+                    if (!admissionResultDeferred.settled())
+                        admissionResultDeferred.reject(timeoutErr);
+                    consumerQueue.fail(timeoutErr);
+                    return;
+                }
+                await sleepMs(wait);
+                if (driverAborted) {
+                    consumerQueue.close();
+                    return;
+                }
+                attempt += 1;
+                currentSub = buildAttempt(asMessageId(uuidv7()));
+            }
+        };
+        // Kick off the driver eagerly. Unhandled-rejection guard so a
+        // driver-internal bug doesn't crash Node before the consumer
+        // sees the queue's failure.
+        void runDriver().catch((err) => {
+            const wrapped = err instanceof Error ? err : new Error(String(err));
+            if (!sessionIdDeferred.settled())
+                sessionIdDeferred.reject(wrapped);
+            if (!admittedTaskIdDeferred.settled())
+                admittedTaskIdDeferred.reject(wrapped);
+            if (!admissionResultDeferred.settled())
+                admissionResultDeferred.reject(wrapped);
+            if (!consumerQueue.isClosed)
+                consumerQueue.fail(wrapped);
+        });
+        return {
+            [Symbol.asyncIterator]() {
+                return {
+                    next() {
+                        return consumerQueue.next();
+                    },
+                    async return(value) {
+                        abortFromConsumer();
+                        return { value: value, done: true };
+                    },
+                    async throw(err) {
+                        abortFromConsumer();
+                        throw err instanceof Error ? err : new Error(String(err));
+                    },
+                };
+            },
+        };
+    }
+    /**
+     * Wire an `AbortSignal` to the subscription. On abort, send `task.cancel`
+     * (if we know the task id) and end the iterator. Returns a cleanup
+     * function the subscription's `onClose` invokes so the listener doesn't
+     * outlive the task (matters when a single AbortController is reused
+     * across many short-lived tasks).
+     */
+    bindAbort(connection, sub, signal, sessionOverride) {
+        const onAbort = () => {
+            const taskId = sub.currentTaskId;
+            if (taskId !== undefined && connection.isOpen) {
+                try {
+                    // Forward the cold-address `sessionId` override. A cold
+                    // `task.continue` queued under `flow.pause` hasn't committed
+                    // its override to `taskSessions` yet when the abort fires;
+                    // the cancel needs the explicit value to resolve.
+                    connection.sendEnvelope({
+                        kind: 'task.cancel',
+                        payload: { task_id: taskId, reason: 'abort signal' },
+                    }, sessionOverride !== undefined ? { sessionId: sessionOverride } : undefined);
+                }
+                catch {
+                    // best-effort
+                }
+            }
+            // `sub.close()` (NOT `sub.return()`) — `return()` invokes
+            // `onEarlyReturn` which would emit a second `task.cancel`. The
+            // abort path already sent the cancel above; closing the queue
+            // ends the iterator without re-firing the early-return handler.
+            sub.close();
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        return () => signal.removeEventListener('abort', onAbort);
+    }
+    // -------------------------------------------------------------------
+    // Skills foundation glue
+    // -------------------------------------------------------------------
+    /**
+     * Inject the rendered active-skills block + slim index into an
+     * `InlineAgentSpec` synchronously. Validates caller-pinned skills
+     * against the cached snapshot first; unresolved names throw
+     * `SkillNotFoundError`. Returns the original spec when the catalog
+     * is empty or when no `SkillsManager` is configured.
+     *
+     * When the caller pinned any skills, the SDK resolves the `requires:`
+     * chain (with the depth/breadth/token caps applied), renders the
+     * bodies into an `<active_skills>` block, and prepends that block to
+     * the spec's `instructions` *before* the slim-index block. Trust
+     * violations, cap breaches, cycles, or unresolved deps all throw
+     * `QodoSkillError` so no partial body lands on the wire.
+     */
+    applyAgentSkillsInjection(spec, pinned, currentFile) {
+        if (this.skills === undefined)
+            return spec;
+        const effectivePinned = this.resolveEffectivePinned(pinned);
+        if (effectivePinned !== undefined && effectivePinned.length > 0) {
+            this.validatePinnedSync(effectivePinned);
+        }
+        const activation = this.composeActiveSkills(effectivePinned);
+        const renderOpts = this.buildRenderOptions(effectivePinned, currentFile);
+        const injection = injectIntoAgentSpec(spec, this.skills, renderOpts);
+        this.dispatchSkillsEvents(injection.events);
+        this.throwIfPinsOmitted(injection.omittedPinned, renderOpts);
+        this.dispatchSkillsEvents(activation.events);
+        const finalSpec = activation.text.length > 0
+            ? { ...injection.spec, instructions: prependInstructions(injection.spec.instructions, activation.text) }
+            : injection.spec;
+        return finalSpec;
+    }
+    /**
+     * Inject the active-skills block + slim index into every inline-agent
+     * node of an `InlineGraphSpec`. Mirrors `applyAgentSkillsInjection`
+     * for the graph case.
+     */
+    applyGraphSkillsInjection(graph, pinned, currentFile) {
+        if (this.skills === undefined)
+            return graph;
+        const effectivePinned = this.resolveEffectivePinned(pinned);
+        if (effectivePinned !== undefined && effectivePinned.length > 0) {
+            this.validatePinnedSync(effectivePinned);
+        }
+        const activation = this.composeActiveSkills(effectivePinned);
+        const renderOpts = this.buildRenderOptions(effectivePinned, currentFile);
+        const injection = injectIntoGraphSpec(graph, this.skills, renderOpts);
+        this.dispatchSkillsEvents(injection.events);
+        this.throwIfPinsOmitted(injection.omittedPinned, renderOpts);
+        this.dispatchSkillsEvents(activation.events);
+        if (activation.text.length === 0)
+            return injection.spec;
+        return {
+            ...injection.spec,
+            agents: prependActiveSkillsToGraphAgents(injection.spec.agents, activation.text),
+        };
+    }
+    /**
+     * MCP projection at the wire boundary. When the consumer set
+     * `mcpTools` (or `mcpToolOverrides`), this:
+     *
+     *   1. Awaits the MCP pool's catalog-settle window so cold-start
+     *      `tools/list` round-trips can complete before projection.
+     *   2. Runs `projectMcpTools` against the live pool snapshot.
+     *   3. Partitions the diagnostics:
+     *      - `unknownMcps` and `unknownMcpTools` always reject (consumer
+     *        code drift; pre-deploy-detectable).
+     *      - `unreachableMcps` is policed per-MCP via the registry's
+     *        `unavailability` setting. `'fail'` raises
+     *        `QodoMcpUnavailableError`; `'warn'` omits the MCP's tools
+     *        and emits a console warning.
+     *   4. Returns a fresh `InlineAgentSpec` with `tools[]` replaced by
+     *      the projected surface and `mcpTools` / `mcpToolOverrides`
+     *      stripped (SDK-only fields — QAR rejects them at the wire
+     *      validator via `D10-R5` if they slipped through).
+     *
+     * When the spec carries neither `mcpTools` nor `mcpToolOverrides`, the
+     * helper returns the input verbatim — projection is opt-in, the v1
+     * `tools: FunctionToolDef[]` ergonomic continues to work.
+     */
+    async projectMcpToolsForWire(spec) {
+        const hasSelector = spec.mcpTools !== undefined;
+        const hasOverrides = spec.mcpToolOverrides !== undefined;
+        // Auto-include the `qodo-skills.*` tool surface whenever the
+        // consumer opted into skills. The slim-index preamble (rendered into
+        // `instructions` by the skills injector) tells the LLM "Use the
+        // qodo-skills.get_skill tool to ..."; that instruction is only
+        // actionable when the three tools actually land on the wire's
+        // `function_tools`. Projection is the SDK's single surface that
+        // decides what tools the model can see, so it owns the include.
+        //
+        // No skills + no selector + no overrides → projection is a no-op;
+        // return verbatim to preserve the v1 ergonomic where
+        // `tools: FunctionToolDef[]` reaches the wire untouched.
+        const skillsConfigured = this.skills !== undefined;
+        if (!hasSelector && !hasOverrides && !skillsConfigured)
+            return spec;
+        // Build prefix policy + unavailability policy from the registry
+        // snapshot. The registry's `getMcpPolicy` returns defaults
+        // (`prefixToolNames: true`, `unavailability: 'fail'`) for any
+        // unregistered name, so passing the full registered set here is
+        // sufficient; the projection function ignores entries not in the
+        // pool snapshot.
+        const prefixPolicy = new Map();
+        const unavailabilityByName = new Map();
+        for (const { name } of this.registry.listMcps()) {
+            const policy = this.registry.getMcpPolicy(name);
+            prefixPolicy.set(name, policy.prefixToolNames);
+            unavailabilityByName.set(name, policy.unavailability);
+        }
+        // Acquire the live pool — fall back to a fresh empty pool when no
+        // remote/stdio MCPs are registered so the projection function
+        // doesn't need a null-pool branch. An empty pool yields
+        // empty registered-names + empty catalog snapshot; the selector's
+        // unknown-MCP diagnostics then flag every referenced name.
+        const livePool = this.registry._getMcpPool();
+        const pool = livePool ?? new McpClientPool();
+        if (livePool !== null) {
+            // Bounded wait — `waitForCatalogsToSettle` defaults to 250ms.
+            // Catalogs already populated resolve immediately. Cold-start
+            // failures (Promise rejection) are swallowed by the settle
+            // helper; they surface here as `unreachableMcps`.
+            await livePool.waitForCatalogsToSettle();
+        }
+        const projectionInput = {
+            mcpTools: spec.mcpTools,
+            consumerTools: spec.tools ?? undefined,
+            mcpToolOverrides: spec
+                .mcpToolOverrides,
+        };
+        // SDK-transport ('sdk') MCPs aren't in the pool — their dispatch
+        // goes through the in-process handler bridge. Pass their names as
+        // "extra known" so referencing them in `mcpTools` doesn't trip
+        // `QodoUnknownMcpError`. Projection still won't auto-project tools
+        // for them (no tools/list contract); consumer ships those via
+        // `tools[]`.
+        const sdkTransportNames = new Set(this.registry._listSdkTransportMcpNames());
+        const result = projectMcpTools(projectionInput, pool, prefixPolicy, sdkTransportNames);
+        // Partition diagnostics. Unknown MCPs / tools are unconditional
+        // throws — they indicate consumer code drift, not transient flake.
+        if (result.diagnostics.unknownMcps.length > 0) {
+            throw new QodoUnknownMcpError(result.diagnostics.unknownMcps);
+        }
+        if (result.diagnostics.unknownMcpTools.length > 0) {
+            throw new QodoUnknownMcpToolError(result.diagnostics.unknownMcpTools);
+        }
+        // Per-MCP unavailability policy. `'fail'` names collect into the
+        // typed error payload; `'warn'` names emit a structured console
+        // warning so observability consumers see the degradation without
+        // the task failing.
+        const failNames = [];
+        const warnNames = [];
+        for (const name of result.diagnostics.unreachableMcps) {
+            const policy = unavailabilityByName.get(name) ?? 'fail';
+            if (policy === 'fail')
+                failNames.push(name);
+            else
+                warnNames.push(name);
+        }
+        if (warnNames.length > 0) {
+            // Structured-payload warning. Stable JSON shape so
+            // `gtrace`-style log aggregators parse cleanly; one
+            // line per unreachable MCP so each event is independently
+            // grep-able. `event` is the stable discriminator;
+            // `reason` distinguishes cold-start (only case in v1) from a
+            // future post-cache-disconnect surface.
+            //
+            // The typed-event-handler surface
+            // (`QodoClientOptions.onMcpUnavailable`) is a follow-up — so
+            // consumers wanting first-class observability can grep this
+            // payload until that lands.
+            const ts = new Date().toISOString();
+            for (const name of warnNames) {
+                // eslint-disable-next-line no-console
+                console.warn(JSON.stringify({
+                    event: 'qodo.sdk.mcp.unavailable',
+                    mcpName: name,
+                    ts,
+                    reason: 'cold_start_unreachable',
+                    hint: "Check MCP connectivity; tools omitted from this task's projection.",
+                }));
+            }
+        }
+        if (failNames.length > 0) {
+            throw new QodoMcpUnavailableError(failNames);
+        }
+        // Auto-include the qodo-skills.* tool surface when skills are
+        // configured. The 3 entries are appended AFTER projection so a
+        // consumer-shipped tool with a colliding name (rare — consumers
+        // shouldn't author tools named `qodo-skills.*`) still wins via the
+        // dedup-by-name pass below, mirroring the projection's
+        // "consumer-shipped wins on collision" invariant.
+        //
+        // Whether the consumer also referenced `qodo-skills` in their
+        // `mcpTools.allowlist` doesn't matter — the projection step above
+        // can't synthesize tools for an sdk-transport MCP (no `tools/list`
+        // catalog), so we'd land here with the 3 entries missing regardless.
+        // De-dup-by-name guards against the unlikely future where projection
+        // grows an sdk-transport bridge that DOES emit the qodo-skills
+        // catalog; we'd still ship exactly three entries.
+        const projectedTools = skillsConfigured
+            ? mergeQodoSkillsTools(result.tools)
+            : result.tools;
+        // Strip the SDK-only fields and replace `tools[]` with the projected
+        // surface. Object spread + delete keeps the original spec immutable
+        // (consumers may hold references for retry / display).
+        const stripped = stripMcpToolsFromSpec(spec);
+        return { ...stripped, tools: projectedTools };
+    }
+    /**
+     * MCP projection over an `InlineGraphSpec`. Walks every node whose
+     * `spec` is an inline `InlineAgentSpec` and applies
+     * {@link projectMcpToolsForWire} to it; static refs and nested
+     * subgraphs are recursed into. Returns a fresh `InlineGraphSpec` with
+     * the same shape but every per-node `tools[]` replaced by the
+     * projected surface. Diagnostic errors propagate from the first
+     * node that fails — earlier nodes have already projected
+     * successfully, but the wire write hasn't started so the early
+     * partial work is invisible.
+     */
+    async projectMcpToolsForGraphWire(graph) {
+        const agentEntries = Object.entries(graph.agents);
+        const newAgents = {};
+        let touched = false;
+        for (const [name, agentNode] of agentEntries) {
+            const node = agentNode;
+            const inner = node.spec;
+            if (isInlineAgentNode(inner)) {
+                const projected = await this.projectMcpToolsForWire(inner);
+                if (projected !== inner) {
+                    newAgents[name] = { ...node, spec: projected };
+                    touched = true;
+                }
+                else {
+                    newAgents[name] = node;
+                }
+            }
+            else if (isInlineGraphNode(inner)) {
+                const projectedGraph = await this.projectMcpToolsForGraphWire(inner);
+                if (projectedGraph !== inner) {
+                    newAgents[name] = { ...node, spec: projectedGraph };
+                    touched = true;
+                }
+                else {
+                    newAgents[name] = node;
+                }
+            }
+            else {
+                newAgents[name] = node;
+            }
+        }
+        if (!touched)
+            return graph;
+        return { ...graph, agents: newAgents };
+    }
+    /**
+     * Resolve the caller-pinned roots into a rendered active-skills block
+     * + telemetry events. Pure — relies on the already-loaded snapshot
+     * (callers await `manager.discover()` before getting here). Returns
+     * an empty result when no pins are effective.
+     */
+    composeActiveSkills(effectivePinned) {
+        if (this.skills === undefined)
+            return { text: '', skills: [], events: [] };
+        if (effectivePinned === undefined || effectivePinned.length === 0) {
+            return { text: '', skills: [], events: [] };
+        }
+        const snapshot = this.skills.currentSnapshot;
+        if (snapshot === null) {
+            // Defensive — the public entry points await discover() before this
+            // is invoked. Falling through with an empty block keeps the wire
+            // payload coherent if a future refactor changes the call order.
+            return { text: '', skills: [], events: [] };
+        }
+        const lookup = lookupFromSnapshot(snapshot.skills, this.skills);
+        const roots = [];
+        const seen = new Set();
+        for (const spec of effectivePinned) {
+            const skill = lookup.get(spec);
+            if (skill === null) {
+                // validatePinnedSync would normally catch this; throw the same
+                // typed error in case it slipped through.
+                throw new SkillNotFoundError(spec);
+            }
+            if (seen.has(skill.fqn))
+                continue;
+            seen.add(skill.fqn);
+            roots.push(skill);
+        }
+        const resolution = resolveAllActivations(roots, lookup);
+        if (resolution.outcome === 'failed') {
+            this.dispatchSkillsEvents(resolution.events);
+            const failureReason = mapFailureReason(resolution.failure.result.outcome);
+            throw new QodoSkillError(resolution.failure.root.fqn, failureReason, activationFailureMessage(resolution.failure.root, resolution.failure.result));
+        }
+        const rendered = renderActiveSkillsBlock(resolution.ordered, this.skills);
+        // Deliberately do NOT call `manager.markActive(skill.fqn)` here.
+        //
+        // `composeActiveSkills` runs **before** the wire write is guaranteed
+        // to succeed. The preflight HTTP call can still reject
+        // (`agent_spec_rejected`), and the WebSocket `task.start` write can
+        // still fail. Mutating the shared `activeFqns` set here would leak
+        // past those failure modes — the next LLM-driven `get_skill` for
+        // the same FQN would see the stale entry and suppress the
+        // `sdk.skill.activated { source: 'llm' }` event (the MCP server's
+        // `newlyActive` branch). Telemetry would then under-count fresh
+        // activations, and the active set would claim skills the model has
+        // not actually loaded.
+        //
+        // The caller-pin activation signal is the
+        // `sdk.skill.activated { source: 'caller' }` event the renderer
+        // emits — that's what consumers wire for "this skill is now part of
+        // the conversation". `getActiveSkills()` and
+        // `skillsMcpServer.loadedSkillFqns` reflect the strictly per-client
+        // LLM-driven `get_skill` history, which is what the body cache
+        // actually maps to.
+        return rendered;
+    }
+    /**
+     * Surface a caller-pin overflow as a loud failure. The renderer drops
+     * pinned skills that would push the block past its hard cap
+     * (`2 × charBudget`, floored at `charBudget + 4096`). Silently
+     * truncating the wire payload would make the model behave as if the
+     * caller never pinned those skills — throw instead so the caller
+     * fixes the pin list or raises the budget.
+     */
+    throwIfPinsOmitted(omitted, renderOpts) {
+        if (omitted.length === 0)
+            return;
+        const budget = renderOpts.charBudget ?? 8000;
+        const hardCap = Math.max(budget * 2, budget + 4096);
+        throw new SkillsBudgetExceededError(omitted.map((s) => s.fqn), hardCap);
+    }
+    /**
+     * Resolve per-call pinned skills against the constructor-level
+     * `SkillsConfig.activate` default:
+     *
+     *   - `opts.skills === undefined` → fall back to the constructor's
+     *     `activate` (or `undefined` if none).
+     *   - `opts.skills === []` → explicit empty, no fallback.
+     *   - `opts.skills === [...]` → per-call wins outright.
+     */
+    resolveEffectivePinned(perCall) {
+        if (perCall !== undefined)
+            return perCall;
+        if (this.skills === undefined)
+            return undefined;
+        return this.skills.defaultActivate;
+    }
+    buildRenderOptions(pinned, currentFile) {
+        const opts = {};
+        if (pinned !== undefined) {
+            opts.pinned = pinned;
+        }
+        if (currentFile !== undefined) {
+            opts.currentFilePath = currentFile;
+        }
+        // Forward the constructor-level `indexCharBudget` so consumers who
+        // configured a tighter budget actually see it applied.
+        //
+        // Validate before forwarding: `NaN`, `Infinity`, or non-positive
+        // values would break `Math.max()` and `>` comparisons inside the
+        // renderer's hard-cap logic (`x > NaN` is always false, so the cap
+        // never fires). On invalid input, ignore and let the renderer fall
+        // back to `DEFAULT_INDEX_CHAR_BUDGET`.
+        if (this.skills !== undefined) {
+            const budget = this.skills.indexCharBudget;
+            if (budget !== undefined && Number.isFinite(budget) && budget > 0) {
+                opts.charBudget = Math.floor(budget);
+            }
+        }
+        return opts;
+    }
+    /**
+     * Validate caller-pinned specifiers against the manager's already-loaded
+     * snapshot. Throws `SkillNotFoundError` on a miss and
+     * `SkillAmbiguousPinError` on a bare-name pin that matches multiple
+     * vendors. Assumes the snapshot is present (the public entry-points
+     * await `discover()` before calling this helper).
+     */
+    validatePinnedSync(pinned) {
+        if (this.skills === undefined)
+            return;
+        const snapshot = this.skills.currentSnapshot;
+        if (snapshot === null)
+            return;
+        for (const spec of pinned) {
+            const result = resolveSpecifierInList(snapshot.skills, spec);
+            if (result.outcome === 'not_found') {
+                throw new SkillNotFoundError(spec);
+            }
+            if (result.outcome === 'ambiguous') {
+                throw new SkillAmbiguousPinError(spec, result.candidates);
+            }
+        }
+    }
+    /** Forward renderer telemetry events to the manager's configured sink. */
+    dispatchSkillsEvents(events) {
+        if (this.skills === undefined || events.length === 0)
+            return;
+        this.skills.forwardEvents(events);
+    }
+}
+/**
+ * Prepend the rendered active-skills block to an `Instructions` field
+ * (string or preset). For preset: write to `append` so the QAR-side prompt
+ * builder concatenates after the preset body. The active block lands BEFORE
+ * the existing append content + slim-index block, since the bodies are
+ * authoritative.
+ */
+function prependInstructions(current, blockText) {
+    if (typeof current === 'string') {
+        if (current.length === 0)
+            return blockText;
+        return `${blockText}\n\n${current}`;
+    }
+    const existingAppend = current.append ?? '';
+    const newAppend = existingAppend.length === 0
+        ? blockText
+        : `${blockText}\n\n${existingAppend}`;
+    return { preset: current.preset, append: newAppend };
+}
+/**
+ * Walk a graph's agents map and prepend the active-skills block to every
+ * inline `AgentSpec`. Static-ref nodes are returned untouched (no
+ * instructions surface on the wire). Sub-graphs recurse.
+ */
+function prependActiveSkillsToGraphAgents(agents, blockText) {
+    const out = {};
+    for (const [name, agent] of Object.entries(agents)) {
+        out[name] = prependToGraphAgent(agent, blockText);
+    }
+    return out;
+}
+function prependToGraphAgent(agent, blockText) {
+    const inner = agent.spec;
+    if (typeof inner !== 'object' || inner === null || !('kind' in inner)) {
+        return agent;
+    }
+    if (inner.kind === 'AgentSpec') {
+        return {
+            ...agent,
+            spec: { ...inner, instructions: prependInstructions(inner.instructions, blockText) },
+        };
+    }
+    if (inner.kind === 'GraphSpec') {
+        return {
+            ...agent,
+            spec: { ...inner, agents: prependActiveSkillsToGraphAgents(inner.agents, blockText) },
+        };
+    }
+    return agent;
+}
+/**
+ * Map the resolver's failure outcome onto the typed `QodoSkillError.reason`
+ * field. The two enums diverge only in the `'ok'` variant (filtered out
+ * before this is called).
+ */
+function mapFailureReason(outcome) {
+    return outcome;
+}
+/**
+ * Synchronous specifier resolver used by `TaskClient` for caller-pinned
+ * validation. Mirrors `SkillsManager.get` for the cached-snapshot case,
+ * plus an ambiguity check: a bare name that matches multiple
+ * `fqnNoVersion` values returns `ambiguous` so the caller surfaces a
+ * loud `SkillAmbiguousPinError` rather than silently picking one.
+ */
+function resolveSpecifierInList(skills, spec) {
+    const versionMatch = /^(.+?)@([^@]+)$/.exec(spec);
+    if (versionMatch !== null) {
+        const fqnNoVersion = versionMatch[1];
+        const version = versionMatch[2];
+        return skills.some((s) => s.fqnNoVersion === fqnNoVersion && s.version === version)
+            ? { outcome: 'found' }
+            : { outcome: 'not_found' };
+    }
+    if (spec.includes('/')) {
+        return skills.some((s) => s.fqnNoVersion === spec)
+            ? { outcome: 'found' }
+            : { outcome: 'not_found' };
+    }
+    const distinctFqnNoVersion = new Set();
+    for (const s of skills) {
+        if (s.name === spec)
+            distinctFqnNoVersion.add(s.fqnNoVersion);
+    }
+    if (distinctFqnNoVersion.size === 0)
+        return { outcome: 'not_found' };
+    if (distinctFqnNoVersion.size === 1)
+        return { outcome: 'found' };
+    return {
+        outcome: 'ambiguous',
+        candidates: [...distinctFqnNoVersion].sort(),
+    };
+}
+/**
+ * Parse a server `error` envelope into the appropriate typed error class:
+ *
+ *   - `agent_spec_rejected` → `QodoAgentSpecRejectedError` (carries
+ *     `issues: InlineAgentSpecIssue[]`).
+ *   - Any code recognized by `classForServerErrorCode` →
+ *     the matching `QodoServerError` subclass.
+ *   - Anything else → `QodoUnknownServerError` so consumers' `catch
+ *     (err: QodoServerError)` blocks still see structured fields.
+ *
+ * The wire `payload.errors` array is duck-typed (codegen still narrows
+ * to the base `ErrorPayload` shape without the `errors` extension), so
+ * absent/malformed entries default to an empty array and the typed
+ * error class carries just `code` + `message`.
+ */
+function errorFromServerErrorEnvelope(envelope) {
+    const payload = envelope.payload;
+    if (payload.code === 'agent_spec_rejected') {
+        return errorFromAgentSpecRejection(envelope);
+    }
+    const entries = [];
+    if (Array.isArray(payload.errors)) {
+        for (const entry of payload.errors) {
+            if (entry === null || typeof entry !== 'object')
+                continue;
+            const rule_id = typeof entry.rule_id === 'string' ? entry.rule_id : payload.code;
+            const path = typeof entry.path === 'string' ? entry.path : '';
+            const message = typeof entry.message === 'string' ? entry.message : (payload.message ?? '');
+            entries.push({ rule_id, path, message });
+        }
+    }
+    const offendingMessageId = typeof payload.offending_message_id === 'string' ? payload.offending_message_id : undefined;
+    const message = payload.message ?? `server error: ${payload.code}`;
+    const Cls = classForServerErrorCode(payload.code);
+    if (Cls !== undefined) {
+        const err = new Cls(message, entries, offendingMessageId);
+        // Attach the envelope's inherited `session_id` to
+        // `QodoAdmissionStalledError` so consumers reading the typed throw
+        // can pull the derived session UUID without dipping into the
+        // envelope. The ErrorEnv carries the derived `session_id` for
+        // post-derivation failures (admission_stalled is one) — anything
+        // but the all-zero pre-bind UUID is a valid scope.
+        if (err instanceof QodoAdmissionStalledError) {
+            const sid = envelope.session_id;
+            if (typeof sid === 'string' && sid.length > 0 && !isZeroUuid(sid)) {
+                err.attachSessionId(sid);
+            }
+        }
+        return err;
+    }
+    return new QodoUnknownServerError(payload.code, message, entries, offendingMessageId);
+}
+/**
+ * Tell the pre-bind zero-UUID (`00000000-0000-0000-0000-000000000000`)
+ * apart from a real derived session_id. The wire emits the zero-UUID on
+ * pre-derivation errors (envelope parse, auth rejection, invalid
+ * `idempotency_key`); post-derivation errors (`admission_stalled`,
+ * `admission_in_progress`, etc.) carry the real derived UUID. Don't
+ * surface the zero-UUID through typed errors — it's not a routable
+ * address.
+ */
+function isZeroUuid(value) {
+    return value === '00000000-0000-0000-0000-000000000000';
+}
+/**
+ * Parse QAR's `agent_spec_rejected` envelope into a typed
+ * `QodoAgentSpecRejectedError`. The envelope's `payload` carries the
+ * structured `errors: [{ rule_id, path, message }]` array; codegen
+ * types the payload as the base `ErrorPayload` (`{ code, message,
+ * offending_message_id? }`) without the `errors` extension, so the
+ * parse here is duck-typed: we read `errors` if present, otherwise
+ * fall back to a single-entry list with the envelope's `code` as
+ * `rule_id`.
+ */
+function errorFromAgentSpecRejection(envelope) {
+    const payload = envelope.payload;
+    const issues = [];
+    if (Array.isArray(payload.errors)) {
+        for (const entry of payload.errors) {
+            if (entry === null || typeof entry !== 'object')
+                continue;
+            const rule_id = typeof entry.rule_id === 'string' ? entry.rule_id : payload.code;
+            const path = typeof entry.path === 'string' ? entry.path : '';
+            const message = typeof entry.message === 'string' ? entry.message : (payload.message ?? '');
+            issues.push({ rule_id, path, message });
+        }
+    }
+    if (issues.length === 0) {
+        // Envelope didn't carry the structured `errors` array — synthesize a
+        // single entry from the top-level `code` + `message` so the typed error
+        // always carries at least one issue (the constructor's invariant).
+        issues.push({
+            rule_id: payload.code,
+            path: '',
+            message: payload.message ?? `Inline AgentSpec rejected with code ${payload.code}`,
+        });
+    }
+    return new QodoAgentSpecRejectedError(issues);
+}
+/**
+ * Yield events from a `Promise<TaskSubscription>`. Used by the preflighted
+ * `tasks.startWith*` paths so the preflight HTTP call + the wire
+ * `task.start` write can be kicked off eagerly in the public method
+ * (closing the cancel-race-during-preflight foot-gun), while the
+ * returned iterable still lazily yields events the consumer iterates
+ * through.
+ *
+ * `wrapServerErrors` flips on so a server-side `error` envelope arriving
+ * on the subscription surfaces as a typed `QodoServerError` (or
+ * `QodoAgentSpecRejectedError` for the spec-rejection carve-out)
+ * instead of a yielded `kind: 'error'` event.
+ */
+async function* yieldFromPromisedSub(subPromise, wrapServerErrors) {
+    const sub = await subPromise;
+    for await (const event of sub) {
+        if (wrapServerErrors && event.kind === 'error') {
+            const code = event.payload.code;
+            if (typeof code === 'string' && isTypedErrorCode(code)) {
+                throw errorFromServerErrorEnvelope(event);
+            }
+        }
+        yield event;
+    }
+}
+/**
+ * Whether the SDK has a typed `QodoServerError` subclass (or
+ * `QodoAgentSpecRejectedError`) for this wire code. Used by the
+ * iterator wrappers to decide whether to throw vs yield the
+ * `kind: 'error'` event — codes without a typed class flow through
+ * unchanged so existing consumer narrowing keeps working.
+ */
+function isTypedErrorCode(code) {
+    if (code === 'agent_spec_rejected')
+        return true;
+    return classForServerErrorCode(code) !== undefined;
+}
+/**
+ * Decorate an `AsyncIterable<TaskEvent>` with the synchronous `taskId` and
+ * the `sessionId` Promise so consumers can read both before iterating.
+ *
+ * `taskId` is the SDK-derived value — `task_id == task.start.message_id`
+ * — available at envelope mint time.
+ *
+ * `sessionId` is the server-derived UUID arriving on the `task.started`
+ * admission ack; the Promise resolves when the ack lands and rejects if
+ * the subscription terminates without admission.
+ *
+ * Returns a thin wrapper object that delegates `[Symbol.asyncIterator]`
+ * to the underlying iterable — we deliberately don't mutate `iter`.
+ */
+function attachTaskId(iter, taskId, admittedTaskId, sessionId, admissionResult) {
+    return {
+        [Symbol.asyncIterator]: () => iter[Symbol.asyncIterator](),
+        taskId,
+        admittedTaskId,
+        sessionId,
+        admissionResult,
+    };
+}
+/**
+ * Cap on the SDK's `admission_in_progress` retry budget. Mirrors
+ * `PENDING_ADMISSION_TIMEOUT` on the server side. After this wall-clock
+ * window the SDK gives up retrying and throws
+ * {@link QodoAdmissionTimeoutError}. Operator-facing default; consumers
+ * who need a different cap can wrap the SDK call themselves.
+ */
+const PENDING_ADMISSION_TIMEOUT_MS = 5 * 60 * 1000;
+/** Initial backoff for `admission_in_progress` retries when the server omits `retry_after_ms`. */
+const ADMISSION_RETRY_INITIAL_MS = 100;
+function createDeferred() {
+    let resolve;
+    let reject;
+    let done = false;
+    const promise = new Promise((res, rej) => {
+        resolve = (v) => {
+            if (done)
+                return;
+            done = true;
+            res(v);
+        };
+        reject = (e) => {
+            if (done)
+                return;
+            done = true;
+            rej(e);
+        };
+    });
+    // Default unhandled-rejection guard — the deferred may reject before any
+    // consumer awaits `promise`. Without this attach Node logs an
+    // `unhandledRejection` warning between rejection time and the consumer's
+    // `await stream.sessionId` (which still re-surfaces the error).
+    promise.catch(() => undefined);
+    return { promise, resolve, reject, settled: () => done };
+}
+/**
+ * Backoff schedule for `admission_in_progress` retries when the server
+ * omits `retry_after_ms`. Exponential doubling from
+ * `ADMISSION_RETRY_INITIAL_MS`, capped at the operator timeout. ±10%
+ * multiplicative jitter so a pod stampede doesn't synchronize retry
+ * waves.
+ *
+ * Pure function — `Math.random()` is the only impurity and is the source
+ * of the jitter; tests can disable jitter by hand-rolling a wait (the
+ * SDK doesn't expose a seam to override the RNG, matching the rest of
+ * the codebase's transport timers).
+ */
+function computeAdmissionRetryBackoffMs(attempt) {
+    // Apply the cap AFTER jitter so the return value can NEVER exceed
+    // `PENDING_ADMISSION_TIMEOUT_MS`. Capping `base` first and then adding
+    // jitter on top would let the result drift up to +10% above the
+    // timeout.
+    const base = ADMISSION_RETRY_INITIAL_MS * Math.pow(2, attempt);
+    const jitter = base * 0.1 * Math.random();
+    return Math.floor(Math.min(base + jitter, PENDING_ADMISSION_TIMEOUT_MS));
+}
+/**
+ * Read the server's `retry_after_ms` hint off an `admission_in_progress`
+ * envelope. The field is optional + non-negative integer milliseconds;
+ * ill-typed values fall back to `undefined` so the caller uses the SDK's
+ * exponential backoff.
+ */
+function parseRetryAfterMsHint(env) {
+    const v = env.payload.retry_after_ms;
+    if (typeof v === 'number' && Number.isFinite(v) && v >= 0)
+        return Math.floor(v);
+    return undefined;
+}
+/** Promise-returning setTimeout — distinct fn name keeps the call sites greppable. */
+function sleepMs(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Client-side `idempotencyKey` validation — mirrors QAR's wire validator
+ * (`Field(min_length=1, max_length=512, pattern=r"^[^\x00]+$")` on a
+ * Pydantic `str`) so a bad value fails fast on the SDK side rather than
+ * waiting for the server to round-trip an error envelope. Length is
+ * measured in **Unicode code points** (`[...key].length`), matching
+ * Pydantic's `Field` semantics on `str` — NOT UTF-16 code units (which
+ * `key.length` would give) and NOT UTF-8 bytes (relevant for the NUL
+ * exclusion, where the wire validator's `[^\x00]+` pattern matches code
+ * points and would not be fooled by a stray `U+0000`).
+ *
+ * Throws {@link QodoIdempotencyKeyValidationError} with a discriminated
+ * `reason` so callers can branch without parsing the message.
+ *
+ * **Observability hygiene**: NEVER log the raw key from this function or
+ * its call sites. The thrown error carries the code-point count, not the
+ * value; consumers handling the error are responsible for keeping the
+ * original input out of operator-facing surfaces.
+ */
+function validateIdempotencyKey(key) {
+    // Spread iterates code points (handles surrogate pairs correctly);
+    // `String.prototype.length` would count UTF-16 code units and miscount
+    // anything outside the BMP. The wire limit is 512 **code points**.
+    const codePoints = [...key].length;
+    if (codePoints === 0) {
+        throw new QodoIdempotencyKeyValidationError('too_short', 0);
+    }
+    if (codePoints > 512) {
+        throw new QodoIdempotencyKeyValidationError('too_long', codePoints);
+    }
+    // NUL exclusion — mirrors QAR's `pattern=r"^[^\x00]+$"` validator.
+    // We iterate code points (not UTF-16 code units) for consistency with
+    // the length check above; `codePointAt(0) === 0` tests the U+0000 case
+    // without embedding a NUL literal in source.
+    for (const cp of key) {
+        if (cp.codePointAt(0) === 0) {
+            throw new QodoIdempotencyKeyValidationError('contains_nul', codePoints);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// MCP projection helpers
+// ---------------------------------------------------------------------------
+/**
+ * Discriminate an `InlineGraphAgent.spec` union arm — `true` for the
+ * inline `InlineAgentSpec` branch (matched by `kind` literal or absence
+ * of the `agent_id` static-ref field). Mirrors the runtime discriminator
+ * in `inlineGraph.ts` so the projection graph walker doesn't have to
+ * import the private helper.
+ */
+function isInlineAgentNode(spec) {
+    if (typeof spec !== 'object' || spec === null)
+        return false;
+    if (spec.agent_id !== undefined)
+        return false;
+    const kind = spec.kind;
+    return kind === 'AgentSpec' || kind === undefined;
+}
+/** Discriminate the nested-subgraph arm of `InlineGraphAgent.spec`. */
+function isInlineGraphNode(spec) {
+    if (typeof spec !== 'object' || spec === null)
+        return false;
+    return spec.kind === 'GraphSpec';
+}
+/**
+ * Walk an `InlineGraphSpec` looking for any inline-agent node that
+ * declares `mcpTools` / `mcpToolOverrides`. Returns `true` on the first
+ * hit — the caller uses this to decide whether to route the dispatch
+ * through the eager-async path that awaits MCP catalog settle. Recurses
+ * into nested-subgraph nodes so a deeply-nested consumer still
+ * triggers the async path at the root.
+ */
+/**
+ * Walk an `InlineGraphSpec`'s agent nodes and feed every inline
+ * agent's `tools[]` into the supplied bind callback. Static-ref nodes
+ * (`{ agent_id }`) have no tools surface; sub-graphs recurse.
+ *
+ * Used at `startWithGraph` time so `defineFunctionTool` handlers
+ * attached to per-node `tools[]` get installed on the client's
+ * `ToolClient` before the wire `task.start` write.
+ */
+function collectGraphFunctionTools(graph, bind) {
+    for (const node of Object.values(graph.agents)) {
+        const inner = node.spec;
+        if (isInlineAgentNode(inner)) {
+            if (inner.tools != null && inner.tools.length > 0) {
+                bind(inner.tools);
+            }
+        }
+        else if (isInlineGraphNode(inner)) {
+            collectGraphFunctionTools(inner, bind);
+        }
+    }
+}
+function graphHasMcpProjection(graph) {
+    for (const node of Object.values(graph.agents)) {
+        const inner = node.spec;
+        if (isInlineAgentNode(inner)) {
+            if (inner.mcpTools !== undefined ||
+                inner.mcpToolOverrides !== undefined) {
+                return true;
+            }
+        }
+        else if (isInlineGraphNode(inner)) {
+            if (graphHasMcpProjection(inner))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Append the `qodo-skills.*` projected tool surface to the
+ * post-projection wire `tools[]`, deduping by name so a consumer-shipped
+ * tool with a colliding name (rare; consumers shouldn't author tools
+ * under the SDK-owned `qodo-skills.` prefix) still wins.
+ *
+ * Returns the original array reference when nothing would change so
+ * downstream `result !== input` comparisons stay meaningful.
+ */
+function mergeQodoSkillsTools(projected) {
+    const skillsDefs = qodoSkillsFunctionToolDefs();
+    if (skillsDefs.length === 0)
+        return projected;
+    const existingNames = new Set();
+    for (const tool of projected) {
+        existingNames.add(tool.function.name);
+    }
+    const toAppend = [];
+    for (const def of skillsDefs) {
+        if (existingNames.has(def.function.name))
+            continue;
+        toAppend.push(def);
+    }
+    if (toAppend.length === 0)
+        return projected;
+    return [...projected, ...toAppend];
+}
+/**
+ * Recursively apply {@link mergeQodoSkillsTools} to every inline-agent
+ * node in a graph spec. Static refs and nested subgraph nodes are
+ * walked through. Returns the original `graph` reference when nothing
+ * needed to change.
+ */
+function mergeQodoSkillsToolsIntoGraph(graph) {
+    const agentEntries = Object.entries(graph.agents);
+    const newAgents = {};
+    let touched = false;
+    for (const [name, agentNode] of agentEntries) {
+        const node = agentNode;
+        const inner = node.spec;
+        if (isInlineAgentNode(inner)) {
+            const original = inner.tools ?? [];
+            const merged = mergeQodoSkillsTools(original);
+            if (merged !== original) {
+                newAgents[name] = { ...node, spec: { ...inner, tools: merged } };
+                touched = true;
+            }
+            else {
+                newAgents[name] = node;
+            }
+        }
+        else if (isInlineGraphNode(inner)) {
+            const projected = mergeQodoSkillsToolsIntoGraph(inner);
+            if (projected !== inner) {
+                newAgents[name] = { ...node, spec: projected };
+                touched = true;
+            }
+            else {
+                newAgents[name] = node;
+            }
+        }
+        else {
+            newAgents[name] = node;
+        }
+    }
+    if (!touched)
+        return graph;
+    return { ...graph, agents: newAgents };
+}
+/**
+ * Strip SDK-only `mcpTools` / `mcpToolOverrides` fields from an inline
+ * `InlineAgentSpec`. The projection layer replaces `tools[]` separately —
+ * this helper only handles the field removal so the wire envelope
+ * doesn't carry surfaces QAR's wire validator (`D10-R5` on
+ * `extra='forbid'`) would reject.
+ */
+function stripMcpToolsFromSpec(spec) {
+    const hasField = spec.mcpTools !== undefined ||
+        spec.mcpToolOverrides !== undefined;
+    if (!hasField)
+        return spec;
+    // Destructure removes the two fields; rest carries every wire field.
+    const { mcpTools: _mcpTools, mcpToolOverrides: _mcpToolOverrides, ...rest } = spec;
+    void _mcpTools;
+    void _mcpToolOverrides;
+    return rest;
+}
+//# sourceMappingURL=TaskClient.js.map