@picassohq/cli 1.0.3 → 1.0.4

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 (40) hide show
  1. package/dist/build-info.json +1 -1
  2. package/dist/index.js +1591 -1251
  3. package/package.json +1 -1
  4. package/runtime/engine-manifest.json +22 -11
  5. package/runtime/packages/picasso-compaction/cordis.patch.yml +4 -0
  6. package/runtime/packages/picasso-compaction/index.js +623 -0
  7. package/runtime/packages/picasso-compaction/package.json +27 -0
  8. package/runtime/packages/picasso-lean-context/argument-repair.js +422 -0
  9. package/runtime/packages/picasso-lean-context/index.js +23 -2
  10. package/runtime/packages/picasso-model-router/connections.js +49 -3
  11. package/runtime/packages/picasso-model-router/index.js +32 -1
  12. package/runtime/packages/picasso-model-router/package.json +3 -1
  13. package/runtime/packages/picasso-model-router/thinking-default.js +212 -0
  14. package/runtime/packages/picasso-web-search/backends.js +245 -195
  15. package/runtime/packages/picasso-web-search/config.js +75 -27
  16. package/runtime/packages/picasso-web-search/cordis.patch.yml +2 -1
  17. package/runtime/packages/picasso-web-search/failure.js +7 -1
  18. package/runtime/packages/picasso-web-search/index.js +7 -5
  19. package/runtime/packages/picasso-web-search/package.json +6 -0
  20. package/runtime/packages/picasso-web-search/requests.js +339 -0
  21. package/runtime/packages/picasso-web-search/router.js +17 -12
  22. package/runtime/plugins/picasso-compaction/index.js +623 -0
  23. package/runtime/plugins/picasso-compaction/package.json +27 -0
  24. package/runtime/plugins/picasso-lean-context/argument-repair.js +422 -0
  25. package/runtime/plugins/picasso-lean-context/index.js +23 -2
  26. package/runtime/plugins/picasso-model-router/connections.js +49 -3
  27. package/runtime/plugins/picasso-model-router/index.js +32 -1
  28. package/runtime/plugins/picasso-model-router/package.json +3 -1
  29. package/runtime/plugins/picasso-model-router/thinking-default.js +212 -0
  30. package/runtime/plugins/picasso-provider-models/index.js +236 -4
  31. package/runtime/plugins/picasso-web-search/backends.js +245 -195
  32. package/runtime/plugins/picasso-web-search/config.js +75 -27
  33. package/runtime/plugins/picasso-web-search/failure.js +7 -1
  34. package/runtime/plugins/picasso-web-search/index.js +7 -5
  35. package/runtime/plugins/picasso-web-search/package.json +6 -0
  36. package/runtime/plugins/picasso-web-search/requests.js +339 -0
  37. package/runtime/plugins/picasso-web-search/router.js +17 -12
  38. package/runtime/relay/main.mjs +2776 -1494
  39. package/runtime/relay/model-listing.mjs +337 -26
  40. package/runtime/relay/versions-routes.mjs +65 -3
@@ -1,5 +1,8 @@
1
- // Where the fallback list and the optional endpoints come from. Nothing here is assumed: an empty list is the default,
2
- // and a backend whose endpoint or key is absent is left out silently (never an error).
1
+ // Where the fallback list and the optional endpoints come from. With no list set anywhere, the search-capable providers
2
+ // the person has already connected are tried, in AUTO_FALLBACKS order (prism, deepseek, google, anthropic, openai, then
3
+ // Picasso's managed search when signed in); a
4
+ // backend whose endpoint or key is absent is left out silently (never an error). A written list, even an empty one, is
5
+ // used exactly as written (an empty list turns fallbacks off).
3
6
  //
4
7
  // env (wins) settings.json `settings.webSearch` (read live, mtime cached)
5
8
  // PICASSO_WEB_SEARCH_FALLBACKS=prism,... { fallbacks: ['prism', ...] | 'prism,...' }
@@ -8,15 +11,26 @@
8
11
  // PICASSO_WEB_SEARCH_<ANTHROPIC|OPENAI|GOOGLE>_BASE_URL / _MODEL endpoint and model when that backend is a fallback
9
12
  // PICASSO_WEB_SEARCH_TIMEOUT_MS per-backend time limit (default 20000)
10
13
  //
14
+ // Routes the person disconnected (`disconnected` in the shared model-connections.json, beside settings.json; `picasso
15
+ // provider disconnect`, the Mac's Disconnect) are read with it: a fallback never borrows a disconnected route's key.
16
+ //
11
17
  // Keys are never read here: each backend resolves its key per search through the engine's credential seam.
12
18
  import { readFileSync, statSync } from 'node:fs';
13
19
  import { homedir } from 'node:os';
14
- import { join } from 'node:path';
20
+ import { dirname, join } from 'node:path';
15
21
 
16
22
  /** Backends a fallback entry may name, in the vocabulary of the list (`gemini` is an alias of `google`). */
17
- export const FALLBACK_IDS = Object.freeze(['deepseek', 'anthropic', 'openai', 'google', 'prism']);
23
+ export const FALLBACK_IDS = Object.freeze(['deepseek', 'anthropic', 'openai', 'google', 'prism', 'picasso']);
18
24
  const ALIASES = Object.freeze({ gemini: 'google' });
19
25
 
