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

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [17.2.6] - 2026-08-03
+
+### Added
+
+- Added profile-aware Bedrock Mantle region selection, authenticated model discovery, bearer-token or SigV4 authentication, and credential refresh handling for OpenAI Responses models.
+
+### Fixed
+
+- Fixed an issue where Ollama requests without a user-role message would fail to generate output or silently fail with a misleading error.
+
+## [17.2.5] - 2026-08-03
+
+### Changed
+
+- Standardized tool-call examples in `renderToolExamples` and `renderToolInventory` to use Python keyword-argument syntax (`name(key="value")`) across all models, removing the model-specific dialect parameter and the `DialectRenderOptions.example` flag.
+- Updated `renderToolInventory` to render the tool catalog as a unified OpenAI-Harmony-style `## functions` block using TypeScript type declarations and comments, replacing the previous per-tool Markdown sections.
+- Added a `style: "harmony"` option to `jsonSchemaToTypeScript` for generating compact, comma-delimited TypeScript definitions.
+
+### Fixed
+
+- Fixed a session-blocking issue where unescaped Harmony control tokens in replayed assistant responses and tool inputs caused subsequent requests to be rejected with `invalid_prompt` errors.
+- Fixed an issue where Codex Responses dropped native image-generation results from assistant content and replays due to stale `generating` statuses.
+- Fixed Anthropic stream truncation handling where unexpected connection closures were incorrectly treated as clean stops, causing the agent loop to halt silently mid-sentence.
+- Optimized Anthropic prompt caching to prevent unnecessary cache invalidation of the entire system prefix when volatile project footer details (such as current working directory, date, or workspace tree) change.
+
 ## [17.2.4] - 2026-08-01
 
 ### Fixed

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

@@ -1,2 +1,18 @@
-import type { Dialect, InbandTool } from "./types.js";
-export declare function renderToolExamples(tool: InbandTool, dialect: Dialect, intentField?: string): string;
+import type { InbandTool } from "./types.js";
+/**
+ * Render a tool's examples as an `<examples>` block. Calls render in Python
+ * keyword-argument syntax (`name(key="value", n=1)`) regardless of the model's
+ * tool-call dialect, so example bytes stay identical across models. Multiline
+ * string args render as verbatim `"""…"""` blocks, and a call whose only
+ * argument is a string renders as the bare value — the block already names the
+ * tool, and payload args (commands, code, patches) read best verbatim.
+ */
+export declare function renderToolExamples(tool: InbandTool, intentField?: string): string;
+/**
+ * Render a tool's examples as JSDoc-style `@example` lines for comment-gutter
+ * contexts (the Harmony `namespace functions` inventory): `@example "caption"`
+ * followed by the call in the same Python kwargs syntax as the wire block. The
+ * tag line delimits each example, so no XML envelope is needed — which is why
+ * the inventory uses this instead of `//`-prefixing the `<examples>` block.
+ */
+export declare function renderToolExamplesJsdoc(tool: InbandTool): string;

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

