@qodo/sdk 0.13.3 → 2.0.0-next.0

package/dist/client/options.js

@@ -0,0 +1,9 @@
+/**
+ * Construction options for `QodoClient` and friends.
+ *
+ * Strict — no `any` at the public surface. Optional fields that may grow over
+ * time (e.g. `headers`, `transport`) carry an index-signature-free interface so
+ * adding a key is a SemVer-additive change rather than a silent extension.
+ */
+export {};
+//# sourceMappingURL=options.js.map

package/dist/client/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/client/options.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/client/tools/_readlineApprovalPrompt.browser.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Browser stub for {@link readlineApprovalPrompt}. The Node version
+ * imports `readline` to drive an interactive stdin prompt; in the
+ * browser the import is a hard error at bundle time. This stub
+ * always deterministic-denies — there is no meaningful "default
+ * approval flow" in a browser bundle; the consumer MUST register an
+ * explicit `ApprovalHandler` via
+ * `client.tools.setApprovalHandler(...)`.
+ *
+ * Wired via `package.json#browser` (per the existing pattern
+ * established by `transport.browser.ts` /
+ * `resolveOTel.browser.ts`); module-resolution swap is automatic at
+ * bundle time.
+ */
+import type { ApprovalDecision } from './approval.js';
+export declare function readlineApprovalPrompt(toolName: string, _prompt: string): Promise<ApprovalDecision>;
+//# sourceMappingURL=_readlineApprovalPrompt.browser.d.ts.map

package/dist/client/tools/_readlineApprovalPrompt.browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_readlineApprovalPrompt.browser.d.ts","sourceRoot":"","sources":["../../../src/client/tools/_readlineApprovalPrompt.browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,CAAC,CAS3B"}

package/dist/client/tools/_readlineApprovalPrompt.browser.js

@@ -0,0 +1,24 @@
+/**
+ * Browser stub for {@link readlineApprovalPrompt}. The Node version
+ * imports `readline` to drive an interactive stdin prompt; in the
+ * browser the import is a hard error at bundle time. This stub
+ * always deterministic-denies — there is no meaningful "default
+ * approval flow" in a browser bundle; the consumer MUST register an
+ * explicit `ApprovalHandler` via
+ * `client.tools.setApprovalHandler(...)`.
+ *
+ * Wired via `package.json#browser` (per the existing pattern
+ * established by `transport.browser.ts` /
+ * `resolveOTel.browser.ts`); module-resolution swap is automatic at
+ * bundle time.
+ */
+export async function readlineApprovalPrompt(toolName, _prompt) {
+    return {
+        decision: 'deny',
+        reason: `defineFunctionTool(${toolName}): no \`ApprovalHandler\` registered in browser ` +
+            'context — register one with `client.tools.setApprovalHandler(...)` before ' +
+            'dispatching a task that uses requireApproval-gated tools. Browser bundles have ' +
+            'no stdin to default to; deterministic-deny keeps the approval surface safe.',
+    };
+}
+//# sourceMappingURL=_readlineApprovalPrompt.browser.js.map

