@juanbenjumea/pi-agy 0.7.13 → 0.7.15

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.
@@ -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;
@@ -35,6 +35,7 @@ import {
35
35
 
36
36
  import { getDefaultConfigPath } from "./config.js";
37
37
  import { isBridgeInputWithinBudget } from "./bridge-input-budget.js";
38
+ import type { BridgeToolDef } from "./provider-tools.js";
38
39
  import { checkAgyUsage, formatAgyUsage } from "./cli.js";
39
40
  import {
40
41
  FALLBACK_PROVIDER_MODELS,
@@ -180,16 +181,6 @@ export interface McpBridgeHandle {
180
181
  describe: () => { configDir: string; url: string; toolCount: number; pendingResults: number };
181
182
  }
182
183
 
183
- /** A Pi tool projected for agy: MCP-safe advertised name, real Pi identity. */
184
- export interface BridgeToolDef {
185
- /** MCP-safe name as advertised to agy. */
186
- name: string;
187
- /** Real Pi tool name (invoked via shadow toolUse). */
188
- piName: string;
189
- description: string;
190
- inputSchema: Record<string, unknown>;
191
- }
192
-
193
184
  export interface BridgePark {
194
185
  callId: string;
195
186
  /** Real Pi tool name. */
@@ -204,15 +195,6 @@ export interface BridgeToolResult {
204
195
 
205
196
  export type BridgeParkHandler = (park: BridgePark) => boolean;
206
197
 
207
- /** MCP tool names: [a-zA-Z0-9_-]{1,64}. Pi names are sanitized into that. */
208
- export function toSafeBridgeName(name: string): string {
209
- const safe = name
210
- .replace(/[^a-zA-Z0-9_-]+/g, "_")
211
- .replace(/^_+|_+$/g, "")
212
- .slice(0, 64);
213
- return safe || "tool";
214
- }
215
-
216
198
  interface CatalogCache {
217
199
  raw: string;
218
200
  at: number;
@@ -360,13 +342,19 @@ export async function startMcpBridge(
360
342
  if (name === "agy_model_catalog") {
361
343
  const entries = await readCatalog(dir, catalogCache);
362
344
  catalogCache = entries.cache;
345
+ // Never name models from memory: a retired id would look selectable
346
+ // here and then fail at launch.
347
+ if (entries.models.length === 0) {
348
+ return toolText(
349
+ "no agy models resolved: live discovery (agy models) is unavailable. Sign in to agy, then retry; this bridge will not guess model ids.",
350
+ true,
351
+ );
352
+ }
363
353
  const lines = entries.models.map(
364
354
  (entry) =>
365
355
  `- ${entry.id} (--model ${entry.full}${entry.efforts ? `; effort: ${entry.efforts.join("/")}` : "; fixed thinking"})`,
366
356
  );
367
- return toolText(
368
- `agy models${entries.fallback ? " (fallback catalog — live discovery unavailable)" : ""}:\n${lines.join("\n")}`,
369
- );
357
+ return toolText(`agy models:\n${lines.join("\n")}`);
370
358
  }
371
359
  if (name === ACTIVATE_SKILL_TOOL_NAME) {
372
360
  const skillName = stringArg(args.name);
@@ -762,7 +750,7 @@ async function readCatalog(
762
750
  const models = parseProviderCatalog(raw);
763
751
  if (models.length > 0) return { models, fallback: false, cache: { raw, at: Date.now() } };
764
752
  } catch {
765
- // Fall through to the fallback catalog.
753
+ // Fall through to the empty catalog.
766
754
  }
767
755
  return { models: [...FALLBACK_PROVIDER_MODELS], fallback: true, cache };
768
756
  }
@@ -226,16 +226,14 @@ export function providerEntryName(entry: AgyProviderModelEntry): string {
226
226
  }
227
227
 
228
228
  /**
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.
229
+ * Pre-discovery catalog.
230
+ *
231
+ * Intentionally empty: `agy models` is the only source of model names, so a
232
+ * built-in list would silently offer ids the installed CLI no longer serves
233
+ * (a retired tier then fails at launch instead of at selection). Callers treat
234
+ * an empty catalog as "not discovered yet" and surface the discovery error.
233
235
  */
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
- ];
236
+ export const FALLBACK_PROVIDER_MODELS: readonly AgyProviderModelEntry[] = [];
239
237
 
240
238
  /**
241
239
  * Plain provider model definition (structurally compatible with Pi's
@@ -1,4 +1,4 @@
1
- import { randomBytes } from "node:crypto";
1
+ import { createHash, randomBytes } from "node:crypto";
2
2
  import { chmod, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
3
3
  import * as os from "node:os";
4
4
  import * as path from "node:path";
@@ -83,15 +83,20 @@ export function imageExtension(mimeType: string): string {
83
83
  return IMAGE_EXTENSIONS[mimeType.toLowerCase()] ?? "bin";
84
84
  }
85
85
 
86
- /** Collect image blocks in transcript order, optionally only one tool result. */
86
+ /** Collect image blocks in transcript order, optionally only matching tool result(s). */
87
87
  export function collectImageBlocks(
88
88
  messages: ProviderTranscriptMessage[],
89
- onlyToolCallId?: string,
89
+ onlyToolCallId?: string | ReadonlySet<string>,
90
90
  ): PromptImageBlock[] {
91
91
  const blocks: PromptImageBlock[] = [];
92
92
  for (const message of messages) {
93
93
  if (onlyToolCallId !== undefined) {
94
- if (message.role !== "toolResult" || message.toolCallId !== onlyToolCallId) continue;
94
+ if (message.role !== "toolResult") continue;
95
+ if (typeof onlyToolCallId === "string") {
96
+ if (message.toolCallId !== onlyToolCallId) continue;
97
+ } else if (!message.toolCallId || !onlyToolCallId.has(message.toolCallId)) {
98
+ continue;
99
+ }
95
100
  }
96
101
  const content = message.content;
97
102
  if (!Array.isArray(content)) continue;
@@ -209,42 +214,115 @@ export async function clearImageStaging(): Promise<void> {
209
214
  }
210
215
  }
211
216
 
217
+ function formatHistoryEntry(
218
+ message: ProviderTranscriptMessage,
219
+ imageRef: (block: object) => string | undefined,
220
+ ): string | undefined {
221
+ const text = clip(textOfContent(message.content, imageRef).trim(), MAX_MESSAGE_CHARS);
222
+ if (!text) return undefined;
223
+ let label: string;
224
+ if (message.role === "user") label = "User";
225
+ else if (message.role === "assistant") label = "Assistant (previous turn)";
226
+ else if (message.role === "toolResult") {
227
+ label = `Tool result (${message.toolName ?? "tool"}${message.isError ? ", error" : ""})`;
228
+ } else if (message.role === "system") label = "System";
229
+ else label = message.role;
230
+ return `${label}: ${text}`;
231
+ }
232
+
233
+ function makeImageRef(imagePaths?: Map<object, string>): (block: object) => string | undefined {
234
+ return (block: object): string | undefined => {
235
+ const file = imagePaths?.get(block);
236
+ return file
237
+ ? `[attached image saved at ${file} — open it with your file tools to view it]`
238
+ : undefined;
239
+ };
240
+ }
241
+
212
242
  /**
213
- * Render Pi transcript messages into a single agy `-p` prompt. The latest
214
- * user message is authoritative; earlier history is bounded reference. Pi
215
- * tool definitions are intentionally NOT translated — agy runs its own tool
216
- * loop (see the module wall note).
243
+ * Deterministic fingerprint of a transcript prefix so resumed turns can
244
+ * detect compaction, /tree rewinds, replaced replies, or edited history
245
+ * (including image payloads and tool-call arguments) and fall back to a
246
+ * full prompt instead of sending a delta.
247
+ */
248
+ export function transcriptFingerprint(messages: readonly ProviderTranscriptMessage[]): string {
249
+ const hash = createHash("sha256");
250
+ const mix = (value: string): void => {
251
+ hash.update(value);
252
+ hash.update("\u001f");
253
+ };
254
+ for (const message of messages) {
255
+ mix(message.role);
256
+ if (message.toolCallId) mix(`id:${message.toolCallId}`);
257
+ if (message.toolName) mix(`tool:${message.toolName}`);
258
+ if (message.isError) mix("err:1");
259
+ const content = message.content;
260
+ if (typeof content === "string") {
261
+ mix(`t:${content}`);
262
+ } else if (Array.isArray(content)) {
263
+ for (const block of content) {
264
+ if (typeof block === "string") {
265
+ mix(`t:${block}`);
266
+ } else if (block && typeof block === "object") {
267
+ const record = block as Record<string, unknown>;
268
+ if (record.type === "text" && typeof record.text === "string") {
269
+ mix(`t:${record.text}`);
270
+ } else if (record.type === "thinking" && typeof record.thinking === "string") {
271
+ mix(`th:${record.thinking}`);
272
+ } else if (record.type === "image") {
273
+ mix(`img:${String(record.mimeType ?? "")}:${String(record.data ?? "")}`);
274
+ } else if (record.type === "toolCall") {
275
+ let serializedArgs = "";
276
+ try {
277
+ serializedArgs = JSON.stringify(record.arguments ?? {});
278
+ } catch {
279
+ serializedArgs = "[unserializable]";
280
+ }
281
+ mix(`tc:${String(record.id ?? "")}:${String(record.name ?? "")}:${serializedArgs}`);
282
+ }
283
+ }
284
+ }
285
+ }
286
+ hash.update("\u001e");
287
+ }
288
+ return `m${messages.length}-${hash.digest("hex").slice(0, 16)}`;
289
+ }
290
+
291
+ export interface RenderProviderPromptOptions {
292
+ /** Active bridged Pi tool names exposed via the pi-agy-tools MCP server. */
293
+ bridgedToolNames?: readonly string[];
294
+ }
295
+
296
+ /**
297
+ * Render Pi transcript messages into a full agy turn prompt (used for fresh
298
+ * conversations, model switches, compaction, or /tree rewinds). The latest
299
+ * message is authoritative; earlier history is bounded reference. Active Pi
300
+ * tools are bridged over the localhost `pi-agy-tools` MCP server.
217
301
  */
218
302
  export function renderProviderPrompt(
219
303
  messages: ProviderTranscriptMessage[],
220
304
  systemPrompt?: string,
221
305
  imagePaths?: Map<object, string>,
306
+ options?: RenderProviderPromptOptions,
222
307
  ): string {
223
- const imageRef = (block: object): string | undefined => {
224
- const file = imagePaths?.get(block);
225
- return file
226
- ? `[attached image saved at ${file} — open it with your file tools to view it]`
227
- : undefined;
228
- };
308
+ const imageRef = makeImageRef(imagePaths);
229
309
  const lines: string[] = [];
230
310
  if (systemPrompt?.trim()) {
231
311
  lines.push("System instructions:", clip(systemPrompt.trim(), MAX_SYSTEM_CHARS), "");
232
312
  }
313
+ if (options?.bridgedToolNames && options.bridgedToolNames.length > 0) {
314
+ lines.push(
315
+ `Pi tool bridge (pi-agy-tools MCP server): ${options.bridgedToolNames.join(", ")}.`,
316
+ "Prefer these pi-agy-tools MCP tools over built-in workspace file/shell tools so Pi can render native tool cards, run approval gates, and track touched files.",
317
+ "",
318
+ );
319
+ }
233
320
  const history = messages.slice(0, -1);
234
321
  const rendered: string[] = [];
235
322
  let budget = MAX_HISTORY_CHARS;
236
323
  for (let i = history.length - 1; i >= 0 && budget > 0; i--) {
237
- const message = history[i];
238
- const text = clip(textOfContent(message.content, imageRef).trim(), MAX_MESSAGE_CHARS);
239
- if (!text) continue;
240
- let label: string;
241
- if (message.role === "user") label = "User";
242
- else if (message.role === "assistant") label = "Assistant (previous turn)";
243
- else if (message.role === "toolResult") {
244
- label = `Tool result (${message.toolName ?? "tool"}${message.isError ? ", error" : ""})`;
245
- } else if (message.role === "system") label = "System";
246
- else label = message.role;
247
- const entry = `${label}: ${text}`;
324
+ const entry = formatHistoryEntry(history[i], imageRef);
325
+ if (!entry) continue;
248
326
  if (entry.length > budget) break;
249
327
  budget -= entry.length;
250
328
  rendered.unshift(entry);
@@ -258,3 +336,37 @@ export function renderProviderPrompt(
258
336
  lines.push(currentLabel, current || "(empty — respond with a brief acknowledgement)");
259
337
  return lines.join("\n");
260
338
  }
339
+
340
+ /**
341
+ * Render only the new delta messages for an already-synced resumed agy
342
+ * conversation, avoiding redundant system prompt and transcript replay.
343
+ */
344
+ export function renderProviderDeltaPrompt(
345
+ deltaMessages: ProviderTranscriptMessage[],
346
+ imagePaths?: Map<object, string>,
347
+ ): string {
348
+ const imageRef = makeImageRef(imagePaths);
349
+ if (deltaMessages.length === 1 && deltaMessages[0].role === "user") {
350
+ const current = textOfContent(deltaMessages[0].content, imageRef).trim();
351
+ return current || "(empty — respond with a brief acknowledgement)";
352
+ }
353
+ const lines: string[] = [];
354
+ const earlier = deltaMessages.slice(0, -1);
355
+ const rendered: string[] = [];
356
+ let budget = MAX_HISTORY_CHARS;
357
+ for (let i = earlier.length - 1; i >= 0 && budget > 0; i--) {
358
+ const entry = formatHistoryEntry(earlier[i], imageRef);
359
+ if (!entry) continue;
360
+ if (entry.length > budget) break;
361
+ budget -= entry.length;
362
+ rendered.unshift(entry);
363
+ }
364
+ if (rendered.length > 0) {
365
+ lines.push("Additional context since last turn:", ...rendered, "");
366
+ }
367
+ const last = deltaMessages[deltaMessages.length - 1];
368
+ const current = last ? textOfContent(last.content, imageRef).trim() : "";
369
+ const currentLabel = last && last.role !== "user" ? `Current message (${last.role}):` : "Current message:";
370
+ lines.push(currentLabel, current || "(empty — respond with a brief acknowledgement)");
371
+ return lines.join("\n");
372
+ }
@@ -1,4 +1,19 @@
1
- import { toSafeBridgeName, type BridgeToolDef } from "./provider-mcp.js";
1
+ /** A Pi tool projected for agy: MCP-safe advertised name, real Pi identity. */
2
+ export interface BridgeToolDef {
3
+ name: string;
4
+ piName: string;
5
+ description: string;
6
+ inputSchema: Record<string, unknown>;
7
+ }
8
+
9
+ /** MCP tool names: [a-zA-Z0-9_-]{1,64}. Pi names are sanitized into that. */
10
+ function toSafeBridgeName(name: string): string {
11
+ const safe = name
12
+ .replace(/[^a-zA-Z0-9_-]+/g, "_")
13
+ .replace(/^_+|_+$/g, "")
14
+ .slice(0, 64);
15
+ return safe || "tool";
16
+ }
2
17
 
3
18
  /** Pi tool source shape (structural subset of Pi's ToolInfo). */
4
19
  export interface ProviderToolSource {