@qodo/sdk 0.13.4 → 2.0.0-next.1

package/dist/client/tools/bindFunctionToolDefs.js

@@ -0,0 +1,360 @@
+/**
+ * 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 { getFunctionToolHandler, } from './defineFunctionTool.js';
+import { resolveApproval, } from './approval.js';
+import { ToolDeniedError } from '../errors.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 class FunctionToolRouter {
+    bags = new Map();
+    subscription = null;
+    /**
+     * 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.
+     */
+    getApprovalHandler = () => {
+        // Lazy module import to keep the default handler off the
+        // bundle's eager graph (it pulls `process.stdin` references).
+        // Default-injected at `attach` time below.
+        throw new Error('FunctionToolRouter: approval handler getter not initialized — call attach() first');
+    };
+    /**
+     * 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`).
+     */
+    isConnectionLive = () => true;
+    /**
+     * 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) {
+        if (tools === undefined || tools === null || tools.length === 0) {
+            return 0;
+        }
+        let count = 0;
+        for (const tool of tools) {
+            const bag = getFunctionToolHandler(tool);
+            if (bag !== undefined) {
+                this.bags.set(bag.name, bag);
+                count += 1;
+            }
+        }
+        return count;
+    }
+    /**
+     * 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) {
+        // Always (re)bind the approval-handler getter — the consumer may
+        // have called `client.tools.setApprovalHandler(...)` between
+        // construction and the first `attach`. Capturing the function
+        // rather than the value lets a LATER `setApprovalHandler` still
+        // take effect for in-flight batches.
+        this.getApprovalHandler = () => client._getApprovalHandler();
+        // Re-bind the wire-live predicate alongside the approval handler.
+        // Captured as a closure so `runOne`'s post-approval gate observes
+        // the CURRENT connection state, not a snapshot at attach time (a
+        // `Connection` re-bind via `_bindConnection` re-points
+        // `_isConnectionLive` to the new instance transparently).
+        this.isConnectionLive = () => client._isConnectionLive();
+        if (this.subscription !== null)
+            return;
+        this.subscription = client._attachFallbackHandler((req) => this.dispatch(req));
+    }
+    /**
+     * Detach the underlying `onRequest` subscription. Used in tests + by
+     * `QodoClient.disconnect()` so a client teardown cleanly drops the
+     * router-installed handler.
+     */
+    detach() {
+        if (this.subscription !== null) {
+            try {
+                this.subscription.unsubscribe();
+            }
+            catch {
+                // best-effort — `onRequest`'s unsubscribe is documented as
+                // never throwing; the swallow exists purely so a future
+                // subscription-impl regression doesn't take the disconnect
+                // path with it.
+            }
+            this.subscription = null;
+        }
+    }
+    /**
+     * @internal — exposed for unit tests. Returns a snapshot of the
+     * registered tool names. Consumer code should not depend on this; it
+     * lives behind an underscore-prefixed name.
+     */
+    _registeredNames() {
+        return [...this.bags.keys()];
+    }
+    /**
+     * 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.
+     */
+    dispatch = async (req) => {
+        if (this.bags.size === 0)
+            return undefined;
+        const { calls, node_name: nodeName } = req.payload;
+        // Pre-flight: every call name must be in the table, else
+        // return undefined and let the next handler in the stack
+        // claim the batch.
+        for (const call of calls) {
+            if (!this.bags.has(call.name))
+                return undefined;
+        }
+        const results = await Promise.all(calls.map((call) => this.runOne(this.bags.get(call.name), call, nodeName)));
+        return results;
+    };
+    /**
+     * 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.
+     */
+    async runOne(bag, call, nodeName) {
+        // Zod-parse the inbound arguments BEFORE invoking the handler so
+        // the handler's typed `args: z.infer<TSchema>` parameter matches
+        // runtime reality — defaults applied, transforms run, refinements
+        // validated. Parse failures (e.g., the model emitted a number
+        // where the schema demands a string) surface as a per-call
+        // `outcome: 'error'` with the formatted Zod issue list; the
+        // handler never runs.
+        //
+        // `safeParse` is preferred over `parse` so we don't widen the
+        // try/catch's failure mode. The handler's own throws still
+        // route through the catch below.
+        const parsed = bag.parameters.safeParse(call.arguments);
+        if (!parsed.success) {
+            const issues = parsed.error.issues
+                .map((i) => {
+                const path = i.path.length > 0 ? i.path.join('.') : '(root)';
+                return `${path}: ${i.message}`;
+            })
+                .join('; ');
+            return {
+                outcome: 'error',
+                error: `defineFunctionTool(${bag.name}): argument validation failed — ${issues}`,
+            };
+        }
+        // S4 — `requireApproval` gate. When the consumer marked the tool
+        // with `requireApproval`, run the consumer-registered approval
+        // handler BEFORE invoking the function-tool handler. A denied
+        // approval returns `outcome: 'denied'` without invoking the
+        // function-tool handler at all — the LLM sees the denial as a
+        // normal tool response (denial is a recoverable error, not a
+        // pipeline-fatal one).
+        //
+        // Approval runs AFTER Zod-parse so the approval surface sees the
+        // canonical args bag (defaults applied, transforms run) — keeps
+        // the prompt UX consistent with what the handler would actually
+        // receive on approve. We pass `parsed.data` as `parsedArguments`
+        // so `buildPrompt` renders the canonical bag.
+        let approvalDecision;
+        if (bag.approval !== undefined) {
+            let resolved;
+            try {
+                resolved = await resolveApproval(this.getApprovalHandler(), bag.name, bag.approval, call, nodeName, parsed.data);
+            }
+            catch (err) {
+                // resolveApproval itself maps handler throws to `_denial`; an
+                // escape here means the approval-handler getter blew up
+                // (e.g., the consumer's getter throws). Map to per-call
+                // error so one bad approval-handler can't poison the whole
+                // batch (the router would otherwise propagate the rejection
+                // up and tank dispatch).
+                const message = err instanceof Error ? err.message : String(err);
+                return { outcome: 'error', error: message };
+            }
+            if ('_denial' in resolved) {
+                return resolved._denial;
+            }
+            approvalDecision = resolved;
+            // Post-approval pre-flight: if the wire died while the resolver
+            // was parked (auto-reconnect exhausted, explicit `disconnect()`,
+            // or the owning task already `task.done`-swept
+            // `toolCallSessions`), the function-tool handler MUST NOT run.
+            // The previous behavior was to invoke the handler — its
+            // real-world side effect would occur (DB write, API call,
+            // refund, …) and the subsequent `sendResponse` would throw
+            // `QodoColdAddressError`, swallowed by
+            // `ToolClient.attachDispatcher`'s send-fallback at
+            // `ToolClient.ts:524-544`. The consumer had no signal that the
+            // side effect ran; QAR's agent loop saw a tool-response timeout
+            // and surfaced a generic failure. By gating here we keep
+            // approve→side-effect coupled to approve→response-deliverable.
+            //
+            // The synthesized `outcome: 'error'` still routes through the
+            // dispatcher's send path and will (correctly) be swallowed if
+            // the wire stays dead — but the load-bearing invariant is that
+            // the function-tool handler never executes. See
+            // `docs/sdk2/concepts/03-hitl.md` for the post-fix contract +
+            // consumer guidance (observe `qar.client.reconnect_failed` and
+            // treat any in-flight approval as "handler will not run").
+            if (!this.isConnectionLive()) {
+                return {
+                    outcome: 'error',
+                    error: `defineFunctionTool(${bag.name}): connection lost before approval ` +
+                        'resolved; function handler skipped to avoid an un-acknowledgeable side effect.',
+                };
+            }
+        }
+        // Build the per-call context AFTER approval so the `approval`
+        // field can be set without breaking the `readonly` contract on
+        // FunctionToolHandlerContext. The conditional spread keeps
+        // `approval` off the ctx entirely when the tool has no gate —
+        // consumers reading `ctx.approval` see `undefined` either way,
+        // but `JSON.stringify(ctx)` stays clean for the no-gate case.
+        const ctx = {
+            toolCallId: call.tool_call_id,
+            nodeName,
+            call,
+            ...(approvalDecision !== undefined ? { approval: approvalDecision } : {}),
+        };
+        try {
+            const handler = bag.handler;
+            // `parsed.data` is the OUTPUT type of the Zod schema — the
+            // same shape `z.infer<TSchema>` declares at the type level.
+            const raw = await handler(parsed.data, ctx);
+            return coerceHandlerReturn(raw);
+        }
+        catch (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 };
+        }
+    }
+}
+/**
+ * Normalize a handler return into the SDK's `ToolResponseResult`
+ * discriminated-union shape. Plain `JsonObject` returns are wrapped in
+ * `{ outcome: 'success', result }`; `ToolResponseResult` literals pass
+ * through. Anything else throws — the wire validator rejects malformed
+ * responses and we'd rather fail at the handler than ship garbage.
+ */
+function coerceHandlerReturn(raw) {
+    if (raw === null || typeof raw !== 'object') {
+        throw new TypeError('defineFunctionTool: handler must return a JsonObject or ToolResponseResult.');
+    }
+    const maybeResult = raw;
+    if (typeof maybeResult.outcome === 'string') {
+        // Looks like a ToolResponseResult literal — pass through. The
+        // dispatcher's `isValidToolResponseResult` runtime guard re-checks
+        // the shape on the wire boundary, so we don't duplicate the
+        // validation here.
+        return raw;
+    }
+    // Plain JsonObject — wrap.
+    return { outcome: 'success', result: raw };
+}
+//# sourceMappingURL=bindFunctionToolDefs.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bindFunctionToolDefs.js","sourceRoot":"","sources":["../../../src/client/tools/bindFunctionToolDefs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH,OAAO,EACL,sBAAsB,GAIvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,eAAe,GAGhB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAS/C;;;;;;;;GAQG;AACH,MAAM,OAAO,kBAAkB;IACZ,IAAI,GAAG,IAAI,GAAG,EAAkC,CAAC;IAC1D,YAAY,GAAmC,IAAI,CAAC;IAC5D;;;;;;OAMG;IACK,kBAAkB,GAA0B,GAAG,EAAE;QACvD,yDAAyD;QACzD,8DAA8D;QAC9D,2CAA2C;QAC3C,MAAM,IAAI,KAAK,CACb,mFAAmF,CACpF,CAAC;IACJ,CAAC,CAAC;IAEF;;;;;;;;;;;;;;;OAeG;IACK,gBAAgB,GAAkB,GAAG,EAAE,CAAC,IAAI,CAAC;IAErD;;;;;;;;OAQG;IACI,QAAQ,CAAC,KAAoD;QAClE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChE,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,GAAG,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;YACzC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;gBACtB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;gBAC7B,KAAK,IAAI,CAAC,CAAC;YACb,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;;;;;;OAYG;IACI,MAAM,CAAC,MAAkB;QAC9B,iEAAiE;QACjE,6DAA6D;QAC7D,8DAA8D;QAC9D,gEAAgE;QAChE,qCAAqC;QACrC,IAAI,CAAC,kBAAkB,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC;QAC7D,kEAAkE;QAClE,kEAAkE;QAClE,iEAAiE;QACjE,uDAAuD;QACvD,0DAA0D;QAC1D,IAAI,CAAC,gBAAgB,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;QACzD,IAAI,IAAI,CAAC,YAAY,KAAK,IAAI;YAAE,OAAO;QACvC,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IACjF,CAAC;IAED;;;;OAIG;IACI,MAAM;QACX,IAAI,IAAI,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;YAC/B,IAAI,CAAC;gBACH,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC;YAClC,CAAC;YAAC,MAAM,CAAC;gBACP,2DAA2D;gBAC3D,wDAAwD;gBACxD,2DAA2D;gBAC3D,gBAAgB;YAClB,CAAC;YACD,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC;IACH,CAAC;IAED;;;;OAIG;IACI,gBAAgB;QACrB,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACK,QAAQ,GAAuB,KAAK,EAAE,GAAG,EAAE,EAAE;QACnD,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAC3C,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC;QACnD,yDAAyD;QACzD,yDAAyD;QACzD,mBAAmB;QACnB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,OAAO,SAAS,CAAC;QAClD,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CACjB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,CACvD,CACF,CAAC;QACF,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;IAEF;;;;;;;OAOG;IACK,KAAK,CAAC,MAAM,CAClB,GAA2B,EAC3B,IAAc,EACd,QAAgB;QAEhB,iEAAiE;QACjE,iEAAiE;QACjE,kEAAkE;QAClE,8DAA8D;QAC9D,2DAA2D;QAC3D,4DAA4D;QAC5D,sBAAsB;QACtB,EAAE;QACF,8DAA8D;QAC9D,2DAA2D;QAC3D,iCAAiC;QACjC,MAAM,MAAM,GAAG,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACxD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;iBAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBACT,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;gBAC7D,OAAO,GAAG,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;YACjC,CAAC,CAAC;iBACD,IAAI,CAAC,IAAI,CAAC,CAAC;YACd,OAAO;gBACL,OAAO,EAAE,OAAO;gBAChB,KAAK,EAAE,sBAAsB,GAAG,CAAC,IAAI,mCAAmC,MAAM,EAAE;aACjF,CAAC;QACJ,CAAC;QACD,iEAAiE;QACjE,+DAA+D;QAC/D,8DAA8D;QAC9D,4DAA4D;QAC5D,8DAA8D;QAC9D,6DAA6D;QAC7D,uBAAuB;QACvB,EAAE;QACF,iEAAiE;QACjE,gEAAgE;QAChE,gEAAgE;QAChE,iEAAiE;QACjE,8CAA8C;QAC9C,IAAI,gBAA8C,CAAC;QACnD,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC/B,IAAI,QAEwC,CAAC;YAC7C,IAAI,CAAC;gBACH,QAAQ,GAAG,MAAM,eAAe,CAC9B,IAAI,CAAC,kBAAkB,EAAE,EACzB,GAAG,CAAC,IAAI,EACR,GAAG,CAAC,QAAQ,EACZ,IAAI,EACJ,QAAQ,EACR,MAAM,CAAC,IAAkB,CAC1B,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,8DAA8D;gBAC9D,wDAAwD;gBACxD,wDAAwD;gBACxD,2DAA2D;gBAC3D,4DAA4D;gBAC5D,yBAAyB;gBACzB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACjE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;YAC9C,CAAC;YACD,IAAI,SAAS,IAAI,QAAQ,EAAE,CAAC;gBAC1B,OAAO,QAAQ,CAAC,OAAO,CAAC;YAC1B,CAAC;YACD,gBAAgB,GAAG,QAAQ,CAAC;YAC5B,gEAAgE;YAChE,iEAAiE;YACjE,+CAA+C;YAC/C,+DAA+D;YAC/D,wDAAwD;YACxD,0DAA0D;YAC1D,2DAA2D;YAC3D,uCAAuC;YACvC,mDAAmD;YACnD,+DAA+D;YAC/D,gEAAgE;YAChE,yDAAyD;YACzD,+DAA+D;YAC/D,EAAE;YACF,8DAA8D;YAC9D,8DAA8D;YAC9D,+DAA+D;YAC/D,gDAAgD;YAChD,8DAA8D;YAC9D,+DAA+D;YAC/D,2DAA2D;YAC3D,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,CAAC;gBAC7B,OAAO;oBACL,OAAO,EAAE,OAAO;oBAChB,KAAK,EACH,sBAAsB,GAAG,CAAC,IAAI,qCAAqC;wBACnE,gFAAgF;iBACnF,CAAC;YACJ,CAAC;QACH,CAAC;QACD,8DAA8D;QAC9D,+DAA+D;QAC/D,2DAA2D;QAC3D,8DAA8D;QAC9D,+DAA+D;QAC/D,8DAA8D;QAC9D,MAAM,GAAG,GAA+B;YACtC,UAAU,EAAE,IAAI,CAAC,YAAY;YAC7B,QAAQ;YACR,IAAI;YACJ,GAAG,CAAC,gBAAgB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1E,CAAC;QACF,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,GAAG,CAAC,OAAuC,CAAC;YAC5D,2DAA2D;YAC3D,4DAA4D;YAC5D,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC5C,OAAO,mBAAmB,CAAC,GAAG,CAAC,CAAC;QAClC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,eAAe,EAAE,CAAC;gBACnC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;YACnD,CAAC;YACD,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QAC9C,CAAC;IACH,CAAC;CACF;AAED;;;;;;GAMG;AACH,SAAS,mBAAmB,CAAC,GAAY;IACvC,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5C,MAAM,IAAI,SAAS,CACjB,6EAA6E,CAC9E,CAAC;IACJ,CAAC;IACD,MAAM,WAAW,GAAG,GAA8B,CAAC;IACnD,IAAI,OAAO,WAAW,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC5C,8DAA8D;QAC9D,mEAAmE;QACnE,4DAA4D;QAC5D,mBAAmB;QACnB,OAAO,GAAyB,CAAC;IACnC,CAAC;IACD,2BAA2B;IAC3B,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,GAAiB,EAAE,CAAC;AAC3D,CAAC"}

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

