@picassohq/cli 0.0.0-stage → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (232) hide show
  1. package/agents/browser_agent.yaml +53 -0
  2. package/agents/code_reviewer.yaml +49 -0
  3. package/agents/codebase_investigator.yaml +70 -0
  4. package/agents/design_auditor.yaml +50 -0
  5. package/agents/devex_auditor.yaml +50 -0
  6. package/agents/doc_writer.yaml +54 -0
  7. package/agents/engineering_architect.yaml +51 -0
  8. package/agents/generalist.yaml +55 -0
  9. package/agents/migration_planner.yaml +51 -0
  10. package/agents/product_reviewer.yaml +48 -0
  11. package/agents/qa_operator.yaml +52 -0
  12. package/agents/release_engineer.yaml +50 -0
  13. package/agents/security_auditor.yaml +62 -0
  14. package/agents/test_writer.yaml +52 -0
  15. package/assets/first-light-lockup.png +0 -0
  16. package/assets/first-light-tagline.png +0 -0
  17. package/assets/house/README.md +26 -0
  18. package/assets/house/auraone-banner.png +0 -0
  19. package/assets/house/auraone-logo.png +0 -0
  20. package/assets/house/kiro-prism-banner.png +0 -0
  21. package/assets/house/kiro-prism-logo.png +0 -0
  22. package/assets/house/picasso-banner.png +0 -0
  23. package/assets/house/picasso-logo.png +0 -0
  24. package/assets/wordmark-app.png +0 -0
  25. package/assets/wordmark-tight.png +0 -0
  26. package/assets/wordmark.png +0 -0
  27. package/design/styles.css +1042 -0
  28. package/dist/build-info.json +37 -0
  29. package/dist/index.js +3062 -0
  30. package/goals/cli-hardening.yaml +40 -0
  31. package/goals/repo-maintenance.yaml +40 -0
  32. package/package.json +49 -4
  33. package/runtime/dsh/picasso-ecosystem.community.amendments.yml +24 -0
  34. package/runtime/dsh/picasso-ecosystem.community.json +185 -0
  35. package/runtime/dsh/picasso-ecosystem.community.patch.yml +40 -0
  36. package/runtime/dsh/picasso-ecosystem.cordis.patch.yml +143 -0
  37. package/runtime/dsh/picasso-isolation.patch.yml +25 -0
  38. package/runtime/dsh/picasso-providers.patch.yml +373 -0
  39. package/runtime/dsh/picasso-runtime.cordis.yml +738 -0
  40. package/runtime/dsh/picasso-sdk.patch.yml +204 -0
  41. package/runtime/engine-manifest.json +215 -0
  42. package/runtime/package.json +6 -0
  43. package/runtime/packages/picasso-cache-probe/cordis.patch.yml +5 -0
  44. package/runtime/packages/picasso-cache-probe/index.js +477 -0
  45. package/runtime/packages/picasso-cache-probe/package.json +38 -0
  46. package/runtime/packages/picasso-commands/cordis.patch.yml +4 -0
  47. package/runtime/packages/picasso-commands/fresh-review.js +573 -0
  48. package/runtime/packages/picasso-commands/index.js +497 -0
  49. package/runtime/packages/picasso-commands/package.json +28 -0
  50. package/runtime/packages/picasso-instructions/conflicts.js +115 -0
  51. package/runtime/packages/picasso-instructions/formats.js +145 -0
  52. package/runtime/packages/picasso-instructions/frontmatter.js +175 -0
  53. package/runtime/packages/picasso-instructions/glob.js +114 -0
  54. package/runtime/packages/picasso-instructions/globals.js +90 -0
  55. package/runtime/packages/picasso-instructions/imports.js +123 -0
  56. package/runtime/packages/picasso-instructions/index.js +326 -0
  57. package/runtime/packages/picasso-instructions/modes.js +64 -0
  58. package/runtime/packages/picasso-instructions/package.json +30 -0
  59. package/runtime/packages/picasso-instructions/parse.js +134 -0
  60. package/runtime/packages/picasso-instructions/report.js +161 -0
  61. package/runtime/packages/picasso-instructions/resolve.js +939 -0
  62. package/runtime/packages/picasso-instructions/scan.js +181 -0
  63. package/runtime/packages/picasso-instructions/settings.js +150 -0
  64. package/runtime/packages/picasso-instructions/skills.js +345 -0
  65. package/runtime/packages/picasso-lean-context/cordis.patch.yml +13 -0
  66. package/runtime/packages/picasso-lean-context/index.js +6280 -0
  67. package/runtime/packages/picasso-lean-context/package.json +26 -0
  68. package/runtime/packages/picasso-lean-context/read-image-recovery.js +306 -0
  69. package/runtime/packages/picasso-lean-context/timeline.js +418 -0
  70. package/runtime/packages/picasso-librarian/classify.js +146 -0
  71. package/runtime/packages/picasso-librarian/cordis.patch.yml +10 -0
  72. package/runtime/packages/picasso-librarian/index.js +878 -0
  73. package/runtime/packages/picasso-librarian/notes.js +159 -0
  74. package/runtime/packages/picasso-librarian/package.json +34 -0
  75. package/runtime/packages/picasso-librarian/state.js +478 -0
  76. package/runtime/packages/picasso-memory/index.js +1184 -0
  77. package/runtime/packages/picasso-memory/package.json +21 -0
  78. package/runtime/packages/picasso-model-router/connections.js +912 -0
  79. package/runtime/packages/picasso-model-router/cordis.patch.yml +17 -0
  80. package/runtime/packages/picasso-model-router/index.js +1083 -0
  81. package/runtime/packages/picasso-model-router/package.json +30 -0
  82. package/runtime/packages/picasso-options/cordis.patch.yml +4 -0
  83. package/runtime/packages/picasso-options/index.js +263 -0
  84. package/runtime/packages/picasso-options/package.json +28 -0
  85. package/runtime/packages/picasso-progress-reports/cordis.patch.yml +10 -0
  86. package/runtime/packages/picasso-progress-reports/index.js +267 -0
  87. package/runtime/packages/picasso-progress-reports/package.json +30 -0
  88. package/runtime/packages/picasso-progress-reports/report.js +235 -0
  89. package/runtime/packages/picasso-sdk-server/aside.js +142 -0
  90. package/runtime/packages/picasso-sdk-server/connections.js +38 -0
  91. package/runtime/packages/picasso-sdk-server/context-timeline.js +27 -0
  92. package/runtime/packages/picasso-sdk-server/egress-gate.js +520 -0
  93. package/runtime/packages/picasso-sdk-server/failure-policy.js +246 -0
  94. package/runtime/packages/picasso-sdk-server/file-input.js +169 -0
  95. package/runtime/packages/picasso-sdk-server/goal.js +131 -0
  96. package/runtime/packages/picasso-sdk-server/ignore-file.js +458 -0
  97. package/runtime/packages/picasso-sdk-server/ignore-plugin.js +12 -0
  98. package/runtime/packages/picasso-sdk-server/ignore-sandbox.js +122 -0
  99. package/runtime/packages/picasso-sdk-server/ignore-snapshot.js +131 -0
  100. package/runtime/packages/picasso-sdk-server/image-input.js +44 -0
  101. package/runtime/packages/picasso-sdk-server/index.js +891 -0
  102. package/runtime/packages/picasso-sdk-server/instructions.js +34 -0
  103. package/runtime/packages/picasso-sdk-server/jobs.js +113 -0
  104. package/runtime/packages/picasso-sdk-server/mcp-gate.js +51 -0
  105. package/runtime/packages/picasso-sdk-server/model-selection.js +162 -0
  106. package/runtime/packages/picasso-sdk-server/package.json +50 -0
  107. package/runtime/packages/picasso-sdk-server/picasso-records.js +50 -0
  108. package/runtime/packages/picasso-sdk-server/provider-reload.js +84 -0
  109. package/runtime/packages/picasso-sdk-server/queue.js +322 -0
  110. package/runtime/packages/picasso-sdk-server/requester.js +43 -0
  111. package/runtime/packages/picasso-sdk-server/rewind.js +108 -0
  112. package/runtime/packages/picasso-sdk-server/schedule.js +187 -0
  113. package/runtime/packages/picasso-sdk-server/session-grants.js +35 -0
  114. package/runtime/packages/picasso-sdk-server/session-state.js +118 -0
  115. package/runtime/packages/picasso-sdk-server/shell-paths.js +869 -0
  116. package/runtime/packages/picasso-sdk-server/stream-deltas.js +211 -0
  117. package/runtime/packages/picasso-sdk-server/team-tasks.js +451 -0
  118. package/runtime/packages/picasso-sdk-server/tool-output.js +128 -0
  119. package/runtime/packages/picasso-sdk-server/tools-list.js +51 -0
  120. package/runtime/packages/picasso-sdk-server/wave2-hooks.js +612 -0
  121. package/runtime/packages/picasso-sdk-server/workspace-archive.js +170 -0
  122. package/runtime/packages/picasso-sdk-server/workspace-restore.js +180 -0
  123. package/runtime/packages/picasso-web-search/backends.js +412 -0
  124. package/runtime/packages/picasso-web-search/config.js +121 -0
  125. package/runtime/packages/picasso-web-search/cordis.patch.yml +7 -0
  126. package/runtime/packages/picasso-web-search/failure.js +116 -0
  127. package/runtime/packages/picasso-web-search/format.js +42 -0
  128. package/runtime/packages/picasso-web-search/index.js +71 -0
  129. package/runtime/packages/picasso-web-search/package.json +38 -0
  130. package/runtime/packages/picasso-web-search/router.js +156 -0
  131. package/runtime/packages/picasso-x-reader/circle.js +324 -0
  132. package/runtime/packages/picasso-x-reader/command.js +169 -0
  133. package/runtime/packages/picasso-x-reader/cordis.patch.yml +8 -0
  134. package/runtime/packages/picasso-x-reader/index.js +170 -0
  135. package/runtime/packages/picasso-x-reader/package.json +39 -0
  136. package/runtime/packages/picasso-x-reader/read.js +370 -0
  137. package/runtime/packages/picasso-x-reader/rewrite.js +38 -0
  138. package/runtime/packages/picasso-x-reader/settings.js +131 -0
  139. package/runtime/packages/picasso-x-reader/urls.js +154 -0
  140. package/runtime/packages/picasso-x-reader/xmd.js +512 -0
  141. package/runtime/plugins/picasso-auth-bridge/index.js +380 -0
  142. package/runtime/plugins/picasso-auth-bridge/package.json +28 -0
  143. package/runtime/plugins/picasso-auto-approve/index.js +1003 -0
  144. package/runtime/plugins/picasso-auto-approve/package.json +28 -0
  145. package/runtime/plugins/picasso-browser/index.js +424 -0
  146. package/runtime/plugins/picasso-browser/package.json +28 -0
  147. package/runtime/plugins/picasso-checkpoints/evidence.js +210 -0
  148. package/runtime/plugins/picasso-checkpoints/index.js +885 -0
  149. package/runtime/plugins/picasso-checkpoints/package.json +29 -0
  150. package/runtime/plugins/picasso-commands/fresh-review.js +573 -0
  151. package/runtime/plugins/picasso-commands/index.js +497 -0
  152. package/runtime/plugins/picasso-commands/package.json +28 -0
  153. package/runtime/plugins/picasso-instructions/conflicts.js +115 -0
  154. package/runtime/plugins/picasso-instructions/formats.js +145 -0
  155. package/runtime/plugins/picasso-instructions/frontmatter.js +175 -0
  156. package/runtime/plugins/picasso-instructions/glob.js +114 -0
  157. package/runtime/plugins/picasso-instructions/globals.js +90 -0
  158. package/runtime/plugins/picasso-instructions/imports.js +123 -0
  159. package/runtime/plugins/picasso-instructions/index.js +326 -0
  160. package/runtime/plugins/picasso-instructions/modes.js +64 -0
  161. package/runtime/plugins/picasso-instructions/package.json +30 -0
  162. package/runtime/plugins/picasso-instructions/parse.js +134 -0
  163. package/runtime/plugins/picasso-instructions/report.js +161 -0
  164. package/runtime/plugins/picasso-instructions/resolve.js +939 -0
  165. package/runtime/plugins/picasso-instructions/scan.js +181 -0
  166. package/runtime/plugins/picasso-instructions/settings.js +150 -0
  167. package/runtime/plugins/picasso-instructions/skills.js +345 -0
  168. package/runtime/plugins/picasso-lean-context/index.js +6280 -0
  169. package/runtime/plugins/picasso-lean-context/package.json +26 -0
  170. package/runtime/plugins/picasso-lean-context/read-image-recovery.js +306 -0
  171. package/runtime/plugins/picasso-lean-context/timeline.js +418 -0
  172. package/runtime/plugins/picasso-librarian/classify.js +146 -0
  173. package/runtime/plugins/picasso-librarian/index.js +878 -0
  174. package/runtime/plugins/picasso-librarian/notes.js +159 -0
  175. package/runtime/plugins/picasso-librarian/package.json +34 -0
  176. package/runtime/plugins/picasso-librarian/state.js +478 -0
  177. package/runtime/plugins/picasso-lifecycle-hooks/index.js +186 -0
  178. package/runtime/plugins/picasso-lifecycle-hooks/package.json +25 -0
  179. package/runtime/plugins/picasso-mail/inbox.js +207 -0
  180. package/runtime/plugins/picasso-mail/index.js +293 -0
  181. package/runtime/plugins/picasso-mail/package.json +22 -0
  182. package/runtime/plugins/picasso-memory/index.js +1184 -0
  183. package/runtime/plugins/picasso-memory/package.json +21 -0
  184. package/runtime/plugins/picasso-model-router/connections.js +912 -0
  185. package/runtime/plugins/picasso-model-router/index.js +1083 -0
  186. package/runtime/plugins/picasso-model-router/package.json +30 -0
  187. package/runtime/plugins/picasso-options/index.js +263 -0
  188. package/runtime/plugins/picasso-options/package.json +28 -0
  189. package/runtime/plugins/picasso-progress-reports/index.js +267 -0
  190. package/runtime/plugins/picasso-progress-reports/package.json +30 -0
  191. package/runtime/plugins/picasso-progress-reports/report.js +235 -0
  192. package/runtime/plugins/picasso-provider-models/index.js +436 -0
  193. package/runtime/plugins/picasso-provider-models/package.json +28 -0
  194. package/runtime/plugins/picasso-repo-index/index.js +1850 -0
  195. package/runtime/plugins/picasso-repo-index/package.json +28 -0
  196. package/runtime/plugins/picasso-schedule-pause/index.js +344 -0
  197. package/runtime/plugins/picasso-schedule-pause/package.json +28 -0
  198. package/runtime/plugins/picasso-session-lifecycle/index.js +796 -0
  199. package/runtime/plugins/picasso-session-lifecycle/package.json +28 -0
  200. package/runtime/plugins/picasso-trackers/index.js +895 -0
  201. package/runtime/plugins/picasso-trackers/package.json +28 -0
  202. package/runtime/plugins/picasso-web-search/backends.js +412 -0
  203. package/runtime/plugins/picasso-web-search/config.js +121 -0
  204. package/runtime/plugins/picasso-web-search/failure.js +116 -0
  205. package/runtime/plugins/picasso-web-search/format.js +42 -0
  206. package/runtime/plugins/picasso-web-search/index.js +71 -0
  207. package/runtime/plugins/picasso-web-search/package.json +38 -0
  208. package/runtime/plugins/picasso-web-search/router.js +156 -0
  209. package/runtime/plugins/picasso-x-reader/circle.js +324 -0
  210. package/runtime/plugins/picasso-x-reader/command.js +169 -0
  211. package/runtime/plugins/picasso-x-reader/index.js +170 -0
  212. package/runtime/plugins/picasso-x-reader/package.json +39 -0
  213. package/runtime/plugins/picasso-x-reader/read.js +370 -0
  214. package/runtime/plugins/picasso-x-reader/rewrite.js +38 -0
  215. package/runtime/plugins/picasso-x-reader/settings.js +131 -0
  216. package/runtime/plugins/picasso-x-reader/urls.js +154 -0
  217. package/runtime/plugins/picasso-x-reader/xmd.js +512 -0
  218. package/runtime/relay/attachment-text.mjs +737 -0
  219. package/runtime/relay/companion/companion.css +126 -0
  220. package/runtime/relay/companion/companion.js +648 -0
  221. package/runtime/relay/companion/icon.svg +5 -0
  222. package/runtime/relay/companion/index.html +25 -0
  223. package/runtime/relay/companion/manifest.json +13 -0
  224. package/runtime/relay/companion/sw.js +41 -0
  225. package/runtime/relay/main.mjs +38580 -0
  226. package/runtime/relay/model-listing.mjs +614 -0
  227. package/runtime/relay/versions-routes.mjs +1400 -0
  228. package/runtime/verify-plugins.mjs +205 -0
  229. package/runtime-lock/package-lock.json +10779 -0
  230. package/runtime-lock/package.json +7 -0
  231. package/scripts/install-runtime.mjs +400 -0
  232. package/README.md +0 -3
