@oh-my-pi/pi-agent-core 15.13.0 → 15.13.2

package/src/agent-loop.ts

@@ -15,7 +15,13 @@ import {
 	validateToolArguments,
 	zodToWireSchema,
 } from "@oh-my-pi/pi-ai";
-import { logger, sanitizeText } from "@oh-my-pi/pi-utils";
+import {
+	encodeInbandToolHistory,
+	renderInbandToolPrompt,
+	renderToolExamples,
+	type ToolCallSyntax,
+	wrapInbandToolStream,
+} from "@oh-my-pi/pi-ai/grammar";
 import {
 	createHarmonyAuditEvent,
 	detectHarmonyLeakInAssistantMessage,
@@ -25,7 +31,9 @@ import {
 	isHarmonyLeakMitigationTarget,
 	recoverHarmonyToolCall,
 	signalListLabel,
-} from "./harmony-leak";
+} from "@oh-my-pi/pi-ai/utils/harmony-leak";
+import { preferredToolSyntax } from "@oh-my-pi/pi-catalog/identity";
+import { logger, sanitizeText } from "@oh-my-pi/pi-utils";
 import { type AgentRunCoverage, type AgentRunSummary, ToolCallBlockedError } from "./run-collector";
 import {
 	type AgentTelemetry,
@@ -76,6 +84,25 @@ class HarmonyLeakInterruption extends Error {
 		this.name = "HarmonyLeakInterruption";
 	}
 }
+function resolveOwnedToolSyntaxFromEnv(value: string | undefined): ToolCallSyntax | undefined {
+	switch (value) {
+		case "1":
+		case "true":
+			return "glm";
+		case "glm":
+		case "hermes":
+		case "kimi":
+		case "xml":
+		case "anthropic":
+		case "deepseek":
+		case "harmony":
+		case "pi":
+		case "qwen3":
+			return value;
+		default:
+			return undefined;
+	}
+}
 
 type AssistantContentBlock = AssistantMessage["content"][number];
 type AssistantToolCallBlock = Extract<AssistantContentBlock, { type: "toolCall" }>;
@@ -483,6 +510,7 @@ function injectIntentIntoSchema(schema: unknown, mode: "require" | "optional" =
 		properties: {
 			[INTENT_FIELD]: {
 				type: "string",
+				description: "Concise intent in present participle form (2-6 words) strictly on a single line, no newlines",
 			},
 			...properties,
 		},
@@ -490,7 +518,11 @@ function injectIntentIntoSchema(schema: unknown, mode: "require" | "optional" =
 	};
 }
 
-export function normalizeTools(tools: AgentContext["tools"], injectIntent: boolean): Context["tools"] {
+export function normalizeTools(
+	tools: AgentContext["tools"],
+	injectIntent: boolean,
+	exampleSyntax?: ToolCallSyntax,
+): Context["tools"] {
 	injectIntent = injectIntent && Bun.env.PI_NO_INTENT !== "1";
 	return tools?.map(t => {
 		const intentMode = resolveIntentMode(t.intent);
@@ -504,7 +536,12 @@ export function normalizeTools(tools: AgentContext["tools"], injectIntent: boole
 			}
 		}
 		const description = t.description ?? "";
-		return { ...t, parameters, description };
+		const injectExampleIntent = injectIntent && intentMode !== "omit";
+		const examplesBlock = exampleSyntax
+			? renderToolExamples({ ...t, parameters }, exampleSyntax, injectExampleIntent ? INTENT_FIELD : undefined)
+			: "";
+		const finalDescription = examplesBlock ? `${description}\n\n${examplesBlock}` : description;
+		return { ...t, parameters, description: finalDescription };
 	});
 }
 
