@juanbenjumea/pi-agy 0.7.6 → 0.7.8

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.
@@ -1,3 +1,5 @@
1
+ import * as path from "node:path";
2
+
1
3
  import {
2
4
  checkAgyConnectivity,
3
5
  checkAgyHealth,
@@ -8,9 +10,32 @@ import {
8
10
  const TTL_MS = 5 * 60 * 1000;
9
11
  const USAGE_TTL_MS = 60 * 1000;
10
12
  const USAGE_FAILURE_TTL_MS = 5 * 1000;
11
- let cachedAt = 0;
12
- let cachedUsageAt = 0;
13
- let cachedUsage: AgyUsageSnapshot | undefined;
13
+
14
+ interface PreflightEntry {
15
+ healthAt: number;
16
+ usageAt: number;
17
+ usage?: AgyUsageSnapshot;
18
+ }
19
+
20
+ // Per-directory: health/quota answers depend on the working directory, so a
21
+ // single global entry would serve dir B dir A's snapshot. Bounded so long
22
+ // sessions across many checkouts cannot grow the map without limit.
23
+ const MAX_CACHED_DIRS = 32;
24
+ const entries = new Map<string, PreflightEntry>();
25
+
26
+ function entryFor(cwd: string): PreflightEntry {
27
+ const key = path.resolve(cwd);
28
+ let entry = entries.get(key);
29
+ if (!entry) {
30
+ entry = { healthAt: 0, usageAt: 0, usage: undefined };
31
+ entries.set(key, entry);
32
+ if (entries.size > MAX_CACHED_DIRS) {
33
+ const oldest = entries.keys().next();
34
+ if (!oldest.done) entries.delete(oldest.value);
35
+ }
36
+ }
37
+ return entry;
38
+ }
14
39
 
15
40
  /** Run cached health/model checks and a shorter-lived model quota refresh. */
16
41
  export async function runPreflight(
@@ -18,11 +43,13 @@ export async function runPreflight(
18
43
  signal?: AbortSignal,
19
44
  timeoutMs?: number,
20
45
  ): Promise<AgyUsageSnapshot | undefined> {
46
+ const entry = entryFor(cwd);
21
47
  const now = Date.now();
22
- const healthFresh = cachedAt > 0 && now - cachedAt < TTL_MS;
23
- const usageTtl = cachedUsage?.error || !cachedUsage ? USAGE_FAILURE_TTL_MS : USAGE_TTL_MS;
24
- const usageFresh = cachedUsageAt > 0 && now - cachedUsageAt < usageTtl;
25
- if (healthFresh && usageFresh) return cachedUsage;
48
+ const healthFresh = entry.healthAt > 0 && now - entry.healthAt < TTL_MS;
49
+ const usageTtl =
50
+ entry.usage?.error || !entry.usage ? USAGE_FAILURE_TTL_MS : USAGE_TTL_MS;
51
+ const usageFresh = entry.usageAt > 0 && now - entry.usageAt < usageTtl;
52
+ if (healthFresh && usageFresh) return entry.usage;
26
53
  if (timeoutMs !== undefined && timeoutMs <= 0) {
27
54
  throw new Error("agy timed out before preflight");
28
55
  }
@@ -30,14 +57,16 @@ export async function runPreflight(
30
57
  const health = healthFresh
31
58
  ? Promise.resolve()
32
59
  : runHealthWithRetry(cwd, signal, timeoutMs).then(() => undefined);
33
- const usage = usageFresh ? Promise.resolve(cachedUsage) : checkAgyUsage(cwd, signal, timeoutMs);
60
+ const usage = usageFresh
61
+ ? Promise.resolve(entry.usage)
62
+ : checkAgyUsage(cwd, signal, timeoutMs);
34
63
  const [, refreshedUsage] = await Promise.all([health, usage]);
35
- if (!healthFresh) cachedAt = Date.now();
64
+ if (!healthFresh) entry.healthAt = Date.now();
36
65
  if (!usageFresh) {
37
- cachedUsage = refreshedUsage;
38
- cachedUsageAt = Date.now();
66
+ entry.usage = refreshedUsage;
67
+ entry.usageAt = Date.now();
39
68
  }
40
- return cachedUsage;
69
+ return entry.usage;
41
70
  }
42
71
 
43
72
  /**
@@ -73,7 +102,5 @@ async function runHealthWithRetry(
73
102
 
74
103
  /** Test helper — reset the in-process cache. */
75
104
  export function resetPreflightCache(): void {
76
- cachedAt = 0;
77
- cachedUsageAt = 0;
78
- cachedUsage = undefined;
105
+ entries.clear();
79
106
  }
@@ -41,12 +41,22 @@ import {
41
41
  type AgyProviderModelEntry,
42
42
  } from "./provider-models.js";
43
43
  import { getHistory } from "./sessions.js";
44
+ import {
45
+ ACTIVATE_SKILL_TOOL_NAME,
46
+ formatSkillsSummary,
47
+ readSkillContent,
48
+ scanSkills,
49
+ type SkillEntry,
50
+ } from "./skills.js";
44
51
  import { runPreflightCommand } from "./spawn.js";
45
52
 
46
53
  export const BRIDGE_MCP_KEY = "pi-agy-tools";
47
- /** Built-in read-only tools (sessions, quota, catalog), plus dynamic bridged Pi tools. */
48
- const BUILTIN_TOOL_COUNT = 3;
54
+ /** Built-in read-only tools (sessions, quota, catalog, activate_skill, bridge_poll_result), plus dynamic bridged Pi tools. */
55
+ const BUILTIN_TOOL_COUNT = 5;
49
56
  export const BRIDGE_TOKEN_HEADER = "x-pi-agy-token";
57
+ export const POLL_TOOL_NAME = "bridge_poll_result";
58
+ /** Async escalation threshold: park requests longer than this early-ack so agy's 180s timeout is avoided. */
59
+ export const DEFAULT_PARK_ESCALATE_MS = 20_000;
50
60
  const BRIDGE_MCP_PATH = "/mcp";
51
61
  const MAX_BODY_BYTES = 1024 * 1024;
52
62
  const CATALOG_TTL_MS = 5 * 60_000;
@@ -205,12 +215,20 @@ interface CatalogCache {
205
215
  at: number;
206
216
  }
207
217
 
218
+ export interface StartMcpBridgeOptions {
219
+ escalateAfterMs?: number;
220
+ }
221
+
208
222
  /**
209
223
  * Start the bridge for a workspace directory. Never throws: any failure
210
224
  * cleans up and resolves `undefined` so provider turns proceed plain.
211
225
  */
212
- export async function startMcpBridge(dir: string): Promise<McpBridgeHandle | undefined> {
226
+ export async function startMcpBridge(
227
+ dir: string,
228
+ options?: StartMcpBridgeOptions,
229
+ ): Promise<McpBridgeHandle | undefined> {
213
230
  const token = randomBytes(32).toString("hex");
231
+ const escalateAfterMs = options?.escalateAfterMs ?? DEFAULT_PARK_ESCALATE_MS;
214
232
  let catalogCache: CatalogCache | undefined;
215
233
 
216
234
  const mcp = new McpServer(
@@ -221,45 +239,78 @@ export async function startMcpBridge(dir: string): Promise<McpBridgeHandle | und
221
239
  let bridgedTools: BridgeToolDef[] = [];
222
240
  let parkHandler: BridgeParkHandler | undefined;
223
241
  const parks = new Map<string, (result: BridgeToolResult) => void>();
242
+ const escalations = new Map<
243
+ string,
244
+ { name: string; state: "running" | "done" | "failed"; result?: BridgeToolResult; reason?: string }
245
+ >();
224
246
 
225
- mcp.setRequestHandler(ListToolsRequestSchema, () => ({
226
- tools: [
227
- ...bridgedTools.map((tool) => ({
228
- name: tool.name,
229
- description: `${tool.description} (Pi tool: runs with Pi permissions and review.)`,
230
- inputSchema: tool.inputSchema,
231
- })),
232
- {
233
- name: "agy_sessions_list",
234
- description:
235
- "List recorded agy conversations for a directory (ids, models, ages, summaries) to find a conversation to resume. Read-only.",
236
- inputSchema: {
237
- type: "object",
238
- properties: {
239
- dir: { type: "string", description: "Directory to list. Defaults to the current workspace." },
240
- limit: { type: "number", description: "Maximum entries (default 10, max 10)." },
247
+ mcp.setRequestHandler(ListToolsRequestSchema, () => {
248
+ const skills = scanSkills(dir);
249
+ return {
250
+ tools: [
251
+ ...bridgedTools.map((tool) => ({
252
+ name: tool.name,
253
+ description: `${tool.description} (Pi tool: runs with Pi permissions and review. Long calls over 20s report STILL RUNNING; fetch via ${POLL_TOOL_NAME}.)`,
254
+ inputSchema: tool.inputSchema,
255
+ })),
256
+ {
257
+ name: "agy_sessions_list",
258
+ description:
259
+ "List recorded agy conversations for a directory (ids, models, ages, summaries) to find a conversation to resume. Read-only.",
260
+ inputSchema: {
261
+ type: "object",
262
+ properties: {
263
+ dir: { type: "string", description: "Directory to list. Defaults to the current workspace." },
264
+ limit: { type: "number", description: "Maximum entries (default 10, max 10)." },
265
+ },
241
266
  },
242
267
  },
243
- },
244
- {
245
- name: "agy_quota_report",
246
- description:
247
- "Read current Antigravity model quotas and reset times without spending a model turn. Read-only.",
248
- inputSchema: {
249
- type: "object",
250
- properties: {
251
- model: { type: "string", description: "Optional agy model slug to focus the report." },
268
+ {
269
+ name: "agy_quota_report",
270
+ description:
271
+ "Read current Antigravity model quotas and reset times without spending a model turn. Read-only.",
272
+ inputSchema: {
273
+ type: "object",
274
+ properties: {
275
+ model: { type: "string", description: "Optional agy model slug to focus the report." },
276
+ },
252
277
  },
253
278
  },
254
- },
255
- {
256
- name: "agy_model_catalog",
257
- description:
258
- "List agy models available to this workspace as Pi picker entries (id, agy --model value, effort tiers). Read-only.",
259
- inputSchema: { type: "object", properties: {} },
260
- },
261
- ],
262
- }));
279
+ {
280
+ name: "agy_model_catalog",
281
+ description:
282
+ "List agy models available to this workspace as Pi picker entries (id, agy --model value, effort tiers). Read-only.",
283
+ inputSchema: { type: "object", properties: {} },
284
+ },
285
+ {
286
+ name: ACTIVATE_SKILL_TOOL_NAME,
287
+ description: `Activate a Pi Agent Skill to read its full instructions (SKILL.md). Available skills:\n${formatSkillsSummary(skills)}`,
288
+ inputSchema: {
289
+ type: "object",
290
+ properties: {
291
+ name: {
292
+ type: "string",
293
+ description: "Skill name to activate from the catalog.",
294
+ },
295
+ },
296
+ required: ["name"],
297
+ },
298
+ },
299
+ {
300
+ name: POLL_TOOL_NAME,
301
+ description:
302
+ "Poll the result of a long-running bridged Pi tool call that returned STILL RUNNING.",
303
+ inputSchema: {
304
+ type: "object",
305
+ properties: {
306
+ callId: { type: "string", description: "Call ID returned in the STILL RUNNING message." },
307
+ },
308
+ required: ["callId"],
309
+ },
310
+ },
311
+ ],
312
+ };
313
+ });
263
314
 
264
315
  mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
265
316
  try {
@@ -300,6 +351,52 @@ export async function startMcpBridge(dir: string): Promise<McpBridgeHandle | und
300
351
  `agy models${entries.fallback ? " (fallback catalog — live discovery unavailable)" : ""}:\n${lines.join("\n")}`,
301
352
  );
302
353
  }
354
+ if (name === ACTIVATE_SKILL_TOOL_NAME) {
355
+ const skillName = stringArg(args.name);
356
+ if (!skillName) {
357
+ return toolText("Error: skill 'name' argument is required.", true);
358
+ }
359
+ const skills = scanSkills(dir);
360
+ const found = skills.find((s) => s.name === skillName);
361
+ if (!found) {
362
+ return toolText(`Unknown skill: "${skillName}". Available skills:\n${formatSkillsSummary(skills)}`, true);
363
+ }
364
+ const body = readSkillContent(found);
365
+ return toolText(body);
366
+ }
367
+ if (name === POLL_TOOL_NAME) {
368
+ const callId = stringArg(args.callId);
369
+ if (!callId) {
370
+ return toolText("Error: 'callId' argument is required.", true);
371
+ }
372
+ const record = escalations.get(callId);
373
+ if (!record) {
374
+ return toolText(
375
+ `Error: no escalated bridge call "${callId}". It either finished synchronously or the callId is invalid.`,
376
+ true,
377
+ );
378
+ }
379
+ if (record.state === "running") {
380
+ return toolText(
381
+ `STILL RUNNING: Pi tool "${record.name}" (callId ${callId}) has not finished yet. Poll again shortly.`,
382
+ false,
383
+ );
384
+ }
385
+ if (record.state === "failed") {
386
+ escalations.delete(callId);
387
+ return toolText(
388
+ `Error: Pi tool "${record.name}" failed: ${record.reason ?? "unknown failure"}`,
389
+ true,
390
+ );
391
+ }
392
+ // Delivered done result; clean up escalation entry.
393
+ escalations.delete(callId);
394
+ const result = record.result;
395
+ return {
396
+ content: [{ type: "text" as const, text: result?.text ?? "(no output)" }],
397
+ ...(result?.isError ? { isError: true as const } : {}),
398
+ };
399
+ }
303
400
  const bridged = bridgedTools.find((tool) => tool.name === name);
304
401
  if (bridged) {
305
402
  const callArgs =
@@ -311,8 +408,21 @@ export async function startMcpBridge(dir: string): Promise<McpBridgeHandle | und
311
408
  if (!handler) {
312
409
  return toolText("Pi tool bridge is not awaiting calls right now; retry shortly.", true);
313
410
  }
411
+ let escalateTimer: NodeJS.Timeout | undefined;
412
+ let didEscalate = false;
314
413
  const parked = await new Promise<BridgeToolResult | undefined>((resolve) => {
315
- parks.set(callId, resolve);
414
+ parks.set(callId, (res) => {
415
+ if (escalateTimer) clearTimeout(escalateTimer);
416
+ if (didEscalate) {
417
+ const record = escalations.get(callId);
418
+ if (record) {
419
+ record.state = "done";
420
+ record.result = res;
421
+ }
422
+ } else {
423
+ resolve(res);
424
+ }
425
+ });
316
426
  let accepted = false;
317
427
  try {
318
428
  accepted = handler({ callId, toolName: bridged.piName, args: callArgs });
@@ -322,7 +432,22 @@ export async function startMcpBridge(dir: string): Promise<McpBridgeHandle | und
322
432
  if (!accepted) {
323
433
  parks.delete(callId);
324
434
  resolve(undefined);
435
+ return;
325
436
  }
437
+ // Early-ack escalation: if the tool runs longer than escalateAfterMs,
438
+ // settle the MCP request with STILL RUNNING so agy avoids its 180s timeout.
439
+ escalateTimer = setTimeout(() => {
440
+ didEscalate = true;
441
+ escalations.set(callId, { name: bridged.piName, state: "running" });
442
+ resolve({
443
+ text: [
444
+ `STILL RUNNING: the Pi tool "${bridged.piName}" has not finished yet.`,
445
+ `Call ${POLL_TOOL_NAME} with callId "${callId}" to fetch the result. Poll again if it is still running; you may perform other tasks in between.`,
446
+ ].join("\n"),
447
+ isError: false,
448
+ });
449
+ }, escalateAfterMs);
450
+ (escalateTimer as unknown as { unref?: () => void }).unref?.();
326
451
  });
327
452
  if (!parked) {
328
453
  return toolText("Pi turn is not awaiting tool calls; the call was not executed.", true);
@@ -380,6 +505,12 @@ export async function startMcpBridge(dir: string): Promise<McpBridgeHandle | und
380
505
  });
381
506
 
382
507
  const failAllParks = (message: string): void => {
508
+ for (const [callId, rec] of escalations) {
509
+ if (rec.state === "running") {
510
+ rec.state = "failed";
511
+ rec.reason = message;
512
+ }
513
+ }
383
514
  if (parks.size === 0) return;
384
515
  const pending = [...parks.values()];
385
516
  parks.clear();
@@ -393,6 +524,13 @@ export async function startMcpBridge(dir: string): Promise<McpBridgeHandle | und
393
524
  };
394
525
 
395
526
  const completePark = (callId: string, result: BridgeToolResult): boolean => {
527
+ const esc = escalations.get(callId);
528
+ if (esc && esc.state === "running") {
529
+ esc.state = "done";
530
+ esc.result = result;
531
+ parks.delete(callId);
532
+ return true;
533
+ }
396
534
  const resolve = parks.get(callId);
397
535
  if (!resolve) return false;
398
536
  parks.delete(callId);
@@ -0,0 +1,260 @@
1
+ import { randomBytes } from "node:crypto";
2
+ import { chmod, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
3
+ import * as os from "node:os";
4
+ import * as path from "node:path";
5
+
6
+ /** Bounds for transcript rendering into a single turn prompt. */
7
+ const MAX_HISTORY_CHARS = 24_000;
8
+ const MAX_SYSTEM_CHARS = 8_000;
9
+ const MAX_MESSAGE_CHARS = 6_000;
10
+
11
+ /** Minimal structural transcript message (subset of Pi's Message). */
12
+ export interface ProviderTranscriptMessage {
13
+ role: string;
14
+ content?: unknown;
15
+ toolName?: string;
16
+ toolCallId?: string;
17
+ isError?: boolean;
18
+ }
19
+
20
+ export function textOfContent(content: unknown, imagePath?: (block: object) => string | undefined): string {
21
+ if (typeof content === "string") return content;
22
+ if (Array.isArray(content)) {
23
+ const parts: string[] = [];
24
+ for (const block of content) {
25
+ if (typeof block === "string") {
26
+ parts.push(block);
27
+ } else if (block && typeof block === "object") {
28
+ const record = block as Record<string, unknown>;
29
+ if (record.type === "text" && typeof record.text === "string") {
30
+ parts.push(record.text);
31
+ } else if (record.type === "image") {
32
+ const staged = imagePath?.(block);
33
+ parts.push(
34
+ staged ?? "[image omitted: agy provider turns are text-only]",
35
+ );
36
+ } else if (record.type === "toolCall") {
37
+ parts.push(`[tool call: ${String(record.name ?? "unknown")}]`);
38
+ } else if (record.type === "thinking" && typeof record.thinking === "string") {
39
+ parts.push(record.thinking);
40
+ }
41
+ }
42
+ }
43
+ return parts.join("\n");
44
+ }
45
+ return "";
46
+ }
47
+
48
+ function clip(text: string, max: number): string {
49
+ if (text.length <= max) return text;
50
+ return text.slice(0, max - 1) + "…";
51
+ }
52
+
53
+ export interface PromptImageBlock {
54
+ /** Identity of the transcript block (lookup key, never serialized). */
55
+ block: object;
56
+ data: string;
57
+ mimeType: string;
58
+ }
59
+
60
+ export interface StagedImages {
61
+ /** Per-turn subdir, undefined when nothing stageable. */
62
+ dir: string | undefined;
63
+ /** Block identity → absolute path (order-independent lookup). */
64
+ paths: Map<object, string>;
65
+ /** Remove this staging (idempotent, never throws). */
66
+ cleanup: () => Promise<void>;
67
+ }
68
+
69
+ /** Cap staged images per invocation (count and per-file size). */
70
+ export const MAX_STAGED_IMAGES = 8;
71
+ export const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
72
+
73
+ const IMAGE_EXTENSIONS: Record<string, string> = {
74
+ "image/png": "png",
75
+ "image/jpeg": "jpg",
76
+ "image/webp": "webp",
77
+ "image/gif": "gif",
78
+ "image/bmp": "bmp",
79
+ "image/svg+xml": "svg",
80
+ };
81
+
82
+ export function imageExtension(mimeType: string): string {
83
+ return IMAGE_EXTENSIONS[mimeType.toLowerCase()] ?? "bin";
84
+ }
85
+
86
+ /** Collect image blocks in transcript order, optionally only one tool result. */
87
+ export function collectImageBlocks(
88
+ messages: ProviderTranscriptMessage[],
89
+ onlyToolCallId?: string,
90
+ ): PromptImageBlock[] {
91
+ const blocks: PromptImageBlock[] = [];
92
+ for (const message of messages) {
93
+ if (onlyToolCallId !== undefined) {
94
+ if (message.role !== "toolResult" || message.toolCallId !== onlyToolCallId) continue;
95
+ }
96
+ const content = message.content;
97
+ if (!Array.isArray(content)) continue;
98
+ for (const block of content) {
99
+ if (typeof block !== "object" || block === null) continue;
100
+ const record = block as Record<string, unknown>;
101
+ if (record.type !== "image") continue;
102
+ if (typeof record.data !== "string" || typeof record.mimeType !== "string") continue;
103
+ blocks.push({ block, data: record.data, mimeType: record.mimeType });
104
+ }
105
+ }
106
+ return blocks;
107
+ }
108
+
109
+ /** Strict base64 (Node's decoder silently strips non-alphabet chars). */
110
+ const STRICT_BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
111
+
112
+ function decodeImageData(data: string): Buffer | undefined {
113
+ if (typeof data !== "string" || data.length === 0 || data.length % 4 !== 0) return undefined;
114
+ if (!STRICT_BASE64_RE.test(data)) return undefined;
115
+ try {
116
+ const bytes = Buffer.from(data, "base64");
117
+ if (bytes.length === 0 || bytes.length > MAX_IMAGE_BYTES) return undefined;
118
+ return bytes;
119
+ } catch {
120
+ return undefined;
121
+ }
122
+ }
123
+
124
+ /** Process-stable staging root (0700): per-turn subdirs, one --add-dir. */
125
+ let imageStagingRoot: string | undefined;
126
+
127
+ /** Live staging dirs (teardown sweep; per-turn cleanup disposes handles). */
128
+ const liveStagingDirs = new Set<string>();
129
+
130
+ export function getLiveImageStagingCount(): number {
131
+ return liveStagingDirs.size;
132
+ }
133
+
134
+ /** Resolve (creating once) the process staging root for agy --add-dir. */
135
+ export async function ensureImageStagingRoot(): Promise<string> {
136
+ if (!imageStagingRoot) {
137
+ // mkdtemp (not join+mkdir): atomic, unique, 0700 — no pre-creation or
138
+ // symlink race between check and creation.
139
+ imageStagingRoot = await mkdtemp(path.join(os.tmpdir(), "pi-agy-images-"));
140
+ try {
141
+ await chmod(imageStagingRoot, 0o700);
142
+ } catch {
143
+ // mkdtemp already guarantees 0700; best effort.
144
+ }
145
+ }
146
+ return imageStagingRoot;
147
+ }
148
+
149
+ /**
150
+ * Materialize image blocks as files agy's tools can open. Newest transcript
151
+ * images win (oldest starve first) so a fresh attachment is never dropped
152
+ * behind history. Failures degrade to omitted notes, never to turn
153
+ * failures. Each call owns its subdir; dispose via the returned cleanup.
154
+ */
155
+ export async function stageImages(blocks: PromptImageBlock[]): Promise<StagedImages> {
156
+ const paths = new Map<object, string>();
157
+ const noop = async (): Promise<void> => undefined;
158
+ const bounded = blocks.slice(-MAX_STAGED_IMAGES);
159
+ if (bounded.length === 0) return { dir: undefined, paths, cleanup: noop };
160
+ let root: string;
161
+ try {
162
+ root = await ensureImageStagingRoot();
163
+ } catch {
164
+ return { dir: undefined, paths, cleanup: noop };
165
+ }
166
+ const dir = path.join(root, randomBytes(8).toString("hex"));
167
+ try {
168
+ await mkdir(dir, { mode: 0o700 });
169
+ } catch {
170
+ return { dir: undefined, paths, cleanup: noop };
171
+ }
172
+ liveStagingDirs.add(dir);
173
+ let cleaned = false;
174
+ const cleanup = async (): Promise<void> => {
175
+ if (cleaned) return;
176
+ cleaned = true;
177
+ liveStagingDirs.delete(dir);
178
+ await rm(dir, { recursive: true, force: true }).catch(() => undefined);
179
+ };
180
+ for (let index = 0; index < bounded.length; index++) {
181
+ const block = bounded[index];
182
+ const bytes = decodeImageData(block.data);
183
+ if (!bytes) continue;
184
+ const file = path.join(dir, `image-${index}.${imageExtension(block.mimeType)}`);
185
+ try {
186
+ await writeFile(file, bytes, { mode: 0o600 });
187
+ await chmod(file, 0o600);
188
+ } catch {
189
+ continue;
190
+ }
191
+ paths.set(block.block, file);
192
+ }
193
+ if (paths.size === 0) {
194
+ await cleanup();
195
+ return { dir: undefined, paths, cleanup: noop };
196
+ }
197
+ return { dir, paths, cleanup };
198
+ }
199
+
200
+ /** Remove every staging dir and the root (teardown, tests). */
201
+ export async function clearImageStaging(): Promise<void> {
202
+ const dirs = [...liveStagingDirs];
203
+ liveStagingDirs.clear();
204
+ await Promise.all(dirs.map((dir) => rm(dir, { recursive: true, force: true }).catch(() => undefined)));
205
+ if (imageStagingRoot) {
206
+ const root = imageStagingRoot;
207
+ imageStagingRoot = undefined;
208
+ await rm(root, { recursive: true, force: true }).catch(() => undefined);
209
+ }
210
+ }
211
+
212
+ /**
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).
217
+ */
218
+ export function renderProviderPrompt(
219
+ messages: ProviderTranscriptMessage[],
220
+ systemPrompt?: string,
221
+ imagePaths?: Map<object, string>,
222
+ ): 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
+ };
229
+ const lines: string[] = [];
230
+ if (systemPrompt?.trim()) {
231
+ lines.push("System instructions:", clip(systemPrompt.trim(), MAX_SYSTEM_CHARS), "");
232
+ }
233
+ const history = messages.slice(0, -1);
234
+ const rendered: string[] = [];
235
+ let budget = MAX_HISTORY_CHARS;
236
+ 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}`;
248
+ if (entry.length > budget) break;
249
+ budget -= entry.length;
250
+ rendered.unshift(entry);
251
+ }
252
+ if (rendered.length > 0) {
253
+ lines.push("Conversation history (reference only; the current message is authoritative):", ...rendered, "");
254
+ }
255
+ const last = messages[messages.length - 1];
256
+ const current = last ? textOfContent(last.content, imageRef).trim() : "";
257
+ const currentLabel = last && last.role !== "user" ? `Current message (${last.role}):` : "Current message:";
258
+ lines.push(currentLabel, current || "(empty — respond with a brief acknowledgement)");
259
+ return lines.join("\n");
260
+ }