@jini-ai/mcp 0.3.3 → 0.4.0

package/dist/server/tools/delegated-tool.d.ts

@@ -27,11 +27,14 @@ import { type McpToolDef } from '../tool-protocol.js';
  * is unset on every registration today, so `ToolExecutor` arms no timer of its own.
  */
 export declare const DEFAULT_DELEGATED_TOOL_TIMEOUT_MS: number;
-export interface CreateExecuteDelegatedToolToolOptions {
+export interface CreateExecuteDelegatedToolToolRequiredArgs {
     /** The one run this MCP server process — and therefore this tool instance — is scoped to. */
     readonly runId: string;
+}
+/** Optional correlation-id source and deadline override. */
+export interface CreateExecuteDelegatedToolToolOptions {
     /** Generates each call's `toolUseId`. @default node:crypto randomUUID */
-    readonly generateToolUseId?: () => string;
+    readonly generateToolUseId?: (required: Record<string, never>) => string;
     /**
      * Request deadline for one delegated tool call, in milliseconds. Set this to match the host's
      * own exchange total-lifetime ceiling plus headroom, so the exchange — not this request — is
@@ -54,7 +57,7 @@ export interface CreateExecuteDelegatedToolToolOptions {
  * registry — reads and writes alike. See {@link createExecuteReadonlyDelegatedToolTool} for what
  * that costs under a host that gates on the annotation, and for the companion that answers it.
  */
-export declare function createExecuteDelegatedToolTool(options: CreateExecuteDelegatedToolToolOptions): McpToolDef;
+export declare function createExecuteDelegatedToolTool(requiredArgs: CreateExecuteDelegatedToolToolRequiredArgs, options?: CreateExecuteDelegatedToolToolOptions): McpToolDef;
 /**
  * Builds the `execute_readonly_delegated_tool` companion for one specific `runId` — the same
  * gateway, narrowed to tools whose registration declares them read-only, and annotated
@@ -83,5 +86,5 @@ export declare function createExecuteDelegatedToolTool(options: CreateExecuteDel
  * Flipping the existing tool's annotation instead was rejected for the same reason: it would lie to
  * every caller, including the ones the annotation exists to protect.
  */
-export declare function createExecuteReadonlyDelegatedToolTool(options: CreateExecuteDelegatedToolToolOptions): McpToolDef;
+export declare function createExecuteReadonlyDelegatedToolTool(requiredArgs: CreateExecuteDelegatedToolToolRequiredArgs, options?: CreateExecuteDelegatedToolToolOptions): McpToolDef;
 //# sourceMappingURL=delegated-tool.d.ts.map

package/dist/server/tools/delegated-tool.js

@@ -3,8 +3,8 @@
  *
  * `execute_delegated_tool` and its read-only companion `execute_readonly_delegated_tool` — the
  * MCP-callback half of gap 3's continuation transport (see
- * `packages/daemon/source-map.md`'s "run/chat orchestration gap 3, part 1" addition and this
- * package's own dated section in `source-map.md` for the rest of the spike). The swarm-consensus
+ * `packages/daemon/archived provenance ledger`'s "run/chat orchestration gap 3, part 1" addition and this
+ * package's own dated section in `archived provenance ledger` for the rest of the spike). The swarm-consensus
  * Final Recommendation asked for exactly this: "inject the already-shipped MCP host into one
  * MCP-capable CLI's launch config, prove a tool round-trip through the existing
  * `delegated-tool-bridge.ts`." Where `../tools/run-tools.js`'s tools proxy generic
@@ -101,9 +101,8 @@ export const DEFAULT_DELEGATED_TOOL_TIMEOUT_MS = 6 * 60 * 1000;
  * @returns The `McpToolDef` to host.
  * @complexity O(1) at construction; each call is one HTTP round trip.
  */
-function createDelegatedGateway(variant, options) {
-    const { runId } = options;
-    const generateToolUseId = options.generateToolUseId ?? randomUUID;
+function createDelegatedGateway(variant, { runId }, options) {
+    const generateToolUseId = options.generateToolUseId ?? ((_required) => randomUUID());
     const requested = options.delegatedToolTimeoutMs;
     const timeoutMs = typeof requested === 'number' && Number.isFinite(requested) && requested > 0
         ? requested
@@ -144,17 +143,17 @@ function createDelegatedGateway(variant, options) {
             openWorldHint: false,
             title: variant.title,
         },
-        handler: async (args, ctx) => {
-            requireString(args.toolId, 'toolId');
+        handler: async ({ args, ctx }) => {
+            const toolId = requireString({ value: args.toolId, name: 'toolId' });
             const body = {
                 runId,
-                toolUseId: generateToolUseId(),
-                toolId: args.toolId,
+                toolUseId: generateToolUseId({}),
+                toolId: toolId,
                 input: args.input,
                 ...(variant.requireReadOnly === undefined ? {} : { requireReadOnly: variant.requireReadOnly }),
             };
-            const data = await postDaemonJson(ctx.baseUrl, '/api/delegated-tool-calls', body, {
-                ...daemonCallOptions(ctx),
+            const data = await postDaemonJson({ baseUrl: ctx.baseUrl, route: '/api/delegated-tool-calls', body: body }, {
+                ...daemonCallOptions({ ctx }),
                 timeoutMs,
             });
             return unwrapMcpContentEnvelope(data.result);
@@ -171,14 +170,14 @@ function createDelegatedGateway(variant, options) {
  * registry — reads and writes alike. See {@link createExecuteReadonlyDelegatedToolTool} for what
  * that costs under a host that gates on the annotation, and for the companion that answers it.
  */
-export function createExecuteDelegatedToolTool(options) {
+export function createExecuteDelegatedToolTool(requiredArgs, options = {}) {
     return createDelegatedGateway({
         name: 'execute_delegated_tool',
         title: 'Execute a Jini-registered tool',
         description: 'Execute a Jini-registered tool (never an agent-vendor-specific tool name) against the current run, routed through the daemon\'s ToolExecutor deny-by-default gate — the same authorization/confirmation/audit path every other tool-execution mechanism in this host uses. On a completed outcome, returns {result} normally. Any other outcome surfaces as an HTTP error the caller must catch, not a status field in a 200 body: denied/confirmation-denied raise a 403 TOOL_OPERATION_DENIED; timed-out/cancelled/failed raise a 500 INTERNAL_ERROR.',
         readOnlyHint: false,
         idempotentHint: false,
-    }, options);
+    }, requiredArgs, options);
 }
 /**
  * Builds the `execute_readonly_delegated_tool` companion for one specific `runId` — the same
@@ -208,7 +207,7 @@ export function createExecuteDelegatedToolTool(options) {
  * Flipping the existing tool's annotation instead was rejected for the same reason: it would lie to
  * every caller, including the ones the annotation exists to protect.
  */
-export function createExecuteReadonlyDelegatedToolTool(options) {
+export function createExecuteReadonlyDelegatedToolTool(requiredArgs, options = {}) {
     return createDelegatedGateway({
         name: 'execute_readonly_delegated_tool',
         title: 'Execute a read-only Jini-registered tool',
@@ -219,6 +218,6 @@ export function createExecuteReadonlyDelegatedToolTool(options) {
         // third convention for the same claim.
         idempotentHint: true,
         requireReadOnly: true,
-    }, options);
+    }, requiredArgs, options);
 }
 //# sourceMappingURL=delegated-tool.js.map

package/dist/server/tools/run-tools.js

@@ -10,7 +10,7 @@
  * `../daemon-client.js` — no separate authorization mechanism, no caching,
  * no state: whatever `@jini-ai/http-kit`'s same-origin guard / bearer-auth
  * middleware already enforces on the target route is the only gate a call
- * here passes through (see `source-map.md`'s 2026-07-21 addition for the
+ * here passes through (see `archived provenance ledger`'s 2026-07-21 addition for the
  * full origin-mapping and what was deliberately not ported).
  */
 import { getDaemonJson, postDaemonJson } from '../daemon-client.js';
@@ -53,22 +53,22 @@ export const startRunTool = {
         additionalProperties: false,
     },
     annotations: { ...WRITE_ANNOTATIONS, title: 'Start a run' },
-    handler: async (args, ctx) => {
-        requireString(args.contextRef, 'contextRef');
-        const body = { contextRef: args.contextRef };
+    handler: async ({ args, ctx }) => {
+        const contextRef = requireString({ value: args.contextRef, name: 'contextRef' });
+        const body = { contextRef: contextRef };
         const agentId = optionalNonEmptyString(args.agentId);
         if (agentId !== undefined)
             body.agentId = agentId;
         const idempotencyKey = optionalNonEmptyString(args.idempotencyKey);
         if (idempotencyKey !== undefined)
             body.idempotencyKey = idempotencyKey;
-        return postDaemonJson(ctx.baseUrl, '/api/runs', body, daemonCallOptions(ctx));
+        return postDaemonJson({ baseUrl: ctx.baseUrl, route: '/api/runs', body: body }, daemonCallOptions({ ctx }));
     },
 };
 /** `get_run` -> `GET /api/runs/:runId` (`packages/http/src/runs.ts`'s `runStatusRoute`). */
 export const getRunTool = {
     name: 'get_run',
-    description: 'Poll a run started by start_run. Returns {run} with the run\'s current state (queued|running|succeeded|failed|canceled, per @jini-ai/protocol\'s RunState).',
+    description: 'Poll a run started by start_run. Returns {run} with the run\'s current state (queued|starting|running|succeeded|failed|cancelled, per @jini-ai/protocol\'s RunState).',
     inputSchema: {
         type: 'object',
         properties: {
@@ -78,9 +78,9 @@ export const getRunTool = {
         additionalProperties: false,
     },
     annotations: { ...READ_ANNOTATIONS, title: 'Check a run' },
-    handler: async (args, ctx) => {
-        requireString(args.runId, 'runId');
-        return getDaemonJson(ctx.baseUrl, `/api/runs/${encodeURIComponent(args.runId)}`, daemonCallOptions(ctx));
+    handler: async ({ args, ctx }) => {
+        const runId = requireString({ value: args.runId, name: 'runId' });
+        return getDaemonJson({ baseUrl: ctx.baseUrl, route: `/api/runs/${encodeURIComponent(runId)}` }, daemonCallOptions({ ctx }));
     },
 };
 /** `cancel_run` -> `POST /api/runs/:runId/cancel` (`packages/http/src/runs.ts`'s `runCancelRoute`). */
@@ -97,13 +97,13 @@ export const cancelRunTool = {
         additionalProperties: false,
     },
     annotations: { ...WRITE_ANNOTATIONS, title: 'Cancel a run' },
-    handler: async (args, ctx) => {
-        requireString(args.runId, 'runId');
+    handler: async ({ args, ctx }) => {
+        const runId = requireString({ value: args.runId, name: 'runId' });
         const body = {};
         const reason = optionalNonEmptyString(args.reason);
         if (reason !== undefined)
             body.reason = reason;
-        return postDaemonJson(ctx.baseUrl, `/api/runs/${encodeURIComponent(args.runId)}/cancel`, body, daemonCallOptions(ctx));
+        return postDaemonJson({ baseUrl: ctx.baseUrl, route: `/api/runs/${encodeURIComponent(runId)}/cancel`, body: body }, daemonCallOptions({ ctx }));
     },
 };
 /**
@@ -115,7 +115,7 @@ const ACTIVE_CONTEXT_NOT_SUPPORTED = 'get_active_context is not supported by thi
 /** Reads `/api/active`, turning a 404 into {@link ACTIVE_CONTEXT_NOT_SUPPORTED}; every other failure is rethrown unchanged. */
 async function fetchActiveContext(ctx) {
     try {
-        return await getDaemonJson(ctx.baseUrl, '/api/active', daemonCallOptions(ctx));
+        return await getDaemonJson({ baseUrl: ctx.baseUrl, route: '/api/active' }, daemonCallOptions({ ctx }));
     }
     catch (err) {
         if (err?.status === 404)
@@ -129,7 +129,7 @@ export const getActiveContextTool = {
     description: 'The resource (resourceRef) plus optional detail the caller last recorded as its current focus via POST /api/active — a generic, product-neutral pointer (this kernel has no "project" or "file" noun; a host maps resourceRef to whatever domain object it manages). Returns {active:false} once the pointer has aged past its TTL (5 minutes, see ACTIVE_CONTEXT_TTL_MS in packages/http/src/active-context.ts) or was never set. On a host that does not support active context at all, the call fails with an explicit "not supported by this host" error instead — that means nothing is tracked here, not that the pointer expired.',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
     annotations: { ...READ_ANNOTATIONS, title: 'What is the caller focused on?' },
-    handler: async (_args, ctx) => {
+    handler: async ({ ctx }) => {
         const data = await fetchActiveContext(ctx);
         if (data.active !== true) {
             return {
@@ -146,7 +146,7 @@ export const listAgentsTool = {
     description: 'List every agent def registered with this host\'s @jini-ai/agent-runtime — {id, name} pairs suitable for start_run\'s optional agentId argument. Static registration data only: this does not probe which agent binaries are actually installed on the host machine.',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
     annotations: { ...READ_ANNOTATIONS, title: 'List registered agents' },
-    handler: async (_args, ctx) => getDaemonJson(ctx.baseUrl, '/api/agents', daemonCallOptions(ctx)),
+    handler: async ({ ctx }) => getDaemonJson({ baseUrl: ctx.baseUrl, route: '/api/agents' }, daemonCallOptions({ ctx })),
 };
 /** The full set of kernel-run tool defs this package ships, ready to pass as `createMcpToolServer`'s `tools` option. */
 export const RUN_TOOLS = [

package/dist/server/tools/tool-catalog-tools.js

@@ -68,12 +68,12 @@ export const searchToolsTool = {
         additionalProperties: false,
     },
     annotations: { ...READ_ANNOTATIONS, title: 'Search the tool catalog' },
-    handler: async (args, ctx) => {
-        requireString(args.query, 'query');
-        const params = new URLSearchParams({ q: args.query });
+    handler: async ({ args, ctx }) => {
+        const query = requireString({ value: args.query, name: 'query' });
+        const params = new URLSearchParams({ q: query });
         if (typeof args.limit === 'number')
             params.set('limit', String(args.limit));
-        const data = await getDaemonJson(ctx.baseUrl, `/api/tools/search?${params.toString()}`, daemonCallOptions(ctx));
+        const data = await getDaemonJson({ baseUrl: ctx.baseUrl, route: `/api/tools/search?${params.toString()}` }, daemonCallOptions({ ctx }));
         return data.hits;
     },
 };
@@ -90,9 +90,9 @@ export const describeToolTool = {
         additionalProperties: false,
     },
     annotations: { ...READ_ANNOTATIONS, title: 'Describe a tool' },
-    handler: async (args, ctx) => {
-        requireString(args.id, 'id');
-        return getDaemonJson(ctx.baseUrl, `/api/tools/${encodeURIComponent(args.id)}`, daemonCallOptions(ctx));
+    handler: async ({ args, ctx }) => {
+        const id = requireString({ value: args.id, name: 'id' });
+        return getDaemonJson({ baseUrl: ctx.baseUrl, route: `/api/tools/${encodeURIComponent(id)}` }, daemonCallOptions({ ctx }));
     },
 };
 /** Both tool-catalog discovery tools, ready to pass as `createMcpToolServer`'s `tools` option. */

package/dist/tools/ask-choice/index.d.ts

@@ -0,0 +1,123 @@
+import type { AskChoiceCall, AskChoiceExchangeStore, AskChoiceMessages, AskChoicePendingStore, AskChoicePolicy, AskChoicePresentation } from './types.js';
+export type * from './types.js';
+export { ASK_CHOICE_INPUT_SCHEMA } from './schema.js';
+export { createAskChoiceAnswerTicketStore } from './pending.js';
+/** Existing callback wire keys; the tool's identity is supplied by the host. */
+export declare const ASK_CHOICE_ANSWER_TICKET_PARAM = "__askChoiceAnswerTicket";
+/** Creates a choice tool without a CMS, renderer, permission system, clock, or global store.
+ * The host composes this descriptor/handler into its registry and mounts callbacks against the
+ * same exchange and pending stores. Policy and presentation are required, with no product defaults.
+ */
+export declare function createAskChoiceTool({ toolId, description, permission, policy, presentation, pendingQuestions, surfaceExchanges, messages }: {
+    toolId: string;
+    description: string;
+    permission: string;
+    policy: AskChoicePolicy;
+    presentation: AskChoicePresentation;
+    pendingQuestions: AskChoicePendingStore;
+    surfaceExchanges: AskChoiceExchangeStore;
+    messages: AskChoiceMessages;
+}): {
+    descriptor: {
+        id: string;
+        name: string;
+        description: string;
+        sideEffects: "none";
+        authorization: {
+            permission: string;
+        };
+        inputSchema: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["title"];
+            readonly anyOf: readonly [{
+                readonly required: readonly ["singleSelect"];
+            }, {
+                readonly required: readonly ["multiSelect"];
+            }];
+            readonly properties: {
+                readonly title: {
+                    readonly type: "string";
+                };
+                readonly description: {
+                    readonly type: "string";
+                };
+                readonly submitLabel: {
+                    readonly type: "string";
+                };
+                readonly singleSelect: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["label", "options"];
+                    readonly properties: {
+                        readonly label: {
+                            readonly type: "string";
+                        };
+                        readonly options: {
+                            readonly type: "array";
+                            readonly minItems: 1;
+                            readonly items: {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["value", "label"];
+                                readonly properties: {
+                                    readonly value: {
+                                        readonly type: "string";
+                                    };
+                                    readonly label: {
+                                        readonly type: "string";
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+                readonly multiSelect: {
+                    readonly properties: {
+                        readonly hint: {
+                            readonly type: "string";
+                        };
+                        readonly label: {
+                            readonly type: "string";
+                        };
+                        readonly options: {
+                            readonly type: "array";
+                            readonly minItems: 1;
+                            readonly items: {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["value", "label"];
+                                readonly properties: {
+                                    readonly value: {
+                                        readonly type: "string";
+                                    };
+                                    readonly label: {
+                                        readonly type: "string";
+                                    };
+                                };
+                            };
+                        };
+                    };
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["label", "options"];
+                };
+                readonly choice: {
+                    readonly type: "string";
+                    readonly description: "Set by the rendered form; never by the model.";
+                };
+                readonly selections: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Set by the rendered form; never by the model.";
+                };
+            };
+        };
+    };
+    handler({ ctx }: {
+        ctx: AskChoiceCall;
+    }): Promise<Record<string, unknown>>;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/ask-choice/index.js

@@ -0,0 +1,98 @@
+import { parseQuestion, QuestionShapeError } from './question.js';
+import { ASK_CHOICE_INPUT_SCHEMA } from './schema.js';
+export { ASK_CHOICE_INPUT_SCHEMA } from './schema.js';
+export { createAskChoiceAnswerTicketStore } from './pending.js';
+/** Existing callback wire keys; the tool's identity is supplied by the host. */
+export const ASK_CHOICE_ANSWER_TICKET_PARAM = '__askChoiceAnswerTicket';
+const SURFACE_EXCHANGE_ID_PARAM = '__exchangeId';
+const SURFACE_DISMISSED_PARAM = '__dismissed';
+const SURFACE_TYPED_ANSWER_PARAM = '__typedAnswer';
+function describeAnswer(params, messages) {
+    const choice = typeof params['choice'] === 'string' ? params['choice'] : undefined;
+    const selections = Array.isArray(params['selections']) ? params['selections'] : undefined;
+    if (choice === undefined && selections === undefined)
+        return { submitted: false, reason: 'no-answer', note: messages.noAnswer };
+    return { submitted: true, ...(choice === undefined ? {} : { choice }), ...(selections === undefined ? {} : { selections }), note: messages.submitted };
+}
+async function waitForAnswer({ exchange, ui, signal, messages }) {
+    const close = () => exchange.close({});
+    signal.addEventListener('abort', close, { once: true });
+    try {
+        if (signal.aborted) {
+            close();
+            return { submitted: false, reason: 'abandoned', note: messages.abandoned };
+        }
+        await exchange.send({ emission: { channel: 'mcp-ui', payload: { resource: ui } } });
+        const answer = await exchange.receive({});
+        if (answer.status !== 'received')
+            return { submitted: false, reason: answer.status, note: messages[answer.status] };
+        if (answer.params[SURFACE_DISMISSED_PARAM] === true)
+            return { submitted: false, reason: 'cancelled', note: messages.cancelled };
+        const typed = answer.params[SURFACE_TYPED_ANSWER_PARAM];
+        if (typeof typed === 'string' && typed.trim())
+            return { submitted: true, freeText: typed.trim(), note: messages.typed };
+        return describeAnswer(answer.params, messages);
+    }
+    finally {
+        signal.removeEventListener('abort', close);
+        close();
+    }
+}
+/** Creates a choice tool without a CMS, renderer, permission system, clock, or global store.
+ * The host composes this descriptor/handler into its registry and mounts callbacks against the
+ * same exchange and pending stores. Policy and presentation are required, with no product defaults.
+ */
+export function createAskChoiceTool({ toolId, description, permission, policy, presentation, pendingQuestions, surfaceExchanges, messages }) {
+    const descriptor = {
+        id: toolId, name: toolId, description, sideEffects: 'none',
+        authorization: { permission }, inputSchema: ASK_CHOICE_INPUT_SCHEMA,
+    };
+    return {
+        descriptor,
+        async handler({ ctx }) {
+            await policy.authorize({ ctx, toolId });
+            const input = typeof ctx.input === 'object' && ctx.input !== null ? ctx.input : {};
+            const isAnswer = typeof input['title'] !== 'string' && (typeof input['choice'] === 'string' || Array.isArray(input['selections']));
+            if (isAnswer) {
+                const rawTicket = input[ASK_CHOICE_ANSWER_TICKET_PARAM];
+                const ticket = typeof rawTicket === 'string' ? rawTicket : undefined;
+                if (!pendingQuestions.redeem({ ticket, principalId: ctx.principalId, params: input })) {
+                    throw policy.inputError({ message: messages.forgedAnswer });
+                }
+                return describeAnswer(input, messages);
+            }
+            let question;
+            try {
+                question = parseQuestion({ input, toolId });
+            }
+            catch (error) {
+                if (!(error instanceof QuestionShapeError))
+                    throw error;
+                throw policy.shapeError({ message: error.message, toolId, inputSchema: ASK_CHOICE_INPUT_SCHEMA });
+            }
+            if (ctx.signal.aborted)
+                return { submitted: false, reason: 'abandoned', note: messages.abandoned };
+            const exchange = ctx.emitSurface ? surfaceExchanges.open({ toolId, principalId: ctx.principalId, emit: ctx.emitSurface }) : undefined;
+            const ticket = exchange ? undefined : pendingQuestions.mint({ principalId: ctx.principalId, question });
+            const baseParams = exchange ? { [SURFACE_EXCHANGE_ID_PARAM]: exchange.id } : { [ASK_CHOICE_ANSWER_TICKET_PARAM]: ticket };
+            let ui;
+            try {
+                ui = presentation.render({
+                    toolName: toolId, principalId: ctx.principalId, question, baseParams,
+                }, { ...(exchange ? { cancelParams: { [SURFACE_EXCHANGE_ID_PARAM]: exchange.id, [SURFACE_DISMISSED_PARAM]: true } } : {}),
+                });
+                if (!exchange)
+                    return presentation.buildResult({ modelText: messages.pending, ui });
+            }
+            catch (error) {
+                exchange?.close({});
+                // A form that was not delivered must not leave a redeemable fallback ticket behind.
+                if (ticket !== undefined)
+                    pendingQuestions.redeem({ ticket, principalId: ctx.principalId, params: {} });
+                throw error;
+            }
+            return waitForAnswer({ exchange, ui, signal: ctx.signal, messages });
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/ask-choice/pending.d.ts

@@ -0,0 +1,11 @@
+import type { AskChoicePendingStore } from './types.js';
+/** Optional in-memory adapter. Use one instance for all callbacks belonging to the same host.
+ * IDs must be unpredictable and unique; the caller owns their generation and the ticket lifetime.
+ * Expired tickets are swept on mint; redeem consumes even a mismatched or expired ticket.
+ */
+export declare function createAskChoiceAnswerTicketStore({ now, newTicketId, ttlMs }: {
+    now: (args: Record<string, never>) => number;
+    newTicketId: (args: Record<string, never>) => string;
+    ttlMs: number;
+}): AskChoicePendingStore;
+//# sourceMappingURL=pending.d.ts.map

package/dist/tools/ask-choice/pending.js

@@ -0,0 +1,34 @@
+import { matchesOptions } from './question.js';
+/** Optional in-memory adapter. Use one instance for all callbacks belonging to the same host.
+ * IDs must be unpredictable and unique; the caller owns their generation and the ticket lifetime.
+ * Expired tickets are swept on mint; redeem consumes even a mismatched or expired ticket.
+ */
+export function createAskChoiceAnswerTicketStore({ now, newTicketId, ttlMs }) {
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0)
+        throw new Error('ttlMs must be a positive finite number');
+    const pending = new Map();
+    return {
+        mint({ principalId, question }) {
+            const nowMs = now({});
+            for (const [ticket, entry] of pending)
+                if (entry.expiresAtMs <= nowMs)
+                    pending.delete(ticket);
+            const ticket = newTicketId({});
+            if (!ticket || pending.has(ticket))
+                throw new Error('Ticket ID must be non-empty and unique');
+            // Snapshot the displayed options so caller mutation cannot change what this ticket authorizes.
+            pending.set(ticket, { principalId, expiresAtMs: nowMs + ttlMs, question: structuredClone(question) });
+            return ticket;
+        },
+        redeem({ ticket, principalId, params }) {
+            if (ticket === undefined)
+                return false;
+            const entry = pending.get(ticket);
+            if (!entry)
+                return false;
+            pending.delete(ticket);
+            return entry.expiresAtMs > now({}) && entry.principalId === principalId && matchesOptions({ question: entry.question, params });
+        },
+    };
+}
+//# sourceMappingURL=pending.js.map

package/dist/tools/ask-choice/question.d.ts

@@ -0,0 +1,16 @@
+import type { AskChoiceQuestion } from './types.js';
+/** Internal marker: only malformed question content gets schema-retry decoration. */
+export declare class QuestionShapeError extends Error {
+    constructor({ message }: {
+        message: string;
+    }, options?: ErrorOptions);
+}
+export declare function parseQuestion({ input, toolId }: {
+    input: Record<string, unknown>;
+    toolId: string;
+}): AskChoiceQuestion;
+export declare function matchesOptions({ question, params }: {
+    question: AskChoiceQuestion;
+    params: Record<string, unknown>;
+}): boolean;
+//# sourceMappingURL=question.d.ts.map

package/dist/tools/ask-choice/question.js

@@ -0,0 +1,60 @@
+/** Internal marker: only malformed question content gets schema-retry decoration. */
+export class QuestionShapeError extends Error {
+    constructor({ message }, options = {}) {
+        super(message, options);
+    }
+}
+function readSelect(raw, field, toolId) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'object' || raw === null) {
+        throw new QuestionShapeError({ message: `${toolId}: '${field}' must be an object.` });
+    }
+    const spec = raw;
+    if (typeof spec['label'] !== 'string' || !spec['label'] || !Array.isArray(spec['options']) || !spec['options'].length) {
+        throw new QuestionShapeError({ message: `${toolId}: '${field}' requires a non-empty 'label' and at least one option.` });
+    }
+    const options = spec['options'].map((entry) => {
+        const option = typeof entry === 'object' && entry !== null ? entry : {};
+        const value = option['value'];
+        const label = option['label'];
+        if (typeof value !== 'string' || !value || typeof label !== 'string' || !label) {
+            throw new QuestionShapeError({ message: `${toolId}: every '${field}' option requires a string 'value' and 'label'.` });
+        }
+        return { value, label };
+    });
+    return { label: spec['label'], options, ...(typeof spec['hint'] === 'string' ? { hint: spec['hint'] } : {}) };
+}
+export function parseQuestion({ input, toolId }) {
+    const title = input['title'];
+    if (typeof title !== 'string' || !title)
+        throw new QuestionShapeError({ message: `${toolId}: 'title' is required.` });
+    const singleSelect = readSelect(input['singleSelect'], 'singleSelect', toolId);
+    const multiSelect = readSelect(input['multiSelect'], 'multiSelect', toolId);
+    if (!singleSelect && !multiSelect) {
+        throw new QuestionShapeError({ message: `${toolId}: at least one of 'singleSelect' or 'multiSelect' is required.` });
+    }
+    return {
+        title,
+        ...(typeof input['description'] === 'string' ? { description: input['description'] } : {}),
+        ...(typeof input['submitLabel'] === 'string' ? { submitLabel: input['submitLabel'] } : {}),
+        ...(singleSelect ? { singleSelect } : {}), ...(multiSelect ? { multiSelect } : {}),
+    };
+}
+export function matchesOptions({ question, params }) {
+    const choice = params['choice'];
+    if (question.singleSelect) {
+        if (!question.singleSelect.options.some(option => option.value === choice))
+            return false;
+    }
+    else if (choice !== undefined)
+        return false;
+    const selections = params['selections'];
+    if (selections === undefined)
+        return true;
+    if (!question.multiSelect || !Array.isArray(selections))
+        return false;
+    const offered = new Set(question.multiSelect.options.map(option => option.value));
+    return selections.every(value => typeof value === 'string' && offered.has(value));
+}
+//# sourceMappingURL=question.js.map