@code-yeongyu/senpi 2026.11.6-2 → 2026.11.6-3

package/dist/core/egress/sealed-format.js

@@ -0,0 +1,174 @@
+/**
+ * Sealed custody formats (C6, row CK3): provider fields under the provider DEK, the account config object under K_cfg,
+ * and HPKE key wraps (K_cfg, K_proj, DEK) to device and custody keys.
+ *
+ * Every AAD is rebuilt by the opener from its own context and never stored. Its bytes are a per-kind ASCII label, a NUL
+ * and the canonical JSON of a flat record whose members are all required strings or one safe integer: on that domain
+ * the encoding is injective, so a ciphertext cannot move between accounts, providers, owners, digests, positions, DEK
+ * generations, wrap kinds, recipient keys or format versions. The label names the format version and, for the raw
+ * AES-GCM paths, the exact algorithm: AES-256-GCM, 96-bit nonce, 128-bit tag.
+ *
+ * Nonces come from the CSPRNG only, never a counter: K_cfg is sealed by every enrolled device. NIST SP 800-38D allows
+ * 2^32 random-nonce seals per key; a DEK sees about fields x refreshes and K_cfg one seal per publish per device, both
+ * orders of magnitude below. AES-GCM is not key-committing; that is safe here because every key is 256-bit random and
+ * only a dekId's owner can submit a wrap for it, who could plant any value anyway. AES-GCM-SIV is not in Web Crypto.
+ */
+import { canonicalJson } from "@earendil-works/pi-agent-core";
+import { hpkeOpenBase, hpkeSealBase, SealedFormatError } from "./hpke.js";
+export { SealedFormatError } from "./hpke.js";
+const isSourceDigest = (value) => /^[A-Za-z0-9:_-]{1,256}$/.test(value);
+const isDekId = (value) => /^[A-Za-z0-9_-]{1,128}$/.test(value);
+/** The one boundary parser for a source digest read from an entry; a FieldAad cannot be built without one. */
+export function parseSourceDigest(value) {
+    if (!isSourceDigest(value))
+        throw new SealedFormatError("invalid_aad");
+    return value;
+}
+/** The one boundary parser for a dekId read from an entry; a FieldAad cannot be built without one. */
+export function parseDekId(value) {
+    if (!isDekId(value))
+        throw new SealedFormatError("invalid_aad");
+    return value;
+}
+export const HPKE_SUITE = "DHKEM(P-256,HKDF-SHA256)/HKDF-SHA256/AES-256-GCM";
+const NONCE_BYTES = 12;
+const TAG_BYTES = 16;
+const KEY_BYTES = 32;
+const encoder = new TextEncoder();
+function text(value) {
+    if (typeof value !== "string")
+        throw new SealedFormatError("invalid_aad");
+    return value;
+}
+function counter(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+        throw new SealedFormatError("invalid_aad");
+    return value;
+}
+function aadBytes(label, record) {
+    return encoder.encode(`${label}\u0000${canonicalJson(record)}`);
+}
+/** @internal Exposed for the encoding vectors. */
+export function fieldAadBytes(aad) {
+    return aadBytes("omo-custody/field-aad/v1", {
+        account: text(aad.account),
+        provider: text(aad.provider),
+        owner: text(aad.owner),
+        sourceDigest: text(aad.sourceDigest),
+        field: text(aad.field),
+        dekId: text(aad.dekId),
+    });
+}
+/** @internal Exposed for the encoding vectors. */
+export function wrapAadBytes(aad) {
+    return aadBytes("omo-custody/wrap-aad/v1", {
+        account: text(aad.account),
+        kind: text(aad.kind),
+        id: text(aad.id),
+        recipientKeyId: text(aad.recipientKeyId),
+    });
+}
+/** @internal Exposed for the encoding vectors. */
+export function configAadBytes(aad) {
+    return aadBytes("omo-custody/cfg-aad/v1", {
+        accountId: text(aad.accountId),
+        version: counter(aad.version),
+        cfgKeyId: text(aad.cfgKeyId),
+    });
+}
+const wrapInfo = (kind) => encoder.encode(`omo-custody/wrap/v1/${kind}`);
+function encodeBase64Url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+/** Strict: no padding, no foreign characters, no non-zero trailing bits, so one byte string has one encoding. */
+export function decodeBase64Url(value) {
+    if (!/^[A-Za-z0-9_-]*$/.test(value) || value.length % 4 === 1)
+        throw new SealedFormatError("open_failed");
+    const binary = atob(value.replaceAll("-", "+").replaceAll("_", "/"));
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    if (encodeBase64Url(bytes) !== value)
+        throw new SealedFormatError("open_failed");
+    return bytes;
+}
+async function aesKey(key, usage) {
+    if (key.length !== KEY_BYTES)
+        throw new SealedFormatError("invalid_key");
+    return crypto.subtle.importKey("raw", Uint8Array.from(key), { name: "AES-GCM" }, false, [usage]);
+}
+async function aes256GcmSeal(key, aad, plaintext) {
+    const nonce = crypto.getRandomValues(new Uint8Array(NONCE_BYTES));
+    const ct = await crypto.subtle.encrypt({ name: "AES-GCM", iv: nonce, additionalData: aad, tagLength: TAG_BYTES * 8 }, await aesKey(key, "encrypt"), plaintext);
+    return { nonce: encodeBase64Url(nonce), ct: encodeBase64Url(new Uint8Array(ct)) };
+}
+/** @internal Raw AES-256-GCM open, exposed for the external known-answer vector. Any failure is `open_failed`. */
+export async function aes256GcmOpen(key, nonce, aad, ct) {
+    const cryptoKey = await aesKey(key, "decrypt");
+    if (nonce.length !== NONCE_BYTES || ct.length < TAG_BYTES)
+        throw new SealedFormatError("open_failed");
+    try {
+        const pt = await crypto.subtle.decrypt({
+            name: "AES-GCM",
+            iv: Uint8Array.from(nonce),
+            additionalData: Uint8Array.from(aad),
+            tagLength: TAG_BYTES * 8,
+        }, cryptoKey, Uint8Array.from(ct));
+        return new Uint8Array(pt);
+    }
+    catch {
+        throw new SealedFormatError("open_failed");
+    }
+}
+const openBlob = (key, aad, blob) => aes256GcmOpen(key, decodeBase64Url(blob.nonce), aad, decodeBase64Url(blob.ct));
+function requireVersion1(v) {
+    if (v !== 1)
+        throw new SealedFormatError("unsupported_version");
+}
+/** Seals one secret under the provider DEK. Empty secrets are never sealed. */
+export async function sealField(dek, aad, secret, meta) {
+    if (secret.length === 0)
+        throw new SealedFormatError("empty_secret");
+    const blob = await aes256GcmSeal(dek, fieldAadBytes(aad), encoder.encode(secret));
+    return { v: 1, state: "sealed", ...blob, meta };
+}
+/** Opens a sealed field under the AAD the opener rebuilt from the entry and the requested position. */
+export async function openField(dek, aad, field) {
+    requireVersion1(field.v);
+    if (field.state !== "sealed")
+        throw new SealedFormatError("open_failed");
+    return openBlob(dek, fieldAadBytes(aad), field);
+}
+export function sealConfig(kCfg, aad, plaintext) {
+    return aes256GcmSeal(kCfg, configAadBytes(aad), Uint8Array.from(plaintext));
+}
+/** Opens the config object; its AAD is rebuilt from the envelope's own public fields. */
+export async function openConfig(kCfg, envelope) {
+    requireVersion1(envelope.v);
+    return openBlob(kCfg, configAadBytes(envelope), envelope.cfg);
+}
+export async function wrapKey(recipientPublicKey, aad, key) {
+    if (key.length === 0)
+        throw new SealedFormatError("invalid_key");
+    const sealed = await hpkeSealBase(recipientPublicKey, { info: wrapInfo(aad.kind), aad: wrapAadBytes(aad), pt: key });
+    return { suite: HPKE_SUITE, enc: encodeBase64Url(sealed.enc), ct: encodeBase64Url(sealed.ct) };
+}
+/** Opens a wrap at `position` with the recipient's own key id; nothing read from the wrap enters the AAD. */
+export async function unwrapKey(recipient, position, wrap) {
+    if (wrap.suite !== HPKE_SUITE)
+        throw new SealedFormatError("unsupported_version");
+    const aad = {
+        account: position.account,
+        kind: position.kind,
+        id: position.id,
+        recipientKeyId: recipient.keyId,
+    };
+    return hpkeOpenBase(recipient, {
+        enc: decodeBase64Url(wrap.enc),
+        ct: decodeBase64Url(wrap.ct),
+        info: wrapInfo(aad.kind),
+        aad: wrapAadBytes(aad),
+    });
+}
+//# sourceMappingURL=sealed-format.js.map

