@qodo/sdk 0.13.3 → 2.0.0-next.0

package/dist/client/ToolClient.js

@@ -0,0 +1,1115 @@
+/**
+ * `ToolClient` — surfaces inbound `tool.request` envelopes
+ * (parallel-batched) and accepts outbound `tool.response` envelopes
+ * (same shape).
+ *
+ * The parallel-batched envelope shape:
+ *
+ *   - `tool.request.payload` carries `calls: ToolCall[]` (always a list, even
+ *     for a single call — modern LLM `parallel_tool_use`) and a required
+ *     `node_name`. The handler receives the full envelope; `req.payload.calls`
+ *     is the call list, `req.payload.node_name` is the originating node.
+ *   - `tool.response.payload` carries `responses: ToolResponseItem[]` (same
+ *     length / membership as the request's `calls`) and the same `node_name`.
+ *
+ * Handler return shapes:
+ *
+ *   - returns `ToolResponseResult` (single SDK union)         → auto-batched
+ *     into `responses: [resp]` against `calls[0]`. Requires `calls.length === 1`;
+ *     otherwise a `QodoWireValidationError` surfaces. The most common shape
+ *     after a 1.x → 2.0 migration (where every request was single-call).
+ *   - returns `readonly ToolResponseResult[]` (one per call)  → auto-batched
+ *     positionally; length must equal `calls.length`.
+ *   - returns `undefined`                                     → fall through
+ *     to the next handler in the stack; if every handler returns `undefined`
+ *     the consumer is expected to call `respond()` later (approval flow / async
+ *     tool). With zero handlers, the SDK emits a `denied` envelope so QAR's
+ *     agent loop doesn't hang.
+ *
+ * `respond(nodeName, response | responses)` is the manual escape hatch. It
+ * builds a `tool.response` envelope and writes it through the connection. No
+ * ack: QAR's `task.delta` / `task.done` chain advances on its own once the
+ * response lands.
+ *
+ * Concurrency: each `tool.request` envelope carries N calls but is dispatched
+ * as a single handler invocation. QAR may emit multiple `tool.request`
+ * envelopes per task (separate dispatch rounds); each runs through the stack
+ * independently. The wire is keyed on `tool_call_id` for each individual call.
+ *
+ * Error mapping (per-call):
+ *   - handler throws `ToolDeniedError`   → `status: 'error'`, `error.code: 'denied'`
+ *   - handler throws anything else       → `status: 'error'`, `error.code: 'error'`
+ *   - returns malformed result           → `status: 'error'`, generic message
+ *                                          (handler internals never leak to QAR)
+ *
+ * Error/reason strings are truncated so a stack trace can't blow up the wire
+ * payload.
+ */
+import { QodoWireValidationError, ToolDeniedError } from './errors.js';
+import { isThenable } from './internal/thenable.js';
+import { toolOutcomeFor } from '../observability/spans.js';
+import { QAR_TOOL_OUTCOME } from '../observability/attributes.js';
+import { FunctionToolRouter } from './tools/bindFunctionToolDefs.js';
+import { defaultApprovalHandler, } from './tools/approval.js';
+/** Cap on `error.message` strings serialized into `tool.response` items. */
+const MAX_ERROR_LEN = 1024;
+export class ToolClient {
+    resolveConnection;
+    spanRecorder;
+    handlers = [];
+    /**
+     * SDK-attached auto-bridge handlers (qodo-skills, remote-MCP). Distinct
+     * from {@link handlers} (consumer-registered via `onRequest`) so the
+     * dispatcher's deterministic-deny path can fire when only SDK fallbacks
+     * are in the stack and no consumer-side handler exists.
+     *
+     * Without this split, the bridge-being-attached defeats the
+     * zero-primary-handler deny fallback. Walking primaries first,
+     * fallbacks second, with deny keyed on `primaries.length === 0`
+     * (regardless of fallback count) gives consumers the
+     * deterministic-deny ergonomic they expect from "I didn't register
+     * a handler" + lets the SDK auto-bridges still route MCP / skills
+     * calls when the consumer DOES register handlers later.
+     */
+    fallbackHandlers = [];
+    wireValidationHandlers = [];
+    dispatcher = null;
+    dispatcherConnection = null;
+    /**
+     * `defineFunctionTool` router — owns the per-tool-name handler map
+     * and a single `onRequest` subscription that dispatches inbound
+     * `tool.request` calls by name. Lazily attached the first time a
+     * function-tool handler is registered.
+     */
+    functionToolRouter = new FunctionToolRouter();
+    /**
+     * S4 — consumer-overridable approval resolver for
+     * `requireApproval`-gated function tools. Defaults to the
+     * stdin-prompt-when-TTY-else-deny handler from
+     * `src/client/tools/approval.ts`. Production apps register a custom
+     * handler (Slack, web UI, pager) via {@link setApprovalHandler}.
+     *
+     * Mutable so a `setApprovalHandler` call AFTER the router attaches
+     * still applies to subsequent batches — the router captures a
+     * getter, not the value, at attach time.
+     */
+    approvalHandler = defaultApprovalHandler;
+    /**
+     * @param resolveConnection Returns the live `Connection` or throws if the
+     *                          client isn't connected yet.
+     * @param spanRecorder      Recorder for `qar.client.tool.*` spans. No-op
+     *                          when OTel isn't configured.
+     */
+    constructor(resolveConnection, spanRecorder) {
+        this.resolveConnection = resolveConnection;
+        this.spanRecorder = spanRecorder;
+    }
+    /**
+     * Register a handler for inbound `tool.request` events.
+     *
+     * Stacking semantics: the first handler that returns a non-`undefined`
+     * value (single result or array) claims the entire request; its responses
+     * are auto-sent. If every handler returns `undefined`, the consumer must
+     * call `respond()` explicitly within QAR's per-task tool-response timeout.
+     *
+     * `QodoClient.connect()` already attaches the fan-out dispatcher on the
+     * live connection (so a `tool.request` arriving with zero handlers
+     * deterministically emits `status: 'error'` / `error.code: 'denied'`
+     * instead of leaving QAR paused on the call set). `onRequest` just adds to
+     * the stack.
+     *
+     * If `attachDispatcher()` throws — e.g. the caller registered a handler
+     * before `connect()` and we have no connection to attach to — we roll
+     * back the handler push so consumers don't end up with an orphaned
+     * registration they can't `unsubscribe()`.
+     */
+    onRequest(handler) {
+        this.handlers.push(handler);
+        try {
+            this.attachDispatcher();
+        }
+        catch (err) {
+            // Roll back the just-added handler so the failed call leaves no trace.
+            const idx = this.handlers.lastIndexOf(handler);
+            if (idx >= 0)
+                this.handlers.splice(idx, 1);
+            throw err;
+        }
+        return {
+            unsubscribe: () => {
+                const idx = this.handlers.indexOf(handler);
+                if (idx >= 0)
+                    this.handlers.splice(idx, 1);
+                // Don't detach the dispatcher when the stack empties — the bound
+                // dispatcher is the deterministic-deny path for `tool.request`s
+                // that arrive while no handler is registered. Detach only on
+                // disconnect (handled by the dispatcher's `onConnectionClosed`).
+            },
+        };
+    }
+    /**
+     * Register `defineFunctionTool`-produced entries against the
+     * client's internal router. Any tool in `tools` carrying the
+     * `defineFunctionTool` handler symbol gets added to the router's
+     * name → handler table; tools without the symbol (e.g. hand-authored
+     * `FunctionToolDef` literals) are skipped.
+     *
+     * Idempotent — re-registering the same tool name replaces the
+     * existing handler in-place. The router's `onRequest` subscription
+     * is attached lazily on first registration; it stays attached for
+     * the lifetime of the client.
+     *
+     * `tasks.startWithAgent` / `tasks.startWithGraph` auto-call this
+     * with `agent.tools` so the common path "drop helpers into
+     * `tools[]`" needs no manual binding. The explicit method is
+     * available for consumers using `tasks.start` (server-defined
+     * agent_id) who still want type-safe handler organization by tool
+     * name, or for any pre-task registration flow.
+     *
+     * @returns Number of newly registered handlers from this call.
+     */
+    bindFunctionTools(tools) {
+        const added = this.functionToolRouter.register(tools);
+        if (added > 0)
+            this.functionToolRouter.attach(this);
+        return added;
+    }
+    /**
+     * Register the resolver invoked when a `requireApproval`-gated
+     * function tool is about to dispatch (S4). The handler decides
+     * approve / deny; the SDK runs the function-tool handler on
+     * approve and returns `outcome: 'denied'` to QAR on deny.
+     *
+     * The default handler prompts on stdin when `process.stdin.isTTY`
+     * is true; in non-interactive contexts it deterministic-denies
+     * with a typed error message pointing at the missing registration.
+     * Production apps that route approvals to Slack / a web UI / a
+     * pager should register a custom handler at startup.
+     *
+     * Late binding is fine — a handler registered AFTER the router
+     * has attached still applies to subsequent inbound batches.
+     *
+     * @see {@link ApprovalHandler} for the resolver contract.
+     * @see `src/client/tools/approval.ts` for the default behavior.
+     */
+    setApprovalHandler(handler) {
+        if (typeof handler !== 'function') {
+            throw new TypeError('ToolClient.setApprovalHandler: handler must be a function');
+        }
+        this.approvalHandler = handler;
+    }
+    /**
+     * @internal — read by `FunctionToolRouter.attach` so dispatch-time
+     * approvals see the consumer's current handler (or the default).
+     * Exposed under the `_` prefix to keep it off the public IDE
+     * autocomplete; same convention as
+     * {@link _attachFallbackHandler} / {@link _bindConnection}.
+     */
+    _getApprovalHandler() {
+        return this.approvalHandler;
+    }
+    /**
+     * @internal — used by `FunctionToolRouter` to pre-check the wire
+     * after an approval resolves, BEFORE invoking the function-tool
+     * handler. Without the gate, a long-parked approval (Slack / web UI
+     * / pager round-trip) can resolve approve AFTER the auto-reconnect
+     * loop exhausted; the handler then runs (real-world side effect),
+     * `sendResponse` throws {@link QodoColdAddressError} because
+     * `clearTerminalState` already wiped the per-tool-call session map,
+     * and the swallow path in {@link attachDispatcher}'s send-fallback
+     * drops the response without a signal. Pinned in
+     * `tests/qar-mode/hitl-state-machine-matrix.test.ts`.
+     *
+     * Returns `false` when the connection is not currently addressable
+     * for outbound sends — either pre-`connect()`, mid-reconnect, or
+     * post-`failed`. The router synthesizes
+     * `outcome: 'error', error: 'connection lost before approval resolved'`
+     * for this case so the handler never executes; the result still
+     * routes through the normal dispatcher send path, which (correctly)
+     * swallows it once more because the wire is dead — but the
+     * load-bearing behavior is the **handler skip**, not the response.
+     */
+    _isConnectionLive() {
+        return this.isConnectionLive();
+    }
+    /**
+     * @internal — wired by `QodoClient.connect()` once the WS is open. Attaches
+     * a fan-out dispatcher to the connection so an inbound `tool.request` always
+     * round-trips a response, even when no `onRequest` handler is registered.
+     * Without this seam QAR's agent loop would hang on the call set.
+     */
+    _bindConnection(connection) {
+        this.attachDispatcher(connection);
+    }
+    /**
+     * @internal — used by `QodoClient` to attach SDK-side auto-bridges
+     * (`qodo-skills` MCP, generic remote-MCP). Fallback handlers are
+     * walked AFTER primary handlers (consumer-registered via {@link
+     * onRequest}). They don't count toward the dispatcher's
+     * "zero-handlers → deterministic deny" check, so a consumer who
+     * registers a remote MCP but no `onRequest` handler still sees the
+     * deny fallback fire on unknown tools rather than hanging.
+     *
+     * Same registration / unsubscribe ergonomics as {@link onRequest};
+     * the API split is purely internal so consumers don't accidentally
+     * register against the fallback stack.
+     */
+    _attachFallbackHandler(handler) {
+        this.fallbackHandlers.push(handler);
+        try {
+            this.attachDispatcher();
+        }
+        catch (err) {
+            const idx = this.fallbackHandlers.lastIndexOf(handler);
+            if (idx >= 0)
+                this.fallbackHandlers.splice(idx, 1);
+            throw err;
+        }
+        return {
+            unsubscribe: () => {
+                const idx = this.fallbackHandlers.indexOf(handler);
+                if (idx >= 0)
+                    this.fallbackHandlers.splice(idx, 1);
+            },
+        };
+    }
+    /**
+     * Register a handler for inbound wire-validation failures — `tool.request`
+     * envelopes the SDK dropped because they violated the wire shape
+     * (missing `node_name`, empty `calls`). The handler receives a typed
+     * `QodoWireValidationError` that carries the offending `message_id` and
+     * the field that failed validation, so consumer telemetry can branch on
+     * the exact protocol drift without parsing the `[@qodo/sdk]` log line.
+     *
+     * Observer-style: every registered handler fires on every drop (no
+     * winner-takes-all dispatch). Handlers run inside a defensive try/catch
+     * — a throwing handler logs to `console.error` and is otherwise swallowed
+     * so the dispatch hot path stays alive.
+     *
+     * The SDK has no `tool_call_id` to respond against for these envelopes,
+     * so registering a handler does NOT make the runtime see a response —
+     * QAR's per-task tool-response timeout remains the wire-side safety net.
+     * This surface exists purely so consumer code can observe the failure.
+     *
+     * Returning `Subscription` mirrors `onRequest` — `unsubscribe()` removes
+     * the handler; the dispatcher itself stays attached (it's the path that
+     * fires the breadcrumb log even when no handler is registered).
+     */
+    onWireValidationError(handler) {
+        this.wireValidationHandlers.push(handler);
+        try {
+            this.attachDispatcher();
+        }
+        catch (err) {
+            // Roll back the registration so the failed call leaves no trace.
+            const idx = this.wireValidationHandlers.lastIndexOf(handler);
+            if (idx >= 0)
+                this.wireValidationHandlers.splice(idx, 1);
+            throw err;
+        }
+        return {
+            unsubscribe: () => {
+                const idx = this.wireValidationHandlers.indexOf(handler);
+                if (idx >= 0)
+                    this.wireValidationHandlers.splice(idx, 1);
+            },
+        };
+    }
+    /**
+     * @internal — invoked by the dispatcher when it drops a malformed inbound
+     * `tool.request`. Fires every registered `onWireValidationError` handler
+     * with a typed error; per-handler exceptions are logged + swallowed so
+     * one buggy observer can't crash dispatch.
+     */
+    emitWireValidationError(err) {
+        // Snapshot the handler list — a handler may unsubscribe itself while
+        // we iterate. Mirrors `dispatch()`'s pattern with `onRequest` handlers.
+        const snapshot = [...this.wireValidationHandlers];
+        for (const handler of snapshot) {
+            try {
+                // Sync throw → caught here. Async rejection → caught by the
+                // Promise.resolve() chain below. Without the async guard a
+                // consumer registering `async (err) => { await persist(err); }`
+                // would surface their handler's rejections as a process-level
+                // `unhandledRejection`.
+                const result = handler(err);
+                if (isThenable(result)) {
+                    result.then(undefined, (handlerErr) => {
+                        logHandlerObserverError('onWireValidationError', handlerErr);
+                    });
+                }
+            }
+            catch (handlerErr) {
+                logHandlerObserverError('onWireValidationError', handlerErr);
+            }
+        }
+    }
+    async respond(nodeName, responses, opts) {
+        validateNodeName(nodeName, 'ToolClient.respond');
+        const batch = Array.isArray(responses)
+            ? responses
+            : [responses];
+        if (batch.length === 0) {
+            throw new QodoWireValidationError('ToolClient.respond: responses must be a non-empty list — tool.response always carries ≥ 1 item.');
+        }
+        for (const r of batch) {
+            if (!isValidToolResponseResult(r.result)) {
+                throw new TypeError('ToolClient.respond: every response.result must be a ToolResponseResult ({ outcome: "success" | "error" | "denied", ... })');
+            }
+            if (typeof r.tool_call_id !== 'string' || r.tool_call_id.length === 0) {
+                throw new TypeError('ToolClient.respond: every response must carry a non-empty tool_call_id');
+            }
+        }
+        const connection = this.resolveConnection();
+        // Per-call span family — one `qar.client.tool.respond` span per response
+        // item so per-call latency + outcome land independently in traces. Spans
+        // share the same parent (whatever was active when the consumer called
+        // respond()).
+        //
+        // The per-call `session_id` is looked up by tool_call_id — every
+        // response item echoes back to the session of its originating
+        // `tool.request`. When the consumer passed `opts.sessionId`
+        // (cold-respond after process restart), use it for the span
+        // attribute — the in-memory map will be empty in that scenario, but
+        // the consumer knows the right value. `Connection.sendEnvelope`
+        // performs its own lookup and throws `QodoColdAddressError` on miss
+        // if no override is provided.
+        const spans = batch.map((r) => this.spanRecorder.startToolRespondSpan({
+            sessionId: opts?.sessionId ?? connection.getSessionForToolCall(r.tool_call_id),
+            toolCallId: r.tool_call_id,
+            outcome: toolOutcomeFor(r.result.outcome),
+            nodeName,
+        }));
+        try {
+            // Use the FIRST span's context for the actual WS write so the outbound
+            // envelope's `traceparent` references something deterministic. The other
+            // per-call spans still record latency individually; their context isn't
+            // attached to the wire frame (a single envelope can carry only one
+            // traceparent). Cross-process trace continuity per call is preserved by
+            // the matched `qar.tool_call_id` attribute on both sides.
+            spans[0].withContext(() => this.sendResponse(nodeName, batch, opts?.sessionId));
+            for (const s of spans)
+                s.succeed();
+        }
+        catch (err) {
+            for (const s of spans)
+                s.fail(err);
+            throw err;
+        }
+    }
+    attachDispatcher(explicitConnection) {
+        const connection = explicitConnection ?? this.resolveConnection();
+        if (this.dispatcher !== null && this.dispatcherConnection === connection)
+            return;
+        // Connection swap (rare — disconnect + reconnect between onRequest calls):
+        // detach the stale dispatcher from the old connection before re-attaching.
+        if (this.dispatcher !== null && this.dispatcherConnection !== null) {
+            try {
+                this.dispatcherConnection.unsubscribe(this.dispatcher);
+            }
+            catch {
+                // The old connection may already be torn down — best-effort cleanup.
+            }
+        }
+        this.dispatcher = new ToolRequestDispatcher(this.handlers, this.fallbackHandlers, (nodeName, responses) => {
+            // Two failure modes for the send: connection closed mid-flight (no
+            // useful retry), or `JSON.stringify` blew up on a payload that slipped
+            // past the validator (e.g., a Date / Map masquerading as a JsonObject —
+            // the recursive validator catches cycles + non-JSON primitives but
+            // can't catch every prototype-shaped impostor). For the second case
+            // we attempt a deterministic per-call `status: 'error'` envelope so
+            // QAR's agent loop unblocks instead of timing out.
+            try {
+                this.sendResponse(nodeName, responses);
+                return;
+            }
+            catch (err) {
+                if (!this.isConnectionLive())
+                    return;
+                if (this.isInternalSerializationError(err, responses)) {
+                    try {
+                        const fallback = responses.map((r) => ({
+                            tool_call_id: r.tool_call_id,
+                            result: {
+                                outcome: 'error',
+                                error: 'internal: failed to serialize tool response',
+                            },
+                        }));
+                        this.sendResponse(nodeName, fallback);
+                    }
+                    catch {
+                        // Fallback also failed — best-effort; QAR's per-task
+                        // tool-response timeout is the safety net.
+                    }
+                }
+            }
+        }, () => {
+            // Connection closed (clean or via transport error). Drop our refs so
+            // a later `onRequest` (after a fresh `connect()`) re-attaches against
+            // the new connection instead of pointing at a dead one.
+            this.dispatcher = null;
+            this.dispatcherConnection = null;
+        }, 
+        // Per-call session lookup via the connection's `toolCallSessions`
+        // map — populated when the inbound `tool.request` landed, so it's
+        // guaranteed to be present here (the dispatcher only builds spans
+        // for envelopes it just absorbed).
+        (call, nodeName) => this.spanRecorder.startToolHandlerSpan({
+            sessionId: connection.getSessionForToolCall(call.tool_call_id),
+            toolCallId: call.tool_call_id,
+            toolName: call.name,
+            nodeName,
+        }), (err) => this.emitWireValidationError(err));
+        connection.subscribe(this.dispatcher);
+        this.dispatcherConnection = connection;
+    }
+    sendResponse(nodeName, responses, sessionOverride) {
+        const connection = this.resolveConnection();
+        const payload = {
+            node_name: nodeName,
+            responses: responses.map((r) => toResponseItem(r.tool_call_id, r.result)),
+        };
+        connection.sendEnvelope({ kind: 'tool.response', payload }, sessionOverride !== undefined ? { sessionId: sessionOverride } : undefined);
+    }
+    /**
+     * Snapshot whether the underlying connection is still open. Used by the
+     * dispatcher's send-fallback to distinguish "connection died" (give up) from
+     * "the payload itself was poisoned" (try a safe `status: 'error'`).
+     */
+    isConnectionLive() {
+        try {
+            return this.resolveConnection().isOpen;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Heuristic: a send failure is an internal serialization error (rather than
+     * a connection-level one) when the connection is live AND the batch we just
+     * tried to send wasn't already the safe internal-error fallback. Filtering
+     * on the fallback's own message stops a serialization-failed loop from
+     * looping.
+     */
+    isInternalSerializationError(_err, lastBatch) {
+        const alreadyFallback = lastBatch.every((r) => r.result.outcome === 'error' && r.result.error.startsWith('internal: '));
+        return !alreadyFallback;
+    }
+}
+/**
+ * The fan-out subscription: walks the handler stack for every `tool.request`,
+ * routes the first non-`undefined` handler-return (single result or array of
+ * results) to the connection.
+ *
+ * Handlers receive the full `ToolRequestEnvelope` (so they can read
+ * `node_name` and the entire `calls` list). The dispatcher itself doesn't
+ * claim the envelope (`consider` returns `false`) so task subscriptions still
+ * see `tool.request` on their `for await` stream if the consumer wants to
+ * observe both surfaces.
+ */
+class ToolRequestDispatcher {
+    handlers;
+    fallbackHandlers;
+    onResult;
+    onConnectionClosed;
+    buildHandlerSpan;
+    onWireValidationError;
+    constructor(handlers, 
+    /**
+     * SDK-side fallback handler stack (auto-bridges). Walked AFTER the
+     * primary {@link handlers} stack so consumer-registered `onRequest`
+     * handlers get first claim; the dispatcher's
+     * "zero-primary-handlers → deterministic deny" check is keyed off
+     * `handlers.length` only (independent of fallback presence) so
+     * consumer-side deny semantics aren't shadowed by SDK auto-bridges.
+     */
+    fallbackHandlers, onResult, onConnectionClosed, 
+    /**
+     * Span builder for the per-call inbound `tool.request` → handler invocation.
+     * Each dispatch opens one span per `ToolCall`; the dispatcher closes each
+     * with the matching per-call outcome before batching the responses.
+     */
+    buildHandlerSpan, 
+    /**
+     * Fired when an inbound `tool.request` is dropped because it violates
+     * the wire shape (empty `node_name` / empty `calls`). Lets the parent
+     * `ToolClient` route the typed error to its registered
+     * `onWireValidationError` observers AFTER the `[@qodo/sdk]` breadcrumb
+     * lands on `console.error`.
+     */
+    onWireValidationError) {
+        this.handlers = handlers;
+        this.fallbackHandlers = fallbackHandlers;
+        this.onResult = onResult;
+        this.onConnectionClosed = onConnectionClosed;
+        this.buildHandlerSpan = buildHandlerSpan;
+        this.onWireValidationError = onWireValidationError;
+    }
+    consider(env) {
+        if (env.kind !== 'tool.request')
+            return false;
+        // Fire-and-forget guard against unhandled promise rejections.
+        // `dispatch()` already wraps its body in a top-level try/catch and
+        // best-efforts a `denied` envelope per call via
+        // `emitContainedFailure`. The .catch() here only fires if THAT path
+        // also throws — e.g. a sync exception escapes before the inner try runs
+        // (buggy interceptor wrapping the async function), or
+        // `emitContainedFailure` itself throws past its own swallowing layer.
+        // Either way: log a single breadcrumb so the failure is observable in
+        // operator logs, then swallow. NEVER let this become a process-level
+        // `unhandledRejection`.
+        void this.dispatch(env).catch((err) => {
+            logUnhandledDispatchFailure(err, env.message_id);
+        });
+        // Don't claim — task subscriptions also surface tool.request on the
+        // iterator for consumers that want to observe the round-trip.
+        return false;
+    }
+    considerClient(_ev) {
+        // Tool dispatcher is wire-only — it doesn't yield client lifecycle
+        // events to anyone. The `qar.client.*` events surface on `TaskEvent`
+        // iterators and on `client.receive()` instead. Parameter kept (unused)
+        // to satisfy the `InboundSubscription` interface signature exactly.
+    }
+    fail(_err) {
+        // The connection layer reports the failure to every subscription. We
+        // hand it back to ToolClient via the close hook so future onRequest()
+        // calls re-attach against a fresh connection rather than the dead one.
+        this.onConnectionClosed();
+    }
+    close() {
+        this.onConnectionClosed();
+    }
+    async dispatch(env) {
+        // Top-level guard — anything from `buildHandlerSpan` throwing (buggy OTel
+        // tracer impl) to a handler throwing synchronously past the inner mapper
+        // lands here. The fire-and-forget caller in `consider()` would otherwise
+        // surface this as an unhandled promise rejection.
+        // Containment policy: best-effort emit a `denied`/`error` envelope per
+        // call so QAR's agent loop unblocks; if even that fails, swallow — the
+        // runtime's per-task tool-response timeout is the safety net.
+        try {
+            await this.dispatchInner(env);
+        }
+        catch (err) {
+            this.emitContainedFailure(env, err);
+        }
+    }
+    async dispatchInner(env) {
+        const { calls, node_name: nodeName } = env.payload;
+        // Inbound wire validation. An inbound envelope with empty
+        // `node_name` or empty `calls` can't be routed (no `tool_call_id` to
+        // respond against, no node to address). Throwing here would fail the
+        // connection across every subscription — far worse for a single
+        // malformed envelope. Log + drop, and let the runtime time out the call
+        // set on its end.
+        // Task subscriptions still observe the malformed envelope on their
+        // iterator, so consumers can also branch on `event.kind === 'tool.request'`
+        // and inspect `payload` if they need their own surface.
+        if (typeof nodeName !== 'string' || nodeName.length === 0) {
+            const violation = 'node_name is required and must be a non-empty string';
+            logWireValidationDrop({ violation, messageId: env.message_id });
+            this.fireWireValidationError(violation, env.message_id, undefined);
+            return;
+        }
+        if (!Array.isArray(calls) || calls.length === 0) {
+            const violation = 'calls must be a non-empty list';
+            logWireValidationDrop({ violation, messageId: env.message_id, nodeName });
+            this.fireWireValidationError(violation, env.message_id, nodeName);
+            return;
+        }
+        // Per-call spans (one per `ToolCall`). All share the same OTel parent —
+        // whatever context was active when the inbound envelope arrived. Spans
+        // close per-call with the matching outcome.
+        const spans = calls.map((c) => this.buildHandlerSpan(c, nodeName));
+        // `primaries.length === 0` is the consumer-side signal "no handler
+        // registered" (the dispatcher tracks consumer handlers separately
+        // from SDK auto-bridges). When no consumer registered a handler AND
+        // no SDK fallback claims, the dispatcher emits the deterministic
+        // deny envelope so QAR's agent loop unblocks.
+        const noPrimaryHandlers = this.handlers.length === 0;
+        if (noPrimaryHandlers && this.fallbackHandlers.length === 0) {
+            // Pre-fix behavior preserved verbatim for the "absolutely no
+            // handlers anywhere" case.
+            for (const s of spans)
+                this.finishHandlerSpan(s, 'denied');
+            const responses = calls.map((c) => ({
+                tool_call_id: c.tool_call_id,
+                result: { outcome: 'denied', error: 'no handler registered' },
+            }));
+            this.onResult(nodeName, responses);
+            return;
+        }
+        // Stage 1 — walk consumer-registered handlers. If any claims (returns
+        // non-undefined), we emit + return. Snapshot the stack so a handler
+        // unsubscribing itself mid-iterate doesn't break the walk.
+        const primaryResult = await this.walkHandlerStack([...this.handlers], env, calls, spans, nodeName);
+        if (primaryResult === 'claimed')
+            return;
+        // Stage 2 — walk SDK fallback handlers (auto-bridges).
+        const fallbackResult = await this.walkHandlerStack([...this.fallbackHandlers], env, calls, spans, nodeName);
+        if (fallbackResult === 'claimed')
+            return;
+        // Both stages exhausted with no claim. Two terminal cases:
+        //   (a) No consumer handlers existed → emit the deterministic deny
+        //       so QAR's agent loop unblocks. This is the post-fix semantic:
+        //       the SDK auto-bridges are advisory — they don't suppress the
+        //       deny that a zero-consumer-handlers config would otherwise
+        //       get.
+        //   (b) Consumer handlers existed but all returned undefined → defer
+        //       to manual `respond()`. The consumer's contract is "I'll
+        //       respond later"; QAR's per-task tool-response timeout is the
+        //       wire-side safety net.
+        if (noPrimaryHandlers) {
+            for (const s of spans)
+                this.finishHandlerSpan(s, 'denied');
+            const responses = calls.map((c) => ({
+                tool_call_id: c.tool_call_id,
+                result: { outcome: 'denied', error: 'no handler registered' },
+            }));
+            this.onResult(nodeName, responses);
+            return;
+        }
+        // Every handler returned undefined — defer to manual `respond()`. The
+        // handler spans end here with no outcome attribute; the manual respond
+        // path opens its own `qar.client.tool.respond` spans carrying the
+        // outcome. QAR enforces a per-tool-response timeout server-side; the
+        // SDK doesn't double-time-out here.
+        for (const s of spans)
+            s.succeed();
+    }
+    /**
+     * Walk an ordered handler stack once, returning `'claimed'` when any
+     * handler produces a non-`undefined` result (the dispatcher emits the
+     * response + returns to the caller), or `'all-undefined'` when every
+     * handler in the stack returned `undefined` (caller decides the next
+     * step — try fallbacks, deny, or defer).
+     *
+     * Centralizes the per-handler invocation + per-call response
+     * normalization + span outcome attribution so primary + fallback
+     * stacks share identical semantics.
+     */
+    async walkHandlerStack(snapshot, env, calls, spans, nodeName) {
+        for (const handler of snapshot) {
+            let raw;
+            try {
+                // Run the handler inside the FIRST span's context so any
+                // child spans the handler opens (e.g. wrapping its own work in
+                // `tracer.startActiveSpan`) parent under our
+                // `qar.client.tool.handler` — without this, the handler's spans
+                // would leaf back to whatever was active when the inbound
+                // `tool.request` arrived. For multi-call batches, the parent is
+                // calls[0]'s span; per-call attribution still lands via
+                // `qar.tool_call_id` on each sibling span.
+                raw = await spans[0].withContext(() => handler(env));
+            }
+            catch (err) {
+                // A handler-thrown exception applies to the whole batch — there's no
+                // per-call attribution available from the throw. Map it once and
+                // replicate across every call. `denied` (ToolDeniedError) is intent,
+                // not failure → succeed-with-attr; anything else is an error path.
+                const mapped = mapHandlerError(err);
+                const outcome = mapped.outcome;
+                for (const s of spans) {
+                    if (outcome === 'denied') {
+                        this.finishHandlerSpan(s, 'denied');
+                    }
+                    else {
+                        s.setAttribute(QAR_TOOL_OUTCOME, outcome);
+                        s.fail(err);
+                    }
+                }
+                const responses = calls.map((c) => ({
+                    tool_call_id: c.tool_call_id,
+                    result: mapped,
+                }));
+                this.onResult(nodeName, responses);
+                return 'claimed';
+            }
+            if (raw === undefined)
+                continue;
+            const normalized = this.normalizeHandlerReturn(raw, calls);
+            if (normalized === null) {
+                // Length mismatch / malformed — fail the whole batch, surface generic.
+                for (const s of spans) {
+                    s.setAttribute(QAR_TOOL_OUTCOME, 'error');
+                    s.fail(new Error('handler returned malformed ToolResponseResult batch'));
+                }
+                const fallback = calls.map((c) => ({
+                    tool_call_id: c.tool_call_id,
+                    result: {
+                        outcome: 'error',
+                        error: 'handler returned malformed ToolResponseResult batch',
+                    },
+                }));
+                this.onResult(nodeName, fallback);
+                return 'claimed';
+            }
+            const validated = [];
+            let anyMalformed = false;
+            normalized.forEach((result, idx) => {
+                if (!isValidToolResponseResult(result)) {
+                    anyMalformed = true;
+                    spans[idx].setAttribute(QAR_TOOL_OUTCOME, 'error');
+                    spans[idx].fail(new Error('handler returned malformed ToolResponseResult'));
+                    validated.push({
+                        tool_call_id: calls[idx].tool_call_id,
+                        result: {
+                            outcome: 'error',
+                            error: 'handler returned malformed ToolResponseResult',
+                        },
+                    });
+                    return;
+                }
+                this.finishHandlerSpan(spans[idx], toolOutcomeFor(result.outcome));
+                validated.push({ tool_call_id: calls[idx].tool_call_id, result });
+            });
+            void anyMalformed;
+            this.onResult(nodeName, validated);
+            return 'claimed';
+        }
+        return 'all-undefined';
+    }
+    /**
+     * Coerce the handler's return into a positional `ToolResponseResult[]`
+     * matching `calls`. Returns `null` on length mismatch / non-array, non-result
+     * shape — the caller emits a generic "malformed" batch.
+     */
+    normalizeHandlerReturn(raw, calls) {
+        if (Array.isArray(raw)) {
+            const arr = raw;
+            if (arr.length !== calls.length)
+                return null;
+            return arr;
+        }
+        // Single result — only valid when the request has exactly one call.
+        if (calls.length !== 1)
+            return null;
+        return [raw];
+    }
+    /**
+     * Close a handler span with the documented outcome attribute. `error`
+     * outcomes (handler returned `outcome: "error"`) are *not* span errors —
+     * the wire path succeeded; the tool itself reported failure. Span ERROR
+     * status is reserved for unhandled exceptions in the dispatch path.
+     */
+    finishHandlerSpan(span, outcome) {
+        span.setAttribute(QAR_TOOL_OUTCOME, outcome);
+        span.succeed();
+    }
+    /**
+     * Best-effort containment for an unexpected failure in `dispatchInner` —
+     * triggered when something outside the handler-error mapping path throws
+     * (most realistically: an OTel tracer impl throwing from `buildHandlerSpan`
+     * before the per-call try/catch can run). Emits a `denied` envelope per
+     * call so QAR's agent loop unblocks. Any further failure (e.g., the
+     * tracer is wedged AND the send fails too) is swallowed — the runtime's
+     * per-task tool-response timeout is the final safety net.
+     */
+    emitContainedFailure(env, _err) {
+        try {
+            const nodeName = env.payload?.node_name;
+            const calls = env.payload?.calls;
+            if (typeof nodeName !== 'string' ||
+                nodeName.length === 0 ||
+                !Array.isArray(calls) ||
+                calls.length === 0) {
+                return;
+            }
+            const responses = calls.map((c) => ({
+                tool_call_id: c.tool_call_id,
+                result: { outcome: 'denied', error: 'internal: dispatch failed' },
+            }));
+            this.onResult(nodeName, responses);
+        }
+        catch {
+            // Containment of the containment — swallow.
+        }
+    }
+    /**
+     * Build a `QodoWireValidationError` carrying structured drop metadata and
+     * hand it to the parent `ToolClient` for fan-out to registered
+     * `onWireValidationError` observers. Defensive: any failure inside the
+     * handler-fan-out path is swallowed by the parent, but a synchronous
+     * exception during error CONSTRUCTION (extremely unlikely) is also
+     * caught here so it can't escape the dispatch hot path.
+     */
+    fireWireValidationError(violation, messageId, nodeName) {
+        try {
+            const err = new QodoWireValidationError(`inbound tool.request envelope dropped: ${violation}`, { messageId, nodeName, scope: 'inbound' });
+            this.onWireValidationError(err);
+        }
+        catch {
+            // Even constructing the error / dispatching the observers wedged.
+            // The breadcrumb log already landed; that's the contract.
+        }
+    }
+}
+/**
+ * Map an exception thrown by a `ToolRequestHandler` to a `ToolResponseResult`.
+ * `ToolDeniedError` is the typed escape path (operator approval flow rejected,
+ * capability lookup denied) → `outcome: 'denied'`. Everything else maps to
+ * `outcome: 'error'` so the agent loop sees a generic failure rather than a
+ * silent denial. Truncation lives at the wire boundary (`toResponseItem`) so
+ * the cap applies uniformly to handler-thrown, handler-returned, and
+ * manual-respond paths.
+ */
+function mapHandlerError(err) {
+    if (err instanceof ToolDeniedError) {
+        return { outcome: 'denied', error: err.message };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return { outcome: 'error', error: message };
+}
+function truncate(s) {
+    if (s.length <= MAX_ERROR_LEN)
+        return s;
+    return `${s.slice(0, MAX_ERROR_LEN - 1)}…`;
+}
+/**
+ * Validate a `node_name` argument supplied at the outbound boundary. The wire
+ * requires a non-empty string; empty / non-string values produce a typed
+ * `QodoWireValidationError` so consumer bugs surface synchronously instead
+ * of as a malformed envelope.
+ */
+function validateNodeName(value, where) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new QodoWireValidationError(`${where}: node_name is required and must be a non-empty string.`);
+    }
+}
+/** Cap on individual field values rendered into the wire-validation breadcrumb. */
+const LOG_FIELD_MAX_LEN = 200;
+/**
+ * Emit a single diagnostic line when the dispatcher drops a malformed inbound
+ * `tool.request` envelope (empty `node_name` or empty `calls`). Without a
+ * signal, consumers have nothing to grep for when QAR's tool-loop times
+ * out and they need to diagnose protocol drift.
+ *
+ * Wire-provided fields (`nodeName`, `messageId`) are sanitized via
+ * `safeForLog` before interpolation — control characters in a malformed
+ * envelope would otherwise corrupt the log format and let an upstream
+ * bug (or hostile peer) forge fake breadcrumb lines. Each field is also
+ * clamped to `LOG_FIELD_MAX_LEN` so an attacker can't blow up the log
+ * line size.
+ *
+ * Logged at `console.error` because `console.warn` isn't part of the SDK's
+ * existing in-repo logging vocabulary (only `console.error` is used; see
+ * `src/client/observers.ts`). Wrapped defensively — a hostile or wedged
+ * `console` must never crash the dispatch hot path.
+ */
+function logWireValidationDrop(fields) {
+    try {
+        // `violation` is SDK-authored static prose, never wire-derived — no need
+        // to sanitize. `messageId` and `nodeName` come from the inbound envelope
+        // and MUST be sanitized.
+        const parts = [
+            `[@qodo/sdk] tool.request envelope dropped: ${fields.violation}`,
+            `message_id=${safeForLog(fields.messageId)}`,
+        ];
+        if (fields.nodeName !== undefined) {
+            parts.push(`node_name=${safeForLog(fields.nodeName)}`);
+        }
+        // eslint-disable-next-line no-console
+        console.error(parts.join(' '));
+    }
+    catch {
+        // Console itself is wedged — give up; the wire path is the contract.
+    }
+}
+/**
+ * Logged when an observer registered via `onWireValidationError(handler)`
+ * itself throws. Mirrors the swallow-and-surface pattern in
+ * `KindObserverPort.logHandlerError` (`src/client/observers.ts`) so the same
+ * "[@qodo/sdk]" breadcrumb vocabulary covers every consumer-handler failure.
+ */
+// `isThenable` lives in `./internal/thenable.ts` so this module and
+// `observers.ts` share one canonical implementation — a local copy here
+// missing the `typeof === 'function'` arm would let callable thenables
+// escape the async-containment path.
+function logHandlerObserverError(surface, err) {
+    try {
+        const msg = err instanceof Error ? err.message : String(err);
+        // eslint-disable-next-line no-console
+        console.error(`[@qodo/sdk] ${surface} handler threw — swallowed: ${safeForLog(msg)}`);
+    }
+    catch {
+        try {
+            // eslint-disable-next-line no-console
+            console.error(`[@qodo/sdk] ${surface} handler threw — swallowed (logger error)`);
+        }
+        catch {
+            // Console fully wedged — drop.
+        }
+    }
+}
+function logUnhandledDispatchFailure(err, messageId) {
+    try {
+        const message = err instanceof Error ? err.message : String(err);
+        // eslint-disable-next-line no-console
+        console.error(`[@qodo/sdk] tool.request dispatch failed past containment: ${safeForLog(message)} ` +
+            `message_id=${safeForLog(messageId)}`);
+    }
+    catch {
+        // Even the breadcrumb is wedged. Drop silently — the priority is keeping
+        // the dispatch hot path alive.
+    }
+}
+/**
+ * Render a wire-provided value into a single log-safe token. Replaces
+ * control characters (newlines, tabs, carriage returns, NULs, every C0/C1
+ * range) with their `\xNN` / `\uNNNN` escapes, wraps the result in quotes,
+ * and clamps to `LOG_FIELD_MAX_LEN` so a single malformed field can't
+ * dominate the log line. Non-string values fall back to `JSON.stringify`
+ * (defensive — TS callers always pass strings, but inbound envelopes are
+ * runtime-untrusted).
+ */
+function safeForLog(value) {
+    let s;
+    if (typeof value === 'string') {
+        s = value;
+    }
+    else {
+        try {
+            s = JSON.stringify(value);
+        }
+        catch {
+            s = String(value);
+        }
+    }
+    // Escape:
+    //   - ASCII C0 control chars (0x00-0x1F, 0x7F) and the C1 range (0x80-0x9F)
+    //     — any of these can break grep, terminal output, or log aggregators.
+    //   - U+2028 / U+2029 — Unicode line/paragraph separators; some log parsers
+    //     (and some V8 versions' `JSON.stringify`) treat them as newlines.
+    //   - U+202A–U+202E + U+2066–U+2069 — Unicode bidi overrides (LRE/RLE/PDF/
+    //     LRO/RLO + FSI/PDI family). Without escaping these, a hostile node_name
+    //     can right-to-left-flip part of the log line so tampering visually
+    //     looks like a legitimate field.
+    //   - U+2060 (Word Joiner) + U+FEFF (BOM / ZWNBSP) — invisible format chars
+    //     that defeat grep-based debugging by inserting zero-width separators.
+    // Ordinary printable Unicode is left intact so non-ASCII node names still
+    // render readably.
+    s = s.replace(/[\x00-\x1f\x7f-\x9f\u2028\u2029\u202a-\u202e\u2066-\u2069\u2060\ufeff]/g, (c) => {
+        const code = c.charCodeAt(0);
+        return code <= 0xff
+            ? `\\x${code.toString(16).padStart(2, '0')}`
+            : `\\u${code.toString(16).padStart(4, '0')}`;
+    });
+    if (s.length > LOG_FIELD_MAX_LEN) {
+        s = `${s.slice(0, LOG_FIELD_MAX_LEN - 1)}…`;
+    }
+    return JSON.stringify(s);
+}
+/**
+ * Runtime guard for the SDK-side `ToolResponseResult` discriminated union.
+ *
+ * The wire shape is the flat `ToolResponseItem` (`status` + optional `result`
+ * / `error`); the SDK convenience union narrows that. Validating here means a
+ * buggy handler can't ship a malformed envelope onto the wire.
+ */
+function isValidToolResponseResult(x) {
+    if (typeof x !== 'object' || x === null)
+        return false;
+    const r = x;
+    switch (r.outcome) {
+        case 'success':
+            // Recursive JSON-shape check (catches cycles + non-JSON primitives like
+            // BigInt, Symbol, function, NaN/Infinity, undefined). Without this the
+            // wire-side `JSON.stringify` would either throw (cycle) or silently
+            // drop fields (non-JSON primitives).
+            return isJsonObject(r.result);
+        case 'error':
+            return typeof r.error === 'string';
+        case 'denied':
+            return r.error === undefined || typeof r.error === 'string';
+        default:
+            return false;
+    }
+}
+/**
+ * Recursive JSON-object validator with cycle detection. Mirrors the
+ * `JsonObject` / `JsonValue` shapes in `src/qar/json.ts`.
+ *
+ *   - rejects arrays (a top-level `result` must be a JSON object, not array);
+ *   - rejects `BigInt`, `Symbol`, `function`, `undefined` values;
+ *   - rejects non-finite numbers (`NaN`, `Infinity`) — these become `null`
+ *     under `JSON.stringify` which silently corrupts the result on the wire;
+ *   - tracks visited objects in a `WeakSet` so a cyclic payload returns
+ *     `false` instead of triggering the recursion bomb at serialize time.
+ */
+function isJsonObject(x, seen = new WeakSet()) {
+    if (typeof x !== 'object' || x === null || Array.isArray(x))
+        return false;
+    if (seen.has(x))
+        return false;
+    seen.add(x);
+    for (const value of Object.values(x)) {
+        if (!isJsonValue(value, seen))
+            return false;
+    }
+    return true;
+}
+function isJsonValue(x, seen) {
+    if (x === null)
+        return true;
+    switch (typeof x) {
+        case 'string':
+        case 'boolean':
+            return true;
+        case 'number':
+            return Number.isFinite(x);
+        case 'object': {
+            if (Array.isArray(x)) {
+                if (seen.has(x))
+                    return false;
+                seen.add(x);
+                return x.every((item) => isJsonValue(item, seen));
+            }
+            return isJsonObject(x, seen);
+        }
+        default:
+            // 'bigint', 'symbol', 'function', 'undefined' → not JSON-representable.
+            return false;
+    }
+}
+/**
+ * Translate one SDK-side `ToolResponseResult` into the flat wire item.
+ *
+ * Wire-faithful mapping:
+ *
+ *   - `success` → `status: 'ok'`, `result` carried as-is.
+ *   - `error`   → `status: 'error'`, `error: { code: 'error', message }`.
+ *   - `denied`  → `status: 'error'`, `error: { code: 'denied', message? }`.
+ *
+ * `denied` collapses to wire `status: 'error'` with a distinct `error.code` so
+ * QAR's tool-loop telemetry can still distinguish policy rejection from
+ * generic failure. Truncation happens HERE (not in callers) so every outbound
+ * error/denied envelope is bounded — handler-thrown, handler-returned, and
+ * `respond()` paths all go through this single seam.
+ */
+function toResponseItem(toolCallId, result) {
+    switch (result.outcome) {
+        case 'success':
+            return {
+                tool_call_id: toolCallId,
+                status: 'ok',
+                result: result.result,
+            };
+        case 'error':
+            return {
+                tool_call_id: toolCallId,
+                status: 'error',
+                error: { code: 'error', message: truncate(result.error) },
+            };
+        case 'denied':
+            return {
+                tool_call_id: toolCallId,
+                status: 'error',
+                error: {
+                    code: 'denied',
+                    message: result.error !== undefined ? truncate(result.error) : 'denied',
+                },
+            };
+    }
+}
+//# sourceMappingURL=ToolClient.js.map