@@ -1,12 +1,9 @@
 import type { InbandTool } from "./types.js";
 /**
- * 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 declare function renderToolInventory(tools: readonly InbandTool[], model: string): string;
+export declare function renderToolInventory(tools: readonly InbandTool[]): string;

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

@@ -4,6 +4,15 @@ export declare function renderToolResponseResults(results: readonly DialectToolR
 export declare function kimiCallId(name: string, id: string, index: number): string;
 export declare function harmonyRecipient(name: string): string;
 export declare function stringifyJson(value: unknown): string;
+/**
+ * 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 declare function pyCall(name: string, args: Record<string, unknown>): string;
+/** Render a JSON-ish value as a Python literal (`True`/`False`/`None`, escaped strings, lists, dicts). */
+export declare function pyValue(value: unknown): string;
 export declare function escapeXmlAttr(value: string): string;
 export declare function escapeXmlText(value: string): string;
 export type AssistantTranscriptParts = {

package/dist/types/dialect/types.d.ts

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

package/dist/types/error/aws.d.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 declare class AwsCredentialsError extends Error {
     readonly kind: AwsCredentialsErrorKind;

package/dist/types/error/flags.d.ts

@@ -40,6 +40,11 @@ export declare function retriable(id: number | undefined, opts?: {
 }): boolean;
 export declare function status(error: unknown): number | undefined;
 export declare function isStreamReadErrorText(text: string): boolean;
+/** 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 declare function isStreamEnvelopeErrorText(text: string): boolean;
 export declare function classify(error: unknown, api?: Api): number;
 /**
  * Whether an error (or message string) classifies as an account usage/quota

package/dist/types/providers/aws-credentials.d.ts

@@ -4,16 +4,11 @@
  * Chain (first hit wins):
  *  1. Static credentials from the environment
  *     (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` [+ `AWS_SESSION_TOKEN`]).
- *  2. Profile in `~/.aws/credentials` (and `~/.aws/config` for SSO):
- *      - static `aws_access_key_id` / `aws_secret_access_key` / `aws_session_token`
- *      - SSO profile referencing a cached token in `~/.aws/sso/cache/*.json`,
- *        which we exchange for short-lived role credentials via
- *        `https://portal.sso.{region}.amazonaws.com/federation/credentials`.
- *      - `credential_process` — an external command emitting the AWS SDK
- *        `Version: 1` JSON envelope on stdout. Used by `aws-vault`, `granted`,
- *        in-house brokers, etc.
- *  3. EC2 IMDSv2 (only when `AWS_EC2_METADATA_DISABLED` is unset / falsey and
- *     `169.254.169.254` is reachable within a 1 s timeout).
+ *  2. Web identity (`AWS_WEB_IDENTITY_TOKEN_FILE` + `AWS_ROLE_ARN`).
+ *  3. Profile in `~/.aws/credentials` (and `~/.aws/config` for SSO):
+ *      - static keys, SSO, or `credential_process`.
+ *  4. ECS/container credentials from `AWS_CONTAINER_CREDENTIALS_*`.
+ *  5. EC2 IMDSv2 when metadata is enabled.
  *
  * Resolved credentials are cached process-wide per profile and refreshed
  * 60 s before `Expiration` to absorb clock skew.

package/dist/types/providers/bedrock-mantle.d.ts

@@ -0,0 +1,13 @@
+import { type AwsBedrockProviderOptions } from "../registry/aws.js";
+import type { FetchImpl, Model } from "../types.js";
+import type { OpenAIResponsesOptions } from "./openai-responses.js";
+export type BedrockMantleProviderOptions = AwsBedrockProviderOptions;
+export interface BedrockMantleOptions extends OpenAIResponsesOptions {
+    providerOptions?: BedrockMantleProviderOptions;
+}
+export declare function createBedrockMantleAuthenticatedFetch(options?: BedrockMantleOptions): FetchImpl;
+export interface PreparedBedrockMantleRequest {
+    model: Model<"openai-responses">;
+    options: OpenAIResponsesOptions;
+}
+export declare function prepareBedrockMantleRequest(model: Model<"openai-responses">, options: BedrockMantleOptions): PreparedBedrockMantleRequest;

package/dist/types/providers/openai-shared.d.ts

@@ -421,17 +421,27 @@ export interface BuildResponsesInputOptions<TApi extends Api> {
     preserveAssistantMessageIds?: boolean;
 }
 /**
- * Escape reserved Harmony control tokens in the client-boundary text of
- * replayed Responses input items — user/developer/system message text and
- * tool-result output. Model-owned items (assistant output, reasoning, tool-call
- * arguments) carry no client data and are returned untouched.
+ * Escape reserved Harmony control tokens in the free-text fields of replayed
+ * Responses input items: user/developer/system text, tool-result output,
+ * assistant message text, and tool-call payloads.
+ *
+ * Tool-call items are covered deliberately. The original #6913 fix skipped
+ * model-owned items on the theory that they carry no client data — but a model
+ * legitimately writing *about* Harmony samples `<|channel|>` etc. into its own
+ * `function_call.arguments`, and a full-transcript replay (stale or blocked
+ * previous_response_id, provider fallback) feeds those bytes back as input,
+ * which gpt-5.x reject with invalid_prompt / "Request blocked", permanently
+ * poisoning the session. `arguments` is a JSON document, so it uses
+ * {@link escapeHarmonyControlTokensInJson} to stay parseable. Reasoning items
+ * are left untouched: `encrypted_content` is opaque and plaintext summaries
+ * are never rendered back into the prompt.
  *
  * Native history replay pushes stored `providerPayload` items straight onto the
  * wire, bypassing {@link convertResponsesInputContent}; without this a stored
  * `input_text` carrying `<|channel|>analysis` still reaches gpt-5.x raw (#6913).
  * Callers gate on {@link isHarmonyDialectModel}. Items are copied, not mutated.
  */
-export declare function escapeReplayedClientText(items: ResponseInput): ResponseInput;
+export declare function escapeReplayedControlTokens(items: ResponseInput): ResponseInput;
 export declare function buildResponsesInput<TApi extends Api>(options: BuildResponsesInputOptions<TApi>): ResponseInput;
 export declare function convertResponsesAssistantMessage<TApi extends Api>(assistantMsg: AssistantMessage, model: Model<TApi>, msgIndex: number, knownCallIds: Set<string>, includeThinkingSignatures?: boolean, customCallIds?: Set<string>, preserveMessageIds?: boolean, supportsCustomToolCalls?: boolean, customToolWireNameMap?: ReadonlyMap<string, string>, computerCallIds?: Set<string>): ResponseInput;
 /** Appends one tool result while keeping consecutive outputs ahead of its synthetic image messages. */
@@ -516,6 +526,8 @@ export interface ProcessResponsesStreamOptions {
     requestServiceTier?: ServiceTier;
 }
 export declare function computerCallMetadata(item: ResponseComputerToolCall): ComputerToolCallMetadata;
+/** Append a native Responses image result and emit its completion event. */
+export declare function appendResponsesImageResult(output: AssistantMessage, stream: AssistantMessageEventStream, result: string): void;
 export declare function processResponsesStream<TApi extends Api>(openaiStream: AsyncIterable<ResponseStreamEvent>, output: AssistantMessage, stream: AssistantMessageEventStream, model: Model<TApi>, options?: ProcessResponsesStreamOptions): Promise<void>;
 export declare function mapOpenAIResponsesStopReason(status: ResponseStatus | undefined): StopReason;
 export declare function hasExecutableIncompleteResponsesToolCalls(output: AssistantMessage): boolean;

package/dist/types/providers/transform-messages.d.ts

@@ -13,7 +13,7 @@ import type { Api, AssistantMessage, Message, Model } from "../types.js";
  * credential redaction is enabled. Exported so hosts can route the same shapes
  * through reversible obfuscation (keyed placeholders restored before local tool
  * execution) instead of the irreversible `[*_token_redacted]` rewrite below —
- * an irreversible placeholder echoed back in edit-tool `old_text` can never
+ * an irreversible placeholder echoed back in edit-tool `old_string` can never
  * match the real bytes on disk.
  */
 export declare const SENSITIVE_TOKEN_RE: RegExp;

package/dist/types/registry/amazon-bedrock.d.ts

@@ -1,5 +1,11 @@
+import { resolveAwsRegistryApiKey } from "./aws.js";
 export declare const amazonBedrockProvider: {
     readonly id: "amazon-bedrock";
     readonly name: "Amazon Bedrock";
-    readonly envKeys: () => "<authenticated>" | undefined;
+    readonly envKeys: typeof resolveAwsRegistryApiKey;
+    readonly mapSimpleOptions: (options: import("../index.js").SimpleStreamOptions) => {
+        region: string | undefined;
+        profile: string | undefined;
+        bearerToken: string | undefined;
+    };
 };

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

@@ -0,0 +1,13 @@
+export interface AwsBedrockProviderOptions extends Readonly<Record<string, unknown>> {
+    /** AWS region used in the service endpoint and SigV4 credential scope. */
+    region?: string;
+    /** Named AWS shared-credentials/config profile. */
+    profile?: string;
+    /** Amazon Bedrock API key sent as a bearer token, ahead of SigV4 credential resolution. */
+    bearerToken?: string;
+}
+export declare function hasAwsCredentialSource(): boolean;
+/** Registry key marker for AWS transports that resolve their own bearer/IAM credentials. */
+export declare function resolveAwsRegistryApiKey(): string | undefined;
+/** Resolve a real AWS bearer token while filtering the registry's auth marker. */
+export declare function resolveAwsBearerToken(apiKey?: string, bearerToken?: string): string | undefined;

package/dist/types/registry/bedrock-mantle.d.ts

@@ -0,0 +1,22 @@
+import type { Model } from "../types.js";
+import { resolveAwsRegistryApiKey } from "./aws.js";
+export declare const bedrockMantleProvider: {
+    readonly id: "bedrock-mantle";
+    readonly name: "Amazon Bedrock Mantle";
+    readonly envKeys: typeof resolveAwsRegistryApiKey;
+    readonly allowsMissingApiKey: true;
+    readonly prepareRequest: (model: Model<import("@oh-my-pi/pi-catalog").Api>, options: import("../index.js").StreamOptions) => import("../providers/bedrock-mantle.js").PreparedBedrockMantleRequest;
+    readonly mapSimpleOptions: (options: import("../index.js").SimpleStreamOptions) => {
+        providerOptions: Readonly<Record<string, unknown>> | undefined;
+    };
+    readonly prepareModelDiscovery: (config: import("./types.js").ProviderModelDiscoveryConfig) => {
+        baseUrl?: string;
+        fetch?: import("@oh-my-pi/pi-utils").FetchImpl;
+        apiKey: undefined;
+        authenticated: false;
+    } | {
+        authenticated: true;
+        baseUrl: string;
+        fetch: import("@oh-my-pi/pi-utils").FetchImpl;
+    };
+};

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

@@ -25,7 +25,12 @@ declare const ALL: ({
 } | {
     readonly id: "amazon-bedrock";
     readonly name: "Amazon Bedrock";
-    readonly envKeys: () => "<authenticated>" | undefined;
+    readonly envKeys: typeof import("./aws.js").resolveAwsRegistryApiKey;
+    readonly mapSimpleOptions: (options: import("../index.js").SimpleStreamOptions) => {
+        region: string | undefined;
+        profile: string | undefined;
+        bearerToken: string | undefined;
+    };
 } | {
     readonly id: "anthropic";
     readonly name: "Anthropic (Claude Pro/Max)";
@@ -41,6 +46,25 @@ declare const ALL: ({
     readonly id: "baseten";
     readonly name: "Baseten";
     readonly login: (cb: import("./oauth/index.js").OAuthLoginCallbacks) => Promise<string>;
+} | {
+    readonly id: "bedrock-mantle";
+    readonly name: "Amazon Bedrock Mantle";
+    readonly envKeys: typeof import("./aws.js").resolveAwsRegistryApiKey;
+    readonly allowsMissingApiKey: true;
+    readonly prepareRequest: (model: import("@oh-my-pi/pi-catalog").Model<import("@oh-my-pi/pi-catalog").Api>, options: import("../index.js").StreamOptions) => import("../providers/bedrock-mantle.js").PreparedBedrockMantleRequest;
+    readonly mapSimpleOptions: (options: import("../index.js").SimpleStreamOptions) => {
+        providerOptions: Readonly<Record<string, unknown>> | undefined;
+    };
+    readonly prepareModelDiscovery: (config: import("./types.js").ProviderModelDiscoveryConfig) => {
+        baseUrl?: string;
+        fetch?: import("@oh-my-pi/pi-utils").FetchImpl;
+        apiKey: undefined;
+        authenticated: false;
+    } | {
+        authenticated: true;
+        baseUrl: string;
+        fetch: import("@oh-my-pi/pi-utils").FetchImpl;
+    };
 } | {
     readonly id: "cerebras";
     readonly name: "Cerebras";

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

@@ -9,6 +9,7 @@
  * (default model, model-manager factory, catalog discovery) lives in
  * `@oh-my-pi/pi-catalog`'s descriptor table.
  */
+import type { Api, FetchImpl, Model, SimpleStreamOptions, StreamOptions } from "../types.js";
 import type { OAuthCredentials, OAuthLoginCallbacks } from "./oauth/types.js";
 /**
  * API-key environment fallback: either a single env var name (e.g.
@@ -16,6 +17,21 @@ import type { OAuthCredentials, OAuthLoginCallbacks } from "./oauth/types.js";
  * the host (Vertex ADC, Bedrock credential chains, …).
  */
 export type KeyResolver = string | (() => string | undefined);
+/** Credentials are resolved by the provider transport rather than used as a bearer string. */
+export declare const AUTHENTICATED_SENTINEL = "<authenticated>";
+export interface PreparedProviderRequest {
+    readonly model: Model<Api>;
+    readonly options: StreamOptions;
+}
+export type ProviderRequestPreparer = (model: Model<Api>, options: StreamOptions) => PreparedProviderRequest;
+export type ProviderSimpleOptionsMapper = (options: SimpleStreamOptions) => Readonly<Record<string, unknown>>;
+export interface ProviderModelDiscoveryConfig {
+    readonly apiKey?: string;
+    readonly baseUrl?: string;
+    readonly fetch?: FetchImpl;
+    readonly authenticated?: boolean;
+}
+export type ProviderModelDiscoveryPreparer = (config: ProviderModelDiscoveryConfig) => ProviderModelDiscoveryConfig;
 /**
  * Declarative description of a single provider's auth/login wiring. All
  * fields are optional except `id`/`name`; presence of a field opts the
@@ -39,6 +55,14 @@ export interface ProviderDefinition {
     /** Whether to surface in the interactive login list. Defaults to true when `login` is present. */
     readonly showInLoginList?: boolean;
     readonly envKeys?: KeyResolver;
+    /** Provider transport can authenticate without a resolved API-key string. */
+    readonly allowsMissingApiKey?: boolean;
+    /** Provider-owned request shaping applied before generic API dispatch. */
+    readonly prepareRequest?: ProviderRequestPreparer;
+    /** Provider-owned projection from the generic simple-stream option bag. */
+    readonly mapSimpleOptions?: ProviderSimpleOptionsMapper;
+    /** Provider-owned authentication and endpoint setup for model discovery. */
+    readonly prepareModelDiscovery?: ProviderModelDiscoveryPreparer;
     readonly login?: (callbacks: OAuthLoginCallbacks) => Promise<OAuthCredentials | string>;
     readonly refreshToken?: (credentials: OAuthCredentials) => Promise<OAuthCredentials>;
     readonly getApiKey?: (credentials: OAuthCredentials) => string;

package/dist/types/types.d.ts

@@ -124,10 +124,10 @@ export declare function serviceTierFamily(model: ServiceTierModel): ServiceTierF
 export declare function resolveModelServiceTier(tiers: ServiceTierByFamily | null | undefined, model: Pick<Model, "provider" | "api" | "id">): ServiceTier | undefined;
 /**
  * True when the tier should be sent on the wire as the provider's service-tier
- * request field. OpenAI / OpenAI-Codex accept `flex`/`scale`/`priority`; Google
- * (Gemini API + Vertex) and OpenRouter accept `flex`/`priority`; Fireworks
- * Serverless realizes only its Priority serving path. Anthropic is absent — it
- * realizes `priority` via `speed: "fast"`, not a service-tier field.
+ * request field. OpenAI / OpenAI-Codex accept every {@link ServiceTier};
+ * Google (Gemini API + Vertex) and OpenRouter accept `flex`/`priority`;
+ * Fireworks Serverless realizes only its Priority serving path. Anthropic is
+ * absent because it realizes `priority` via `speed: "fast"`.
  */
 export declare function shouldSendServiceTier(serviceTier: ServiceTier | null | undefined, target: Provider | ServiceTierModel | undefined): boolean;
 /**
@@ -249,6 +249,11 @@ export interface StreamOptions {
      * For example, Anthropic uses `user_id` for abuse tracking and rate limiting.
      */
     metadata?: Record<string, unknown>;
+    /**
+     * Provider-owned request configuration. Provider hooks interpret this bag;
+     * generic API transports do not forward its fields onto the wire.
+     */
+    providerOptions?: Readonly<Record<string, unknown>>;
     /** OpenAI Responses/Codex response fields to include verbatim. */
     include?: OpenAIResponseInclude[];
     /**
@@ -660,6 +665,8 @@ export interface AssistantRetryRecovery {
 export interface ContextSnapshot {
     promptTokens: number;
     nonMessageTokens: number;
+    /** Estimated prompt tokens removed by local history rewrites after this provider snapshot was recorded. */
+    historyRewriteTokensRemoved?: number;
     lastMessageTimestamp?: number;
 }
 export interface AssistantMessage {

package/dist/types/utils/aws-profile.d.ts

@@ -0,0 +1,17 @@
+/** INI sections with `profile ` / `sso-session ` prefixes normalized. */
+export type AwsIniFile = Record<string, Record<string, string>>;
+export declare function parseAwsIni(text: string): AwsIniFile;
+/** Resolve the selected shared-credentials profile. */
+export declare function resolveAwsProfile(profile?: string): string;
+/**
+ * Whether the shared config file participates in profile/region resolution.
+ * Explicit profile selection enables it; the implicit default profile follows
+ * the AWS SDK's `AWS_SDK_LOAD_CONFIG` opt-in.
+ */
+export declare function shouldLoadAwsSharedConfig(profile?: string): boolean;
+export declare function resolveAwsProfileRegion(profile?: string): string | undefined;
+/** Region selected by the environment or active shared-config profile. */
+export declare function resolveAwsAmbientRegion(profile?: string): string | undefined;
+/** Resolve the region precedence shared by AWS transports and credential exchanges. */
+export declare function resolveAwsRegion(explicitRegion?: string, profile?: string): string;
+export declare function hasConfiguredAwsProfile(profile?: string): boolean;

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

@@ -8,6 +8,15 @@ import type { AssistantMessage, Model, ToolCall } from "../types.js";
  * the persisted transcript keeps the byte-for-byte original.
  */
 export declare function escapeHarmonyControlTokens(text: string): string;
+/**
+ * Escape reserved Harmony control tokens inside a JSON document string (e.g.
+ * `function_call.arguments`). Doubles the backslash so the document remains
+ * valid JSON whose *decoded* strings carry the inert `<\|token\|>` spelling.
+ * `<|` cannot occur outside a string literal in valid JSON, so the blanket
+ * replace never corrupts structure; malformed documents are escaped
+ * best-effort.
+ */
+export declare function escapeHarmonyControlTokensInJson(text: string): string;
 /**
  * Whether requests to `model` are served by a Harmony-dialect backend
  * (gpt-5.x / gpt-oss), which rejects reserved control-token spellings appearing

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

@@ -9,10 +9,16 @@
  * literal enums/consts, and descriptions survive.
  */
 export interface JsonSchemaToTsOptions {
-    /** Indentation unit for nested object bodies. Default two spaces. */
+    /** Indentation unit for nested object bodies. Default two spaces (none in `harmony` style). */
     readonly indent?: string;
-    /** Emit `description` keywords as JSDoc comments on object properties. Default true. */
+    /** Emit `description` keywords as comments on object properties. Default true. */
     readonly comments?: boolean;
+    /**
+     * Output flavor. `default` renders JSDoc comments, `;` delimiters, and
+     * indented bodies; `harmony` renders the flat OpenAI-Harmony convention —
+     * `//` line comments, `,` delimiters, no indentation.
+     */
+    readonly style?: "default" | "harmony";
 }
 /** Convert a JSON Schema object into a simplified TypeScript type string. */
 export declare function jsonSchemaToTypeScript(schema: unknown, options?: JsonSchemaToTsOptions): string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "17.2.4",
+	"version": "17.2.6",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,9 +38,9 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.1",
-		"@oh-my-pi/pi-catalog": "17.2.4",
-		"@oh-my-pi/pi-utils": "17.2.4",
-		"@oh-my-pi/pi-wire": "17.2.4",
+		"@oh-my-pi/pi-catalog": "17.2.6",
+		"@oh-my-pi/pi-utils": "17.2.6",
+		"@oh-my-pi/pi-wire": "17.2.6",
 		"arktype": "2.2.3",
 		"zod": "^4"
 	},

package/src/auth-broker/discover.ts

@@ -6,6 +6,7 @@
  */
 import * as path from "node:path";
 import {
+	$envExact,
 	getAgentDbPath,
 	getAgentDir,
 	getAuthBrokerSnapshotCachePath,
@@ -55,7 +56,7 @@ export function getAuthBrokerTokenFilePath(): string {
  */
 async function defaultResolveConfigValue(config: string): Promise<string | undefined> {
 	if (config.startsWith("!")) return undefined;
-	const envValue = process.env[config];
+	const envValue = $envExact(config);
 	return envValue || config;
 }
 

package/src/auth-broker/wire-schema-resource.ts

@@ -12,7 +12,7 @@
  * exception (standard type keeps extra keys): it preserves provider-specific extension fields so
  * they round-trip through the broker instead of being dropped (see below).
  */
-import { type Type, type } from "arktype";
+import { scope, type Type } from "arktype";
 import {
 	type ApiKeyCredential,
 	type AuthCredential,
@@ -84,6 +84,11 @@ export interface AuthBrokerWireSchemas {
 }
 
 function buildAuthBrokerWireSchemas(): AuthBrokerWireSchemas {
+	// Wire schemas validate only a handful of times per process, so ArkType's
+	// definition-time JIT codegen is startup tax. A local jitless scope skips
+	// that codegen and uses interpreted traversal; correctness is unchanged.
+	const { type } = scope({}, { jitless: true });
+
 	// ─── Credential payloads ───────────────────────────────────────────────────
 
 	/** Real OAuth credential (broker-side) — refresh token is the actual upstream value. */

package/src/auth-storage.ts

@@ -12,7 +12,7 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { parseAlibabaTokenPlanCredential } from "@oh-my-pi/pi-catalog/wire/alibaba-token-plan";
-import { $env, getAgentDbPath, getDbBusyTimeoutMs, logger } from "@oh-my-pi/pi-utils";
+import { $env, $envExact, getAgentDbPath, getDbBusyTimeoutMs, logger } from "@oh-my-pi/pi-utils";
 import type { ApiKeyResolver } from "./auth-retry";
 import * as AIError from "./error";
 import { isUsageLimitOutcome } from "./error/rate-limit";
@@ -643,7 +643,7 @@ export type AuthStorageOptions = {
  * Does NOT support "!command" syntax (that requires pi-natives).
  */
 async function defaultConfigValueResolver(config: string): Promise<string | undefined> {
-	const envValue = process.env[config];
+	const envValue = $envExact(config);
 	return envValue || config;
 }
 

package/src/dialect/examples.ts

@@ -1,25 +1,32 @@
-import type { ToolCall } from "../types";
-import { getDialectDefinition } from "./factory";
-import type { Dialect, InbandTool } from "./types";
+import { pyCall } from "./rendering";
+import type { InbandTool } from "./types";
 
 const INTENT_PLACEHOLDER = "…";
 
-export function renderToolExamples(tool: InbandTool, dialect: Dialect, intentField?: string): string {
+/**
+ * Render a tool's examples as an `<examples>` block. Calls render in Python
+ * keyword-argument syntax (`name(key="value", n=1)`) regardless of the model's
+ * tool-call dialect, so example bytes stay identical across models. Multiline
+ * string args render as verbatim `"""…"""` blocks, and a call whose only
+ * argument is a string renders as the bare value — the block already names the
+ * tool, and payload args (commands, code, patches) read best verbatim.
+ */
+export function renderToolExamples(tool: InbandTool, intentField?: string): string {
 	const examples = tool.examples;
 	if (!examples?.length) return "";
-	const definition = getDialectDefinition(dialect);
 	const renderCall = (args: Record<string, unknown>): string => {
+		const bare = bareStringArg(args);
+		if (bare !== undefined) {
+			// Bare payload. The intent placeholder still rides on the envelope so
+			// intent-traced schemas (where `i` is required) keep teaching it.
+			const intentAttr = intentField ? ` ${intentField}="${INTENT_PLACEHOLDER}"` : "";
+			return `<example${intentAttr}>\n${bare}\n</example>`;
+		}
 		// When intent tracing injects `i` into the schema, examples must show a
 		// placeholder so the model learns to emit it. Keep it first, matching the
 		// schema injection order.
 		const finalArgs = intentField ? { [intentField]: INTENT_PLACEHOLDER, ...args } : args;
-		const call: ToolCall = {
-			type: "toolCall",
-			id: "example",
-			name: tool.name,
-			arguments: finalArgs,
-		};
-		return `<example>\n${definition.renderToolCall(call, { tools: [tool], example: true }).trim()}\n</example>`;
+		return `<example>\n${pyCall(tool.name, finalArgs)}\n</example>`;
 	};
 	const parts = examples.map(ex => {
 		const head = ex.caption ? `# ${ex.caption}\n` : "";
@@ -31,3 +38,34 @@ export function renderToolExamples(tool: InbandTool, dialect: Dialect, intentFie
 	});
 	return `<examples>\n${parts.join("\n")}\n</examples>`;
 }
+
+/**
+ * Render a tool's examples as JSDoc-style `@example` lines for comment-gutter
+ * contexts (the Harmony `namespace functions` inventory): `@example "caption"`
+ * followed by the call in the same Python kwargs syntax as the wire block. The
+ * tag line delimits each example, so no XML envelope is needed — which is why
+ * the inventory uses this instead of `//`-prefixing the `<examples>` block.
+ */
+export function renderToolExamplesJsdoc(tool: InbandTool): string {
+	const examples = tool.examples;
+	if (!examples?.length) return "";
+	const renderCall = (args: Record<string, unknown>): string => bareStringArg(args) ?? pyCall(tool.name, args);
+	const parts = examples.map(ex => {
+		const head = ex.caption ? `@example ${JSON.stringify(ex.caption)}` : "@example";
+		if ("call" in ex) return `${head}\n${renderCall(ex.call)}`;
+		if ("good" in ex) return `${head}\nWRONG:\n${renderCall(ex.bad)}\nRIGHT:\n${renderCall(ex.good)}`;
+		return ex.note ? `${head}\n${ex.note}` : head;
+	});
+	return parts.join("\n");
+}
+
+/** Sole-argument string payload, if the call has exactly one string argument. */
+function bareStringArg(args: Record<string, unknown>): string | undefined {
+	let sole: unknown;
+	let count = 0;
+	for (const key in args) {
+		count++;
+		sole = args[key];
+	}
+	return count === 1 && typeof sole === "string" ? sole : undefined;
+}