package/dist/core/egress/wire.d.ts

@@ -0,0 +1,226 @@
+/**
+ * The brain-to-hand `model` lane of hosted model-key custody (row CK7; custody design 2.2, 4.3, 4.6, 15.14, 15.15).
+ *
+ * Message shapes only: the brain's device-proxy egress (CK9), the hand's provider-call executor (CK8), the hook and
+ * refresh channels (CK16, CK21) and the publisher (CK12d) speak these. Every request that makes the hand execute
+ * something carries a `SignedPlacementClaim`, checked by `verifyPlacementClaim` before anything runs.
+ */
+import type { DeviceId, ProviderId, WaitCondition } from "@earendil-works/pi-agent-core";
+import type { AssistantMessageEvent, SimpleStreamOptions, StopReason, TranscriptContext, Usage } from "@earendil-works/pi-ai";
+import type { OpenAiCompactBody } from "../extensions/builtin/compaction/openai-remote-schema.ts";
+import type { UrlSecretField } from "./endpoint.ts";
+import type { SignedPlacementClaim } from "./placement-claim.ts";
+import type { ServiceKeyEntry } from "./roster-entries.ts";
+/**
+ * The stream options a brain may send a hand: serializable request shaping only. Never secrets or headers, callbacks,
+ * signals or live objects, or the loop-only `commitStep` (4.3, 2.3 options hygiene). `env` stays hand-local because
+ * provider adapters resolve the model `baseUrl` from it: a brain-supplied `env` could redirect the hand's dial, with
+ * the hand's own API key, to a gateway of the brain's choosing. `cwd` stays hand-local because the start message's
+ * `cwd` is the one source the hand interprets.
+ */
+export declare const WIRE_STREAM_OPTION_KEYS: readonly ["abortServerSideFallback", "affinitySessionId", "cacheRetention", "deferred", "extraBody", "maxRetries", "maxRetryDelayMs", "maxTokens", "metadata", "reasoning", "refusalFallbacks", "samplingParams", "serviceTier", "sessionAffinityKey", "sessionId", "streamKind", "temperature", "thinkingBudgets", "thinkingSelection", "timeoutMs", "toolChoice", "transport", "websocketConnectTimeoutMs"];
+export type WireStreamOptions = Pick<SimpleStreamOptions, (typeof WIRE_STREAM_OPTION_KEYS)[number]>;
+export type HandLocalStreamOptionKey = Exclude<keyof SimpleStreamOptions, keyof WireStreamOptions>;
+export declare const PROVIDER_CALL_ERROR_CODES: readonly ["auth", "rate_limited", "unavailable", "aborted", "unknown_provider", "local_only_unsupported", "stale_epoch", "claim_expired", "claim_invalid", "registry_key_unknown", "registry_key_revoked", "definition_mismatch"];
+export type ProviderCallErrorCode = (typeof PROVIDER_CALL_ERROR_CODES)[number];
+export type SecretField = "apiKey" | `credential:${number}` | `header:${string}` | `modelHeader:${string}:${string}` | UrlSecretField;
+/** A JSON value, for payloads whose precise schema another row owns (see `HookModelRequestInput`, `WrapTable`). */
+export type WireJson = string | number | boolean | null | readonly WireJson[] | {
+    readonly [key: string]: WireJson;
+};
+/** The serializable projection of today's request-hook input; CK21 pins its golden shape. */
+export type HookModelRequestInput = WireJson;
+/** keyId -> recipientKeyId -> HPKE wrap, the wraps-document tables (2.2); CK3 owns the wrap encoding. */
+export type WrapTable = Readonly<Record<string, Readonly<Record<string, WireJson>>>>;
+export type ProviderCallKind = {
+    readonly kind: "step";
+    readonly stepId: string;
+    readonly attempt: number;
+} | {
+    readonly kind: "aux";
+    readonly auxId: string;
+    readonly streamKind: string;
+    readonly auxKind: "stream" | "warm" | "compact-endpoint";
+};
+/** Step, aux `stream` and aux `warm` carry the admitted request; `compact-endpoint` carries only the body (15.14). */
+export type ProviderCallRequest = {
+    readonly context: TranscriptContext;
+    readonly options: WireStreamOptions;
+} | {
+    readonly compactBody: OpenAiCompactBody;
+};
+export interface ProviderCallStart {
+    readonly t: "provider.call.start";
+    readonly callId: string;
+    readonly sessionId: string;
+    readonly call: ProviderCallKind;
+    readonly claim: SignedPlacementClaim;
+    readonly providerId: ProviderId;
+    readonly modelId: string;
+    readonly expectedSourceDigest?: string;
+    /** Always `"disabled"` for aux calls. */
+    readonly hooks: "enabled" | "disabled";
+    readonly cwd?: string;
+    readonly request: ProviderCallRequest;
+    readonly budget: {
+        readonly deadlineMs: number;
+        readonly maxOutputTokens?: number;
+    };
+}
+/** Sent once, before the dial, when the hand ran the session's request hooks; seq 0 is reserved for it. */
+export interface ProviderCallHooked {
+    readonly t: "provider.call.hooked";
+    readonly callId: string;
+    readonly seq: 0;
+    readonly request: ProviderCallRequest;
+}
+export interface ProviderCallEvent {
+    readonly t: "provider.call.event";
+    readonly callId: string;
+    readonly seq: number;
+    readonly event: AssistantMessageEvent;
+}
+export interface ProviderCallEnd {
+    readonly t: "provider.call.end";
+    readonly callId: string;
+    readonly seq: number;
+    readonly usage: Usage;
+    readonly stopReason: StopReason;
+}
+export interface ProviderCallError {
+    readonly t: "provider.call.error";
+    readonly callId: string;
+    readonly seq: number;
+    readonly code: ProviderCallErrorCode;
+    readonly until?: number;
+    readonly retryable: boolean;
+    readonly usage?: Usage;
+    readonly message: string;
+}
+export interface ProviderCallCancel {
+    readonly t: "provider.call.cancel";
+    readonly callId: string;
+    readonly reason: "user" | "superseded" | "budget" | "shutdown";
+}
+export interface ProviderCallAck {
+    readonly t: "provider.call.ack";
+    readonly callId: string;
+}
+export interface ProviderCallResultQuery {
+    readonly t: "provider.call.result";
+    readonly callId: string;
+    readonly claim: SignedPlacementClaim;
+}
+export type ProviderCallResultReply = {
+    readonly t: "provider.call.result.reply";
+    readonly callId: string;
+    readonly state: "unknown";
+} | {
+    readonly t: "provider.call.result.reply";
+    readonly callId: string;
+    readonly state: "running";
+    readonly lastSeq: number;
+    readonly hooked?: ProviderCallHooked;
+} | {
+    readonly t: "provider.call.result.reply";
+    readonly callId: string;
+    readonly state: "done";
+    readonly hooked?: ProviderCallHooked;
+    readonly events: readonly AssistantMessageEvent[];
+    readonly end: ProviderCallEnd | ProviderCallError;
+};
+export interface CustodyRefreshRequest {
+    readonly t: "custody.refresh.request";
+    readonly providerId: ProviderId;
+    readonly field: SecretField;
+    readonly version: number;
+    readonly claim: SignedPlacementClaim;
+}
+export interface CustodyRefreshAck {
+    readonly t: "custody.refresh.ack";
+    readonly providerId: ProviderId;
+    readonly field: SecretField;
+    readonly outcome: "changed" | "unchanged" | "unresolved";
+    readonly version?: number;
+}
+/** `recipient`: a device enrolled during a custody kill that needs K_cfg/K_proj wraps from a peer (6.6(d), 3.6). */
+export interface CustodyRewrapRequest {
+    readonly t: "custody.rewrap.request";
+    readonly dekIds: readonly string[];
+    readonly custodyEntry: ServiceKeyEntry;
+    readonly recipient?: DeviceId;
+}
+/** Device to device over the hand channel; never sent to the service. */
+export interface CustodyRewrapDeliver {
+    readonly t: "custody.rewrap.deliver";
+    readonly recipient: DeviceId;
+    readonly cfgWraps: WrapTable;
+    readonly projWraps: WrapTable;
+    readonly projCheck: Readonly<Record<string, string>>;
+    readonly sig: string;
+}
+export interface HookModelRequest {
+    readonly t: "hook.model_request";
+    readonly sessionId: string;
+    readonly stepId: string;
+    readonly claim: SignedPlacementClaim;
+    readonly input: HookModelRequestInput;
+}
+export interface HookModelRequestReply {
+    readonly t: "hook.model_request.reply";
+    readonly sessionId: string;
+    readonly stepId: string;
+    readonly output: HookModelRequestInput;
+}
+export interface HandSessionAdvertisement {
+    readonly t: "hand.session.advertise";
+    readonly sessionId: string;
+    readonly connectionId: string;
+    readonly cwd: string;
+    /** H(extension set hash, cwd, project-local hook set), per session (4.9). */
+    readonly advertHash: string;
+    readonly requestHooks: readonly ProviderId[] | "*";
+    readonly streamHooks: readonly ProviderId[] | "*";
+    readonly extensionProviders: readonly ProviderId[];
+    readonly handLocalProviders: readonly {
+        readonly id: ProviderId;
+        readonly models: readonly string[];
+    }[];
+    readonly handDefines: readonly ProviderId[];
+}
+export interface HandPresence {
+    readonly deviceId: DeviceId;
+    readonly online: boolean;
+    readonly capabilities: readonly string[];
+    /** sessionId -> advertHash for the sessions bound to this hand. */
+    readonly sessionAdverts?: Readonly<Record<string, string>>;
+    /** providerId -> this device's current live sourceDigest for the providers it defines; re-sent on file change. */
+    readonly liveDigests?: Readonly<Record<ProviderId, string>>;
+}
+export type StepNotice = {
+    readonly t: "step.waiting";
+    readonly sessionId: string;
+    readonly stepId: string;
+    readonly steer: string;
+    readonly waitFor: readonly WaitCondition[];
+} | {
+    readonly t: "step.resumed";
+    readonly sessionId: string;
+    readonly stepId: string;
+} | {
+    readonly t: "step.reset";
+    readonly sessionId: string;
+    readonly stepId: string;
+    readonly cause: "superseded" | "readmitted";
+};
+export interface ProviderCallChannel {
+    start(msg: ProviderCallStart): Promise<void>;
+    result(msg: ProviderCallResultQuery): Promise<ProviderCallResultReply>;
+    ack(msg: ProviderCallAck): Promise<void>;
+    cancel(msg: ProviderCallCancel): Promise<void>;
+    /** Resumes from any seq; `fromSeq: 0` includes `hooked`. */
+    events(callId: string, fromSeq: number): AsyncIterable<ProviderCallHooked | ProviderCallEvent | ProviderCallEnd | ProviderCallError>;
+    readonly presence: AsyncIterable<HandPresence>;
+    readonly hooks: AsyncIterable<HandSessionAdvertisement>;
+}
+//# sourceMappingURL=wire.d.ts.map