26
+ /**
27
+ * The order tried when no list is set anywhere: every search-capable provider the person has already connected, then
28
+ * Picasso's managed search while the person is signed in and the managed lane is on (last, so the person's own keys
29
+ * answer first). A backend with no key (or no sign-in) is left out silently, so this costs nothing where none is
30
+ * connected. An explicit list (even an empty one) replaces it.
31
+ */
32
+ export const AUTO_FALLBACKS = Object.freeze(['prism', 'deepseek', 'google', 'anthropic', 'openai', 'picasso']);
33
+
20
34
  export const DEFAULT_TIMEOUT_MS = 20_000;
21
35
  export const DEFAULT_PRISM_KEY_REF = 'PRISM_API_KEY';
22
36
 
@@ -30,6 +44,20 @@ export function defaultSettingsFile(env = process.env) {
30
44
  return join(home, 'settings', 'settings.json');
31
45
  }
32
46
 
47
+ /** The shared connections file beside a settings file (`<settings>/model-connections.json`). */
48
+ export function connectionsFileFor(settingsFile) {
49
+ return join(dirname(settingsFile), 'model-connections.json');
50
+ }
51
+
52
+ /** `disconnected` of a parsed connections document: route ids, deduplicated. */
53
+ export function disconnectedRoutes(document) {
54
+ const out = [];
55
+ for (const id of isRecord(document) && Array.isArray(document.disconnected) ? document.disconnected : []) {
56
+ if (typeof id === 'string' && id.trim() !== '' && !out.includes(id.trim())) out.push(id.trim());
57
+ }
58
+ return out;
59
+ }
60
+
33
61
  /** The ordered, deduplicated fallback ids from a comma/space list or an array; unknown names are dropped. */
