pi-agy-provider 1.1.1 → 1.1.3

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.
package/README.md CHANGED
@@ -27,10 +27,14 @@ Update anytime with `pi update npm:pi-agy-provider`.
27
27
  | `/teamwork [idea]` | **Teamwork** | Two-phase workflow: refines `prompt_draft.md` with you first, then launches autonomous specialist teammates (`on\|off\|status`). |
28
28
  | `/goal <task>` | **Goal** | Autonomous multi-turn loop with self-auditing continuations until the objective completes (`/goal off\|status`). |
29
29
  | `/grill-me [plan]` | **Grill** | Dependency-ordered frontier design interview using interactive `ask_user_question` cards (or Markdown fallback) before coding (`/grill`, `on\|off\|status`). |
30
- | `/m <spec> <msg>` | **Consult** | One-shot consult with another model/effort without switching your session model, e.g. `/m opus3 review diff`, `/m argon1 quick check` (alias `/consult`). |
30
+ | `/m <spec> <msg>` | **Consult** | One-shot consult with another model/effort (`1`=low, `2`=medium, `3`=high) without switching your session model, e.g. `/m flash1 commit and push`, `/m opus3 review diff` (alias `/consult`). |
31
31
  | `/btw [prompt]` | **Side chat** | Non-blocking side thread overlay in an isolated runtime (`Esc` / `Alt+m` to minimize, `Alt+/` to restore, `/btw:model`, `/btw:thinking`, `/btw:copy`, `/btw:new`). |
32
32
 
33
- > While `/swarm`, `/boost`, `/teamwork`, or subagents are streaming, pressing `Enter` routes side questions straight into `/btw` instead of stalling in the steer queue (`Alt+Enter` still queues a main-session follow-up).
33
+ > **Tips:**
34
+ > - **Save quota with `/m`:** Offload routine tasks like `/m flash1 commit and push` (Flash with `1` = low thinking) instead of burning your main model's quota, without switching your session model.
35
+ > - **Non-blocking steer:** While `/swarm`, `/boost`, `/teamwork`, or subagents are streaming, pressing `Enter` routes side questions straight into `/btw` instead of stalling in the steer queue (`Alt+Enter` still queues a main-session follow-up).
36
+
37
+ ![/btw side conversation overlay and compact 2-row context footer](assets/btw-overlay.jpg)
34
38
 
35
39
  ## Commands
36
40
 
@@ -38,7 +42,7 @@ Update anytime with `pi update npm:pi-agy-provider`.
38
42
  | --- | --- |
39
43
  | `/agy` | Active conversation ID, model, driver, tool mode, and context status |
40
44
  | `/agy-tools [on\|off\|status]` | Switch between **Pi tools mode** (default, routes work through Pi tools/MCP/permissions) and **native** `agy` tools |
41
- | `/agy-config` | Configure driver (`driver acp\|stream-json\|one-shot`) and 2-row custom context footer (`footer on\|off`) |
45
+ | `/agy-config` | Configure driver (`driver acp\|stream-json\|one-shot`) and toggle the compact 2-row custom footer with context progress bar (`footer on\|off`) |
42
46
  | `/agy-login [method]` | Authenticate `agy` via ACP (`oauth-personal`, `oauth-business`, `gemini-api-key`, `agent-platform`, `status`) |
43
47
  | `/agy-usage` | Live 5-hour & weekly quota bars per model group (zero model tokens spent) |
44
48
  | `/agy-subagents [list]` | Interactive live worker & subagent inspector (plus real-time stack above editor) |
@@ -50,11 +54,14 @@ Update anytime with `pi update npm:pi-agy-provider`.
50
54
  | `/clear [prompt]` / `/agy-reset` | Reset both the `agy` conversation and Pi session (`/agy-reset` drops only the `agy` side) |
51
55
  | `/rename [name]` | Rename the Pi session and sync the title to `agy` conversation metadata |
52
56
 
57
+ ![Live 5-hour and weekly quota bars in /agy-usage](assets/agy-usage.png)
58
+
53
59
  ## Tool Modes & Drivers
54
60
 
55
61
  - **Pi tools mode (`pi-tools:on`, default)**: `agy` runs with native tools disabled and calls your active Pi builtins, extensions, private skills, and MCP servers through a local loopback bridge so Pi's hooks and permissions apply.
56
62
  - **Native mode (`/agy-tools off`)**: `agy` uses its own built-in file/shell/browser tools (read-only steps render as native Pi cards; edits render unified diffs).
