@juanbenjumea/pi-agy 0.6.5 → 0.6.6

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/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.6.6
4
+
5
+ - Surface agy's native and legacy subagent spawn steps as bounded live progress and structured per-run observations (`details.subagents`) with ACTIVE/DONE/ERROR correlation, multi-spawn support, and retry-safe activity tracking.
6
+ - Append a compact observed-subagent summary to tool content and render the structured roster in native results and durable `/agy` receipts without duplicating the synthetic appendix.
7
+ - Keep diagnostics truthful and bounded: retain at most 32 sanitized observations, print at most 12, label unfinished entries `active at last event`, ignore send/manage events, and deliberately withhold nested conversation ids/log URIs as lifecycle handles.
8
+ - Add captured native-stream, legacy fallback, missing-step-index, control-safety, roster-bound, execution, and rendering coverage.
9
+
3
10
  ## 0.6.5
4
11
 
5
12
  - Add `agy_agents` and `/agy agents` to list configured custom agy agents through the CLI's read-only `agy agents` subcommand without spending a model turn; parsing is control-safe and capped at 200 names.
package/README.md CHANGED
@@ -30,6 +30,7 @@ Requires Node.js >= 20.3.
30
30
  | Preflight | Every call | Health/model checks cached 5 min per process; model quotas refresh every minute |
31
31
  | Quota discovery | None | Read-only `/usage` probe exposes model-specific remaining quota and reset times to agents |
32
32
  | Custom agents | None | Read-only `agy_agents` / `/agy agents` discovery plus validated `agent` / `agent=name` selection via `--agent` |
33
+ | Subagent visibility | None | Native stream progress plus a capped per-run roster in result details/receipts; observations never claim live lifecycle control |
33
34
  | Concurrency | Unlocked | Per-directory lock (in-process + filesystem, symlink-aware), lock wait counts against the timeout |
34
35
  | Transient failures | Fatal | One retry when agy fails before doing any work |
35
36
  | Cancellation | Direct child only | Full process-tree kill on cancel/timeout via detached process groups; a fully delivered result is preserved |
@@ -45,6 +46,9 @@ outlive the run.
45
46
 
46
47
  Active tool updates show bounded intent (for example a tool action or async
47
48
  threshold) but never echo full command lines, which may contain secrets.
49
+ Subagent spawn steps likewise produce bounded progress and a final per-run
50
+ observation roster (maximum 32). An `active at last event` entry describes the
51
+ last stream record only; it does not claim that a controllable process remains live.
48
52
  Background commands are intentionally not detached or managed out-of-band:
49
53
  agy exposes no reliable headless task lifecycle or task-to-process ownership,
50
54
  so timeout/cancellation still kills the full process tree and prevents work from
@@ -91,6 +95,12 @@ headless `/usage` continue without failing the task. The extension requires
91
95
  agy 1.1.11+ before invoking `/usage`; older versions are refused safely because
92
96
  that command could otherwise consume model quota as a prompt.
93
97
 
98
+ When agy emits `subagent` stream steps, `agy_execute` returns a capped,
99
+ control-safe `details.subagents` list and appends the same observed summary to
100
+ tool content. Native rendering deduplicates that synthetic appendix and shows
101
+ compact/expanded roster metadata. Conversation ids and log URIs from nested
102
+ subagents are deliberately not exposed as lifecycle handles.
103
+
94
104
  Context handoff is opt-in and text-only. `summary` sends up to 12,000
95
105
  characters from the latest durable summaries and four conversational messages;
96
106
  `recent` sends up to 40,000 characters from the recent conversational tail.
@@ -1023,7 +1023,11 @@ export function spawnAgy(options: AgyOptions, signal: AbortSignal): Promise<stri
1023
1023
  /** Real agy work (tool steps / model responses), as opposed to lifecycle chatter. */
1024
1024
  function isActivityProgress(parsed: AgyStreamLine): boolean {
1025
1025
  const step = parsed.step_update;
1026
- return step?.step_type === "tool" || step?.step_type === "agent_response";
1026
+ return (
1027
+ step?.step_type === "tool" ||
1028
+ step?.step_type === "subagent" ||
1029
+ step?.step_type === "agent_response"
1030
+ );
1027
1031
  }
1028
1032
 
