open-multi-agent-kit 0.96.2 → 0.97.0

package/dist/core/package-doctor-source-scan.js

@@ -1,7 +1,8 @@
 import { closeSync, constants, fstatSync, openSync, readSync, realpathSync, statSync } from "node:fs";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 const MAX_EXTENSION_FILES = 256;
 const MAX_EXTENSION_BYTES = 1_048_576;
+const SOURCE_EXTENSIONS = [".ts", ".mts", ".cts", ".tsx", ".js", ".mjs", ".cjs", ".jsx"];
 export const PACKAGE_DOCTOR_SUPPORTED_EVENTS = new Set([
     "resources_discover",
     "session_start",
@@ -18,6 +19,7 @@ export const PACKAGE_DOCTOR_SUPPORTED_EVENTS = new Set([
     "before_agent_start",
     "agent_start",
     "agent_end",
+    "agent_settled",
     "turn_start",
     "turn_end",
     "message_start",
@@ -41,16 +43,85 @@ function packageRelativePath(root, path) {
         return null;
     return candidate.replace(/\\/gu, "/");
 }
+/**
+ * True only for an existing regular file. A bare `existsSync` also matches the
+ * directory a specifier like `./nested` names, which would shadow its real
+ * `./nested/index.ts` target.
+ */
+function isFilePath(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Candidate on-disk paths for one relative import specifier. */
+function resolutionCandidates(fromFile, specifier) {
+    const base = resolve(dirname(fromFile), specifier);
+    const candidates = [base];
+    for (const extension of SOURCE_EXTENSIONS) {
+        candidates.push(`${base}${extension}`, resolve(base, `index${extension}`));
+    }
+    // TypeScript source commonly imports its own emitted specifier (`./x.js`).
+    const rewritten = base.replace(/\.(?:js|mjs|cjs|jsx)$/u, "");
+    if (rewritten !== base) {
+        for (const extension of SOURCE_EXTENSIONS)
+            candidates.push(`${rewritten}${extension}`);
+    }
+    return candidates;
+}
+/**
+ * Relative imports of `text` that resolve to a real file inside the package.
+ * Bare specifiers (`node:fs`, `some-package`) are dependencies, not package
+ * source, and anything resolving outside the root is dropped rather than read.
+ */
+function relativeImportTargets(root, fromFile, text) {
+    const targets = [];
+    for (const specifier of importedSpecifiers(text)) {
+        if (!specifier.startsWith("./") && !specifier.startsWith("../"))
+            continue;
+        for (const candidate of resolutionCandidates(fromFile, specifier)) {
+            if (packageRelativePath(root, candidate) === null)
+                continue;
+            if (!isFilePath(candidate))
+                continue;
+            targets.push(candidate);
+            break;
+        }
+    }
+    return targets;
+}
+/**
+ * Read every package-owned extension source reachable from the manifest entries.
+ *
+ * Scanning only the declared entry files made the compatibility verdict wrong
+ * for any package that keeps handlers in imported modules, so the walk follows
+ * relative imports transitively. Package-external reads stay impossible: a
+ * candidate must resolve inside the root, and each open still verifies the
+ * realpath, refuses symlinks, and matches device/inode before reading.
+ */
 export function scanPackageExtensionSources(root, extensions) {
     const sources = [];
     const skipped = [];
     const realRoot = realpathSync(root);
-    for (const path of [...new Set(extensions)].slice(0, MAX_EXTENSION_FILES)) {
+    const seen = new Set();
+    const queue = [...new Set(extensions)];
+    let truncated = extensions.length > MAX_EXTENSION_FILES;
+    while (queue.length > 0) {
+        if (sources.length >= MAX_EXTENSION_FILES) {
+            truncated = true;
+            break;
+        }
+        const path = queue.shift();
         const file = packageRelativePath(root, path);
         if (file === null) {
             skipped.push("<outside-package>");
             continue;
         }
+        if (seen.has(file))
+            continue;
+        seen.add(file);
         let fd;
         try {
             const realPath = realpathSync(path);
@@ -77,7 +148,9 @@ export function scanPackageExtensionSources(root, extensions) {
                 skipped.push(file);
                 continue;
             }
-            sources.push({ file, text: buffer.subarray(0, offset).toString("utf8") });
+            const text = buffer.subarray(0, offset).toString("utf8");
+            sources.push({ file, text });
+            queue.push(...relativeImportTargets(root, path, text));
         }
         catch {
             skipped.push(file);
@@ -87,7 +160,7 @@ export function scanPackageExtensionSources(root, extensions) {
                 closeSync(fd);
         }
     }
-    if (extensions.length > MAX_EXTENSION_FILES)
+    if (truncated)
         skipped.push("<file-limit>");
     return { sources, skipped };
 }

package/dist/core/package-doctor-source-scan.js.map

@@ -1 +1 @@
-{"version":3,"file":"package-doctor-source-scan.js","sourceRoot":"","sources":["../../src/core/package-doctor-source-scan.ts"],"names":[],"mappings":"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","sourcesContent":["import { closeSync, constants, fstatSync, openSync, readSync, realpathSync, statSync } from \"node:fs\";\nimport { isAbsolute, relative, resolve, sep } from \"node:path\";\n\nconst MAX_EXTENSION_FILES = 256;\nconst MAX_EXTENSION_BYTES = 1_048_576;\n\nexport const PACKAGE_DOCTOR_SUPPORTED_EVENTS = new Set([\n\t\"resources_discover\",\n\t\"session_start\",\n\t\"session_before_switch\",\n\t\"session_before_fork\",\n\t\"session_before_compact\",\n\t\"session_compact\",\n\t\"session_shutdown\",\n\t\"session_before_tree\",\n\t\"session_tree\",\n\t\"context\",\n\t\"before_provider_request\",\n\t\"after_provider_response\",\n\t\"before_agent_start\",\n\t\"agent_start\",\n\t\"agent_end\",\n\t\"turn_start\",\n\t\"turn_end\",\n\t\"message_start\",\n\t\"message_update\",\n\t\"message_end\",\n\t\"tool_execution_start\",\n\t\"tool_execution_update\",\n\t\"tool_execution_end\",\n\t\"model_select\",\n\t\"thinking_level_select\",\n\t\"tool_call\",\n\t\"tool_result\",\n\t\"user_bash\",\n\t\"input\",\n]);\n\nexport interface ScannedPackageSource {\n\tfile: string;\n\ttext: string;\n}\n\nfunction packageRelativePath(root: string, path: string): string | null {\n\tconst candidate = relative(root, resolve(path));\n\tif (!candidate || candidate === \".\") return candidate || \".\";\n\tif (candidate === \"..\" || candidate.startsWith(`..${sep}`) || isAbsolute(candidate)) return null;\n\treturn candidate.replace(/\\\\/gu, \"/\");\n}\n\nexport function scanPackageExtensionSources(\n\troot: string,\n\textensions: string[],\n): { sources: ScannedPackageSource[]; skipped: string[] } {\n\tconst sources: ScannedPackageSource[] = [];\n\tconst skipped: string[] = [];\n\tconst realRoot = realpathSync(root);\n\tfor (const path of [...new Set(extensions)].slice(0, MAX_EXTENSION_FILES)) {\n\t\tconst file = packageRelativePath(root, path);\n\t\tif (file === null) {\n\t\t\tskipped.push(\"<outside-package>\");\n\t\t\tcontinue;\n\t\t}\n\t\tlet fd: number | undefined;\n\t\ttry {\n\t\t\tconst realPath = realpathSync(path);\n\t\t\tif (packageRelativePath(realRoot, realPath) === null) {\n\t\t\t\tskipped.push(\"<outside-package>\");\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst expected = statSync(realPath);\n\t\t\tfd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));\n\t\t\tconst opened = fstatSync(fd);\n\t\t\tif (!opened.isFile() || opened.dev !== expected.dev || opened.ino !== expected.ino) {\n\t\t\t\tskipped.push(file);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst buffer = Buffer.alloc(MAX_EXTENSION_BYTES + 1);\n\t\t\tlet offset = 0;\n\t\t\twhile (offset < buffer.length) {\n\t\t\t\tconst read = readSync(fd, buffer, offset, buffer.length - offset, offset);\n\t\t\t\tif (read === 0) break;\n\t\t\t\toffset += read;\n\t\t\t}\n\t\t\tif (offset > MAX_EXTENSION_BYTES) {\n\t\t\t\tskipped.push(file);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tsources.push({ file, text: buffer.subarray(0, offset).toString(\"utf8\") });\n\t\t} catch {\n\t\t\tskipped.push(file);\n\t\t} finally {\n\t\t\tif (fd !== undefined) closeSync(fd);\n\t\t}\n\t}\n\tif (extensions.length > MAX_EXTENSION_FILES) skipped.push(\"<file-limit>\");\n\treturn { sources, skipped };\n}\n\nexport function importedSpecifiers(text: string): string[] {\n\tconst specifiers = new Set<string>();\n\tconst patterns = [\n\t\t/\\b(?:import|export)\\s+(?:[^\"']+?\\s+from\\s+)?[\"']([^\"']+)[\"']/gu,\n\t\t/\\b(?:import|require)\\s*\\(\\s*[\"']([^\"']+)[\"']\\s*\\)/gu,\n\t];\n\tfor (const pattern of patterns) {\n\t\tfor (const match of text.matchAll(pattern)) {\n\t\t\tif (match[1]) specifiers.add(match[1]);\n\t\t}\n\t}\n\treturn [...specifiers];\n}\n\nexport function subscribedEvents(text: string): string[] {\n\tconst events: string[] = [];\n\tfor (const match of text.matchAll(/\\b(?:api|omk|pi)\\.on\\(\\s*[\"']([^\"']+)[\"']/gu)) {\n\t\tif (match[1] !== undefined) events.push(match[1]);\n\t}\n\treturn events;\n}\n\nexport function sourceFilesMatching(sources: ScannedPackageSource[], predicate: (text: string) => boolean): string[] {\n\tconst files: string[] = [];\n\tfor (const source of sources) {\n\t\tif (predicate(source.text)) files.push(source.file);\n\t}\n\treturn files;\n}\n"]}
+{"version":3,"file":"package-doctor-source-scan.js","sourceRoot":"","sources":["../../src/core/package-doctor-source-scan.ts"],"names":[],"mappings":"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","sourcesContent":["import { closeSync, constants, fstatSync, openSync, readSync, realpathSync, statSync } from \"node:fs\";\nimport { dirname, isAbsolute, relative, resolve, sep } from \"node:path\";\n\nconst MAX_EXTENSION_FILES = 256;\nconst MAX_EXTENSION_BYTES = 1_048_576;\nconst SOURCE_EXTENSIONS = [\".ts\", \".mts\", \".cts\", \".tsx\", \".js\", \".mjs\", \".cjs\", \".jsx\"] as const;\n\nexport const PACKAGE_DOCTOR_SUPPORTED_EVENTS = new Set([\n\t\"resources_discover\",\n\t\"session_start\",\n\t\"session_before_switch\",\n\t\"session_before_fork\",\n\t\"session_before_compact\",\n\t\"session_compact\",\n\t\"session_shutdown\",\n\t\"session_before_tree\",\n\t\"session_tree\",\n\t\"context\",\n\t\"before_provider_request\",\n\t\"after_provider_response\",\n\t\"before_agent_start\",\n\t\"agent_start\",\n\t\"agent_end\",\n\t\"agent_settled\",\n\t\"turn_start\",\n\t\"turn_end\",\n\t\"message_start\",\n\t\"message_update\",\n\t\"message_end\",\n\t\"tool_execution_start\",\n\t\"tool_execution_update\",\n\t\"tool_execution_end\",\n\t\"model_select\",\n\t\"thinking_level_select\",\n\t\"tool_call\",\n\t\"tool_result\",\n\t\"user_bash\",\n\t\"input\",\n]);\n\nexport interface ScannedPackageSource {\n\tfile: string;\n\ttext: string;\n}\n\nfunction packageRelativePath(root: string, path: string): string | null {\n\tconst candidate = relative(root, resolve(path));\n\tif (!candidate || candidate === \".\") return candidate || \".\";\n\tif (candidate === \"..\" || candidate.startsWith(`..${sep}`) || isAbsolute(candidate)) return null;\n\treturn candidate.replace(/\\\\/gu, \"/\");\n}\n\n/**\n * True only for an existing regular file. A bare `existsSync` also matches the\n * directory a specifier like `./nested` names, which would shadow its real\n * `./nested/index.ts` target.\n */\nfunction isFilePath(path: string): boolean {\n\ttry {\n\t\treturn statSync(path).isFile();\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/** Candidate on-disk paths for one relative import specifier. */\nfunction resolutionCandidates(fromFile: string, specifier: string): string[] {\n\tconst base = resolve(dirname(fromFile), specifier);\n\tconst candidates = [base];\n\tfor (const extension of SOURCE_EXTENSIONS) {\n\t\tcandidates.push(`${base}${extension}`, resolve(base, `index${extension}`));\n\t}\n\t// TypeScript source commonly imports its own emitted specifier (`./x.js`).\n\tconst rewritten = base.replace(/\\.(?:js|mjs|cjs|jsx)$/u, \"\");\n\tif (rewritten !== base) {\n\t\tfor (const extension of SOURCE_EXTENSIONS) candidates.push(`${rewritten}${extension}`);\n\t}\n\treturn candidates;\n}\n\n/**\n * Relative imports of `text` that resolve to a real file inside the package.\n * Bare specifiers (`node:fs`, `some-package`) are dependencies, not package\n * source, and anything resolving outside the root is dropped rather than read.\n */\nfunction relativeImportTargets(root: string, fromFile: string, text: string): string[] {\n\tconst targets: string[] = [];\n\tfor (const specifier of importedSpecifiers(text)) {\n\t\tif (!specifier.startsWith(\"./\") && !specifier.startsWith(\"../\")) continue;\n\t\tfor (const candidate of resolutionCandidates(fromFile, specifier)) {\n\t\t\tif (packageRelativePath(root, candidate) === null) continue;\n\t\t\tif (!isFilePath(candidate)) continue;\n\t\t\ttargets.push(candidate);\n\t\t\tbreak;\n\t\t}\n\t}\n\treturn targets;\n}\n\n/**\n * Read every package-owned extension source reachable from the manifest entries.\n *\n * Scanning only the declared entry files made the compatibility verdict wrong\n * for any package that keeps handlers in imported modules, so the walk follows\n * relative imports transitively. Package-external reads stay impossible: a\n * candidate must resolve inside the root, and each open still verifies the\n * realpath, refuses symlinks, and matches device/inode before reading.\n */\nexport function scanPackageExtensionSources(\n\troot: string,\n\textensions: string[],\n): { sources: ScannedPackageSource[]; skipped: string[] } {\n\tconst sources: ScannedPackageSource[] = [];\n\tconst skipped: string[] = [];\n\tconst realRoot = realpathSync(root);\n\tconst seen = new Set<string>();\n\tconst queue = [...new Set(extensions)];\n\tlet truncated = extensions.length > MAX_EXTENSION_FILES;\n\n\twhile (queue.length > 0) {\n\t\tif (sources.length >= MAX_EXTENSION_FILES) {\n\t\t\ttruncated = true;\n\t\t\tbreak;\n\t\t}\n\t\tconst path = queue.shift() as string;\n\t\tconst file = packageRelativePath(root, path);\n\t\tif (file === null) {\n\t\t\tskipped.push(\"<outside-package>\");\n\t\t\tcontinue;\n\t\t}\n\t\tif (seen.has(file)) continue;\n\t\tseen.add(file);\n\t\tlet fd: number | undefined;\n\t\ttry {\n\t\t\tconst realPath = realpathSync(path);\n\t\t\tif (packageRelativePath(realRoot, realPath) === null) {\n\t\t\t\tskipped.push(\"<outside-package>\");\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst expected = statSync(realPath);\n\t\t\tfd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));\n\t\t\tconst opened = fstatSync(fd);\n\t\t\tif (!opened.isFile() || opened.dev !== expected.dev || opened.ino !== expected.ino) {\n\t\t\t\tskipped.push(file);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst buffer = Buffer.alloc(MAX_EXTENSION_BYTES + 1);\n\t\t\tlet offset = 0;\n\t\t\twhile (offset < buffer.length) {\n\t\t\t\tconst read = readSync(fd, buffer, offset, buffer.length - offset, offset);\n\t\t\t\tif (read === 0) break;\n\t\t\t\toffset += read;\n\t\t\t}\n\t\t\tif (offset > MAX_EXTENSION_BYTES) {\n\t\t\t\tskipped.push(file);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst text = buffer.subarray(0, offset).toString(\"utf8\");\n\t\t\tsources.push({ file, text });\n\t\t\tqueue.push(...relativeImportTargets(root, path, text));\n\t\t} catch {\n\t\t\tskipped.push(file);\n\t\t} finally {\n\t\t\tif (fd !== undefined) closeSync(fd);\n\t\t}\n\t}\n\tif (truncated) skipped.push(\"<file-limit>\");\n\treturn { sources, skipped };\n}\n\nexport function importedSpecifiers(text: string): string[] {\n\tconst specifiers = new Set<string>();\n\tconst patterns = [\n\t\t/\\b(?:import|export)\\s+(?:[^\"']+?\\s+from\\s+)?[\"']([^\"']+)[\"']/gu,\n\t\t/\\b(?:import|require)\\s*\\(\\s*[\"']([^\"']+)[\"']\\s*\\)/gu,\n\t];\n\tfor (const pattern of patterns) {\n\t\tfor (const match of text.matchAll(pattern)) {\n\t\t\tif (match[1]) specifiers.add(match[1]);\n\t\t}\n\t}\n\treturn [...specifiers];\n}\n\nexport function subscribedEvents(text: string): string[] {\n\tconst events: string[] = [];\n\tfor (const match of text.matchAll(/\\b(?:api|omk|pi)\\.on\\(\\s*[\"']([^\"']+)[\"']/gu)) {\n\t\tif (match[1] !== undefined) events.push(match[1]);\n\t}\n\treturn events;\n}\n\nexport function sourceFilesMatching(sources: ScannedPackageSource[], predicate: (text: string) => boolean): string[] {\n\tconst files: string[] = [];\n\tfor (const source of sources) {\n\t\tif (predicate(source.text)) files.push(source.file);\n\t}\n\treturn files;\n}\n"]}

package/dist/core/prompt-attachment.d.ts

@@ -0,0 +1,51 @@
+/**
+ * First-class prompt image attachments.
+ *
+ * Pure validation/metadata layer between clipboard/file acquisition and
+ * `AgentSession.prompt(text, { images })`. Attachments are content-addressed
+ * (sha256), validated by magic bytes — clipboard MIME metadata is never
+ * trusted — and carry decoded dimensions for preview and pixel-budget checks.
+ */
+export type PromptAttachmentSource = "clipboard" | "file" | "browser-capture";
+export declare const PROMPT_IMAGE_MIME_TYPES: readonly ["image/png", "image/jpeg", "image/webp", "image/gif"];
+export type PromptImageMimeType = (typeof PROMPT_IMAGE_MIME_TYPES)[number];
+export interface PromptImageAttachment {
+    readonly id: string;
+    readonly kind: "image";
+    readonly source: PromptAttachmentSource;
+    readonly mimeType: PromptImageMimeType;
+    readonly byteLength: number;
+    /** 0 when dimensions cannot be parsed from the container header. */
+    readonly width: number;
+    /** 0 when dimensions cannot be parsed from the container header. */
+    readonly height: number;
+    readonly sha256: string;
+    readonly createdAt: number;
+}
+/** Defaults from the attachment roadmap (§validation). */
+export declare const PROMPT_ATTACHMENT_LIMITS: {
+    readonly maxAttachments: 8;
+    readonly maxImageBytes: number;
+    readonly maxDraftBytes: number;
+    readonly maxPixels: 40000000;
+};
+export type PromptAttachmentValidationCode = "empty" | "unsupported" | "too-large" | "too-many-pixels" | "limit-reached";
+export declare class PromptAttachmentError extends Error {
+    readonly code: PromptAttachmentValidationCode;
+    constructor(code: PromptAttachmentValidationCode, message: string);
+}
+/** Detect the image container from magic bytes. Clipboard metadata is not trusted. */
+export declare function sniffImageMimeType(bytes: Uint8Array): PromptImageMimeType | null;
+export interface PromptAttachmentLimits {
+    maxImageBytes?: number;
+    maxPixels?: number;
+}
+/**
+ * Validate raw image bytes and build the attachment record. Throws
+ * {@link PromptAttachmentError} with a stable code so callers can surface a
+ * precise message instead of silently dropping the paste.
+ */
+export declare function createPromptImageAttachment(bytes: Uint8Array, source: PromptAttachmentSource, limits?: PromptAttachmentLimits): PromptImageAttachment;
+/** Human summary for preview footers: `1280×720 · PNG · 312 KiB`. */
+export declare function describePromptImageAttachment(attachment: PromptImageAttachment): string;
+//# sourceMappingURL=prompt-attachment.d.ts.map

package/dist/core/prompt-attachment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-attachment.d.ts","sourceRoot":"","sources":["../../src/core/prompt-attachment.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,MAAM,sBAAsB,GAAG,WAAW,GAAG,MAAM,GAAG,iBAAiB,CAAC;AAE9E,eAAO,MAAM,uBAAuB,iEAAkE,CAAC;AACvG,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED,2DAA0D;AAC1D,eAAO,MAAM,wBAAwB;;;;;CAK3B,CAAC;AAEX,MAAM,MAAM,8BAA8B,GACvC,OAAO,GACP,aAAa,GACb,WAAW,GACX,iBAAiB,GACjB,eAAe,CAAC;AAEnB,qBAAa,qBAAsB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,IAAI,EAAE,8BAA8B,CAAC;IAE9C,YAAY,IAAI,EAAE,8BAA8B,EAAE,OAAO,EAAE,MAAM,EAIhE;CACD;AAQD,sFAAsF;AACtF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,mBAAmB,GAAG,IAAI,CAsChF;AAoFD,MAAM,WAAW,sBAAsB;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAC1C,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,sBAAsB,EAC9B,MAAM,GAAE,sBAA2B,GACjC,qBAAqB,CAwCvB;AAED,wEAAqE;AACrE,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,qBAAqB,GAAG,MAAM,CAMvF","sourcesContent":["/**\n * First-class prompt image attachments.\n *\n * Pure validation/metadata layer between clipboard/file acquisition and\n * `AgentSession.prompt(text, { images })`. Attachments are content-addressed\n * (sha256), validated by magic bytes — clipboard MIME metadata is never\n * trusted — and carry decoded dimensions for preview and pixel-budget checks.\n */\n\nimport { createHash, randomUUID } from \"node:crypto\";\n\nexport type PromptAttachmentSource = \"clipboard\" | \"file\" | \"browser-capture\";\n\nexport const PROMPT_IMAGE_MIME_TYPES = [\"image/png\", \"image/jpeg\", \"image/webp\", \"image/gif\"] as const;\nexport type PromptImageMimeType = (typeof PROMPT_IMAGE_MIME_TYPES)[number];\n\nexport interface PromptImageAttachment {\n\treadonly id: string;\n\treadonly kind: \"image\";\n\treadonly source: PromptAttachmentSource;\n\treadonly mimeType: PromptImageMimeType;\n\treadonly byteLength: number;\n\t/** 0 when dimensions cannot be parsed from the container header. */\n\treadonly width: number;\n\t/** 0 when dimensions cannot be parsed from the container header. */\n\treadonly height: number;\n\treadonly sha256: string;\n\treadonly createdAt: number;\n}\n\n/** Defaults from the attachment roadmap (§validation). */\nexport const PROMPT_ATTACHMENT_LIMITS = {\n\tmaxAttachments: 8,\n\tmaxImageBytes: 10 * 1024 * 1024,\n\tmaxDraftBytes: 32 * 1024 * 1024,\n\tmaxPixels: 40_000_000,\n} as const;\n\nexport type PromptAttachmentValidationCode =\n\t| \"empty\"\n\t| \"unsupported\"\n\t| \"too-large\"\n\t| \"too-many-pixels\"\n\t| \"limit-reached\";\n\nexport class PromptAttachmentError extends Error {\n\treadonly code: PromptAttachmentValidationCode;\n\n\tconstructor(code: PromptAttachmentValidationCode, message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"PromptAttachmentError\";\n\t\tthis.code = code;\n\t}\n}\n\ninterface ImageHeaderInfo {\n\tmimeType: PromptImageMimeType;\n\twidth: number;\n\theight: number;\n}\n\n/** Detect the image container from magic bytes. Clipboard metadata is not trusted. */\nexport function sniffImageMimeType(bytes: Uint8Array): PromptImageMimeType | null {\n\tif (bytes.length < 12) return null;\n\tif (\n\t\tbytes[0] === 0x89 &&\n\t\tbytes[1] === 0x50 &&\n\t\tbytes[2] === 0x4e &&\n\t\tbytes[3] === 0x47 &&\n\t\tbytes[4] === 0x0d &&\n\t\tbytes[5] === 0x0a &&\n\t\tbytes[6] === 0x1a &&\n\t\tbytes[7] === 0x0a\n\t) {\n\t\treturn \"image/png\";\n\t}\n\tif (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return \"image/jpeg\";\n\tif (\n\t\tbytes[0] === 0x47 &&\n\t\tbytes[1] === 0x49 &&\n\t\tbytes[2] === 0x46 &&\n\t\tbytes[3] === 0x38 &&\n\t\t(bytes[4] === 0x37 || bytes[4] === 0x39) &&\n\t\tbytes[5] === 0x61\n\t) {\n\t\treturn \"image/gif\";\n\t}\n\tif (\n\t\tbytes[0] === 0x52 &&\n\t\tbytes[1] === 0x49 &&\n\t\tbytes[2] === 0x46 &&\n\t\tbytes[3] === 0x46 &&\n\t\tbytes[8] === 0x57 &&\n\t\tbytes[9] === 0x45 &&\n\t\tbytes[10] === 0x42 &&\n\t\tbytes[11] === 0x50\n\t) {\n\t\treturn \"image/webp\";\n\t}\n\treturn null;\n}\n\nfunction readPngDimensions(bytes: Uint8Array): { width: number; height: number } {\n\t// IHDR: width u32BE at 16, height u32BE at 20.\n\tif (bytes.length < 24) return { width: 0, height: 0 };\n\tconst view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);\n\treturn { width: view.getUint32(16), height: view.getUint32(20) };\n}\n\nfunction readGifDimensions(bytes: Uint8Array): { width: number; height: number } {\n\tif (bytes.length < 10) return { width: 0, height: 0 };\n\tconst view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);\n\treturn { width: view.getUint16(6, true), height: view.getUint16(8, true) };\n}\n\nfunction readWebpDimensions(bytes: Uint8Array): { width: number; height: number } {\n\tif (bytes.length < 30) return { width: 0, height: 0 };\n\tconst view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);\n\tconst chunk = String.fromCharCode(bytes[12], bytes[13], bytes[14], bytes[15]);\n\tif (chunk === \"VP8X\") {\n\t\tconst width = 1 + (bytes[24] | (bytes[25] << 8) | (bytes[26] << 16));\n\t\tconst height = 1 + (bytes[27] | (bytes[28] << 8) | (bytes[29] << 16));\n\t\treturn { width, height };\n\t}\n\tif (chunk === \"VP8 \") {\n\t\t// Lossy bitstream: frame tag skips 3 bytes, then 3-byte start code, then dims.\n\t\tconst width = view.getUint16(26, true) & 0x3fff;\n\t\tconst height = view.getUint16(28, true) & 0x3fff;\n\t\treturn { width, height };\n\t}\n\tif (chunk === \"VP8L\") {\n\t\tconst bits = view.getUint32(21, true);\n\t\tconst width = (bits & 0x3fff) + 1;\n\t\tconst height = ((bits >> 14) & 0x3fff) + 1;\n\t\treturn { width, height };\n\t}\n\treturn { width: 0, height: 0 };\n}\n\nfunction readJpegDimensions(bytes: Uint8Array): { width: number; height: number } {\n\t// Walk SOF markers; height/width are u16BE at marker offset +5/+7.\n\tlet index = 2;\n\twhile (index + 9 < bytes.length) {\n\t\tif (bytes[index] !== 0xff) {\n\t\t\tindex += 1;\n\t\t\tcontinue;\n\t\t}\n\t\tconst marker = bytes[index + 1];\n\t\tif (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd9)) {\n\t\t\tindex += 2;\n\t\t\tcontinue;\n\t\t}\n\t\tconst length = (bytes[index + 2] << 8) | bytes[index + 3];\n\t\tif (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {\n\t\t\tconst height = (bytes[index + 5] << 8) | bytes[index + 6];\n\t\t\tconst width = (bytes[index + 7] << 8) | bytes[index + 8];\n\t\t\treturn { width, height };\n\t\t}\n\t\tindex += 2 + length;\n\t}\n\treturn { width: 0, height: 0 };\n}\n\nfunction readImageHeader(bytes: Uint8Array, mimeType: PromptImageMimeType): ImageHeaderInfo {\n\tlet dims = { width: 0, height: 0 };\n\tswitch (mimeType) {\n\t\tcase \"image/png\":\n\t\t\tdims = readPngDimensions(bytes);\n\t\t\tbreak;\n\t\tcase \"image/gif\":\n\t\t\tdims = readGifDimensions(bytes);\n\t\t\tbreak;\n\t\tcase \"image/webp\":\n\t\t\tdims = readWebpDimensions(bytes);\n\t\t\tbreak;\n\t\tcase \"image/jpeg\":\n\t\t\tdims = readJpegDimensions(bytes);\n\t\t\tbreak;\n\t\tdefault:\n\t\t\tbreak;\n\t}\n\treturn { mimeType, ...dims };\n}\n\nexport interface PromptAttachmentLimits {\n\tmaxImageBytes?: number;\n\tmaxPixels?: number;\n}\n\n/**\n * Validate raw image bytes and build the attachment record. Throws\n * {@link PromptAttachmentError} with a stable code so callers can surface a\n * precise message instead of silently dropping the paste.\n */\nexport function createPromptImageAttachment(\n\tbytes: Uint8Array,\n\tsource: PromptAttachmentSource,\n\tlimits: PromptAttachmentLimits = {},\n): PromptImageAttachment {\n\tconst maxImageBytes = limits.maxImageBytes ?? PROMPT_ATTACHMENT_LIMITS.maxImageBytes;\n\tconst maxPixels = limits.maxPixels ?? PROMPT_ATTACHMENT_LIMITS.maxPixels;\n\n\tif (bytes.length === 0) {\n\t\tthrow new PromptAttachmentError(\"empty\", \"Clipboard image is empty.\");\n\t}\n\tif (bytes.length > maxImageBytes) {\n\t\tthrow new PromptAttachmentError(\n\t\t\t\"too-large\",\n\t\t\t`Image is ${(bytes.length / (1024 * 1024)).toFixed(1)} MiB — limit is ${(maxImageBytes / (1024 * 1024)).toFixed(0)} MiB.`,\n\t\t);\n\t}\n\tconst mimeType = sniffImageMimeType(bytes);\n\tif (!mimeType) {\n\t\tthrow new PromptAttachmentError(\n\t\t\t\"unsupported\",\n\t\t\t\"Clipboard content is not a supported image (PNG, JPEG, WebP, GIF).\",\n\t\t);\n\t}\n\tconst header = readImageHeader(bytes, mimeType);\n\tconst pixels = header.width * header.height;\n\tif (pixels > maxPixels) {\n\t\tthrow new PromptAttachmentError(\n\t\t\t\"too-many-pixels\",\n\t\t\t`Image is ${header.width}×${header.height} (${(pixels / 1_000_000).toFixed(0)} MP) — limit is ${(maxPixels / 1_000_000).toFixed(0)} MP.`,\n\t\t);\n\t}\n\tconst sha256 = createHash(\"sha256\").update(bytes).digest(\"hex\");\n\treturn {\n\t\tid: randomUUID(),\n\t\tkind: \"image\",\n\t\tsource,\n\t\tmimeType,\n\t\tbyteLength: bytes.length,\n\t\twidth: header.width,\n\t\theight: header.height,\n\t\tsha256,\n\t\tcreatedAt: Date.now(),\n\t};\n}\n\n/** Human summary for preview footers: `1280×720 · PNG · 312 KiB`. */\nexport function describePromptImageAttachment(attachment: PromptImageAttachment): string {\n\tconst dims = attachment.width > 0 && attachment.height > 0 ? `${attachment.width}×${attachment.height} · ` : \"\";\n\tconst kib = attachment.byteLength / 1024;\n\tconst size = kib >= 1024 ? `${(kib / 1024).toFixed(1)} MiB` : `${Math.round(kib)} KiB`;\n\tconst mime = attachment.mimeType.replace(\"image/\", \"\").toUpperCase();\n\treturn `${dims}${mime} · ${size}`;\n}\n"]}

package/dist/core/prompt-attachment.js

@@ -0,0 +1,186 @@
+/**
+ * First-class prompt image attachments.
+ *
+ * Pure validation/metadata layer between clipboard/file acquisition and
+ * `AgentSession.prompt(text, { images })`. Attachments are content-addressed
+ * (sha256), validated by magic bytes — clipboard MIME metadata is never
+ * trusted — and carry decoded dimensions for preview and pixel-budget checks.
+ */
+import { createHash, randomUUID } from "node:crypto";
+export const PROMPT_IMAGE_MIME_TYPES = ["image/png", "image/jpeg", "image/webp", "image/gif"];
+/** Defaults from the attachment roadmap (§validation). */
+export const PROMPT_ATTACHMENT_LIMITS = {
+    maxAttachments: 8,
+    maxImageBytes: 10 * 1024 * 1024,
+    maxDraftBytes: 32 * 1024 * 1024,
+    maxPixels: 40_000_000,
+};
+export class PromptAttachmentError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "PromptAttachmentError";
+        this.code = code;
+    }
+}
+/** Detect the image container from magic bytes. Clipboard metadata is not trusted. */
+export function sniffImageMimeType(bytes) {
+    if (bytes.length < 12)
+        return null;
+    if (bytes[0] === 0x89 &&
+        bytes[1] === 0x50 &&
+        bytes[2] === 0x4e &&
+        bytes[3] === 0x47 &&
+        bytes[4] === 0x0d &&
+        bytes[5] === 0x0a &&
+        bytes[6] === 0x1a &&
+        bytes[7] === 0x0a) {
+        return "image/png";
+    }
+    if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return "image/jpeg";
+    if (bytes[0] === 0x47 &&
+        bytes[1] === 0x49 &&
+        bytes[2] === 0x46 &&
+        bytes[3] === 0x38 &&
+        (bytes[4] === 0x37 || bytes[4] === 0x39) &&
+        bytes[5] === 0x61) {
+        return "image/gif";
+    }
+    if (bytes[0] === 0x52 &&
+        bytes[1] === 0x49 &&
+        bytes[2] === 0x46 &&
+        bytes[3] === 0x46 &&
+        bytes[8] === 0x57 &&
+        bytes[9] === 0x45 &&
+        bytes[10] === 0x42 &&
+        bytes[11] === 0x50) {
+        return "image/webp";
+    }
+    return null;
+}
+function readPngDimensions(bytes) {
+    // IHDR: width u32BE at 16, height u32BE at 20.
+    if (bytes.length < 24)
+        return { width: 0, height: 0 };
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    return { width: view.getUint32(16), height: view.getUint32(20) };
+}
+function readGifDimensions(bytes) {
+    if (bytes.length < 10)
+        return { width: 0, height: 0 };
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    return { width: view.getUint16(6, true), height: view.getUint16(8, true) };
+}
+function readWebpDimensions(bytes) {
+    if (bytes.length < 30)
+        return { width: 0, height: 0 };
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const chunk = String.fromCharCode(bytes[12], bytes[13], bytes[14], bytes[15]);
+    if (chunk === "VP8X") {
+        const width = 1 + (bytes[24] | (bytes[25] << 8) | (bytes[26] << 16));
+        const height = 1 + (bytes[27] | (bytes[28] << 8) | (bytes[29] << 16));
+        return { width, height };
+    }
+    if (chunk === "VP8 ") {
+        // Lossy bitstream: frame tag skips 3 bytes, then 3-byte start code, then dims.
+        const width = view.getUint16(26, true) & 0x3fff;
+        const height = view.getUint16(28, true) & 0x3fff;
+        return { width, height };
+    }
+    if (chunk === "VP8L") {
+        const bits = view.getUint32(21, true);
+        const width = (bits & 0x3fff) + 1;
+        const height = ((bits >> 14) & 0x3fff) + 1;
+        return { width, height };
+    }
+    return { width: 0, height: 0 };
+}
+function readJpegDimensions(bytes) {
+    // Walk SOF markers; height/width are u16BE at marker offset +5/+7.
+    let index = 2;
+    while (index + 9 < bytes.length) {
+        if (bytes[index] !== 0xff) {
+            index += 1;
+            continue;
+        }
+        const marker = bytes[index + 1];
+        if (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd9)) {
+            index += 2;
+            continue;
+        }
+        const length = (bytes[index + 2] << 8) | bytes[index + 3];
+        if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+            const height = (bytes[index + 5] << 8) | bytes[index + 6];
+            const width = (bytes[index + 7] << 8) | bytes[index + 8];
+            return { width, height };
+        }
+        index += 2 + length;
+    }
+    return { width: 0, height: 0 };
+}
+function readImageHeader(bytes, mimeType) {
+    let dims = { width: 0, height: 0 };
+    switch (mimeType) {
+        case "image/png":
+            dims = readPngDimensions(bytes);
+            break;
+        case "image/gif":
+            dims = readGifDimensions(bytes);
+            break;
+        case "image/webp":
+            dims = readWebpDimensions(bytes);
+            break;
+        case "image/jpeg":
+            dims = readJpegDimensions(bytes);
+            break;
+        default:
+            break;
+    }
+    return { mimeType, ...dims };
+}
+/**
+ * Validate raw image bytes and build the attachment record. Throws
+ * {@link PromptAttachmentError} with a stable code so callers can surface a
+ * precise message instead of silently dropping the paste.
+ */
+export function createPromptImageAttachment(bytes, source, limits = {}) {
+    const maxImageBytes = limits.maxImageBytes ?? PROMPT_ATTACHMENT_LIMITS.maxImageBytes;
+    const maxPixels = limits.maxPixels ?? PROMPT_ATTACHMENT_LIMITS.maxPixels;
+    if (bytes.length === 0) {
+        throw new PromptAttachmentError("empty", "Clipboard image is empty.");
+    }
+    if (bytes.length > maxImageBytes) {
+        throw new PromptAttachmentError("too-large", `Image is ${(bytes.length / (1024 * 1024)).toFixed(1)} MiB — limit is ${(maxImageBytes / (1024 * 1024)).toFixed(0)} MiB.`);
+    }
+    const mimeType = sniffImageMimeType(bytes);
+    if (!mimeType) {
+        throw new PromptAttachmentError("unsupported", "Clipboard content is not a supported image (PNG, JPEG, WebP, GIF).");
+    }
+    const header = readImageHeader(bytes, mimeType);
+    const pixels = header.width * header.height;
+    if (pixels > maxPixels) {
+        throw new PromptAttachmentError("too-many-pixels", `Image is ${header.width}×${header.height} (${(pixels / 1_000_000).toFixed(0)} MP) — limit is ${(maxPixels / 1_000_000).toFixed(0)} MP.`);
+    }
+    const sha256 = createHash("sha256").update(bytes).digest("hex");
+    return {
+        id: randomUUID(),
+        kind: "image",
+        source,
+        mimeType,
+        byteLength: bytes.length,
+        width: header.width,
+        height: header.height,
+        sha256,
+        createdAt: Date.now(),
+    };
+}
+/** Human summary for preview footers: `1280×720 · PNG · 312 KiB`. */
+export function describePromptImageAttachment(attachment) {
+    const dims = attachment.width > 0 && attachment.height > 0 ? `${attachment.width}×${attachment.height} · ` : "";
+    const kib = attachment.byteLength / 1024;
+    const size = kib >= 1024 ? `${(kib / 1024).toFixed(1)} MiB` : `${Math.round(kib)} KiB`;
+    const mime = attachment.mimeType.replace("image/", "").toUpperCase();
+    return `${dims}${mime} · ${size}`;
+}
+//# sourceMappingURL=prompt-attachment.js.map

package/dist/core/prompt-attachment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-attachment.js","sourceRoot":"","sources":["../../src/core/prompt-attachment.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * First-class prompt image attachments.\n *\n * Pure validation/metadata layer between clipboard/file acquisition and\n * `AgentSession.prompt(text, { images })`. Attachments are content-addressed\n * (sha256), validated by magic bytes — clipboard MIME metadata is never\n * trusted — and carry decoded dimensions for preview and pixel-budget checks.\n */\n\nimport { createHash, randomUUID } from \"node:crypto\";\n\nexport type PromptAttachmentSource = \"clipboard\" | \"file\" | \"browser-capture\";\n\nexport const PROMPT_IMAGE_MIME_TYPES = [\"image/png\", \"image/jpeg\", \"image/webp\", \"image/gif\"] as const;\nexport type PromptImageMimeType = (typeof PROMPT_IMAGE_MIME_TYPES)[number];\n\nexport interface PromptImageAttachment {\n\treadonly id: string;\n\treadonly kind: \"image\";\n\treadonly source: PromptAttachmentSource;\n\treadonly mimeType: PromptImageMimeType;\n\treadonly byteLength: number;\n\t/** 0 when dimensions cannot be parsed from the container header. */\n\treadonly width: number;\n\t/** 0 when dimensions cannot be parsed from the container header. */\n\treadonly height: number;\n\treadonly sha256: string;\n\treadonly createdAt: number;\n}\n\n/** Defaults from the attachment roadmap (§validation). */\nexport const PROMPT_ATTACHMENT_LIMITS = {\n\tmaxAttachments: 8,\n\tmaxImageBytes: 10 * 1024 * 1024,\n\tmaxDraftBytes: 32 * 1024 * 1024,\n\tmaxPixels: 40_000_000,\n} as const;\n\nexport type PromptAttachmentValidationCode =\n\t| \"empty\"\n\t| \"unsupported\"\n\t| \"too-large\"\n\t| \"too-many-pixels\"\n\t| \"limit-reached\";\n\nexport class PromptAttachmentError extends Error {\n\treadonly code: PromptAttachmentValidationCode;\n\n\tconstructor(code: PromptAttachmentValidationCode, message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"PromptAttachmentError\";\n\t\tthis.code = code;\n\t}\n}\n\ninterface ImageHeaderInfo {\n\tmimeType: PromptImageMimeType;\n\twidth: number;\n\theight: number;\n}\n\n/** Detect the image container from magic bytes. Clipboard metadata is not trusted. */\nexport function sniffImageMimeType(bytes: Uint8Array): PromptImageMimeType | null {\n\tif (bytes.length < 12) return null;\n\tif (\n\t\tbytes[0] === 0x89 &&\n\t\tbytes[1] === 0x50 &&\n\t\tbytes[2] === 0x4e &&\n\t\tbytes[3] === 0x47 &&\n\t\tbytes[4] === 0x0d &&\n\t\tbytes[5] === 0x0a &&\n\t\tbytes[6] === 0x1a &&\n\t\tbytes[7] === 0x0a\n\t) {\n\t\treturn \"image/png\";\n\t}\n\tif (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return \"image/jpeg\";\n\tif (\n\t\tbytes[0] === 0x47 &&\n\t\tbytes[1] === 0x49 &&\n\t\tbytes[2] === 0x46 &&\n\t\tbytes[3] === 0x38 &&\n\t\t(bytes[4] === 0x37 || bytes[4] === 0x39) &&\n\t\tbytes[5] === 0x61\n\t) {\n\t\treturn \"image/gif\";\n\t}\n\tif (\n\t\tbytes[0] === 0x52 &&\n\t\tbytes[1] === 0x49 &&\n\t\tbytes[2] === 0x46 &&\n\t\tbytes[3] === 0x46 &&\n\t\tbytes[8] === 0x57 &&\n\t\tbytes[9] === 0x45 &&\n\t\tbytes[10] === 0x42 &&\n\t\tbytes[11] === 0x50\n\t) {\n\t\treturn \"image/webp\";\n\t}\n\treturn null;\n}\n\nfunction readPngDimensions(bytes: Uint8Array): { width: number; height: number } {\n\t// IHDR: width u32BE at 16, height u32BE at 20.\n\tif (bytes.length < 24) return { width: 0, height: 0 };\n\tconst view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);\n\treturn { width: view.getUint32(16), height: view.getUint32(20) };\n}\n\nfunction readGifDimensions(bytes: Uint8Array): { width: number; height: number } {\n\tif (bytes.length < 10) return { width: 0, height: 0 };\n\tconst view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);\n\treturn { width: view.getUint16(6, true), height: view.getUint16(8, true) };\n}\n\nfunction readWebpDimensions(bytes: Uint8Array): { width: number; height: number } {\n\tif (bytes.length < 30) return { width: 0, height: 0 };\n\tconst view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);\n\tconst chunk = String.fromCharCode(bytes[12], bytes[13], bytes[14], bytes[15]);\n\tif (chunk === \"VP8X\") {\n\t\tconst width = 1 + (bytes[24] | (bytes[25] << 8) | (bytes[26] << 16));\n\t\tconst height = 1 + (bytes[27] | (bytes[28] << 8) | (bytes[29] << 16));\n\t\treturn { width, height };\n\t}\n\tif (chunk === \"VP8 \") {\n\t\t// Lossy bitstream: frame tag skips 3 bytes, then 3-byte start code, then dims.\n\t\tconst width = view.getUint16(26, true) & 0x3fff;\n\t\tconst height = view.getUint16(28, true) & 0x3fff;\n\t\treturn { width, height };\n\t}\n\tif (chunk === \"VP8L\") {\n\t\tconst bits = view.getUint32(21, true);\n\t\tconst width = (bits & 0x3fff) + 1;\n\t\tconst height = ((bits >> 14) & 0x3fff) + 1;\n\t\treturn { width, height };\n\t}\n\treturn { width: 0, height: 0 };\n}\n\nfunction readJpegDimensions(bytes: Uint8Array): { width: number; height: number } {\n\t// Walk SOF markers; height/width are u16BE at marker offset +5/+7.\n\tlet index = 2;\n\twhile (index + 9 < bytes.length) {\n\t\tif (bytes[index] !== 0xff) {\n\t\t\tindex += 1;\n\t\t\tcontinue;\n\t\t}\n\t\tconst marker = bytes[index + 1];\n\t\tif (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd9)) {\n\t\t\tindex += 2;\n\t\t\tcontinue;\n\t\t}\n\t\tconst length = (bytes[index + 2] << 8) | bytes[index + 3];\n\t\tif (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {\n\t\t\tconst height = (bytes[index + 5] << 8) | bytes[index + 6];\n\t\t\tconst width = (bytes[index + 7] << 8) | bytes[index + 8];\n\t\t\treturn { width, height };\n\t\t}\n\t\tindex += 2 + length;\n\t}\n\treturn { width: 0, height: 0 };\n}\n\nfunction readImageHeader(bytes: Uint8Array, mimeType: PromptImageMimeType): ImageHeaderInfo {\n\tlet dims = { width: 0, height: 0 };\n\tswitch (mimeType) {\n\t\tcase \"image/png\":\n\t\t\tdims = readPngDimensions(bytes);\n\t\t\tbreak;\n\t\tcase \"image/gif\":\n\t\t\tdims = readGifDimensions(bytes);\n\t\t\tbreak;\n\t\tcase \"image/webp\":\n\t\t\tdims = readWebpDimensions(bytes);\n\t\t\tbreak;\n\t\tcase \"image/jpeg\":\n\t\t\tdims = readJpegDimensions(bytes);\n\t\t\tbreak;\n\t\tdefault:\n\t\t\tbreak;\n\t}\n\treturn { mimeType, ...dims };\n}\n\nexport interface PromptAttachmentLimits {\n\tmaxImageBytes?: number;\n\tmaxPixels?: number;\n}\n\n/**\n * Validate raw image bytes and build the attachment record. Throws\n * {@link PromptAttachmentError} with a stable code so callers can surface a\n * precise message instead of silently dropping the paste.\n */\nexport function createPromptImageAttachment(\n\tbytes: Uint8Array,\n\tsource: PromptAttachmentSource,\n\tlimits: PromptAttachmentLimits = {},\n): PromptImageAttachment {\n\tconst maxImageBytes = limits.maxImageBytes ?? PROMPT_ATTACHMENT_LIMITS.maxImageBytes;\n\tconst maxPixels = limits.maxPixels ?? PROMPT_ATTACHMENT_LIMITS.maxPixels;\n\n\tif (bytes.length === 0) {\n\t\tthrow new PromptAttachmentError(\"empty\", \"Clipboard image is empty.\");\n\t}\n\tif (bytes.length > maxImageBytes) {\n\t\tthrow new PromptAttachmentError(\n\t\t\t\"too-large\",\n\t\t\t`Image is ${(bytes.length / (1024 * 1024)).toFixed(1)} MiB — limit is ${(maxImageBytes / (1024 * 1024)).toFixed(0)} MiB.`,\n\t\t);\n\t}\n\tconst mimeType = sniffImageMimeType(bytes);\n\tif (!mimeType) {\n\t\tthrow new PromptAttachmentError(\n\t\t\t\"unsupported\",\n\t\t\t\"Clipboard content is not a supported image (PNG, JPEG, WebP, GIF).\",\n\t\t);\n\t}\n\tconst header = readImageHeader(bytes, mimeType);\n\tconst pixels = header.width * header.height;\n\tif (pixels > maxPixels) {\n\t\tthrow new PromptAttachmentError(\n\t\t\t\"too-many-pixels\",\n\t\t\t`Image is ${header.width}×${header.height} (${(pixels / 1_000_000).toFixed(0)} MP) — limit is ${(maxPixels / 1_000_000).toFixed(0)} MP.`,\n\t\t);\n\t}\n\tconst sha256 = createHash(\"sha256\").update(bytes).digest(\"hex\");\n\treturn {\n\t\tid: randomUUID(),\n\t\tkind: \"image\",\n\t\tsource,\n\t\tmimeType,\n\t\tbyteLength: bytes.length,\n\t\twidth: header.width,\n\t\theight: header.height,\n\t\tsha256,\n\t\tcreatedAt: Date.now(),\n\t};\n}\n\n/** Human summary for preview footers: `1280×720 · PNG · 312 KiB`. */\nexport function describePromptImageAttachment(attachment: PromptImageAttachment): string {\n\tconst dims = attachment.width > 0 && attachment.height > 0 ? `${attachment.width}×${attachment.height} · ` : \"\";\n\tconst kib = attachment.byteLength / 1024;\n\tconst size = kib >= 1024 ? `${(kib / 1024).toFixed(1)} MiB` : `${Math.round(kib)} KiB`;\n\tconst mime = attachment.mimeType.replace(\"image/\", \"\").toUpperCase();\n\treturn `${dims}${mime} · ${size}`;\n}\n"]}

