@picassohq/cli 1.0.1 → 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 (28) hide show
  1. package/dist/build-info.json +1 -1
  2. package/dist/index.js +1291 -1257
  3. package/package.json +1 -1
  4. package/runtime/engine-manifest.json +10 -9
  5. package/runtime/packages/picasso-lean-context/index.js +238 -7
  6. package/runtime/packages/picasso-lean-context/read-image-recovery.js +306 -0
  7. package/runtime/packages/picasso-lean-context/timeline.js +4 -3
  8. package/runtime/packages/picasso-model-router/connections.js +17 -0
  9. package/runtime/packages/picasso-model-router/index.js +2 -0
  10. package/runtime/packages/picasso-sdk-server/aside.js +15 -1
  11. package/runtime/packages/picasso-sdk-server/index.js +6 -1
  12. package/runtime/packages/picasso-web-search/backends.js +71 -9
  13. package/runtime/packages/picasso-web-search/failure.js +9 -4
  14. package/runtime/packages/picasso-web-search/format.js +13 -6
  15. package/runtime/packages/picasso-web-search/index.js +9 -4
  16. package/runtime/packages/picasso-web-search/router.js +3 -2
  17. package/runtime/plugins/picasso-lean-context/index.js +238 -7
  18. package/runtime/plugins/picasso-lean-context/read-image-recovery.js +306 -0
  19. package/runtime/plugins/picasso-lean-context/timeline.js +4 -3
  20. package/runtime/plugins/picasso-model-router/connections.js +17 -0
  21. package/runtime/plugins/picasso-model-router/index.js +2 -0
  22. package/runtime/plugins/picasso-web-search/backends.js +71 -9
  23. package/runtime/plugins/picasso-web-search/failure.js +9 -4
  24. package/runtime/plugins/picasso-web-search/format.js +13 -6
  25. package/runtime/plugins/picasso-web-search/index.js +9 -4
  26. package/runtime/plugins/picasso-web-search/router.js +3 -2
  27. package/runtime/relay/main.mjs +2403 -1075
  28. package/runtime/relay/versions-routes.mjs +218 -16
@@ -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
+ }
@@ -4,7 +4,7 @@
4
4
  // - the session's durable events (`sessionQuery.observeSession`): prompts, runtime context messages, tool calls and
5
5
  // their results, memory recalls, compaction, `assistant/message.usage` per step, `subagent/catalog` children;
6
6
  // - lean-context's per-step records (`ContextStats.stepsFor`, live engine only): the Tier-2 reminders the pre-step
7
- // normaliser injected (plan-mode, runtime-policy, stale-todos) and the step's message count. The engine logs each
7
+ // normaliser injected (plan-mode, runtime-policy, stale-todos, plan-nudge) and the step's message count. The engine logs each
8
8
  // step's normalised messages, so the reminders themselves are read from the log (sourced `user/message` rows);
9
9
  // the records corroborate them and add any the log missed. `stepStats` says how many steps a record covered.
10
10
  // The same fold runs without records (`picasso context timeline` reads a saved session's log directly).