1029
1033
  export function spawnAgyStream(
@@ -19,6 +19,10 @@ import {
19
19
  import { loadAgyConfig, resolveDefaultModel } from "./config.js";
20
20
  import type { AgyContextMode } from "./context.js";
21
21
  import type { AgyUsage } from "./stream.js";
22
+ import {
23
+ formatAgySubagentObservations,
24
+ type AgyObservedSubagent,
25
+ } from "./subagents.js";
22
26
  import { withDirLock } from "./lock.js";
23
27
  import {
24
28
  captureGitBaseline,
@@ -60,6 +64,8 @@ export interface AgyExecutionDetails {
60
64
  agent?: string;
61
65
  usage?: AgyUsage;
62
66
  duration_seconds?: number;
67
+ /** Stream observations only; entries do not imply a live controllable process. */
68
+ subagents?: AgyObservedSubagent[];
63
69
  changed_files?: string[];
64
70
  preexisting_files?: string[];
65
71
  context_mode?: AgyContextMode;
@@ -243,6 +249,8 @@ export async function executeAgyTask(
243
249
  }
244
250
 
245
251
  let text = run.response;
252
+ const subagentSummary = formatAgySubagentObservations(run.subagents);
253
+ if (subagentSummary) text = `${text}\n\n## ${subagentSummary}`;
246
254
  const quotaSummary = quota?.models.length
247
255
  ? formatAgyUsage(quota, resolveAgyModelId(model, options.tier))
248
256
  : undefined;
@@ -281,6 +289,7 @@ export async function executeAgyTask(
281
289
  agent,
282
290
  usage: run.usage,
283
291
  duration_seconds: run.duration_seconds,
292
+ subagents: run.subagents,
284
293
  changed_files: changedFiles,
285
294
  preexisting_files: preexistingFiles,
286
295
  context_mode: options.context ?? "none",
@@ -48,6 +48,7 @@ function firstText(content: unknown): string {
48
48
  function stripSyntheticResultSections(value: string): string {
49
49
  const markers = [
50
50
  "\n\n## agy quota snapshot",
51
+ "\n\n## agy subagents observed",
51
52
  "\n\n## git diff --stat",
52
53
  "\n\n## git diff --cached --stat",
53
54
  "\n\nagy made no newly-dirty files",
@@ -139,6 +140,27 @@ function formatAgyResult(
139
140
  }
140
141
  if (metadata.length) lines.push(theme.fg("dim", metadata.join(" · ")));
141
142
 
143
+ const subagents = Array.isArray(details.subagents) ? details.subagents.slice(0, 32) : [];
144
+ if (subagents.length) {
145
+ const done = subagents.filter((entry) => entry?.status === "done").length;
146
+ const errors = subagents.filter((entry) => entry?.status === "error").length;
147
+ lines.push(
148
+ theme.fg(
149
+ "muted",
150
+ `${subagents.length} subagent${subagents.length === 1 ? "" : "s"} observed${done ? ` · ${done} done` : ""}${errors ? ` · ${errors} error${errors === 1 ? "" : "s"}` : ""}`,
151
+ ),
152
+ );
153
+ if (expanded) {
154
+ for (const entry of subagents) {
155
+ if (!entry || typeof entry !== "object") continue;
156
+ const name = oneLine(entry.name ?? "subagent", 80);
157
+ const status = entry.status === "active" ? "active at last event" : oneLine(entry.status, 30);
158
+ const task = entry.task ? ` · ${oneLine(entry.task, 120)}` : "";
159
+ lines.push(theme.fg("toolOutput", `↳ ${name} · ${status}${task}`));
160
+ }
161
+ }
162
+ }
163
+
142
164
  const changed = details.changed_files ?? [];
143
165
  const preexisting = details.preexisting_files ?? [];
144
166
  if (changed.length || preexisting.length) {
@@ -1,5 +1,11 @@
1
1
  import { stripTerminalSequences } from "@earendil-works/pi-tui";
2
2
 
3
+ import {
4
+ formatAgySubagentProgress,
5
+ observeAgySubagents,
6
+ type AgyObservedSubagent,
7
+ } from "./subagents.js";
8
+
3
9
  export interface AgyUsage {
4
10
  input_tokens?: number;
5
11
  output_tokens?: number;
@@ -20,7 +26,10 @@ export interface AgyStepUpdate {
20
26
  tool_info?: {
21
27
  name?: string;
22
28
  parameters?: Record<string, unknown>;
29
+ error?: { message?: unknown };
23
30
  };
31
+ subagent_info?: { subagents?: unknown };
32
+ error?: { message?: unknown };
24
33
  }
25
34
 
26
35
  export interface AgyStreamLine {
@@ -51,6 +60,8 @@ export interface AgyRunResult {
51
60
  conversation_id?: string;
52
61
  usage?: AgyUsage;
53
62
  duration_seconds?: number;
63
+ /** Bounded observations from subagent stream steps; not live lifecycle state. */
64
+ subagents?: AgyObservedSubagent[];
54
65
  }
55
66
 
56
67
  export type AgyProgressHandler = (
@@ -108,6 +119,9 @@ export function formatStepProgress(parsed: AgyStreamLine): string | null {
108
119
  const step = parsed.step_update;
109
120
  if (!step) return null;
110
121
 
122
+ const subagentProgress = formatAgySubagentProgress(step);
123
+ if (subagentProgress) return subagentProgress;
124
+
111
125
  if (step.step_type === "tool" && step.state === "ACTIVE") {
112
126
  const name =
113
127
  compactProgressValue(step.tool_name ?? step.tool_info?.name, 40) ?? "tool";
@@ -216,6 +230,7 @@ export function accumulateRunResult(parsed: AgyStreamLine, current: AgyRunResult
216
230
 
217
231
  const step = parsed.step_update;
218
232
  if (typeof step?.conversation_id === "string") next.conversation_id = step.conversation_id;
233
+ if (step) next.subagents = observeAgySubagents(next.subagents, step);
219
234
 
220
235
  if (parsed.result) {
221
236
  if (typeof parsed.result.conversation_id === "string") {
@@ -0,0 +1,236 @@
1
+ import { stripTerminalSequences } from "@earendil-works/pi-tui";
2
+
3
+ export type AgyObservedSubagentStatus = "active" | "done" | "error";
4
+
5
+ export interface AgyObservedSubagent {
6
+ /** Correlation data from the agy stream; not an internal lifecycle handle. */
7
+ step_index?: number;
8
+ slot: number;
9
+ name: string;
10
+ type?: string;
11
+ task?: string;
12
+ status: AgyObservedSubagentStatus;
13
+ duration_seconds?: number;
14
+ error?: string;
15
+ }
16
+
17
+ export interface AgySubagentStep {
18
+ step_index?: number;
19
+ state?: string;
20
+ step_type?: string;
21
+ tool_name?: string;
22
+ duration_seconds?: number;
23
+ subagent_info?: { subagents?: unknown };
24
+ tool_info?: {
25
+ name?: string;
26
+ parameters?: Record<string, unknown>;
27
+ error?: { message?: unknown };
28
+ };
29
+ error?: { message?: unknown };
30
+ }
31
+
32
+ export const MAX_OBSERVED_SUBAGENTS = 32;
33
+ const MAX_REPORTED_SUBAGENTS = 12;
34
+
35
+ const SPAWN_TOOLS = new Set([
36
+ "invoke_subagent",
37
+ "run_subagent",
38
+ "define_subagent",
39
+ "browser_subagent",
40
+ ]);
41
+ const NON_SPAWN_SUBAGENT_TOOLS = new Set(["send_message", "manage_subagents"]);
42
+
43
+ function clean(value: unknown, max: number): string | undefined {
44
+ if (typeof value !== "string") return undefined;
45
+ const text = stripTerminalSequences(value)
46
+ .replace(/[\u0000-\u001f\u007f-\u009f\u200e\u200f\u202a-\u202e\u2066-\u2069]+/g, " ")
47
+ .replace(/\s+/g, " ")
48
+ .trim();
49
+ if (!text) return undefined;
50
+ return text.length > max ? `${text.slice(0, max - 1)}…` : text;
51
+ }
52
+
53
+ function pick(record: Record<string, unknown>, keys: string[], max: number): string | undefined {
54
+ for (const key of keys) {
55
+ const value = clean(record[key], max);
56
+ if (value) return value;
57
+ }
58
+ return undefined;
59
+ }
60
+
61
+ interface Candidate {
62
+ slot: number;
63
+ name: string;
64
+ type?: string;
65
+ task?: string;
66
+ }
67
+
68
+ function candidatesFromArray(raw: unknown[]): Candidate[] {
69
+ return raw.slice(0, MAX_OBSERVED_SUBAGENTS).flatMap((value, slot) => {
70
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return [];
71
+ const record = value as Record<string, unknown>;
72
+ const type = pick(record, ["type_name", "type", "Type"], 40);
73
+ const name = pick(record, ["role", "name", "Name"], 80) ?? type ?? "subagent";
74
+ const task = pick(record, ["initial_prompt", "task", "Task", "prompt", "Prompt"], 120);
75
+ return [{ slot, name, type, task }];
76
+ });
77
+ }
78
+
79
+ function candidates(step: AgySubagentStep): Candidate[] {
80
+ const tool = clean(step.tool_name ?? step.tool_info?.name, 40);
81
+ const raw = step.subagent_info?.subagents;
82
+ if (Array.isArray(raw)) return candidatesFromArray(raw);
83
+
84
+ if (!tool || !SPAWN_TOOLS.has(tool)) return [];
85
+ const parameters = step.tool_info?.parameters ?? {};
86
+ const nested = parameters.Subagents ?? parameters.subagents;
87
+ if (Array.isArray(nested)) return candidatesFromArray(nested);
88
+ const type = pick(parameters, ["Type", "type"], 40);
89
+ return [{
90
+ slot: 0,
91
+ name:
92
+ pick(parameters, ["Name", "name", "Role", "role", "Agent", "agent"], 80) ??
93
+ type ??
94
+ tool,
95
+ type,
96
+ task: pick(
97
+ parameters,
98
+ ["Task", "task", "Prompt", "prompt", "Instruction", "instruction", "Goal", "goal"],
99
+ 120,
100
+ ),
101
+ }];
102
+ }
103
+
104
+ function isSpawnStep(step: AgySubagentStep, tool: string | undefined): boolean {
105
+ if (tool && NON_SPAWN_SUBAGENT_TOOLS.has(tool)) return false;
106
+ return step.step_type === "subagent" || Boolean(tool && SPAWN_TOOLS.has(tool));
107
+ }
108
+
109
+ function statusFor(state: string | undefined): AgyObservedSubagentStatus | undefined {
110
+ if (state === "ACTIVE") return "active";
111
+ if (state === "DONE") return "done";
112
+ if (state === "ERROR") return "error";
113
+ return undefined;
114
+ }
115
+
116
+ function sameEntry(
117
+ entry: AgyObservedSubagent,
118
+ step: AgySubagentStep,
119
+ candidate: Candidate,
120
+ ): boolean {
121
+ if (typeof step.step_index === "number") {
122
+ return entry.step_index === step.step_index && entry.slot === candidate.slot;
123
+ }
124
+ return entry.step_index === undefined && entry.slot === candidate.slot && entry.name === candidate.name;
125
+ }
126
+
127
+ /**
128
+ * Fold one agy stream step into a bounded observation list. This records what
129
+ * the stream reported; it never claims the subagent is still live or exposes a
130
+ * controllable lifecycle handle.
131
+ */
132
+ export function observeAgySubagents(
133
+ current: AgyObservedSubagent[] | undefined,
134
+ step: AgySubagentStep,
135
+ ): AgyObservedSubagent[] | undefined {
136
+ const tool = clean(step.tool_name ?? step.tool_info?.name, 40);
137
+ if (!isSpawnStep(step, tool)) return current;
138
+
139
+ const status = statusFor(step.state);
140
+ if (!status) return current;
141
+ const next = (current ?? []).map((entry) => ({ ...entry }));
142
+ const found = candidates(step);
143
+ const duration =
144
+ typeof step.duration_seconds === "number" &&
145
+ Number.isFinite(step.duration_seconds) &&
146
+ step.duration_seconds >= 0
147
+ ? step.duration_seconds
148
+ : undefined;
149
+ const error =
150
+ status === "error"
151
+ ? clean(step.error?.message ?? step.tool_info?.error?.message, 120) ?? "subagent step error"
152
+ : undefined;
153
+
154
+ // Completion records can omit their original payload. Update every entry
155
+ // correlated to the step rather than inventing a nameless replacement.
156
+ if (found.length === 0 && typeof step.step_index === "number") {
157
+ for (const entry of next) {
158
+ if (entry.step_index !== step.step_index) continue;
159
+ entry.status = status;
160
+ if (duration !== undefined) entry.duration_seconds = duration;
161
+ if (error) entry.error = error;
162
+ }
163
+ return next.length ? next : undefined;
164
+ }
165
+
166
+ for (const candidate of found) {
167
+ const existing = next.find((entry) => sameEntry(entry, step, candidate));
168
+ if (existing) {
169
+ existing.name = candidate.name;
170
+ existing.type = candidate.type ?? existing.type;
171
+ existing.task = candidate.task ?? existing.task;
172
+ existing.status = status;
173
+ if (duration !== undefined) existing.duration_seconds = duration;
174
+ if (error) existing.error = error;
175
+ continue;
176
+ }
177
+ if (next.length >= MAX_OBSERVED_SUBAGENTS) break;
178
+ next.push({
179
+ ...(typeof step.step_index === "number" ? { step_index: step.step_index } : {}),
180
+ slot: candidate.slot,
181
+ name: candidate.name,
182
+ type: candidate.type,
183
+ task: candidate.task,
184
+ status,
185
+ duration_seconds: duration,
186
+ error,
187
+ });
188
+ }
189
+ return next.length ? next : undefined;
190
+ }
191
+
192
+ function formatDuration(seconds: number): string {
193
+ if (seconds < 60) return `${seconds.toFixed(seconds < 10 ? 1 : 0)}s`;
194
+ return `${Math.floor(seconds / 60)}m${Math.round(seconds % 60)}s`;
195
+ }
196
+
197
+ /** Bounded final report suitable for tool content and native rendering. */
198
+ export function formatAgySubagentObservations(
199
+ entries: readonly AgyObservedSubagent[] | undefined,
200
+ ): string | undefined {
201
+ if (!entries?.length) return undefined;
202
+ const lines = [`agy subagents observed: ${entries.length}`];
203
+ for (const entry of entries.slice(0, MAX_REPORTED_SUBAGENTS)) {
204
+ const status = entry.status === "active" ? "active at last event" : entry.status;
205
+ const parts = [
206
+ `- ${clean(entry.name, 80) ?? "subagent"}`,
207
+ status,
208
+ typeof entry.duration_seconds === "number"
209
+ ? formatDuration(entry.duration_seconds)
210
+ : undefined,
211
+ entry.type ? `type ${clean(entry.type, 40)}` : undefined,
212
+ entry.task ? `“${clean(entry.task, 120)}”` : undefined,
213
+ entry.error ? clean(entry.error, 120) : undefined,
214
+ ].filter((part): part is string => Boolean(part));
215
+ lines.push(parts.join(" · "));
216
+ }
217
+ if (entries.length > MAX_REPORTED_SUBAGENTS) {
218
+ lines.push(`- … ${entries.length - MAX_REPORTED_SUBAGENTS} more in structured details`);
219
+ }
220
+ return lines.join("\n");
221
+ }
222
+
223
+ /** Compact progress text for a native subagent stream step. */
224
+ export function formatAgySubagentProgress(step: AgySubagentStep): string | undefined {
225
+ const tool = clean(step.tool_name ?? step.tool_info?.name, 40);
226
+ if (!isSpawnStep(step, tool)) return undefined;
227
+ const found = candidates(step);
228
+ if (found.length === 0) return undefined;
229
+ const first = found[0];
230
+ const extra = found.length > 1 ? ` +${found.length - 1}` : "";
231
+ const task = first.task ? ` — ${first.task}` : "";
232
+ if (step.state === "ACTIVE") return `▸ subagent ${first.name}${extra}${task}`;
233
+ if (step.state === "DONE") return `✓ subagent ${first.name}${extra} completed`;
234
+ if (step.state === "ERROR") return `✗ subagent ${first.name}${extra} errored`;
235
+ return undefined;
236
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@juanbenjumea/pi-agy",
3
- "version": "0.6.5",
3
+ "version": "0.6.6",
4
4
  "description": "Reliable Antigravity delegation for Pi — quota-aware runs, resumable tasks, repo verification, cancellation, and trustworthy diff summaries.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -79,6 +79,7 @@ agy_usage
79
79
  - **Quota discovery** — `agy_usage` and `/agy usage` report model-specific remaining quota and reset times; executions refresh quota snapshots, automatically fall back when an implicit default is exhausted, and return machine-readable `quota_status` as well.
80
80
  - **Custom-agent selection** — `agy_agents` and `/agy agents` list configured agents without inference; `agent` / `agent=name` passes a validated `--agent` and persists its identity with resumable conversations.
81
81
  - **Streaming progress and receipts** — live tool steps via `stream-json` and Pi `onUpdate`; direct `/agy` runs persist bounded, expandable TUI-only receipts without feeding them to the primary model.
82
+ - **Observed subagents** — native subagent stream steps produce bounded progress and a capped per-run roster in result details/receipts. `active at last event` is diagnostic history, never a claim of live lifecycle control.
82
83
  - **Conversation continuity** — `conversation_id`, `continue`, session store under `$PI_CODING_AGENT_DIR/agy-sessions.json` (or `~/.pi/agent/agy-sessions.json` by default) with one-line task summaries; runs that time out or are cancelled are recorded too and stay resumable, and the `agy_history` tool lets agents list past conversations.
83
84
  - **Optional Pi context handoff** — `context=summary|recent` sends bounded text-only history while excluding system prompts, thinking, tool calls/results, images, and custom messages; default is `none`.
84
85
  - **Repo-aware verify** — prefers `just ci` when a justfile defines `ci:`.