@@ -883,18 +920,37 @@ async function streamAssistantResponse(
 	let llmContext: Context;
 	if (config.appendOnlyContext) {
 		config.appendOnlyContext.syncMessages(normalizedMessages);
-		llmContext = config.appendOnlyContext.build(context, { intentTracing: !!config.intentTracing });
+		llmContext = config.appendOnlyContext.build(context, {
+			intentTracing: !!config.intentTracing,
+			exampleSyntax: preferredToolSyntax(config.model.id),
+		});
 	} else {
 		llmContext = {
 			systemPrompt: context.systemPrompt,
 			messages: normalizedMessages,
-			tools: normalizeTools(context.tools, !!config.intentTracing),
+			tools: normalizeTools(context.tools, !!config.intentTracing, preferredToolSyntax(config.model.id)),
 		};
 	}
 	if (config.transformProviderContext) {
 		llmContext = config.transformProviderContext(llmContext, config.model);
 	}
 
+	// Owned tool calling: take tool calls away from the provider and run them
+	// through the selected in-band prompt syntax. `PI_OWNED_TOOLS=1` still
+	// force-enables GLM; `PI_OWNED_TOOLS=<syntax>` force-enables that syntax.
+	const ownedSyntax: ToolCallSyntax | undefined =
+		config.toolCallSyntax ?? resolveOwnedToolSyntaxFromEnv(Bun.env.PI_OWNED_TOOLS);
+	let promptToolWireTools: Context["tools"];
+	if (ownedSyntax && llmContext.tools && llmContext.tools.length > 0) {
+		promptToolWireTools = llmContext.tools;
+		llmContext = {
+			...llmContext,
+			systemPrompt: [...(llmContext.systemPrompt ?? []), renderInbandToolPrompt(promptToolWireTools, ownedSyntax)],
+			messages: encodeInbandToolHistory(llmContext.messages, ownedSyntax, promptToolWireTools),
+			tools: undefined,
+		};
+	}
+
 	const streamFunction = streamFn || streamSimple;
 
 	// Resolve API key (important for expiring tokens) — do this before resolving
@@ -919,12 +975,22 @@ async function streamAssistantResponse(
 			: harmonyAbortController.signal
 		: signal;
 	const repetitionAbortController = new AbortController();
-	const finalRequestSignal = requestSignal
-		? AbortSignal.any([requestSignal, repetitionAbortController.signal])
-		: repetitionAbortController.signal;
+	// Owned tool calling: aborted by the stream wrapper when the model starts
+	// fabricating a `<tool_response>`, so the provider stops generating the rest of
+	// the hallucinated turn. Merged into the provider signal ONLY (not
+	// `requestSignal`), so it cancels the request without tripping the loop's
+	// external-abort handling (`abortRacePromise` / `requestSignal.aborted`).
+	const promptToolAbortController = ownedSyntax ? new AbortController() : undefined;
+	const providerAbortSignals: AbortSignal[] = [];
+	if (requestSignal) providerAbortSignals.push(requestSignal);
+	providerAbortSignals.push(repetitionAbortController.signal);
+	if (promptToolAbortController) providerAbortSignals.push(promptToolAbortController.signal);
+	const finalRequestSignal =
+		providerAbortSignals.length === 1 ? providerAbortSignals[0]! : AbortSignal.any(providerAbortSignals);
 	const effectiveTemperature =
 		harmonyRetryAttempt > 0 && config.temperature !== undefined ? config.temperature + 0.05 : config.temperature;
-	const effectiveToolChoice = dynamicToolChoice ?? config.toolChoice;
+	// Owned tool calling sends no native tools, so any tool_choice would error.
+	const effectiveToolChoice = ownedSyntax ? undefined : (dynamicToolChoice ?? config.toolChoice);
 	const effectiveReasoning = dynamicReasoning ?? config.reasoning;
 	const effectiveDisableReasoning = dynamicDisableReasoning ?? config.disableReasoning;
 
@@ -969,7 +1035,7 @@ async function streamAssistantResponse(
 
 	try {
 		return await runInActiveSpan(chatSpan, async () => {
-			const response = await streamFunction(config.model, llmContext, {
+			let response = await streamFunction(config.model, llmContext, {
 				...config,
 				// Hand streamSimple a resolver so its central auth-retry policy can
 				// re-resolve on 401 / usage-limit: the initial step reuses the key
@@ -992,6 +1058,20 @@ async function streamAssistantResponse(
 				signal: finalRequestSignal,
 				onResponse: captureOnResponse,
 			});
+			if (promptToolWireTools && ownedSyntax) {
+				// Re-materialize in-band tool-call text as native toolCall content blocks
+				// so the rest of the loop executes them unchanged. When the model starts
+				// fabricating tool results, the abort callback cancels the provider — unless
+				// `abortOnFabricatedToolResult` is false, in which case the stream drains and
+				// the fabricated continuation is discarded without aborting.
+				response = wrapInbandToolStream(
+					response,
+					promptToolWireTools,
+					ownedSyntax,
+					() => promptToolAbortController?.abort(),
+					config.abortOnFabricatedToolResult ?? true,
+				);
+			}
 
 			let partialMessage: AssistantMessage | null = null;
 			let addedPartial = false;

package/src/agent.ts

@@ -22,11 +22,12 @@ import {
 	type ToolChoice,
 	type ToolResultMessage,
 } from "@oh-my-pi/pi-ai";
+import type { ToolCallSyntax } from "@oh-my-pi/pi-ai/grammar";
+import type { HarmonyAuditEvent } from "@oh-my-pi/pi-ai/utils/harmony-leak";
 import { getBundledModel } from "@oh-my-pi/pi-catalog/models";
 import { logger } from "@oh-my-pi/pi-utils";
 import { abortReasonText, agentLoop, agentLoopContinue } from "./agent-loop";
 import type { AppendOnlyContextManager } from "./append-only-context";
-import type { HarmonyAuditEvent } from "./harmony-leak";
 import type {
 	AgentContext,
 	AgentEvent,
@@ -220,6 +221,15 @@ export interface AgentOptions {
 
 	/** Enable intent tracing schema injection/stripping in the harness. */
 	intentTracing?: boolean;
+	/** Owned tool-calling syntax. Undefined keeps provider-native tool calling. */
+	toolCallSyntax?: ToolCallSyntax;
+	/**
+	 * When owned tool calling is active and the model fabricates a tool result
+	 * mid-turn: `true` (default) aborts the provider request immediately; `false`
+	 * drains the request and discards the fabricated continuation. Forwarded to
+	 * the loop's {@link AgentLoopConfig.abortOnFabricatedToolResult}.
+	 */
+	abortOnFabricatedToolResult?: boolean;
 	/** Dynamic tool choice override, resolved per LLM call. */
 	getToolChoice?: () => ToolChoice | undefined;
 
@@ -316,6 +326,8 @@ export class Agent {
 	#preferWebsockets?: boolean;
 	#transformToolCallArguments?: (args: Record<string, unknown>, toolName: string) => Record<string, unknown>;
 	#intentTracing: boolean;
+	#toolCallSyntax?: ToolCallSyntax;
+	#abortOnFabricatedToolResult?: boolean;
 	#getToolChoice?: () => ToolChoice | undefined;
 	#onPayload?: SimpleStreamOptions["onPayload"];
 	#onResponse?: SimpleStreamOptions["onResponse"];
@@ -378,6 +390,8 @@ export class Agent {
 		this.#preferWebsockets = opts.preferWebsockets;
 		this.#transformToolCallArguments = opts.transformToolCallArguments;
 		this.#intentTracing = opts.intentTracing === true;
+		this.#toolCallSyntax = opts.toolCallSyntax;
+		this.#abortOnFabricatedToolResult = opts.abortOnFabricatedToolResult;
 		this.#getToolChoice = opts.getToolChoice;
 		this.#onAssistantMessageEvent = opts.onAssistantMessageEvent;
 		this.#onHarmonyLeak = opts.onHarmonyLeak;
@@ -657,8 +671,8 @@ export class Agent {
 	}
 
 	// State mutators
-	setSystemPrompt(v: string[]) {
-		this.#state.systemPrompt = v;
+	setSystemPrompt(v: string[] | string) {
+		this.#state.systemPrompt = typeof v === "string" ? [v] : v;
 	}
 
 	setModel(m: Model) {
@@ -1023,6 +1037,8 @@ export class Agent {
 			cursorOnToolResult,
 			transformToolCallArguments: this.#transformToolCallArguments,
 			intentTracing: this.#intentTracing,
+			toolCallSyntax: this.#toolCallSyntax,
+			abortOnFabricatedToolResult: this.#abortOnFabricatedToolResult,
 			appendOnlyContext: this.#appendOnlyContext,
 			beforeToolCall: this.beforeToolCall ? (ctx, signal) => this.beforeToolCall?.(ctx, signal) : undefined,
 			afterToolCall: this.afterToolCall ? (ctx, signal) => this.afterToolCall?.(ctx, signal) : undefined,

package/src/append-only-context.ts

@@ -15,6 +15,7 @@
  */
 
 import type { Context, Message, Tool } from "@oh-my-pi/pi-ai";
+import type { ToolCallSyntax } from "@oh-my-pi/pi-ai/grammar";
 import { normalizeTools } from "./agent-loop";
 import type { AgentContext } from "./types";
 
@@ -33,6 +34,7 @@ export interface StablePrefixSnapshot {
 export interface BuildOptions {
 	/** Inject the `_i` intent field into tool schemas (must match agent-loop's normalizeTools). */
 	intentTracing: boolean;
+	exampleSyntax?: ToolCallSyntax;
 }
 
 /**
@@ -268,7 +270,7 @@ export class AppendOnlyContextManager {
 
 function takeSnapshot(context: AgentContext, options: BuildOptions): StablePrefixSnapshot {
 	const systemPrompt = [...context.systemPrompt];
-	const tools = normalizeTools(context.tools, options.intentTracing) ?? [];
+	const tools = normalizeTools(context.tools, options.intentTracing, options.exampleSyntax) ?? [];
 	return {
 		systemPrompt,
 		tools,
@@ -288,6 +290,7 @@ function computeFingerprint(systemPrompt: string[], tools: Tool[], options: Buil
 			cw: t.customWireName,
 		})),
 		i: options.intentTracing,
+		ex: options.exampleSyntax,
 	});
 	let hash = 0;
 	for (let i = 0; i < payload.length; i++) {

package/src/index.ts

@@ -6,7 +6,6 @@ export * from "./agent-loop";
 export * from "./append-only-context";
 // Compaction
 export * from "./compaction";
-export * from "./harmony-leak";
 // Proxy utilities
 export * from "./proxy";
 // Run-level telemetry collector + aggregators

package/src/types.ts

@@ -17,8 +17,9 @@ import type {
 	ToolResultMessage,
 	TSchema,
 } from "@oh-my-pi/pi-ai";
+import type { ToolCallSyntax } from "@oh-my-pi/pi-ai/grammar";
+import type { HarmonyAuditEvent } from "@oh-my-pi/pi-ai/utils/harmony-leak";
 import type { AppendOnlyContextManager } from "./append-only-context";
-import type { HarmonyAuditEvent } from "./harmony-leak";
 import type { AgentRunCoverage, AgentRunSummary } from "./run-collector";
 import type { AgentTelemetryConfig } from "./telemetry";
 
@@ -199,6 +200,27 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * then strips from arguments before executing tools.
 	 */
 	intentTracing?: boolean;
+	/**
+	 * Owned tool calling syntax.
+	 *
+	 * Undefined keeps provider-native tool calling. A syntax value sends no
+	 * native `tools`, forces `toolChoice` off, appends that syntax's tool catalog
+	 * instructions, re-encodes prior tool calls/results as text, and parses the
+	 * model's text output back into canonical `toolCall` blocks.
+	 */
+	toolCallSyntax?: ToolCallSyntax;
+	/**
+	 * When owned (in-band) tool calling is active and the model starts
+	 * fabricating a tool result inside its own turn, control how the loop reacts:
+	 * - `true` (default): abort the provider request immediately so it stops
+	 *   generating the hallucinated continuation (cheaper, lower latency).
+	 * - `false`: let the request finish and silently discard everything past the
+	 *   fabrication boundary (keeps the connection alive but pays for the tokens
+	 *   the model spends on the discarded tail).
+	 * Only meaningful when {@link toolCallSyntax} (or `PI_OWNED_TOOLS`) selects an
+	 * owned syntax; native tool calling never fabricates results in text.
+	 */
+	abortOnFabricatedToolResult?: boolean;
 	/**
 	 * Append-only context mode — stabilizes system prompt + tool spec bytes
 	 * across turns so provider prefix caches hit at maximum rate.

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

@@ -1,118 +0,0 @@
-/**
- * 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 "@oh-my-pi/pi-ai";
-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 {};