@juanbenjumea/pi-agy 0.7.14 → 0.7.16

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.
@@ -0,0 +1,116 @@
1
+ /**
2
+ * Last-good provider catalog persistence.
3
+ *
4
+ * The catalog is discovered at runtime and deliberately ships no hardcoded
5
+ * model ids, so a cold process has nothing to answer `getModels()` with until
6
+ * `agy models` returns. Pi resolves configured scopes (`enabledModels`) at
7
+ * startup, so an empty catalog there reports `No models match pattern
8
+ * "antigravity/<id>"` for a model that exists — the provider looked empty, not
9
+ * the model missing.
10
+ *
11
+ * Persisting the last observed roster closes that window without inventing
12
+ * model names: a fresh process starts from real, previously observed entries,
13
+ * and discovery still replaces them. Loading is synchronous because it feeds
14
+ * provider registration; both directions are best effort and never throw, so a
15
+ * corrupt or unwritable cache degrades to today's empty-start behaviour.
16
+ */
17
+
18
+ import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
19
+ import * as path from "node:path";
20
+
21
+ import { getDefaultConfigPath } from "./config.js";
22
+ import type { AgyProviderEffort, AgyProviderModelEntry } from "./provider-models.js";
23
+
24
+ const CACHE_FILENAME = "agy-provider-models.json";
25
+ const MAX_CACHED_ENTRIES = 500;
26
+ const EFFORT_VALUES: readonly AgyProviderEffort[] = ["low", "medium", "high"];
27
+
28
+ export function providerCatalogCachePath(configPath = getDefaultConfigPath()): string {
29
+ return path.join(path.dirname(configPath), CACHE_FILENAME);
30
+ }
31
+
32
+ /** Validate one cached entry; anything malformed is dropped, not repaired. */
33
+ function toEntry(value: unknown): AgyProviderModelEntry | undefined {
34
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
35
+ const record = value as Record<string, unknown>;
36
+ if (typeof record.full !== "string" || !record.full.trim()) return undefined;
37
+ if (typeof record.id !== "string" || !record.id.trim()) return undefined;
38
+ const entry: AgyProviderModelEntry = { full: record.full, id: record.id };
39
+ if (Array.isArray(record.efforts)) {
40
+ const efforts = record.efforts.filter(
41
+ (effort): effort is AgyProviderEffort =>
42
+ typeof effort === "string" && (EFFORT_VALUES as readonly string[]).includes(effort),
43
+ );
44
+ // A base entry is only effort-driven when it still carries usable tiers.
45
+ if (efforts.length > 0) entry.efforts = [...new Set(efforts)];
46
+ }
47
+ return entry;
48
+ }
49
+
50
+ /** Read the last-good catalog. Returns `[]` when absent, unreadable, or invalid. */
51
+ export function loadProviderCatalogCache(configPath = getDefaultConfigPath()): AgyProviderModelEntry[] {
52
+ let raw: string;
53
+ try {
54
+ raw = readFileSync(providerCatalogCachePath(configPath), "utf8");
55
+ } catch {
56
+ return [];
57
+ }
58
+ try {
59
+ const parsed: unknown = JSON.parse(raw);
60
+ const list = Array.isArray(parsed)
61
+ ? parsed
62
+ : typeof parsed === "object" && parsed !== null && Array.isArray((parsed as { models?: unknown }).models)
63
+ ? (parsed as { models: unknown[] }).models
64
+ : [];
65
+ const entries: AgyProviderModelEntry[] = [];
66
+ const seen = new Set<string>();
67
+ for (const value of list.slice(0, MAX_CACHED_ENTRIES)) {
68
+ const entry = toEntry(value);
69
+ if (!entry || seen.has(entry.id)) continue;
70
+ seen.add(entry.id);
71
+ entries.push(entry);
72
+ }
73
+ return entries;
74
+ } catch {
75
+ return [];
76
+ }
77
+ }
78
+
79
+ /**
80
+ * Persist the roster just discovered. Writes a sibling temp file and renames,
81
+ * so a crash mid-write can never leave a half-parsed cache behind.
82
+ */
83
+ export function saveProviderCatalogCache(
84
+ entries: readonly AgyProviderModelEntry[],
85
+ configPath = getDefaultConfigPath(),
86
+ ): void {
87
+ if (entries.length === 0) return;
88
+ const target = providerCatalogCachePath(configPath);
89
+ const temp = `${target}.${process.pid}.tmp`;
90
+ try {
91
+ mkdirSync(path.dirname(target), { recursive: true });
92
+ const payload = JSON.stringify(
93
+ { version: 1, models: entries.slice(0, MAX_CACHED_ENTRIES) },
94
+ null,
95
+ 2,
96
+ );
97
+ writeFileSync(temp, payload, { encoding: "utf8", mode: 0o600 });
98
+ renameSync(temp, target);
99
+ } catch {
100
+ // Best effort: an unwritable cache must never fail a refresh.
101
+ try {
102
+ unlinkSync(temp);
103
+ } catch {
104
+ // Nothing to clean up.
105
+ }
106
+ }
107
+ }
108
+
109
+ /** Test helper — drop the persisted roster. */
110
+ export function clearProviderCatalogCache(configPath = getDefaultConfigPath()): void {
111
+ try {
112
+ unlinkSync(providerCatalogCachePath(configPath));
113
+ } catch {
114
+ // Absent is already the desired state.
115
+ }
116
+ }
@@ -36,6 +36,13 @@ import {
36
36
  import type {
37
37
  AgyProviderEffort,
38
38
  } from "./provider-models.js";
39
+ import {
40
+ diffAgyUsage,
41
+ validateAgyUsage,
42
+ ZERO_USAGE_BASELINE,
43
+ type NormalizedProviderUsage,
44
+ type ValidatedAgyUsage,
45
+ } from "./provider-usage.js";
39
46
 
40
47
  export interface ProviderDriverProfile {
41
48
  dir: string;
@@ -48,6 +55,8 @@ export interface ProviderDriverProfile {
48
55
  imageRoot?: string;
49
56
  /** Fingerprint of the bridged Pi-tool catalog; changes recycle (fresh ListTools). */
50
57
  bridgeTools?: string;
58
+ /** Session-only `--settings` JSON (e.g. denying shadowed built-in tools). */
59
+ settingsJson?: string;
51
60
  }
52
61
 
53
62
  export interface ProviderDriverTurn {
@@ -56,6 +65,7 @@ export interface ProviderDriverTurn {
56
65
  signal: AbortSignal;
57
66
  timeoutMs: number;
58
67
  onText?: (delta: string) => void;
68
+ onThinking?: (delta: string) => void;
59
69
  onActivity?: (label: string) => void;
60
70
  }
61
71
 
@@ -67,6 +77,8 @@ export interface ProviderDriverOutcome {
67
77
  conversationId?: string;
68
78
  activity: string[];
69
79
  deniedActions?: Array<{ action?: string; display_name?: string }>;
80
+ /** Validated per-turn native usage delta, when a same-generation baseline is known. */
81
+ usage?: NormalizedProviderUsage;
70
82
  }
71
83
 
72
84
  /** A bridged Pi-tool call parked mid-turn: agy waits on the MCP response. */
@@ -82,7 +94,7 @@ export interface DriverPark {
82
94
  */
83
95
  export type DriverTurnEnd =
84
96
  | { kind: "done"; outcome: ProviderDriverOutcome }
85
- | { kind: "parked"; park: DriverPark };
97
+ | { kind: "parked"; park: DriverPark; parks: DriverPark[] };
86
98
 
87
99
  export interface ProviderDriverStats {
88
100
  spawns: number;
@@ -115,11 +127,14 @@ interface TurnPhase {
115
127
 
116
128
  /** Wall-clock cap for a suspended (parked) turn without Pi progress. */
117
129
  export const SUSPENDED_TURN_MAX_MS = 30 * 60_000;
130
+ /** Micro-batch window for collecting parallel bridged MCP tool calls into one Pi turn. */
131
+ export const PROVIDER_PARK_BATCH_MS = 15;
118
132
 
119
133
  interface ActiveTurn {
120
134
  signal: AbortSignal;
121
135
  timeoutMs: number;
122
136
  onText?: (delta: string) => void;
137
+ onThinking?: (delta: string) => void;
123
138
  onActivity?: (label: string) => void;
124
139
  text: string;
125
140
  truncated: boolean;
@@ -130,6 +145,10 @@ interface ActiveTurn {
130
145
  settled: boolean;
131
146
  /** Suspended mid-turn on a parked bridge call: child alive, timers off. */
132
147
  suspended: boolean;
148
+ /** Parks collected in the current micro-batch before flushing to Pi. */
149
+ pendingParks: DriverPark[];
150
+ /** Micro-batch flush timer. */
151
+ parkBatchTimer?: NodeJS.Timeout;
133
152
  /** Live waiter for the current phase (turn() or continueTurn()). */
134
153
  phase?: TurnPhase;
135
154
  /** Terminal envelope received during a park; owned until consumed or abandoned. */
@@ -140,7 +159,7 @@ interface ActiveTurn {
140
159
  }
141
160
 
142
161
  function profileKey(profile: ProviderDriverProfile): string {
143
- return `${profile.dir}::${profile.fullModel}::${profile.effort ?? ""}::${profile.skipPermissions ? "skip" : "ask"}::${profile.bridgeDir ?? ""}::${profile.bridgeTools ?? ""}::${profile.imageRoot ?? ""}`;
162
+ return `${profile.dir}::${profile.fullModel}::${profile.effort ?? ""}::${profile.skipPermissions ? "skip" : "ask"}::${profile.bridgeDir ?? ""}::${profile.bridgeTools ?? ""}::${profile.imageRoot ?? ""}::${profile.settingsJson ?? ""}`;
144
163
  }
145
164
 
146
165
  export class AgyProviderDriver {
@@ -148,10 +167,13 @@ export class AgyProviderDriver {
148
167
  private generation = 0;
149
168
  private profile?: ProviderDriverProfile;
150
169
  private boundConversationId?: string;
170
+ /** Committed cumulative usage baseline for this child process generation (undefined until primed on external resume). */
171
+ private usageBaseline?: ValidatedAgyUsage;
151
172
  private active?: ActiveTurn;
152
173
  private queue: Promise<void> = Promise.resolve();
153
174
  private idleTimer?: NodeJS.Timeout;
154
175
  private readonly idleMs: number;
176
+ private readonly parkBatchMs: number;
155
177
  private lineBuffer = "";
156
178
  private readonly decoder = new StringDecoder("utf8");
157
179
  /**
@@ -168,8 +190,9 @@ export class AgyProviderDriver {
168
190
  private lifecycle: string[] = [];
169
191
  private closed = false;
170
192
 
171
- constructor(options?: { idleMs?: number }) {
193
+ constructor(options?: { idleMs?: number; parkBatchMs?: number }) {
172
194
  this.idleMs = options?.idleMs ?? PROVIDER_DRIVER_IDLE_MS;
195
+ this.parkBatchMs = options?.parkBatchMs ?? PROVIDER_PARK_BATCH_MS;
173
196
  }
174
197
 
175
198
  /**
@@ -193,18 +216,48 @@ export class AgyProviderDriver {
193
216
  onParksOrphaned?: (message: string) => void;
194
217
 
195
218
  /**
196
- * Accept a parked bridge call for the active turn. Suspends the turn
219
+ * Accept a parked bridge call for the active turn. Collects parallel
220
+ * calls within `parkBatchMs` into a single Pi turn, then suspends the turn
197
221
  * (timers off, child alive) and ends the current phase as parked.
198
222
  * Returns false when no turn can take the park — the caller must fail it.
199
223
  */
200
224
  notifyPark(park: DriverPark): boolean {
201
225
  const turn = this.active;
202
226
  if (!turn || turn.settled || turn.suspended || !turn.phase) return false;
203
- turn.suspended = true;
227
+ turn.pendingParks.push(park);
204
228
  if (turn.timer) {
205
229
  clearTimeout(turn.timer);
206
230
  turn.timer = undefined;
207
231
  }
232
+ this.log(`park:${park.toolName}`);
233
+ if (!turn.parkBatchTimer) {
234
+ if (this.parkBatchMs <= 0) {
235
+ this.flushParks(turn);
236
+ } else {
237
+ turn.parkBatchTimer = setTimeout(() => {
238
+ turn.parkBatchTimer = undefined;
239
+ this.flushParks(turn);
240
+ }, this.parkBatchMs);
241
+ (turn.parkBatchTimer as unknown as { unref?: () => void }).unref?.();
242
+ }
243
+ }
244
+ return true;
245
+ }
246
+
247
+ private clearParkBatchTimer(turn: ActiveTurn): void {
248
+ if (turn.parkBatchTimer) {
249
+ clearTimeout(turn.parkBatchTimer);
250
+ turn.parkBatchTimer = undefined;
251
+ }
252
+ }
253
+
254
+ private flushParks(turn: ActiveTurn): void {
255
+ if (this.active !== turn || turn.settled || turn.suspended || !turn.phase || turn.pendingParks.length === 0) {
256
+ return;
257
+ }
258
+ const parks = turn.pendingParks;
259
+ turn.pendingParks = [];
260
+ turn.suspended = true;
208
261
  // Keep this deadline through terminal-awaiting-consumption too: a lost
209
262
  // Pi continuation must not hold the child, parks, images or driver forever.
210
263
  turn.suspendedTimer = setTimeout(() => {
@@ -216,9 +269,7 @@ export class AgyProviderDriver {
216
269
  (turn.suspendedTimer as unknown as { unref?: () => void }).unref?.();
217
270
  const phase = turn.phase;
218
271
  turn.phase = undefined;
219
- this.log(`park:${park.toolName}`);
220
- phase.resolve({ kind: "parked", park });
221
- return true;
272
+ phase.resolve({ kind: "parked", park: parks[0], parks });
222
273
  }
223
274
 
224
275
  private clearSuspendedTimer(turn: ActiveTurn): void {
@@ -239,9 +290,11 @@ export class AgyProviderDriver {
239
290
  /** Abandonment has no future consumer: orphan parks once and release ownership. */
240
291
  private abandonTurn(turn: ActiveTurn, error: Error): void {
241
292
  if (this.active !== turn) return;
242
- const parked = turn.suspended || !!turn.pendingTerminal;
293
+ this.clearParkBatchTimer(turn);
294
+ const parked = turn.suspended || turn.pendingParks.length > 0 || !!turn.pendingTerminal;
243
295
  // Teardown must also release a retained terminal, but must never replace it
244
296
  // with an abort/transport failure during ordinary terminal settlement.
297
+ turn.pendingParks = [];
245
298
  turn.pendingTerminal = undefined;
246
299
  turn.suspended = false;
247
300
  if (parked) this.failParksOrphaned(error.message);
@@ -257,7 +310,7 @@ export class AgyProviderDriver {
257
310
  private interruptTurn(turn: ActiveTurn, flag: "aborted" | "timedOut", message: string): void {
258
311
  if (turn.settled || this.active !== turn) return;
259
312
  this.killChild();
260
- if (turn.suspended) this.abandonTurn(turn, new Error(message));
313
+ if (turn.suspended || turn.pendingParks.length > 0) this.abandonTurn(turn, new Error(message));
261
314
  else if (turn.text) this.settleDone(turn, flag === "aborted" ? { aborted: true } : { timedOut: true });
262
315
  else this.settleError(turn, new Error(message));
263
316
  }
@@ -273,6 +326,7 @@ export class AgyProviderDriver {
273
326
  signal?: AbortSignal;
274
327
  timeoutMs?: number;
275
328
  onText?: (delta: string) => void;
329
+ onThinking?: (delta: string) => void;
276
330
  onActivity?: (label: string) => void;
277
331
  }): Promise<DriverTurnEnd> {
278
332
  const turn = this.active;
@@ -296,6 +350,7 @@ export class AgyProviderDriver {
296
350
  turn.suspended = false;
297
351
  this.clearSuspendedTimer(turn);
298
352
  if (options?.onText) turn.onText = options.onText;
353
+ if (options?.onThinking) turn.onThinking = options.onThinking;
299
354
  if (options?.onActivity) turn.onActivity = options.onActivity;
300
355
  if (options?.timeoutMs !== undefined) turn.timeoutMs = options.timeoutMs;
301
356
  if (turn.onAbort) {
@@ -389,6 +444,7 @@ export class AgyProviderDriver {
389
444
  if ((this.profile.bridgeDir ?? "") !== (profile.bridgeDir ?? "")) return "bridge-changed";
390
445
  if ((this.profile.imageRoot ?? "") !== (profile.imageRoot ?? "")) return "images-changed";
391
446
  if ((this.profile.bridgeTools ?? "") !== (profile.bridgeTools ?? "")) return "tools-changed";
447
+ if ((this.profile.settingsJson ?? "") !== (profile.settingsJson ?? "")) return "settings-changed";
392
448
  return "permissions-changed";
393
449
  }
394
450
  if ((resume ?? undefined) !== this.boundConversationId) return "conversation-changed";
@@ -401,6 +457,7 @@ export class AgyProviderDriver {
401
457
  this.child = undefined;
402
458
  this.profile = undefined;
403
459
  this.boundConversationId = undefined;
460
+ this.usageBaseline = undefined;
404
461
  if (child) killProcessTree(child);
405
462
  }
406
463
 
@@ -410,6 +467,7 @@ export class AgyProviderDriver {
410
467
  if (profile.effort) args.push("--effort", profile.effort);
411
468
  if (resume) args.push("--conversation", resume);
412
469
  if (profile.skipPermissions) args.push("--dangerously-skip-permissions");
470
+ if (profile.settingsJson) args.push("--settings", profile.settingsJson);
413
471
  if (profile.bridgeDir) args.push("--add-dir", profile.bridgeDir);
414
472
  if (profile.imageRoot) args.push("--add-dir", profile.imageRoot);
415
473
  // Same flags as the former per-turn spawn, minus `-p`: turns arrive on stdin.
@@ -424,6 +482,10 @@ export class AgyProviderDriver {
424
482
  this.child = child;
425
483
  this.profile = profile;
426
484
  this.boundConversationId = resume ?? undefined;
485
+ // Fresh processes start at known zero cumulative usage; externally resumed
486
+ // conversations prime their baseline on the first terminal snapshot so
487
+ // prior session history is never charged to the first resumed turn.
488
+ this.usageBaseline = resume ? undefined : { ...ZERO_USAGE_BASELINE };
427
489
  this.lineBuffer = "";
428
490
  this.pendingLines = [];
429
491
  this.primed = false;
@@ -465,6 +527,7 @@ export class AgyProviderDriver {
465
527
  this.child = undefined;
466
528
  this.profile = undefined;
467
529
  this.boundConversationId = undefined;
530
+ this.usageBaseline = undefined;
468
531
  this.log(`exit:${code ?? "signal"}`);
469
532
  // Abort/timeout paths settle the turn themselves before killing; an
470
533
  // unsettled turn here means the child died mid-turn: fail closed.
@@ -510,10 +573,21 @@ export class AgyProviderDriver {
510
573
  }
511
574
  }
512
575
 
576
+ private pushThinking(turn: ActiveTurn, delta: string): void {
577
+ if (!delta || turn.settled) return;
578
+ try {
579
+ turn.onThinking?.(delta);
580
+ } catch {
581
+ // Same dead-stream tolerance as text deltas.
582
+ }
583
+ }
584
+
513
585
  private pushActivity(turn: ActiveTurn, label: string): void {
514
- if (turn.settled || turn.seenActivity.has(label) || turn.activity.length >= MAX_ACTIVITY_ENTRIES) return;
515
- turn.seenActivity.add(label);
516
- turn.activity.push(label);
586
+ if (turn.settled) return;
587
+ if (!turn.seenActivity.has(label) && turn.activity.length < MAX_ACTIVITY_ENTRIES) {
588
+ turn.seenActivity.add(label);
589
+ turn.activity.push(label);
590
+ }
517
591
  try {
518
592
  turn.onActivity?.(label);
519
593
  } catch {
@@ -553,6 +627,17 @@ export class AgyProviderDriver {
553
627
  const parsed = parseStreamLine(line);
554
628
  if (!parsed) return;
555
629
  const step = parsed.step_update;
630
+ if (step) {
631
+ const thinkingDelta =
632
+ typeof step.thinking_delta === "string" && step.thinking_delta
633
+ ? step.thinking_delta
634
+ : typeof step.thought_delta === "string" && step.thought_delta
635
+ ? step.thought_delta
636
+ : step.step_type === "thinking" && typeof step.text_delta === "string" && step.text_delta
637
+ ? step.text_delta
638
+ : undefined;
639
+ if (thinkingDelta) this.pushThinking(turn, thinkingDelta);
640
+ }
556
641
  if (step?.step_type === "agent_response") {
557
642
  this.pushLiveText(turn, step.text_delta, undefined);
558
643
  // response_text may arrive on the same record family in other builds.
@@ -600,14 +685,24 @@ export class AgyProviderDriver {
600
685
  text = text.slice(0, MAX_TURN_TEXT_CHARS);
601
686
  turn.truncated = true;
602
687
  }
603
- this.settleDone(turn, { text });
688
+ let usage: NormalizedProviderUsage | undefined;
689
+ const validatedUsage = validateAgyUsage(result.usage);
690
+ if (validatedUsage) {
691
+ if (this.usageBaseline) {
692
+ usage = diffAgyUsage(validatedUsage, this.usageBaseline);
693
+ }
694
+ this.usageBaseline = validatedUsage;
695
+ }
696
+ this.settleDone(turn, { text, usage });
604
697
  }
605
698
 
606
699
  private settleDone(
607
700
  turn: ActiveTurn,
608
- overrides?: { text?: string; aborted?: boolean; timedOut?: boolean },
701
+ overrides?: { text?: string; aborted?: boolean; timedOut?: boolean; usage?: NormalizedProviderUsage },
609
702
  ): void {
610
703
  if (turn.settled) return;
704
+ this.clearParkBatchTimer(turn);
705
+ turn.pendingParks = [];
611
706
  const retain = turn.suspended && !turn.phase;
612
707
  turn.settled = true;
613
708
  turn.suspended = false;
@@ -638,6 +733,7 @@ export class AgyProviderDriver {
638
733
  conversationId: turn.runResult.conversation_id,
639
734
  activity: turn.activity,
640
735
  deniedActions: turn.runResult.denied_actions,
736
+ ...(overrides?.usage ? { usage: overrides.usage } : {}),
641
737
  },
642
738
  };
643
739
  if (retain) turn.pendingTerminal = { kind: "done", end };
@@ -647,6 +743,8 @@ export class AgyProviderDriver {
647
743
 
648
744
  private settleError(turn: ActiveTurn, error: Error): void {
649
745
  if (turn.settled) return;
746
+ this.clearParkBatchTimer(turn);
747
+ turn.pendingParks = [];
650
748
  const retain = turn.suspended && !turn.phase;
651
749
  turn.settled = true;
652
750
  turn.suspended = false;
@@ -702,6 +800,7 @@ export class AgyProviderDriver {
702
800
  signal: options.signal,
703
801
  timeoutMs: options.timeoutMs,
704
802
  onText: options.onText,
803
+ onThinking: options.onThinking,
705
804
  onActivity: options.onActivity,
706
805
  text: "",
707
806
  truncated: false,
@@ -710,6 +809,7 @@ export class AgyProviderDriver {
710
809
  runResult: { response: "" },
711
810
  settled: false,
712
811
  suspended: false,
812
+ pendingParks: [],
713
813
  phase: { resolve, reject },
714
814
  };
715
815
  this.active = turn;
@@ -34,6 +34,7 @@ import {
34
34
  } from "@modelcontextprotocol/sdk/types.js";
35
35
 
36
36
  import { getDefaultConfigPath } from "./config.js";
37
+ import { loadProviderCatalogCache } from "./provider-catalog-store.js";
37
38
  import { isBridgeInputWithinBudget } from "./bridge-input-budget.js";
38
39
  import type { BridgeToolDef } from "./provider-tools.js";
39
40
  import { checkAgyUsage, formatAgyUsage } from "./cli.js";
@@ -342,13 +343,19 @@ export async function startMcpBridge(
342
343
  if (name === "agy_model_catalog") {
343
344
  const entries = await readCatalog(dir, catalogCache);
344
345
  catalogCache = entries.cache;
346
+ // Never name models from memory: a retired id would look selectable
347
+ // here and then fail at launch.
348
+ if (entries.models.length === 0) {
349
+ return toolText(
350
+ "no agy models resolved: live discovery (agy models) is unavailable. Sign in to agy, then retry; this bridge will not guess model ids.",
351
+ true,
352
+ );
353
+ }
345
354
  const lines = entries.models.map(
346
355
  (entry) =>
347
356
  `- ${entry.id} (--model ${entry.full}${entry.efforts ? `; effort: ${entry.efforts.join("/")}` : "; fixed thinking"})`,
348
357
  );
349
- return toolText(
350
- `agy models${entries.fallback ? " (fallback catalog — live discovery unavailable)" : ""}:\n${lines.join("\n")}`,
351
- );
358
+ return toolText(`agy models:\n${lines.join("\n")}`);
352
359
  }
353
360
  if (name === ACTIVATE_SKILL_TOOL_NAME) {
354
361
  const skillName = stringArg(args.name);
@@ -744,9 +751,17 @@ async function readCatalog(
744
751
  const models = parseProviderCatalog(raw);
745
752
  if (models.length > 0) return { models, fallback: false, cache: { raw, at: Date.now() } };
746
753
  } catch {
747
- // Fall through to the fallback catalog.
754
+ // Fall through to the last roster this machine observed.
748
755
  }
749
- return { models: [...FALLBACK_PROVIDER_MODELS], fallback: true, cache };
756
+ // The provider persists the roster it discovered, so a discovery failure
757
+ // here degrades to those real, previously observed ids instead of an empty
758
+ // list that reads as "this workspace has no models".
759
+ const observed = loadProviderCatalogCache();
760
+ return {
761
+ models: observed.length > 0 ? observed : [...FALLBACK_PROVIDER_MODELS],
762
+ fallback: true,
763
+ cache,
764
+ };
750
765
  }
751
766
 
752
767
  async function readBody(req: IncomingMessage): Promise<{ body?: unknown; tooLarge: boolean }> {
@@ -6,17 +6,22 @@
6
6
  *
7
7
  * `agy models` prints one model per line: `<slug> <display label>`. Only the
8
8
  * first column (the slug) is a valid `--model` value; the label is
9
- * display-only. Gemini bases with multiple effort tiers collapse to a single
10
- * base entry with a thinking-level toggle (the picked level is sent as agy
11
- * `--effort`); fixed-thinking families (Claude, GPT-OSS, single-tier Gemini)
12
- * keep agy's exact qualified slug and never receive `--effort`.
9
+ * display-only. A base whose catalog carries two or more effort tiers collapses
10
+ * to a single base entry with a thinking-level toggle (the picked level becomes
11
+ * agy `--effort`). A base with one tier or none keeps agy's exact qualified
12
+ * slug and never receives `--effort`.
13
+ *
14
+ * That grouping is derived from the catalog alone. Which families accept
15
+ * `--effort` is agy's own answer to "does `B-T` exist" — tier-qualified ids are
16
+ * rejected as a conflict and tierless families as unsupported — so no vendor
17
+ * name needs to be known here.
13
18
  *
14
19
  * Pure functions only — no spawning, no Pi imports — so the catalog is
15
20
  * unit-testable without the CLI.
16
21
  */
17
22
 
18
- /** Reasoning-effort tiers agy accepts via `--effort`. */
19
- export type AgyProviderEffort = "low" | "medium" | "high";
23
+ /** Reasoning-effort tiers agy accepts via `--effort` (`agy --help`). */
24
+ export type AgyProviderEffort = "low" | "medium" | "high" | "xhigh" | "max";
20
25
 
21
26
  /** Pi thinking levels that map onto agy effort tiers. */
22
27
  export type AgyThinkingLevel =
@@ -28,12 +33,25 @@ export type AgyThinkingLevel =
28
33
  | "xhigh"
29
34
  | "max";
30
35
 
31
- const EFFORT_RANK: Record<AgyProviderEffort, number> = { low: 0, medium: 1, high: 2 };
36
+ const EFFORT_RANK: Record<AgyProviderEffort, number> = {
37
+ low: 0,
38
+ medium: 1,
39
+ high: 2,
40
+ xhigh: 3,
41
+ max: 4,
42
+ };
32
43
 
33
- const EFFORT_ORDER: readonly AgyProviderEffort[] = ["low", "medium", "high"];
44
+ const EFFORT_ORDER: readonly AgyProviderEffort[] = ["low", "medium", "high", "xhigh", "max"];
34
45
 
35
- /** Split an agy slug into (base, tier); tier is null without a tier suffix. */
36
- const TIER_RE = /^(.+)-(high|medium|low)$/;
46
+ /**
47
+ * Split an agy slug into (base, tier); tier is null without a tier suffix.
48
+ *
49
+ * `xhigh` and `max` belong here: when they did not, `gemini-4-neon-xhigh`
50
+ * became its own base entry instead of a fourth stop inside the `gemini-4-neon`
51
+ * thinking picker. Longer alternatives come first so `-xhigh` can never be
52
+ * read as `-high`.
53
+ */
54
+ const TIER_RE = /^(.+)-(xhigh|max|high|medium|low)$/;
37
55
 
38
56
  /**
39
57
  * Preserve the established hyphenated first-column format. A leading-dash
@@ -71,14 +89,6 @@ export function parseAgyModelIds(raw: string): AgyModelId[] {
71
89
  return [...new Set(ids.filter(isAgyModelId))];
72
90
  }
73
91
 
74
- /**
75
- * Families verified to accept base-slug + `--effort`. Only these collapse to
76
- * a base entry with a thinking toggle; every other family keeps agy's exact
77
- * qualified slug so unknown or fixed-thinking families degrade safely instead
78
- * of forcing an unsupported `--effort`.
79
- */
80
- const EFFORT_CAPABLE_FAMILIES: readonly RegExp[] = [/^gemini-/];
81
-
82
92
  export interface AgyProviderModelEntry {
83
93
  /**
84
94
  * Exact agy `--model` value: a base slug (e.g. `gemini-3.8-flash`) when
@@ -115,9 +125,15 @@ export function toProviderEffort(
115
125
  candidate = "medium";
116
126
  break;
117
127
  case "high":
128
+ candidate = "high";
129
+ break;
130
+ // agy exposes these as real stops, so pass them through instead of
131
+ // collapsing every strong level onto "high".
118
132
  case "xhigh":
133
+ candidate = "xhigh";
134
+ break;
119
135
  case "max":
120
- candidate = "high";
136
+ candidate = "max";
121
137
  break;
122
138
  default:
123
139
  candidate = efforts[0] ?? "low";
@@ -144,8 +160,8 @@ export function slugifyProviderId(full: string): string {
144
160
  /**
145
161
  * Build the thinking-level map for an effort-driven base: `off` and `minimal`
146
162
  * are always hidden (agy has no no-thinking mode; a base requires an effort),
147
- * as is any of low/medium/high the base does not offer. Pi treats null as
148
- * hidden, so the toggle shows exactly agy's stops.
163
+ * as is any tier the base does not offer. Pi treats null as hidden, so the
164
+ * toggle shows exactly agy's stops.
149
165
  */
150
166
  export function thinkingMapForEfforts(
151
167
  efforts: readonly AgyProviderEffort[],
@@ -154,17 +170,17 @@ export function thinkingMapForEfforts(
154
170
  off: null,
155
171
  minimal: null,
156
172
  };
157
- for (const level of ["low", "medium", "high"] as const) {
173
+ for (const level of ["low", "medium", "high", "xhigh", "max"] as const) {
158
174
  if (!efforts.includes(level)) map[level] = null;
159
175
  }
160
176
  return map;
161
177
  }
162
178
 
163
179
  /**
164
- * Parse raw `agy models` text into provider entries. Effort-capable Gemini
165
- * bases with >= 2 tier variants collapse to one base entry carrying the tiers
166
- * they accept; everything else keeps agy's exact qualified slug. Insertion
167
- * order of first-seen bases is preserved.
180
+ * Parse raw `agy models` text into provider entries. A base with >= 2 tier
181
+ * variants collapses to one base entry carrying the tiers it accepts;
182
+ * everything else keeps agy's exact qualified slug. Insertion order of
183
+ * first-seen bases is preserved.
168
184
  */
169
185
  export function parseProviderCatalog(raw: string): AgyProviderModelEntry[] {
170
186
  const groups = new Map<string, { lines: string[]; tiers: Set<AgyProviderEffort> }>();
@@ -191,7 +207,7 @@ export function parseProviderCatalog(raw: string): AgyProviderModelEntry[] {
191
207
  };
192
208
  for (const [base, group] of groups) {
193
209
  const efforts = [...group.tiers].sort((a, b) => EFFORT_RANK[a] - EFFORT_RANK[b]);
194
- if (efforts.length >= 2 && EFFORT_CAPABLE_FAMILIES.some((re) => re.test(base))) {
210
+ if (efforts.length >= 2) {
195
211
  pushEntry({ full: base, id: slugifyProviderId(base), efforts });
196
212
  } else {
197
213
  for (const line of group.lines) {
@@ -226,16 +242,14 @@ export function providerEntryName(entry: AgyProviderModelEntry): string {
226
242
  }
227
243
 
228
244
  /**
229
- * Fallback catalog when `agy models` fails at load (binary missing, auth not
230
- * yet done, network stall). Keeps the picker populated so selection yields a
231
- * clear runtime error instead of an empty list. Update when agy ships new
232
- * Gemini versions.
245
+ * Pre-discovery catalog.
246
+ *
247
+ * Intentionally empty: `agy models` is the only source of model names, so a
248
+ * built-in list would silently offer ids the installed CLI no longer serves
249
+ * (a retired tier then fails at launch instead of at selection). Callers treat
250
+ * an empty catalog as "not discovered yet" and surface the discovery error.
233
251
  */
234
- export const FALLBACK_PROVIDER_MODELS: AgyProviderModelEntry[] = [
235
- { full: "gemini-3.8-flash", id: "gemini-3-8-flash", efforts: ["low", "medium", "high"] },
236
- { full: "gemini-3.1-pro", id: "gemini-3-1-pro", efforts: ["low", "high"] },
237
- { full: "claude-sonnet-4-6", id: "claude-sonnet-4-6" },
238
- ];
252
+ export const FALLBACK_PROVIDER_MODELS: readonly AgyProviderModelEntry[] = [];
239
253
 
240
254
  /**
241
255
  * Plain provider model definition (structurally compatible with Pi's