package/dist/core/egress/wire.js

@@ -0,0 +1,47 @@
+/**
+ * The stream options a brain may send a hand: serializable request shaping only. Never secrets or headers, callbacks,
+ * signals or live objects, or the loop-only `commitStep` (4.3, 2.3 options hygiene). `env` stays hand-local because
+ * provider adapters resolve the model `baseUrl` from it: a brain-supplied `env` could redirect the hand's dial, with
+ * the hand's own API key, to a gateway of the brain's choosing. `cwd` stays hand-local because the start message's
+ * `cwd` is the one source the hand interprets.
+ */
+export const WIRE_STREAM_OPTION_KEYS = [
+    "abortServerSideFallback",
+    "affinitySessionId",
+    "cacheRetention",
+    "deferred",
+    "extraBody",
+    "maxRetries",
+    "maxRetryDelayMs",
+    "maxTokens",
+    "metadata",
+    "reasoning",
+    "refusalFallbacks",
+    "samplingParams",
+    "serviceTier",
+    "sessionAffinityKey",
+    "sessionId",
+    "streamKind",
+    "temperature",
+    "thinkingBudgets",
+    "thinkingSelection",
+    "timeoutMs",
+    "toolChoice",
+    "transport",
+    "websocketConnectTimeoutMs",
+];
+export const PROVIDER_CALL_ERROR_CODES = [
+    "auth",
+    "rate_limited",
+    "unavailable",
+    "aborted",
+    "unknown_provider",
+    "local_only_unsupported",
+    "stale_epoch",
+    "claim_expired",
+    "claim_invalid",
+    "registry_key_unknown",
+    "registry_key_revoked",
+    "definition_mismatch",
+];
+//# sourceMappingURL=wire.js.map