@@ -79,8 +79,8 @@ function parseArguments(raw) {
79
79
  const FILE_READ_TOOLS = new Set(["read", "read_file", "view", "fs_read", "cat"]);
80
80
  const SPAWN_TOOLS = new Set(["subagent", "subagent_fork", "spawn_agent", "fork_agent", "spawn", "task", "agent_task"]);
81
81
  const SPAWN_RECEIPT = /^started subagent (\S+)\s*$/;
82
- /** Sourced reminder messages (Tier 2): lean-context's plan-mode / runtime-policy / stale-todos and the CLI's append. */
83
- export const REMINDER_KINDS = new Set(["plan-mode", "runtime-policy", "stale-todos", "append-system-prompt"]);
82
+ /** Sourced reminder messages (Tier 2): lean-context's plan-mode / runtime-policy / stale-todos / plan-nudge and the CLI's append. */
83
+ export const REMINDER_KINDS = new Set(["plan-mode", "runtime-policy", "stale-todos", "plan-nudge", "append-system-prompt"]);
84
84
 
85
85
  /** The timeline kind of one tool call: file / skill / memory / agent / tool. */
86
86
  function toolKind(name, args) {
@@ -134,6 +134,7 @@ function remindersOf(record) {
134
134
  injected.planMode === true ? "plan-mode" : null,
135
135
  injected.runtimePolicy === true ? "runtime-policy" : null,
136
136
  injected.staleTodos === true ? "stale-todos" : null,
137
+ injected.planNudge === true ? "plan-nudge" : null,
137
138
  ].filter(Boolean);
138
139
  }
139
140
 
@@ -408,6 +408,9 @@ export function normalizeSettings(raw) {
408
408
  // What a model pick applies to, remembered for the next pick (CLI `/model` picker, the Mac's model menus):
409
409
  // `default` (absent) = this chat and every new session/thread; `session` = this chat only.
410
410
  const modelPickScope = value.modelPickScope === 'session' ? 'session' : undefined;
411
+ // The models each connection shows in the pickers (`{"<route>": ["<model>", …]}`; @picasso/shared-home
412
+ // active-models.ts writes it, both surfaces read it). Kept through every save, never interpreted here.
413
+ const active = normalizeActive(value.active);
411
414
  return {
412
415
  version: 1,
413
416
  policy,
@@ -417,9 +420,23 @@ export function normalizeSettings(raw) {
417
420
  ...(alwaysThinks.length === 0 ? {} : { alwaysThinks }),
418
421
  ...(defaultEffort === undefined ? {} : { defaultEffort }),
419
422
  ...(modelPickScope === undefined ? {} : { modelPickScope }),
423
+ ...(active === undefined ? {} : { active }),
420
424
  };
421
425
  }
422
426
 
427
+ /** `active` as @picasso/shared-home `normalizeActiveModels` keeps it: route ids, each with de-duplicated model ids. */
428
+ function normalizeActive(raw) {
429
+ if (!isRecord(raw)) return undefined;
430
+ const out = {};
431
+ for (const [route, ids] of Object.entries(raw)) {
432
+ if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(route) || !Array.isArray(ids)) continue;
433
+ const list = [];
434
+ for (const id of ids) if (typeof id === 'string' && id.trim().length > 0 && !list.includes(id.trim())) list.push(id.trim());
435
+ out[route] = list;
436
+ }
437
+ return out;
438
+ }
439
+
423
440
  /**
424
441
  * A live reader: re-parsed only when the file changes; a missing or unreadable file reads as defaults. The change stamp is
425
442
  * inode + size + mtime: `writeSettings` replaces the file by rename (a new inode), so two saves inside one mtime tick
@@ -554,6 +554,8 @@ export class ModelRouterService {
554
554
  alwaysThinks: [...(current.alwaysThinks ?? [])],
555
555
  ...(current.defaultEffort === undefined ? {} : { defaultEffort: current.defaultEffort }),
556
556
  modelPickScope: current.modelPickScope === 'session' ? 'session' : 'default',
557
+ // The models each connection shows in the pickers (active-models.ts in @picasso/shared-home); absent = defaults.
558
+ ...(current.active === undefined ? {} : { active: { ...current.active } }),
557
559
  };
558
560
  }
559
561
 
@@ -5,10 +5,12 @@
5
5
  // anthropic Messages API with the server-side `web_search_20250305` tool
6
6
  // openai Responses API with the hosted `web_search` tool
7
7
  // google Gemini `generateContent` with `google_search` grounding
8
- // prism the owner's optional Prism service: the same Messages server-tool call, answered by Prism itself
8
+ // prism Prism (`prism`, `kiro-prism` routes, or an optional fallback): the same Messages server-tool call,
9
+ // answered by Prism itself from its own search pools (no model call)
9
10
  //
10
11
  // "Native" means the backend whose id the route maps to (NATIVE_ROUTES); any backend can also be a configured
11
12
  // fallback. Results carry only structured fields (url, title, snippet, publishedAt); provider prose is never an answer.
13
+ import { safeBaseUrl } from './config.js';
12
14
  import { BackendFailure, classifyEngineError, classifyHttp } from './failure.js';
13
15
 
14
16
  export const BACKEND_NAMES = Object.freeze({ deepseek: 'DeepSeek', anthropic: 'Anthropic', openai: 'OpenAI', google: 'Google', prism: 'Prism' });
@@ -20,8 +22,14 @@ export const NATIVE_ROUTES = Object.freeze({
20
22
  anthropic: 'anthropic',
21
23
  openai: 'openai',
22
24
  google: 'google',
25
+ // Prism routes: the gateway answers the Messages `web_search_20250305` server tool itself, from its own search pools.
26
+ prism: 'prism',
27
+ 'kiro-prism': 'prism',
23
28
  });
24
29
 
30
+ /** Prism's endpoint when a Prism route's own profile cannot be read (the shipped `prism`/`kiro-prism` baseURL origin). */
31
+ export const DEFAULT_PRISM_URL = 'https://prism.auraone.ai';
32
+
25
33
  /** The credential reference each route's key resolves through (the `apiKeyEnv` of dsh/picasso-runtime.cordis.yml). */
26
34
  export const KEY_REFS = Object.freeze({ anthropic: 'ANTHROPIC_API_KEY', openai: 'OPENAI_API_KEY', google: 'GOOGLE_API_KEY', deepseek: 'DEEPSEEK_API_KEY' });
27
35
 
@@ -44,6 +52,13 @@ const SNIPPET_MAX = 280;
44
52
  const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
45
53
  const str = (value) => (typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined);
46
54
  const prompt = (query) => `Perform a web search for the query: ${query}`;
55
+ const REF_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
56
+
57
+ /** The Messages base of a route's OpenAI-style baseURL (`https://host/v1` -> `https://host`); undefined when unsafe. */
58
+ export function messagesBase(baseURL) {
59
+ const safe = safeBaseUrl(baseURL);
60
+ return safe === undefined ? undefined : safe.replace(/\/v1$/u, '');
61
+ }
47
62
 
48
63
  /** `{ url, title?, snippet?, publishedAt? }` with absent fields omitted; null when the url is not http(s). */
49
64
  function source(url, title, snippet, publishedAt) {
@@ -255,19 +270,57 @@ export function credentialsFrom(ctx, env = process.env) {
255
270
  // The backends
256
271
 
257
272
  /**
258
- * `deps`: `{ creds, fetch, getWeb }`. Every backend answers:
273
+ * The thread's route profile as the engine holds it (`{ baseURL?, apiKeyEnv? }`), read per search from the llm
274
+ * service's provider directory and the settings namespace that configures the route; undefined when it cannot be read.
275
+ * A home may override a route (the Mac profile points `kiro-prism` at `KIRO_PRISM_API_KEY`), so this, not the shipped
276
+ * catalogue, says which endpoint and key the thread itself uses.
277
+ */
278
+ export function routeProfileFrom(ctx) {
279
+ return async (route) => {
280
+ if (str(route) === undefined) return undefined;
281
+ try {
282
+ const entries = ctx?.get?.('llm')?.listConfigurableProviders?.();
283
+ const entry = Array.isArray(entries) ? entries.find((candidate) => isRecord(candidate) && candidate.provider === route) : undefined;
284
+ if (entry === undefined) return undefined;
285
+ const namespaces = ctx?.get?.('settings')?.describe?.();
286
+ let profile = Array.isArray(namespaces) ? namespaces.find((candidate) => isRecord(candidate) && candidate.ns === entry.settingsNs)?.value : undefined;
287
+ for (const key of Array.isArray(entry.settingsPath) ? entry.settingsPath : []) profile = isRecord(profile) ? profile[key] : undefined;
288
+ const baseURL = (isRecord(profile) ? str(profile.baseURL) : undefined) ?? str(entry.defaultBaseURL);
289
+ const apiKeyEnv = isRecord(profile) ? str(profile.apiKeyEnv) : undefined;
290
+ return { ...(baseURL === undefined ? {} : { baseURL }), ...(apiKeyEnv !== undefined && REF_NAME.test(apiKeyEnv) ? { apiKeyEnv } : {}) };
291
+ } catch {
292
+ return undefined;
293
+ }
294
+ };
295
+ }
296
+
297
+ /**
298
+ * `deps`: `{ creds, fetch, getWeb, routeProfile }`. Every backend answers:
259
299
  * `configured(call)` whether a search could be sent (a credential or an engine provider is present); no network
300
+ * `keyRef(call)` the credential reference it needs (for the "no credentials (needs X)" reason), if any
260
301
  * `search(request, call)` `call = { signal, route, model, role, config }`
261
302
  */
262
- export function createBackends({ creds, fetch: fetchImpl = globalThis.fetch, getWeb = () => undefined }) {
303
+ export function createBackends({ creds, fetch: fetchImpl = globalThis.fetch, getWeb = () => undefined, routeProfile = async () => undefined }) {
263
304
  const modelFor = (id, call) => call.config.models[id] ?? (call.role === 'native' && str(call.model) !== undefined ? str(call.model) : DEFAULT_MODELS[id]);
264
305
  const baseFor = (id, call) => call.config.baseUrls[id] ?? DEFAULT_BASE_URLS[id];
265
306
  const keyed = (id) => async (call) => (await creds.configured(KEY_REFS[id])) && Boolean(baseFor(id, call));
266
307
  const requireKey = async (id) => {
267
308
  const key = await creds.resolve(KEY_REFS[id]);
268
- if (key === undefined) throw new BackendFailure('credentials');
309
+ if (key === undefined) throw new BackendFailure('credentials', { ref: KEY_REFS[id] });
269
310
  return key;
270
311
  };
312
+ const keyRefOf = (id) => async () => KEY_REFS[id];
313
+
314
+ // Prism as the thread's own route: the route's endpoint and key reference (its profile), else the configured Prism
315
+ // endpoint and key, else the shipped endpoint. As a fallback: only the configured endpoint and key.
316
+ const prismTarget = async (call) => {
317
+ if (call.role !== 'native') return { url: call.config.prismUrl, keyRef: call.config.prismKeyRef };
318
+ const profile = await routeProfile(call.route);
319
+ return {
320
+ url: messagesBase(profile?.baseURL) ?? call.config.prismUrl ?? DEFAULT_PRISM_URL,
321
+ keyRef: profile?.apiKeyEnv ?? call.config.prismKeyRef,
322
+ };
323
+ };
271
324
 
272
325
  const engineProvider = () => {
273
326
  const registry = getWeb()?.searchProviders;
@@ -304,6 +357,7 @@ export function createBackends({ creds, fetch: fetchImpl = globalThis.fetch, get
304
357
  id: 'anthropic',
305
358
  name: BACKEND_NAMES.anthropic,
306
359
  configured: keyed('anthropic'),
360
+ keyRef: keyRefOf('anthropic'),
307
361
  async search(request, call) {
308
362
  const key = await requireKey('anthropic');
309
363
  const json = await postJson(fetchImpl, `${baseFor('anthropic', call)}/v1/messages`, { 'x-api-key': key, 'anthropic-version': ANTHROPIC_VERSION }, messagesBody(modelFor('anthropic', call), request.query), call.signal);
@@ -314,6 +368,7 @@ export function createBackends({ creds, fetch: fetchImpl = globalThis.fetch, get
314
368
  id: 'openai',
315
369
  name: BACKEND_NAMES.openai,
316
370
  configured: keyed('openai'),
371
+ keyRef: keyRefOf('openai'),
317
372
  async search(request, call) {
318
373
  const key = await requireKey('openai');
319
374
  const body = { model: modelFor('openai', call), input: prompt(request.query), tools: [{ type: 'web_search' }], tool_choice: 'required', store: false };
@@ -324,6 +379,7 @@ export function createBackends({ creds, fetch: fetchImpl = globalThis.fetch, get
324
379
  id: 'google',
325
380
  name: BACKEND_NAMES.google,
326
381
  configured: keyed('google'),
382
+ keyRef: keyRefOf('google'),
327
383
  async search(request, call) {
328
384
  const key = await requireKey('google');
329
385
  const model = encodeURIComponent(modelFor('google', call).replace(/^models\//u, ''));
@@ -334,15 +390,21 @@ export function createBackends({ creds, fetch: fetchImpl = globalThis.fetch, get
334
390
  prism: {
335
391
  id: 'prism',
336
392
  name: BACKEND_NAMES.prism,
337
- // Optional: active only when both an endpoint and a key are configured. Absent is skipped silently.
393
+ // As a fallback, optional: active only when both an endpoint and a key are configured (absent is skipped
394
+ // silently). As a Prism route's own search, the route's endpoint and key.
338
395
  async configured(call) {
339
- return call.config.prismUrl !== undefined && (await creds.configured(call.config.prismKeyRef));
396
+ const { url, keyRef } = await prismTarget(call);
397
+ return url !== undefined && (await creds.configured(keyRef));
398
+ },
399
+ async keyRef(call) {
400
+ return (await prismTarget(call)).keyRef;
340
401
  },
341
402
  async search(request, call) {
342
- const key = await creds.resolve(call.config.prismKeyRef);
343
- if (key === undefined || call.config.prismUrl === undefined) throw new BackendFailure('credentials');
403
+ const { url, keyRef } = await prismTarget(call);
404
+ const key = await creds.resolve(keyRef);
405
+ if (key === undefined || url === undefined) throw new BackendFailure('credentials', { ref: keyRef });
344
406
  const headers = { 'x-api-key': key, authorization: `Bearer ${key}`, 'anthropic-version': ANTHROPIC_VERSION };
345
- const json = await postJson(fetchImpl, `${call.config.prismUrl}/v1/messages`, headers, messagesBody(call.config.models.prism ?? DEFAULT_MODELS.prism, request.query), call.signal);
407
+ const json = await postJson(fetchImpl, `${url}/v1/messages`, headers, messagesBody(modelFor('prism', call), request.query), call.signal);
346
408
  return parseMessagesSearch(json);
347
409
  },
348
410
  },
@@ -9,7 +9,8 @@ export const TRANSIENT_KINDS = Object.freeze(new Set(['rate', 'server']));
9
9
  export class BackendFailure extends Error {
10
10
  /**
11
11
  * @param {string} kind billing | auth | forbidden | rate | server | rejected | credentials | empty | unreadable | network | outcome-unknown | timeout
12
- * @param {{status?: number, retryAfterMs?: number}} [detail]
12
+ * @param {{status?: number, retryAfterMs?: number, ref?: string}} [detail] `ref`: the credential reference a
13
+ * `credentials` failure needs (a name such as `PRISM_API_KEY`, never a value)
13
14
  */
14
15
  constructor(kind, detail = {}) {
15
16
  super(`web search backend failed: ${kind}`);
@@ -17,6 +18,7 @@ export class BackendFailure extends Error {
17
18
  this.kind = kind;
18
19
  if (detail.status !== undefined) this.status = detail.status;
19
20
  if (detail.retryAfterMs !== undefined) this.retryAfterMs = detail.retryAfterMs;
21
+ if (typeof detail.ref === 'string' && REF_NAME.test(detail.ref)) this.ref = detail.ref;
20
22
  }
21
23
 
22
24
  get permanent() {
@@ -29,13 +31,15 @@ export class BackendFailure extends Error {
29
31
 
30
32
  /** The closed-vocabulary reason shown to the model and the person. */
31
33
  get reason() {
32
- return reasonFor(this.kind, this.status, this.retryAfterMs);
34
+ return reasonFor(this.kind, this.status, this.retryAfterMs, this.ref);
33
35
  }
34
36
  }
35
37
 
38
+ const REF_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
39
+
36
40
  const withStatus = (label, status) => (status === undefined ? label : `${label} (HTTP ${status})`);
37
41
 
38
- export function reasonFor(kind, status, retryAfterMs) {
42
+ export function reasonFor(kind, status, retryAfterMs, ref) {
39
43
  switch (kind) {
40
44
  case 'billing':
41
45
  return withStatus('insufficient balance or billing problem', status);
@@ -50,7 +54,8 @@ export function reasonFor(kind, status, retryAfterMs) {
50
54
  case 'rejected':
51
55
  return withStatus('request rejected', status);
52
56
  case 'credentials':
53
- return 'no credentials';
57
+ // The reference names the key to add (`picasso provider set`), never its value.
58
+ return typeof ref === 'string' && REF_NAME.test(ref) ? `no credentials (needs ${ref})` : 'no credentials';
54
59
  case 'empty':
55
60
  return 'returned no search results block';
56
61
  case 'unreadable':
@@ -25,11 +25,18 @@ export function formatBackendMarker(name) {
25
25
  return `${BACKEND_MARKER_PREFIX}${name}${BACKEND_MARKER_SUFFIX}`;
26
26
  }
27
27
 
28
- /** `attempts`: `[{ name, reason }]` in the order tried. An empty list says no backend is configured for this route. */
29
- export function formatUnavailable(attempts) {
30
- const lines =
31
- attempts.length === 0
32
- ? ['- none: this model route has no native web search and no fallback is configured']
33
- : attempts.map((attempt) => `- ${attempt.name}: ${attempt.reason}`);
28
+ /** The line for a route with nothing to try: it names the route and what web search needs there. */
29
+ export function formatNothingConfigured(route) {
30
+ const id = typeof route === 'string' && /^[A-Za-z0-9._-]{1,64}$/u.test(route) ? route : undefined;
31
+ if (id === undefined) return '- none: this model route has no native web search and no fallback is configured';
32
+ return `- none: the ${id} route has no native web search and no fallback is configured (web search needs a fallback in settings.webSearch.fallbacks or PICASSO_WEB_SEARCH_FALLBACKS, e.g. anthropic or openai)`;
33
+ }
34
+
35
+ /**
36
+ * `attempts`: `[{ name, reason }]` in the order tried. An empty list says no backend is configured for this route;
37
+ * `route` (the thread's route id, a config key) is named in that line when given.
38
+ */
39
+ export function formatUnavailable(attempts, { route } = {}) {
40
+ const lines = attempts.length === 0 ? [formatNothingConfigured(route)] : attempts.map((attempt) => `- ${attempt.name}: ${attempt.reason}`);
34
41
  return [UNAVAILABLE_HEADLINE, BACKENDS_TRIED_LABEL, ...lines, UNAVAILABLE_INSTRUCTION].join('\n');
35
42
  }
@@ -8,14 +8,14 @@
8
8
  //
9
9
  // The tool's schema and description belong to the engine's tool-web and are untouched, so the wire tool list (Tier 1)
10
10
  // is byte-identical: `ready` is always true, so the model is never told `unknown tool "web_search"` (see createSearchProvider).
11
- import { createBackends, credentialsFrom } from './backends.js';
11
+ import { createBackends, credentialsFrom, routeProfileFrom } from './backends.js';
12
12
  import { configReader } from './config.js';
13
13
  import { createRouter } from './router.js';
14
14
 
15
15
  export * from './format.js';
16
16
  export * from './failure.js';
17
17
  export * from './config.js';
18
- export { BACKEND_NAMES, DEFAULT_BASE_URLS, DEFAULT_MODELS, KEY_REFS, NATIVE_ROUTES, createBackends, credentialsFrom, parseGeminiSearch, parseMessagesSearch, parseOpenAiSearch } from './backends.js';
18
+ export { BACKEND_NAMES, DEFAULT_BASE_URLS, DEFAULT_MODELS, DEFAULT_PRISM_URL, KEY_REFS, NATIVE_ROUTES, createBackends, credentialsFrom, messagesBase, parseGeminiSearch, parseMessagesSearch, parseOpenAiSearch, routeProfileFrom } from './backends.js';
19
19
  export { DEFAULT_RETRY_DELAY_MS, MAX_RETRY_WAIT_MS, UNAVAILABLE_CODE, createRouter } from './router.js';
20
20
 
21
21
  export const name = 'picasso-web-search';
@@ -29,9 +29,14 @@ const DESCRIPTION = Object.freeze({
29
29
  });
30
30
 
31
31
  /** The search provider over a web seam (`web.registerSearchProvider`), for tests and for `apply`. */
32
- export function createSearchProvider({ ctx, getWeb, fetch: fetchImpl, readConfig, sleep, maxRetryWaitMs } = {}) {
32
+ export function createSearchProvider({ ctx, getWeb, fetch: fetchImpl, readConfig, sleep, maxRetryWaitMs, routeProfile } = {}) {
33
33
  const creds = credentialsFrom(ctx);
34
- const backends = createBackends({ creds, ...(fetchImpl === undefined ? {} : { fetch: fetchImpl }), getWeb: getWeb ?? (() => undefined) });
34
+ const backends = createBackends({
35
+ creds,
36
+ ...(fetchImpl === undefined ? {} : { fetch: fetchImpl }),
37
+ getWeb: getWeb ?? (() => undefined),
38
+ routeProfile: routeProfile ?? routeProfileFrom(ctx),
39
+ });
35
40
  const router = createRouter({ ctx, readConfig: readConfig ?? configReader(), backends, ...(sleep === undefined ? {} : { sleep }), ...(maxRetryWaitMs === undefined ? {} : { maxRetryWaitMs }) });
36
41
  return {
37
42
  id: PROVIDER_ID,