@picassohq/cli 1.0.3 → 1.0.5

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 (64) hide show
  1. package/dist/build-info.json +2 -1
  2. package/dist/index.js +1860 -1316
  3. package/package.json +1 -1
  4. package/runtime/dsh/picasso-ecosystem.cordis.patch.yml +4 -7
  5. package/runtime/dsh/picasso-sdk.patch.yml +47 -0
  6. package/runtime/engine-manifest.json +37 -16
  7. package/runtime/packages/picasso-compaction/cordis.patch.yml +4 -0
  8. package/runtime/packages/picasso-compaction/index.js +875 -0
  9. package/runtime/packages/picasso-compaction/package.json +27 -0
  10. package/runtime/packages/picasso-hooks/cordis.patch.yml +4 -0
  11. package/runtime/packages/picasso-hooks/index.js +302 -0
  12. package/runtime/packages/picasso-hooks/lifecycle-events.js +651 -0
  13. package/runtime/packages/picasso-hooks/package.json +29 -0
  14. package/runtime/packages/picasso-lean-context/argument-repair.js +422 -0
  15. package/runtime/packages/picasso-lean-context/glob-walk.js +518 -0
  16. package/runtime/packages/picasso-lean-context/index.js +159 -11
  17. package/runtime/packages/picasso-memory/index.js +66 -24
  18. package/runtime/packages/picasso-model-router/connections.js +213 -10
  19. package/runtime/packages/picasso-model-router/index.js +128 -1
  20. package/runtime/packages/picasso-model-router/package.json +3 -1
  21. package/runtime/packages/picasso-model-router/thinking-default.js +236 -0
  22. package/runtime/packages/picasso-progress-reports/index.js +128 -18
  23. package/runtime/packages/picasso-sdk-server/command-runs.js +37 -0
  24. package/runtime/packages/picasso-sdk-server/ignore-file.js +5 -1
  25. package/runtime/packages/picasso-sdk-server/index.js +11 -3
  26. package/runtime/packages/picasso-sdk-server/package.json +1 -0
  27. package/runtime/packages/picasso-sdk-server/wave2-hooks.js +26 -6
  28. package/runtime/packages/picasso-web-search/backends.js +245 -195
  29. package/runtime/packages/picasso-web-search/config.js +75 -27
  30. package/runtime/packages/picasso-web-search/cordis.patch.yml +2 -1
  31. package/runtime/packages/picasso-web-search/failure.js +7 -1
  32. package/runtime/packages/picasso-web-search/index.js +7 -5
  33. package/runtime/packages/picasso-web-search/package.json +6 -0
  34. package/runtime/packages/picasso-web-search/requests.js +339 -0
  35. package/runtime/packages/picasso-web-search/router.js +17 -12
  36. package/runtime/packages/picasso-x-reader/settings.js +4 -1
  37. package/runtime/plugins/picasso-auto-approve/index.js +21 -8
  38. package/runtime/plugins/picasso-compaction/index.js +875 -0
  39. package/runtime/plugins/picasso-compaction/package.json +27 -0
  40. package/runtime/plugins/picasso-hooks/index.js +302 -0
  41. package/runtime/plugins/picasso-hooks/lifecycle-events.js +651 -0
  42. package/runtime/plugins/picasso-hooks/package.json +29 -0
  43. package/runtime/plugins/picasso-lean-context/argument-repair.js +422 -0
  44. package/runtime/plugins/picasso-lean-context/glob-walk.js +518 -0
  45. package/runtime/plugins/picasso-lean-context/index.js +159 -11
  46. package/runtime/plugins/picasso-memory/index.js +66 -24
  47. package/runtime/plugins/picasso-model-router/connections.js +213 -10
  48. package/runtime/plugins/picasso-model-router/index.js +128 -1
  49. package/runtime/plugins/picasso-model-router/package.json +3 -1
  50. package/runtime/plugins/picasso-model-router/thinking-default.js +236 -0
  51. package/runtime/plugins/picasso-progress-reports/index.js +128 -18
  52. package/runtime/plugins/picasso-provider-models/index.js +236 -4
  53. package/runtime/plugins/picasso-trackers/index.js +12 -2
  54. package/runtime/plugins/picasso-web-search/backends.js +245 -195
  55. package/runtime/plugins/picasso-web-search/config.js +75 -27
  56. package/runtime/plugins/picasso-web-search/failure.js +7 -1
  57. package/runtime/plugins/picasso-web-search/index.js +7 -5
  58. package/runtime/plugins/picasso-web-search/package.json +6 -0
  59. package/runtime/plugins/picasso-web-search/requests.js +339 -0
  60. package/runtime/plugins/picasso-web-search/router.js +17 -12
  61. package/runtime/plugins/picasso-x-reader/settings.js +4 -1
  62. package/runtime/relay/main.mjs +3877 -1989
  63. package/runtime/relay/model-listing.mjs +337 -26
  64. package/runtime/relay/versions-routes.mjs +86 -20
@@ -1,7 +1,7 @@
1
1
  // @picasso/model-router — ordered model connections with automatic fallback.
2
2
  //
3
3
  // A "connection" is one configured provider route the engine can reach (an API key, a gateway, a coding plan, a
4
- // subscription, or Picasso's free managed route). The user orders them; when a request fails because of quota, a
4
+ // subscription, or Picasso's managed route). The user orders them; when a request fails because of quota, a
5
5
  // 429, out-of-credit/billing, an expired or refused key (401/403) or a provider outage, the next turn or step moves