34
62
  export function parseFallbackList(raw) {
35
63
  const items = Array.isArray(raw) ? raw : typeof raw === 'string' ? raw.split(/[\s,]+/u) : [];
@@ -62,8 +90,11 @@ export function safeBaseUrl(raw) {
62
90
 
63
91
  const text = (value) => (typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined);
64
92
 
65
- /** The effective configuration from a parsed settings file and the environment (env wins). */
66
- export function webSearchConfig(file, env = process.env) {
93
+ /**
94
+ * The effective configuration from a parsed settings file and the environment (env wins), plus the disconnected
95
+ * routes of a parsed connections document.
96
+ */
97
+ export function webSearchConfig(file, env = process.env, connections = undefined) {
67
98
  const settings = isRecord(file) && isRecord(file.settings) ? file.settings : {};
68
99
  const stored = isRecord(settings.webSearch) ? settings.webSearch : {};
69
100
  const fromEnv = text(env.PICASSO_WEB_SEARCH_FALLBACKS);
@@ -80,41 +111,58 @@ export function webSearchConfig(file, env = process.env) {
80
111
  }
81
112
  const prismUrl = safeBaseUrl(text(env.PICASSO_WEB_SEARCH_PRISM_URL) ?? stored.prismUrl);
82
113
  const prismKeyRef = text(env.PICASSO_WEB_SEARCH_PRISM_KEY_ENV);
83
- // No list anywhere but a Prism endpoint is configured: setting that endpoint is the opt-in, so Prism is tried when the
84
- // native search fails. Without an endpoint nothing is assumed and the list stays empty.
114
+ // No list anywhere: a route with no search of its own (a gateway, an OpenAI-compatible host) uses the search of the
115
+ // providers already connected, in AUTO_FALLBACKS order. An explicit list, even an empty one, is honoured as written.
85
116
  const unlisted = fromEnv === undefined && stored.fallbacks === undefined;
86
- const fallbacks = unlisted && prismUrl !== undefined ? ['prism'] : listed;
117
+ const fallbacks = unlisted ? [...AUTO_FALLBACKS] : listed;
87
118
  return {
88
119
  fallbacks,
120
+ auto: unlisted,
89
121
  baseUrls,
90
122
  models,
91
123
  ...(prismUrl === undefined ? {} : { prismUrl }),
92
124
  prismKeyRef: prismKeyRef !== undefined && /^[A-Za-z_][A-Za-z0-9_]*$/u.test(prismKeyRef) ? prismKeyRef : DEFAULT_PRISM_KEY_REF,
93
125
  timeoutMs: Number.isFinite(timeout) && timeout >= 1000 ? Math.min(timeout, 120_000) : DEFAULT_TIMEOUT_MS,
126
+ disconnected: disconnectedRoutes(connections),
127
+ connected: disconnectedRoutes(isRecord(connections) ? { disconnected: connections.connected } : undefined),
94
128
  };
95
129
  }
96
130
 
97
- /** A live reader over the settings file: re-parsed only when its mtime changes; unreadable reads as defaults. */
98
- export function configReader({ settingsFile, env = process.env } = {}) {
131
+ /** A file's change stamp (inode + size + mtime), or undefined when it cannot be read. */
132
+ function stampOf(file) {
133
+ try {
134
+ const stat = statSync(file);
135
+ return `${stat.ino}:${stat.size}:${stat.mtimeMs}`;
136
+ } catch {
137
+ return undefined;
138
+ }
139
+ }
140
+
141
+ function readJson(file, stamp) {
142
+ if (stamp === undefined) return undefined;
143
+ try {
144
+ return JSON.parse(readFileSync(file, 'utf8'));
145
+ } catch {
146
+ return undefined;
147
+ }
148
+ }
149
+
150
+ /**
151
+ * A live reader over the settings file and the connections file beside it: re-parsed only when either changes;
152
+ * unreadable reads as defaults.
153
+ */
154
+ export function configReader({ settingsFile, connectionsFile, env = process.env } = {}) {
99
155
  const file = typeof settingsFile === 'string' && settingsFile !== '' ? settingsFile : defaultSettingsFile(env);
100
- let mtime;
156
+ const connections = typeof connectionsFile === 'string' && connectionsFile !== '' ? connectionsFile : connectionsFileFor(file);
157
+ let key;
101
158
  let cached = webSearchConfig(undefined, env);
102
159
  return () => {
103
- let stat;
104
- try {
105
- stat = statSync(file);
106
- } catch {
107
- mtime = undefined;
108
- cached = webSearchConfig(undefined, env);
109
- return cached;
110
- }
111
- if (stat.mtimeMs !== mtime) {
112
- mtime = stat.mtimeMs;
113
- try {
114
- cached = webSearchConfig(JSON.parse(readFileSync(file, 'utf8')), env);
115
- } catch {
116
- cached = webSearchConfig(undefined, env);
117
- }
160
+ const settingsStamp = stampOf(file);
161
+ const connectionsStamp = stampOf(connections);
162
+ const next = `${settingsStamp ?? 'missing'}|${connectionsStamp ?? 'missing'}`;
163
+ if (next !== key) {
164
+ key = next;
165
+ cached = webSearchConfig(readJson(file, settingsStamp), env, readJson(connections, connectionsStamp));
118
166
  }
119
167
  return cached;
120
168
  };
@@ -8,7 +8,7 @@ export const TRANSIENT_KINDS = Object.freeze(new Set(['rate', 'server']));
8
8
 
9
9
  export class BackendFailure extends Error {
10
10
  /**
11
- * @param {string} kind billing | auth | forbidden | rate | server | rejected | credentials | empty | unreadable | network | outcome-unknown | timeout
11
+ * @param {string} kind billing | auth | forbidden | rate | server | rejected | credentials | signed-out | quota | empty | unreadable | network | outcome-unknown | timeout
12
12
  * @param {{status?: number, retryAfterMs?: number, ref?: string}} [detail] `ref`: the credential reference a
13
13
  * `credentials` failure needs (a name such as `PRISM_API_KEY`, never a value)
14
14
  */
@@ -56,6 +56,12 @@ export function reasonFor(kind, status, retryAfterMs, ref) {
56
56
  case 'credentials':
57
57
  // The reference names the key to add (`picasso provider set`), never its value.
58
58
  return typeof ref === 'string' && REF_NAME.test(ref) ? `no credentials (needs ${ref})` : 'no credentials';
59
+ case 'signed-out':
60
+ // Picasso's managed search: the account session is missing or no longer accepted.
61
+ return 'not signed in to Picasso';
62
+ case 'quota':
63
+ // Picasso's managed search: the account's daily managed limit (the same one managed models use).
64
+ return 'daily usage limit reached (resets at 00:00 UTC)';
59
65
  case 'empty':
60
66
  return 'returned no search results block';
61
67
  case 'unreadable':
@@ -3,8 +3,9 @@
3
3
  // dsh's `ctx.web` selects ONE search provider by id (`web.searchProvider`), and the shipped composition pins a DeepSeek
4
4
  // one, so every thread's `web_search` went to the DeepSeek API with the DeepSeek key whatever model it ran. This plugin
5
5
  // registers `picasso-web-search` (the CLI patch and the Mac relay pin it) and chooses per call, from the thread's own
6
- // route: its native search with its own credentials, then the configured fallbacks (PICASSO_WEB_SEARCH_FALLBACKS,
7
- // `settings.webSearch`), then a structured error that names every backend tried. See router.js and README.md.
6
+ // route: its native search with its own credentials, then the fallbacks (the list in PICASSO_WEB_SEARCH_FALLBACKS /
7
+ // `settings.webSearch`; with no list, the search-capable providers already connected, then Picasso's managed search
8
+ // while signed in), then a structured error that names every backend tried. See router.js and README.md.
8
9
  //
9
10
  // The tool's schema and description belong to the engine's tool-web and are untouched, so the wire tool list (Tier 1)
10
11
  // is byte-identical: `ready` is always true, so the model is never told `unknown tool "web_search"` (see createSearchProvider).
@@ -15,7 +16,7 @@ import { createRouter } from './router.js';
15
16
  export * from './format.js';
16
17
  export * from './failure.js';
17
18
  export * from './config.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
+ export { BACKEND_NAMES, FALLBACK_ROUTES, fallbackDisconnected, DEFAULT_BASE_URLS, DEFAULT_MODELS, DEFAULT_PRISM_URL, GROUNDING_RESOLVE_MAX, GROUNDING_RESOLVE_TIMEOUT_MS, KEY_REFS, DEFAULT_MINIMAX_URL, MANAGED_AVAILABLE_TTL_MS, MANAGED_SEARCH_SYMBOL, MINIMAX_SEARCH_PATH, NATIVE_ROUTES, PRISM_ROUTES, nativeBackendFor, parseMiniMaxSearch, createBackends, credentialsFrom, isGroundingRedirect, managedSearchCapability, managedSearchFailure, messagesBase, parseGeminiSearch, parseManagedSearch, parseMessagesSearch, parseOpenAiSearch, resolveGroundingRedirects, routeProfileFrom } from './backends.js';
19
20
  export { DEFAULT_RETRY_DELAY_MS, MAX_RETRY_WAIT_MS, UNAVAILABLE_CODE, createRouter } from './router.js';
20
21
 
21
22
  export const name = 'picasso-web-search';
@@ -25,15 +26,16 @@ export const dshTarget = '0.2.2-rc.3';
25
26
  export const PROVIDER_ID = 'picasso-web-search';
26
27
 
27
28
  const DESCRIPTION = Object.freeze({
28
- en: "Searches with the model you are chatting with (its own web search and key), then any fallback you configured. Reports a failure instead of guessing.",
29
+ en: "Searches with the model you are chatting with (its own web search and key), then the other search-capable providers you have connected, or the fallbacks you listed. Reports a failure instead of guessing.",
29
30
  });
30
31
 
31
32
  /** 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, routeProfile } = {}) {
33
+ export function createSearchProvider({ ctx, getWeb, fetch: fetchImpl, readConfig, sleep, maxRetryWaitMs, routeProfile, managedSearch } = {}) {
33
34
  const creds = credentialsFrom(ctx);
34
35
  const backends = createBackends({
35
36
  creds,
36
37
  ...(fetchImpl === undefined ? {} : { fetch: fetchImpl }),
38
+ ...(managedSearch === undefined ? {} : { managedSearch }),
37
39
  getWeb: getWeb ?? (() => undefined),
38
40
  routeProfile: routeProfile ?? routeProfileFrom(ctx),
39
41
  });
@@ -11,6 +11,10 @@
11
11
  "types": "./index.d.ts",
12
12
  "default": "./index.js"
13
13
  },
14
+ "./requests": {
15
+ "types": "./requests.d.ts",
16
+ "default": "./requests.js"
17
+ },
14
18
  "./cordis.patch.yml": "./cordis.patch.yml",
15
19
  "./package.json": "./package.json"
16
20
  },
@@ -28,6 +32,8 @@
28
32
  "index.d.ts",
29
33
  "format.js",
30
34
  "failure.js",
35
+ "requests.js",
36
+ "requests.d.ts",
31
37
  "config.js",
32
38
  "backends.js",
33
39
  "router.js",
@@ -0,0 +1,339 @@
1
+ // The search requests and their parsers: one place for the wire shapes, shared by the plugin's backends (backends.js)
2
+ // and by the Picasso API's managed search (`POST /v1/managed/search`, apps/api/src/managed/web-search.ts), which
3
+ // imports `@picasso/web-search/requests`. Zero dependencies; no engine, settings or credential code here.
4
+ //
5
+ // messagesSearchRequest Anthropic Messages with the server-side `web_search_20250305` tool (Anthropic, and Prism,
6
+ // which answers the same call itself from its own search pools, no model call)
7
+ // geminiSearchRequest Gemini `generateContent` with `google_search` grounding (redirect links resolved)
8
+ // minimaxSearchRequest MiniMax coding-plan search (`POST <origin>/v1/coding_plan/search`)
9
+ //
10
+ // Every function returns `{ result: { sources, truncated: false }, ...meter }` or throws a BackendFailure (failure.js):
11
+ // results carry only url, title, snippet and publishedAt; provider prose is never an answer. The meter fields are what
12
+ // a caller that bills per search reads (how many searches the provider ran, the tokens a grounded call used).
13
+ import { BackendFailure, classifyHttp } from './failure.js';
14
+
15
+ export { BackendFailure } from './failure.js';
16
+
17
+ export const ANTHROPIC_VERSION = '2023-06-01';
18
+ export const USER_AGENT = 'picasso-web-search/0.1';
19
+ export const MESSAGES_MAX_USES = 2;
20
+ const MAX_TOKENS = 2048;
21
+ const BODY_PEEK_BYTES = 4096;
22
+ const SNIPPET_MAX = 280;
23
+
24
+ /** MiniMax's coding-plan search path, appended to the origin of a MiniMax endpoint. */
25
+ export const MINIMAX_SEARCH_PATH = '/v1/coding_plan/search';
26
+
27
+ const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
28
+ const str = (value) => (typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined);
29
+ const prompt = (query) => `Perform a web search for the query: ${query}`;
30
+
31
+ /** `{ url, title?, snippet?, publishedAt? }` with absent fields omitted; null when the url is not http(s). */
32
+ export function normalizeSource(url, title, snippet, publishedAt) {
33
+ const link = str(url);
34
+ if (link === undefined || !/^https?:\/\//iu.test(link)) return null;
35
+ const clean = typeof snippet !== 'string' ? undefined : str(snippet.replace(/\s+/gu, ' '));
36
+ return {
37
+ url: link,
38
+ ...(str(title) === undefined ? {} : { title: str(title) }),
39
+ ...(clean === undefined ? {} : { snippet: clean.length <= SNIPPET_MAX ? clean : `${clean.slice(0, SNIPPET_MAX - 1)}…` }),
40
+ ...(str(publishedAt) === undefined ? {} : { publishedAt: str(publishedAt) }),
41
+ };
42
+ }
43
+
44
+ export function dedupeSources(list) {
45
+ const seen = new Set();
46
+ const out = [];
47
+ for (const item of list) {
48
+ if (item === null || seen.has(item.url)) continue;
49
+ seen.add(item.url);
50
+ out.push(item);
51
+ }
52
+ return out;
53
+ }
54
+
55
+ // ---------------------------------------------------------------------------------------------------------------------
56
+ // HTTP
57
+
58
+ /** Up to BODY_PEEK_BYTES of an error body as text; the rest is cancelled unread, so a huge body costs no memory. */
59
+ async function peekBody(response) {
60
+ const reader = response.body?.getReader?.();
61
+ if (reader === undefined) return '';
62
+ const chunks = [];
63
+ let size = 0;
64
+ try {
65
+ while (size < BODY_PEEK_BYTES) {
66
+ const { done, value } = await reader.read();
67
+ if (done) break;
68
+ chunks.push(value);
69
+ size += value.byteLength;
70
+ }
71
+ } catch {
72
+ // An unreadable body classifies by status alone.
73
+ } finally {
74
+ reader.cancel().catch(() => {});
75
+ }
76
+ const bytes = new Uint8Array(Math.min(size, BODY_PEEK_BYTES));
77
+ let offset = 0;
78
+ for (const chunk of chunks) {
79
+ if (offset >= bytes.byteLength) break;
80
+ const part = chunk.subarray(0, bytes.byteLength - offset);
81
+ bytes.set(part, offset);
82
+ offset += part.byteLength;
83
+ }
84
+ return new TextDecoder().decode(bytes);
85
+ }
86
+
87
+ /** POST a JSON body; a non-2xx answer is a classified BackendFailure (its body is read only to classify, never shown). */
88
+ export async function postJson(fetchImpl, url, headers, body, signal) {
89
+ const response = await fetchImpl(url, {
90
+ method: 'POST',
91
+ redirect: 'error',
92
+ headers: { 'content-type': 'application/json', accept: 'application/json', 'user-agent': USER_AGENT, ...headers },
93
+ body: JSON.stringify(body),
94
+ ...(signal === undefined ? {} : { signal }),
95
+ });
96
+ if (!response.ok) {
97
+ const peek = await peekBody(response);
98
+ throw classifyHttp(response.status, peek, response.headers?.get?.('retry-after') ?? undefined);
99
+ }
100
+ try {
101
+ return await response.json();
102
+ } catch (error) {
103
+ if (signal?.aborted === true) throw error;
104
+ throw new BackendFailure('unreadable');
105
+ }
106
+ }
107
+
108
+ // ---------------------------------------------------------------------------------------------------------------------
109
+ // Anthropic Messages server-tool shape (Anthropic, and Prism which answers the same call itself)
110
+
111
+ function messagesError(code) {
112
+ switch (code) {
113
+ case 'too_many_requests':
114
+ return new BackendFailure('rate');
115
+ case 'unavailable':
116
+ return new BackendFailure('server');
117
+ case 'outcome_unknown':
118
+ return new BackendFailure('outcome-unknown');
119
+ default:
120
+ return new BackendFailure('rejected');
121
+ }
122
+ }
123
+
124
+ /** Sources of a Messages response: `web_search_tool_result` blocks, snippets from the text blocks' citations. */
125
+ export function parseMessagesSearch(json) {
126
+ const blocks = isRecord(json) && Array.isArray(json.content) ? json.content : [];
127
+ const results = blocks.filter((block) => isRecord(block) && block.type === 'web_search_tool_result');
128
+ if (results.length === 0) throw new BackendFailure('empty');
129
+ const snippets = new Map();
130
+ for (const block of blocks) {
131
+ if (!isRecord(block) || block.type !== 'text' || !Array.isArray(block.citations)) continue;
132
+ for (const cite of block.citations) {
133
+ if (isRecord(cite) && str(cite.url) !== undefined && str(cite.cited_text) !== undefined && !snippets.has(cite.url)) snippets.set(cite.url, cite.cited_text);
134
+ }
135
+ }
136
+ const found = [];
137
+ for (const block of results) {
138
+ const content = block.content;
139
+ if (isRecord(content) && content.type === 'web_search_tool_result_error') throw messagesError(content.error_code);
140
+ if (!Array.isArray(content)) continue;
141
+ for (const item of content) {
142
+ if (isRecord(item) && item.type === 'web_search_result') found.push(normalizeSource(item.url, item.title, snippets.get(item.url), item.page_age));
143
+ }
144
+ }
145
+ return { sources: dedupeSources(found), truncated: false };
146
+ }
147
+
148
+ /** How many searches a Messages response ran: `usage.server_tool_use.web_search_requests`, else its result blocks. */
149
+ export function messagesSearchCount(json) {
150
+ const reported = isRecord(json) && isRecord(json.usage) && isRecord(json.usage.server_tool_use) ? Number(json.usage.server_tool_use.web_search_requests) : Number.NaN;
151
+ if (Number.isInteger(reported) && reported >= 1) return Math.min(reported, MESSAGES_MAX_USES);
152
+ const blocks = isRecord(json) && Array.isArray(json.content) ? json.content : [];
153
+ return Math.max(1, Math.min(MESSAGES_MAX_USES, blocks.filter((block) => isRecord(block) && block.type === 'web_search_tool_result').length));
154
+ }
155
+
156
+ export function messagesBody(model, query) {
157
+ return {
158
+ model,
159
+ max_tokens: MAX_TOKENS,
160
+ messages: [{ role: 'user', content: [{ type: 'text', text: prompt(query) }] }],
161
+ tools: [{ type: 'web_search_20250305', name: 'web_search', max_uses: MESSAGES_MAX_USES }],
162
+ };
163
+ }
164
+
165
+ /** The auth headers Prism takes on its Messages endpoint (the key both ways, as the gateway accepts either). */
166
+ export function prismHeaders(key) {
167
+ return { 'x-api-key': key, authorization: `Bearer ${key}` };
168
+ }
169
+
170
+ /**
171
+ * One Messages web search at `<base>/v1/messages` with `headers` (the key; `anthropic-version` is added). Returns
172
+ * `{ result, searches }`.
173
+ */
174
+ export async function messagesSearchRequest({ fetch: fetchImpl, base, headers, model, query, signal }) {
175
+ const json = await postJson(fetchImpl, `${base}/v1/messages`, { ...headers, 'anthropic-version': ANTHROPIC_VERSION }, messagesBody(model, query), signal);
176
+ return { result: parseMessagesSearch(json), searches: messagesSearchCount(json) };
177
+ }
178
+
179
+ // ---------------------------------------------------------------------------------------------------------------------
180
+ // OpenAI Responses
181
+
182
+ /** The sentence an annotation ends, as plain text: markdown links and bare citations removed. */
183
+ function sentenceBefore(text, index) {
184
+ const head = text.slice(0, Math.max(0, index));
185
+ const start = Math.max(head.lastIndexOf('. '), head.lastIndexOf('\n'), -1) + 1;
186
+ return head
187
+ .slice(start)
188
+ .replace(/\[([^\]]*)\]\([^)]*\)/gu, '$1')
189
+ .replace(/\(\s*\)/gu, '')
190
+ .replace(/^[\s.\-*•]+/u, '')
191
+ .trim();
192
+ }
193
+
194
+ export function parseOpenAiSearch(json) {
195
+ const output = isRecord(json) && Array.isArray(json.output) ? json.output : [];
196
+ if (!output.some((item) => isRecord(item) && item.type === 'web_search_call')) throw new BackendFailure('empty');
197
+ const found = [];
198
+ for (const item of output) {
199
+ if (!isRecord(item) || item.type !== 'message' || !Array.isArray(item.content)) continue;
200
+ for (const part of item.content) {
201
+ if (!isRecord(part) || part.type !== 'output_text' || !Array.isArray(part.annotations)) continue;
202
+ const text = typeof part.text === 'string' ? part.text : '';
203
+ for (const note of part.annotations) {
204
+ if (!isRecord(note) || note.type !== 'url_citation') continue;
205
+ const snippet = Number.isInteger(note.start_index) ? sentenceBefore(text, note.start_index) : '';
206
+ found.push(normalizeSource(note.url, note.title, snippet === '' ? undefined : snippet));
207
+ }
208
+ }
209
+ }
210
+ return { sources: dedupeSources(found), truncated: false };
211
+ }
212
+
213
+ export function openAiSearchBody(model, query) {
214
+ return { model, input: prompt(query), tools: [{ type: 'web_search' }], tool_choice: 'required', store: false };
215
+ }
216
+
217
+ // ---------------------------------------------------------------------------------------------------------------------
218
+ // MiniMax coding-plan search
219
+
220
+ /** `{ organic: [{ title, link, snippet, date }], base_resp: { status_code } }`; a non-zero status is a failure. */
221
+ export function parseMiniMaxSearch(json) {
222
+ const status = isRecord(json) && isRecord(json.base_resp) ? Number(json.base_resp.status_code ?? 0) : 0;
223
+ if (status === 1002) throw new BackendFailure('rate');
224
+ if (status === 1004) throw new BackendFailure('auth');
225
+ if (status === 1008 || status === 2056) throw new BackendFailure('billing');
226
+ if (status !== 0) throw new BackendFailure('rejected');
227
+ const organic = isRecord(json) && Array.isArray(json.organic) ? json.organic : undefined;
228
+ if (organic === undefined) throw new BackendFailure('empty');
229
+ const found = organic.map((item) => (isRecord(item) ? normalizeSource(item.link, item.title, typeof item.snippet === 'string' ? item.snippet : undefined, item.date) : null));
230
+ return { sources: dedupeSources(found), truncated: false };
231
+ }
232
+
233
+ /** One MiniMax coding-plan search at `<origin>/v1/coding_plan/search`. Returns `{ result }`. */
234
+ export async function minimaxSearchRequest({ fetch: fetchImpl, origin, key, query, signal }) {
235
+ const headers = { authorization: `Bearer ${key}`, 'MM-API-Source': 'Picasso' };
236
+ return { result: parseMiniMaxSearch(await postJson(fetchImpl, `${origin}${MINIMAX_SEARCH_PATH}`, headers, { q: query }, signal)) };
237
+ }
238
+
239
+ // ---------------------------------------------------------------------------------------------------------------------
240
+ // Gemini grounding
241
+
242
+ export function parseGeminiSearch(json) {
243
+ const candidates = isRecord(json) && Array.isArray(json.candidates) ? json.candidates : [];
244
+ const grounding = candidates.map((candidate) => (isRecord(candidate) ? candidate.groundingMetadata : undefined)).find(isRecord);
245
+ if (grounding === undefined) throw new BackendFailure('empty');
246
+ const chunks = Array.isArray(grounding.groundingChunks) ? grounding.groundingChunks : [];
247
+ const snippets = new Map();
248
+ for (const support of Array.isArray(grounding.groundingSupports) ? grounding.groundingSupports : []) {
249
+ const segment = isRecord(support) && isRecord(support.segment) ? str(support.segment.text) : undefined;
250
+ if (segment === undefined || !Array.isArray(support.groundingChunkIndices)) continue;
251
+ for (const index of support.groundingChunkIndices) if (!snippets.has(index)) snippets.set(index, segment);
252
+ }
253
+ const found = chunks.map((chunk, index) => (isRecord(chunk) && isRecord(chunk.web) ? normalizeSource(chunk.web.uri, chunk.web.title, snippets.get(index)) : null));
254
+ return { sources: dedupeSources(found), truncated: false };
255
+ }
256
+
257
+ /** The grounded call's meter: search queries Google ran (at least one) and the tokens of the model call. */
258
+ export function geminiSearchMeter(json) {
259
+ const candidates = isRecord(json) && Array.isArray(json.candidates) ? json.candidates : [];
260
+ const grounding = candidates.map((candidate) => (isRecord(candidate) ? candidate.groundingMetadata : undefined)).find(isRecord);
261
+ const queries = grounding !== undefined && Array.isArray(grounding.webSearchQueries) ? grounding.webSearchQueries.filter((query) => typeof query === 'string').length : 0;
262
+ const usage = isRecord(json) && isRecord(json.usageMetadata) ? json.usageMetadata : {};
263
+ const count = (value) => (Number.isFinite(Number(value)) && Number(value) > 0 ? Math.floor(Number(value)) : 0);
264
+ return {
265
+ searchQueries: Math.max(1, queries),
266
+ inputTokens: count(usage.promptTokenCount),
267
+ // Thinking tokens are billed as output.
268
+ outputTokens: count(usage.candidatesTokenCount) + count(usage.thoughtsTokenCount),
269
+ };
270
+ }
271
+
272
+ export function geminiSearchBody(query) {
273
+ return { contents: [{ role: 'user', parts: [{ text: prompt(query) }] }], tools: [{ google_search: {} }] };
274
+ }
275
+
276
+ /**
277
+ * One grounded Gemini search at `<base>/models/<model>:generateContent` (`base` ends in the API version, e.g.
278
+ * `https://generativelanguage.googleapis.com/v1beta`), redirect links resolved. Returns `{ result, searchQueries,
279
+ * inputTokens, outputTokens }`.
280
+ */
281
+ export async function geminiSearchRequest({ fetch: fetchImpl, base, key, model, query, signal }) {
282
+ const id = encodeURIComponent(String(model).replace(/^models\//u, ''));
283
+ const json = await postJson(fetchImpl, `${base}/models/${id}:generateContent`, { 'x-goog-api-key': key }, geminiSearchBody(query), signal);
284
+ const parsed = parseGeminiSearch(json);
285
+ const result = { ...parsed, sources: await resolveGroundingRedirects(parsed.sources, fetchImpl, signal) };
286
+ return { result, ...geminiSearchMeter(json) };
287
+ }
288
+
289
+ /** Gemini grounding hands out links of its own redirector instead of the page; only these are ever resolved. */
290
+ const GROUNDING_REDIRECT_HOST = 'vertexaisearch.cloud.google.com';
291
+ const GROUNDING_REDIRECT_PATH = '/grounding-api-redirect/';
292
+ export const GROUNDING_RESOLVE_MAX = 10;
293
+ export const GROUNDING_RESOLVE_TIMEOUT_MS = 3000;
294
+
295
+ export function isGroundingRedirect(link) {
296
+ try {
297
+ const url = new URL(link);
298
+ return url.protocol === 'https:' && url.hostname === GROUNDING_REDIRECT_HOST && url.pathname.startsWith(GROUNDING_REDIRECT_PATH);
299
+ } catch {
300
+ return false;
301
+ }
302
+ }
303
+
304
+ /** The page one redirect link points at: the `Location` of a single unfollowed hop, sent with no key, cookie or body. */
305
+ async function groundingTarget(fetchImpl, link, signal) {
306
+ try {
307
+ const response = await fetchImpl(link, { method: 'GET', redirect: 'manual', credentials: 'omit', headers: { 'user-agent': USER_AGENT }, signal });
308
+ response.body?.cancel?.().catch(() => {});
309
+ if (response.status < 300 || response.status >= 400) return undefined;
310
+ const location = str(response.headers?.get?.('location'));
311
+ if (location === undefined) return undefined;
312
+ const target = new URL(location);
313
+ if ((target.protocol !== 'https:' && target.protocol !== 'http:') || target.username !== '' || target.password !== '') return undefined;
314
+ if (isGroundingRedirect(target.href)) return undefined;
315
+ return target.href;
316
+ } catch {
317
+ return undefined;
318
+ }
319
+ }
320
+
321
+ /**
322
+ * Sources with Gemini's redirect links replaced by the pages they point at. Bounded: the first GROUNDING_RESOLVE_MAX
323
+ * redirect links, at once, under one time limit; the target page itself is never requested. A link that does not
324
+ * resolve (refused, slow, no `Location`) stays as the redirect link, which still opens the page.
325
+ */
326
+ export async function resolveGroundingRedirects(sources, fetchImpl, signal, timeoutMs = GROUNDING_RESOLVE_TIMEOUT_MS) {
327
+ const links = [...new Set(sources.map((item) => item.url).filter(isGroundingRedirect))].slice(0, GROUNDING_RESOLVE_MAX);
328
+ if (links.length === 0 || signal?.aborted === true) return sources;
329
+ const limit = AbortSignal.timeout(timeoutMs);
330
+ const combined = signal === undefined ? limit : AbortSignal.any([signal, limit]);
331
+ const targets = new Map();
332
+ await Promise.all(
333
+ links.map(async (link) => {
334
+ const target = await groundingTarget(fetchImpl, link, combined);
335
+ if (target !== undefined) targets.set(link, target);
336
+ }),
337
+ );
338
+ return dedupeSources(sources.map((item) => (targets.has(item.url) ? { ...item, url: targets.get(item.url) } : item)));
339
+ }
@@ -1,15 +1,18 @@
1
1
  // One search, in a fixed order:
2
2
  //
3
- // 1. NATIVE the route the thread runs on (NATIVE_ROUTES), with that route's own credentials. A route with no
3
+ // 1. NATIVE the route the thread runs on (nativeBackendFor: NATIVE_ROUTES, minimax-* routes and Picasso's managed
4
+ // route), with that route's own credentials. A route with no
4
5
  // native search (a gateway, an OpenAI-compatible host, ...) has no first step.
5
- // 2. FALLBACKS the configured list, in order (config.js). A fallback whose endpoint or key is absent is left out
6
- // silently, so a Mac without the owner's Prism service never sees it.
6
+ // 2. FALLBACKS the list, in order (config.js): the one written in the settings or the environment, else the
7
+ // search-capable providers already connected (AUTO_FALLBACKS). A fallback whose endpoint or key is
8
+ // absent is left out silently, so a Mac without the owner's Prism service never sees it. A fallback
9
+ // that would borrow a disconnected route's key (FALLBACK_ROUTES) is never tried.
7
10
  // 3. FAILURE every backend failed: one structured error naming each backend and why, telling the model web search
8
11
  // is unavailable and not to substitute scraping from the shell (zero fallback: a failure is reported).
9
12
  //
10
13
  // Billing and authorisation errors (402/401/403 and "insufficient balance" bodies) mark the backend dead for the rest of
11
14
  // the session; 429/5xx get one bounded retry that honours Retry-After; everything else is tried once.
12
- import { NATIVE_ROUTES } from './backends.js';
15
+ import { fallbackDisconnected, nativeBackendFor } from './backends.js';
13
16
  import { BackendFailure } from './failure.js';
14
17
  import { formatBackendMarker, formatUnavailable } from './format.js';
15
18
 
@@ -93,12 +96,12 @@ export function createRouter({ ctx, readConfig, backends, sleep = defaultSleep,
93
96
  }
94
97
 
95
98
  async function plan(config, route, model) {
96
- const nativeId = NATIVE_ROUTES[route];
99
+ const nativeId = nativeBackendFor(route);
97
100
  const base = { config, route, model };
98
101
  const steps = [];
99
102
  if (nativeId !== undefined) steps.push({ id: nativeId, role: 'native' });
100
103
  for (const id of config.fallbacks) {
101
- if (id === nativeId) continue;
104
+ if (id === nativeId || fallbackDisconnected(id, config.disconnected)) continue;
102
105
  if (backends[id] !== undefined && (await backends[id].configured({ ...base, role: 'fallback' }))) steps.push({ id, role: 'fallback' });
103
106
  }
104
107
  return steps;
@@ -121,8 +124,9 @@ export function createRouter({ ctx, readConfig, backends, sleep = defaultSleep,
121
124
  continue;
122
125
  }
123
126
  if (step.role === 'native' && !(await backend.configured(call))) {
124
- const ref = await backend.keyRef?.(call);
125
- attempts.push({ name: backend.name, reason: new BackendFailure('credentials', { ref }).reason });
127
+ const unconfigured = backend.unconfigured?.(call);
128
+ const ref = unconfigured === undefined ? await backend.keyRef?.(call) : undefined;
129
+ attempts.push({ name: backend.name, reason: (unconfigured ?? new BackendFailure('credentials', { ref })).reason });
126
130
  continue;
127
131
  }
128
132
  try {
@@ -139,16 +143,17 @@ export function createRouter({ ctx, readConfig, backends, sleep = defaultSleep,
139
143
  },
140
144
 
141
145
  /**
142
- * Whether a search on `route` has anything to try: the route's native search has credentials, or a configured
143
- * fallback is active. Configuration only (no network, no per-session state). The seam's `ready` does NOT use this
146
+ * Whether a search on `route` has anything to try: the route's native search has credentials, or a fallback (listed
147
+ * or automatic) is active. Configuration only (no network, no per-session state). The seam's `ready` does NOT use this
144
148
  * (see index.js): the tool stays offered so a route with nothing configured gets the structured failure.
145
149
  */
146
150
  async configured(route) {
147
151
  const config = readConfig();
148
- const nativeId = NATIVE_ROUTES[route];
152
+ const nativeId = nativeBackendFor(route);
149
153
  if (nativeId !== undefined && (await backends[nativeId].configured({ config, route, role: 'native' }))) return true;
150
154
  for (const id of config.fallbacks) {
151
- if (id !== nativeId && backends[id] !== undefined && (await backends[id].configured({ config, route, role: 'fallback' }))) return true;
155
+ if (id === nativeId || fallbackDisconnected(id, config.disconnected)) continue;
156
+ if (backends[id] !== undefined && (await backends[id].configured({ config, route, role: 'fallback' }))) return true;
152
157
  }
153
158
  return false;
154
159
  },