57
63
  - **Execution drivers (`/agy-config driver …`)**: Supports warm zero-respawn **`acp`** (native image blocks, live model discovery, cooperative cancel) and persistent **`stream-json`** RPC, with automatic compaction tracking and liveness-aware stall recovery.
64
+ - **Compact 2-row footer (`/agy-config footer on|off`)**: Displays a clean context usage progress bar (`~tokens/limit %`), token/cache stats, model + thinking effort, and `pi-tools` state. Toggle this custom footer style anytime inside `/agy-config` (or `/agy-config footer off` if you prefer another footer extension).
58
65
 
59
66
  > [!WARNING]
60
67
  > In **native tool mode** (`/agy-tools off`), `agy` executes built-in file/shell/browser actions directly with `--dangerously-skip-permissions` before replaying cards to Pi. Keep `pi-tools:on` whenever you want tool calls gated by Pi's permission hooks.
package/index.ts CHANGED
@@ -104,6 +104,7 @@ import {
104
104
  capabilitiesForModel,
105
105
  FALLBACK_MODELS,
106
106
  formatAgyConsultLabel,
107
+ formatConsultCompactionWarning,
107
108
  getAgyConsultCompletions,
108
109
  isAgyModelHidden,
109
110
  mergeAgyModels,
@@ -4368,17 +4369,28 @@ export default function antigravityExtension(pi: ExtensionAPI): void {
4368
4369
  currentEffort,
4369
4370
  ) ?? [];
4370
4371
  const prefix = argumentPrefix.trim().toLowerCase();
4371
- const probedOtherModels = activeSessionCtx
4372
- ? probeCtx(() => listOtherPiModels(activeSessionCtx!.modelRegistry))
4372
+ const probedOtherState = activeSessionCtx
4373
+ ? probeCtx(() => ({
4374
+ models: listOtherPiModels(activeSessionCtx!.modelRegistry),
4375
+ contextTokens: activeSessionCtx!.getContextUsage?.()?.tokens,
4376
+ }))
4373
4377
  : undefined;
4374
- const otherItems = (
4375
- probedOtherModels && !probedOtherModels.stale ? probedOtherModels.value : []
4376
- )
4377
- .map((m) => ({
4378
- value: `${m.provider}/${m.id} `,
4379
- label: `${m.provider}/${m.id}`,
4380
- description: `${m.name || m.id} · pi model`,
4381
- }))
4378
+ const otherState =
4379
+ probedOtherState && !probedOtherState.stale
4380
+ ? probedOtherState.value
4381
+ : { models: [], contextTokens: undefined };
4382
+ const otherItems = otherState.models
4383
+ .map((m) => {
4384
+ const warning = formatConsultCompactionWarning(
4385
+ otherState.contextTokens,
4386
+ m.contextWindow,
4387
+ );
4388
+ return {
4389
+ value: `${m.provider}/${m.id} `,
4390
+ label: `${m.provider}/${m.id}`,
4391
+ description: `${m.name || m.id} · pi model${warning}`,
4392
+ };
4393
+ })
4382
4394
  .filter(
4383
4395
  (item) =>
4384
4396
  !prefix ||
@@ -182,6 +182,18 @@ export interface AcpPromptResponse {
182
182
  _meta?: Record<string, unknown>;
183
183
  }
184
184
 
185
+ export class AgyAcpTimeoutError extends Error {
186
+ readonly method: string;
187
+ readonly timeoutMs: number;
188
+
189
+ constructor(method: string, timeoutMs: number, message: string) {
190
+ super(message);
191
+ this.name = "AgyAcpTimeoutError";
192
+ this.method = method;
193
+ this.timeoutMs = timeoutMs;
194
+ }
195
+ }
196
+
185
197
  export class AgyAcpRpcError extends Error {
186
198
  readonly code: number;
187
199
  readonly data?: unknown;
@@ -439,10 +451,10 @@ export function selectAcpPermissionOutcome(
439
451
  /**
440
452
  * Convert an ACP `PromptResponse` usage payload into `AgyUsage`.
441
453
  *
442
- * Handles both uncached `usage.inputTokens` (`agy acp` 1.5.0 native format, where
443
- * `inputTokens + cachedReadTokens + outputTokens === totalTokens`) and inclusive
444
- * `inputTokens` / `_meta.quota.token_count.input_tokens` (where `inputTokens`
445
- * includes `cachedReadTokens` and `inputTokens + outputTokens === totalTokens`).
454
+ * Reconciles `agy acp` 1.5.0+ net accounting (`inputTokens` excludes cache
455
+ * counters and `outputTokens` includes `thoughtTokens`) and legacy formats
456
+ * (`inputTokens` includes `cachedReadTokens` / `cachedWriteTokens` and/or
457
+ * `outputTokens` excludes `thoughtTokens`) against `totalTokens` when present.
446
458
  */
447
459
  export function acpUsageToAgyUsage(response: AcpPromptResponse): AgyUsage | undefined {
448
460
  const standard = asRecord(response.usage);
@@ -451,18 +463,20 @@ export function acpUsageToAgyUsage(response: AcpPromptResponse): AgyUsage | unde
451
463
  const tokenCount = asRecord(quota?.token_count);
452
464
 
453
465
  const cacheRead = safeNonNegativeInt(standard?.cachedReadTokens);
466
+ const cacheWrite = safeNonNegativeInt(standard?.cachedWriteTokens);
454
467
  const standardInput = safeNonNegativeInt(standard?.inputTokens);
455
468
  const quotaInput = safeNonNegativeInt(tokenCount?.input_tokens);
456
469
  const rawInput = standardInput ?? quotaInput;
457
- const output =
470
+ const rawOutput =
458
471
  safeNonNegativeInt(standard?.outputTokens) ?? safeNonNegativeInt(tokenCount?.output_tokens);
459
472
  const thinking = safeNonNegativeInt(standard?.thoughtTokens);
460
473
  const explicitTotal = safeNonNegativeInt(standard?.totalTokens);
461
474
 
462
475
  if (
463
476
  rawInput === undefined &&
464
- output === undefined &&
477
+ rawOutput === undefined &&
465
478
  cacheRead === undefined &&
479
+ cacheWrite === undefined &&
466
480
  thinking === undefined &&
467
481
  explicitTotal === undefined
468
482
  ) {
@@ -470,43 +484,103 @@ export function acpUsageToAgyUsage(response: AcpPromptResponse): AgyUsage | unde
470
484
  }
471
485
 
472
486
  let uncachedInput = rawInput;
473
- if (rawInput !== undefined && cacheRead !== undefined && cacheRead > 0) {
474
- let includesCacheRead = false;
487
+ let resolvedOutput = rawOutput;
488
+ const cr = cacheRead ?? 0;
489
+ const cw = cacheWrite ?? 0;
490
+ const thoughts = thinking ?? 0;
491
+
492
+ if (rawInput !== undefined || rawOutput !== undefined) {
493
+ const inVal = rawInput ?? 0;
494
+ const outVal = rawOutput ?? 0;
495
+ const outputIncludesThoughts = thinking === undefined || outVal >= thinking;
496
+
475
497
  if (explicitTotal !== undefined) {
476
- const diffIfInclusive =
477
- rawInput >= cacheRead
478
- ? Math.abs(rawInput + (output ?? 0) - explicitTotal)
479
- : Number.POSITIVE_INFINITY;
480
- const diffIfUncached = Math.abs(rawInput + cacheRead + (output ?? 0) - explicitTotal);
481
- includesCacheRead = diffIfInclusive < diffIfUncached;
482
- } else if (standardInput === undefined && rawInput >= cacheRead) {
483
- includesCacheRead = true;
484
- }
485
- if (includesCacheRead) {
486
- uncachedInput = Math.max(0, rawInput - cacheRead);
498
+ const candidates: Array<{ input: number; output: number }> = [];
499
+ // 1. ACP 1.5.0+: input excludes cache counters, output already includes thoughtTokens.
500
+ if (outputIncludesThoughts) {
501
+ candidates.push({ input: inVal, output: outVal });
502
+ }
503
+ // 2. Legacy ACP: input includes cache counters, output excludes thoughts.
504
+ if (inVal >= cr) {
505
+ if (cw > 0 && inVal >= cr + cw) {
506
+ candidates.push({ input: inVal - cr - cw, output: outVal + thoughts });
507
+ }
508
+ candidates.push({ input: inVal - cr, output: outVal + thoughts });
509
+ }
510
+ // 3. Gross input + inclusive output.
511
+ if (outputIncludesThoughts && inVal >= cr) {
512
+ if (cw > 0 && inVal >= cr + cw) {
513
+ candidates.push({ input: inVal - cr - cw, output: outVal });
514
+ }
515
+ candidates.push({ input: inVal - cr, output: outVal });
516
+ }
517
+ // 4. Net input + exclusive output.
518
+ if (thoughts > 0) {
519
+ candidates.push({ input: inVal, output: outVal + thoughts });
520
+ }
521
+ const matched = candidates.find((c) => c.input + c.output + cr + cw === explicitTotal);
522
+ if (matched) {
523
+ if (rawInput !== undefined) uncachedInput = matched.input;
524
+ if (rawOutput !== undefined) resolvedOutput = matched.output;
525
+ } else if (!outputIncludesThoughts && rawOutput !== undefined) {
526
+ resolvedOutput = outVal + thoughts;
527
+ }
528
+ } else {
529
+ if (standardInput === undefined && rawInput !== undefined && cr > 0 && rawInput >= cr) {
530
+ uncachedInput = Math.max(0, rawInput - cr);
531
+ }
532
+ if (!outputIncludesThoughts && rawOutput !== undefined) {
533
+ resolvedOutput = outVal + thoughts;
534
+ }
487
535
  }
488
536
  }
489
- const computedTotal = (uncachedInput ?? 0) + (output ?? 0) + (cacheRead ?? 0);
537
+ const computedTotal = (uncachedInput ?? 0) + (resolvedOutput ?? 0) + cr + cw;
490
538
 
491
539
  return {
492
540
  ...(uncachedInput !== undefined ? { input_tokens: uncachedInput } : {}),
493
- ...(output !== undefined ? { output_tokens: output } : {}),
541
+ ...(resolvedOutput !== undefined ? { output_tokens: resolvedOutput } : {}),
494
542
  ...(thinking !== undefined ? { thinking_tokens: thinking } : {}),
495
543
  ...(cacheRead !== undefined ? { cache_read_tokens: cacheRead } : {}),
544
+ ...(cacheWrite !== undefined && cacheWrite > 0 ? { cache_write_tokens: cacheWrite } : {}),
496
545
  total_tokens: Math.max(explicitTotal ?? 0, computedTotal),
497
546
  };
498
547
  }
499
548
 
500
549
  /**
501
550
  * Fallback normalization when SQLite per-step `generator_metadata` is unavailable:
502
- * `agy acp` sums `inputTokens` and `cachedReadTokens` across every internal LLM
503
- * sub-request in a multi-tool turn, whereas Pi treats one `AssistantMessage.usage`
504
- * as that message's context window size (`input + cacheRead`).
551
+ * - When `agy acp` emitted `usage_update` (`contextUsed > 0`), use the final
552
+ * inference's reported context occupancy directly (applying legacy duplicate-cache
553
+ * correction only when a single inference proves `contextUsed === total + cacheRead`,
554
+ * never subtracting `cacheRead` from already-correct ACP 1.5.0 `used` counts).
555
+ * - Otherwise divide cumulative `inputTokens` / `cachedReadTokens` by `modelCalls`.
505
556
  */
506
557
  export function normalizeAcpTurnUsageForStepCount(
507
558
  usage: AgyUsage,
508
559
  modelCalls: number,
560
+ contextUsed?: number,
561
+ usageInferences?: number,
509
562
  ): AgyUsage {
563
+ if (contextUsed !== undefined && contextUsed > 0 && (usageInferences ?? 0) > 0) {
564
+ if (usageInferences === 1) {
565
+ const reconciledTotal = usage.total_tokens ?? 0;
566
+ const cr = usage.cache_read_tokens ?? 0;
567
+ const resolvedTotal =
568
+ cr > 0 && contextUsed === reconciledTotal + cr ? reconciledTotal : contextUsed;
569
+ return {
570
+ ...usage,
571
+ total_tokens: resolvedTotal,
572
+ };
573
+ }
574
+ const output = usage.output_tokens ?? 0;
575
+ const netContextInput = Math.max(0, contextUsed - output);
576
+ const { cache_write_tokens: _cw, ...rest } = usage;
577
+ return {
578
+ ...rest,
579
+ input_tokens: netContextInput,
580
+ cache_read_tokens: 0,
581
+ total_tokens: contextUsed,
582
+ };
583
+ }
510
584
  const divisor = Math.max(1, Math.floor(modelCalls));
511
585
  if (divisor <= 1) return usage;
512
586
  const input =
@@ -515,13 +589,18 @@ export function normalizeAcpTurnUsageForStepCount(
515
589
  usage.cache_read_tokens !== undefined
516
590
  ? Math.round(usage.cache_read_tokens / divisor)
517
591
  : undefined;
592
+ const cacheWrite =
593
+ usage.cache_write_tokens !== undefined
594
+ ? Math.round(usage.cache_write_tokens / divisor)
595
+ : undefined;
518
596
  const output = usage.output_tokens;
519
- const total = (input ?? 0) + (cacheRead ?? 0) + (output ?? 0);
597
+ const total = (input ?? 0) + (cacheRead ?? 0) + (cacheWrite ?? 0) + (output ?? 0);
520
598
  return {
521
599
  ...(input !== undefined ? { input_tokens: input } : {}),
522
600
  ...(output !== undefined ? { output_tokens: output } : {}),
523
601
  ...(usage.thinking_tokens !== undefined ? { thinking_tokens: usage.thinking_tokens } : {}),
524
602
  ...(cacheRead !== undefined ? { cache_read_tokens: cacheRead } : {}),
603
+ ...(cacheWrite !== undefined && cacheWrite > 0 ? { cache_write_tokens: cacheWrite } : {}),
525
604
  total_tokens: total,
526
605
  };
527
606
  }
@@ -573,9 +652,40 @@ export function acpEmptyTurnApiFailure(
573
652
  lastApiError: string | undefined,
574
653
  ): string | undefined {
575
654
  if (stopReason !== "end_turn" || responseText.trim() || !lastApiError) return undefined;
655
+ if (/\bRESOURCE_EXHAUSTED\b|\b429\b|\bquota\b/i.test(lastApiError)) {
656
+ return `Antigravity quota exceeded: request failed after agy gave up retrying (${lastApiError}).`;
657
+ }
576
658
  return `Antigravity request failed after agy gave up retrying (${lastApiError}).`;
577
659
  }
578
660
 
661
+ /**
662
+ * `agy` sometimes emits account quota exhaustion as an ordinary `end_turn` reply
663
+ * (`Usage Limit Reached ...`) with zero billed tokens instead of `stopReason: "refusal"`.
664
+ * Prefix with `"Antigravity quota exceeded:"` so Pi fails fast without auto-retrying.
665
+ */
666
+ export function detectAcpPlainTextQuotaExhaustion(
667
+ stopReason: string,
668
+ responseText: string,
669
+ usage: AgyUsage | undefined,
670
+ quota?: AcpQuotaSnapshot,
671
+ ): string | undefined {
672
+ if (stopReason !== "end_turn" || (usage?.total_tokens ?? 0) > 0) return undefined;
673
+ const trimmed = responseText.trim();
674
+ if (
675
+ !/^\s*Usage Limit Reached\b[\s\S]*\bYou have reached your current quota for this period\b/i.test(
676
+ trimmed,
677
+ )
678
+ ) {
679
+ return undefined;
680
+ }
681
+ const compact = trimmed.replace(/\s+/g, " ");
682
+ const withReset =
683
+ quota?.resetTime && !compact.includes(quota.resetTime)
684
+ ? `${compact} (resets ${quota.resetTime})`
685
+ : compact;
686
+ return `Antigravity quota exceeded: ${withReset}`;
687
+ }
688
+
579
689
  /**
580
690
  * Format a clear user-facing error message when an ACP turn stops with a
581
691
  * non-`end_turn` reason (e.g. `stopReason === "refusal"` on quota exhaustion).
@@ -591,12 +701,19 @@ export function formatAcpStopError(
591
701
  ? `${msg} (resets ${quota.resetTime})`
592
702
  : msg;
593
703
 
704
+ const ensureNonRetryableRefusal = (msg: string): string =>
705
+ stopReason === "refusal" &&
706
+ /\b429\b|rate.?limit|RESOURCE_EXHAUSTED/i.test(msg) &&
707
+ !/quota exceeded/i.test(msg)
708
+ ? `Antigravity quota exceeded: ${msg}`
709
+ : msg;
710
+
594
711
  if (rawErr?.trim()) {
595
- return appendReset(rawErr.trim());
712
+ return ensureNonRetryableRefusal(appendReset(rawErr.trim()));
596
713
  }
597
714
  const trimmedResponse = responseText.trim();
598
715
  if (stopReason === "refusal" && trimmedResponse) {
599
- return appendReset(trimmedResponse.slice(0, 500));
716
+ return ensureNonRetryableRefusal(appendReset(trimmedResponse.slice(0, 500)));
600
717
  }
601
718
  if (stopReason === "refusal") {
602
719
  return appendReset("Antigravity refused the request or reached its usage quota limit.");
@@ -976,6 +1093,8 @@ export class AcpTurnNormalizer {
976
1093
  #streamedTextSegments: string[] = [];
977
1094
  #currentSegment = "";
978
1095
  #lastStepWarning: string | undefined;
1096
+ #lastContextUsed: number | undefined;
1097
+ #usageInferenceCount = 0;
979
1098
 
980
1099
  constructor(outcome: AgyTurnOutcome) {
981
1100
  this.#outcome = outcome;
@@ -1184,6 +1303,14 @@ export class AcpTurnNormalizer {
1184
1303
  }
1185
1304
  break;
1186
1305
  }
1306
+ case "usage_update": {
1307
+ const used = safeNonNegativeInt(update.used);
1308
+ if (used !== undefined && used > 0) {
1309
+ this.#lastContextUsed = used;
1310
+ this.#usageInferenceCount += 1;
1311
+ }
1312
+ break;
1313
+ }
1187
1314
  default:
1188
1315
  break;
1189
1316
  }
@@ -1213,6 +1340,16 @@ export class AcpTurnNormalizer {
1213
1340
  lastWarningText(): string | undefined {
1214
1341
  return this.#lastStepWarning;
1215
1342
  }
1343
+
1344
+ /** Latest positive `usage_update.used` context size reported during this turn, if any. */
1345
+ lastContextUsed(): number | undefined {
1346
+ return this.#lastContextUsed;
1347
+ }
1348
+
1349
+ /** Count of positive `usage_update` inference reports observed during this turn. */
1350
+ usageInferenceCount(): number {
1351
+ return this.#usageInferenceCount;
1352
+ }
1216
1353
  }
1217
1354
 
1218
1355
  interface PendingRpc {
@@ -1227,6 +1364,7 @@ export interface AgyAcpClientHandlers {
1227
1364
  onPermission?: (request: AcpPermissionRequest) => AcpPermissionResponse | Promise<AcpPermissionResponse>;
1228
1365
  onProtocolWarning?: (line: string) => void;
1229
1366
  onTransportError?: (error: Error) => void;
1367
+ getStderrSummary?: () => string | undefined;
1230
1368
  }
1231
1369
 
1232
1370
  export class AgyAcpClient {
@@ -1261,6 +1399,19 @@ export class AgyAcpClient {
1261
1399
  return this.#initResult;
1262
1400
  }
1263
1401
 
1402
+ get closed(): boolean {
1403
+ return (
1404
+ this.#closed ||
1405
+ this.#child.exitCode !== null ||
1406
+ this.#child.signalCode !== null ||
1407
+ Boolean(this.#child.killed)
1408
+ );
1409
+ }
1410
+
1411
+ hasPendingRpc(): boolean {
1412
+ return this.#pending.size > 0;
1413
+ }
1414
+
1264
1415
  setHandlers(handlers: AgyAcpClientHandlers): void {
1265
1416
  this.#handlers = handlers;
1266
1417
  }
@@ -1327,6 +1478,9 @@ export class AgyAcpClient {
1327
1478
  }
1328
1479
  this.#initResult = res;
1329
1480
  return res;
1481
+ }).catch((err) => {
1482
+ this.#initPromise = undefined;
1483
+ throw err;
1330
1484
  });
1331
1485
  void this.#initPromise.catch(() => undefined);
1332
1486
  }
@@ -1580,11 +1734,19 @@ export class AgyAcpClient {
1580
1734
  };
1581
1735
 
1582
1736
  if (options.timeoutMs && options.timeoutMs > 0) {
1737
+ const timeoutMs = options.timeoutMs;
1583
1738
  pending.timer = setTimeout(() => {
1584
1739
  this.#pending.delete(id);
1585
1740
  cleanup();
1586
- reject(new Error(`ACP ${method} timed out after ${options.timeoutMs}ms`));
1587
- }, options.timeoutMs);
1741
+ const detail = this.#handlers.getStderrSummary?.()?.trim();
1742
+ reject(
1743
+ new AgyAcpTimeoutError(
1744
+ method,
1745
+ timeoutMs,
1746
+ `ACP ${method} timed out after ${timeoutMs}ms${detail ? `: ${detail}` : ""}`,
1747
+ ),
1748
+ );
1749
+ }, timeoutMs);
1588
1750
  pending.timer.unref?.();
1589
1751
  }
1590
1752