@oh-my-pi/pi-ai 17.2.4 → 17.2.6

package/src/dialect/gemini.ts

@@ -2,7 +2,13 @@ import type { Message, ToolCall } from "../types";
 import { mintToolCallId, partialSuffixOverlapAny } from "./coercion";
 import { FencedThinkingScanner } from "./fenced-thinking";
 import dialectPrompt from "./gemini.md" with { type: "text" };
-import { assistantTranscriptParts, collectToolResultRun, joinUserBodies, messageContentText } from "./rendering";
+import {
+	assistantTranscriptParts,
+	collectToolResultRun,
+	joinUserBodies,
+	messageContentText,
+	pyValue,
+} from "./rendering";
 import type {
 	DialectDefinition,
 	DialectRenderOptions,
@@ -494,11 +500,15 @@ function topLevelIndexOf(text: string, ch: string): number {
 	return -1;
 }
 
-function renderToolCall(call: ToolCall, options: DialectRenderOptions = {}): string {
-	const kwargs = Object.entries(call.arguments)
-		.map(([key, value]) => `${key}=${pyValue(value)}`)
-		.join(", ");
-	return options.example ? `${call.name}(${kwargs})` : `default_api.${call.name}(${kwargs})`;
+function renderToolCall(call: ToolCall, _options: DialectRenderOptions = {}): string {
+	// Always escaped single-line literals: the scanner round-trips this wire
+	// form through unescapePythonString, so pyCall's verbatim `"""` example
+	// blocks would corrupt backslash-bearing content.
+	let kwargs = "";
+	for (const key in call.arguments) {
+		kwargs += `${kwargs ? ", " : ""}${key}=${pyValue(call.arguments[key])}`;
+	}
+	return `default_api.${call.name}(${kwargs})`;
 }
 
 function renderAssistantToolCalls(calls: readonly ToolCall[], options: DialectRenderOptions = {}): string {
@@ -507,8 +517,7 @@ function renderAssistantToolCalls(calls: readonly ToolCall[], options: DialectRe
 		calls.length === 1
 			? renderToolCall(calls[0]!, options)
 			: `[${calls.map(call => renderToolCall(call, options)).join(", ")}]`;
-	// Examples show the bare call; the live wire form fences it as `tool_code`.
-	return options.example ? body : `${CODE_OPEN}\n${body}\n${FENCE}`;
+	return `${CODE_OPEN}\n${body}\n${FENCE}`;
 }
 
 function renderToolResults(results: readonly DialectToolResult[]): string {
@@ -560,29 +569,6 @@ function geminiTurn(role: "model" | "user", body: string): string {
 	return `<start_of_turn>${role}\n${body}<end_of_turn>\n`;
 }
 
-function pyValue(value: unknown): string {
-	if (value === null || value === undefined) return "None";
-	if (typeof value === "boolean") return value ? "True" : "False";
-	if (typeof value === "number") return Number.isFinite(value) ? String(value) : pyString(String(value));
-	if (typeof value === "string") return pyString(value);
-	if (Array.isArray(value)) return `[${value.map(pyValue).join(", ")}]`;
-	if (typeof value === "object") {
-		const entries = Object.entries(value as Record<string, unknown>);
-		return `{${entries.map(([key, val]) => `${pyString(key)}: ${pyValue(val)}`).join(", ")}}`;
-	}
-	return pyString(String(value));
-}
-
-function pyString(value: string): string {
-	const escaped = value
-		.replaceAll("\\", "\\\\")
-		.replaceAll('"', '\\"')
-		.replaceAll("\n", "\\n")
-		.replaceAll("\r", "\\r")
-		.replaceAll("\t", "\\t");
-	return `"${escaped}"`;
-}
-
 const definition: DialectDefinition = {
 	dialect: "gemini",
 	prompt: dialectPrompt,

package/src/dialect/harmony.ts

@@ -273,8 +273,7 @@ function parseRecipient(header: string): string {
 	return match?.[1] ?? "";
 }
 
-function renderToolCall(call: ToolCall, options: DialectRenderOptions = {}): string {
-	if (options.example) return stringifyJson(call.arguments);
+function renderToolCall(call: ToolCall, _options: DialectRenderOptions = {}): string {
 	return `${START}assistant${CHANNEL}commentary to=${harmonyRecipient(call.name)}${MESSAGE}${stringifyJson(call.arguments)}${CALL}`;
 }
 

package/src/dialect/inventory.ts

@@ -1,73 +1,30 @@
-import { preferredDialect } from "@oh-my-pi/pi-catalog/identity";
 import { jsonSchemaToTypeScript, toolWireSchema } from "../utils/schema";
-import { renderToolExamples } from "./examples";
+import { renderToolExamplesJsdoc } from "./examples";
 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 dialect. 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 dialect is resolved from it
- * (`preferredDialect`, which falls back to XML for empty/unknown ids).
+ * Tool catalog in the OpenAI-Harmony `namespace functions { … }` shape: each
+ * tool renders as its full description (and Python-syntax examples) as `//`
+ * comment lines above a flat `type <name> = (_: {…});` declaration. Shared by
+ * the verbose system-prompt inventory and `/dump` so both render the catalog
+ * the same way.
  */
-export function renderToolInventory(tools: readonly InbandTool[], model: string): string {
+export function renderToolInventory(tools: readonly InbandTool[]): string {
 	if (tools.length === 0) return "";
-	const dialect = preferredDialect(model);
-	return tools
-		.map(tool => {
-			const params = jsonSchemaToTypeScript(toolWireSchema(tool));
-			const examples = renderToolExamples(tool, dialect);
-			const description = demoteDescriptionHeaders(tool.description ?? "");
-			const parts = [`# Tool: ${tool.name}`, description, "", `Parameters: ${params}`];
-			if (examples) parts.push("", examples);
-			return parts.join("\n");
-		})
-		.join("\n\n");
-}
-
-const FENCE = /^ {0,3}(`{3,}|~{3,})/;
-const ATX = /^ {0,3}#{1,6}( |\t|$)/;
-const TOP_LEVEL = /^ {0,3}#( |\t|$)/;
-
-/**
- * Each description is rendered under a `# Tool: <name>` heading. When the
- * description carries its own top-level (`# `) markdown headers they sit at the
- * same level as that wrapper, so the section structure flattens and the
- * description's headers read like sibling tools. Demote every ATX header in the
- * description by one level so the whole block nests under `# Tool: <name>`.
- *
- * Only triggered when a level-1 header is actually present — descriptions that
- * already start at `##` are left untouched. Headers inside fenced code blocks
- * are never rewritten.
- */
-function demoteDescriptionHeaders(description: string): string {
-	const lines = description.split("\n");
-
-	let fence: string | undefined;
-	let collides = false;
-	for (const line of lines) {
-		const marker = FENCE.exec(line)?.[1][0];
-		if (marker) {
-			fence = fence === undefined ? marker : fence === marker ? undefined : fence;
-		} else if (fence === undefined && TOP_LEVEL.test(line)) {
-			collides = true;
-			break;
+	const declarations = tools.map(tool => {
+		const params = jsonSchemaToTypeScript(toolWireSchema(tool), { style: "harmony" });
+		const lines: string[] = [];
+		const description = tool.description ?? "";
+		if (description) {
+			for (const line of description.split("\n")) lines.push(`// ${line}`.trimEnd());
 		}
-	}
-	if (!collides) return description;
-
-	fence = undefined;
-	for (let i = 0; i < lines.length; i++) {
-		const line = lines[i];
-		const marker = FENCE.exec(line)?.[1][0];
-		if (marker) {
-			fence = fence === undefined ? marker : fence === marker ? undefined : fence;
-		} else if (fence === undefined && ATX.test(line)) {
-			lines[i] = line.replace(/^( {0,3})#/, "$1##");
+		const examples = renderToolExamplesJsdoc(tool);
+		if (examples) {
+			if (description) lines.push("//");
+			for (const line of examples.split("\n")) lines.push(`// ${line}`.trimEnd());
 		}
-	}
-	return lines.join("\n");
+		lines.push(params === "{}" ? `type ${tool.name} = ();` : `type ${tool.name} = (_: ${params});`);
+		return lines.join("\n");
+	});
+	return `## functions\n\nnamespace functions {\n\n${declarations.join("\n\n")}\n\n} // namespace functions`;
 }

package/src/dialect/rendering.ts

@@ -19,6 +19,60 @@ export function stringifyJson(value: unknown): string {
 	return stringifyJsonValue(value) ?? "null";
 }
 
+/**
+ * Render `name(key=value, …)` with Python-literal argument values. Top-level
+ * multiline strings render as verbatim `"""…"""` blocks so payload-carrying
+ * args (file content, scripts, patches) keep real newlines instead of `\n`
+ * escape soup; nested values always use escaped single-line literals.
+ */
+export function pyCall(name: string, args: Record<string, unknown>): string {
+	let kwargs = "";
+	for (const key in args) {
+		kwargs += `${kwargs ? ", " : ""}${key}=${pyArgValue(args[key])}`;
+	}
+	return `${name}(${kwargs})`;
+}
+
+function pyArgValue(value: unknown): string {
+	if (typeof value === "string" && value.includes("\n")) {
+		// Verbatim `"""` fencing is only unambiguous when the content cannot
+		// collide with the fence: no `"""` inside, no quote butting against a
+		// fence edge, no trailing backslash swallowing the closer.
+		const fenceSafe =
+			!value.includes('"""') && !value.startsWith('"') && !value.endsWith('"') && !value.endsWith("\\");
+		if (fenceSafe) return `"""${value}"""`;
+	}
+	return pyValue(value);
+}
+
+/** Render a JSON-ish value as a Python literal (`True`/`False`/`None`, escaped strings, lists, dicts). */
+export function pyValue(value: unknown): string {
+	if (value === null || value === undefined) return "None";
+	if (typeof value === "boolean") return value ? "True" : "False";
+	if (typeof value === "number") return Number.isFinite(value) ? String(value) : pyString(String(value));
+	if (typeof value === "string") return pyString(value);
+	if (Array.isArray(value)) return `[${value.map(pyValue).join(", ")}]`;
+	if (typeof value === "object") {
+		const record = value as Record<string, unknown>;
+		let entries = "";
+		for (const key in record) {
+			entries += `${entries ? ", " : ""}${pyString(key)}: ${pyValue(record[key])}`;
+		}
+		return `{${entries}}`;
+	}
+	return pyString(String(value));
+}
+
+function pyString(value: string): string {
+	const escaped = value
+		.replaceAll("\\", "\\\\")
+		.replaceAll('"', '\\"')
+		.replaceAll("\n", "\\n")
+		.replaceAll("\r", "\\r")
+		.replaceAll("\t", "\\t");
+	return `"${escaped}"`;
+}
+
 export function escapeXmlAttr(value: string): string {
 	return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 }

package/src/dialect/types.ts

@@ -27,7 +27,6 @@ export interface DialectToolResult {
 
 export interface DialectRenderOptions {
 	readonly tools?: readonly InbandTool[];
-	readonly example?: boolean;
 }
 
 export interface DialectDefinition {

package/src/error/aws.ts

@@ -9,7 +9,11 @@ export type AwsCredentialsErrorKind =
 	/** SSO `GetRoleCredentials` call failed or returned no role. */
 	| "sso-role"
 	/** External `credential_process` failed, timed out, or emitted bad output. */
-	| "credential-process";
+	| "credential-process"
+	/** STS web-identity exchange failed or returned malformed credentials. */
+	| "web-identity"
+	/** ECS/container credential endpoint failed or returned malformed credentials. */
+	| "container";
 
 /** A failure resolving AWS credentials for the Bedrock provider. */
 export class AwsCredentialsError extends Error {

package/src/error/flags.ts

@@ -270,6 +270,14 @@ export function isStreamReadErrorText(text: string): boolean {
 	return STREAM_READ_ERROR_PATTERN.test(text);
 }
 
+/** Persisted-text form of {@link isStreamEnvelopeError}: recognizes the
+ *  prefix-tagged envelope diagnostic on an aborted turn's `errorMessage` /
+ *  `stopDetails.explanation` so loop-level salvage can classify it after the
+ *  original `Error` instance is gone. */
+export function isStreamEnvelopeErrorText(text: string): boolean {
+	return text.includes(STREAM_ENVELOPE_ERROR_PREFIX);
+}
+
 function isTransientErrorText(text: string): boolean {
 	return (
 		isUnexpectedSocketCloseMessage(text) ||

package/src/providers/amazon-bedrock.ts

@@ -10,9 +10,10 @@
 import type { Effort } from "@oh-my-pi/pi-catalog/effort";
 import { mapEffortToAnthropicAdaptiveEffort, requireSupportedEffort } from "@oh-my-pi/pi-catalog/model-thinking";
 import { calculateCost } from "@oh-my-pi/pi-catalog/models";
-import { $env, $flag, fetchWithRetry, parseStreamingJson, parseStreamingJsonThrottled } from "@oh-my-pi/pi-utils";
+import { $flag, fetchWithRetry, parseStreamingJson, parseStreamingJsonThrottled } from "@oh-my-pi/pi-utils";
 import { renderDemotedThinking } from "../dialect/demotion";
 import * as AIError from "../error";
+import { resolveAwsBearerToken } from "../registry/aws";
 import type {
 	Api,
 	AssistantMessage,
@@ -30,6 +31,7 @@ import type {
 	ToolResultMessage,
 } from "../types";
 import { normalizeSystemPrompts, normalizeToolCallId, resolveCacheRetention } from "../utils";
+import { resolveAwsAmbientRegion } from "../utils/aws-profile";
 import {
 	clearStreamingPartialJson,
 	kStreamingBlockIndex,
@@ -74,11 +76,9 @@ export interface BedrockOptions extends StreamOptions {
 	 */
 	thinkingDisplay?: BedrockThinkingDisplay;
 }
-const AUTHENTICATED_API_KEY_SENTINEL = "<authenticated>";
 
 function resolveBearerToken(options: BedrockOptions): string | undefined {
-	const apiKey = options.apiKey === AUTHENTICATED_API_KEY_SENTINEL ? undefined : options.apiKey;
-	return options.bearerToken || apiKey || $env.AWS_BEARER_TOKEN_BEDROCK;
+	return resolveAwsBearerToken(options.apiKey, options.bearerToken);
 }
 
 function inferRegionFromBedrockArn(modelId: string): string | undefined {
@@ -149,7 +149,7 @@ function regionServesGeo(region: string, geo: string): boolean {
 function resolveBedrockRegion(modelId: string, options: BedrockOptions): string {
 	const explicit = options.region || inferRegionFromBedrockArn(modelId);
 	if (explicit) return explicit;
-	const ambient = $env.AWS_REGION || $env.AWS_DEFAULT_REGION;
+	const ambient = resolveAwsAmbientRegion(options.profile);
 	const geo = inferenceProfileGeo(modelId);
 	if (geo) {
 		if (ambient && regionServesGeo(ambient, geo)) return ambient;

package/src/providers/anthropic.ts

@@ -2563,7 +2563,22 @@ const streamAnthropicOnce = (
 					if (!sawEvent || !sawMessageStart) {
 						throw new AIError.AnthropicStreamEnvelopeError("stream ended before message_start");
 					}
+					if (!sawTerminalEnvelope) {
+						// Neither a message_delta stop_reason nor message_stop arrived: the
+						// connection died mid-generation. Finalizing the partial message as
+						// a clean "stop" would make the agent loop treat the truncated turn
+						// as complete (silent mid-sentence halt), so fail the turn. The
+						// envelope error is transparently retried before replay-unsafe
+						// content streams; afterwards it surfaces as an error turn whose
+						// complete tool calls the agent loop salvages
+						// (`recoverTransientErrorToolTurn` recognizes the envelope-error
+						// text and `retainCompletedToolCalls` drops half-streamed calls).
+						throw new AIError.AnthropicStreamEnvelopeError("stream ended before message_stop");
+					}
 					if (!sawMessageStop) {
+						// A stop_reason arrived via message_delta, so generation finished;
+						// only the trailing message_stop frame is missing (non-conforming
+						// gateway). Degrade to best-effort instead of discarding the turn.
 						reportAnthropicEnvelopeAnomaly("stream ended before message_stop");
 					}
 					if (openBlocks.size > 0) {
@@ -2780,15 +2795,48 @@ type SystemBlockOptions = {
 	cacheControl?: AnthropicCacheControl;
 };
 
-function applyClaudeCodeSystemCache(
+/**
+ * Place system-block cache breakpoints that survive volatile project context.
+ *
+ * omp normally appends its project footer (cwd, date, workspace tree) after the
+ * stable system prefix. When cwd is outside a single direct child repository,
+ * an active-repo context block follows that footer. Caching up to the last three
+ * eligible blocks therefore covers both layouts:
+ *
+ * - stable prefix, project footer
+ * - stable prefix, project footer, active-repo context
+ *
+ * A footer change can then fall back to the stable-prefix entry instead of
+ * re-writing the entire system cache (issue #7324).
+ *
+ * @returns breakpoints placed, capped by `maxBreakpoints`.
+ */
+function cacheSystemPrefixBreakpoints(
 	blocks: AnthropicSystemBlock[],
 	cacheControl: AnthropicCacheControl | undefined,
+	maxBreakpoints: number,
+	firstCacheableIndex: number,
 ): number {
-	if (!cacheControl || blocks.length === 0) return 0;
-	const lastIndex = blocks.length - 1;
-	if (blocks[lastIndex].cache_control != null) return 0;
-	blocks[lastIndex] = { ...blocks[lastIndex], cache_control: cloneAnthropicCacheControl(cacheControl) };
-	return 1;
+	if (!cacheControl || maxBreakpoints <= 0) return 0;
+	let placed = 0;
+	for (let index = blocks.length - 1; index >= firstCacheableIndex && placed < maxBreakpoints; index--) {
+		if (blocks[index].cache_control != null) continue;
+		blocks[index] = { ...blocks[index], cache_control: cloneAnthropicCacheControl(cacheControl) };
+		placed++;
+	}
+	return placed;
+}
+
+/**
+ * First system-block index that may carry a cache breakpoint. Skips the OAuth
+ * cloak blocks that must stay uncached: the CC billing header (block 0, a
+ * per-request fingerprint) and the Claude Code identity instruction (block 1).
+ */
+function firstCacheableSystemIndex(blocks: readonly AnthropicSystemBlock[]): number {
+	let index = 0;
+	if (blocks[index]?.text?.startsWith(CLAUDE_BILLING_HEADER_PREFIX)) index++;
+	if (blocks[index]?.text === claudeCodeSystemInstruction) index++;
+	return index;
 }
 
 export function buildAnthropicSystemBlocks(
@@ -2812,7 +2860,7 @@ export function buildAnthropicSystemBlocks(
 		for (const prompt of sanitizedPrompts) {
 			blocks.push({ type: "text", text: prompt });
 		}
-		applyClaudeCodeSystemCache(blocks, cacheControl);
+		cacheSystemPrefixBreakpoints(blocks, cacheControl, 3, firstCacheableSystemIndex(blocks));
 
 		return blocks;
 	}
@@ -3083,17 +3131,6 @@ type CacheControlBlock = {
 	cache_control?: AnthropicCacheControl | null;
 };
 
-function applyCacheControlToLastBlock<T extends CacheControlBlock>(
-	blocks: T[],
-	cacheControl: AnthropicCacheControl,
-): boolean {
-	if (blocks.length === 0) return false;
-	const lastIndex = blocks.length - 1;
-	if (blocks[lastIndex].cache_control != null) return false;
-	blocks[lastIndex] = { ...blocks[lastIndex], cache_control: cloneAnthropicCacheControl(cacheControl) };
-	return true;
-}
-
 function applyCacheControlToLastTextBlock(
 	blocks: Array<ContentBlockParam & CacheControlBlock>,
 	cacheControl: AnthropicCacheControl,
@@ -3127,24 +3164,32 @@ function applyPromptCaching(params: MessageCreateParamsStreaming, cacheControl?:
 	let isCCLayout = false;
 
 	if (params.system && Array.isArray(params.system) && params.system.length > 0) {
-		isCCLayout =
-			params.system.length >= 3 &&
-			(params.system[0] as { text?: string }).text?.startsWith(CLAUDE_BILLING_HEADER_PREFIX) === true;
-		if (isCCLayout) {
-			const placed = Math.min(
-				MAX_CACHE_BREAKPOINTS - cacheBreakpointsUsed,
-				applyClaudeCodeSystemCache(params.system as AnthropicSystemBlock[], cacheControl),
-			);
-			cacheBreakpointsUsed += placed;
-		} else if (applyCacheControlToLastBlock(params.system, cacheControl)) {
-			cacheBreakpointsUsed++;
-		}
+		isCCLayout = params.system[0]?.text?.startsWith(CLAUDE_BILLING_HEADER_PREFIX) === true;
+		const maxSystemBreakpoints = Math.min(3, MAX_CACHE_BREAKPOINTS - cacheBreakpointsUsed);
+		cacheBreakpointsUsed += cacheSystemPrefixBreakpoints(
+			params.system as AnthropicSystemBlock[],
+			cacheControl,
+			maxSystemBreakpoints,
+			isCCLayout ? firstCacheableSystemIndex(params.system as AnthropicSystemBlock[]) : 0,
+		);
 	}
 
 	if (cacheBreakpointsUsed >= MAX_CACHE_BREAKPOINTS) return;
 
-	const start = isCCLayout ? Math.max(0, params.messages.length - 1) : Math.max(0, params.messages.length - 2);
-	for (let i = start; i < params.messages.length; i++) {
+	// `convertAnthropicMessages` appends this neutral pad after a trailing
+	// assistant because Anthropic rejects assistant-prefill endings. It is absent
+	// from the next normal turn, so caching it wastes a scarce breakpoint; anchor
+	// the cache window on the preceding real assistant instead.
+	const trailingIndex = params.messages.length - 1;
+	const trailingMessage = params.messages[trailingIndex];
+	const hasTrailingAssistantPad =
+		trailingMessage?.role === "user" &&
+		trailingMessage.content === "Continue." &&
+		params.messages[trailingIndex - 1]?.role === "assistant";
+	const messageEnd = hasTrailingAssistantPad ? trailingIndex - 1 : trailingIndex;
+	const messageWindowSize = isCCLayout ? 1 : 2;
+	const start = Math.max(0, messageEnd - messageWindowSize + 1);
+	for (let i = messageEnd; i >= start; i--) {
 		if (cacheBreakpointsUsed >= MAX_CACHE_BREAKPOINTS) break;
 		const message = params.messages[i];
 		if (!message) continue;