package/dist/core/provider-resilience.d.ts

@@ -39,6 +39,34 @@ export declare function isContentSafetyStopMessage(text: string | undefined): bo
 export declare function isQuotaExhaustionMessage(text: string | undefined): boolean;
 /** Orphan tool results / Kimi-K3 protocol shape errors that heal after sanitize+retry. */
 export declare function isOrphanToolCallIdError(text: string | undefined): boolean;
+/**
+ * Transient upstream availability failures: gateway 5xx passthroughs
+ * ("503 Upstream request failed", "Endpoint is unavailable") and dropped
+ * streams that never carried a finish reason ("Stream ended without
+ * finish_reason"). Transport problems, not transcript-shape problems — they
+ * heal by backoff/retry or switching model, never by transcript sanitization.
+ */
+export declare function isUpstreamUnavailableMessage(text: string | undefined): boolean;
+/** Family key for a model route, or undefined when it has no known alias group. */
+export declare function modelRouteFamily(model: {
+    readonly provider?: string | undefined;
+    readonly id: string;
+    readonly name?: string | undefined;
+}): string | undefined;
+/**
+ * Alternative provider routes serving the same model family as
+ * {@link failed}, in registry order, excluding the failed route itself.
+ * Callers filter by authentication and per-turn failure bookkeeping.
+ */
+export declare function sameModelRouteCandidates<T extends {
+    readonly provider: string;
+    readonly id: string;
+    readonly name?: string | undefined;
+}>(failed: {
+    readonly provider: string;
+    readonly id: string;
+    readonly name?: string | undefined;
+}, available: readonly T[]): T[];
 /**
  * Errors the agent loop may auto-retry (after optional failover / message sanitize).
  * Kept in one place so agent-session and tests share the same contract.

package/dist/core/provider-resilience.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-resilience.d.ts","sourceRoot":"","sources":["../../src/core/provider-resilience.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACpB,CAAC,CAAC;AAEH,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,QAAW,CAAC;AAE/C,8EAA8E;AAC9E,eAAO,MAAM,2BAA2B,QAAuC,CAAC;AAEhF,wEAAwE;AACxE,eAAO,MAAM,kCAAkC,EAAE,SAAS,iBAAiB,EAQjE,CAAC;AAEX,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IACjD,wFAAwF;IACxF,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C,kFAAkF;IAClF,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAC5C,kFAAkF;IAClF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC3D,CAAC,CAAC;AAEH,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CACjD,IAAI,CAAC,0BAA0B,EAAE,yBAAyB,GAAG,0BAA0B,CAAC,CACxF,GAAG;IACH,QAAQ,CAAC,kBAAkB,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAK1D,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAMvG;AAED,0EAA0E;AAC1E,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAM3G;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAK5E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAK1E;AAED,0FAA0F;AAC1F,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAGzE;AAED;;;GAGG;AACH,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAKjF;AAED,wBAAgB,yBAAyB,CACxC,QAAQ,EAAE,0BAA0B,GAAG,SAAS,GAC9C,SAAS,iBAAiB,EAAE,CAI9B;AAED,0EAA0E;AAC1E,wBAAgB,yBAAyB,CAAC,OAAO,EAAE;IAClD,QAAQ,CAAC,wBAAwB,EAAE,OAAO,CAAC;IAC3C,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,OAAO,CAGV;AAED,0EAA0E;AAC1E,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACrD,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC9B,GAAG,OAAO,CAEV;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,0BAA0B,GAAG,SAAS,GAAG;IAC5F,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;IAC1C,QAAQ,CAAC,wBAAwB,EAAE,OAAO,CAAC;IAC3C,QAAQ,CAAC,kBAAkB,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC1D,CAOA;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACpC,UAAU,EAAE,SAAS,iBAAiB,EAAE,EACxC,OAAO,EAAE;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,EACzE,SAAS,EAAE,CAAC,SAAS,EAAE,iBAAiB,KAAK,OAAO,GAClD,iBAAiB,GAAG,SAAS,CAQ/B;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMlF","sourcesContent":["/**\n * Provider resilience — root-level recovery for sticky safety models and\n * sanitize-and-retry protocol failures (orphan tool_call_id, terminated streams).\n *\n * This is not a jailbreak layer. It keeps sessions alive when a provider\n * false-positives or returns a sticky transcript-shape error.\n */\n\nexport type FailoverCandidate = Readonly<{\n\treadonly provider: string;\n\treadonly id: string;\n}>;\n\n/** Models known to emit high false-positive content/safety stops on coding work. */\nexport const STICKY_SAFETY_MODEL_RE = /fable/i;\n\n/** Claude lines that must stay on-model when they refuse. No DeepSeek hop. */\nexport const NO_SAFETY_FAILOVER_MODEL_RE = /(?:claude-)?(?:fable|opus|sonnet)/i;\n\n/** Default failover chain when a sticky safety model refuses a turn. */\nexport const DEFAULT_SAFETY_FAILOVER_CANDIDATES: readonly FailoverCandidate[] = [\n\t{ provider: \"kimi-coding\", id: \"k3\" },\n\t{ provider: \"modelstudio-maas\", id: \"qwen3.8-max-preview\" },\n\t{ provider: \"xai\", id: \"grok-4.5\" },\n\t{ provider: \"deepseek\", id: \"deepseek-v4-pro\" },\n\t{ provider: \"deepseek\", id: \"deepseek-v4-flash\" },\n\t{ provider: \"modelstudio-maas\", id: \"deepseek-v4-pro\" },\n\t{ provider: \"kimi-coding\", id: \"kimi-for-coding\" },\n] as const;\n\nexport type ProviderResilienceSettings = Readonly<{\n\t/** When true (default), refuse selecting sticky safety models (e.g. claude-fable-5). */\n\treadonly blockStickySafetyModels?: boolean;\n\t/** When true (default), auto-switch model on content/safety stop before retry. */\n\treadonly autoFailoverOnSafetyStop?: boolean;\n\t/** Ordered failover targets. Falls back to DEFAULT_SAFETY_FAILOVER_CANDIDATES. */\n\treadonly failoverCandidates?: readonly FailoverCandidate[];\n}>;\n\nexport const DEFAULT_PROVIDER_RESILIENCE: Required<\n\tPick<ProviderResilienceSettings, \"blockStickySafetyModels\" | \"autoFailoverOnSafetyStop\">\n> & {\n\treadonly failoverCandidates: readonly FailoverCandidate[];\n} = {\n\tblockStickySafetyModels: true,\n\tautoFailoverOnSafetyStop: true,\n\tfailoverCandidates: DEFAULT_SAFETY_FAILOVER_CANDIDATES,\n};\n\nexport function isStickySafetyModel(modelId: string | undefined, provider?: string | undefined): boolean {\n\tconst id = (modelId ?? \"\").trim();\n\tif (!id) return false;\n\tif (STICKY_SAFETY_MODEL_RE.test(id)) return true;\n\tconst p = (provider ?? \"\").toLowerCase();\n\treturn p.includes(\"anthropic\") && STICKY_SAFETY_MODEL_RE.test(id);\n}\n\n/** Fable / Opus / Sonnet stay on the requested id after a safety stop. */\nexport function isNoSafetyFailoverModel(modelId: string | undefined, provider?: string | undefined): boolean {\n\tconst id = (modelId ?? \"\").trim();\n\tif (!id) return false;\n\tif (NO_SAFETY_FAILOVER_MODEL_RE.test(id)) return true;\n\tconst p = (provider ?? \"\").toLowerCase();\n\treturn p.includes(\"anthropic\") && NO_SAFETY_FAILOVER_MODEL_RE.test(id);\n}\n\nexport function isContentSafetyStopMessage(text: string | undefined): boolean {\n\tif (!text) return false;\n\treturn /content\\/safety stop|stop_reason\\s*=\\s*(refusal|sensitive)|safety stop|provider\\.refusal|kind=provider_refusal/i.test(\n\t\ttext,\n\t);\n}\n\n/**\n * Billing/quota exhaustion (\"usage limit for this billing cycle\",\n * \"insufficient_quota\", zero balance, ...). Same-model retry is useless until\n * the cycle resets, but the turn can still be saved by failing over to another\n * candidate — so these classify as retryable-with-failover, not auth-fatal.\n */\nexport function isQuotaExhaustionMessage(text: string | undefined): boolean {\n\tif (!text) return false;\n\treturn /usage limit|GoUsageLimitError|FreeUsageLimitError|available balance|insufficient_quota|out of budget|quota exceeded|billing/i.test(\n\t\ttext,\n\t);\n}\n\n/** Orphan tool results / Kimi-K3 protocol shape errors that heal after sanitize+retry. */\nexport function isOrphanToolCallIdError(text: string | undefined): boolean {\n\tif (!text) return false;\n\treturn /tool_call_id\\s+is\\s+not\\s+found|tool_call_id\\s+not\\s+found|unknown\\s+tool_call_id/i.test(text);\n}\n\n/**\n * Errors the agent loop may auto-retry (after optional failover / message sanitize).\n * Kept in one place so agent-session and tests share the same contract.\n */\nexport function isTransientProviderErrorMessage(text: string | undefined): boolean {\n\tif (!text) return false;\n\treturn /overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|network.?error|connection.?error|connection.?refused|connection.?lost|websocket.?closed|websocket.?error|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|ended without|stream ended before message_stop|http2 request did not get a response|timed? out|timeout|\\bterminated\\b|retry delay|content\\/safety stop|stop_reason\\s*=\\s*(refusal|sensitive)|safety stop|tool_call_id\\s+is\\s+not\\s+found|tool_call_id\\s+not\\s+found|invalid_request_error|json error injected into sse stream|injected into sse/i.test(\n\t\ttext,\n\t);\n}\n\nexport function resolveFailoverCandidates(\n\tsettings: ProviderResilienceSettings | undefined,\n): readonly FailoverCandidate[] {\n\tconst custom = settings?.failoverCandidates;\n\tif (custom && custom.length > 0) return custom;\n\treturn DEFAULT_SAFETY_FAILOVER_CANDIDATES;\n}\n\n/** Explicit `--model` / `--provider` pins stay on the requested model. */\nexport function shouldHonorSafetyFailover(options: {\n\treadonly autoFailoverOnSafetyStop: boolean;\n\treadonly modelPinned: boolean;\n\treadonly modelId?: string;\n\treadonly provider?: string;\n}): boolean {\n\tif (!options.autoFailoverOnSafetyStop || options.modelPinned) return false;\n\treturn !isNoSafetyFailoverModel(options.modelId, options.provider);\n}\n\n/** Sticky-model eject still applies unless the user pinned that model. */\nexport function shouldEjectStickySafetyModel(options: {\n\treadonly blockStickySafetyModels: boolean;\n\treadonly modelPinned: boolean;\n}): boolean {\n\treturn options.blockStickySafetyModels && !options.modelPinned;\n}\n\nexport function resolveProviderResilience(settings: ProviderResilienceSettings | undefined): {\n\treadonly blockStickySafetyModels: boolean;\n\treadonly autoFailoverOnSafetyStop: boolean;\n\treadonly failoverCandidates: readonly FailoverCandidate[];\n} {\n\treturn {\n\t\tblockStickySafetyModels: settings?.blockStickySafetyModels ?? DEFAULT_PROVIDER_RESILIENCE.blockStickySafetyModels,\n\t\tautoFailoverOnSafetyStop:\n\t\t\tsettings?.autoFailoverOnSafetyStop ?? DEFAULT_PROVIDER_RESILIENCE.autoFailoverOnSafetyStop,\n\t\tfailoverCandidates: resolveFailoverCandidates(settings),\n\t};\n}\n\n/**\n * Pick first failover candidate that is not the current model and passes `isAllowed`.\n * Pure — caller performs auth checks and setModel.\n */\nexport function pickFailoverCandidate(\n\tcandidates: readonly FailoverCandidate[],\n\tcurrent: { readonly provider?: string; readonly id?: string } | undefined,\n\tisAllowed: (candidate: FailoverCandidate) => boolean,\n): FailoverCandidate | undefined {\n\tfor (const c of candidates) {\n\t\tif (current && c.provider === current.provider && c.id === current.id) continue;\n\t\tif (isStickySafetyModel(c.id, c.provider)) continue;\n\t\tif (!isAllowed(c)) continue;\n\t\treturn c;\n\t}\n\treturn undefined;\n}\n\nexport function stickySafetyBlockMessage(modelId: string, provider: string): string {\n\treturn (\n\t\t`Blocked sticky safety model ${provider}/${modelId} (providerResilience.blockStickySafetyModels). ` +\n\t\t`Use kimi-coding/k3, modelstudio-maas/qwen3.8-max-preview, grok-4.5, or deepseek; ` +\n\t\t`or set providerResilience.blockStickySafetyModels=false.`\n\t);\n}\n"]}
+{"version":3,"file":"provider-resilience.d.ts","sourceRoot":"","sources":["../../src/core/provider-resilience.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACpB,CAAC,CAAC;AAEH,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,QAAW,CAAC;AAE/C,8EAA8E;AAC9E,eAAO,MAAM,2BAA2B,QAAuC,CAAC;AAEhF,wEAAwE;AACxE,eAAO,MAAM,kCAAkC,EAAE,SAAS,iBAAiB,EAQjE,CAAC;AAEX,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IACjD,wFAAwF;IACxF,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C,kFAAkF;IAClF,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAC5C,kFAAkF;IAClF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC3D,CAAC,CAAC;AAEH,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CACjD,IAAI,CAAC,0BAA0B,EAAE,yBAAyB,GAAG,0BAA0B,CAAC,CACxF,GAAG;IACH,QAAQ,CAAC,kBAAkB,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAK1D,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAMvG;AAED,0EAA0E;AAC1E,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAM3G;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAK5E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAK1E;AAED,0FAA0F;AAC1F,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAGzE;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAK9E;AAaD,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC,GAAG,MAAM,GAAG,SAAS,CAMrB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACvC,CAAC,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EAEhG,MAAM,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EAC9F,SAAS,EAAE,SAAS,CAAC,EAAE,GACrB,CAAC,EAAE,CASL;AAED;;;GAGG;AACH,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAKjF;AAED,wBAAgB,yBAAyB,CACxC,QAAQ,EAAE,0BAA0B,GAAG,SAAS,GAC9C,SAAS,iBAAiB,EAAE,CAI9B;AAED,0EAA0E;AAC1E,wBAAgB,yBAAyB,CAAC,OAAO,EAAE;IAClD,QAAQ,CAAC,wBAAwB,EAAE,OAAO,CAAC;IAC3C,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,OAAO,CAGV;AAED,0EAA0E;AAC1E,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACrD,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC9B,GAAG,OAAO,CAEV;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,0BAA0B,GAAG,SAAS,GAAG;IAC5F,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;IAC1C,QAAQ,CAAC,wBAAwB,EAAE,OAAO,CAAC;IAC3C,QAAQ,CAAC,kBAAkB,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC1D,CAOA;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACpC,UAAU,EAAE,SAAS,iBAAiB,EAAE,EACxC,OAAO,EAAE;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,EACzE,SAAS,EAAE,CAAC,SAAS,EAAE,iBAAiB,KAAK,OAAO,GAClD,iBAAiB,GAAG,SAAS,CAQ/B;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMlF","sourcesContent":["/**\n * Provider resilience — root-level recovery for sticky safety models and\n * sanitize-and-retry protocol failures (orphan tool_call_id, terminated streams).\n *\n * This is not a jailbreak layer. It keeps sessions alive when a provider\n * false-positives or returns a sticky transcript-shape error.\n */\n\nexport type FailoverCandidate = Readonly<{\n\treadonly provider: string;\n\treadonly id: string;\n}>;\n\n/** Models known to emit high false-positive content/safety stops on coding work. */\nexport const STICKY_SAFETY_MODEL_RE = /fable/i;\n\n/** Claude lines that must stay on-model when they refuse. No DeepSeek hop. */\nexport const NO_SAFETY_FAILOVER_MODEL_RE = /(?:claude-)?(?:fable|opus|sonnet)/i;\n\n/** Default failover chain when a sticky safety model refuses a turn. */\nexport const DEFAULT_SAFETY_FAILOVER_CANDIDATES: readonly FailoverCandidate[] = [\n\t{ provider: \"kimi-coding\", id: \"k3\" },\n\t{ provider: \"modelstudio-maas\", id: \"qwen3.8-max-preview\" },\n\t{ provider: \"xai\", id: \"grok-4.5\" },\n\t{ provider: \"deepseek\", id: \"deepseek-v4-pro\" },\n\t{ provider: \"deepseek\", id: \"deepseek-v4-flash\" },\n\t{ provider: \"modelstudio-maas\", id: \"deepseek-v4-pro\" },\n\t{ provider: \"kimi-coding\", id: \"kimi-for-coding\" },\n] as const;\n\nexport type ProviderResilienceSettings = Readonly<{\n\t/** When true (default), refuse selecting sticky safety models (e.g. claude-fable-5). */\n\treadonly blockStickySafetyModels?: boolean;\n\t/** When true (default), auto-switch model on content/safety stop before retry. */\n\treadonly autoFailoverOnSafetyStop?: boolean;\n\t/** Ordered failover targets. Falls back to DEFAULT_SAFETY_FAILOVER_CANDIDATES. */\n\treadonly failoverCandidates?: readonly FailoverCandidate[];\n}>;\n\nexport const DEFAULT_PROVIDER_RESILIENCE: Required<\n\tPick<ProviderResilienceSettings, \"blockStickySafetyModels\" | \"autoFailoverOnSafetyStop\">\n> & {\n\treadonly failoverCandidates: readonly FailoverCandidate[];\n} = {\n\tblockStickySafetyModels: true,\n\tautoFailoverOnSafetyStop: true,\n\tfailoverCandidates: DEFAULT_SAFETY_FAILOVER_CANDIDATES,\n};\n\nexport function isStickySafetyModel(modelId: string | undefined, provider?: string | undefined): boolean {\n\tconst id = (modelId ?? \"\").trim();\n\tif (!id) return false;\n\tif (STICKY_SAFETY_MODEL_RE.test(id)) return true;\n\tconst p = (provider ?? \"\").toLowerCase();\n\treturn p.includes(\"anthropic\") && STICKY_SAFETY_MODEL_RE.test(id);\n}\n\n/** Fable / Opus / Sonnet stay on the requested id after a safety stop. */\nexport function isNoSafetyFailoverModel(modelId: string | undefined, provider?: string | undefined): boolean {\n\tconst id = (modelId ?? \"\").trim();\n\tif (!id) return false;\n\tif (NO_SAFETY_FAILOVER_MODEL_RE.test(id)) return true;\n\tconst p = (provider ?? \"\").toLowerCase();\n\treturn p.includes(\"anthropic\") && NO_SAFETY_FAILOVER_MODEL_RE.test(id);\n}\n\nexport function isContentSafetyStopMessage(text: string | undefined): boolean {\n\tif (!text) return false;\n\treturn /content\\/safety stop|stop_reason\\s*=\\s*(refusal|sensitive)|safety stop|provider\\.refusal|kind=provider_refusal/i.test(\n\t\ttext,\n\t);\n}\n\n/**\n * Billing/quota exhaustion (\"usage limit for this billing cycle\",\n * \"insufficient_quota\", zero balance, ...). Same-model retry is useless until\n * the cycle resets, but the turn can still be saved by failing over to another\n * candidate — so these classify as retryable-with-failover, not auth-fatal.\n */\nexport function isQuotaExhaustionMessage(text: string | undefined): boolean {\n\tif (!text) return false;\n\treturn /usage limit|GoUsageLimitError|FreeUsageLimitError|available balance|insufficient_quota|out of budget|quota exceeded|billing/i.test(\n\t\ttext,\n\t);\n}\n\n/** Orphan tool results / Kimi-K3 protocol shape errors that heal after sanitize+retry. */\nexport function isOrphanToolCallIdError(text: string | undefined): boolean {\n\tif (!text) return false;\n\treturn /tool_call_id\\s+is\\s+not\\s+found|tool_call_id\\s+not\\s+found|unknown\\s+tool_call_id/i.test(text);\n}\n\n/**\n * Transient upstream availability failures: gateway 5xx passthroughs\n * (\"503 Upstream request failed\", \"Endpoint is unavailable\") and dropped\n * streams that never carried a finish reason (\"Stream ended without\n * finish_reason\"). Transport problems, not transcript-shape problems — they\n * heal by backoff/retry or switching model, never by transcript sanitization.\n */\nexport function isUpstreamUnavailableMessage(text: string | undefined): boolean {\n\tif (!text) return false;\n\treturn /upstream(?: request)? failed|upstream connect|endpoint (?:is )?unavailable|stream ended without finish_reason|\\b50[0234]\\b/i.test(\n\t\ttext,\n\t);\n}\n\n/**\n * Route families: the same underlying model served by several provider\n * routes. Matched on the model id OR display name so alias routes like\n * `openrouter/stealth/ox-alpha`, `opencode-go/ox-alpha-free`, and\n * `opencode/x-preview-f-free` (\"Ox Alpha Free (Unlimited)\") rotate as one\n * ox-alpha family.\n */\nconst MODEL_ROUTE_FAMILIES: readonly { readonly pattern: RegExp; readonly family: string }[] = [\n\t{ pattern: /(?:^|[-_/])ox[-_ ]?alpha(?:[-_/\\s(]|$)/i, family: \"ox-alpha\" },\n];\n\n/** Family key for a model route, or undefined when it has no known alias group. */\nexport function modelRouteFamily(model: {\n\treadonly provider?: string | undefined;\n\treadonly id: string;\n\treadonly name?: string | undefined;\n}): string | undefined {\n\tfor (const { pattern, family } of MODEL_ROUTE_FAMILIES) {\n\t\tif (pattern.test(model.id)) return family;\n\t\tif (model.name && pattern.test(model.name)) return family;\n\t}\n\treturn undefined;\n}\n\n/**\n * Alternative provider routes serving the same model family as\n * {@link failed}, in registry order, excluding the failed route itself.\n * Callers filter by authentication and per-turn failure bookkeeping.\n */\nexport function sameModelRouteCandidates<\n\tT extends { readonly provider: string; readonly id: string; readonly name?: string | undefined },\n>(\n\tfailed: { readonly provider: string; readonly id: string; readonly name?: string | undefined },\n\tavailable: readonly T[],\n): T[] {\n\tconst family = modelRouteFamily(failed);\n\tif (!family) return [];\n\tconst candidates: T[] = [];\n\tfor (const model of available) {\n\t\tif (model.provider === failed.provider && model.id === failed.id) continue;\n\t\tif (modelRouteFamily(model) === family) candidates.push(model);\n\t}\n\treturn candidates;\n}\n\n/**\n * Errors the agent loop may auto-retry (after optional failover / message sanitize).\n * Kept in one place so agent-session and tests share the same contract.\n */\nexport function isTransientProviderErrorMessage(text: string | undefined): boolean {\n\tif (!text) return false;\n\treturn /overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|network.?error|connection.?error|connection.?refused|connection.?lost|websocket.?closed|websocket.?error|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|ended without|stream ended before message_stop|http2 request did not get a response|timed? out|timeout|\\bterminated\\b|retry delay|content\\/safety stop|stop_reason\\s*=\\s*(refusal|sensitive)|safety stop|tool_call_id\\s+is\\s+not\\s+found|tool_call_id\\s+not\\s+found|invalid_request_error|json error injected into sse stream|injected into sse/i.test(\n\t\ttext,\n\t);\n}\n\nexport function resolveFailoverCandidates(\n\tsettings: ProviderResilienceSettings | undefined,\n): readonly FailoverCandidate[] {\n\tconst custom = settings?.failoverCandidates;\n\tif (custom && custom.length > 0) return custom;\n\treturn DEFAULT_SAFETY_FAILOVER_CANDIDATES;\n}\n\n/** Explicit `--model` / `--provider` pins stay on the requested model. */\nexport function shouldHonorSafetyFailover(options: {\n\treadonly autoFailoverOnSafetyStop: boolean;\n\treadonly modelPinned: boolean;\n\treadonly modelId?: string;\n\treadonly provider?: string;\n}): boolean {\n\tif (!options.autoFailoverOnSafetyStop || options.modelPinned) return false;\n\treturn !isNoSafetyFailoverModel(options.modelId, options.provider);\n}\n\n/** Sticky-model eject still applies unless the user pinned that model. */\nexport function shouldEjectStickySafetyModel(options: {\n\treadonly blockStickySafetyModels: boolean;\n\treadonly modelPinned: boolean;\n}): boolean {\n\treturn options.blockStickySafetyModels && !options.modelPinned;\n}\n\nexport function resolveProviderResilience(settings: ProviderResilienceSettings | undefined): {\n\treadonly blockStickySafetyModels: boolean;\n\treadonly autoFailoverOnSafetyStop: boolean;\n\treadonly failoverCandidates: readonly FailoverCandidate[];\n} {\n\treturn {\n\t\tblockStickySafetyModels: settings?.blockStickySafetyModels ?? DEFAULT_PROVIDER_RESILIENCE.blockStickySafetyModels,\n\t\tautoFailoverOnSafetyStop:\n\t\t\tsettings?.autoFailoverOnSafetyStop ?? DEFAULT_PROVIDER_RESILIENCE.autoFailoverOnSafetyStop,\n\t\tfailoverCandidates: resolveFailoverCandidates(settings),\n\t};\n}\n\n/**\n * Pick first failover candidate that is not the current model and passes `isAllowed`.\n * Pure — caller performs auth checks and setModel.\n */\nexport function pickFailoverCandidate(\n\tcandidates: readonly FailoverCandidate[],\n\tcurrent: { readonly provider?: string; readonly id?: string } | undefined,\n\tisAllowed: (candidate: FailoverCandidate) => boolean,\n): FailoverCandidate | undefined {\n\tfor (const c of candidates) {\n\t\tif (current && c.provider === current.provider && c.id === current.id) continue;\n\t\tif (isStickySafetyModel(c.id, c.provider)) continue;\n\t\tif (!isAllowed(c)) continue;\n\t\treturn c;\n\t}\n\treturn undefined;\n}\n\nexport function stickySafetyBlockMessage(modelId: string, provider: string): string {\n\treturn (\n\t\t`Blocked sticky safety model ${provider}/${modelId} (providerResilience.blockStickySafetyModels). ` +\n\t\t`Use kimi-coding/k3, modelstudio-maas/qwen3.8-max-preview, grok-4.5, or deepseek; ` +\n\t\t`or set providerResilience.blockStickySafetyModels=false.`\n\t);\n}\n"]}

package/dist/core/provider-resilience.js

@@ -65,6 +65,56 @@ export function isOrphanToolCallIdError(text) {
         return false;
     return /tool_call_id\s+is\s+not\s+found|tool_call_id\s+not\s+found|unknown\s+tool_call_id/i.test(text);
 }
+/**
+ * Transient upstream availability failures: gateway 5xx passthroughs
+ * ("503 Upstream request failed", "Endpoint is unavailable") and dropped
+ * streams that never carried a finish reason ("Stream ended without
+ * finish_reason"). Transport problems, not transcript-shape problems — they
+ * heal by backoff/retry or switching model, never by transcript sanitization.
+ */
+export function isUpstreamUnavailableMessage(text) {
+    if (!text)
+        return false;
+    return /upstream(?: request)? failed|upstream connect|endpoint (?:is )?unavailable|stream ended without finish_reason|\b50[0234]\b/i.test(text);
+}
+/**
+ * Route families: the same underlying model served by several provider
+ * routes. Matched on the model id OR display name so alias routes like
+ * `openrouter/stealth/ox-alpha`, `opencode-go/ox-alpha-free`, and
+ * `opencode/x-preview-f-free` ("Ox Alpha Free (Unlimited)") rotate as one
+ * ox-alpha family.
+ */
+const MODEL_ROUTE_FAMILIES = [
+    { pattern: /(?:^|[-_/])ox[-_ ]?alpha(?:[-_/\s(]|$)/i, family: "ox-alpha" },
+];
+/** Family key for a model route, or undefined when it has no known alias group. */
+export function modelRouteFamily(model) {
+    for (const { pattern, family } of MODEL_ROUTE_FAMILIES) {
+        if (pattern.test(model.id))
+            return family;
+        if (model.name && pattern.test(model.name))
+            return family;
+    }
+    return undefined;
+}
+/**
+ * Alternative provider routes serving the same model family as
+ * {@link failed}, in registry order, excluding the failed route itself.
+ * Callers filter by authentication and per-turn failure bookkeeping.
+ */
+export function sameModelRouteCandidates(failed, available) {
+    const family = modelRouteFamily(failed);
+    if (!family)
+        return [];
+    const candidates = [];
+    for (const model of available) {
+        if (model.provider === failed.provider && model.id === failed.id)
+            continue;
+        if (modelRouteFamily(model) === family)
+            candidates.push(model);
+    }
+    return candidates;
+}
 /**
  * Errors the agent loop may auto-retry (after optional failover / message sanitize).
  * Kept in one place so agent-session and tests share the same contract.