6
6
  // to the next connection in that order that serves the same model (or an equivalent configured one).
7
7
  //
@@ -43,8 +43,11 @@ export const ENV_COOLDOWN_MS = 'PICASSO_CONNECTION_COOLDOWN_MS';
43
43
  * ("retry in about a minute"); the engine's own retries are spent in ~15 s, so a turn on a busy shared org used to end.
44
44
  */
45
45
  export const DEFAULT_RATE_LIMIT_WAIT_MS = 60_000;
46
- /** The most rate-limit waits one failing step makes before the failure ends the turn. */
47
- export const MAX_RATE_LIMIT_WAITS_PER_STEP = 3;
46
+ /**
47
+ * The most rate-limit waits one failing step makes before the failure ends the turn (was 3: a busy shared org ended long
48
+ * turns after ~3 min). Each wait is shown as a note and stopping the turn ends it at once.
49
+ */
50
+ export const MAX_RATE_LIMIT_WAITS_PER_STEP = 10;
48
51
  /** A provider's own wait hint shorter than this still waits this long (the engine already spent its quick retries). */
49
52
  export const MIN_RATE_LIMIT_WAIT_MS = 10_000;
50
53
  /**
@@ -52,6 +55,43 @@ export const MIN_RATE_LIMIT_WAIT_MS = 10_000;
52
55
  * surfaced to the person instead of holding the turn silently.
53
56
  */
54
57
  export const MAX_RATE_LIMIT_WAIT_MS = 5 * 60_000;
58
+ /**
59
+ * A managed (Picasso) route that drops a connection or answers 502/503/504 (a deploy switching revisions, a reset) is
60
+ * retried with backoff for up to this long before it is called unavailable and any fallback is considered.
61
+ */
62
+ export const MANAGED_RETRY_BUDGET_MS = 30_000;
63
+ /** The waits between those retries (the last one repeats), each capped by what is left of the budget. */
64
+ export const MANAGED_RETRY_BACKOFF_MS = Object.freeze([1_000, 2_000, 4_000, 8_000, 15_000]);
65
+ /** Test/dev override of the budget (`PICASSO_MANAGED_RETRY_BUDGET_MS`; `0` turns the retries off). */
66
+ export const ENV_MANAGED_RETRY_BUDGET_MS = 'PICASSO_MANAGED_RETRY_BUDGET_MS';
67
+ /**
68
+ * The connection to Picasso dropped under a managed call (a deploy retired the replica mid-stream, a reset, the local
69
+ * proxy could not reach the API): the managed transport's failure says `managed_stream_interrupted` (or
70
+ * `managed_stream_incomplete` for a clean close before the answer finished). The step is sent again — the engine has
71
+ * already discarded the failed attempt, partial text included, so a half answer is never kept — under the same request
72
+ * id (the transport reuses it), so the server bills the call once. At most MANAGED_DROP_RETRIES retries per step.
73
+ */
74
+ export const MANAGED_DROP_RETRIES = 3;
75
+ /** The waits before those retries. */
76
+ export const MANAGED_DROP_BACKOFF_MS = Object.freeze([1_000, 3_000, 9_000]);
77
+ /** The one quiet line shown while a dropped managed call is retried. */
78
+ export const MANAGED_DROP_NOTE = 'connection to Picasso dropped — retrying';
79
+ const MANAGED_DROP_WORDING = /managed_stream_interrupted|managed_stream_incomplete/u;
80
+
81
+ /** True when an engine failure is a dropped connection to Picasso (see {@link MANAGED_DROP_RETRIES}). */
82
+ export function isManagedConnectionDrop(failure) {
83
+ const message = typeof failure?.message === 'string' ? failure.message : '';
84
+ const serverError = typeof failure?.details?.serverError === 'string' ? failure.details.serverError : '';
85
+ return MANAGED_DROP_WORDING.test(`${message} ${serverError}`);
86
+ }
87
+
88
+ export function managedRetryBudgetMs(env = process.env) {
89
+ const value = Number(env[ENV_MANAGED_RETRY_BUDGET_MS]);
90
+ return env[ENV_MANAGED_RETRY_BUDGET_MS] !== undefined && Number.isFinite(value) && value >= 0 ? value : MANAGED_RETRY_BUDGET_MS;
91
+ }
92
+
93
+ /** Managed refusals that answer the same way however often they are retried (never waited out). */
94
+ const DETERMINISTIC_MANAGED_REFUSAL = /secret_exposure_blocked|secret_read_denied|daily_limit|access_blocked|scope_forbidden|not_allowed|policy_required|allowance_required|budget_exceeded|account_suspended/u;
55
95
  /** Sessions whose wait counters are kept (a subagent is a session of its own); the oldest are dropped past this. */
56
96
  const MAX_TRACKED_SESSIONS = 256;
57
97
  /** Test/dev override of the wait (`PICASSO_RATE_LIMIT_WAIT_MS`). */
