@fgv/ts-extras 5.1.0-4 → 5.1.0-40

package/lib/packlets/ai-assist/streamingAdapters/clientToolContinuationBuilder.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Per-provider continuation message builders and the `executeClientToolTurn`
+ * helper for orchestrating a single client-tool round-trip.
+ *
+ * Each provider requires a different wire format for the follow-up request:
+ * - **Anthropic**: assistant turn reconstructed from the ordered accumulation
+ *   buffer (thinking / redacted_thinking / text / tool_use in original stream
+ *   order) + user turn with `tool_result` blocks. When thinking is active, the
+ *   follow-up request must NOT set `tool_choice: { type: 'any' }` or
+ *   `tool_choice: { type: 'tool', ... }` (E3 / §5.4 of b4-spike-findings).
+ * - **OpenAI / xAI Responses API**: `function_call` input items +
+ *   `function_call_output` input items.
+ * - **Gemini**: model turn with `functionCall` parts + user turn with
+ *   `functionResponse` parts (correlation by tool name).
+ *
+ * @packageDocumentation
+ */
+import { type Logging, Result } from '@fgv/ts-utils';
+import { type JsonObject } from '@fgv/ts-json-base';
+import { type AiServerToolConfig, type IAiClientTool, type IAiClientToolContinuation, type IAiClientToolTurnResult, type IAiStreamEvent, type IChatRequest, type IAiProviderDescriptor } from '../model';
+import { type IResolvedThinkingConfig } from '../thinkingOptionsResolver';
+import { type IAccumulatedBlock } from './anthropic';
+import { type IAccumulatedFunctionCall } from './openaiResponses';
+import { type IAccumulatedGeminiFunctionCall } from './gemini';
+/**
+ * Accumulated result for a single tool call, collected during stream iteration.
+ * @internal
+ */
+interface IToolCallResult {
+    readonly toolName: string;
+    readonly callId?: string;
+    readonly args: JsonObject;
+    readonly result: string;
+    readonly isError: boolean;
+}
+/**
+ * Builds the Anthropic follow-up messages for a client-tool round-trip.
+ *
+ * Reconstructs the assistant turn from the ordered accumulation buffer
+ * (all block types in original stream order) and appends a user turn
+ * with `tool_result` blocks for each executed tool call.
+ *
+ * **Single source of truth for the id (id-correlation fix).** Each
+ * `tool_result.tool_use_id` is drawn from — and validated against — the set of
+ * assistant `tool_use.id`s actually present in the accumulation buffer. The id
+ * is NEVER derived from the tool name: a tool name can never match a `toolu_*`
+ * id, so a name fallback produces exactly the "malformed identifier" the
+ * provider rejects. If any tool result cannot be correlated to a buffered
+ * `tool_use` block with a non-empty id, the build fails loud (naming the tool)
+ * rather than emitting a malformed continuation.
+ *
+ * **Constraint (E3):** The returned continuation does NOT include a forced
+ * `tool_choice` field. When thinking is active, Anthropic rejects
+ * `tool_choice: { type: 'any' }` and `tool_choice: { type: 'tool', ... }`
+ * with an HTTP 400 error. Only `tool_choice: { type: 'auto' }` (the default,
+ * i.e. omitted) is compatible with extended thinking.
+ *
+ * @internal
+ */
+export declare function buildAnthropicContinuation(accBuffer: Map<number, IAccumulatedBlock>, toolResults: IToolCallResult[], logger?: Logging.ILogger): Result<IAiClientToolContinuation>;
+/**
+ * Builds the OpenAI / xAI Responses API follow-up input items for a
+ * client-tool round-trip.
+ *
+ * Emits `function_call` items (the model's call) followed by
+ * `function_call_output` items (the harness execution result), one pair
+ * per executed tool call.
+ *
+ * **Single source of truth for the id (id-correlation fix).** Each
+ * `function_call_output.call_id` is drawn from — and validated against — the
+ * set of `function_call.call_id`s in the accumulation map. It is NEVER derived
+ * from the tool name (the OpenAI parity of the Anthropic `tool_use_id` fix). A
+ * missing / empty / unmatched call id fails the build loud rather than emitting
+ * a continuation the provider would reject.
+ *
+ * @internal
+ */
+export declare function buildOpenAiContinuation(calls: Map<string, IAccumulatedFunctionCall>, toolResults: IToolCallResult[], logger?: Logging.ILogger): Result<IAiClientToolContinuation>;
+/**
+ * Builds the Gemini follow-up contents for a client-tool round-trip.
+ *
+ * Emits a model turn with `functionCall` parts (one per tool call) and a
+ * user turn with `functionResponse` parts (correlation by tool name, since
+ * Gemini does not assign call IDs).
+ *
+ * When thinking is enabled, Gemini stamps an opaque `thoughtSignature` on each
+ * `functionCall` part and requires it echoed back, verbatim, as a sibling of
+ * `functionCall` on the continuation's model turn — otherwise the follow-up is
+ * rejected with "Function call is missing a thought_signature in functionCall
+ * parts". The captured signature (see {@link IAccumulatedGeminiFunctionCall})
+ * is replayed here only when present; the key is omitted entirely when thinking
+ * was disabled. See https://ai.google.dev/gemini-api/docs/thought-signatures.
+ *
+ * @internal
+ */
+export declare function buildGeminiContinuation(calls: IAccumulatedGeminiFunctionCall[], toolResults: IToolCallResult[]): IAiClientToolContinuation;
+/**
+ * Decision returned by an {@link IExecuteClientToolTurnParams.onBeforeToolExecute}
+ * gate for a single client-tool call.
+ *
+ * @remarks
+ * - `{ action: 'proceed' }` — run the tool's `execute` normally.
+ * - `{ action: 'deny', reason }` — do NOT run `execute`; a synthesized tool-result
+ *   carrying `reason` is fed into the continuation exactly like a normal result so
+ *   the model can react, and a `client-tool-result` event is emitted for the call.
+ *   The turn continues.
+ *
+ * A gate that wants to signal a hard error (as opposed to a deliberate deny) should
+ * return `Result.fail` (or reject) from the callback. Note this is NOT the same as a
+ * `tool.execute` failure: an `execute` failure yields an `isError` tool-result and the
+ * **turn continues**, whereas a gate `fail`/reject **terminates the turn** — it fails
+ * `nextTurn` (and emits an inline `error` event) rather than synthesizing a deny.
+ *
+ * @public
+ */
+export type IToolExecutionDecision = {
+    readonly action: 'proceed';
+} | {
+    readonly action: 'deny';
+    readonly reason: string;
+};
+/**
+ * Parameters for {@link AiAssist.executeClientToolTurn}.
+ *
+ * @remarks
+ * Carries the unified {@link AiAssist.IChatRequest} shape (`system?` + ordered
+ * `messages`): the last message is the current user turn and the preceding
+ * messages are history, linearized before the current turn — identically to the
+ * completion and streaming paths. {@link IExecuteClientToolTurnParams.continuationMessages}
+ * remains a distinct post-current-turn axis (see below).
+ *
+ * @public
+ */
+export interface IExecuteClientToolTurnParams extends IChatRequest {
+    /** The provider descriptor for routing (Anthropic / OpenAI / Gemini). */
+    readonly descriptor: IAiProviderDescriptor;
+    /** API key for authentication. */
+    readonly apiKey: string;
+    /**
+     * The cumulative provider-native wire tail from the previous turn's
+     * {@link AiAssist.IAiClientToolContinuation.messages}. Supply this as-is
+     * each round — `messages` is already cumulative, so **replace** rather
+     * than manually concatenate:
+     *
+     * ```ts
+     * tail = outcome.continuation.messages; // replace — already cumulative
+     * ```
+     *
+     * On the first turn this should be `undefined` (or omitted).
+     *
+     * Each provider applies its own shape guard to the supplied wire objects:
+     * - Anthropic: projects each entry to `{ role, content }` (sufficient for
+     *   thinking blocks and `tool_result` arrays).
+     * - OpenAI / xAI Responses: passes each item verbatim (`function_call` /
+     *   `function_call_output` items carry distinct fields per `type`); only
+     *   guards that each entry is a JSON object.
+     * - Gemini: projects each entry to `{ role, parts }`.
+     *
+     * Entries that fail their provider's shape check are silently skipped.
+     * Do NOT place these objects in the `messages` parameter — the
+     * normalized-message path strips provider-native fields.
+     */
+    readonly continuationMessages?: ReadonlyArray<JsonObject>;
+    /**
+     * Sampling temperature. Sent to the provider only when explicitly provided; omitted otherwise
+     * so the provider's own default applies (current-gen models reject a caller-supplied default).
+     */
+    readonly temperature?: number;
+    /** Server-side tools to include. */
+    readonly tools?: ReadonlyArray<AiServerToolConfig>;
+    /** Client-defined tools available for the model to call. */
+    readonly clientTools: ReadonlyArray<IAiClientTool>;
+    /** Optional abort signal. */
+    readonly signal?: AbortSignal;
+    /**
+     * Optional override of the descriptor's default base URL. Same semantics as
+     * the non-streaming completion path and `callProviderCompletionStream`: a
+     * well-formed `http`/`https` URL is substituted for `descriptor.baseUrl`
+     * when composing the per-format request, with the per-format suffix appended
+     * unchanged. Validated at the dispatcher; auth shape is unaffected. Use this
+     * to point a client-tool turn at a local / LAN OpenAI-compatible server
+     * (Ollama, LM Studio, llama.cpp).
+     */
+    readonly endpoint?: string;
+    /** Optional logger for diagnostics. */
+    readonly logger?: Logging.ILogger;
+    /** Optional resolved thinking config (pre-resolved by the caller). */
+    readonly resolvedThinking?: IResolvedThinkingConfig;
+    /** Resolved model string (pre-resolved by the caller). When omitted, uses the descriptor's default model. */
+    readonly model?: string;
+    /**
+     * Optional host gate invoked for each client-tool call **after** the model's raw
+     * args have been validated against the tool's `parametersSchema` and **before**
+     * `tool.execute(...)` runs. The full `tool` (including `tool.config.annotations`)
+     * and the validated `args` are passed so gate logic can key off a tool's behavior
+     * annotations (e.g. deny a `destructiveHint` call pending confirmation).
+     *
+     * Returning `{ action: 'proceed' }` (or omitting the callback) runs `execute`
+     * normally. Returning `{ action: 'deny', reason }` skips `execute` and synthesizes
+     * a denial tool-result carrying `reason` into the continuation (the model sees the
+     * denial and can react); **the turn continues**. A callback that returns `Result.fail`
+     * or rejects is a hard error that **terminates the turn** (fails `nextTurn` + emits an
+     * inline `error` event) — distinct from a `tool.execute` failure, which continues the
+     * turn with an `isError` result. A deny must therefore be explicit.
+     */
+    readonly onBeforeToolExecute?: (tool: IAiClientTool, args: unknown) => Promise<Result<IToolExecutionDecision>>;
+}
+/**
+ * Return value of {@link AiAssist.executeClientToolTurn}.
+ * @public
+ */
+export interface IExecuteClientToolTurnResult {
+    /**
+     * The unified-event iterable. Callers iterate this to drive the streaming UI.
+     * The iterable forwards `text-delta`, `tool-event`, `client-tool-call-start`,
+     * `client-tool-call-done`, and `client-tool-result` events through.
+     */
+    readonly events: AsyncIterable<IAiStreamEvent>;
+    /**
+     * Resolves when the stream terminates. On success, carries the
+     * {@link AiAssist.IAiClientToolTurnResult} with the optional continuation for the
+     * next round. On failure, carries the error message.
+     */
+    readonly nextTurn: Promise<Result<IAiClientToolTurnResult>>;
+}
+/**
+ * True when a request would combine Gemini built-in grounding (a `web_search`
+ * server tool) with client (function) tools — a combination Gemini's
+ * `generateContent` API rejects with HTTP 400 (`INVALID_ARGUMENT`). Callers gate
+ * on `descriptor.apiFormat === 'gemini'` before consulting this; other providers
+ * accept the mix. Kept as a pure predicate so the conflict rule is unit-testable
+ * without a live stream.
+ *
+ * @internal
+ */
+export declare function hasGeminiToolConflict(tools: ReadonlyArray<AiServerToolConfig> | undefined, clientTools: ReadonlyArray<IAiClientTool>): boolean;
+/**
+ * Orchestrates a single client-tool streaming turn for any supported provider.
+ *
+ * Starts a streaming request, iterates the underlying provider stream, and:
+ * - Forwards `text-delta`, `tool-event`, `client-tool-call-start`, and
+ *   `client-tool-call-done` events through to the consumer.
+ * - For each `client-tool-call-done` event: validates the raw args against the
+ *   tool's `parametersSchema`, invokes `execute(typedArgs)`, and emits a
+ *   `client-tool-result` event.
+ * - After stream completion: builds the per-provider continuation (or
+ *   `{ continuation: undefined }` when no tool calls occurred) and resolves
+ *   `nextTurn`.
+ *
+ * **Anthropic constraint (E3):** The continuation for Anthropic does not set
+ * a forced `tool_choice`. Only `tool_choice: 'auto'` (the default, i.e.
+ * omitted) is compatible with extended thinking.
+ *
+ * @param params - Turn parameters
+ * @returns `{ events, nextTurn }` — stream iterable + completion promise
+ * @public
+ */
+export declare function executeClientToolTurn(params: IExecuteClientToolTurnParams): Result<IExecuteClientToolTurnResult>;
+export {};
+//# sourceMappingURL=clientToolContinuationBuilder.d.ts.map

package/lib/packlets/ai-assist/streamingAdapters/clientToolContinuationBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clientToolContinuationBuilder.d.ts","sourceRoot":"","sources":["../../../../src/packlets/ai-assist/streamingAdapters/clientToolContinuationBuilder.ts"],"names":[],"mappings":"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"}