package/dist/core/extensions/builtin/ask-user/escape-residue.d.ts

@@ -0,0 +1,50 @@
+import type { Question } from "./schema.ts";
+/**
+ * Escape residue in question text (oh-my-openagent#12797). Some models write non-ASCII tool-call text as
+ * `\uXXXX` escapes and then drop the backslash (`ub0b4 Tailscale 쓰기` for `내 Tailscale 쓰기`) or double it, so
+ * the decoded string still holds `\ub0b4`. The JSON is valid either way; only the text is wrong.
+ *
+ * Heuristic, applied to every header, question, option label and option description after quoted code is blanked
+ * out (fenced ``` or ~~~ blocks, then ``...`` spans, then `...` spans), since quoted code may name an escape on purpose:
+ * - A literal `\uXXXX` whose code point is non-ASCII is residue.
+ * - A bare run of `uXXXX` tokens is a candidate only when no ASCII letter, digit, `_` or `\` precedes it and
+ *   none follows it, so `menu1234`, `u1a2b3c4d` and other hex-like ids never match. A candidate is residue
+ *   when it decodes to non-ASCII text and either
+ *   - the run has two or more tokens (`ub0b4uc4f0`), each decoding to a letter, mark, number, punctuation or
+ *     symbol (a paired surrogate counts), or
+ *   - its single token decodes to a letter in a script the question set already uses outside ASCII, with
+ *     Hangul, Han, Hiragana, Katakana and Bopomofo counted as one family (a wrong high digit lands a Hangul
+ *     syllable in Han). `u1234` in English text, or beside Korean text, decodes to Ethiopic and stays.
+ * Known gap: a token glued to a preceding ASCII letter (`cafu00e9`) is not detected.
+ * Known limit: an escape named in plain prose outside code (\u00e9 with no backticks) is refused once like residue;
+ * its re-call opens as written.
+ */
+export type EscapeResidue = {
+    field: string;
+    token: string;
+};
+export declare function findEscapeResidue(questions: readonly Question[]): EscapeResidue[];
+/**
+ * The one-refusal bound, scoped to assistant turns. One assistant message's tool calls run in parallel inside one turn,
+ * and the model sees a refusal only after that turn ends. So every residue call in a turn with no open retry is refused,
+ * and every residue call in a later turn opens as written with a warning, whether or not its text changed. The retry
+ * stays open until a turn uses it, so no question set is refused twice in a row and a re-call can never loop.
+ */
+export type EscapeResidueRetry = {
+    refusedThisTurn: boolean;
+    retryOpen: boolean;
+    retriedThisTurn: boolean;
+};
+export declare function freshEscapeResidueRetry(): EscapeResidueRetry;
+/**
+ * Records any call; true means refuse it. A call made while the retry is open uses it up, clean or not, so a clean
+ * re-call closes the retry and a later residue set is refused once again. A residue call with no open retry is refused.
+ */
+export declare function refuseEscapeResidue(retry: EscapeResidueRetry, hasResidue: boolean): boolean;
+export declare function endEscapeResidueTurn(retry: EscapeResidueRetry): void;
+export declare class AskUserEscapeResidueError extends Error {
+    readonly residue: EscapeResidue[];
+    constructor(residue: EscapeResidue[]);
+}
+export declare function escapeResidueNote(residue: readonly EscapeResidue[]): string;
+//# sourceMappingURL=escape-residue.d.ts.map

