@gajae-code/ai 0.15.4 → 0.15.6

package/src/stream.ts

@@ -67,6 +67,7 @@ import type {
 	Api,
 	AssistantMessage,
 	AssistantMessageEvent,
+	AuthRetryCredential,
 	Context,
 	Model,
 	OptionsForApi,
@@ -115,6 +116,7 @@ const serviceProviderMap: Record<string, KeyResolver> = {
 	mistral: "MISTRAL_API_KEY",
 	minimax: "MINIMAX_API_KEY",
 	"minimax-code": "MINIMAX_CODE_API_KEY",
+	"commandcode-goat": "CMD_API_KEY",
 	"minimax-code-cn": "MINIMAX_CODE_CN_API_KEY",
 	"opencode-go": "OPENCODE_API_KEY",
 	"opencode-zen": "OPENCODE_API_KEY",
@@ -131,10 +133,12 @@ const serviceProviderMap: Record<string, KeyResolver> = {
 	tavily: "TAVILY_API_KEY",
 	parallel: "PARALLEL_API_KEY",
 	kagi: "KAGI_API_KEY",
-	// Kiro uses AWS SSO OIDC OAuth flow; bearer token is stored as the OAuth access token.
+	// Kiro API keys use the ksk_ prefix; preserve the AWS bearer fallback for OAuth.
 	kiro: () => {
-		const bearerToken = $credentialEnv("AWS_BEARER_TOKEN_KIRO");
-		if (bearerToken) return bearerToken;
+		const apiKey = $credentialEnv("KIRO_API_KEY");
+		return apiKey?.trim().startsWith("ksk_") && !/[\x00-\x1f\x7f]/.test(apiKey)
+			? apiKey
+			: $credentialEnv("AWS_BEARER_TOKEN_KIRO");
 	},
 	// GitHub Copilot uses GitHub personal access token
 	"github-copilot": () => $pickCredentialEnv("COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"),
@@ -219,6 +223,7 @@ export function listProvidersWithEnvKey(): string[] {
  * Used to give OpenCode users an accurate headless auth diagnostic (#755).
  */
 const OPENCODE_SUBSCRIPTION_PROVIDERS = new Set(["opencode-go", "opencode-zen"]);
+const API_KEY_LOGIN_PROVIDERS = new Set(["commandcode-goat"]);
 
 /**
  * Provider-specific credential guidance appended to "no credential" errors.
@@ -237,12 +242,16 @@ export function formatProviderCredentialHint(provider: string): string {
 	const resolver = serviceProviderMap[provider];
 	const envVar = typeof resolver === "string" ? resolver : undefined;
 	const isOpenCodeSubscription = OPENCODE_SUBSCRIPTION_PROVIDERS.has(provider);
+	const isApiKeyLoginProvider = API_KEY_LOGIN_PROVIDERS.has(provider);
 	const parts: string[] = [];
 	if (isOpenCodeSubscription) {
 		parts.push(
 			"OpenCode subscriptions authenticate with an API key (created at https://opencode.ai/auth), not a separate session/OAuth token.",
 		);
 	}
+	if (isApiKeyLoginProvider) {
+		parts.push("Command Code GOAT uses an API key from https://commandcode.ai/studio/#api-keys.");
+	}
 	if (provider === "jetbrains-junie") {
 		parts.push(
 			"JetBrains AI (Junie) authenticates with an access token generated at https://junie.jetbrains.com/cli; there is no OAuth login for this provider.",
@@ -265,10 +274,18 @@ function pipeAssistantStream(
 	outer: AssistantMessageEventStream,
 	inner: AssistantMessageEventStream,
 	signal?: AbortSignal,
+	onStreamCreated?: () => void,
 ): void {
 	void (async () => {
 		try {
+			let admitted = false;
+			const markAdmission = (): void => {
+				if (admitted) return;
+				admitted = true;
+				onStreamCreated?.();
+			};
 			for await (const event of inner) {
+				if (event.type !== "start") markAdmission();
 				outer.push(event);
 				// The inner provider stream owns abort semantics (it receives the
 				// same signal), but stop forwarding as soon as the consumer
@@ -286,14 +303,16 @@ function pipeAssistantStream(
 	})();
 }
 
-function streamFromLazyImport(
+export function streamFromLazyImport(
 	createInner: () => Promise<AssistantMessageEventStream>,
 	signal?: AbortSignal,
+	onStreamCreated?: () => void,
 ): AssistantMessageEventStream {
 	const outer = new AssistantMessageEventStream();
 	void (async () => {
 		try {
-			pipeAssistantStream(outer, await createInner(), signal);
+			const inner = await createInner();
+			pipeAssistantStream(outer, inner, signal, onStreamCreated);
 		} catch (error) {
 			outer.fail(error);
 		}
@@ -315,6 +334,7 @@ export function stream<TApi extends Api>(
 	model: Model<TApi>,
 	context: Context,
 	options?: OptionsForApi<TApi>,
+	onStreamCreated?: () => void,
 ): AssistantMessageEventStream {
 	if (!hasValidatedManagedAttempt(options)) assertManagedAttempt(options);
 	if (options?.fallbackManaged) {
@@ -348,6 +368,7 @@ export function stream<TApi extends Api>(
 				return streamGitLabDuo(model, context, adapterOptions);
 			},
 			(options as StreamOptions | undefined)?.signal,
+			onStreamCreated,
 		);
 	}
 
@@ -360,15 +381,22 @@ export function stream<TApi extends Api>(
 			isProviderSafetyStopModelTrusted(model)
 				? withProviderSafetyStopAdapterInvocation(vertexOptions)
 				: vertexOptions,
+			onStreamCreated,
 		);
 	} else if (model.api === "bedrock-converse-stream") {
 		// Bedrock doesn't have any API keys instead it sources credentials from standard AWS env variables or from given AWS profile.
-		return streamBedrock(model as Model<"bedrock-converse-stream">, context, (options || {}) as BedrockOptions);
+		return streamBedrock(
+			model as Model<"bedrock-converse-stream">,
+			context,
+			(options || {}) as BedrockOptions,
+			onStreamCreated,
+		);
 	} else if (model.api === "kiro-codewhisperer-stream") {
 		return streamKiroCodeWhisperer(
 			model as Model<"kiro-codewhisperer-stream">,
 			context,
 			(options || {}) as KiroCodeWhispererOptions,
+			onStreamCreated,
 		);
 	}
 
@@ -385,23 +413,39 @@ export function stream<TApi extends Api>(
 	switch (api) {
 		case "anthropic-messages": {
 			const anthropicOptions = adapterProviderOptions as AnthropicOptions;
-			return streamAnthropic(model as Model<"anthropic-messages">, context, {
-				...anthropicOptions,
-				isOAuth: anthropicOptions.isOAuth ?? model.isOAuth,
-			});
+			return streamAnthropic(
+				model as Model<"anthropic-messages">,
+				context,
+				{
+					...anthropicOptions,
+					isOAuth: anthropicOptions.isOAuth ?? model.isOAuth,
+				},
+				onStreamCreated,
+			);
 		}
 
 		case "openai-completions":
-			return streamOpenAICompletions(model as Model<"openai-completions">, context, adapterProviderOptions as any);
+			return streamOpenAICompletions(
+				model as Model<"openai-completions">,
+				context,
+				adapterProviderOptions as any,
+				onStreamCreated,
+			);
 
 		case "openai-responses":
-			return streamOpenAIResponses(model as Model<"openai-responses">, context, adapterProviderOptions as any);
+			return streamOpenAIResponses(
+				model as Model<"openai-responses">,
+				context,
+				adapterProviderOptions as any,
+				onStreamCreated,
+			);
 
 		case "azure-openai-responses":
 			return streamAzureOpenAIResponses(
 				model as Model<"azure-openai-responses">,
 				context,
 				adapterProviderOptions as any,
+				onStreamCreated,
 			);
 
 		case "openai-codex-responses":
@@ -409,23 +453,35 @@ export function stream<TApi extends Api>(
 				model as Model<"openai-codex-responses">,
 				context,
 				adapterProviderOptions as any,
+				onStreamCreated,
 			);
 
 		case "google-generative-ai":
-			return streamGoogle(model as Model<"google-generative-ai">, context, adapterProviderOptions);
+			return streamGoogle(model as Model<"google-generative-ai">, context, adapterProviderOptions, onStreamCreated);
 
 		case "google-gemini-cli":
 			return streamGoogleGeminiCli(
 				model as Model<"google-gemini-cli">,
 				context,
 				adapterProviderOptions as GoogleGeminiCliOptions,
+				onStreamCreated,
 			);
 
 		case "ollama-chat":
-			return streamOllama(model as Model<"ollama-chat">, context, adapterProviderOptions as OllamaChatOptions);
+			return streamOllama(
+				model as Model<"ollama-chat">,
+				context,
+				adapterProviderOptions as OllamaChatOptions,
+				onStreamCreated,
+			);
 
 		case "cursor-agent":
-			return streamCursor(model as Model<"cursor-agent">, context, adapterProviderOptions as CursorOptions);
+			return streamCursor(
+				model as Model<"cursor-agent">,
+				context,
+				adapterProviderOptions as CursorOptions,
+				onStreamCreated,
+			);
 
 		default:
 			throw new Error(`Unhandled API: ${api}`);
@@ -537,9 +593,19 @@ export function streamSimple<TApi extends Api>(
 			? AbortSignal.any([options.signal, consumerAbortController.signal])
 			: consumerAbortController.signal;
 		const onAuthError = options!.onAuthError!;
-		const runAttempt = async (apiKey: string, captureAuthFailure: boolean): Promise<AuthRetryFailure | undefined> => {
+		const runAttempt = async (
+			apiKey: string,
+			captureAuthFailure: boolean,
+			onStreamCreated?: () => void,
+		): Promise<AuthRetryFailure | undefined> => {
 			const bufferedEvents: AssistantMessageEvent[] = [];
 			let emittedReplayUnsafeEvent = false;
+			let admitted = false;
+			const markAdmission = (): void => {
+				if (admitted) return;
+				admitted = true;
+				onStreamCreated?.();
+			};
 			const flushBuffered = (): void => {
 				emitBufferedEvents(outer, bufferedEvents);
 				bufferedEvents.length = 0;
@@ -550,6 +616,7 @@ export function streamSimple<TApi extends Api>(
 					...options,
 					apiKey,
 					onAuthError: undefined,
+					onStreamCreated: markAdmission,
 					signal: requestSignal,
 				});
 				for await (const event of inner) {
@@ -585,6 +652,12 @@ export function streamSimple<TApi extends Api>(
 				}
 				flushBuffered();
 				outer.fail(error);
+			} finally {
+				// A lazy import or a synchronous provider failure can happen before
+				// the admission hook is reached. Release that attempt's lease in
+				// the failure path without extending a successful request's lease
+				// through the response lifetime.
+				if (!admitted) markAdmission();
 			}
 			return undefined;
 		};
@@ -598,19 +671,22 @@ export function streamSimple<TApi extends Api>(
 		};
 
 		void (async () => {
-			const failure = await runAttempt(retryApiKey, true);
+			const failure = await runAttempt(retryApiKey, true, options?.onStreamCreated);
 			if (!failure) return;
-			let nextKey: string | undefined;
+			let nextCredential: string | AuthRetryCredential | undefined;
 			try {
-				nextKey = await onAuthError(model.provider, retryApiKey, failure.error);
+				nextCredential = await onAuthError(model.provider, retryApiKey, failure.error);
 			} catch {
-				nextKey = undefined;
+				nextCredential = undefined;
 			}
-			if (!nextKey || nextKey === retryApiKey) {
+			const retryCredential: AuthRetryCredential | undefined =
+				typeof nextCredential === "string" ? { apiKey: nextCredential } : nextCredential;
+			if (!retryCredential?.apiKey || retryCredential.apiKey === retryApiKey) {
+				if (retryCredential) retryCredential.onStreamCreated?.();
 				emitFailure(failure);
 				return;
 			}
-			await runAttempt(nextKey, false);
+			await runAttempt(retryCredential.apiKey, false, retryCredential.onStreamCreated);
 		})();
 		return outer;
 	}
@@ -623,26 +699,39 @@ export function streamSimple<TApi extends Api>(
 	// pi-native transport.
 	const resolvedRequestMaxTokens = resolveDefaultRequestMaxTokens(model, options?.maxTokens);
 	if (model.transport === "pi-native") {
-		return streamFromLazyImport(async () => {
-			const { streamPiNative } = await import("./providers/pi-native-client");
-			return streamPiNative(model, context, { ...options, maxTokens: resolvedRequestMaxTokens });
-		}, options?.signal);
+		return streamFromLazyImport(
+			async () => {
+				const { streamPiNative } = await import("./providers/pi-native-client");
+				return streamPiNative(model, context, { ...options, maxTokens: resolvedRequestMaxTokens });
+			},
+			options?.signal,
+			options?.onStreamCreated,
+		);
 	}
 
 	// Check custom API registry (extension-provided APIs)
 	const customApiProvider = getCustomApi(model.api);
 	if (customApiProvider) {
-		return customApiProvider.streamSimple(model, context, { ...options, maxTokens: resolvedRequestMaxTokens });
+		const events = customApiProvider.streamSimple(model, context, {
+			...options,
+			maxTokens: resolvedRequestMaxTokens,
+		});
+		if (!options?.onStreamCreated) return events;
+		const forwarded = new AssistantMessageEventStream();
+		pipeAssistantStream(forwarded, events, options.signal, options.onStreamCreated);
+		return forwarded;
 	}
 
 	// Vertex AI uses Application Default Credentials, not API keys
 	if (model.api === "google-vertex") {
 		const providerOptions = mapOptionsForApi(model, options, undefined);
-		return stream(model, context, providerOptions);
+		const events = stream(model, context, providerOptions, options?.onStreamCreated);
+		return events;
 	} else if (model.api === "bedrock-converse-stream") {
 		// Bedrock doesn't have any API keys instead it sources credentials from standard AWS env variables or from given AWS profile.
 		const providerOptions = mapOptionsForApi(model, options, undefined);
-		return stream(model, context, providerOptions);
+		const events = stream(model, context, providerOptions, options?.onStreamCreated);
+		return events;
 	}
 
 	const apiKey = options?.apiKey || getEnvApiKey(model.provider);
@@ -656,58 +745,71 @@ export function streamSimple<TApi extends Api>(
 
 	// GitLab Duo - wraps Anthropic/OpenAI behind GitLab AI Gateway direct access tokens
 	if (model.provider === "gitlab-duo") {
-		return streamFromLazyImport(async () => {
-			const { streamGitLabDuo } = await import("./providers/gitlab-duo");
-			return streamGitLabDuo(
-				model,
-				context,
-				copyProviderSafetyStopAdapterInvocation(adapterOptions, {
-					...adapterOptions,
-					apiKey,
-					maxTokens: resolvedSpecialProviderMaxTokens,
-				}),
-			);
-		}, options?.signal);
+		return streamFromLazyImport(
+			async () => {
+				const { streamGitLabDuo } = await import("./providers/gitlab-duo");
+				return streamGitLabDuo(
+					model,
+					context,
+					copyProviderSafetyStopAdapterInvocation(adapterOptions, {
+						...adapterOptions,
+						apiKey,
+						maxTokens: resolvedSpecialProviderMaxTokens,
+					}),
+				);
+			},
+			options?.signal,
+			options?.onStreamCreated,
+		);
 	}
 
 	// Kimi Code - route to dedicated handler that wraps OpenAI or Anthropic API
 	if (model.provider === "kimi-code") {
-		return streamFromLazyImport(async () => {
-			const { streamKimi } = await import("./providers/kimi");
-			// Pass raw SimpleStreamOptions - streamKimi handles mapping internally
-			return streamKimi(
-				model as Model<"openai-completions">,
-				context,
-				copyProviderSafetyStopAdapterInvocation(adapterOptions, {
-					...adapterOptions,
-					apiKey,
-					maxTokens: resolvedSpecialProviderMaxTokens,
-					format: options?.kimiApiFormat ?? "anthropic",
-				}),
-			);
-		}, options?.signal);
+		return streamFromLazyImport(
+			async () => {
+				const { streamKimi } = await import("./providers/kimi");
+				// Pass raw SimpleStreamOptions - streamKimi handles mapping internally
+				return streamKimi(
+					model as Model<"openai-completions">,
+					context,
+					copyProviderSafetyStopAdapterInvocation(adapterOptions, {
+						...adapterOptions,
+						apiKey,
+						maxTokens: resolvedSpecialProviderMaxTokens,
+						format: options?.kimiApiFormat ?? "anthropic",
+					}),
+				);
+			},
+			options?.signal,
+			options?.onStreamCreated,
+		);
 	}
 
 	// Synthetic - route to dedicated handler that wraps OpenAI or Anthropic API
 	if (model.provider === "synthetic") {
-		return streamFromLazyImport(async () => {
-			const { streamSynthetic } = await import("./providers/synthetic");
-			// Pass raw SimpleStreamOptions - streamSynthetic handles mapping internally
-			return streamSynthetic(
-				model as Model<"openai-completions">,
-				context,
-				copyProviderSafetyStopAdapterInvocation(adapterOptions, {
-					...adapterOptions,
-					apiKey,
-					maxTokens: resolvedSpecialProviderMaxTokens,
-					format: options?.syntheticApiFormat ?? "openai", // Default to OpenAI format
-				}),
-			);
-		}, options?.signal);
+		return streamFromLazyImport(
+			async () => {
+				const { streamSynthetic } = await import("./providers/synthetic");
+				// Pass raw SimpleStreamOptions - streamSynthetic handles mapping internally
+				return streamSynthetic(
+					model as Model<"openai-completions">,
+					context,
+					copyProviderSafetyStopAdapterInvocation(adapterOptions, {
+						...adapterOptions,
+						apiKey,
+						maxTokens: resolvedSpecialProviderMaxTokens,
+						format: options?.syntheticApiFormat ?? "openai", // Default to OpenAI format
+					}),
+				);
+			},
+			options?.signal,
+			options?.onStreamCreated,
+		);
 	}
 
 	const providerOptions = mapOptionsForApi(model, options, apiKey);
-	return stream(model, context, providerOptions);
+	const events = stream(model, context, providerOptions, options?.onStreamCreated);
+	return events;
 }
 
 export async function completeSimple<TApi extends Api>(
@@ -856,6 +958,8 @@ function mapOptionsForApi<TApi extends Api>(
 		providerSessionState: options?.providerSessionState,
 		onPayload: options?.onPayload,
 		onResponse: options?.onResponse,
+		onStreamCreated: options?.onStreamCreated,
+		disableProviderRetries: options?.disableProviderRetries,
 		onSseEvent: options?.onSseEvent,
 		attemptScope: options?.attemptScope,
 		execHandlers: options?.execHandlers,
@@ -1160,6 +1264,12 @@ function mapOptionsForApi<TApi extends Api>(
 			});
 		}
 
+		case "kiro-codewhisperer-stream":
+			return castApi<"kiro-codewhisperer-stream">({
+				...base,
+				reasoning: options?.reasoning,
+			});
+
 		default:
 			throw new Error(`Unhandled API in mapOptionsForApi: ${model.api}`);
 	}

package/src/types.d.ts

@@ -54,7 +54,7 @@ export interface ThinkingConfig {
     /** Provider-specific transport used to encode the selected effort. */
     mode: ThinkingControlMode;
 }
-export declare const KNOWN_PROVIDERS: readonly ["alibaba-token-plan", "amazon-bedrock", "kiro", "azure-openai", "anthropic", "google", "google-gemini-cli", "google-antigravity", "google-vertex", "openai", "openai-codex", "opencodex", "kimi-code", "minimax-code", "minimax-code-cn", "github-copilot", "fireworks", "firepass", "fugu", "gitlab-duo", "cursor", "jetbrains-junie", "deepseek", "deepinfra", "xai", "groq", "cerebras", "openrouter", "kilo", "vercel-ai-gateway", "zai", "glm-zcode", "mistral", "minimax", "opencode-go", "opencode-zen", "opengateway", "bizrouter", "mara", "synthetic", "cloudflare-ai-gateway", "huggingface", "litellm", "moonshot", "nvidia", "nanogpt", "ollama", "ollama-cloud", "qianfan", "qwen-portal", "sglang", "together", "venice", "vllm", "xiaomi", "xiaomi-token-plan-sgp", "xiaomi-token-plan-ams", "xiaomi-token-plan-cn", "zenmux", "lm-studio", "omlx"];
+export declare const KNOWN_PROVIDERS: readonly ["alibaba-token-plan", "amazon-bedrock", "kiro", "azure-openai", "anthropic", "google", "google-gemini-cli", "google-antigravity", "google-vertex", "openai", "openai-codex", "opencodex", "kimi-code", "minimax-code", "minimax-code-cn", "github-copilot", "fireworks", "firepass", "fugu", "gitlab-duo", "cursor", "jetbrains-junie", "deepseek", "deepinfra", "xai", "groq", "cerebras", "openrouter", "kilo", "vercel-ai-gateway", "zai", "glm-zcode", "mistral", "minimax", "opencode-go", "commandcode-goat", "opencode-zen", "opengateway", "bizrouter", "mara", "synthetic", "cloudflare-ai-gateway", "huggingface", "litellm", "moonshot", "nvidia", "nanogpt", "ollama", "ollama-cloud", "qianfan", "qwen-portal", "sglang", "together", "venice", "vllm", "xiaomi", "xiaomi-token-plan-sgp", "xiaomi-token-plan-ams", "xiaomi-token-plan-cn", "zenmux", "lm-studio", "omlx"];
 export type KnownProvider = (typeof KNOWN_PROVIDERS)[number];
 export declare function isKnownProvider(provider: string): provider is KnownProvider;
 export type Provider = KnownProvider | string;
@@ -155,6 +155,18 @@ export interface RawSseEvent {
 export type FetchImpl = ((input: string | URL | Request, init?: RequestInit) => Promise<Response>) & {
     preconnect?: typeof globalThis.fetch.preconnect;
 };
+/**
+ * Credential returned by an auth retry resolver.
+ *
+ * The optional admission callback lets an authority-bearing caller retain a
+ * credential lease until the replacement provider request is actually
+ * admitted. Ordinary callers can continue returning a string from
+ * {@link StreamOptions.onAuthError}.
+ */
+export interface AuthRetryCredential {
+    apiKey: string;
+    onStreamCreated?: () => void;
+}
 export interface StreamOptions {
     temperature?: number;
     topP?: number;
@@ -186,7 +198,7 @@ export interface StreamOptions {
      * event has been emitted. Returning a different key retries the provider
      * request once.
      */
-    onAuthError?: (provider: string, apiKey: string, error: unknown) => Promise<string | undefined>;
+    onAuthError?: (provider: string, apiKey: string, error: unknown) => Promise<string | AuthRetryCredential | undefined>;
     cacheRetention?: CacheRetention;
     /**
      * Additional headers to include in provider requests.
@@ -243,6 +255,14 @@ export interface StreamOptions {
      * The `scope` parameter carries the per-attempt identity for execution attribution.
      */
     onResponse?: (response: ProviderResponseMetadata, model?: Model<Api>, scope?: AttemptScopeRef) => void | Promise<void>;
+    /**
+     * Internal dispatch-admission hook. Providers invoke this immediately before
+     * submitting an outbound request; stream forwarding retains a first-response
+     * fallback for custom providers that do not expose a transport seam.
+     */
+    onStreamCreated?: () => void;
+    /** Internal authority policy: disable provider-owned retries and corrective replays. */
+    disableProviderRetries?: boolean;
     /**
      * Optional callback for raw Server-Sent Events as they arrive from HTTP streaming providers.
      *
@@ -399,31 +419,22 @@ export interface ToolCall {
      */
     incompleteArgumentsReason?: "truncated" | "malformed" | "conflicting" | "ambiguous";
     /**
-     * Set when the raw argument JSON spelled a printable character as a `\uXXXX`
-     * escape instead of a literal character. This includes ASCII landings because
-     * a one-nibble mutation can move an intended non-ASCII scalar below U+0080.
-     * Such a payload parses cleanly but
-     * is unverifiable: one mistyped hex digit decodes to a different, equally
-     * valid character, so the text can be silently wrong with no in-band evidence.
-     * The agent loop resamples the turn a bounded number of times and then
-     * rejects the call instead of executing it. The single bounded exception
-     * is a tool that enumerated its display-only fields
-     * (`displaySafeEscapedArgFields`): when every escaped scalar corroborates
-     * a decoded non-ASCII character inside those fields, the call executes
-     * with a warning instead — rendered question text, never executable
-     * content, ids, or durable metadata.
-     * Escapes that are required (control characters) or unavoidable (lone
-     * surrogates) never set this.
+     * Set by current producers when raw argument JSON carries unsafe Unicode
+     * data, such as malformed escape evidence or a decoded unpaired surrogate.
+     * Valid JSON `\uXXXX` escapes are canonical spellings of the decoded string
+     * and current producers do not set this flag for them.
+     *
+     * Legacy producers may still set the flag for any escaped non-ASCII spelling.
+     * The agent loop keeps its bounded legacy resample/display-safe behavior for
+     * those calls while consuming the transient evidence below.
      */
     escapedNonAsciiArguments?: boolean;
     /**
-     * Bounded, payload-free evidence for the original raw escape positions and
-     * process-keyed scalar/path identities. Required for the display-safe terminal exemption: decoded values
-     * alone cannot prove that an ASCII landing such as `\u0077` was not a
-     * one-nibble mutation of a non-ASCII escape. Presence of this evidence implies
-     * the guarded state even if a legacy producer omitted
-     * `escapedNonAsciiArguments`. The agent consumes and removes this transient
-     * field before the tool-call message can become durable.
+     * Bounded, payload-free evidence for raw Unicode argument data. Current
+     * producers attach it only for unsafe data; legacy producers may attach
+     * non-malformed positional evidence used by the display-safe compatibility
+     * path. The agent consumes and removes this transient field before the
+     * tool-call message can become durable.
      */
     escapedUnicodeArgumentEvidence?: UnicodeEscapeEvidence;
 }