@@ -0,0 +1,26 @@
1
+ {
2
+ "name": "@picasso/lean-context",
3
+ "version": "0.1.0",
4
+ "private": true,
5
+ "type": "module",
6
+ "description": "Picasso Lean-Context Cordis plugin: on-demand tool gateway (tool_search/tool_call/<server>_call), Tier-1 system-prompt & runtime-context parity normalizer, 8 KB instruction cap, and 2 KB skill catalog budget.",
7
+ "main": "./index.js",
8
+ "exports": {
9
+ ".": "./index.js",
10
+ "./timeline": {
11
+ "types": "./timeline.d.ts",
12
+ "default": "./timeline.js"
13
+ }
14
+ },
15
+ "scripts": {
16
+ "test": "node --import ../../test/setup/hermetic-preload.mjs --test test/*.test.js"
17
+ },
18
+ "keywords": [
19
+ "picasso",
20
+ "dsh",
21
+ "cordis",
22
+ "lean-context",
23
+ "tool-gateway",
24
+ "prompt-cache"
25
+ ]
26
+ }
@@ -0,0 +1,306 @@
1
+ // read_image recovery for misnamed and non-wire image formats (both surfaces).
2
+ //
3
+ // The engine's `read_image` (`@deepseek-ai/dsh-tool-fs`) trusts the file extension: a `.jpg` path is saved as
4
+ // image/jpeg, and the attachment store's decode then refuses bytes that are really PNG (IMAGE_TYPE_MISMATCH) or HEIC
5
+ // (INVALID_IMAGE). A `.heic`/`.tiff` path is refused before any read (IMAGE_UNSUPPORTED_FORMAT). Photos and Messages
6
+ // exports hit this constantly.
7
+ //
8
+ // The engine forbids argument rewriting in `tools/pre-execute`, so this is a `tools/execute` around-dispatch wrapper.
9
+ // The engine body always runs first; a successful read is returned untouched (no extra I/O on the normal path). Only
10
+ // when it fails with one of the format codes below does the wrapper:
11
+ // 1. re-check the calling route's image input (the engine's extension refusal runs before that check);
12
+ // 2. sniff the real format from the file's magic bytes;
13
+ // 3. a PNG/JPEG/WebP/GIF the deployment accepts is saved with its real media type;
14
+ // 4. HEIC/HEIF/AVIF/TIFF/BMP/PSD/JPEG 2000 (or an accepted-format miss) is converted with macOS `sips` into a
15
+ // private temp dir, saved as JPEG (PNG when JPEG is not accepted), and the temp dir is removed;
16
+ // 5. otherwise a one-line error names what the file really is and what to do.
17
+ // The returned `{ isError: false, value }` is normalized by the engine pipeline against the engine's own output schema
18
+ // and renderer, so the model sees the stock envelope and image block. Nothing here touches the tool list or prompt
19
+ // (Tier 1 unchanged), and `tools/execute` runs for direct, `tool_call` and `run_code` dispatches alike.
20
+ //
21
+ // Never fakes content (C1): the image saved is always the file's own bytes or `sips`' conversion of them.
22
+
23
+ import { execFile } from "node:child_process";
24
+ import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
25
+ import { tmpdir } from "node:os";
26
+ import { basename, extname, join } from "node:path";
27
+
28
+ export const READ_IMAGE_TOOL = "read_image";
29
+
30
+ /** Engine failure codes that may mean "the bytes are not what the name says". */
31
+ export const RECOVERABLE_CODES = Object.freeze(["IMAGE_TYPE_MISMATCH", "INVALID_IMAGE", "IMAGE_UNSUPPORTED_FORMAT", "UNSUPPORTED_IMAGE_TYPE"]);
32
+ const RECOVERABLE = new Set(RECOVERABLE_CODES);
33
+
34
+ /** The engine's extension table (`IMAGE_EXTENSIONS` in dsh-tool-fs read-image). */
35
+ const ENGINE_EXTENSIONS = Object.freeze({ ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif" });
36
+
37
+ /** Largest source file read for a `sips` conversion; the converted result still passes the store's own limits. */
38
+ export const CONVERT_SOURCE_MAX_BYTES = 100 * 1024 * 1024;
39
+ const HEADER_BYTES = 64;
40
+ const SIPS_TIMEOUT_MS = 60_000;
41
+ const DEFAULT_SIPS = "/usr/bin/sips";
42
+
43
+ const ascii = (data, offset, length) => {
44
+ if (data.byteLength < offset + length) return "";
45
+ let out = "";
46
+ for (let i = offset; i < offset + length; i += 1) out += String.fromCharCode(data[i]);
47
+ return out;
48
+ };
49
+ const startsWith = (data, bytes, offset = 0) => data.byteLength >= offset + bytes.length && bytes.every((b, i) => data[offset + i] === b);
50
+
51
+ const HEIC_BRANDS = new Set(["heic", "heix", "hevc", "hevx", "heim", "heis", "hevm", "hevs"]);
52
+ const HEIF_BRANDS = new Set(["mif1", "msf1", "mif2"]);
53
+ const AVIF_BRANDS = new Set(["avif", "avis"]);
54
+ const VIDEO_BRANDS = new Set(["isom", "iso2", "mp41", "mp42", "qt ", "M4V ", "3gp4", "3gp5", "dash", "avc1"]);
55
+
56
+ /**
57
+ * The real format of a file from its first bytes.
58
+ * @param {Uint8Array} data - at least the first 32 bytes when available.
59
+ * @returns {{ label: string, mediaType?: string, convertible?: boolean, image: boolean } | undefined}
60
+ * `mediaType` is set for the four wire formats; `convertible` for formats `sips` can turn into JPEG/PNG.
61
+ */
62
+ export function sniffImageFormat(data) {
63
+ if (!(data instanceof Uint8Array) || data.byteLength < 2) return undefined;
64
+ if (startsWith(data, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return { label: "PNG", mediaType: "image/png", image: true, convertible: true };
65
+ if (startsWith(data, [0xff, 0xd8, 0xff])) return { label: "JPEG", mediaType: "image/jpeg", image: true, convertible: true };
66
+ if (ascii(data, 0, 6) === "GIF87a" || ascii(data, 0, 6) === "GIF89a") return { label: "GIF", mediaType: "image/gif", image: true, convertible: true };
67
+ if (ascii(data, 0, 4) === "RIFF" && ascii(data, 8, 4) === "WEBP") return { label: "WebP", mediaType: "image/webp", image: true, convertible: true };
68
+ if (ascii(data, 4, 4) === "ftyp") {
69
+ const major = ascii(data, 8, 4);
70
+ // Compatible brands follow the minor version (box size from the first 4 bytes, capped to what was read).
71
+ const boxSize = Math.min(((data[0] << 24) | (data[1] << 16) | (data[2] << 8) | data[3]) >>> 0, data.byteLength);
72
+ const brands = [major];
73
+ for (let at = 16; at + 4 <= boxSize; at += 4) brands.push(ascii(data, at, 4));
74
+ if (brands.some((brand) => AVIF_BRANDS.has(brand)) && !HEIC_BRANDS.has(major)) return { label: "AVIF", image: true, convertible: true };
75
+ if (brands.some((brand) => HEIC_BRANDS.has(brand))) return { label: "HEIC", image: true, convertible: true };
76
+ if (brands.some((brand) => HEIF_BRANDS.has(brand))) return { label: "HEIF", image: true, convertible: true };
77
+ if (VIDEO_BRANDS.has(major)) return { label: "MP4/QuickTime video", image: false };
78
+ }
79
+ if (startsWith(data, [0x49, 0x49, 0x2a, 0x00]) || startsWith(data, [0x4d, 0x4d, 0x00, 0x2a])) return { label: "TIFF", image: true, convertible: true };
80
+ if (ascii(data, 0, 4) === "8BPS") return { label: "Photoshop (PSD)", image: true, convertible: true };
81
+ if (startsWith(data, [0x00, 0x00, 0x00, 0x0c, 0x6a, 0x50, 0x20, 0x20]) || startsWith(data, [0xff, 0x4f, 0xff, 0x51])) return { label: "JPEG 2000", image: true, convertible: true };
82
+ if (ascii(data, 0, 4) === "icns") return { label: "ICNS", image: true, convertible: true };
83
+ if (ascii(data, 0, 2) === "BM" && data.byteLength >= 14) return { label: "BMP", image: true, convertible: true };
84
+ if (ascii(data, 0, 5) === "%PDF-") return { label: "PDF document", image: false };
85
+ if (startsWith(data, [0x50, 0x4b, 0x03, 0x04])) return { label: "ZIP archive", image: false };
86
+ const head = ascii(data, 0, Math.min(data.byteLength, HEADER_BYTES)).trimStart().toLowerCase();
87
+ if (head.startsWith("<svg") || (head.startsWith("<?xml") && head.includes("<svg"))) return { label: "SVG (vector text)", image: false };
88
+ return undefined;
89
+ }
90
+
91
+ function serviceOf(ctx, name) {
92
+ try {
93
+ const viaGet = ctx?.get?.(name);
94
+ if (viaGet !== undefined) return viaGet;
95
+ } catch {
96
+ // fall through to the direct property
97
+ }
98
+ try {
99
+ return ctx?.[name];
100
+ } catch {
101
+ return undefined;
102
+ }
103
+ }
104
+
105
+ /** A failed tool result in the engine's own shape (`toolErrorResult`). */
106
+ function failure(message, code, name = "ImageInputError") {
107
+ return { content: [{ type: "text", text: `Error: ${message}` }], isError: true, error: { message, info: { name, code } } };
108
+ }
109
+
110
+ /** `sips` conversion of `data` into `format` (`jpeg`|`png`); the temp dir is always removed. */
111
+ async function convertWithSips(data, format, { sipsPath, signal, tmpRoot }) {
112
+ const dir = mkdtempSync(join(tmpRoot ?? tmpdir(), "picasso-read-image-"));
113
+ try {
114
+ const source = join(dir, "source");
115
+ const out = join(dir, `converted.${format === "png" ? "png" : "jpg"}`);
116
+ writeFileSync(source, data, { mode: 0o600 });
117
+ await new Promise((resolveRun, rejectRun) => {
118
+ execFile(sipsPath, ["-s", "format", format, source, "--out", out], { timeout: SIPS_TIMEOUT_MS, signal, windowsHide: true }, (error, _stdout, stderr) => {
119
+ if (error) {
120
+ const detail = String(stderr ?? "").split("\n").map((line) => line.trim()).find((line) => line.length > 0) ?? error.message;
121
+ rejectRun(new Error(detail));
122
+ return;
123
+ }
124
+ resolveRun();
125
+ });
126
+ });
127
+ if (!existsSync(out)) throw new Error("sips produced no output file");
128
+ return new Uint8Array(readFileSync(out));
129
+ } finally {
130
+ rmSync(dir, { recursive: true, force: true });
131
+ }
132
+ }
133
+
134
+ /** The engine's model-facing remedy for a store refusal, keyed by code; other codes keep the store's message. */
135
+ function saveRefusal(error, limits) {
136
+ switch (error?.code) {
137
+ case "IMAGE_DIMENSION_TOO_LARGE":
138
+ return `at least one image side exceeds the ${limits?.maxImageDimension}px limit; downscale the image and read the smaller copy`;
139
+ case "IMAGE_TOO_MANY_PIXELS":
140
+ return `the image exceeds the ${limits?.maxImagePixels}-pixel decoded-size limit; downscale the image and read the smaller copy`;
141
+ case "IMAGE_TOO_LARGE":
142
+ case "IMAGES_TOO_LARGE":
143
+ return "the image cannot be stored within the deployment's byte limits; downscale the image and read the smaller copy";
144
+ default:
145
+ return String(error?.message ?? error);
146
+ }
147
+ }
148
+
149
+ /**
150
+ * The calling route's image input, resolved the way the engine's `assertImageCapableRoute` does.
151
+ * @returns {Promise<{ ok: true } | { ok: false, model?: string }>} `ok: false` without `model` = unresolvable.
152
+ */
153
+ async function routeAcceptsImages(ctx, exec) {
154
+ let routed;
155
+ try {
156
+ routed = exec?.agent?.session?.requestHeader?.()?.config;
157
+ } catch {
158
+ routed = undefined;
159
+ }
160
+ const provider = routed?.provider ?? exec?.agent?.options?.provider;
161
+ const model = routed?.model ?? exec?.agent?.options?.model;
162
+ const llm = serviceOf(ctx, "llm");
163
+ if (provider === undefined || model === undefined || typeof llm?.resolveModelInfo !== "function") return { ok: false };
164
+ const info = await llm.resolveModelInfo(provider, model, exec?.signal);
165
+ return Array.isArray(info?.inputModalities) && info.inputModalities.includes("image") ? { ok: true } : { ok: false, model };
166
+ }
167
+
168
+ /**
169
+ * Re-read one failed `read_image` call by its real format.
170
+ * @returns {Promise<object | undefined>} a tool result, or `undefined` to keep the engine's own failure.
171
+ */
172
+ export async function recoverReadImage(ctx, exec, original, options = {}) {
173
+ const filePath = exec?.arguments?.file_path;
174
+ if (typeof filePath !== "string" || filePath.trim().length === 0) return undefined;
175
+ const fs = serviceOf(ctx, "fs");
176
+ const attachments = serviceOf(ctx, "attachments");
177
+ if (typeof fs?.resolve !== "function" || typeof fs?.readBytes !== "function" || typeof attachments?.saveImage !== "function") return undefined;
178
+ const limits = attachments.imageLimits ?? {};
179
+ const accepted = Array.isArray(limits.mediaTypes) ? limits.mediaTypes : ["image/png", "image/jpeg", "image/webp", "image/gif"];
180
+
181
+ const route = await routeAcceptsImages(ctx, exec);
182
+ if (!route.ok) {
183
+ if (route.model === undefined) return undefined;
184
+ return failure(
185
+ `cannot read "${filePath}" as an image: model "${route.model}" does not declare image input; switch to an image-capable model to read images`,
186
+ "IMAGE_UNSUPPORTED_MODEL",
187
+ );
188
+ }
189
+
190
+ let cwd;
191
+ const workingDirectory = serviceOf(ctx, "workingDirectory");
192
+ if (exec?.agent !== undefined && typeof workingDirectory?.ensure === "function") {
193
+ cwd = await workingDirectory.ensure(exec.agent, exec.signal);
194
+ }
195
+ const target = await fs.resolve(filePath, { ...(cwd === undefined ? {} : { cwd }), signal: exec?.signal });
196
+ const info = await fs.stat(target, exec?.signal);
197
+ if (info === undefined || info.type !== "file") return undefined;
198
+ const displayPath = target.displayPath ?? filePath;
199
+ const extension = extname(displayPath).toLowerCase();
200
+ const named = extension === "" ? "no extension" : `its ${extension} name`;
201
+
202
+ const header = typeof fs.readByteRange === "function"
203
+ ? await fs.readByteRange(target, { offset: 0, length: HEADER_BYTES }, exec?.signal)
204
+ : await fs.readBytes(target, exec?.signal, CONVERT_SOURCE_MAX_BYTES);
205
+ const real = sniffImageFormat(header);
206
+ if (real === undefined) return undefined;
207
+ const engineType = ENGINE_EXTENSIONS[extension] ?? (extension === "" ? sniffImageFormat(header)?.mediaType : undefined);
208
+ const origCode = original?.error?.info?.code;
209
+ // Same format as the engine assumed and the store still refused: the file is damaged, not misnamed.
210
+ if (real.mediaType !== undefined && real.mediaType === engineType && accepted.includes(real.mediaType) && origCode !== "IMAGE_UNSUPPORTED_FORMAT") return undefined;
211
+
212
+ if (!real.image) {
213
+ return failure(
214
+ `cannot read "${displayPath}": the file is a ${real.label} despite ${named}, not an image; read_image accepts PNG/JPEG/WebP/GIF (HEIC/HEIF/AVIF/TIFF/BMP/PSD are converted on macOS)`,
215
+ "IMAGE_UNSUPPORTED_FORMAT",
216
+ );
217
+ }
218
+
219
+ const direct = real.mediaType !== undefined && accepted.includes(real.mediaType);
220
+ let data;
221
+ let mediaType;
222
+ let name = basename(displayPath);
223
+ if (direct) {
224
+ const byteCap = Math.min(limits.maxImageBytes ?? Infinity, limits.maxMessageImageBytes ?? Infinity);
225
+ data = await fs.readBytes(target, exec?.signal, Number.isFinite(byteCap) ? byteCap : CONVERT_SOURCE_MAX_BYTES);
226
+ mediaType = real.mediaType;
227
+ } else {
228
+ const format = accepted.includes("image/jpeg") ? "jpeg" : accepted.includes("image/png") ? "png" : undefined;
229
+ const sipsPath = options.sipsPath ?? DEFAULT_SIPS;
230
+ const canConvert = real.convertible === true && format !== undefined && (options.platform ?? process.platform) === "darwin" && existsSync(sipsPath);
231
+ if (!canConvert) {
232
+ return failure(
233
+ `cannot read "${displayPath}": the file is ${real.label} image data despite ${named}, and it cannot be converted here (automatic conversion needs macOS sips); convert it to JPEG or PNG and read the copy`,
234
+ "IMAGE_UNSUPPORTED_FORMAT",
235
+ );
236
+ }
237
+ const source = await fs.readBytes(target, exec?.signal, CONVERT_SOURCE_MAX_BYTES);
238
+ try {
239
+ data = await convertWithSips(source, format, { sipsPath, signal: exec?.signal, tmpRoot: options.tmpRoot });
240
+ } catch (error) {
241
+ return failure(
242
+ `cannot read "${displayPath}": the file is ${real.label} image data despite ${named}, and sips could not convert it (${String(error?.message ?? error)}); the file may be damaged, re-export it as JPEG or PNG and read the copy`,
243
+ "IMAGE_UNSUPPORTED_FORMAT",
244
+ );
245
+ }
246
+ mediaType = format === "png" ? "image/png" : "image/jpeg";
247
+ const stem = name.slice(0, name.length - extname(name).length) || name;
248
+ name = `${stem}.${format === "png" ? "png" : "jpg"}`;
249
+ }
250
+
251
+ let ref;
252
+ try {
253
+ ref = await attachments.saveImage({ data, mediaType, name });
254
+ } catch (error) {
255
+ return failure(`cannot read "${displayPath}" (${real.label} despite ${named}): ${saveRefusal(error, limits)}`, error?.code ?? "IMAGE_UNSUPPORTED_FORMAT", error?.name ?? "AttachmentError");
256
+ }
257
+ try {
258
+ ctx.emit?.("fs/observed", target, { kind: "present", version: info.version }, exec);
259
+ } catch {
260
+ // observation is bookkeeping for read-before-write; the read itself succeeded
261
+ }
262
+ const path = typeof fs.processPath === "function" ? fs.processPath(target) : displayPath;
263
+ return {
264
+ isError: false,
265
+ value: {
266
+ path,
267
+ image: {
268
+ attachmentId: ref.attachmentId,
269
+ mediaType: ref.mediaType,
270
+ bytes: ref.bytes,
271
+ width: ref.width,
272
+ height: ref.height,
273
+ ...(ref.name === undefined ? {} : { name: ref.name }),
274
+ ...(ref.originalDimensions === undefined ? {} : { originalDimensions: { width: ref.originalDimensions.width, height: ref.originalDimensions.height } }),
275
+ },
276
+ },
277
+ };
278
+ }
279
+
280
+ /**
281
+ * The `tools/execute` listener: the engine body first, recovery only on a format failure of `read_image`.
282
+ * A throw inside recovery keeps the engine's own failure (never a worse error than before).
283
+ */
284
+ export function createReadImageRecovery(ctx, options = {}) {
285
+ return async function readImageRecovery(exec, next) {
286
+ const result = await next();
287
+ if (exec?.name !== READ_IMAGE_TOOL || result?.isError !== true) return result;
288
+ if (!RECOVERABLE.has(result?.error?.info?.code)) return result;
289
+ if (exec?.signal?.aborted) return result;
290
+ try {
291
+ return (await recoverReadImage(ctx, exec, result, options)) ?? result;
292
+ } catch {
293
+ return result;
294
+ }
295
+ };
296
+ }
297
+
298
+ /** Mount the wrapper on every scope (CLI root scope and Mac preset scopes). Returns the disposer, if any. */
299
+ export function installReadImageRecovery(ctx, options = {}) {
300
+ if (typeof ctx?.on !== "function") return undefined;
301
+ try {
302
+ return ctx.on("tools/execute", createReadImageRecovery(ctx, options), { global: true });
303
+ } catch {
304
+ return undefined;
305
+ }
306
+ }