package/dist/core/extensions/builtin/ask-user/escape-residue.js

@@ -0,0 +1,113 @@
+const BARE_RUN = /(?<![\\A-Za-z0-9_])((?:u[0-9a-fA-F]{4})+)(?![A-Za-z0-9_])/g;
+const LITERAL = /\\u([0-9a-fA-F]{4})/g;
+// Order matters: a fence holds backticks and newlines, and a double-backtick span may hold a single backtick.
+const QUOTED_CODE = [/(```|~~~)[\s\S]*?\1/g, /``[^\n]*?``/g, /`[^`\n]*`/g];
+const NON_ASCII_LETTER = /(?!\p{ASCII})\p{L}/gu;
+const PRINTABLE = /^[\p{L}\p{M}\p{N}\p{P}\p{S}]$/u;
+const CJK_FAMILY = "CJK";
+const SCRIPTS = [
+    [CJK_FAMILY, /[\p{Script=Hangul}\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Bopomofo}]/u],
+    ["Latin", /\p{Script=Latin}/u],
+    ["Cyrillic", /\p{Script=Cyrillic}/u],
+    ["Greek", /\p{Script=Greek}/u],
+    ["Arabic", /\p{Script=Arabic}/u],
+    ["Hebrew", /\p{Script=Hebrew}/u],
+    ["Thai", /\p{Script=Thai}/u],
+    ["Devanagari", /\p{Script=Devanagari}/u],
+];
+function scriptOf(char) {
+    return SCRIPTS.find(([, pattern]) => pattern.test(char))?.[0];
+}
+function decode(run) {
+    const units = [];
+    for (let index = 1; index < run.length; index += 5)
+        units.push(Number.parseInt(run.slice(index, index + 4), 16));
+    return String.fromCharCode(...units);
+}
+function isResidueRun(run, scripts) {
+    const decoded = decode(run);
+    const chars = Array.from(decoded);
+    if (chars.some((char) => (char.codePointAt(0) ?? 0) < 0x80))
+        return false;
+    if (run.length > 5)
+        return chars.every((char) => PRINTABLE.test(char));
+    const char = chars[0] ?? "";
+    if (!/\p{L}/u.test(char))
+        return false;
+    const script = scriptOf(char);
+    return script !== undefined && scripts.has(script);
+}
+function textFields(questions) {
+    const fields = [];
+    questions.forEach((question, index) => {
+        const at = `questions[${index}]`;
+        fields.push([`${at}.header`, question.header], [`${at}.question`, question.question]);
+        question.options.forEach((option, optionIndex) => {
+            fields.push([`${at}.options[${optionIndex}].label`, option.label]);
+            if (option.description !== undefined)
+                fields.push([`${at}.options[${optionIndex}].description`, option.description]);
+        });
+    });
+    return fields;
+}
+export function findEscapeResidue(questions) {
+    const fields = textFields(questions).map(([field, text]) => [
+        field,
+        QUOTED_CODE.reduce((masked, pattern) => masked.replace(pattern, (span) => " ".repeat(span.length)), text),
+    ]);
+    const scripts = new Set();
+    for (const [, text] of fields) {
+        for (const [char] of text.matchAll(NON_ASCII_LETTER)) {
+            const script = scriptOf(char);
+            if (script !== undefined)
+                scripts.add(script);
+        }
+    }
+    const residue = [];
+    for (const [field, text] of fields) {
+        for (const match of text.matchAll(LITERAL)) {
+            if (Number.parseInt(match[1] ?? "0", 16) >= 0x80)
+                residue.push({ field, token: match[0] });
+        }
+        for (const match of text.matchAll(BARE_RUN)) {
+            const run = match[1] ?? "";
+            if (isResidueRun(run, scripts))
+                residue.push({ field, token: run });
+        }
+    }
+    return residue;
+}
+export function freshEscapeResidueRetry() {
+    return { refusedThisTurn: false, retryOpen: false, retriedThisTurn: false };
+}
+/**
+ * Records any call; true means refuse it. A call made while the retry is open uses it up, clean or not, so a clean
+ * re-call closes the retry and a later residue set is refused once again. A residue call with no open retry is refused.
+ */
+export function refuseEscapeResidue(retry, hasResidue) {
+    if (retry.retryOpen) {
+        retry.retriedThisTurn = true;
+        return false;
+    }
+    if (hasResidue)
+        retry.refusedThisTurn = true;
+    return hasResidue;
+}
+export function endEscapeResidueTurn(retry) {
+    retry.retryOpen = retry.refusedThisTurn || (retry.retryOpen && !retry.retriedThisTurn);
+    retry.refusedThisTurn = false;
+    retry.retriedThisTurn = false;
+}
+export class AskUserEscapeResidueError extends Error {
+    constructor(residue) {
+        const found = residue.map(({ field, token }) => `${field} has "${token}"`).join("; ");
+        super(`Escape residue in the question text: ${found}. Non-ASCII text was written as a \\uXXXX escape that lost its backslash or kept a literal one, so the user would see the code instead of the character. Call this tool again with the same questions, writing every non-ASCII character directly as UTF-8 text, never as a \\uXXXX escape.`);
+        this.name = "AskUserEscapeResidueError";
+        this.residue = residue;
+    }
+}
+export function escapeResidueNote(residue) {
+    const tokens = [...new Set(residue.map(({ token }) => token))].join(", ");
+    return `This question may show undecoded character codes (${tokens}); it is shown as the model wrote it.`;
+}
+//# sourceMappingURL=escape-residue.js.map

package/dist/core/extensions/builtin/ask-user/extension.js

@@ -1,4 +1,5 @@
 import { APP_NAME } from "../../../../config.js";
+import { endEscapeResidueTurn, freshEscapeResidueRetry } from "./escape-residue.js";
 import { pickVariant, TOOL_NAMES } from "./family.js";
 import { deliverQueuedQuestionOutcomes, getPendingQuestions } from "./registry.js";
 import { resumeDanglingQuestion } from "./resume.js";
@@ -19,7 +20,7 @@ export default function askUserExtension(pi) {
             // In TUI mode interactive-mode's text dispatch handles /answer first.
         },
     });
