@picassohq/cli 1.0.4 → 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 (40) hide show
  1. package/dist/build-info.json +2 -1
  2. package/dist/index.js +1557 -1353
  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 +20 -10
  7. package/runtime/packages/picasso-compaction/index.js +257 -5
  8. package/runtime/packages/picasso-hooks/cordis.patch.yml +4 -0
  9. package/runtime/packages/picasso-hooks/index.js +302 -0
  10. package/runtime/packages/picasso-hooks/lifecycle-events.js +651 -0
  11. package/runtime/packages/picasso-hooks/package.json +29 -0
  12. package/runtime/packages/picasso-lean-context/glob-walk.js +518 -0
  13. package/runtime/packages/picasso-lean-context/index.js +136 -9
  14. package/runtime/packages/picasso-memory/index.js +66 -24
  15. package/runtime/packages/picasso-model-router/connections.js +164 -7
  16. package/runtime/packages/picasso-model-router/index.js +97 -1
  17. package/runtime/packages/picasso-model-router/thinking-default.js +29 -5
  18. package/runtime/packages/picasso-progress-reports/index.js +128 -18
  19. package/runtime/packages/picasso-sdk-server/command-runs.js +37 -0
  20. package/runtime/packages/picasso-sdk-server/ignore-file.js +5 -1
  21. package/runtime/packages/picasso-sdk-server/index.js +11 -3
  22. package/runtime/packages/picasso-sdk-server/package.json +1 -0
  23. package/runtime/packages/picasso-sdk-server/wave2-hooks.js +26 -6
  24. package/runtime/packages/picasso-x-reader/settings.js +4 -1
  25. package/runtime/plugins/picasso-auto-approve/index.js +21 -8
  26. package/runtime/plugins/picasso-compaction/index.js +257 -5
  27. package/runtime/plugins/picasso-hooks/index.js +302 -0
  28. package/runtime/plugins/picasso-hooks/lifecycle-events.js +651 -0
  29. package/runtime/plugins/picasso-hooks/package.json +29 -0
  30. package/runtime/plugins/picasso-lean-context/glob-walk.js +518 -0
  31. package/runtime/plugins/picasso-lean-context/index.js +136 -9
  32. package/runtime/plugins/picasso-memory/index.js +66 -24
  33. package/runtime/plugins/picasso-model-router/connections.js +164 -7
  34. package/runtime/plugins/picasso-model-router/index.js +97 -1
  35. package/runtime/plugins/picasso-model-router/thinking-default.js +29 -5
  36. package/runtime/plugins/picasso-progress-reports/index.js +128 -18
  37. package/runtime/plugins/picasso-trackers/index.js +12 -2
  38. package/runtime/plugins/picasso-x-reader/settings.js +4 -1
  39. package/runtime/relay/main.mjs +2254 -1648
  40. package/runtime/relay/versions-routes.mjs +24 -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');