package/dist/client/tools/_readlineApprovalPrompt.browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_readlineApprovalPrompt.browser.js","sourceRoot":"","sources":["../../../src/client/tools/_readlineApprovalPrompt.browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,QAAgB,EAChB,OAAe;IAEf,OAAO;QACL,QAAQ,EAAE,MAAM;QAChB,MAAM,EACJ,sBAAsB,QAAQ,kDAAkD;YAChF,4EAA4E;YAC5E,iFAAiF;YACjF,6EAA6E;KAChF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,33 @@
+/**
+ * Node-only readline prompt for the default approval handler. Lives
+ * in its own file so the browser bundle can swap it for a stub via
+ * package.json's `"browser"` field (mirroring the existing
+ * `transport.browser.ts` / `manager.browser.ts` pattern). Keeping
+ * the `readline` import in this file means the rest of
+ * `approval.ts` — types, normalization, annotation merging,
+ * `resolveApproval` — stays bundler-safe.
+ *
+ * The Node version reads `process.stdin` when `isTTY` is true and
+ * deterministic-denies otherwise. The browser stub
+ * (`_readlineApprovalPrompt.browser.ts`) always deterministic-denies
+ * with a message explaining that the consumer must register an
+ * explicit `ApprovalHandler`.
+ */
+import type { ApprovalDecision } from './approval.js';
+/**
+ * Prompt for a yes/no approval on stdin. Returns the resolved
+ * {@link ApprovalDecision}. In non-TTY contexts (daemon, web worker,
+ * CI), returns `{ decision: 'deny' }` with a typed reason explaining
+ * how to register a custom handler.
+ *
+ * Concurrent invocations queue on a module-level mutex so multiple
+ * `requireApproval`-gated tools in one `tool.request` batch don't
+ * interleave on the shared stdin (see comment on `promptQueue`).
+ *
+ * The Node `readline` import is statically resolvable in this file —
+ * which is intentional: bundlers walking `approval.ts` see the
+ * import path (via the per-file alias in `package.json#browser`) and
+ * substitute the browser stub instead.
+ */
+export declare function readlineApprovalPrompt(toolName: string, prompt: string): Promise<ApprovalDecision>;
+//# sourceMappingURL=_readlineApprovalPrompt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"_readlineApprovalPrompt.d.ts","sourceRoot":"","sources":["../../../src/client/tools/_readlineApprovalPrompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAkBtD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,gBAAgB,CAAC,CAU3B"}

package/dist/client/tools/_readlineApprovalPrompt.js

