@oh-my-pi/pi-ai 15.13.1 → 15.13.3

package/CHANGELOG.md

@@ -2,6 +2,58 @@
 
 ## [Unreleased]
 
+## [15.13.3] - 2026-06-15
+
+### Added
+
+- Added the `gemini` in-band tool-call syntax with Python-style ```tool_code``` blocks and `default_api` invocations
+- Added the `gemma` token-delimited in-band tool-call syntax using `<|tool_call>` and `<|tool_response>` blocks
+- Added `gemini` and `gemma` to owned stream tool-result token detection so their tool responses are recognized
+- Fixed truncated Gemini and Gemma tool blocks from being emitted as plain text during streaming
+- Added the Azure OpenAI provider definition (`azure`) to the registry; `AZURE_OPENAI_API_KEY` resolves as its env-var API key via the catalog provider table.
+
+### Changed
+
+- Gemini tool-call examples now render without the `default_api.` namespace prefix, keeping `<example>` blocks concise. The live wire format still uses `default_api.` per the Gemini grammar.
+
+### Fixed
+
+- Fixed duplicate tool call projections by deduplicating provider-native `toolCall` events against in-band `tool_code` calls and keeping only the first real channel
+- Dropped nameless native `toolCall` events so they no longer appear as surfaced tool calls in owned-mode streams
+- Fixed truncated Gemini and Gemma tool blocks from being emitted as plain text during streaming
+- Fixed Gemini/Gemma in-band tool-call parsing around Python comments, raw/unicode string literals, and Gemma close-token text inside string values.
+
+## [15.13.2] - 2026-06-15
+
+### Added
+
+- Added `jsonSchemaToTypeScript` to `@oh-my-pi/pi-ai/utils/schema` to render JSON Schema argument shapes as compact, human-readable TypeScript-style signatures
+- Added the generic `ToolExample` type (`ToolCallExample`/`ToolCompareExample`/`ToolNoteExample`, parameterized over a tool's argument shape) and an `examples` property on the `Tool` interface for defining tool-call examples once as data.
+- Added `renderToolExamples` (via `@oh-my-pi/pi-ai/grammar`) to render a tool's examples into an `<examples>` block in the model's native tool-call syntax, with an optional `_i` intent-field placeholder injected when intent tracing is active.
+- Added per-grammar `renderToolCall` rendering of a single tool-call invocation (the inner element only, without the parallel-call block envelope), distinct from `renderAssistantToolCalls` which renders a complete block of one or more parallel calls.
+- Added a `GrammarRenderOptions.example` flag to `renderToolCall`: when set, the invocation renders as the bare payload — Harmony emits just the JSON arguments, dropping the verbose `<|start|>…<|message|>…<|call|>` envelope — so `renderToolExamples` keeps `<examples>` blocks legible.
+- Added an `abortOnFabrication` parameter to `wrapInbandToolStream` (default `true`): when `false`, a fabricated in-band tool-result continuation is discarded without aborting the provider request instead of cutting the turn short.
+- Added `@oh-my-pi/pi-ai/utils/harmony-leak` export with helpers to detect, audit, and recover GPT-5 Harmony tool-call header leaks
+- Added the `@oh-my-pi/pi-ai/grammar` public entrypoint for grammar factories, prompt/call rendering, in-band scanning, history encoding, and related typed utilities
+- Added a unified in-band tool-call grammar engine with syntax-owned scanners, prompts, history rendering, tool-result rendering, and stream adaptation for GLM, Hermes/Qwen, Kimi, XML/Anthropic, DeepSeek, Harmony, and pi-native formats.
+
+### Changed
+
+- Changed Harmony in-band tool-call rendering to omit the `<|constrain|>json` marker before the payload in `commentary` channel calls
+- Changed tool inventory rendering to present each tool’s `Parameters` section as a simplified TypeScript-style signature derived from its wire schema
+- Added raw in-band tool-call block capture to parsed owned tool calls so debugging can inspect the exact model-emitted call syntax.
+- Moved the canonical `ToolCallSyntax` union to `@oh-my-pi/pi-catalog/identity` and re-exported it from `@oh-my-pi/pi-ai/grammar` so the catalog can own the syntax vocabulary without an `@oh-my-pi/pi-ai` runtime import; all existing import paths are unchanged.
+- Made tool-call argument validation more lenient for schema-directed scalar coercions, including object/array stringification and 0/1 boolean coercion.
+- Changed `renderToolInventory` (the verbose system-prompt inventory and `/dump`) to render each tool as a `# Tool: <name>` markdown section instead of a `<tool name="…">…</tool>` wrapper.
+
+### Fixed
+
+- Fixed Harmony leak handling support by adding `recoverHarmonyToolCall` plus leak-detection workflows for contaminated assistant messages so recoverable tool-call arguments can be safely truncated and retried
+- Fixed false-positive gating in Harmony leak heuristics using signal-based checks so unrelated text containing `to=functions...` is not treated as leaked tool-call markup
+- Routed Kimi, DeepSeek DSML, and plain thinking markup healing through the shared in-band scanners so provider leak repair and owned tool calling parse the same wire formats.
+- Fixed Cursor provider (`cursor-agent` API) streaming dropping large MCP tool-call arguments — most visibly the built-in `task` tool's `tasks` array on multi-subagent dispatches, which failed downstream schema validation with `tasks: Invalid input: expected array, received undefined`. Two upstream behaviors were fighting the stream handler in `packages/ai/src/providers/cursor.ts`: (1) `args_text_delta` carries the *cumulative* args text so far per `agent.proto`, but the handler concatenated each snapshot onto the buffer, garbling the JSON; (2) `tool_call_completed` carries an `McpArgs` map that omits oversized parameters entirely and downgrades unparsable values to their raw string fallback, but the handler unconditionally overwrote the streamed args with that map. The handler now strips the already-buffered prefix from each `args_text_delta` snapshot (falling back to append when the snapshot doesn't extend the buffer) and merges the decoded `McpArgs` map into the streamed args — preserving streamed keys the completion frame omits and the structured value when the completion frame downgrades to a string. ([#2615](https://github.com/can1357/oh-my-pi/issues/2615))
+- Fixed Codex Responses stream mis-routing interleaved `function_call_arguments.delta` events when more than one tool call was open concurrently. The runtime tracked a singleton `currentItem`/`currentBlock`, so every delta — regardless of `item_id` — was appended to whichever item was most recently added, and `output_item.done` for the earlier call then overwrote a sibling's stored arguments (visible as `tasks: Invalid input: expected array, received undefined` on the `task` tool). Open items are now keyed by `item_id` with `output_index` fallback; deltas/done events route to the matching block, late deltas whose item already closed are dropped instead of corrupting a sibling, and `toolcall_*` stream events emit the right `contentIndex` per call ([#2619](https://github.com/can1357/oh-my-pi/issues/2619)).
+
 ## [15.13.1] - 2026-06-15
 
 ### Fixed

package/dist/types/grammar/anthropic.d.ts

@@ -0,0 +1,9 @@
+import type { Grammar, InbandScanEvent, InbandScanner, InbandScannerOptions } from "./types";
+export declare class AnthropicInbandScanner implements InbandScanner {
+    #private;
+    constructor(options?: InbandScannerOptions);
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const grammar: Grammar;
+export default grammar;

package/dist/types/grammar/catalog.d.ts

@@ -0,0 +1,3 @@
+import type { InbandTool, ToolCallSyntax } from "./types";
+export declare function renderToolCatalog(tools: readonly InbandTool[]): string;
+export declare function renderInbandToolPrompt(tools: readonly InbandTool[], syntax: ToolCallSyntax): string;

package/dist/types/grammar/coercion.d.ts

@@ -0,0 +1,23 @@
+import type { InbandTool } from "./types";
+export interface ToolArgShape {
+    stringArgs: Set<string>;
+    properties: Record<string, unknown>;
+    parameterOrder: string[];
+}
+export declare function buildArgShapes(tools?: readonly InbandTool[]): Map<string, ToolArgShape>;
+export declare function buildStringArgsResolver(tools?: readonly InbandTool[]): (toolName: string) => ReadonlySet<string>;
+export declare function resolveToolSchema(tool: InbandTool): Record<string, unknown>;
+export declare function isStringOnlySchema(schema: unknown): boolean;
+export declare function collectSchemaTypes(schema: unknown, out?: Set<string>, depth?: number): Set<string>;
+export declare function jsonTypeOf(value: unknown): string;
+export declare function decodeValue(raw: string): unknown;
+export declare function coerceValue(raw: string, schema: unknown): unknown;
+export declare function isArraySchema(schema: unknown): boolean;
+export declare function isObjectSchema(schema: unknown): boolean;
+export declare function getObjectProperties(schema: unknown): Record<string, unknown>;
+export declare function getArrayItemSchema(schema: unknown): unknown;
+export declare function mintToolCallId(): string;
+export declare function partialSuffixOverlap(text: string, tag: string): number;
+export declare function partialSuffixOverlapAny(text: string, tags: readonly string[]): number;
+export declare function normalizeKimiFunctionName(rawId: string): string;
+export declare function asRecord(value: unknown): Record<string, unknown>;

package/dist/types/grammar/deepseek.d.ts

@@ -0,0 +1,14 @@
+import type { Grammar, InbandScanEvent, InbandScanner, InbandScannerOptions } from "./types";
+export declare const DEEPSEEK_TOOL_CALLS_BEGIN = "<\uFF5Ctool\u2581calls\u2581begin\uFF5C>";
+export declare const DEEPSEEK_TOOL_CALLS_END = "<\uFF5Ctool\u2581calls\u2581end\uFF5C>";
+export declare const DEEPSEEK_TOOL_CALL_BEGIN = "<\uFF5Ctool\u2581call\u2581begin\uFF5C>";
+export declare const DEEPSEEK_TOOL_CALL_END = "<\uFF5Ctool\u2581call\u2581end\uFF5C>";
+export declare const DEEPSEEK_TOOL_SEPARATOR = "<\uFF5Ctool\u2581sep\uFF5C>";
+export declare class DeepSeekInbandScanner implements InbandScanner {
+    #private;
+    constructor(options?: InbandScannerOptions);
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const grammar: Grammar;
+export default grammar;

package/dist/types/grammar/examples.d.ts

@@ -0,0 +1,2 @@
+import type { InbandTool, ToolCallSyntax } from "./types";
+export declare function renderToolExamples(tool: InbandTool, syntax: ToolCallSyntax, intentField?: string): string;

package/dist/types/grammar/factory.d.ts

@@ -0,0 +1,3 @@
+import type { Grammar, InbandScanner, InbandScannerOptions, ToolCallSyntax } from "./types";
+export declare function getInbandGrammar(syntax: ToolCallSyntax): Grammar;
+export declare function createInbandScanner(syntax: ToolCallSyntax, options?: InbandScannerOptions): InbandScanner;

package/dist/types/grammar/gemini.d.ts

@@ -0,0 +1,16 @@
+import type { Grammar, InbandScanEvent, InbandScanner } from "./types";
+/**
+ * Scanner for the hosted-Gemini / Gemma 3 Pythonic tool-calling convention
+ * (see `docs/toolconv/gemini.md`). Tool calls arrive as a ```` ```tool_code ````
+ * fenced block whose body is one or more Python call expressions, e.g.
+ * `print(default_api.search(pattern="x", skip=40))`. Like the qwen3 scanner we
+ * buffer the whole block until its closing fence, then parse all calls at once
+ * (no incremental argument deltas — Python literals are not worth streaming).
+ */
+export declare class GeminiInbandScanner implements InbandScanner {
+    #private;
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const grammar: Grammar;
+export default grammar;

package/dist/types/grammar/gemma.d.ts

@@ -0,0 +1,14 @@
+import type { Grammar, InbandScanEvent, InbandScanner } from "./types";
+/**
+ * Scanner for the Gemma 4 token-delimited tool-calling convention (see
+ * `docs/toolconv/gemma.md`). Each call is one `<|tool_call>call:NAME{…}<tool_call|>`
+ * block whose argument list is `key:value` pairs; string values are wrapped in
+ * the `<|"|>` token rather than ASCII quotes, so splitting must skip those spans.
+ */
+export declare class GemmaInbandScanner implements InbandScanner {
+    #private;
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const grammar: Grammar;
+export default grammar;

package/dist/types/grammar/glm.d.ts

@@ -0,0 +1,9 @@
+import type { Grammar, InbandScanEvent, InbandScanner, InbandScannerOptions } from "./types";
+export declare class GLMInbandScanner implements InbandScanner {
+    #private;
+    constructor(options?: InbandScannerOptions);
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const grammar: Grammar;
+export default grammar;

package/dist/types/grammar/harmony.d.ts

@@ -0,0 +1,8 @@
+import type { Grammar, InbandScanEvent, InbandScanner } from "./types";
+export declare class HarmonyInbandScanner implements InbandScanner {
+    #private;
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const grammar: Grammar;
+export default grammar;

package/dist/types/grammar/hermes.d.ts

@@ -0,0 +1,9 @@
+import type { Grammar, InbandScanEvent, InbandScanner, InbandScannerOptions } from "./types";
+export declare class HermesInbandScanner implements InbandScanner {
+    #private;
+    constructor(options?: InbandScannerOptions);
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const grammar: Grammar;
+export default grammar;

package/dist/types/grammar/history.d.ts

@@ -0,0 +1,3 @@
+import type { Context } from "../types";
+import type { InbandTool, ToolCallSyntax } from "./types";
+export declare function encodeInbandToolHistory(messages: Context["messages"], syntax: ToolCallSyntax, tools?: readonly InbandTool[]): Context["messages"];

package/dist/types/grammar/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./catalog";
+export * from "./coercion";
+export * from "./examples";
+export * from "./factory";
+export * from "./history";
+export * from "./inventory";
+export * from "./owned-stream";
+export * from "./types";

package/dist/types/grammar/inventory.d.ts

@@ -0,0 +1,12 @@
+import type { InbandTool } from "./types";
+/**
+ * Human-readable per-tool inventory: each tool renders as a `# Tool: <name>`
+ * section with its description, a simplified TypeScript-style parameter
+ * signature (derived from the wire JSON Schema), and examples in the model's
+ * native tool-call syntax. Shared by the verbose system-prompt inventory and
+ * `/dump` so both render the catalog the same way.
+ *
+ * `model` is a model id; the native example syntax is resolved from it
+ * (`preferredToolSyntax`, which falls back to XML for empty/unknown ids).
+ */
+export declare function renderToolInventory(tools: readonly InbandTool[], model: string): string;

package/dist/types/grammar/kimi.d.ts

@@ -0,0 +1,13 @@
+import type { Grammar, InbandScanEvent, InbandScanner } from "./types";
+export declare const KIMI_SECTION_BEGIN = "<|tool_calls_section_begin|>";
+export declare const KIMI_SECTION_END = "<|tool_calls_section_end|>";
+export declare const KIMI_CALL_BEGIN = "<|tool_call_begin|>";
+export declare const KIMI_CALL_END = "<|tool_call_end|>";
+export declare const KIMI_ARG_BEGIN = "<|tool_call_argument_begin|>";
+export declare class KimiInbandScanner implements InbandScanner {
+    #private;
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const grammar: Grammar;
+export default grammar;

package/dist/types/grammar/owned-stream.d.ts

@@ -0,0 +1,4 @@
+import type { AssistantMessage, AssistantMessageEventStream as AssistantMessageEventStreamType } from "../types";
+import type { InbandTool, ToolCallSyntax } from "./types";
+export declare function parseInbandToolMessage(message: AssistantMessage, syntax: ToolCallSyntax, tools: readonly InbandTool[]): AssistantMessage;
+export declare function wrapInbandToolStream(inner: AssistantMessageEventStreamType, tools: readonly InbandTool[], syntax: ToolCallSyntax, onAbort?: () => void, abortOnFabrication?: boolean): AssistantMessageEventStreamType;

package/dist/types/grammar/pi.d.ts

@@ -0,0 +1,9 @@
+import type { Grammar, InbandScanEvent, InbandScanner, InbandScannerOptions } from "./types";
+export declare class PiNativeInbandScanner implements InbandScanner {
+    #private;
+    constructor(options?: InbandScannerOptions);
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const grammar: Grammar;
+export default grammar;

package/dist/types/grammar/qwen3.d.ts

@@ -0,0 +1,9 @@
+import type { Grammar, InbandScanEvent, InbandScanner, InbandScannerOptions } from "./types";
+export declare class Qwen3InbandScanner implements InbandScanner {
+    #private;
+    constructor(options?: InbandScannerOptions);
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const grammar: Grammar;
+export default grammar;

package/dist/types/grammar/rendering.d.ts

@@ -0,0 +1,30 @@
+import type { ToolCall } from "../types";
+import type { GrammarRenderOptions, GrammarToolResult } from "./types";
+export declare function renderGlmInvocation(call: ToolCall, options?: GrammarRenderOptions): string;
+export declare function renderGlmToolCalls(calls: readonly ToolCall[], options?: GrammarRenderOptions): string;
+export declare function renderGlmToolResults(results: readonly GrammarToolResult[]): string;
+export declare function renderHermesInvocation(call: ToolCall, _options?: GrammarRenderOptions): string;
+export declare function renderHermesToolCalls(calls: readonly ToolCall[], options?: GrammarRenderOptions): string;
+export declare function renderKimiInvocation(call: ToolCall, _options?: GrammarRenderOptions): string;
+export declare function renderKimiToolCalls(calls: readonly ToolCall[]): string;
+export declare function renderKimiToolResults(results: readonly GrammarToolResult[]): string;
+export declare function renderDeepSeekInvocation(call: ToolCall, _options?: GrammarRenderOptions): string;
+export declare function renderDeepSeekToolCalls(calls: readonly ToolCall[], options?: GrammarRenderOptions): string;
+export declare function renderDeepSeekToolResults(results: readonly GrammarToolResult[]): string;
+export declare function renderHarmonyInvocation(call: ToolCall, options?: GrammarRenderOptions): string;
+export declare function renderHarmonyToolCalls(calls: readonly ToolCall[], options?: GrammarRenderOptions): string;
+export declare function renderHarmonyToolResults(results: readonly GrammarToolResult[]): string;
+export declare function renderAnthropicInvocation(call: ToolCall, options?: GrammarRenderOptions): string;
+export declare function renderAnthropicToolCalls(calls: readonly ToolCall[], options?: GrammarRenderOptions): string;
+export declare function renderAnthropicToolResults(results: readonly GrammarToolResult[]): string;
+export declare function renderXmlInvocation(call: ToolCall, options?: GrammarRenderOptions): string;
+export declare function renderXmlToolCalls(calls: readonly ToolCall[], options?: GrammarRenderOptions): string;
+export declare function renderPiNativeInvocation(call: ToolCall, options?: GrammarRenderOptions): string;
+export declare function renderPiNativeToolCalls(calls: readonly ToolCall[], options?: GrammarRenderOptions): string;
+export declare function renderToolResponseResults(results: readonly GrammarToolResult[]): string;
+export declare function renderGeminiInvocation(call: ToolCall, options?: GrammarRenderOptions): string;
+export declare function renderGeminiToolCalls(calls: readonly ToolCall[], options?: GrammarRenderOptions): string;
+export declare function renderGeminiToolResults(results: readonly GrammarToolResult[]): string;
+export declare function renderGemmaInvocation(call: ToolCall, _options?: GrammarRenderOptions): string;
+export declare function renderGemmaToolCalls(calls: readonly ToolCall[], options?: GrammarRenderOptions): string;
+export declare function renderGemmaToolResults(results: readonly GrammarToolResult[]): string;

package/dist/types/grammar/thinking.d.ts

@@ -0,0 +1,6 @@
+import type { InbandScanEvent, InbandScanner } from "./types";
+export declare class ThinkingInbandScanner implements InbandScanner {
+    #private;
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}

package/dist/types/grammar/types.d.ts

@@ -0,0 +1,67 @@
+import type { ToolCallSyntax } from "@oh-my-pi/pi-catalog/identity";
+import type { Context, ToolCall } from "../types";
+export type { ToolCallSyntax };
+export type InbandScanEvent = {
+    type: "text";
+    text: string;
+} | {
+    type: "thinkingStart";
+} | {
+    type: "thinkingDelta";
+    delta: string;
+} | {
+    type: "thinkingEnd";
+    thinking: string;
+} | {
+    type: "toolStart";
+    id: string;
+    name: string;
+} | {
+    type: "toolArgDelta";
+    id: string;
+    name: string;
+    key: string;
+    delta: string;
+} | {
+    type: "toolEnd";
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    rawBlock?: string;
+};
+export interface InbandScanner {
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+export interface GrammarToolResult {
+    readonly id: string;
+    readonly name: string;
+    readonly index: number;
+    readonly text: string;
+    readonly isError: boolean;
+}
+export interface GrammarRenderOptions {
+    readonly tools?: readonly InbandTool[];
+    readonly example?: boolean;
+}
+export interface Grammar {
+    readonly syntax: ToolCallSyntax;
+    readonly prompt: string;
+    createScanner(options?: InbandScannerOptions): InbandScanner;
+    /** Render a single tool-call invocation — the inner element only, WITHOUT any parallel-call block envelope (e.g. anthropic's `<function_calls>` / kimi's section wrapper). */
+    renderToolCall(call: ToolCall, options?: GrammarRenderOptions): string;
+    /** Render a batch of (parallel) tool calls as one complete block, including whatever envelope the syntax wraps multiple calls in. */
+    renderAssistantToolCalls(calls: readonly ToolCall[], options?: GrammarRenderOptions): string;
+    renderToolResults(results: readonly GrammarToolResult[], options?: GrammarRenderOptions): string;
+}
+export interface InbandScannerOptions {
+    /** string-typed arg names for a tool → read verbatim. Ignored by JSON-carrying syntaxes. */
+    stringArgs?: (toolName: string) => ReadonlySet<string>;
+    /** Full tool schemas for schema-driven syntaxes such as GLM XML and pi-native. */
+    tools?: readonly InbandTool[];
+    /** XML only: parse pipe-wrapped DeepSeek DSML tags vs plain Anthropic invoke/parameter tags. */
+    xmlTagset?: "anthropic" | "dsml";
+    /** Emit thinking markers as thinking events instead of visible text when the syntax defines them. */
+    parseThinking?: boolean;
+}
+export type InbandTool = NonNullable<Context["tools"]>[number];

package/dist/types/grammar/xml.d.ts

@@ -0,0 +1,9 @@
+import type { Grammar, InbandScanEvent, InbandScanner, InbandScannerOptions } from "./types";
+export declare class XmlInbandScanner implements InbandScanner {
+    #private;
+    constructor(options?: InbandScannerOptions);
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const grammar: Grammar;
+export default grammar;

package/dist/types/providers/cursor.d.ts

@@ -1,5 +1,6 @@
 import { type JsonValue } from "@bufbuild/protobuf";
-import type { CursorExecHandlerResult, CursorExecHandlers, CursorToolResultHandler, Message, StreamFunction, StreamOptions, ToolResultMessage } from "../types";
+import type { AssistantMessage, CursorExecHandlerResult, CursorExecHandlers, CursorToolResultHandler, Message, StreamFunction, StreamOptions, TextContent, ThinkingContent, ToolCall, ToolResultMessage } from "../types";
+import { AssistantMessageEventStream } from "../utils/event-stream";
 export declare const CURSOR_API_URL = "https://api2.cursor.sh";
 export declare const CURSOR_CLIENT_VERSION = "cli-2026.01.09-231024f";
 export interface CursorOptions extends StreamOptions {
@@ -9,11 +10,56 @@ export interface CursorOptions extends StreamOptions {
     onToolResult?: CursorToolResultHandler;
 }
 export declare const streamCursor: StreamFunction<"cursor-agent">;
+export type ToolCallState = ToolCall & {
+    index: number;
+    partialJson?: string;
+    kind: "mcp" | "todo";
+};
+export interface BlockState {
+    currentTextBlock: (TextContent & {
+        index: number;
+    }) | null;
+    currentThinkingBlock: (ThinkingContent & {
+        index: number;
+    }) | null;
+    currentToolCall: ToolCallState | null;
+    firstTokenTime: number | undefined;
+    setTextBlock: (b: (TextContent & {
+        index: number;
+    }) | null) => void;
+    setThinkingBlock: (b: (ThinkingContent & {
+        index: number;
+    }) | null) => void;
+    setToolCall: (t: ToolCallState | null) => void;
+    setFirstTokenTime: () => void;
+}
+export interface UsageState {
+    sawTokenDelta: boolean;
+}
 /** Exported for tests: verifies handler is invoked with correct `this` when passed as bound. */
 export declare function resolveExecHandler<TArgs, TResult>(args: TArgs, handler: ((args: TArgs) => Promise<CursorExecHandlerResult<TResult>>) | undefined, onToolResult: CursorToolResultHandler | undefined, buildFromToolResult: (toolResult: ToolResultMessage) => TResult, buildRejected: (reason: string) => TResult, buildError: (error: string) => TResult): Promise<{
     execResult: TResult;
     toolResult?: ToolResultMessage;
 }>;
+/**
+ * Merge the decoded completion-frame `McpArgs` map into the args assembled
+ * from streamed `args_text_delta` snapshots.
+ *
+ * The completion frame is authoritative for the scalars it carries — but it
+ * can omit oversized parameters entirely and can downgrade a structured value
+ * to its raw string fallback when `decodeMcpArgValue` cannot parse it as
+ * JSON. Overwriting the streamed args wholesale therefore loses data (e.g.
+ * the task tool's `tasks` array on multi-subagent dispatches, issue #2615).
+ *
+ * Rules per key:
+ * - completion key absent  → keep the streamed value.
+ * - completion is a string while the streamed value is structured (object or
+ *   array) → keep the streamed value (the completion frame downgraded it).
+ * - otherwise               → completion wins.
+ */
+export declare function mergeCursorMcpToolCallArgs(streamed: Record<string, unknown> | undefined, completion: Record<string, unknown> | undefined): Record<string, unknown>;
+/** Exported for tests: drives one Cursor interaction update through the streaming state machine. */
+export declare function processInteractionUpdate(update: any, output: AssistantMessage, stream: AssistantMessageEventStream, state: BlockState, usageState: UsageState): void;
 /**
  * Build `ConversationStateStructure.rootPromptMessagesJson` blob IDs for the
  * system prompt plus prior conversation history, as JSON blobs matching

package/dist/types/registry/azure.d.ts

@@ -0,0 +1,4 @@
+export declare const azureProvider: {
+    readonly id: "azure";
+    readonly name: "Azure OpenAI";
+};

package/dist/types/registry/registry.d.ts

@@ -25,6 +25,9 @@ declare const ALL: ({
     readonly refreshToken: (credentials: import("./oauth").OAuthCredentials) => Promise<import("./oauth").OAuthCredentials>;
     readonly callbackPort: 54545;
     readonly pasteCodeFlow: true;
+} | {
+    readonly id: "azure";
+    readonly name: "Azure OpenAI";
 } | {
     readonly id: "cerebras";
     readonly name: "Cerebras";

package/dist/types/types.d.ts

@@ -344,6 +344,11 @@ export interface ToolCall {
     arguments: Record<string, any>;
     thoughtSignature?: string;
     intent?: string;
+    /**
+     * Verbatim in-band syntax block that produced this synthetic `ptc_*` call.
+     * Present only for owned prompt/tool-call formats; provider-native calls omit it.
+     */
+    rawBlock?: string;
     /**
      * Original wire-level name when the tool was invoked via OpenAI's custom-tool
      * mechanism (e.g., `apply_patch`). Set by `openai-responses` on receive so
@@ -483,6 +488,20 @@ export type TSchema = ZodType | TJsonSchema;
 export type Static<S> = S extends ZodType ? z.infer<S> : S extends {
     static: infer T;
 } ? T : unknown;
+export interface ToolCallExample<TArgs = Record<string, unknown>> {
+    caption?: string;
+    call: TArgs;
+}
+export interface ToolCompareExample<TArgs = Record<string, unknown>> {
+    caption?: string;
+    bad: TArgs;
+    good: TArgs;
+}
+export interface ToolNoteExample {
+    caption: string;
+    note?: string;
+}
+export type ToolExample<TArgs = Record<string, unknown>> = ToolCallExample<TArgs> | ToolCompareExample<TArgs> | ToolNoteExample;
 export interface Tool<TParameters extends TSchema = TSchema> {
     name: string;
     description: string;
@@ -509,6 +528,15 @@ export interface Tool<TParameters extends TSchema = TSchema> {
      * calls route correctly. Absent for regular JSON function tools.
      */
     customWireName?: string;
+    /**
+     * Illustrative calls/notes; the AI layer renders them into an `<examples>`
+     * block in the model's native tool-call syntax and appends to the wire
+     * description. Author `call`/`bad`/`good` as plain argument objects WITHOUT
+     * `_i` — when intent tracing injects `_i` into the schema, the renderer adds
+     * a placeholder `_i` automatically. Type each tool's `examples` against its
+     * own schema (e.g. `readonly ToolExample<z.input<typeof schema>>[]`).
+     */
+    examples?: readonly ToolExample[];
 }
 export interface Context {
     systemPrompt?: string[];

package/dist/types/utils/harmony-leak.d.ts

@@ -0,0 +1,118 @@
+/**
+ * GPT-5 Harmony-header leakage detection and recovery.
+ *
+ * Background and policy: see `docs/ERRATA-GPT5-HARMONY.md`. This module
+ * implements §3 of that document: detection by signal fusion, plus a
+ * truncate-and-resume primitive for the `edit` tool when its input is in
+ * hashline DSL form. Other tools and surfaces fall through to
+ * abort-and-retry handled by the agent loop.
+ */
+import type { AssistantMessage, Model, ToolCall } from "../types";
+declare const SIGNAL_ORDER: readonly ["M", "C", "G", "S", "B", "R", "T"];
+export type HarmonySignalClass = "H" | (typeof SIGNAL_ORDER)[number];
+export type HarmonySurface = "assistant_text" | "assistant_thinking" | "tool_arg";
+export interface HarmonySignal {
+    classes: HarmonySignalClass[];
+    start: number;
+    end: number;
+    text: string;
+}
+export interface HarmonyDetection {
+    surface: HarmonySurface;
+    contentIndex?: number;
+    toolName?: string;
+    toolCallId?: string;
+    signals: HarmonySignal[];
+}
+export interface HarmonyAuditEvent {
+    action: "truncate_resume" | "abort_retry" | "escalated";
+    surface: HarmonySurface;
+    signal: string;
+    retryN: number;
+    model: string;
+    provider: string;
+    toolName?: string;
+    removedLen: number;
+    removedSha8: string;
+    removedPreview: string;
+    removedBlob?: string;
+}
+export interface HarmonyRecoveredToolCall {
+    message: AssistantMessage;
+    removed: string;
+}
+/**
+ * Whether to run leak detection on responses from this model. We default-on
+ * for every openai-codex model rather than enumerating ids, so a future
+ * gpt-5.6 (or whatever) doesn't silently bypass the mitigation. Detection
+ * itself is cheap; the cost of missing a leak on a new model is not.
+ */
+export declare function isHarmonyLeakMitigationTarget(model: Model): boolean;
+export declare function signalListLabel(signals: readonly HarmonySignal[]): string;
+/**
+ * Detect harmony-protocol leakage in `text`. Returns undefined if clean.
+ *
+ * Trip rule: `H` alone, or `M` paired with at least one co-signal
+ * (`C`/`G`/`S`/`B`/`R`/`T`). Bare `M` does not trip — this document, its
+ * tests, and bug reports legitimately carry the marker.
+ *
+ * The `tool_arg` surface is held to a stricter rule. A tool argument is
+ * arbitrary file/data content that can legitimately carry the marker, a
+ * channel word, harmony control tokens, or a non-Latin script run (editing
+ * these very fixtures does exactly that). The only robust leak signal there
+ * is content trailing the structurally-valid parse, so a `tool_arg` detection
+ * additionally requires the `T` co-signal. Absent a `parsedEnd` boundary `T`
+ * is never set, so `tool_arg` scanning stays inert and a legitimate codex tool
+ * call is never hard-aborted. `assistant_text`/`assistant_thinking` keep the
+ * base rule.
+ *
+ * `parsedEnd`, when supplied, marks the byte at which a structurally valid
+ * tool-argument parse ends; markers at or past it set the `T` co-signal.
+ * `contentIndex`/`toolName`/`toolCallId` flow through to the returned
+ * detection for downstream auditing.
+ */
+export declare function detectHarmonyLeak(text: string, surface: HarmonySurface, options?: {
+    parsedEnd?: number;
+    contentIndex?: number;
+    toolName?: string;
+    toolCallId?: string;
+}): HarmonyDetection | undefined;
+/**
+ * Scan an assistant message's content blocks; return the first detection.
+ *
+ * `toolArgParseEnd`, when supplied, resolves the byte offset at which a tool
+ * call's structurally-valid argument parse ends (the `T` co-signal in
+ * {@link detectHarmonyLeak}). Callers that can parse a tool's argument DSL pass
+ * it to enable `tool_arg` leak detection; omitting it keeps that surface inert
+ * — the safe default the agent loop relies on, since it cannot bound a streamed
+ * tool DSL and must never hard-abort a legitimate tool call.
+ */
+export declare function detectHarmonyLeakInAssistantMessage(message: AssistantMessage, toolArgParseEnd?: (toolCall: ToolCall) => number | undefined): HarmonyDetection | undefined;
+/**
+ * Truncate a contaminated tool call at the start of the contaminated line and
+ * append the tool's recovery sentinel. Returns a recovered AssistantMessage
+ * (containing only the cleaned tool call), a synthetic continuation user
+ * message asking the model to re-issue the rest, and the removed substring
+ * for auditing. Returns undefined when the tool is not recovery-eligible or
+ * the truncation would leave nothing meaningful to dispatch.
+ *
+ * `providerPayload` is dropped from the recovered message: for Codex the
+ * encrypted reasoning blob is opaque/signed and we cannot validate that it is
+ * uncontaminated. The model re-reasons on the next turn.
+ */
+export declare function recoverHarmonyToolCall(message: AssistantMessage, detection: HarmonyDetection): HarmonyRecoveredToolCall | undefined;
+/**
+ * Return the contaminated substring from `message` for audit purposes when
+ * recovery is not applicable (abort path). Walks from the first detected
+ * signal to end-of-content within the relevant block. Returns "" if the
+ * detection cannot be resolved against the message.
+ */
+export declare function extractHarmonyRemoved(message: AssistantMessage, detection: HarmonyDetection): string;
+export declare function createHarmonyAuditEvent(params: {
+    action: HarmonyAuditEvent["action"];
+    detection: HarmonyDetection;
+    model: Model;
+    retryN: number;
+    removed: string;
+}): HarmonyAuditEvent;
+export {};

package/dist/types/utils/schema/index.d.ts

@@ -9,5 +9,6 @@ export * from "./meta-validator";
 export * from "./normalize";
 export * from "./spill";
 export * from "./types";
+export * from "./typescript";
 export * from "./wire";
 export * from "./zod-decontaminate";