@@ -0,0 +1,277 @@
+/**
+ * `defineFunctionTool(opts)` — Zod-schema → OpenAI function-tool helper.
+ *
+ * Closes the parity gap identified by the 2026-05-21 ADK comparison
+ * (see `docs/sdk2/research/2026-05-21-google-adk-vs-qodo-ts-sdk.md`,
+ * Opportunity 4 — auto-derive JSON Schema from a Zod schema instead of
+ * hand-authoring it on every `FunctionToolDef`). Google ADK's
+ * `FunctionTool(func)` derives the schema from Python type hints
+ * (`tools/function_tool.py:42-150`); qodo-ts-sdk's pre-S3 surface
+ * required the consumer to ship the full `parameters: { type: 'object',
+ * properties: {…} }` blob inline.
+ *
+ * The helper does three things in one call:
+ *
+ *   1. Converts the supplied Zod schema to JSON Schema via Zod 4's
+ *      built-in `z.toJSONSchema()`. (`zod-to-json-schema` was the
+ *      pre-2025 path but the package was deprecated in November 2025;
+ *      Zod 4 ships the same capability natively, so we use the built-in
+ *      and avoid a redundant dependency.) Targets `draft-07` — the
+ *      OpenAI-compatible JSON Schema dialect; the produced body drops
+ *      directly into the function-tool wire shape with no further
+ *      shimming.
+ *   2. Returns a fully-formed `FunctionToolDef` that drops into
+ *      `InlineAgentSpec.tools[]` with zero further wiring.
+ *   3. Attaches the runtime `handler` on a symbol-keyed property so
+ *      `JSON.stringify` / structural cloning / spread ignore it (wire
+ *      serialization stays clean — the handler is SDK-local) and the
+ *      SDK can route inbound `tool.request` envelopes for this tool's
+ *      `name` to the right callback automatically at
+ *      `tasks.startWithAgent` / `tasks.startWithGraph` time.
+ *
+ * The handler's `args` parameter is statically typed against
+ * `z.infer<typeof parameters>`, so the consumer gets compile-time
+ * checking against the schema shape — mismatched destructures fail at
+ * the call site rather than at runtime when QAR sends the call. The
+ * router also Zod-parses inbound args before invoking the handler, so
+ * `.default()` values are applied and `.transform()` / `.refine()`
+ * chains run as written; argument-validation failures map to per-call
+ * `outcome: 'error'` without the handler running.
+ *
+ * Backward compatibility: pre-S3 hand-authored `FunctionToolDef`
+ * literals continue to work unchanged. The helper is purely additive —
+ * `InlineAgentSpec.tools[]` accepts both shapes, and the SDK's
+ * auto-bind step (see `ToolClient.bindFunctionToolDefs`) is a no-op for
+ * tools that don't carry the handler symbol.
+ */
+import { z } from 'zod';
+import { type ApprovalConfig } from './approval.js';
+import type { JsonObject } from '../../qar/json.js';
+import type { FunctionToolDef, McpToolAnnotations } from '../../qar/specs.js';
+import type { ToolCall, ToolResponseResult } from '../../qar/payloads.js';
+/**
+ * Symbol used to attach the SDK-local handler bag to a
+ * `FunctionToolDef` produced by {@link defineFunctionTool}. Symbol-keyed
+ * so:
+ *
+ *   - `JSON.stringify` ignores the property (the wire-serialized spec
+ *     stays clean without an explicit strip step at every wire
+ *     boundary).
+ *   - Object spread / `structuredClone` don't carry the handler across
+ *     unless the runtime is opted into symbols (clones drop the handler
+ *     — defensive; consumers building wire payloads via `{ ...tool }`
+ *     don't accidentally try to ship a function).
+ *   - Property-name lookups via dot/bracket access don't collide with a
+ *     consumer-authored field.
+ *
+ * Exported (named) so the SDK's own bind step and unit tests can read
+ * it; consumer code rarely needs to touch it directly —
+ * {@link getFunctionToolHandler} is the safer accessor.
+ */
+export declare const FUNCTION_TOOL_HANDLER_KEY: unique symbol;
+/**
+ * Context passed alongside the parsed `args` to a function-tool handler.
+ * Carries the per-call metadata the runtime delivered on the inbound
+ * envelope — useful for logging, tracing, or routing per-call HITL
+ * decisions.
+ */
+export interface FunctionToolHandlerContext {
+    /** The `tool_call_id` of the inbound call this handler is responding to. */
+    readonly toolCallId: string;
+    /** The originating node name (`payload.node_name`). */
+    readonly nodeName: string;
+    /** The full `ToolCall` from the inbound envelope (HITL block, raw args, etc.). */
+    readonly call: ToolCall;
+    /**
+     * Approval decision payload from the S4 `requireApproval` flow.
+     * Present only when the tool carried `requireApproval` AND the
+     * resolver returned `decision: 'approve'`. Carries the optional
+     * `input` (`'input'`-kind approvals) and `selection`
+     * (`'choice'`-kind approvals) the resolver attached — handlers
+     * can read these to thread the approver's free-text justification
+     * or choice down into the tool's effect.
+     *
+     * Always `undefined` for tools without `requireApproval` — the
+     * field exists so consumers can read it without an unsafe cast
+     * when the gate IS engaged.
+     */
+    readonly approval?: import('./approval.js').ApprovalDecision;
+}
+/**
+ * Allowed return shape from a function-tool handler:
+ *
+ *   - Plain `JsonObject` — wrapped into `{ outcome: 'success', result }`.
+ *   - Full `ToolResponseResult` — passed through (lets the consumer
+ *     reply `denied` / `error` without throwing).
+ *
+ * `void` / `undefined` is intentionally NOT supported — the SDK auto-
+ * dispatcher needs every matched call to produce a concrete response
+ * item. If the consumer wants "I'll respond later" semantics, they
+ * should NOT use `defineFunctionTool`; the manual
+ * `client.tools.onRequest` surface still applies.
+ */
+export type FunctionToolHandlerReturn = JsonObject | ToolResponseResult | Promise<JsonObject | ToolResponseResult>;
+/**
+ * The function-tool handler signature. `args` is the parsed-and-typed
+ * payload derived from the consumer's Zod schema; `ctx` carries the
+ * per-call envelope metadata.
+ *
+ * Throws are caught by the SDK dispatcher and mapped to a per-call
+ * `outcome: 'error'` response (mirrors the
+ * `ToolClient.onRequest` behaviour); `ToolDeniedError` maps to
+ * `outcome: 'denied'`.
+ */
+export type FunctionToolHandler<TArgs> = (args: TArgs, ctx: FunctionToolHandlerContext) => FunctionToolHandlerReturn;
+/**
+ * Internal handler-bag attached to a `FunctionToolDef` via the
+ * {@link FUNCTION_TOOL_HANDLER_KEY} symbol. The `parameters` reference
+ * is kept so unit tests + observability can re-validate / re-print the
+ * schema without round-tripping through JSON.
+ */
+export interface FunctionToolHandlerBag {
+    readonly name: string;
+    readonly handler: FunctionToolHandler<unknown>;
+    readonly parameters: z.ZodType;
+    /**
+     * Normalized approval configuration when the consumer set
+     * `requireApproval` on the tool. Undefined when the tool has no
+     * approval gate — the common case. The router reads this at
+     * dispatch time; presence (not value) drives the gate.
+     */
+    readonly approval?: ApprovalConfig;
+}
+/** Options accepted by {@link defineFunctionTool}. */
+export interface DefineFunctionToolOptions<TSchema extends z.ZodType> {
+    /**
+     * Tool name as the model will call it. Matches the `function.name` on
+     * the produced `FunctionToolDef`. Subject to the same constraints
+     * QAR's tool registry enforces — keep it `[a-zA-Z0-9_-]` and ≤ 64
+     * chars; the SDK doesn't lint here, the wire validator does on
+     * dispatch.
+     */
+    readonly name: string;
+    /**
+     * Human-readable description shown to the model. Surfaced verbatim on
+     * the produced `function.description`. Skip — or pass an empty
+     * string — to omit.
+     */
+    readonly description?: string;
+    /**
+     * Zod schema describing the tool's argument bag. The handler's `args`
+     * parameter is inferred from this schema via `z.infer<TSchema>` so
+     * a destructure typo fails at compile time, not at runtime.
+     *
+     * Use `z.object({...})` at the top level — Zod 4's `toJSONSchema()`
+     * produces the `{ type: 'object', properties: {...}, required: [...] }`
+     * shape OpenAI function tools expect. Non-object top-level schemas
+     * (e.g. `z.string()`) work but produce a schema the LLM may struggle
+     * to invoke correctly; the helper doesn't enforce object-ness so
+     * consumers building thin shim tools (e.g. `z.union(...)`) can still
+     * opt in.
+     */
+    readonly parameters: TSchema;
+    /**
+     * OpenAI strict-mode flag forwarded onto the produced
+     * `function.strict`. Defaults to `undefined` (lets the server pick its
+     * default — currently `true`). Pass `false` to opt out of strict
+     * argument validation; rarely useful, mostly here for parity with the
+     * pre-S3 hand-authored shape.
+     */
+    readonly strict?: boolean;
+    /**
+     * Advisory MCP `Tool.annotations` forwarded onto the produced
+     * `function.annotations`. Useful for non-MCP-backed tools that want
+     * to carry the same advisory hints (e.g. `readOnlyHint: true`) the
+     * SDK propagates through the MCP projection layer.
+     */
+    readonly annotations?: McpToolAnnotations;
+    /**
+     * Runtime callback invoked when QAR sends a `tool.request` envelope
+     * naming this tool. The first arg is the parsed-and-typed payload
+     * derived from `parameters`; the second is the per-call envelope
+     * metadata.
+     */
+    readonly handler: FunctionToolHandler<z.infer<TSchema>>;
+    /**
+     * Ergonomic HITL shorthand (S4 — closes the ADK `require_confirmation`
+     * gap; see `docs/sdk2/research/2026-05-21-google-adk-vs-qodo-ts-sdk.md`
+     * § Opp 5). When set, the SDK gates dispatch on a consumer-side
+     * approval flow before invoking `handler`:
+     *
+     *   - **`true`** — shortcut for `{ kind: 'approval', sensitivity: 'low' }`.
+     *     Synthesizes a yes/no approval prompt at dispatch time. On
+     *     approve, the handler runs with the original parsed args; on
+     *     deny, the SDK returns `{ outcome: 'denied' }` to QAR without
+     *     invoking the handler.
+     *   - **`ApprovalConfig`** — richer config: `kind` picks the resolver
+     *     UX shape (`'approval'` yes/no, `'choice'` closed-set,
+     *     `'input'` free-form); `sensitivity` drives an advisory
+     *     annotation overlay on the produced `FunctionToolDef`; `prompt`
+     *     overrides the default human-facing prompt; `deadlineMs` is
+     *     passed through to the handler.
+     *   - **`false` / `undefined`** — no approval gate. Default — the
+     *     handler runs immediately on every inbound call (the pre-S4
+     *     behavior).
+     *
+     * Override the resolver via `client.tools.setApprovalHandler(fn)`.
+     * The default handler prompts on stdin when `process.stdin.isTTY`
+     * is true; in non-interactive contexts it auto-denies with a typed
+     * error message pointing at the missing registration. See
+     * `src/client/tools/approval.ts` for the full handler contract.
+     *
+     * Composes with the existing manual `client.tools.onRequest`
+     * surface: the manual primary stack runs first, so a consumer who
+     * wants per-batch policy on top of per-tool `requireApproval` still
+     * has the explicit shape available. See
+     * `docs/sdk2/concepts/03-hitl.md` for the three-layer HITL model
+     * `requireApproval` composes onto.
+     */
+    readonly requireApproval?: boolean | ApprovalConfig;
+}
+/**
+ * `FunctionToolDef` with the SDK-local handler bag attached. Assignable
+ * to `FunctionToolDef[]` (e.g. `InlineAgentSpec.tools`) without
+ * narrowing — the symbol-keyed property is opaque to structural typing
+ * at the call site.
+ */
+export type DefinedFunctionToolDef = FunctionToolDef & {
+    readonly [FUNCTION_TOOL_HANDLER_KEY]: FunctionToolHandlerBag;
+};
+/**
+ * Read the SDK-local handler bag off a `FunctionToolDef`. Returns
+ * `undefined` for hand-authored literals that don't carry the symbol —
+ * the SDK's bind step uses this to skip tools that don't auto-route.
+ */
+export declare function getFunctionToolHandler(def: FunctionToolDef): FunctionToolHandlerBag | undefined;
+/**
+ * Derive a `FunctionToolDef` from a Zod schema + handler.
+ *
+ * @example
+ *   import { defineFunctionTool } from '@qodo/sdk';
+ *   import { z } from 'zod';
+ *
+ *   const getCurrentTime = defineFunctionTool({
+ *     name: 'get_current_time',
+ *     description: 'Returns the current time in ISO 8601 format.',
+ *     parameters: z.object({
+ *       timezone: z
+ *         .string()
+ *         .describe('IANA timezone, defaults to UTC.')
+ *         .default('UTC'),
+ *     }),
+ *     handler: async ({ timezone }) => ({
+ *       time: new Date().toLocaleString('en-US', { timeZone: timezone }),
+ *     }),
+ *   });
+ *
+ *   const stream = client.tasks.startWithAgent({
+ *     agent: {
+ *       apiVersion: 'qar/v1',
+ *       instructions: 'Answer with the current time on request.',
+ *       model: 'gpt-4o',
+ *       tools: [getCurrentTime],
+ *     },
+ *   });
+ */
+export declare function defineFunctionTool<TSchema extends z.ZodType>(opts: DefineFunctionToolOptions<TSchema>): DefinedFunctionToolDef;
+//# sourceMappingURL=defineFunctionTool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"defineFunctionTool.d.ts","sourceRoot":"","sources":["../../../src/client/tools/defineFunctionTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,QAAQ,EACR,kBAAkB,EACnB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,yBAAyB,EAAE,OAAO,MAE9C,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,eAAe,EAAE,gBAAgB,CAAC;CAC9D;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,yBAAyB,GACjC,UAAU,GACV,kBAAkB,GAClB,OAAO,CAAC,UAAU,GAAG,kBAAkB,CAAC,CAAC;AAE7C;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,CAAC,KAAK,IAAI,CACvC,IAAI,EAAE,KAAK,EACX,GAAG,EAAE,0BAA0B,KAC5B,yBAAyB,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC/C,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;CACpC;AAED,sDAAsD;AACtD,MAAM,WAAW,yBAAyB,CAAC,OAAO,SAAS,CAAC,CAAC,OAAO;IAClE;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IACxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;CACrD;AAED;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,eAAe,GAAG;IACrD,QAAQ,CAAC,CAAC,yBAAyB,CAAC,EAAE,sBAAsB,CAAC;CAC9D,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,eAAe,GACnB,sBAAsB,GAAG,SAAS,CAEpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,SAAS,CAAC,CAAC,OAAO,EAC1D,IAAI,EAAE,yBAAyB,CAAC,OAAO,CAAC,GACvC,sBAAsB,CAuDxB"}