@@ -0,0 +1,90 @@
+/**
+ * Node-only readline prompt for the default approval handler. Lives
+ * in its own file so the browser bundle can swap it for a stub via
+ * package.json's `"browser"` field (mirroring the existing
+ * `transport.browser.ts` / `manager.browser.ts` pattern). Keeping
+ * the `readline` import in this file means the rest of
+ * `approval.ts` — types, normalization, annotation merging,
+ * `resolveApproval` — stays bundler-safe.
+ *
+ * The Node version reads `process.stdin` when `isTTY` is true and
+ * deterministic-denies otherwise. The browser stub
+ * (`_readlineApprovalPrompt.browser.ts`) always deterministic-denies
+ * with a message explaining that the consumer must register an
+ * explicit `ApprovalHandler`.
+ */
+/**
+ * Module-level mutex serializing concurrent stdin prompts.
+ *
+ * `FunctionToolRouter.dispatch` runs every per-call handler via
+ * `Promise.all`, which is correct for parallel side-effect tools —
+ * but the default approval flow uses readline on `process.stdin`,
+ * and concurrent readline interfaces over the same stdin interleave
+ * (multiple prompts visible at once, keystrokes routing
+ * non-deterministically to whichever interface read first). The
+ * fix is local to the default handler: chain promises so prompts
+ * run one-at-a-time on the shared stdin. Production override
+ * handlers (Slack, web UI) don't share stdin, so they don't need
+ * this — they bypass the mutex entirely.
+ */
+let promptQueue = Promise.resolve();
+/**
+ * Prompt for a yes/no approval on stdin. Returns the resolved
+ * {@link ApprovalDecision}. In non-TTY contexts (daemon, web worker,
+ * CI), returns `{ decision: 'deny' }` with a typed reason explaining
+ * how to register a custom handler.
+ *
+ * Concurrent invocations queue on a module-level mutex so multiple
+ * `requireApproval`-gated tools in one `tool.request` batch don't
+ * interleave on the shared stdin (see comment on `promptQueue`).
+ *
+ * The Node `readline` import is statically resolvable in this file —
+ * which is intentional: bundlers walking `approval.ts` see the
+ * import path (via the per-file alias in `package.json#browser`) and
+ * substitute the browser stub instead.
+ */
+export async function readlineApprovalPrompt(toolName, prompt) {
+    // Chain on the queue tail so the next prompt only starts once
+    // the previous one resolves. Wrap so a thrown prompt doesn't
+    // poison the chain — `.catch(() => undefined)` keeps the next
+    // waiter unblocked.
+    const myTurn = promptQueue.catch(() => undefined).then(() => runPromptOnce(toolName, prompt));
+    promptQueue = myTurn;
+    return myTurn;
+}
+async function runPromptOnce(toolName, prompt) {
+    const stdin = typeof process !== 'undefined' && process.stdin
+        ? process.stdin
+        : undefined;
+    if (stdin === undefined || stdin.isTTY !== true) {
+        return {
+            decision: 'deny',
+            reason: `defineFunctionTool(${toolName}): no \`ApprovalHandler\` registered and ` +
+                'stdin is not a TTY — register one with ' +
+                '`client.tools.setApprovalHandler(...)` before dispatching a task that uses ' +
+                'requireApproval-gated tools. Default behavior is deterministic-deny to keep ' +
+                'the approval surface safe by default.',
+        };
+    }
+    const readline = await import('readline');
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = await new Promise((resolve) => {
+            rl.question(`${prompt} [y/N] `, (input) => {
+                resolve(input);
+            });
+        });
+        const normalized = answer.trim().toLowerCase();
+        if (normalized === 'y' || normalized === 'yes') {
+            return { decision: 'approve' };
+        }
+        return { decision: 'deny', reason: 'approver said no' };
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=_readlineApprovalPrompt.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"_readlineApprovalPrompt.js","sourceRoot":"","sources":["../../../src/client/tools/_readlineApprovalPrompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;;;;;;;;;;GAaG;AACH,IAAI,WAAW,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAC;AAEtD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,QAAgB,EAChB,MAAc;IAEd,8DAA8D;IAC9D,6DAA6D;IAC7D,8DAA8D;IAC9D,oBAAoB;IACpB,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAC1D,aAAa,CAAC,QAAQ,EAAE,MAAM,CAAC,CAChC,CAAC;IACF,WAAW,GAAG,MAAM,CAAC;IACrB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,aAAa,CAC1B,QAAgB,EAChB,MAAc;IAEd,MAAM,KAAK,GACT,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,KAAK;QAC7C,CAAC,CAAE,OAAO,CAAC,KAAsC;QACjD,CAAC,CAAC,SAAS,CAAC;IAChB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO;YACL,QAAQ,EAAE,MAAM;YAChB,MAAM,EACJ,sBAAsB,QAAQ,2CAA2C;gBACzE,yCAAyC;gBACzC,6EAA6E;gBAC7E,8EAA8E;gBAC9E,uCAAuC;SAC1C,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;IAC1C,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC;QAClC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAC;IACH,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,EAAE;YACnD,EAAE,CAAC,QAAQ,CAAC,GAAG,MAAM,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE;gBACxC,OAAO,CAAC,KAAK,CAAC,CAAC;YACjB,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QACH,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC/C,IAAI,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,KAAK,EAAE,CAAC;YAC/C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;QACjC,CAAC;QACD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC1D,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,280 @@
+/**
+ * `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 type { JsonObject } from '../../qar/json.js';
+import type { ToolCall, ToolResponseResult } from '../../qar/payloads.js';
+import type { McpToolAnnotations } from '../../qar/specs.js';
+/**
+ * Sensitivity tier carried on an {@link ApprovalConfig}. Picks the
+ * advisory annotation overlay applied to the produced
+ * `FunctionToolDef.function.annotations`:
+ *
+ *   - `'low'` — no overlay. The flag still gates dispatch through the
+ *     consumer's `ApprovalHandler`; advisory annotations remain at
+ *     whatever the consumer passed in.
+ *   - `'pii'` — adds `destructiveHint: true`. Signals "this tool sees
+ *     user data; treat the call site carefully" to downstream filters.
+ *   - `'secret'` — adds `destructiveHint: true` AND `openWorldHint:
+ *     true`. Signals "this tool touches external state or secret-tier
+ *     data". Equivalent (semantically) to QAR's
+ *     `Sensitivity.SECRET` HITL classification — see
+ *     `docs/sdk2/concepts/03-hitl.md` § Bubble routing.
+ *
+ * Sensitivity is purely the annotation overlay knob; it does NOT
+ * change SDK-side dispatch logic. The same approval flow fires
+ * regardless of tier — the tier is metadata for downstream consumers.
+ */
+export type ApprovalSensitivity = 'low' | 'pii' | 'secret';
+/**
+ * UX shape requested at the approval surface. Mirrors the three
+ * `HITLBlock` kinds from `docs/sdk2/concepts/03-hitl.md`:
+ *
+ *   - `'approval'` — yes/no decision. The {@link ApprovalDecision}'s
+ *     `decision` discriminates `'approve'` vs `'deny'`; the optional
+ *     `reason` carries free-form text. Default kind when
+ *     `requireApproval: true` is set without an explicit
+ *     {@link ApprovalConfig}.
+ *   - `'choice'` — closed-set picker. The {@link ApprovalHandler}
+ *     returns `{ decision: 'approve', selection: '<option-id>' }` when
+ *     a positive option is chosen and `{ decision: 'deny' }` otherwise.
+ *     S4 does not parameterize the option list — for a custom option
+ *     set, drop down to the manual `onRequest` shape (full HITL
+ *     control). `'choice'` here is a hint to the handler that the
+ *     consumer expects a closed-set UI.
+ *   - `'input'` — free-form text response. The handler returns
+ *     `{ decision: 'approve', input: '<text>' }`; the text flows back
+ *     to the underlying function-tool handler via the
+ *     {@link ApprovalDecision.input} field so the handler can pass it
+ *     forward when invoked.
+ *
+ * The kind is an authoring-time hint to the {@link ApprovalHandler} —
+ * it does not change the dispatch wire (no `HITLBlock` is synthesized
+ * onto QAR's envelope).
+ */
+export type ApprovalKind = 'approval' | 'choice' | 'input';
+/**
+ * Configuration for a `requireApproval`-gated tool. Every field is
+ * optional; passing `requireApproval: true` (the boolean form) is
+ * equivalent to passing
+ * `{ kind: 'approval', sensitivity: 'low' }`.
+ *
+ * Fields are advisory hints to the {@link ApprovalHandler} the
+ * consumer registers via `client.tools.setApprovalHandler(...)`. The
+ * SDK passes the full {@link ApprovalConfig} through unchanged so
+ * production handlers can render richer UIs (custom prompts,
+ * deadline-driven escalation, sensitivity-keyed audit routing).
+ */
+export interface ApprovalConfig {
+    /**
+     * UX shape requested at the resolver. See {@link ApprovalKind}.
+     * Defaults to `'approval'`.
+     */
+    readonly kind?: ApprovalKind;
+    /**
+     * Sensitivity tier. Drives the annotation overlay applied to the
+     * produced `FunctionToolDef.function.annotations` (advisory). Does
+     * not change SDK-side dispatch logic. Defaults to `'low'`.
+     */
+    readonly sensitivity?: ApprovalSensitivity;
+    /**
+     * Soft deadline (ms) the handler should observe before escalating
+     * or auto-denying. The SDK does NOT enforce this timeout (a
+     * blocking stdin prompt happily blocks past it); the value is
+     * passed through to the handler so production overrides can wire
+     * their own timer.
+     */
+    readonly deadlineMs?: number;
+    /**
+     * Human-facing prompt rendered at the resolver. Defaults to a
+     * canned string built from the tool name and arguments. Useful
+     * when the tool's `description` is too verbose for an approval UI.
+     */
+    readonly prompt?: string;
+}
+/**
+ * Decision returned by an {@link ApprovalHandler}:
+ *
+ *   - `{ decision: 'approve' }` — the handler runs with the original
+ *     parsed args. Optional `input` is passed through to the handler
+ *     on the per-call context for `'input'`-kind approvals.
+ *   - `{ decision: 'deny' }` — the handler does NOT run; the SDK
+ *     returns `{ outcome: 'denied' }` to QAR with the optional
+ *     `reason` as the error message.
+ *
+ * Throwing from the handler is also valid — every throw maps to
+ * `outcome: 'denied'` (`ToolDeniedError`) or `outcome: 'error'` (any
+ * other Error). Use throws for "the resolver UI broke", returns for
+ * "the resolver decided".
+ */
+export type ApprovalDecision = {
+    readonly decision: 'approve';
+    /** Optional free-text input for `'input'`-kind approvals. */
+    readonly input?: string;
+    /** Optional selection identifier for `'choice'`-kind approvals. */
+    readonly selection?: string;
+} | {
+    readonly decision: 'deny';
+    /** Optional rejection reason; surfaces as the `outcome: 'denied'` error message. */
+    readonly reason?: string;
+};
+/**
+ * Per-call payload passed to an {@link ApprovalHandler}. Carries
+ * everything the resolver needs to render the prompt: the requested
+ * UX shape ({@link ApprovalConfig}), the inbound `ToolCall`, and the
+ * originating graph node name.
+ */
+export interface ApprovalRequest {
+    /** The tool name being gated. Matches `FunctionToolDef.function.name`. */
+    readonly toolName: string;
+    /** The full approval configuration declared on the tool. */
+    readonly config: ApprovalConfig;
+    /** The inbound `ToolCall` (raw args, `tool_call_id`, optional HITL block). */
+    readonly call: ToolCall;
+    /**
+     * Zod-parsed argument bag — the same shape the function-tool
+     * handler would receive on approve. Reflects `.default()` /
+     * `.transform()` / `.refine()` chains applied by the consumer's
+     * schema, so the approver sees the canonical args the handler will
+     * actually run with (not the raw wire bag). The default
+     * {@link ApprovalRequest.prompt} renders against this when present;
+     * falls back to {@link ToolCall.arguments} only if Zod parsing
+     * isn't yet available (e.g. when `resolveApproval` is invoked
+     * outside the router for unit tests).
+     */
+    readonly parsedArguments?: JsonObject;
+    /** Originating graph node name (echoed back on `tool.response`). */
+    readonly nodeName: string;
+    /**
+     * Pre-rendered human prompt — the `config.prompt` value when set,
+     * else a canned `"Approve <tool>(<args>)?"` string. Handlers can
+     * render this verbatim or build their own from the parts above.
+     */
+    readonly prompt: string;
+}
+/**
+ * Handler signature for `client.tools.setApprovalHandler(...)`.
+ *
+ * Returns synchronously or asynchronously. Throws map to denials
+ * (`ToolDeniedError` → `outcome: 'denied'`) or errors (`outcome:
+ * 'error'`) per the function-tool handler contract.
+ */
+export type ApprovalHandler = (req: ApprovalRequest) => ApprovalDecision | Promise<ApprovalDecision>;
+/**
+ * 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 declare const defaultApprovalHandler: ApprovalHandler;
+/**
+ * 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 declare function resolveApproval(handler: ApprovalHandler, toolName: string, config: ApprovalConfig, call: ToolCall, nodeName: string, parsedArguments?: JsonObject): Promise<ApprovalDecision | {
+    readonly _denial: ToolResponseResult;
+}>;
+/**
+ * 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 declare function mergeApprovalAnnotations(base: McpToolAnnotations | undefined, config: ApprovalConfig): McpToolAnnotations | undefined;
+/**
+ * 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 declare function normalizeApprovalConfig(value: boolean | ApprovalConfig | undefined): ApprovalConfig | undefined;
+//# sourceMappingURL=approval.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../../../src/client/tools/approval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE3D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GACxB;IACE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,GACD;IACE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEN;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,UAAU,CAAC;IACtC,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,eAAe,KACjB,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,sBAAsB,EAAE,eACa,CAAC;AAmCnD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,MAAM,EAChB,eAAe,CAAC,EAAE,UAAU,GAC3B,OAAO,CAAC,gBAAgB,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAwDtE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,kBAAkB,GAAG,SAAS,EACpC,MAAM,EAAE,cAAc,GACrB,kBAAkB,GAAG,SAAS,CAoBhC;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,GAC1C,cAAc,GAAG,SAAS,CAI5B"}