@@ -201,8 +241,9 @@ const LABELS = {
201
241
  'github-copilot': 'GitHub Copilot',
202
242
  'openai-codex': 'ChatGPT subscription',
203
243
  'anthropic-subscription': 'Claude subscription',
204
- 'picasso-managed': 'Picasso free',
205
- 'picasso-free': 'Picasso free',
244
+ // The pickers name the managed group "Picasso"; so do the connection list and every switch/retry note.
245
+ 'picasso-managed': 'Picasso',
246
+ 'picasso-free': 'Picasso',
206
247
  ollama: 'Ollama',
207
248
  vllm: 'vLLM',
208
249
  lmstudio: 'LM Studio',
@@ -212,7 +253,7 @@ const GATEWAYS = new Set(['openrouter', 'kiro-prism', 'prism', 'together', 'fire
212
253
  const SUBSCRIPTIONS = new Set(['github-copilot', 'openai-codex', 'anthropic-subscription', 'google-gemini-cli', 'google-antigravity']);
213
254
  const LOCAL = new Set(['ollama', 'vllm', 'lmstudio', 'llamacpp']);
214
255
 
215
- /** Is this route Picasso's free managed route? */
256
+ /** Is this route Picasso's managed route? */
216
257
  export function isManagedRoute(id) {
217
258
  return id === 'picasso-managed' || id === 'picasso-free';
218
259
  }
@@ -281,6 +322,8 @@ const SPENT_QUOTA_WORDING = /\bper[\s_-]?day\b|\bdaily\b|\binsufficient\b|\bbala
281
322
  const SHORT_QUOTA_WINDOW_MS = 2 * 60_000;
282
323
  const OUTAGE_CODES = new Set(['SERVER', 'TIMEOUT', 'TRANSPORT', 'EMPTY_RESPONSE']);
283
324
  const AUTH_CODES = new Set(['AUTH', 'INVALID_CREDENTIAL', 'MISSING_CREDENTIAL']);
325
+ /** A dropped or refused connection, a gateway with no healthy revision behind it (a deploy's revision switch). */
326
+ const TRANSPORT_WORDING = /\b(?:ECONNRESET|ECONNREFUSED|EPIPE|ETIMEDOUT|EAI_AGAIN|UND_ERR_SOCKET|socket hang up|fetch failed|other side closed|no healthy upstream|upstream connect error|gateway time-?out)\b/i;
284
327
 
285
328
  /**
286
329
  * Classify one engine `LlmFailure` (or an `llm/retry` event's `failure`/`error`).
@@ -314,7 +357,7 @@ export function classifyFailure(failure) {
314
357
  return out('auth', true, false, code === 'MISSING_CREDENTIAL' ? 'is missing' : 'expired or was refused');
315
358
  }
316
359
  if (code === 'RATE_LIMIT' || status === 429 || /\b429\b|rate[\s_-]?limit/i.test(message)) return out('rate-limit', true, true, 'is rate limited');
317
- if (OUTAGE_CODES.has(code) || (status !== undefined && status >= 500) || /\b(?:overloaded(?:_error)?|service unavailable|bad gateway)\b/i.test(message)) {
360
+ if (OUTAGE_CODES.has(code) || (status !== undefined && status >= 500) || /\b(?:overloaded(?:_error)?|service unavailable|bad gateway)\b/i.test(message) || TRANSPORT_WORDING.test(message)) {
318
361
  return out('outage', true, true, 'is unavailable');
319
362
  }
320
363
  if (code === 'PI_AI_ERROR' && /\b(?:401|403)\b/u.test(message)) return out('auth', true, false, 'expired or was refused');
@@ -328,13 +371,29 @@ export function reasonPhrase(label, classified) {
328
371
  return `${subject} ${classified.reason}`;
329
372
  }
330
373
 
374
+ /** A provider's own wording for a key it does not recognise ("Invalid API Key", `invalid_key`, "Incorrect API key"). */
375
+ const INVALID_KEY_WORDING = /\b(?:invalid|incorrect|unrecogni[sz]ed|malformed)[\s_-]*(?:api[\s_-]*)?key\b|\binvalid_api_key\b|\bapi[\s_-]*key[\s_-]*(?:is[\s_-]*)?(?:invalid|not[\s_-]*valid|incorrect)\b/iu;
376
+
377
+ /** The HTTP status of a failure: its `status`, else the one the adapter's message starts with ("401: {…}"). */
378
+ export function failureStatus(failure) {
379
+ if (Number.isInteger(failure?.status)) return failure.status;
380
+ const lead = Number(/^\s*([1-5]\d{2})\s*:/u.exec(typeof failure?.message === 'string' ? failure.message : '')?.[1]);
381
+ return Number.isInteger(lead) ? lead : undefined;
382
+ }
383
+
331
384
  /** A short human reason for a probe failure ("Rate limited (429)"). */
332
385
  export function probeReason(classified, failure) {
333
- const status = Number.isInteger(failure?.status) ? ` (${failure.status})` : '';
386
+ // The engine's adapter reports a provider refusal as `{code: 'AUTH', message: '401: {…}'}` with no `status` field.
387
+ const message = typeof failure?.message === 'string' ? failure.message : '';
388
+ const code = failureStatus(failure);
389
+ const status = code === undefined ? '' : ` (${code})`;
334
390
  switch (classified.kind) {
335
391
  case 'quota': return `Hit its usage limit${status}`;
336
392
  case 'billing': return `Out of credit${status}`;
337
- case 'auth': return failure?.code === 'MISSING_CREDENTIAL' ? 'No key configured' : `Key expired or not allowed${status}`;
393
+ case 'auth':
394
+ if (failure?.code === 'MISSING_CREDENTIAL') return 'No key configured';
395
+ // The provider said the key itself is wrong (not expired, not a plan limit): say so, it is the user's to fix.
396
+ return INVALID_KEY_WORDING.test(message) ? `The provider rejected this key as invalid${status}` : `Key expired or not allowed${status}`;
338
397
  case 'rate-limit': return `Rate limited${status}`;
339
398
  case 'outage': return `Provider unavailable${status}`;
340
399
  default: return (typeof failure?.message === 'string' && failure.message ? failure.message.slice(0, 160) : 'Request failed') + status;
@@ -411,6 +470,18 @@ export function normalizeSettings(raw) {
411
470
  // The models each connection shows in the pickers (`{"<route>": ["<model>", …]}`; @picasso/shared-home
412
471
  // active-models.ts writes it, both surfaces read it). Kept through every save, never interpreted here.
413
472
  const active = normalizeActive(value.active);
473
+ // Routes the person disconnected (`picasso provider disconnect`, the Mac's Disconnect): their key still resolves (often
474
+ // from the shell environment other tools need), but they are never a connection, so never a fallback.
475
+ const routeIds = (raw) => {
476
+ const out = [];
477
+ for (const id of Array.isArray(raw) ? raw : []) {
478
+ if (nonEmpty(id) && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(id.trim()) && !out.includes(id.trim())) out.push(id.trim());
479
+ }
480
+ return out;
481
+ };
482
+ const disconnected = routeIds(value.disconnected);
483
+ // Routes whose environment-only key the person connected on purpose (kept through every save).
484
+ const connected = routeIds(value.connected);
414
485
  return {
415
486
  version: 1,
416
487
  policy,
@@ -421,6 +492,8 @@ export function normalizeSettings(raw) {
421
492
  ...(defaultEffort === undefined ? {} : { defaultEffort }),
422
493
  ...(modelPickScope === undefined ? {} : { modelPickScope }),
423
494
  ...(active === undefined ? {} : { active }),
495
+ ...(disconnected.length === 0 ? {} : { disconnected }),
496
+ ...(connected.length === 0 ? {} : { connected }),
424
497
  };
425
498
  }
426
499
 
@@ -509,6 +582,13 @@ export function moveId(order, id, where) {
509
582
  * @param {() => {policy, order, equivalents?}} deps.settings - live settings.
510
583
  * @param {() => Promise<{id: string, name?: string}[]>} deps.providers - the engine's provider routes.
511
584
  * @param {(id: string) => Promise<string[]>} deps.models - model ids a route serves (empty = not configured).
585
+ * @param {(id: string) => Promise<boolean>|boolean} [deps.envOnly] - whether a route's key comes only from the process
586
+ * environment (such a route is a connection only once the person connects it: settings `connected`).
587
+ * @param {(id: string) => Promise<'stored'|'env'|'none'>|'stored'|'env'|'none'} [deps.credential] - where a route's
588
+ * credential comes from: `stored` (a key or sign-in the person saved for Picasso, an inline key, a declared custom
589
+ * endpoint), `env` (only this process's environment, e.g. a `GH_TOKEN` exported for other tools) or `none`. A route
590
+ * with no credential is never a connection (a catalogue route such as GitHub Copilot the person never set up); an
591
+ * environment-only one only once the person connects it (settings `connected`). The managed route is exempt.
512
592
  * @param {(id: string) => Promise<string|undefined>|string|undefined} [deps.identity] - endpoint + key fingerprint of
513
593
  * a route; routes with the same fingerprint are one connection.
514
594
  * @param {(agent, selection, options?: {immediate?: boolean}) => Promise<object|undefined>} deps.install - install
@@ -520,6 +600,7 @@ export function moveId(order, id, where) {
520
600
  * picked option label, undefined when no answerer is available.
521
601
  * @param {(agent, event) => void} [deps.note] - append the quiet run note.
522
602
  * @param {() => number} [deps.now]
603
+ * @param {(ms: number, signal?: AbortSignal) => Promise<boolean>} [deps.sleep] - abortable wait (false: aborted).
523
604
  * @param {(line: string) => void} [deps.log]
524
605
  */
525
606
  export class ConnectionFallback {
@@ -537,6 +618,10 @@ export class ConnectionFallback {
537
618
  this.stepSwitches = new Map();
538
619
  /** Rate-limit waits per session for its current step: `{key: "<turn>:<step>", count}`. */
539
620
  this.rateWaits = new Map();
621
+ /** Managed transient retries per session for its current step: `{key: "<turn>:<step>", attempt, startedAt}`. */
622
+ this.managedRetries = new Map();
623
+ /** Dropped-connection retries per session for its current step: `{key: "<turn>:<step>", attempt}`. */
624
+ this.managedDrops = new Map();
540
625
  }
541
626
 
542
627
  /**
@@ -548,9 +633,34 @@ export class ConnectionFallback {
548
633
  async list() {
549
634
  const settings = this.deps.settings();
550
635
  const providers = await this.deps.providers();
636
+ const disconnected = new Set(Array.isArray(settings.disconnected) ? settings.disconnected : []);
637
+ const connected = new Set(Array.isArray(settings.connected) ? settings.connected : []);
551
638
  const rows = [];
552
639
  for (const provider of providers) {
553
640
  if (!nonEmpty(provider?.id)) continue;
641
+ // A disconnected route is not a connection: never listed, never a fallback. Nor is a route whose key was only
642
+ // found in the environment until the person connects it (`connected`).
643
+ if (disconnected.has(provider.id)) continue;
644
+ if (!connected.has(provider.id) && typeof this.deps.envOnly === 'function') {
645
+ let envOnly = false;
646
+ try {
647
+ envOnly = (await this.deps.envOnly(provider.id)) === true;
648
+ } catch {
649
+ envOnly = false;
650
+ }
651
+ if (envOnly) continue;
652
+ }
653
+ // Only a route the person set up is a connection: a catalogue route with no credential (GitHub Copilot when it
654
+ // was never signed in) or one whose key is only in this shell's environment (not connected) never is.
655
+ if (!isManagedRoute(provider.id) && typeof this.deps.credential === 'function') {
656
+ let source = 'none';
657
+ try {
658
+ source = (await this.deps.credential(provider.id)) ?? 'none';
659
+ } catch {
660
+ source = 'none';
661
+ }
662
+ if (source === 'none' || (source === 'env' && !connected.has(provider.id))) continue;
663
+ }
554
664
  let models = [];
555
665
  try {
556
666
  models = await this.deps.models(provider.id);
@@ -647,6 +757,11 @@ export class ConnectionFallback {
647
757
  async onRequestError(payload, next) {
648
758
  const agent = payload?.agent;
649
759
  const classified = classifyFailure(payload?.failure);
760
+ // A dropped connection to Picasso is retried first, for subagents too (they never switch connections, but the
761
+ // same managed route answers again as soon as the connection is back).
762
+ const drop = agent !== undefined && isManagedConnectionDrop(payload?.failure);
763
+ if (drop && (await this.retryDroppedManaged(agent, payload))) return { kind: 'retry' };
764
+ if (drop && payload?.signal?.aborted) return undefined;
650
765
  if (!classified.fallback || agent === undefined) return next();
651
766
  const stepKey = `${payload?.turn ?? '?'}:${payload?.step ?? '?'}`;
652
767
  if (isChildAgent(agent)) {
@@ -671,6 +786,11 @@ export class ConnectionFallback {
671
786
  if (downstream !== undefined && downstream !== null) return downstream;
672
787
  }
673
788
  if (payload?.signal?.aborted) return undefined;
789
+ // Picasso's managed route that dropped a connection or is between revisions: keep retrying it (one quiet line)
790
+ // for up to MANAGED_RETRY_BUDGET_MS before calling it unavailable or offering anything else.
791
+ // A dropped connection already had its retries above; it does not get the 30 s window as well.
792
+ if (classified.transient && !drop && (await this.retryManaged(agent, payload, classified, stepKey))) return { kind: 'retry' };
793
+ if (payload?.signal?.aborted) return undefined;
674
794
  try {
675
795
  const switched = await this.fallback(agent, payload, classified);
676
796
  if (switched) {
@@ -720,6 +840,88 @@ export class ConnectionFallback {
720
840
  return waited !== false && !payload?.signal?.aborted;
721
841
  }
722
842
 
843
+ /**
844
+ * A transient failure of the managed route (reset, refused, 502/503/504, a 429 whose `Retry-After` fits): wait with
845
+ * backoff ({@link MANAGED_RETRY_BACKOFF_MS}, honoring the provider's hint) and retry the step, for at most
846
+ * {@link managedRetryBudgetMs} per step. One plain note on the first wait; stopping the turn ends the wait at once.
847
+ * False when the route is not managed, the refusal is deterministic, or the budget is spent.
848
+ */
849
+ async retryManaged(agent, payload, classified, stepKey) {
850
+ if (payload?.signal?.aborted) return false;
851
+ const current = this.deps.current?.(agent) ?? {};
852
+ const fromId = nonEmpty(payload?.provider) ? payload.provider : current.provider;
853
+ if (!nonEmpty(fromId) || !isManagedRoute(fromId)) return false;
854
+ const message = typeof payload?.failure?.message === 'string' ? payload.failure.message : '';
855
+ const serverError = typeof payload?.failure?.details?.serverError === 'string' ? payload.failure.details.serverError : '';
856
+ if (DETERMINISTIC_MANAGED_REFUSAL.test(`${message} ${serverError}`)) return false;
857
+ const budget = managedRetryBudgetMs();
858
+ const sessionId = sessionIdOf(agent);
859
+ const now = this.now();
860
+ const seen = this.managedRetries.get(sessionId);
861
+ const state = seen?.key === stepKey ? seen : { key: stepKey, attempt: 0, startedAt: now };
862
+ const remaining = budget - (now - state.startedAt);
863
+ if (remaining <= 0) return false;
864
+ const backoff = MANAGED_RETRY_BACKOFF_MS[Math.min(state.attempt, MANAGED_RETRY_BACKOFF_MS.length - 1)];
865
+ const hinted = classified.retryAfterMs;
866
+ // A provider asking for longer than the whole window left is not waited out here.
867
+ if (hinted !== undefined && hinted > remaining) return false;
868
+ const ms = Math.min(remaining, Math.max(backoff, hinted ?? 0));
869
+ this.managedRetries.delete(sessionId);
870
+ this.managedRetries.set(sessionId, { ...state, attempt: state.attempt + 1 });
871
+ while (this.managedRetries.size > MAX_TRACKED_SESSIONS) this.managedRetries.delete(this.managedRetries.keys().next().value);
872
+ const label = connectionLabel(fromId);
873
+ if (state.attempt === 0) {
874
+ const seconds = Math.max(1, Math.round(budget / 1000));
875
+ this.deps.note?.(agent, {
876
+ type: SWITCH_EVENT,
877
+ direction: 'wait',
878
+ from: { id: fromId, label, ...(nonEmpty(current.model) ? { model: current.model } : {}) },
879
+ reason: classified.kind,
880
+ waitMs: ms,
881
+ attempt: 1,
882
+ note: `${label} is not answering · retrying for up to ${seconds} s`,
883
+ });
884
+ }
885
+ const sleep = this.deps.sleep ?? abortableSleep;
886
+ const waited = await sleep(ms, payload?.signal);
887
+ return waited !== false && !payload?.signal?.aborted;
888
+ }
889
+
890
+ /**
891
+ * A managed call whose connection to Picasso dropped: wait ({@link MANAGED_DROP_BACKOFF_MS}) and retry the step, at
892
+ * most {@link MANAGED_DROP_RETRIES} times per step, with one quiet line on the first retry. Stopping the turn ends
893
+ * the wait at once. False when the route is not managed or the retries are spent.
894
+ */
895
+ async retryDroppedManaged(agent, payload) {
896
+ if (payload?.signal?.aborted) return false;
897
+ const current = this.deps.current?.(agent) ?? {};
898
+ const fromId = nonEmpty(payload?.provider) ? payload.provider : current.provider;
899
+ if (!nonEmpty(fromId) || !isManagedRoute(fromId)) return false;
900
+ const sessionId = sessionIdOf(agent);
901
+ const stepKey = `${payload?.turn ?? '?'}:${payload?.step ?? '?'}`;
902
+ const seen = this.managedDrops.get(sessionId);
903
+ const attempt = seen?.key === stepKey ? seen.attempt : 0;
904
+ if (attempt >= MANAGED_DROP_RETRIES) return false;
905
+ this.managedDrops.delete(sessionId);
906
+ this.managedDrops.set(sessionId, { key: stepKey, attempt: attempt + 1 });
907
+ while (this.managedDrops.size > MAX_TRACKED_SESSIONS) this.managedDrops.delete(this.managedDrops.keys().next().value);
908
+ const ms = MANAGED_DROP_BACKOFF_MS[Math.min(attempt, MANAGED_DROP_BACKOFF_MS.length - 1)];
909
+ if (attempt === 0) {
910
+ this.deps.note?.(agent, {
911
+ type: SWITCH_EVENT,
912
+ direction: 'wait',
913
+ from: { id: fromId, label: connectionLabel(fromId), ...(nonEmpty(current.model) ? { model: current.model } : {}) },
914
+ reason: 'connection',
915
+ waitMs: ms,
916
+ attempt: 1,
917
+ note: MANAGED_DROP_NOTE,
918
+ });
919
+ }
920
+ const sleep = this.deps.sleep ?? abortableSleep;
921
+ const waited = await sleep(ms, payload?.signal);
922
+ return waited !== false && !payload?.signal?.aborted;
923
+ }
924
+
723
925
  async fallback(agent, payload, classified) {
724
926
  const current = this.deps.current(agent) ?? {};
725
927
  const fromId = nonEmpty(payload?.provider) ? payload.provider : current.provider;
@@ -823,6 +1025,7 @@ export class ConnectionFallback {
823
1025
  this.lastProbe.delete(sessionId);
824
1026
  this.stepSwitches.delete(sessionId);
825
1027
  this.rateWaits.delete(sessionId);
1028
+ this.managedRetries.delete(sessionId);
826
1029
  }
827
1030
 
828
1031
  /** `modelRouter/checkAccess {id, model?}` — one tiny probe request. */
@@ -858,7 +1061,7 @@ export class ConnectionFallback {
858
1061
  reason: probeReason(classified, failure),
859
1062
  kind: classified.kind,
860
1063
  ...(nonEmpty(failure.code) ? { code: failure.code } : {}),
861
- ...(Number.isInteger(failure.status) ? { status: failure.status } : {}),
1064
+ ...(failureStatus(failure) === undefined ? {} : { status: failureStatus(failure) }),
862
1065
  latencyMs,
863
1066
  };
864
1067
  }
@@ -57,7 +57,10 @@ import {
57
57
  writeSettings as writeConnectionSettings,
58
58
  } from './connections.js';
59
59
 
60
+ import { createThinkingGuard } from './thinking-default.js';
61
+
60
62
  export * from './connections.js';
63
+ export * from './thinking-default.js';
61
64
 
62
65
  export const name = 'picasso-model-router';
63
66
  export const dshTarget = '0.2.2-rc.3';
@@ -711,6 +714,94 @@ function storedCredentialRefs(home = process.env.DSH_HOME || join(homedir(), '.d
711
714
  return refs;
712
715
  }
713
716
 
717
+ /** Route ids of `records:` entries (`llm-pi-ai/<route>`, a stored sign-in such as a Copilot OAuth record) in `$DSH_HOME/.credentials.yaml`. */
718
+ function storedRecordRoutes(home = process.env.DSH_HOME || join(homedir(), '.dsh')) {
719
+ let text;
720
+ try {
721
+ text = readFileSync(join(home, '.credentials.yaml'), 'utf8');
722
+ } catch {
723
+ return new Set();
724
+ }
725
+ const routes = new Set();
726
+ let inRecords = false;
727
+ for (const line of text.split(/\r?\n/u)) {
728
+ if (/^records:\s*$/u.test(line)) { inRecords = true; continue; }
729
+ if (/^\S/u.test(line)) { inRecords = false; continue; }
730
+ if (!inRecords) continue;
731
+ const match = /^ {2}['"]?llm-pi-ai\/([a-z0-9][a-z0-9-]*)['"]?:/u.exec(line);
732
+ if (match) routes.add(match[1]);
733
+ }
734
+ return routes;
735
+ }
736
+
737
+ function existsSyncSafe(path) {
738
+ try {
739
+ return statSync(path).isFile();
740
+ } catch {
741
+ return false;
742
+ }
743
+ }
744
+
745
+ /** Names set in `$DSH_HOME/.env` (where `picasso provider set` saves a key), values never kept. */
746
+ function dotEnvNames(home = process.env.DSH_HOME || join(homedir(), '.dsh')) {
747
+ let text;
748
+ try {
749
+ text = readFileSync(join(home, '.env'), 'utf8');
750
+ } catch {
751
+ return new Set();
752
+ }
753
+ const names = new Set();
754
+ for (const line of text.split(/\r?\n/u)) {
755
+ const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(\S.*)$/u.exec(line);
756
+ if (match && !/^(['"])\1$/u.test(match[2].trim())) names.add(match[1]);
757
+ }
758
+ return names;
759
+ }
760
+
761
+ /**
762
+ * Ambient routes (declared with no `apiKeyEnv`): the environment alternatives pi-ai authenticates them from. GitHub
763
+ * Copilot also reads `GH_TOKEN` / `GITHUB_TOKEN`, which many shells export for git tooling: that alone never makes it
764
+ * a connection.
765
+ */
766
+ const AMBIENT_ROUTE_ENVS = Object.freeze({
767
+ 'amazon-bedrock': [['AWS_BEARER_TOKEN_BEDROCK'], ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY'], ['AWS_PROFILE']],
768
+ 'google-vertex': [['GOOGLE_CLOUD_API_KEY'], ['GOOGLE_APPLICATION_CREDENTIALS']],
769
+ 'github-copilot': [['COPILOT_GITHUB_TOKEN'], ['GH_TOKEN'], ['GITHUB_TOKEN']],
770
+ });
771
+ /** Sign-in-only subscription routes: a stored sign-in record is their only credential. */
772
+ const SIGN_IN_ROUTES = new Set(['openai-codex', 'anthropic-subscription', 'google-gemini-cli', 'google-antigravity']);
773
+ /** Native routes outside the pi-ai config and the key each reads. */
774
+ const NATIVE_ROUTE_REFS = Object.freeze({ 'deepseek-official': 'DEEPSEEK_API_KEY' });
775
+
776
+ /**
777
+ * Where a route's credential comes from (`deps.credential` of {@link ConnectionFallback}): `stored` — a key or sign-in
778
+ * saved for Picasso (`.credentials.yaml` refs or records, `$DSH_HOME/.env`), an inline key or a declared custom
779
+ * endpoint; `env` — only this process's environment; `none` — nothing (a catalogue route never set up); `unknown` —
780
+ * the engine's route config could not be read (`sources.configKnown === false`), so nothing is concluded.
781
+ */
782
+ export function routeCredentialSource(id, profile, sources) {
783
+ const { env = process.env, refs = {}, records = new Set(), dotEnv = new Set(), configKnown = true } = sources ?? {};
784
+ if (records.has(id)) return 'stored';
785
+ if (SIGN_IN_ROUTES.has(id)) return 'none';
786
+ const saved = (name) => Boolean(refs[name]) || dotEnv.has(name);
787
+ const inEnv = (name) => Boolean(env[name]);
788
+ const declared = isRecord(profile) ? profile : undefined;
789
+ if (declared !== undefined && typeof declared.apiKey === 'string' && declared.apiKey.length > 0) return 'stored';
790
+ const ref = declared !== undefined && typeof declared.apiKeyEnv === 'string' && declared.apiKeyEnv ? declared.apiKeyEnv : declared === undefined ? NATIVE_ROUTE_REFS[id] : undefined;
791
+ if (ref !== undefined) return saved(ref) ? 'stored' : inEnv(ref) ? 'env' : 'none';
792
+ const ambient = AMBIENT_ROUTE_ENVS[id];
793
+ if (ambient !== undefined) {
794
+ if (ambient.some((names) => names.every(saved))) return 'stored';
795
+ if (ambient.some((names) => names.every(inEnv))) return 'env';
796
+ // Vertex through this machine's Application Default Credentials (a machine sign-in, like an exported key).
797
+ return id === 'google-vertex' && sources?.adc === true ? 'env' : 'none';
798
+ }
799
+ if (!configKnown) return 'unknown';
800
+ // A route the person declared with its own endpoint and no key (a local server, an open gateway) is theirs.
801
+ if (declared !== undefined && typeof declared.baseURL === 'string' && declared.baseURL.trim().length > 0) return 'stored';
802
+ return 'none';
803
+ }
804
+
714
805
  export function apply(ctx, config = {}, deps = {}) {
715
806
  const policyFileCache = {};
716
807
  const log = deps.log ?? (typeof ctx.logger?.warn === 'function' ? (line) => ctx.logger.warn(line) : (line) => console.warn(line));
@@ -876,6 +967,7 @@ export function apply(ctx, config = {}, deps = {}) {
876
967
  const connectionInstalls = new Map();
877
968
  /** agent → the route object its current step was prepared with (`agent/pre-step` `modelSelection`). */
878
969
  const stepSelections = new WeakMap();
970
+ const thinkingGuard = createThinkingGuard({ llm: llmRegistry, settings: readConnections, log });
879
971
  /** session id → the last request route seen (`request/context`), the current-route backstop. */
880
972
  const lastRequestRoute = new Map();
881
973
  const appendRecord = deps.appendPluginRecord ?? (() => {
@@ -990,8 +1082,34 @@ export function apply(ctx, config = {}, deps = {}) {
990
1082
  return routeIdentity(profile, (ref) => process.env[ref] || storedCredentialRefs()[ref]);
991
1083
  });
992
1084
 
1085
+ /**
1086
+ * Whether a route's key comes only from this process's environment (not the engine home's stored credentials): such
1087
+ * a route serves only once the person connects it (`connected` in the shared settings; owner 2026-11-17).
1088
+ */
1089
+ const AMBIENT_ENVS = { 'amazon-bedrock': [['AWS_BEARER_TOKEN_BEDROCK'], ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY'], ['AWS_PROFILE']], 'google-vertex': [['GOOGLE_CLOUD_API_KEY'], ['GOOGLE_APPLICATION_CREDENTIALS']] };
1090
+ const routeEnvOnlyOf = deps.routeEnvOnly ?? ((id) => {
1091
+ const stored = storedCredentialRefs();
1092
+ const fromEnv = (names) => names.length > 0 && names.every((ref) => Boolean(process.env[ref]));
1093
+ const fromStore = (names) => names.length > 0 && names.every((ref) => Boolean(stored[ref]));
1094
+ const providers = llmPiAiProviders(ctx);
1095
+ const profile = isRecord(providers) ? providers[id] : undefined;
1096
+ const ref = isRecord(profile) && typeof profile.apiKeyEnv === 'string' && profile.apiKeyEnv ? profile.apiKeyEnv : undefined;
1097
+ if (ref !== undefined) return fromEnv([ref]) && !fromStore([ref]);
1098
+ const ambient = AMBIENT_ENVS[id];
1099
+ return ambient !== undefined && ambient.some(fromEnv) && !ambient.some(fromStore);
1100
+ });
1101
+
1102
+ /** Where a route's credential comes from: only routes the person set up are ever offered as a fallback. */
1103
+ const routeCredentialOf = deps.routeCredential ?? ((id) => {
1104
+ const providers = llmPiAiProviders(ctx);
1105
+ const profile = isRecord(providers) ? providers[id] : undefined;
1106
+ return routeCredentialSource(id, profile, { configKnown: isRecord(providers), env: process.env, refs: storedCredentialRefs(), records: storedRecordRoutes(), dotEnv: dotEnvNames(), adc: id === 'google-vertex' && existsSyncSafe(join(homedir(), '.config', 'gcloud', 'application_default_credentials.json')) });
1107
+ });
1108
+
993
1109
  const fallback = deps.connectionFallback ?? new ConnectionFallback({
994
1110
  settings: readConnections,
1111
+ envOnly: routeEnvOnlyOf,
1112
+ credential: routeCredentialOf,
995
1113
  identity: routeIdentityOf,
996
1114
  providers: async () => {
997
1115
  const registry = llmRegistry();
@@ -1065,7 +1183,16 @@ export function apply(ctx, config = {}, deps = {}) {
1065
1183
  } catch (error) {
1066
1184
  log(`${name}: moving back to the earlier connection skipped (${error instanceof Error ? error.message : String(error)}).`);
1067
1185
  }
1068
- return router.preStep(args, next);
1186
+ // After routing has fixed this step's model: a model that cannot run with thinking off gets a level
1187
+ // (thinking-default.js), whatever sent the request.
1188
+ return router.preStep(args, async () => {
1189
+ try {
1190
+ await thinkingGuard.apply(args?.modelSelection, args?.agent);
1191
+ } catch (error) {
1192
+ log(`${name}: the default thinking level was skipped (${error instanceof Error ? error.message : String(error)}).`);
1193
+ }
1194
+ return next();
1195
+ });
1069
1196
  }),
1070
1197
  ctx.on('agent/request-error', (payload, next) => fallback.onRequestError(payload, next)),
1071
1198
  ctx.on('session/disposed', (session) => {
@@ -9,7 +9,8 @@
9
9
  ".": "./index.js",
10
10
  "./cordis.patch.yml": "./cordis.patch.yml",
11
11
  "./package.json": "./package.json",
12
- "./connections.js": "./connections.js"
12
+ "./connections.js": "./connections.js",
13
+ "./thinking-default.js": "./thinking-default.js"
13
14
  },
14
15
  "dshTarget": "0.2.2-rc.3",
15
16
  "dsh": {
@@ -23,6 +24,7 @@
23
24
  "files": [
24
25
  "index.js",
25
26
  "connections.js",
27
+ "thinking-default.js",
26
28
  "cordis.patch.yml",
27
29
  "README.md"
28
30
  ],