@oh-my-pi/pi-agent-core 15.13.3 → 16.0.1

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [16.0.1] - 2026-06-15
+
+### Fixed
+
+- Fixed transient provider errors after streamed tool-call arguments so incomplete tool calls are marked as interrupted output instead of eligible for automatic retry ([#2683](https://github.com/can1357/oh-my-pi/issues/2683)).
+- Fixed `@oh-my-pi/pi-agent-core` telemetry content capture crashing every chat turn with `TypeError: systemPrompt.map is not a function` when `captureMessageContent` is enabled (`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true`). `ChatRequestSnapshot.systemPrompt` now accepts `string | readonly string[]` and the telemetry serializers normalize a bare string to a single-element array — previously the full-system serializer called `.map` on a string (the `.length` guard passed, so it threw) and the request-message serializer iterated the string into one `system` message per character.
+
+## [16.0.0] - 2026-06-15
+
+### Breaking Changes
+
+- Renamed owned tool-calling options from `toolCallSyntax`/`exampleSyntax` to `dialect`/`exampleDialect`.
+- Changed compaction conversation serialization to use the target model's native dialect turn, thinking, tool-call, and tool-result envelopes when a dialect is selected.
+- Renamed the owned dialect environment variable from `PI_OWNED_TOOLS` to `PI_DIALECT`.
+
+### Added
+
+- Added `onTurnEnd` hook support (`setOnTurnEnd`/`onTurnEnd`) to run awaited per-turn bookkeeping with current messages before the next model request and skip callback execution for aborted or error turns
+
+### Changed
+
+- Renamed `toolCallSyntax` option to `dialect` in AgentOptions and AgentLoopConfig
+- Updated conversation serialization to use dialect's native transcript rendering when a dialect is selected
+- Changed internal references from `ToolCallSyntax` type to `Dialect` type across agent loop and compaction modules
+
 ## [15.13.3] - 2026-06-15
 
 ### Added

package/dist/types/agent-loop.d.ts

@@ -3,9 +3,11 @@
  * Transforms to Message[] only at the LLM call boundary.
  */
 import { type Context, EventStream } from "@oh-my-pi/pi-ai";
-import { type ToolCallSyntax } from "@oh-my-pi/pi-ai/grammar";
+import { type Dialect } from "@oh-my-pi/pi-ai/dialect";
 import { type AgentRunCoverage, type AgentRunSummary } from "./run-collector";
 import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types";
+/** Stop-details marker for a provider error after assistant content/tool args already streamed. */
+export declare const STREAM_INTERRUPTED_AFTER_CONTENT_STOP_DETAIL = "stream_interrupted_after_content";
 /**
  * Start an agent loop with a new prompt message.
  * The prompt is added to the context and events are emitted for it.
@@ -53,7 +55,7 @@ export declare function agentLoopContinueDetailed(context: AgentContext, config:
     readonly detailed: () => Promise<AgentLoopDetailedResult>;
 };
 export declare const INTENT_FIELD = "_i";
-export declare function normalizeTools(tools: AgentContext["tools"], injectIntent: boolean, exampleSyntax?: ToolCallSyntax): Context["tools"];
+export declare function normalizeTools(tools: AgentContext["tools"], injectIntent: boolean, exampleDialect?: Dialect): Context["tools"];
 /** Resolve the human-readable reason an abort carried. A caller that aborts via
  *  `AbortController.abort(reason)` with a string or a non-`AbortError` `Error`
  *  (e.g. the coding agent's user-interrupt label) gets that text surfaced on the

package/dist/types/agent.d.ts

@@ -1,5 +1,5 @@
 import { type ApiKeyResolveContext, type AssistantMessage, type AssistantMessageEvent, type Context, type CursorExecHandlers, type CursorToolResultHandler, type Effort, type ImageContent, type Message, type Model, type ProviderSessionState, type ServiceTier, type SimpleStreamOptions, type ThinkingBudgets, type ToolChoice } from "@oh-my-pi/pi-ai";
-import type { ToolCallSyntax } from "@oh-my-pi/pi-ai/grammar";
+import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 import type { HarmonyAuditEvent } from "@oh-my-pi/pi-ai/utils/harmony-leak";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, AsideMessage, StreamFn, ToolCallContext } from "./types";
@@ -127,8 +127,8 @@ export interface AgentOptions {
     transformToolCallArguments?: (args: Record<string, unknown>, toolName: string) => Record<string, unknown>;
     /** Enable intent tracing schema injection/stripping in the harness. */
     intentTracing?: boolean;
-    /** Owned tool-calling syntax. Undefined keeps provider-native tool calling. */
-    toolCallSyntax?: ToolCallSyntax;
+    /** Owned tool-calling dialect. Undefined keeps provider-native tool calling. */
+    dialect?: Dialect;
     /**
      * When owned tool calling is active and the model fabricates a tool result
      * mid-turn: `true` (default) aborts the provider request immediately; `false`
@@ -299,6 +299,7 @@ export declare class Agent {
     setRawSseEventInterceptor(fn: SimpleStreamOptions["onSseEvent"] | undefined): void;
     setAssistantMessageEventInterceptor(fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined): void;
     setOnBeforeYield(fn: (() => Promise<void> | void) | undefined): void;
+    setOnTurnEnd(fn: ((messages: AgentMessage[], signal?: AbortSignal) => Promise<void> | void) | undefined): void;
     /**
      * Provide a source of non-interrupting "aside" messages (e.g. background-job
      * completions, late LSP diagnostics) drained at each step boundary. Never

package/dist/types/append-only-context.d.ts

@@ -14,7 +14,7 @@
  *    message delta is a cache miss each turn.
  */
 import type { Context, Message, Tool } from "@oh-my-pi/pi-ai";
-import type { ToolCallSyntax } from "@oh-my-pi/pi-ai/grammar";
+import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 import type { AgentContext } from "./types";
 /** Frozen system prompt + tool spec snapshot. */
 export interface StablePrefixSnapshot {
@@ -26,7 +26,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;
+    exampleDialect?: Dialect;
 }
 /**
  * A frozen prefix (system prompt + tools) that produces stable byte

package/dist/types/compaction/utils.d.ts

@@ -2,7 +2,7 @@
  * Shared utilities for compaction and branch summarization.
  */
 import type { Message } from "@oh-my-pi/pi-ai";
-import { type ToolCallSyntax } from "@oh-my-pi/pi-ai/grammar";
+import { type Dialect } from "@oh-my-pi/pi-ai/dialect";
 import type { AgentMessage } from "../types";
 export interface FileOperations {
     read: Set<string>;
@@ -45,5 +45,5 @@ export declare function upsertFileOperations(summary: string, readFiles: string[
  * This prevents the model from treating it as a conversation to continue.
  * Call convertToLlm() first to handle custom message types.
  */
-export declare function serializeConversation(messages: Message[], syntax?: ToolCallSyntax): string;
+export declare function serializeConversation(messages: Message[], dialect?: Dialect): string;
 export declare const SUMMARIZATION_SYSTEM_PROMPT: string;

package/dist/types/telemetry.d.ts

@@ -369,7 +369,7 @@ export interface ChatRequestSnapshot {
     readonly tools?: readonly {
         readonly name: string;
     }[];
-    readonly systemPrompt?: readonly string[];
+    readonly systemPrompt?: string | readonly string[];
     readonly messages?: readonly Message[];
 }
 /**

package/dist/types/types.d.ts

@@ -1,5 +1,5 @@
 import type { ApiKeyResolveContext, AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, Context, Effort, ImageContent, Message, Model, SimpleStreamOptions, Static, streamSimple, TextContent, Tool, ToolChoice, ToolResultMessage, TSchema } from "@oh-my-pi/pi-ai";
-import type { ToolCallSyntax } from "@oh-my-pi/pi-ai/grammar";
+import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 import type { HarmonyAuditEvent } from "@oh-my-pi/pi-ai/utils/harmony-leak";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import type { AgentRunCoverage, AgentRunSummary } from "./run-collector";
@@ -164,14 +164,14 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      */
     intentTracing?: boolean;
     /**
-     * Owned tool calling syntax.
+     * Owned tool calling dialect.
      *
-     * Undefined keeps provider-native tool calling. A syntax value sends no
-     * native `tools`, forces `toolChoice` off, appends that syntax's tool catalog
+     * Undefined keeps provider-native tool calling. A dialect value sends no
+     * native `tools`, forces `toolChoice` off, appends that dialect'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;
+    dialect?: Dialect;
     /**
      * 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:
@@ -180,8 +180,8 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * - `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.
+     * Only meaningful when {@link dialect} (or `PI_DIALECT`) selects an
+     * owned dialect; native tool calling never fabricates results in text.
      */
     abortOnFabricatedToolResult?: boolean;
     /**
@@ -236,6 +236,13 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * rest of the batch.
      */
     beforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined> | BeforeToolCallResult | undefined;
+    /**
+     * Called after a turn ends and before the loop polls steering/asides for the
+     * next iteration. Use this for awaited per-turn bookkeeping that must be
+     * visible before the next model request (e.g. synchronizing an advisor's
+     * backlog so advice produced during the wait is injected as an aside).
+     */
+    onTurnEnd?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<void> | void;
     /**
      * Called after a tool finishes executing, before `tool_execution_end` and the
      * tool-result message are emitted.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "15.13.3",
+	"version": "16.0.1",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -35,11 +35,11 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "15.13.3",
-		"@oh-my-pi/pi-catalog": "15.13.3",
-		"@oh-my-pi/pi-natives": "15.13.3",
-		"@oh-my-pi/pi-utils": "15.13.3",
-		"@oh-my-pi/snapcompact": "15.13.3",
+		"@oh-my-pi/pi-ai": "16.0.1",
+		"@oh-my-pi/pi-catalog": "16.0.1",
+		"@oh-my-pi/pi-natives": "16.0.1",
+		"@oh-my-pi/pi-utils": "16.0.1",
+		"@oh-my-pi/snapcompact": "16.0.1",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -16,12 +16,12 @@ import {
 	zodToWireSchema,
 } from "@oh-my-pi/pi-ai";
 import {
+	type Dialect,
 	encodeInbandToolHistory,
 	renderInbandToolPrompt,
 	renderToolExamples,
-	type ToolCallSyntax,
 	wrapInbandToolStream,
-} from "@oh-my-pi/pi-ai/grammar";
+} from "@oh-my-pi/pi-ai/dialect";
 import {
 	createHarmonyAuditEvent,
 	detectHarmonyLeakInAssistantMessage,
@@ -32,7 +32,7 @@ import {
 	recoverHarmonyToolCall,
 	signalListLabel,
 } from "@oh-my-pi/pi-ai/utils/harmony-leak";
-import { preferredToolSyntax } from "@oh-my-pi/pi-catalog/identity";
+import { preferredDialect } 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 {
@@ -63,6 +63,9 @@ import type {
 } from "./types";
 import { yieldIfDue } from "./utils/yield";
 
+/** Stop-details marker for a provider error after assistant content/tool args already streamed. */
+export const STREAM_INTERRUPTED_AFTER_CONTENT_STOP_DETAIL = "stream_interrupted_after_content";
+
 /** Sentinel returned by the abort race in `streamAssistantResponse`. */
 const ABORTED: unique symbol = Symbol("agent-loop-aborted");
 
@@ -92,7 +95,7 @@ class HarmonyLeakInterruption extends Error {
 		this.name = "HarmonyLeakInterruption";
 	}
 }
-function resolveOwnedToolSyntaxFromEnv(value: string | undefined): ToolCallSyntax | undefined {
+function resolveOwnedDialectFromEnv(value: string | undefined): Dialect | undefined {
 	switch (value) {
 		case "1":
 		case "true":
@@ -371,6 +374,25 @@ function buildAgentEndEvent(
 	}
 	return { type: "agent_end", messages, telemetry: snapshot.summary, coverage: snapshot.coverage };
 }
+/**
+ * Push a `turn_end` event and run the awaited per-turn hook when the run is
+ * still healthy. The hook is skipped for externally aborted or errored turns so
+ * a user interrupt does not hang on a background backlog wait.
+ */
+async function emitTurnEnd(
+	stream: EventStream<AgentEvent, AgentMessage[]>,
+	currentContext: AgentContext,
+	message: AgentMessage,
+	toolResults: ToolResultMessage[],
+	config: AgentLoopConfig,
+	signal?: AbortSignal,
+): Promise<void> {
+	stream.push({ type: "turn_end", message, toolResults });
+	const isAbortedOrError =
+		message.role === "assistant" && (message.stopReason === "aborted" || message.stopReason === "error");
+	if (signal?.aborted || isAbortedOrError) return;
+	await config.onTurnEnd?.(currentContext.messages, signal);
+}
 
 /**
  * Detailed-result handle returned by {@link agentLoopDetailed}. Adds the
@@ -531,7 +553,7 @@ function injectIntentIntoSchema(schema: unknown, mode: "require" | "optional" =
 export function normalizeTools(
 	tools: AgentContext["tools"],
 	injectIntent: boolean,
-	exampleSyntax?: ToolCallSyntax,
+	exampleDialect?: Dialect,
 ): Context["tools"] {
 	injectIntent = injectIntent && Bun.env.PI_NO_INTENT !== "1";
 	return tools?.map(t => {
@@ -547,8 +569,8 @@ export function normalizeTools(
 		}
 		const description = t.description ?? "";
 		const injectExampleIntent = injectIntent && intentMode !== "omit";
-		const examplesBlock = exampleSyntax
-			? renderToolExamples({ ...t, parameters }, exampleSyntax, injectExampleIntent ? INTENT_FIELD : undefined)
+		const examplesBlock = exampleDialect
+			? renderToolExamples({ ...t, parameters }, exampleDialect, injectExampleIntent ? INTENT_FIELD : undefined)
 			: "";
 		const finalDescription = examplesBlock ? `${description}\n\n${examplesBlock}` : description;
 		return { ...t, parameters, description: finalDescription };
@@ -754,7 +776,7 @@ async function runLoopBody(
 						status: message.stopReason === "aborted" ? "aborted" : "error",
 					});
 				}
-				stream.push({ type: "turn_end", message, toolResults });
+				await emitTurnEnd(stream, currentContext, message, toolResults, config, signal);
 
 				stream.push(buildAgentEndEvent(newMessages, telemetry, stepCounter.count));
 				stream.end(newMessages);
@@ -839,7 +861,7 @@ async function runLoopBody(
 				hasMoreToolCalls = true;
 			}
 
-			stream.push({ type: "turn_end", message, toolResults });
+			await emitTurnEnd(stream, currentContext, message, toolResults, config, signal);
 
 			// On external abort (user interrupt), leave the steering queue intact: the
 			// session aborts then continues, delivering the queue into a fresh run.
@@ -925,6 +947,8 @@ async function streamAssistantResponse(
 	const llmMessages = await config.convertToLlm(messages);
 	const normalizedMessages = normalizeMessagesForProvider(llmMessages, config.model);
 
+	const ownedDialect: Dialect | undefined = config.dialect ?? resolveOwnedDialectFromEnv(Bun.env.PI_DIALECT);
+	const exampleDialect = ownedDialect ?? preferredDialect(config.model.id);
 	// Build LLM context — append-only mode caches system prompt + tools
 	// AND keeps an append-only message log so prior-turn bytes are stable.
 	let llmContext: Context;
@@ -932,13 +956,13 @@ async function streamAssistantResponse(
 		config.appendOnlyContext.syncMessages(normalizedMessages);
 		llmContext = config.appendOnlyContext.build(context, {
 			intentTracing: !!config.intentTracing,
-			exampleSyntax: preferredToolSyntax(config.model.id),
+			exampleDialect,
 		});
 	} else {
 		llmContext = {
 			systemPrompt: context.systemPrompt,
 			messages: normalizedMessages,
-			tools: normalizeTools(context.tools, !!config.intentTracing, preferredToolSyntax(config.model.id)),
+			tools: normalizeTools(context.tools, !!config.intentTracing, exampleDialect),
 		};
 	}
 	if (config.transformProviderContext) {
@@ -946,17 +970,15 @@ async function streamAssistantResponse(
 	}
 
 	// 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);
+	// through the selected in-band prompt dialect. `PI_DIALECT=1` still
+	// force-enables GLM; `PI_DIALECT=<dialect>` force-enables that dialect.
 	let promptToolWireTools: Context["tools"];
-	if (ownedSyntax && llmContext.tools && llmContext.tools.length > 0) {
+	if (ownedDialect && llmContext.tools && llmContext.tools.length > 0) {
 		promptToolWireTools = llmContext.tools;
 		llmContext = {
 			...llmContext,
-			systemPrompt: [...(llmContext.systemPrompt ?? []), renderInbandToolPrompt(promptToolWireTools, ownedSyntax)],
-			messages: encodeInbandToolHistory(llmContext.messages, ownedSyntax, promptToolWireTools),
+			systemPrompt: [...(llmContext.systemPrompt ?? []), renderInbandToolPrompt(promptToolWireTools, ownedDialect)],
+			messages: encodeInbandToolHistory(llmContext.messages, ownedDialect, promptToolWireTools),
 			tools: undefined,
 		};
 	}
@@ -990,7 +1012,7 @@ async function streamAssistantResponse(
 	// 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 promptToolAbortController = ownedDialect ? new AbortController() : undefined;
 	const providerAbortSignals: AbortSignal[] = [];
 	if (requestSignal) providerAbortSignals.push(requestSignal);
 	providerAbortSignals.push(repetitionAbortController.signal);
@@ -1000,7 +1022,7 @@ async function streamAssistantResponse(
 	const effectiveTemperature =
 		harmonyRetryAttempt > 0 && config.temperature !== undefined ? config.temperature + 0.05 : config.temperature;
 	// Owned tool calling sends no native tools, so any tool_choice would error.
-	const effectiveToolChoice = ownedSyntax ? undefined : (dynamicToolChoice ?? config.toolChoice);
+	const effectiveToolChoice = ownedDialect ? undefined : (dynamicToolChoice ?? config.toolChoice);
 	const effectiveReasoning = dynamicReasoning ?? config.reasoning;
 	const effectiveDisableReasoning = dynamicDisableReasoning ?? config.disableReasoning;
 
@@ -1068,7 +1090,7 @@ async function streamAssistantResponse(
 				signal: finalRequestSignal,
 				onResponse: captureOnResponse,
 			});
-			if (promptToolWireTools && ownedSyntax) {
+			if (promptToolWireTools && ownedDialect) {
 				// 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
@@ -1077,7 +1099,7 @@ async function streamAssistantResponse(
 				response = wrapInbandToolStream(
 					response,
 					promptToolWireTools,
-					ownedSyntax,
+					ownedDialect,
 					() => promptToolAbortController?.abort(),
 					config.abortOnFabricatedToolResult ?? true,
 				);
@@ -1336,14 +1358,26 @@ function retainCompletedToolCalls(
 	completedToolCallIds: ReadonlySet<string>,
 ): AssistantMessage {
 	if (message.stopReason !== "error" && message.stopReason !== "aborted") return message;
-	let changed = false;
+	let droppedIncompleteToolCall = false;
 	const content = message.content.filter(block => {
 		if (block.type !== "toolCall") return true;
 		const keep = completedToolCallIds.has(block.id);
-		if (!keep) changed = true;
+		if (!keep) droppedIncompleteToolCall = true;
 		return keep;
 	});
-	return changed ? { ...message, content } : message;
+	if (!droppedIncompleteToolCall) return message;
+	return {
+		...message,
+		content,
+		stopDetails:
+			message.stopDetails?.type === STREAM_INTERRUPTED_AFTER_CONTENT_STOP_DETAIL
+				? message.stopDetails
+				: {
+						type: STREAM_INTERRUPTED_AFTER_CONTENT_STOP_DETAIL,
+						category: message.stopDetails?.type ?? null,
+						explanation: message.stopDetails?.explanation ?? null,
+					},
+	};
 }
 
 function emitDiscardedHarmonyPartial(

package/src/agent.ts

@@ -22,7 +22,7 @@ import {
 	type ToolChoice,
 	type ToolResultMessage,
 } from "@oh-my-pi/pi-ai";
-import type { ToolCallSyntax } from "@oh-my-pi/pi-ai/grammar";
+import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 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";
@@ -221,8 +221,8 @@ 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;
+	/** Owned tool-calling dialect. Undefined keeps provider-native tool calling. */
+	dialect?: Dialect;
 	/**
 	 * When owned tool calling is active and the model fabricates a tool result
 	 * mid-turn: `true` (default) aborts the provider request immediately; `false`
@@ -326,7 +326,7 @@ export class Agent {
 	#preferWebsockets?: boolean;
 	#transformToolCallArguments?: (args: Record<string, unknown>, toolName: string) => Record<string, unknown>;
 	#intentTracing: boolean;
-	#toolCallSyntax?: ToolCallSyntax;
+	#dialect?: Dialect;
 	#abortOnFabricatedToolResult?: boolean;
 	#getToolChoice?: () => ToolChoice | undefined;
 	#onPayload?: SimpleStreamOptions["onPayload"];
@@ -335,6 +335,7 @@ export class Agent {
 	#onAssistantMessageEvent?: (message: AssistantMessage, event: AssistantMessageEvent) => void;
 	#onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
 	#onBeforeYield?: () => Promise<void> | void;
+	#onTurnEnd?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<void> | void;
 	#asideMessageProvider?: () => AsideMessage[] | Promise<AsideMessage[]>;
 	#telemetry?: AgentLoopConfig["telemetry"];
 	#appendOnlyContext?: AppendOnlyContextManager;
@@ -390,7 +391,7 @@ export class Agent {
 		this.#preferWebsockets = opts.preferWebsockets;
 		this.#transformToolCallArguments = opts.transformToolCallArguments;
 		this.#intentTracing = opts.intentTracing === true;
-		this.#toolCallSyntax = opts.toolCallSyntax;
+		this.#dialect = opts.dialect;
 		this.#abortOnFabricatedToolResult = opts.abortOnFabricatedToolResult;
 		this.#getToolChoice = opts.getToolChoice;
 		this.#onAssistantMessageEvent = opts.onAssistantMessageEvent;
@@ -639,6 +640,9 @@ export class Agent {
 	setOnBeforeYield(fn: (() => Promise<void> | void) | undefined): void {
 		this.#onBeforeYield = fn;
 	}
+	setOnTurnEnd(fn: ((messages: AgentMessage[], signal?: AbortSignal) => Promise<void> | void) | undefined): void {
+		this.#onTurnEnd = fn;
+	}
 
 	/**
 	 * Provide a source of non-interrupting "aside" messages (e.g. background-job
@@ -1037,13 +1041,14 @@ export class Agent {
 			cursorOnToolResult,
 			transformToolCallArguments: this.#transformToolCallArguments,
 			intentTracing: this.#intentTracing,
-			toolCallSyntax: this.#toolCallSyntax,
+			dialect: this.#dialect,
 			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,
 			onAssistantMessageEvent: this.#onAssistantMessageEvent,
 			onHarmonyLeak: this.#onHarmonyLeak,
+			onTurnEnd: (messages, signal) => this.#onTurnEnd?.(messages, signal),
 			getToolChoice,
 			getReasoning: () => this.#state.thinkingLevel,
 			getDisableReasoning: () => this.#state.disableReasoning,

package/src/append-only-context.ts

@@ -15,7 +15,7 @@
  */
 
 import type { Context, Message, Tool } from "@oh-my-pi/pi-ai";
-import type { ToolCallSyntax } from "@oh-my-pi/pi-ai/grammar";
+import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 import { normalizeTools } from "./agent-loop";
 import type { AgentContext } from "./types";
 
@@ -34,7 +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;
+	exampleDialect?: Dialect;
 }
 
 /**
@@ -270,7 +270,7 @@ export class AppendOnlyContextManager {
 
 function takeSnapshot(context: AgentContext, options: BuildOptions): StablePrefixSnapshot {
 	const systemPrompt = [...context.systemPrompt];
-	const tools = normalizeTools(context.tools, options.intentTracing, options.exampleSyntax) ?? [];
+	const tools = normalizeTools(context.tools, options.intentTracing, options.exampleDialect) ?? [];
 	return {
 		systemPrompt,
 		tools,
@@ -290,7 +290,7 @@ function computeFingerprint(systemPrompt: string[], tools: Tool[], options: Buil
 			cw: t.customWireName,
 		})),
 		i: options.intentTracing,
-		ex: options.exampleSyntax,
+		ex: options.exampleDialect,
 	});
 	let hash = 0;
 	for (let i = 0; i < payload.length; i++) {

package/src/compaction/branch-summarization.ts

@@ -6,7 +6,7 @@
  */
 
 import type { ApiKey, Model } from "@oh-my-pi/pi-ai";
-import { preferredToolSyntax } from "@oh-my-pi/pi-catalog/identity";
+import { preferredDialect } from "@oh-my-pi/pi-catalog/identity";
 import { prompt } from "@oh-my-pi/pi-utils";
 import { type AgentTelemetry, instrumentedCompleteSimple } from "../telemetry";
 import type { AgentMessage } from "../types";
@@ -291,7 +291,7 @@ export async function generateBranchSummary(
 	// Transform to LLM-compatible messages, then serialize to text
 	// Serialization prevents the model from treating it as a conversation to continue
 	const llmMessages = (options.convertToLlm ?? defaultConvertToLlm)(messages);
-	const conversationText = serializeConversation(llmMessages, preferredToolSyntax(model.id));
+	const conversationText = serializeConversation(llmMessages, preferredDialect(model.id));
 
 	// Build prompt
 	const instructions = customInstructions || BRANCH_SUMMARY_PROMPT;

package/src/compaction/compaction.ts

@@ -18,7 +18,7 @@ import {
 	type Usage,
 	withAuth,
 } from "@oh-my-pi/pi-ai";
-import { preferredToolSyntax } from "@oh-my-pi/pi-catalog/identity";
+import { preferredDialect } from "@oh-my-pi/pi-catalog/identity";
 import { clampThinkingLevelForModel } from "@oh-my-pi/pi-catalog/model-thinking";
 import { countTokens } from "@oh-my-pi/pi-natives";
 import { logger, prompt } from "@oh-my-pi/pi-utils";
@@ -643,7 +643,7 @@ export async function generateSummary(
 	// Serialize conversation to text so model doesn't try to continue it
 	// Convert to LLM messages first (handles custom app messages when caller provides a transformer).
 	const llmMessages = (options?.convertToLlm ?? defaultConvertToLlm)(currentMessages);
-	const conversationText = serializeConversation(llmMessages, preferredToolSyntax(model.id));
+	const conversationText = serializeConversation(llmMessages, preferredDialect(model.id));
 
 	// Build the prompt with conversation wrapped in tags
 	let promptText = `<conversation>\n${conversationText}\n</conversation>\n\n`;
@@ -791,7 +791,7 @@ async function generateShortSummary(
 ): Promise<string> {
 	const maxTokens = Math.min(512, Math.floor(0.2 * reserveTokens));
 	const llmMessages = (options?.convertToLlm ?? defaultConvertToLlm)(recentMessages);
-	const conversationText = serializeConversation(llmMessages, preferredToolSyntax(model.id));
+	const conversationText = serializeConversation(llmMessages, preferredDialect(model.id));
 
 	let promptText = `<conversation>\n${conversationText}\n</conversation>\n\n`;
 	if (historySummary) {
@@ -1156,7 +1156,7 @@ async function generateTurnPrefixSummary(
 	const maxTokens = Math.floor(0.5 * reserveTokens); // Smaller budget for turn prefix
 
 	const llmMessages = (options?.convertToLlm ?? defaultConvertToLlm)(messages);
-	const conversationText = serializeConversation(llmMessages, preferredToolSyntax(model.id));
+	const conversationText = serializeConversation(llmMessages, preferredDialect(model.id));
 	const promptText = `<conversation>\n${conversationText}\n</conversation>\n\n${TURN_PREFIX_SUMMARIZATION_PROMPT}`;
 	const summarizationMessages = [
 		{

package/src/compaction/utils.ts

@@ -3,7 +3,7 @@
  */
 
 import type { Message, ToolCall } from "@oh-my-pi/pi-ai";
-import { type Grammar, type GrammarToolResult, getInbandGrammar, type ToolCallSyntax } from "@oh-my-pi/pi-ai/grammar";
+import { type Dialect, getDialectDefinition } from "@oh-my-pi/pi-ai/dialect";
 import { formatGroupedPaths, prompt } from "@oh-my-pi/pi-utils";
 import type { AgentMessage } from "../types";
 import fileOperationsTemplate from "./prompts/file-operations.md" with { type: "text" };
@@ -189,10 +189,7 @@ function truncateForSummary(text: string, maxChars: number): string {
  * This prevents the model from treating it as a conversation to continue.
  * Call convertToLlm() first to handle custom message types.
  */
-export function serializeConversation(messages: Message[], syntax?: ToolCallSyntax): string {
-	const grammar = syntax ? getInbandGrammar(syntax) : undefined;
-	const parts: string[] = [];
-
+export function serializeConversation(messages: Message[], dialect?: Dialect): string {
 	// Tool results flagged contextually useless (and their paired calls) are
 	// dropped from the serialized text: the source region is discarded after
 	// summarization anyway, so excluding them costs nothing and keeps garbage
@@ -203,7 +200,33 @@ export function serializeConversation(messages: Message[], syntax?: ToolCallSynt
 			uselessCallIds.add(msg.toolCallId);
 		}
 	}
+	if (dialect) {
+		const processed: Message[] = [];
+		for (const msg of messages) {
+			if (msg.role === "assistant") {
+				const content = msg.content.filter(block => block.type !== "toolCall" || !uselessCallIds.has(block.id));
+				if (content.length > 0) processed.push(content.length === msg.content.length ? msg : { ...msg, content });
+				continue;
+			}
+			if (msg.role === "toolResult") {
+				if (uselessCallIds.has(msg.toolCallId)) continue;
+				const text = msg.content
+					.filter((c): c is { type: "text"; text: string } => c.type === "text")
+					.map(c => c.text)
+					.join("");
+				if (!text) continue;
+				processed.push({
+					...msg,
+					content: [{ type: "text", text: truncateForSummary(text, TOOL_RESULT_MAX_CHARS) }],
+				});
+				continue;
+			}
+			processed.push(msg);
+		}
+		return getDialectDefinition(dialect).renderTranscript(processed);
+	}
 
+	const parts: string[] = [];
 	for (const msg of messages) {
 		if (msg.role === "user") {
 			const content =
@@ -237,7 +260,7 @@ export function serializeConversation(messages: Message[], syntax?: ToolCallSynt
 				parts.push(`[Assistant]: ${textParts.join("\n")}`);
 			}
 			if (toolCalls.length > 0) {
-				parts.push(`[Tool Call]: ${renderToolCalls(toolCalls, grammar)}`);
+				parts.push(`[Tool Call]: ${renderToolCalls(toolCalls)}`);
 			}
 		} else if (msg.role === "toolResult") {
 			if (uselessCallIds.has(msg.toolCallId)) continue;
@@ -247,9 +270,7 @@ export function serializeConversation(messages: Message[], syntax?: ToolCallSynt
 				.join("");
 			if (content) {
 				const text = truncateForSummary(content, TOOL_RESULT_MAX_CHARS);
-				parts.push(
-					`[Tool Result]: ${renderToolResult(msg.toolCallId, msg.toolName, msg.isError === true, text, grammar)}`,
-				);
+				parts.push(`[Tool Result]: ${text}`);
 			}
 		}
 	}
@@ -258,11 +279,10 @@ export function serializeConversation(messages: Message[], syntax?: ToolCallSynt
 }
 
 /**
- * Render an assistant turn's tool calls. With a grammar, emit the model's
- * native invocation block; otherwise fall back to a compact `name(args)` list.
+ * Render an assistant turn's tool calls as a compact `name(args)` list for the
+ * legacy serializer.
  */
-function renderToolCalls(calls: ToolCall[], grammar: Grammar | undefined): string {
-	if (grammar) return grammar.renderAssistantToolCalls(calls);
+function renderToolCalls(calls: ToolCall[]): string {
 	return calls
 		.map(call => {
 			const argsStr = Object.entries(call.arguments as Record<string, unknown>)
@@ -273,22 +293,6 @@ function renderToolCalls(calls: ToolCall[], grammar: Grammar | undefined): strin
 		.join("; ");
 }
 
-/**
- * Render a single tool result. With a grammar, emit the model's native
- * tool-result envelope; otherwise return the (already truncated) text verbatim.
- */
-function renderToolResult(
-	id: string,
-	name: string,
-	isError: boolean,
-	text: string,
-	grammar: Grammar | undefined,
-): string {
-	if (!grammar) return text;
-	const result: GrammarToolResult = { id, name, index: 0, text, isError };
-	return grammar.renderToolResults([result]);
-}
-
 // ============================================================================
 // Summarization System Prompt
 // ============================================================================

package/src/telemetry.ts

@@ -731,7 +731,7 @@ export interface ChatRequestSnapshot {
 	readonly reasoningEffort?: string;
 	readonly toolChoice?: ToolChoice;
 	readonly tools?: readonly { readonly name: string }[];
-	readonly systemPrompt?: readonly string[];
+	readonly systemPrompt?: string | readonly string[];
 	readonly messages?: readonly Message[];
 }
 
@@ -796,6 +796,11 @@ function applyContentCaptureForResponse(telemetry: AgentTelemetry, span: Span, m
 	}
 }
 
+function normalizeSystemPromptParts(systemPrompt: string | readonly string[] | undefined): readonly string[] {
+	if (!systemPrompt) return [];
+	return typeof systemPrompt === "string" ? [systemPrompt] : systemPrompt;
+}
+
 function serializeRequestMessagesForTelemetry(
 	telemetry: AgentTelemetry,
 	request: ChatRequestSnapshot,
@@ -803,10 +808,8 @@ function serializeRequestMessagesForTelemetry(
 	const serializer = telemetry.config.contentSerializer?.requestMessages;
 	if (serializer) return callContentSerializer(telemetry, "requestMessages", () => serializer(request));
 	const messages: TelemetryMessageSummary[] = [];
-	if (request.systemPrompt) {
-		for (const text of request.systemPrompt)
-			messages.push({ role: "system", content: summarizeTelemetryValue(text) });
-	}
+	for (const text of normalizeSystemPromptParts(request.systemPrompt))
+		messages.push({ role: "system", content: summarizeTelemetryValue(text) });
 	if (request.messages) {
 		for (const message of request.messages) {
 			messages.push({ role: message.role, content: summarizeTelemetryValue(message.content) });
@@ -874,8 +877,8 @@ interface OtelOutputMessage extends OtelInputMessage {
 }
 
 function serializeFullSystemInstructionsForTelemetry(request: ChatRequestSnapshot): string | undefined {
-	const systemPrompt = request.systemPrompt;
-	if (!systemPrompt || systemPrompt.length === 0) return undefined;
+	const systemPrompt = normalizeSystemPromptParts(request.systemPrompt);
+	if (systemPrompt.length === 0) return undefined;
 	return stringifyJsonAttribute(systemPrompt.map(text => ({ type: "text", content: text }) satisfies OtelMessagePart));
 }
 

package/src/types.ts

@@ -17,7 +17,7 @@ import type {
 	ToolResultMessage,
 	TSchema,
 } from "@oh-my-pi/pi-ai";
-import type { ToolCallSyntax } from "@oh-my-pi/pi-ai/grammar";
+import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 import type { HarmonyAuditEvent } from "@oh-my-pi/pi-ai/utils/harmony-leak";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import type { AgentRunCoverage, AgentRunSummary } from "./run-collector";
@@ -201,14 +201,14 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 */
 	intentTracing?: boolean;
 	/**
-	 * Owned tool calling syntax.
+	 * Owned tool calling dialect.
 	 *
-	 * Undefined keeps provider-native tool calling. A syntax value sends no
-	 * native `tools`, forces `toolChoice` off, appends that syntax's tool catalog
+	 * Undefined keeps provider-native tool calling. A dialect value sends no
+	 * native `tools`, forces `toolChoice` off, appends that dialect'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;
+	dialect?: Dialect;
 	/**
 	 * 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:
@@ -217,8 +217,8 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * - `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.
+	 * Only meaningful when {@link dialect} (or `PI_DIALECT`) selects an
+	 * owned dialect; native tool calling never fabricates results in text.
 	 */
 	abortOnFabricatedToolResult?: boolean;
 	/**
@@ -282,6 +282,13 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 		context: BeforeToolCallContext,
 		signal?: AbortSignal,
 	) => Promise<BeforeToolCallResult | undefined> | BeforeToolCallResult | undefined;
+	/**
+	 * Called after a turn ends and before the loop polls steering/asides for the
+	 * next iteration. Use this for awaited per-turn bookkeeping that must be
+	 * visible before the next model request (e.g. synchronizing an advisor's
+	 * backlog so advice produced during the wait is injected as an aside).
+	 */
+	onTurnEnd?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<void> | void;
 
 	/**
 	 * Called after a tool finishes executing, before `tool_execution_end` and the