@@ -541,6 +584,11 @@ export function moveId(order, id, where) {
541
584
  * @param {(id: string) => Promise<string[]>} deps.models - model ids a route serves (empty = not configured).
542
585
  * @param {(id: string) => Promise<boolean>|boolean} [deps.envOnly] - whether a route's key comes only from the process
543
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.
544
592
  * @param {(id: string) => Promise<string|undefined>|string|undefined} [deps.identity] - endpoint + key fingerprint of
545
593
  * a route; routes with the same fingerprint are one connection.
546
594
  * @param {(agent, selection, options?: {immediate?: boolean}) => Promise<object|undefined>} deps.install - install
@@ -552,6 +600,7 @@ export function moveId(order, id, where) {
552
600
  * picked option label, undefined when no answerer is available.
553
601
  * @param {(agent, event) => void} [deps.note] - append the quiet run note.
554
602
  * @param {() => number} [deps.now]
603
+ * @param {(ms: number, signal?: AbortSignal) => Promise<boolean>} [deps.sleep] - abortable wait (false: aborted).
555
604
  * @param {(line: string) => void} [deps.log]
556
605
  */
557
606
  export class ConnectionFallback {
@@ -569,6 +618,10 @@ export class ConnectionFallback {
569
618
  this.stepSwitches = new Map();
570
619
  /** Rate-limit waits per session for its current step: `{key: "<turn>:<step>", count}`. */
571
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();
572
625
  }
573
626
 
574
627
  /**
@@ -597,6 +650,17 @@ export class ConnectionFallback {
597
650
  }
598
651
  if (envOnly) continue;
599
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
+ }
600
664
  let models = [];
601
665
  try {
602
666
  models = await this.deps.models(provider.id);
@@ -693,6 +757,11 @@ export class ConnectionFallback {
693
757
  async onRequestError(payload, next) {
694
758
  const agent = payload?.agent;
695
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;
696
765
  if (!classified.fallback || agent === undefined) return next();
697
766
  const stepKey = `${payload?.turn ?? '?'}:${payload?.step ?? '?'}`;
698
767
  if (isChildAgent(agent)) {
@@ -717,6 +786,11 @@ export class ConnectionFallback {
717
786
  if (downstream !== undefined && downstream !== null) return downstream;
718
787
  }
719
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;
720
794
  try {
721
795
  const switched = await this.fallback(agent, payload, classified);
722
796
  if (switched) {
@@ -766,6 +840,88 @@ export class ConnectionFallback {
766
840
  return waited !== false && !payload?.signal?.aborted;
767
841
  }
768
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
+
769
925
  async fallback(agent, payload, classified) {
770
926
  const current = this.deps.current(agent) ?? {};
771
927
  const fromId = nonEmpty(payload?.provider) ? payload.provider : current.provider;
@@ -869,6 +1025,7 @@ export class ConnectionFallback {
869
1025
  this.lastProbe.delete(sessionId);
870
1026
  this.stepSwitches.delete(sessionId);
871
1027
  this.rateWaits.delete(sessionId);
1028
+ this.managedRetries.delete(sessionId);
872
1029
  }
873
1030
 
874
1031
  /** `modelRouter/checkAccess {id, model?}` — one tiny probe request. */
@@ -714,6 +714,94 @@ function storedCredentialRefs(home = process.env.DSH_HOME || join(homedir(), '.d
714
714
  return refs;
715
715
  }
716
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
+
717
805
  export function apply(ctx, config = {}, deps = {}) {
718
806
  const policyFileCache = {};
719
807
  const log = deps.log ?? (typeof ctx.logger?.warn === 'function' ? (line) => ctx.logger.warn(line) : (line) => console.warn(line));
@@ -1011,9 +1099,17 @@ export function apply(ctx, config = {}, deps = {}) {
1011
1099
  return ambient !== undefined && ambient.some(fromEnv) && !ambient.some(fromStore);
1012
1100
  });
1013
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
+
1014
1109
  const fallback = deps.connectionFallback ?? new ConnectionFallback({
1015
1110
  settings: readConnections,
1016
1111
  envOnly: routeEnvOnlyOf,
1112
+ credential: routeCredentialOf,
1017
1113
  identity: routeIdentityOf,
1018
1114
  providers: async () => {
1019
1115
  const registry = llmRegistry();
@@ -1091,7 +1187,7 @@ export function apply(ctx, config = {}, deps = {}) {
1091
1187
  // (thinking-default.js), whatever sent the request.
1092
1188
  return router.preStep(args, async () => {
1093
1189
  try {
1094
- await thinkingGuard.apply(args?.modelSelection);
1190
+ await thinkingGuard.apply(args?.modelSelection, args?.agent);
1095
1191
  } catch (error) {
1096
1192
  log(`${name}: the default thinking level was skipped (${error instanceof Error ? error.message : String(error)}).`);
1097
1193
  }
@@ -114,6 +114,12 @@ export function requiredThinkingLevel({ provider, model, offered, catalogueDefau
114
114
  */
115
115
  export function createThinkingGuard({ llm, settings, log = () => {} }) {
116
116
  const known = new Map();
117
+ /**
118
+ * The level each session (its agent object) fixed per model the first time it needed one (owner 2026-11-17: each
119
+ * session owns its model and level). A level another session saves later in the shared file reaches new sessions
120
+ * only, never one already running on that model.
121
+ */
122
+ const fixed = new WeakMap();
117
123
  /** `<route>/<model>/<level>` corrections already logged (once each, not every step). */
118
124
  const corrected = new Set();
119
125
 
@@ -137,10 +143,28 @@ export function createThinkingGuard({ llm, settings, log = () => {} }) {
137
143
  }
138
144
 
139
145
  return {
140
- /** The level this step's selection needs and does not have; undefined when it is fine as it is. */
141
- async levelFor(selection) {
146
+ /**
147
+ * The level this step's selection needs and does not have; undefined when it is fine as it is. `owner` (the step's
148
+ * agent): the session, whose first answer per model is kept for its lifetime.
149
+ */
150
+ async levelFor(selection, owner) {
142
151
  if (!isRecord(selection) || !nonEmpty(selection.provider) || !nonEmpty(selection.model)) return undefined;
143
152
  if (nonEmpty(selection.reasoningEffort) && !isOffLevel(selection.reasoningEffort)) return undefined;
153
+ const ref = `${selection.provider}/${selection.model}`;
154
+ const session = owner !== null && typeof owner === 'object' ? fixed.get(owner) : undefined;
155
+ if (session?.has(ref)) return session.get(ref);
156
+ const level = await this.resolveLevel(selection);
157
+ // "None needed" is not fixed: a model learned later to always think still gets a level.
158
+ if (level !== undefined && owner !== null && typeof owner === 'object') {
159
+ const levels = fixed.get(owner) ?? new Map();
160
+ levels.set(ref, level);
161
+ fixed.set(owner, levels);
162
+ }
163
+ return level;
164
+ },
165
+
166
+ /** The level the shared file and the model's own levels give a selection now (see `requiredThinkingLevel`). */
167
+ async resolveLevel(selection) {
144
168
  const described = await describe(selection.provider, selection.model);
145
169
  let saved;
146
170
  try {
@@ -168,7 +192,7 @@ export function createThinkingGuard({ llm, settings, log = () => {} }) {
168
192
  },
169
193
 
170
194
  /** Sets the level on the step's own selection object (what the engine sends this step). True when it changed. */
171
- async apply(selection) {
195
+ async apply(selection, owner) {
172
196
  const correction = await this.correctionFor(selection);
173
197
  if (correction !== undefined) {
174
198
  const was = selection.reasoningEffort;
@@ -187,7 +211,7 @@ export function createThinkingGuard({ llm, settings, log = () => {} }) {
187
211
  }
188
212
  // A model that always thinks still gets a level when the correction left it with none.
189
213
  if (correction === null) {
190
- const required = await this.levelFor(selection);
214
+ const required = await this.levelFor(selection, owner);
191
215
  if (required !== undefined) {
192
216
  try {
193
217
  selection.reasoningEffort = required;
@@ -198,7 +222,7 @@ export function createThinkingGuard({ llm, settings, log = () => {} }) {
198
222
  }
199
223
  return true;
200
224
  }
201
- const level = await this.levelFor(selection);
225
+ const level = await this.levelFor(selection, owner);
202
226
  if (level === undefined) return false;
203
227
  try {
204
228
  selection.reasoningEffort = level;