@qodo/sdk 0.13.4 → 2.0.0-next.0

package/dist/client/tools/approval.js

@@ -0,0 +1,229 @@
+/**
+ * `requireApproval` — ergonomic HITL shorthand on `defineFunctionTool`
+ * (S4). Closes the gap identified by the 2026-05-21 ADK comparison
+ * (see `docs/sdk2/research/2026-05-21-google-adk-vs-qodo-ts-sdk.md`,
+ * Opportunity 5 — ADK's `FunctionTool(my_fn, require_confirmation=True)`
+ * is one line; qodo-ts-sdk's pre-S4 surface required ~10 lines across
+ * annotations + name-based gate + `onRequest` resolution).
+ *
+ * The flag composes onto the existing three-layer HITL model documented
+ * in `docs/sdk2/concepts/03-hitl.md`:
+ *
+ *   - **Layer 1 (instruction).** `defineFunctionTool({ description })`
+ *     already shapes the LLM's choice to call the tool. The optional
+ *     `prompt` on `ApprovalConfig` becomes the human-facing prompt at
+ *     resolution time — not an instruction to the model.
+ *   - **Layer 2 (schema).** QAR currently owns `HITLBlock` synthesis on
+ *     the wire (name-based, server-side, deployment-driven). S4 does
+ *     NOT attempt to push a synthetic `HITLBlock` onto QAR's
+ *     `tool.request` envelope; doing so would require a wire-side ADR
+ *     and a QAR change. Instead, S4 synthesizes the equivalent
+ *     decision-making flow SDK-side at dispatch time.
+ *   - **Layer 3 (trust-tier gate).** The actual gate moves into the SDK
+ *     for tools the consumer marked with `requireApproval`. Before the
+ *     handler runs, the router asks the consumer's
+ *     `ApprovalHandler` to approve / deny. Approve → handler invoked
+ *     with the parsed Zod args. Deny → `outcome: 'denied'` returned to
+ *     the LLM. Denial is a recoverable error (not a pipeline-fatal one);
+ *     the agent loop sees the rejection as a normal tool-result and can
+ *     decide whether to retry, ask the user, or give up.
+ *
+ * Annotation passthrough is **advisory**, not the gate. The MCP spec
+ * explicitly tags `Tool.annotations` as untrusted (see
+ * `docs/sdk2/concepts/03-hitl.md` § Dynamic HITL); the runtime's
+ * name-based policy is what holds when an MCP misbehaves. S4 still
+ * merges `sensitivity`-driven hints (`destructiveHint`, `openWorldHint`)
+ * onto the produced `FunctionToolDef.function.annotations` so downstream
+ * observability (OTel span attrs, Shape C dynamic filters reading
+ * `annotations.destructiveHint`) can see them — but the consumer-side
+ * approval flow IS the SDK-level gate.
+ */
+import { readlineApprovalPrompt } from './_readlineApprovalPrompt.js';
+import { ToolDeniedError } from '../errors.js';
+/**
+ * Default approval handler. Behavior:
+ *
+ *   - If `process.stdin.isTTY` (interactive Node CLI) — prompt via
+ *     `readline` with a yes/no question. `y` / `yes` → approve;
+ *     anything else → deny. Useful for tutorials, scripts,
+ *     `examples/usecases/*`.
+ *   - Otherwise (non-TTY, daemon, web worker, browser bundle, CI) —
+ *     deterministically deny with a typed error message so the
+ *     consumer's stack trace points at the missing
+ *     `setApprovalHandler` registration instead of getting a
+ *     mysterious "tool denied" from QAR. Auto-approving in
+ *     non-interactive contexts would silently defeat the gate — the
+ *     wrong default for an approval surface.
+ *
+ * Override via `client.tools.setApprovalHandler(fn)`. Production
+ * apps that route approvals to Slack / a web UI / a pager should
+ * register an explicit handler at startup; the default is the
+ * "I have an stdin" fallback for the simplest cases.
+ *
+ * **Concurrency.** `FunctionToolRouter.dispatch` fires per-call
+ * handlers via `Promise.all`. Multiple `requireApproval`-gated
+ * calls in one `tool.request` batch would otherwise open multiple
+ * readline interfaces on the same `process.stdin` and interleave —
+ * see {@link readlineApprovalPrompt} for the module-level
+ * promise-chain mutex that serializes the default stdin prompts
+ * (regression test in `tests/require-approval.test.ts`
+ * § readlineApprovalPrompt mutex).
+ * Consumer-override handlers (Slack, web UI) don't share stdin and
+ * stay parallel by design — serializing them would hurt batch
+ * latency in production.
+ */
+export const defaultApprovalHandler = (req) => readlineApprovalPrompt(req.toolName, req.prompt);
+/**
+ * Build the human-facing prompt for an approval request. Falls back
+ * to a canned `"Approve <tool>(<args>)?"` shape when the consumer
+ * didn't set `config.prompt`. Arguments are JSON-stringified with a
+ * 256-char cap so a giant args bag doesn't drown the prompt.
+ */
+function buildPrompt(toolName, config, call, parsedArguments) {
+    if (typeof config.prompt === 'string' && config.prompt.length > 0) {
+        return config.prompt;
+    }
+    // Prefer parsed args when available — the approver should see the
+    // same canonical bag the function-tool handler will actually
+    // receive (defaults applied, transforms run). Fall back to the raw
+    // wire args only when parsing didn't happen (resolveApproval
+    // invoked outside the router; unit-test paths).
+    const argsForPrompt = parsedArguments ?? call.arguments;
+    let argsRender;
+    try {
+        argsRender = JSON.stringify(argsForPrompt);
+    }
+    catch {
+        argsRender = '<unserializable args>';
+    }
+    if (argsRender.length > 256) {
+        argsRender = `${argsRender.slice(0, 253)}...`;
+    }
+    return `Approve ${toolName}(${argsRender})?`;
+}
+/**
+ * Resolve an approval request against the supplied handler. Maps
+ * thrown errors (handler bugs, denial-by-throw) to the wire
+ * `ToolResponseResult` shape:
+ *
+ *   - Handler returns `{ decision: 'approve' }` → returns the
+ *     {@link ApprovalDecision} so the caller can pass through the
+ *     optional `input` / `selection` payload to the function-tool
+ *     handler.
+ *   - Handler returns `{ decision: 'deny' }` → returns the
+ *     pre-formatted `{ outcome: 'denied' }` response item. The
+ *     caller MUST NOT invoke the function-tool handler.
+ *   - Handler throws `ToolDeniedError` → mapped to `outcome: 'denied'`.
+ *   - Handler throws any other Error → mapped to `outcome: 'error'`
+ *     with the error message (capped by the dispatcher's existing
+ *     `MAX_ERROR_LEN` boundary).
+ *
+ * The two-arm return shape (`'approve' | { outcome: 'denied' | 'error' }`)
+ * lets the caller skip the function-tool handler invocation entirely
+ * on rejection — no need for an `if (decision === 'deny')` follow-up
+ * branch.
+ */
+export async function resolveApproval(handler, toolName, config, call, nodeName, parsedArguments) {
+    const req = {
+        toolName,
+        config,
+        call,
+        nodeName,
+        prompt: buildPrompt(toolName, config, call, parsedArguments),
+        ...(parsedArguments !== undefined ? { parsedArguments } : {}),
+    };
+    let raw;
+    try {
+        raw = await handler(req);
+    }
+    catch (err) {
+        if (err instanceof ToolDeniedError) {
+            return { _denial: { outcome: 'denied', error: err.message } };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return { _denial: { outcome: 'error', error: message } };
+    }
+    // Guard the handler's return shape. A malformed return (undefined,
+    // null, missing `decision`, wrong discriminator) used to throw
+    // when we read `decision.decision` outside the try/catch, which
+    // escaped resolveApproval AND escaped runOne — tanking the entire
+    // batch as a router-dispatch exception. The contract is "every
+    // approval outcome maps to a per-call ToolResponseResult", so a
+    // malformed return surfaces as `outcome: 'error'` for THIS call
+    // and the rest of the batch proceeds normally.
+    if (raw === null || typeof raw !== 'object') {
+        return {
+            _denial: {
+                outcome: 'error',
+                error: `ApprovalHandler(${toolName}) returned a non-object value — expected ApprovalDecision`,
+            },
+        };
+    }
+    const decisionField = raw.decision;
+    if (decisionField !== 'approve' && decisionField !== 'deny') {
+        return {
+            _denial: {
+                outcome: 'error',
+                error: `ApprovalHandler(${toolName}) returned a malformed ApprovalDecision ` +
+                    `— expected \`decision: 'approve' | 'deny'\`, got ${JSON.stringify(decisionField)}`,
+            },
+        };
+    }
+    const decision = raw;
+    if (decision.decision === 'deny') {
+        return {
+            _denial: {
+                outcome: 'denied',
+                error: decision.reason ?? `approval denied for ${toolName}`,
+            },
+        };
+    }
+    return decision;
+}
+/**
+ * Merge the consumer-supplied `annotations` (if any) with the
+ * sensitivity-driven advisory overlay. Consumer values WIN on
+ * collision — `requireApproval` is a shorthand, not a forced
+ * override. Set sensitivity to opt into the overlay; leave
+ * `annotations` undefined to accept it verbatim.
+ *
+ * Returns `undefined` when neither side contributes a field
+ * (so the produced `FunctionToolDef` stays free of an empty
+ * `annotations: {}` object — every wire byte counts).
+ */
+export function mergeApprovalAnnotations(base, config) {
+    // Build the overlay as a plain mutable record so the `readonly`
+    // contract on `McpToolAnnotations` stays honored at the type
+    // boundary. We freeze the merged result indirectly via the spread
+    // — consumers see an immutable shape.
+    const overlay = {};
+    if (config.sensitivity === 'pii' || config.sensitivity === 'secret') {
+        overlay.destructiveHint = true;
+    }
+    if (config.sensitivity === 'secret') {
+        overlay.openWorldHint = true;
+    }
+    if (Object.keys(overlay).length === 0 && base === undefined) {
+        return undefined;
+    }
+    // Consumer-supplied annotations WIN — the overlay only fills gaps.
+    return { ...overlay, ...(base ?? {}) };
+}
+/**
+ * Normalize the consumer-facing `requireApproval` value into the
+ * internal {@link ApprovalConfig} shape. `true` → `{ kind:
+ * 'approval', sensitivity: 'low' }`; an explicit
+ * {@link ApprovalConfig} is returned as-is; `false` / `undefined`
+ * returns `undefined` (gate disabled).
+ *
+ * Centralizing the normalization here keeps `defineFunctionTool` and
+ * the router from re-implementing the boolean → object widening.
+ */
+export function normalizeApprovalConfig(value) {
+    if (value === undefined || value === false)
+        return undefined;
+    if (value === true)
+        return { kind: 'approval', sensitivity: 'low' };
+    return value;
+}
+//# sourceMappingURL=approval.js.map

package/dist/client/tools/approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.js","sourceRoot":"","sources":["../../../src/client/tools/approval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AA0K/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAoB,CAAC,GAAG,EAAE,EAAE,CAC7D,sBAAsB,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,SAAS,WAAW,CAClB,QAAgB,EAChB,MAAsB,EACtB,IAAc,EACd,eAAuC;IAEvC,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClE,OAAO,MAAM,CAAC,MAAM,CAAC;IACvB,CAAC;IACD,kEAAkE;IAClE,6DAA6D;IAC7D,mEAAmE;IACnE,6DAA6D;IAC7D,gDAAgD;IAChD,MAAM,aAAa,GAAY,eAAe,IAAI,IAAI,CAAC,SAAS,CAAC;IACjE,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,UAAU,GAAG,uBAAuB,CAAC;IACvC,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QAC5B,UAAU,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC;IAChD,CAAC;IACD,OAAO,WAAW,QAAQ,IAAI,UAAU,IAAI,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAwB,EACxB,QAAgB,EAChB,MAAsB,EACtB,IAAc,EACd,QAAgB,EAChB,eAA4B;IAE5B,MAAM,GAAG,GAAoB;QAC3B,QAAQ;QACR,MAAM;QACN,IAAI;QACJ,QAAQ;QACR,MAAM,EAAE,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,CAAC;QAC5D,GAAG,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9D,CAAC;IACF,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,eAAe,EAAE,CAAC;YACnC,OAAO,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;QAChE,CAAC;QACD,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC;IAC3D,CAAC;IACD,mEAAmE;IACnE,+DAA+D;IAC/D,gEAAgE;IAChE,kEAAkE;IAClE,+DAA+D;IAC/D,gEAAgE;IAChE,gEAAgE;IAChE,+CAA+C;IAC/C,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5C,OAAO;YACL,OAAO,EAAE;gBACP,OAAO,EAAE,OAAO;gBAChB,KAAK,EAAE,mBAAmB,QAAQ,2DAA2D;aAC9F;SACF,CAAC;IACJ,CAAC;IACD,MAAM,aAAa,GAAI,GAAuC,CAAC,QAAQ,CAAC;IACxE,IAAI,aAAa,KAAK,SAAS,IAAI,aAAa,KAAK,MAAM,EAAE,CAAC;QAC5D,OAAO;YACL,OAAO,EAAE;gBACP,OAAO,EAAE,OAAO;gBAChB,KAAK,EACH,mBAAmB,QAAQ,0CAA0C;oBACrE,oDAAoD,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,EAAE;aACtF;SACF,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,GAAuB,CAAC;IACzC,IAAI,QAAQ,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;QACjC,OAAO;YACL,OAAO,EAAE;gBACP,OAAO,EAAE,QAAQ;gBACjB,KAAK,EAAE,QAAQ,CAAC,MAAM,IAAI,uBAAuB,QAAQ,EAAE;aAC5D;SACF,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB,CACtC,IAAoC,EACpC,MAAsB;IAEtB,gEAAgE;IAChE,6DAA6D;IAC7D,kEAAkE;IAClE,sCAAsC;IACtC,MAAM,OAAO,GAGT,EAAE,CAAC;IACP,IAAI,MAAM,CAAC,WAAW,KAAK,KAAK,IAAI,MAAM,CAAC,WAAW,KAAK,QAAQ,EAAE,CAAC;QACpE,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IACjC,CAAC;IACD,IAAI,MAAM,CAAC,WAAW,KAAK,QAAQ,EAAE,CAAC;QACpC,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAC/B,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5D,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,mEAAmE;IACnE,OAAO,EAAE,GAAG,OAAO,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC;AACzC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAA2C;IAE3C,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7D,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;IACpE,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/client/tools/bindFunctionToolDefs.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Bind step — walks `agent.tools[]` (or every agent's `tools[]` in a
+ * graph) at `tasks.startWithAgent` / `tasks.startWithGraph` time,
+ * extracts any `defineFunctionTool` handler bags, and installs a single
+ * primary `onRequest` handler on the supplied `ToolClient` that
+ * dispatches inbound `tool.request` calls by `name` to the right
+ * handler.
+ *
+ * Idempotency: calling the bind step repeatedly with the same tools is
+ * cheap — the underlying handler-table is a Map keyed by tool name, so
+ * re-binding overrides in-place. The single `onRequest` subscription
+ * is attached lazily the first time any handler is registered and
+ * stays attached for the lifetime of the client; subsequent task
+ * starts only mutate the table.
+ *
+ * Attachment mode — **fallback, not primary**. The router installs via
+ * `ToolClient._attachFallbackHandler(...)`, not the public
+ * `onRequest(...)`. Two reasons:
+ *
+ *   1. **Deterministic-deny preservation.** The dispatcher's
+ *      "zero-primary-handlers → emit denied" path keys off
+ *      `this.handlers.length === 0`. Installing the router as a
+ *      primary handler would defeat that fallback whenever the
+ *      consumer hadn't also registered a manual `onRequest` —
+ *      a batch with an unregistered tool name would return
+ *      `undefined` from our router and then nobody would claim it,
+ *      leaving QAR's agent loop stalled until the per-task tool-response
+ *      timeout. As a fallback handler, our router runs AFTER the
+ *      primary stack but does NOT count toward the
+ *      no-primaries check, so unrecognized batches still get the
+ *      deterministic deny.
+ *   2. **Consumer-explicit beats SDK-helper.** When a consumer
+ *      registers a manual `onRequest` for tool name "X" AND defines
+ *      `defineFunctionTool({ name: 'X' })`, the consumer's explicit
+ *      handler wins — the primary stack always runs first.
+ *
+ * Dispatch policy:
+ *
+ *   - If every call name in the inbound batch matches a registered
+ *     function-tool handler, the router claims the batch and returns
+ *     the positional result array. Each handler runs in isolation;
+ *     per-call exceptions are mapped to per-call
+ *     `outcome: 'error'` / `outcome: 'denied'` (the latter when the
+ *     handler throws `ToolDeniedError`).
+ *   - If ANY call in the batch has a name NOT in the table, the
+ *     router returns `undefined`. With no other fallback claiming
+ *     AND no primary handler, the dispatcher's deny path fires for
+ *     the whole batch. With a primary handler present, the dispatcher
+ *     defers (per the documented "consumer will respond later"
+ *     semantics — primary handlers already ran first).
+ *
+ * Argument parsing: the router invokes `bag.parameters.safeParse(...)`
+ * on `call.arguments` before invoking the handler. Successful parse
+ * yields the typed output (defaults applied, transforms run);
+ * failures map to a per-call `outcome: 'error'` with the formatted
+ * Zod issue list. This matches the type contract — `handler: (args:
+ * z.infer<TSchema>) => ...` promises the OUTPUT type, not the wire
+ * INPUT type — and gives consumers the DX they expect from a Zod-
+ * derived helper.
+ */
+import type { ToolClient } from '../ToolClient.js';
+import type { FunctionToolDef } from '../../qar/specs.js';
+/**
+ * Per-client registry of `defineFunctionTool` handlers. One instance
+ * per `QodoClient`; shared across every `tasks.startWith*` call so the
+ * same handler stays installed even as the consumer dispatches multiple
+ * tasks.
+ *
+ * Exposed as a class (not a module-level Map) so each client gets an
+ * isolated table — multi-client test harnesses don't see cross-talk.
+ */
+export declare class FunctionToolRouter {
+    private readonly bags;
+    private subscription;
+    /**
+     * Resolver invoked when a `requireApproval`-gated tool is about to
+     * dispatch. Owned by the parent `ToolClient` (consumer registers via
+     * `client.tools.setApprovalHandler(...)`); the router holds a
+     * getter so an override registered AFTER `attach()` still applies
+     * to subsequent inbound batches.
+     */
+    private getApprovalHandler;
+    /**
+     * Predicate read by {@link runOne} AFTER an approval resolves
+     * `approve` and BEFORE the function-tool handler is invoked. When
+     * the wire has died during the approval round-trip (auto-reconnect
+     * exhausted, `failHardAndCleanup` ran, or an explicit
+     * `client.disconnect()` raced the resolver), this returns `false`
+     * and the router synthesizes a per-call
+     * `outcome: 'error'` — the handler does NOT execute, so no
+     * real-world side effect occurs that we wouldn't be able to
+     * acknowledge on the wire.
+     *
+     * Defaulted to a permissive `true` so the router stays
+     * functionally identical before `attach()` (unit tests construct
+     * the router directly + drive `dispatch` without ever calling
+     * `attach`).
+     */
+    private isConnectionLive;
+    /**
+     * Register every `defineFunctionTool`-produced entry in `tools` with
+     * the router. Hand-authored `FunctionToolDef` literals (no symbol
+     * handler attached) are skipped. Returns the number of newly
+     * registered names — useful for tests + breadcrumb logging.
+     *
+     * If `tools` is empty / `null` / `undefined`, the router is left
+     * alone — no auto-attach, no error.
+     */
+    register(tools: readonly FunctionToolDef[] | null | undefined): number;
+    /**
+     * Lazy attach. The single fallback handler is registered the first
+     * time the router is asked to attach against a `ToolClient`; later
+     * calls are no-ops as long as the subscription remains live. The
+     * router does NOT auto-detach on `client.disconnect()` — re-binding
+     * after reconnect is the consumer's responsibility (the existing
+     * subscription becomes stale; the dispatcher's own `attachDispatcher`
+     * handles re-attachment).
+     *
+     * Attaches via `_attachFallbackHandler` so the dispatcher's
+     * deterministic-deny path stays intact for unregistered tool names
+     * (see the module header for rationale).
+     */
+    attach(client: ToolClient): void;
+    /**
+     * Detach the underlying `onRequest` subscription. Used in tests + by
+     * `QodoClient.disconnect()` so a client teardown cleanly drops the
+     * router-installed handler.
+     */
+    detach(): void;
+    /**
+     * The actual dispatch handler — wired as the body of the single
+     * `onRequest` subscription.
+     *
+     * Returns `undefined` (fall-through) when:
+     *
+     *   - The router has no handlers registered (rare — only if `attach`
+     *     was called before any `register`).
+     *   - Any call in the inbound batch has a name not in the table —
+     *     defers to the next handler so mixed surfaces still work.
+     *
+     * Otherwise, invokes every handler in parallel
+     * (`Promise.all([...])`) and returns the positional result array.
+     * Exceptions per-handler are mapped to per-call response shapes.
+     */
+    private dispatch;
+    /**
+     * Invoke a single handler. Catches throws and maps them to a
+     * per-call `ToolResponseResult`. `ToolDeniedError` becomes `outcome:
+     * 'denied'`; everything else becomes `outcome: 'error'`. Mirrors the
+     * mapping logic in `ToolClient.dispatchInner` so consumers see the
+     * same semantics whether they use `defineFunctionTool` or the manual
+     * `onRequest` surface.
+     */
+    private runOne;
+}
+//# sourceMappingURL=bindFunctionToolDefs.d.ts.map

package/dist/client/tools/bindFunctionToolDefs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindFunctionToolDefs.d.ts","sourceRoot":"","sources":["../../../src/client/tools/bindFunctionToolDefs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAcH,OAAO,KAAK,EAAE,UAAU,EAAsB,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAO1D;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6C;IAClE,OAAO,CAAC,YAAY,CAAwC;IAC5D;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB,CAOxB;IAEF;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,gBAAgB,CAA6B;IAErD;;;;;;;;OAQG;IACI,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM;IAe7E;;;;;;;;;;;;OAYG;IACI,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAiBvC;;;;OAIG;IACI,MAAM,IAAI,IAAI;IAuBrB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,QAAQ,CAed;IAEF;;;;;;;OAOG;YACW,MAAM;CA8HrB"}