-    const state = { timedOut: false, unavailable: false };
+    const state = { timedOut: false, unavailable: false, escapeResidue: freshEscapeResidueRetry() };
     let registered = false;
     const cancelPending = (ctx, origin, message, reportDetachedLoss = false) => {
         for (const entry of getPendingQuestions(ctx.sessionManager.getSessionId()))
@@ -42,6 +43,7 @@ export default function askUserExtension(pi) {
     pi.on("session_start", async (event, ctx) => {
         state.timedOut = false;
         state.unavailable = false;
+        state.escapeResidue = freshEscapeResidueRetry();
         const sessionId = ctx.sessionManager.getSessionId();
         for (const entry of getPendingQuestions(sessionId))
             entry.rebind(pi, ctx, state);
@@ -61,8 +63,12 @@ export default function askUserExtension(pi) {
     pi.on("model_select", async (event, ctx) => {
         sync(ctx, event.model);
     });
+    pi.on("turn_end", () => {
+        endEscapeResidueTurn(state.escapeResidue);
+    });
     pi.on("agent_end", async () => {
         state.timedOut = false;
+        state.escapeResidue = freshEscapeResidueRetry();
     });
     pi.on("session_shutdown", async (event, ctx) => {
         if (event.reason === "reload") {

package/dist/core/extensions/builtin/ask-user/resume.js

@@ -1,3 +1,4 @@
+import { freshEscapeResidueRetry } from "./escape-residue.js";
 import { TOOL_NAMES } from "./family.js";
 import { parseAskUserAnswerFrame } from "./format.js";
 import { ASK_USER_SETTLEMENT_ENTRY, emitAskUserClosed } from "./notify.js";
@@ -143,7 +144,7 @@ export async function resumeDanglingQuestion(pi, event, ctx) {
             continue;
         }
         // The runtime registration owns delivery, including after another reload.
-        void startQuestion(pi, ctx, request, ctx.signal, { timedOut: false, unavailable: false }, dangling.variant, {
+        void startQuestion(pi, ctx, request, ctx.signal, { timedOut: false, unavailable: false, escapeResidue: freshEscapeResidueRetry() }, dangling.variant, {
             resuming: true,
         });
     }

package/dist/core/extensions/builtin/ask-user/tool.d.ts

@@ -1,8 +1,11 @@
 import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "../../types.ts";
+import { type EscapeResidueRetry } from "./escape-residue.ts";
 import { type AskUserVariant, type QuestionRequest, type QuestionResponse } from "./schema.ts";
 export interface AskUserState {
     timedOut: boolean;
     unavailable: boolean;
+    /** One refusal per turn of residue calls; the re-calls in a later turn open as written (oh-my-openagent#12797). */
+    escapeResidue: EscapeResidueRetry;
 }
 /**
  * Deliver a settled async answer as one framed user message. The extension owns