oira666_pi-subagent 0.6.3 → 0.7.1

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.
Files changed (75) hide show
  1. package/README.md +16 -8
  2. package/broker/commands.ts +179 -0
  3. package/broker/contracts.ts +63 -0
  4. package/broker/files.ts +158 -0
  5. package/broker/root.ts +221 -0
  6. package/budget.ts +55 -13
  7. package/config.ts +9 -4
  8. package/docs/async-performance.md +13 -3
  9. package/docs/configuration.md +41 -12
  10. package/docs/sessions.md +8 -9
  11. package/docs/usage.md +12 -4
  12. package/extension/activity-widget.ts +57 -7
  13. package/extension/activity.ts +22 -2
  14. package/extension/async-jobs.ts +31 -3
  15. package/extension/broker-execution.ts +182 -0
  16. package/extension/broker-jobs.ts +112 -0
  17. package/extension/child-ownership.ts +37 -0
  18. package/extension/completion.ts +19 -4
  19. package/extension/events.ts +3 -2
  20. package/extension/execution.ts +98 -36
  21. package/extension/expand-command.ts +2 -2
  22. package/extension/launch-result.ts +36 -0
  23. package/extension/launch-tool.ts +25 -26
  24. package/extension/lead-message-tool.ts +24 -0
  25. package/extension/message-batch.ts +6 -0
  26. package/extension/message-tool.ts +75 -48
  27. package/extension/policy.ts +3 -11
  28. package/extension/prompt-hook.ts +33 -12
  29. package/extension/prompts.ts +2 -1
  30. package/extension/resume-offer.ts +2 -2
  31. package/extension/runtime.ts +19 -5
  32. package/extension/scheduler.ts +74 -0
  33. package/extension/session-start.ts +80 -74
  34. package/extension/settings-commands.ts +293 -0
  35. package/extension/state.ts +6 -7
  36. package/extension/stop-tool.ts +160 -0
  37. package/extension/tool-registration.ts +5 -3
  38. package/extension/usage.ts +3 -3
  39. package/index.ts +2 -0
  40. package/package.json +2 -1
  41. package/render.ts +1 -1
  42. package/resume.ts +16 -16
  43. package/runner/attempt-env.ts +36 -0
  44. package/runner/attempt-parking.ts +95 -0
  45. package/runner/attempt.ts +59 -63
  46. package/runner/extension-policy.ts +3 -1
  47. package/runner/launch.ts +29 -1
  48. package/runner/options.ts +8 -0
  49. package/runner/parallel-result.ts +25 -0
  50. package/runner/parallel.ts +56 -38
  51. package/runner/process-tree.ts +77 -0
  52. package/runner/protocol.ts +3 -0
  53. package/runner/single.ts +47 -8
  54. package/runner/tree-admission.ts +110 -0
  55. package/runner/worker-scheduler.ts +297 -0
  56. package/settings.ts +11 -4
  57. package/shared.ts +2 -2
  58. package/storage/budget-ledger.ts +2 -0
  59. package/storage/budget-state.ts +3 -1
  60. package/storage/name-records.ts +2 -0
  61. package/storage/names-registry.ts +11 -1
  62. package/storage/save-settings.ts +70 -0
  63. package/storage/session-entries.ts +32 -0
  64. package/storage/stopped-workers.ts +64 -0
  65. package/storage/tree-concurrency-ledger.ts +50 -0
  66. package/storage/tree-concurrency-lifecycle.ts +63 -0
  67. package/storage/tree-concurrency-process.ts +42 -0
  68. package/storage/tree-concurrency-state.ts +151 -0
  69. package/storage/tree-concurrency.ts +256 -0
  70. package/storage/worker-stops.ts +58 -0
  71. package/types/contracts.ts +12 -2
  72. package/types/details.ts +1 -0
  73. package/ui/detail-lines.ts +1 -1
  74. package/ui/session.ts +2 -1
  75. package/ui/tree-build.ts +1 -1
package/README.md CHANGED
@@ -26,7 +26,7 @@ Use either `pi-subagent.json` or `pi-subagents.json`. Both filenames are permane
26
26
 
27
27
  ```json
28
28
  {
29
- "limits": { "total": 50, "parallel": 30, "concurrency": 8 },
29
+ "limits": { "total": 50, "tasksPerCall": 20, "concurrency": 8 },
30
30
  "delegation": { "depth": 3, "preventCycles": true },
31
31
  "runner": { "startupTimeoutMs": 120000 }
32
32
  }
@@ -34,6 +34,8 @@ Use either `pi-subagent.json` or `pi-subagents.json`. Both filenames are permane
34
34
 
35
35
  See [settings files](docs/configuration.md#settings-files) for locations, all settings, environment mappings, and trust rules.
36
36
 
37
+ For session-only changes, use `/subagent:enable`, `/subagent:disable`, `/subagent:max-total 80`, `/subagent:max-tasks-per-call 20`, or `/subagent:max-concurency 4`. `/subagent:settings` lists all [session controls](docs/configuration.md#session-settings-commands). Nothing is saved unless you run `/subagent:save-settings`, which asks whether to save to the project or globally.
38
+
37
39
  ## Extension controls
38
40
 
39
41
  Exclude extensions from child agents without changing which extensions the parent loads:
@@ -73,13 +75,13 @@ PI_SUBAGENT_DISABLED=1 pi
73
75
  }
74
76
  ```
75
77
 
76
- Call `subagents` with one or more tasks. It returns `started` immediately, without waiting for worker completion. Tasks run in the background, subject to the concurrency limit. Each completion arrives separately as lead steering, including when the lead is idle. The lead can continue other work after launching workers.
78
+ Call `subagents` with one or more tasks, up to 20 by default. It returns immediately, reporting workers as `started` or `queued` without waiting for completion. The root session creates one shared cross-process FIFO queue, inherited by descendants, with a default cap of 8 live workers across the entire tree. Live parent workers count until their processes exit. A waiting parent can park by saving its context and exiting to free capacity for children. Nested workers cannot loosen the cap. Queued work starts when a live worker releases capacity. Each completion arrives separately as lead steering, including when the lead is idle. The lead can continue other work after launching workers.
77
79
 
78
80
  Every task requires task text and a descendant allowance. The `agent` argument exists only when user-created agent definitions are available. The `intelligence` argument exists only when two or more enabled presets are configured. These choices are independent; with neither, task items contain only `task` and `max_subagents_allowed`. Use `0` for a worker that will not delegate, or `1` to let it launch one subagent. The caller reserves one slot for the worker plus its descendant allowance.
79
81
 
80
82
  Workers with zero descendant allowance receive no delegation tools or added delegation guidance. They still have `message_lead_agent` to contact the lead. Raising `max_subagents_allowed` through `message_subagent` restores delegation tools, subject to the depth limit. Workers that spent a positive allowance keep their tools so they can message existing children.
81
83
 
82
- Workers receive durable human names. Call `message_subagent(name, message, max_subagents_allowed?)` to contact one:
84
+ Workers always receive durable human names when delegation is enabled. `message_subagent` is available whenever delegation is enabled, independently of automatic recovery settings. Call `message_subagent(name, message, max_subagents_allowed?)` to contact one of your own direct children:
83
85
 
84
86
  ```json
85
87
  { "name": "John", "message": "Now update the tests." }
@@ -91,9 +93,13 @@ Send the same message to several workers with an array of names:
91
93
  { "name": ["John", "Maria"], "message": "The shared API changed. Use the new signature." }
92
94
  ```
93
95
 
94
- Each recipient receives only the message text, not the recipient list. Duplicate names receive one copy. Running workers are steered and idle workers resume concurrently. Delivery failures are reported per recipient without undoing successful deliveries. An optional `max_subagents_allowed` applies separately to each recipient.
96
+ Each recipient receives only the message text, not the recipient list. Duplicate names receive one copy. Running workers receive steering without taking another concurrency slot. Saved idle workers resume through the same tree-global FIFO queue and wait if the cap is full. A parent process still alive while waiting for children already occupies a slot. Delivery failures are reported per recipient without undoing successful deliveries. An optional `max_subagents_allowed` applies separately to each recipient.
97
+
98
+ A message steers a running worker or resumes an idle worker with its saved context. It does not wait for the worker to finish. `agent` selects a definition at launch; `name` identifies an existing worker. Messaging or resuming a named worker consumes no new budget slot. Resuming an idle worker still needs concurrency capacity. An optional budget increase can reserve additional descendant slots. See [sessions and budgets](docs/sessions.md) for cap overrides, ownership, and crash recovery.
95
99
 
96
- A message steers a running worker or resumes an idle worker with its saved context. It does not wait for the worker to finish. `agent` selects a definition at launch; `name` identifies an existing worker. Messaging or resuming a named worker consumes no new worker slot. An optional budget increase can reserve additional descendant slots. See [sessions and budgets](docs/sessions.md) for cap overrides, forks, and crash recovery.
100
+ Both `message_subagent` and `stop_subagent` accept only the caller's own direct children. The saved owner identity and backend parent token must match. The root cannot address grandchildren, siblings, or another owner's saved workers. Ask the worker's parent instead. Use `stop_subagent` with a direct child's `name` or array of names to stop each named child's entire subtree, including queued descendants and resumes. Stopping queued work prevents it from starting; stopping live workers releases concurrency capacity. Neither refunds reserved budget.
101
+
102
+ Waiting parents park instead of deadlocking or exceeding the cap. Their processes exit after saving context; the root broker retains child process descriptors and queued work. Parent wakes have lower priority than queued children, but spare capacity can wake a parent before all its children finish. Manual messages to a parked parent fail, and `message_lead_agent` fails while its immediate parent is parked. Wait for the parent to resume. The root can change the shared cap for this session with `/subagent:max-concurency`.
97
103
 
98
104
  A child calls `message_lead_agent(message)` to send nonblocking steering to its lead:
99
105
 
@@ -107,6 +113,8 @@ The child continues without waiting for a reply. The steering wakes an idle lead
107
113
 
108
114
  Delegate only when parallel work or context isolation saves enough effort to cover worker startup and coordination. Pass existing findings with the task so workers do not repeat your research.
109
115
 
116
+ Do not use Bash `sleep` or polling loops to wait for workers. Continue useful work, or end the turn and let completion steering wake the lead. Keep the session open. While the lead is idle and worker work remains, an animated `Waiting for subagents - don't close the session` line appears above the unchanged `Running N` line. Active lead turns keep Pi's normal `Working` indicator.
117
+
110
118
  ## Agent definitions
111
119
 
112
120
  There are no bundled agents. Without user-created definitions, every task uses the same default worker, with no agent-specific system prompt or instructions. It receives the parent's task text unchanged. Pi's normal system prompt and delegation limits still apply.
@@ -136,7 +144,7 @@ Collapsed results show each child's name, task, status, and most recent activity
136
144
 
137
145
  A live single line above the editor shows `Running N: Name elapsed · Name elapsed`, with `+N` for names that do not fit and a separate idle count. It uses live handles and snapshots, not session metadata or disk reads on timer ticks.
138
146
 
139
- `/subagent-expand <name>` opens a saved worker transcript. Its top section shows the current descendant-slot budget: allowed, used/reserved, and remaining. Used slots include allowances reserved for children and their descendants, not just currently running processes. Missing legacy budgets show as unknown. With no name, it opens a searchable picker. Running workers come first in depth order, with top-level workers before nested workers. Live idle parents waiting for children come next; completed or stopped history comes last. Name completion is fuzzy. Each task or resumed turn shows its actual provider/model and thinking level from the worker's session, not the parent's settings. Selected presets also appear as an intelligence label, kept separately for each run. Missing historical model/thinking metadata appears as `unknown`.
147
+ `/subagent:expand <name>` opens a saved worker transcript. Its top section shows the current descendant-slot budget: allowed, used/reserved, and remaining. Used slots include allowances reserved for children and their descendants, not just currently running processes. Missing legacy budgets show as unknown. With no name, it opens a searchable picker. Running workers come first in depth order, with top-level workers before nested workers. Live idle parents waiting for children come next; completed or stopped history comes last. Name completion is fuzzy. Each task or resumed turn shows its actual provider/model and thinking level from the worker's session, not the parent's settings. Selected presets also appear as an intelligence label, kept separately for each run. Missing historical model/thinking metadata appears as `unknown`.
140
148
 
141
149
  [Model presets](docs/configuration.md#caller-selected-intelligence) show labels such as `Nicolas (Junior/code-writer)` in regular tool results. One enabled preset applies automatically to new launches without exposing an `intelligence` argument. Two or more require an explicit `intelligence` choice on every launch item. Omitted or `null` choices reject the whole launch batch before any worker starts. Zero or disabled presets keep the existing launch defaults and show no intelligence label. Without an agent type, labels show `Nicolas (Junior)`; without either qualifier, they show just `Nicolas`. `message_subagent` does not accept `intelligence`; workers retain the original effective model, thinking, and label, even after configuration or parent settings change.
142
150
 
@@ -152,9 +160,9 @@ A live single line above the editor shows `Running N: Name elapsed · Name elaps
152
160
 
153
161
  `/message_subagent` is the human command for steering live workers. Choose `All (+nested)` for the whole live tree, `All` for top-level workers, `Youngest` for live workers with no running descendants, or `Names (e.g. John, Maria)` for comma-separated names or paths such as `John > Maria`. Then enter the message. There is no `No` choice; Esc cancels. The command does not resume completed workers. Automatic broadcast interception has been removed, so ordinary user input stays with the lead and never opens a routing prompt.
154
162
 
155
- A worker that has settled its own turn but still has descendants reports `Idle, waiting for children.` to the lead via steering, followed by its own last answer. Its process stays alive for child messages and completions. `Finished` means the whole subtree has settled, not just the worker's own turn.
163
+ A worker that has settled its own turn but still has descendants reports `Idle, waiting for children.` to the lead via steering, followed by its own last answer. While live it counts toward the cap. If parked, its process exits and the root broker later resumes its saved context. `Finished` means the whole subtree has settled, not just the worker's own turn.
156
164
 
157
- The `WITH SUBS` footer includes recursive worker usage. Resuming or privately forking a named worker adds usage without increasing the unique-worker count. See [usage accounting](docs/usage.md) for programmatic results.
165
+ The `WITH SUBS` footer includes recursive worker usage. Resuming a named worker adds usage without increasing the unique-worker count. See [usage accounting](docs/usage.md) for programmatic results.
158
166
 
159
167
  ## Development
160
168
 
@@ -0,0 +1,179 @@
1
+ import * as fs from "node:fs";
2
+ import * as path from "node:path";
3
+ import { createHash, createHmac, randomUUID } from "node:crypto";
4
+ import { setTimeout as delay } from "node:timers/promises";
5
+ import type { RunningSubagentHandle } from "../runner/options.js";
6
+ import { openTreeConcurrencyStore, type TreeConcurrencyStore } from "../storage/tree-concurrency.js";
7
+ import type { BrokerEndpoint } from "./contracts.js";
8
+ import { readManifest, writeExclusive } from "./files.js";
9
+
10
+ export async function steerBrokerJob(
11
+ endpoint: BrokerEndpoint,
12
+ ownerToken: string,
13
+ targetToken: string,
14
+ message: string,
15
+ ): Promise<boolean> {
16
+ const manifest = readManifest(endpoint);
17
+ const target = openTreeConcurrencyStore(manifest.concurrencyDirectory).get(targetToken);
18
+ const id = createHash("sha256").update(randomUUID()).digest("hex");
19
+ const request = { id, ordered: true, ownerToken, targetToken, message };
20
+ const mac = createHmac("sha256", endpoint.secret).update(JSON.stringify(request)).digest("hex");
21
+ commitCommand(endpoint, id, { request, mac });
22
+ if (target?.status === "queued") return true; // Durable queued delivery, not model acceptance yet.
23
+ const reply = path.join(endpoint.directory, "command-results", `${id}.json`);
24
+ for (;;) {
25
+ if (fs.existsSync(reply)) {
26
+ try {
27
+ return JSON.parse(fs.readFileSync(reply, "utf8")).accepted === true;
28
+ } catch {
29
+ /* The root may still be completing the write. */
30
+ }
31
+ }
32
+ readManifest(endpoint);
33
+ await delay(25);
34
+ }
35
+ }
36
+
37
+ export async function sendBrokerLead(endpoint: BrokerEndpoint, senderToken: string, message: string): Promise<boolean> {
38
+ readManifest(endpoint);
39
+ const id = createHash("sha256").update(randomUUID()).digest("hex");
40
+ const request = { id, ordered: true, kind: "lead", senderToken, message };
41
+ const mac = createHmac("sha256", endpoint.secret).update(JSON.stringify(request)).digest("hex");
42
+ commitCommand(endpoint, id, { request, mac });
43
+ const reply = path.join(endpoint.directory, "command-results", `${id}.json`);
44
+ const deadline = Date.now() + 30000;
45
+ while (Date.now() < deadline) {
46
+ if (fs.existsSync(reply)) {
47
+ try {
48
+ return JSON.parse(fs.readFileSync(reply, "utf8")).accepted === true;
49
+ } catch {
50
+ /* Wait for the root's reply to finish writing. */
51
+ }
52
+ }
53
+ readManifest(endpoint);
54
+ await delay(25);
55
+ }
56
+ return false;
57
+ }
58
+
59
+ function syncDirectory(directory: string): void {
60
+ // Windows cannot open directories for fsync. Command files and the log still sync.
61
+ if (process.platform === "win32") return;
62
+ const fd = fs.openSync(directory, "r");
63
+ try {
64
+ fs.fsyncSync(fd);
65
+ } finally {
66
+ fs.closeSync(fd);
67
+ }
68
+ }
69
+
70
+ function commitCommand(endpoint: BrokerEndpoint, id: string, envelope: unknown): void {
71
+ writeExclusive(path.join(endpoint.directory, "commands", `${id}.json`), envelope);
72
+ writeExclusive(path.join(endpoint.directory, "command-ready", `${id}.json`), { id });
73
+ syncDirectory(path.join(endpoint.directory, "commands"));
74
+ syncDirectory(path.join(endpoint.directory, "command-ready"));
75
+ const fd = fs.openSync(path.join(endpoint.directory, "command-order"), "a", 0o600);
76
+ try {
77
+ // One small O_APPEND write orders same-host submitters. A leading newline
78
+ // separates a torn, unacknowledged tail from the next complete record.
79
+ const record = `\n${id}\n`;
80
+ if (fs.writeSync(fd, record) !== Buffer.byteLength(record)) throw new Error("Incomplete broker order write.");
81
+ fs.fsyncSync(fd);
82
+ } finally {
83
+ fs.closeSync(fd);
84
+ }
85
+ syncDirectory(endpoint.directory);
86
+ }
87
+
88
+ const pending = new WeakMap<object, Map<string, string>>();
89
+ export function processBrokerCommands(
90
+ endpoint: BrokerEndpoint,
91
+ store: TreeConcurrencyStore,
92
+ handles: Map<string, RunningSubagentHandle>,
93
+ ): void {
94
+ let active = pending.get(handles);
95
+ if (!active) pending.set(handles, (active = new Map()));
96
+ const directory = path.join(endpoint.directory, "command-ready");
97
+ if (!fs.existsSync(directory)) return;
98
+ const ready = fs
99
+ .readdirSync(directory)
100
+ .filter(
101
+ (file) =>
102
+ /^[a-f0-9]{64}\.json$/.test(file) && !fs.existsSync(path.join(endpoint.directory, "command-results", file)),
103
+ );
104
+ const orderFile = path.join(endpoint.directory, "command-order");
105
+ const log = fs.existsSync(orderFile) ? fs.readFileSync(orderFile, "utf8") : "";
106
+ // Only newline-terminated records are committed. Never fall back to mtime
107
+ // for ordered requests whose append has not completed yet.
108
+ const logged = log
109
+ .slice(0, log.lastIndexOf("\n") + 1)
110
+ .split("\n")
111
+ .filter((id) => /^[a-f0-9]{64}$/.test(id))
112
+ .map((id) => `${id}.json`);
113
+ const legacy = ready
114
+ .filter((file) => {
115
+ const { request } = JSON.parse(fs.readFileSync(path.join(endpoint.directory, "commands", file), "utf8"));
116
+ return request.ordered !== true;
117
+ })
118
+ .sort(
119
+ (a, b) =>
120
+ fs.statSync(path.join(directory, a)).mtimeMs - fs.statSync(path.join(directory, b)).mtimeMs ||
121
+ a.localeCompare(b),
122
+ );
123
+ const blocked = new Set<string>();
124
+ for (const file of new Set([...legacy, ...logged])) {
125
+ if (!fs.existsSync(path.join(directory, file))) continue;
126
+ const reply = path.join(endpoint.directory, "command-results", file);
127
+ if (fs.existsSync(reply)) continue;
128
+ const { request, mac } = JSON.parse(fs.readFileSync(path.join(endpoint.directory, "commands", file), "utf8"));
129
+ const expected = createHmac("sha256", endpoint.secret).update(JSON.stringify(request)).digest("hex");
130
+ if (mac !== expected) throw new Error("Invalid broker command credentials.");
131
+ const lead = request.kind === "lead";
132
+ const sender = lead ? store.get(request.senderToken) : undefined;
133
+ const target = store.get(lead ? (sender?.parentToken ?? "") : request.targetToken);
134
+ if (
135
+ !target ||
136
+ (lead
137
+ ? sender?.status !== "running" || target.status !== "running"
138
+ : target.parentToken !== request.ownerToken) ||
139
+ ["stopping", "canceled", "released", "rejected", "parking", "suspended", "waking"].includes(target.status)
140
+ ) {
141
+ writeExclusive(reply, { accepted: false });
142
+ if (target && active.get(target.token) === file) active.delete(target.token);
143
+ continue;
144
+ }
145
+ if (blocked.has(target.token) || active.has(target.token)) continue;
146
+ blocked.add(target.token);
147
+ const handle = handles.get(target.token);
148
+ if (!handle) {
149
+ if (lead) writeExclusive(reply, { accepted: false });
150
+ continue; // Durable queued child steering waits for a root-owned handle.
151
+ }
152
+ if (lead) store.markWaiting(target.token, false);
153
+ active.set(target.token, file);
154
+ const finish = (accepted: boolean): void => {
155
+ // A stop can reject this command while its RPC is still unresolved.
156
+ if (!fs.existsSync(reply)) writeExclusive(reply, { accepted });
157
+ };
158
+ void Promise.resolve()
159
+ .then(() => {
160
+ if (fs.existsSync(reply)) return false;
161
+ // Stop may race the poll before this microtask reaches the handle.
162
+ const current = store.get(target.token);
163
+ if (
164
+ !current ||
165
+ ["stopping", "canceled", "released", "rejected", "parking", "suspended", "waking"].includes(current.status) ||
166
+ (lead && (current.status !== "running" || store.get(request.senderToken)?.status !== "running"))
167
+ )
168
+ return false;
169
+ return handle.steer(lead ? `Message from subagent ${sender!.name}:\n${request.message}` : request.message);
170
+ })
171
+ .then(
172
+ (accepted) => finish(accepted !== false),
173
+ () => finish(false),
174
+ )
175
+ .finally(() => {
176
+ if (active!.get(target.token) === file) active!.delete(target.token);
177
+ });
178
+ }
179
+ }
@@ -0,0 +1,63 @@
1
+ import type { AgentConfig } from "../agents.js";
2
+ import type { SubagentBudget } from "../budget.js";
3
+ import type { IntelligencePreset } from "../intelligence.js";
4
+ import type { SubagentSettings } from "../settings.js";
5
+ import type { SubagentModelSettings } from "../storage/name-records.js";
6
+ import type { SingleResult } from "../types.js";
7
+
8
+ export const BROKER_DIR_ENV = "PI_SUBAGENT_BROKER_DIR";
9
+ export const BROKER_SECRET_ENV = "PI_SUBAGENT_BROKER_SECRET";
10
+
11
+ export interface BrokerEndpoint {
12
+ directory: string;
13
+ secret: string;
14
+ }
15
+ export interface BrokerManifest {
16
+ version: 1;
17
+ rootPid: number;
18
+ rootStartTime?: string;
19
+ concurrencyDirectory: string;
20
+ }
21
+
22
+ /** A root-owned task. No callbacks, process-local closures, or AbortSignals cross the boundary. */
23
+ export interface BrokerJobSpec {
24
+ version: 1;
25
+ id: string;
26
+ token: string;
27
+ ownerToken: string;
28
+ ownerId: string;
29
+ toolCallId: string;
30
+ taskIndex: number;
31
+ name: string;
32
+ submittedAt?: number;
33
+ agents: AgentConfig[];
34
+ task: { agent: string; task: string; intelligence?: string };
35
+ cwd: string;
36
+ settings?: SubagentSettings;
37
+ projectTrusted: boolean;
38
+ parentDepth: number;
39
+ maxDepth: number;
40
+ parentAgentStack: string[];
41
+ preventCycles: boolean;
42
+ budget?: SubagentBudget;
43
+ sessionDir: string;
44
+ sessionRoot: string;
45
+ namesFile: string;
46
+ resumeSession: boolean;
47
+ initialResult?: SingleResult;
48
+ fallbackModel?: string;
49
+ resumeSettings?: SubagentModelSettings;
50
+ intelligencePresets?: IntelligencePreset[];
51
+ }
52
+ export type BrokerSubmission = Omit<BrokerJobSpec, "version" | "id" | "token">;
53
+ export interface BrokerReceipt {
54
+ id: string;
55
+ token: string;
56
+ name: string;
57
+ status: "queued";
58
+ }
59
+ export interface BrokerResult {
60
+ version: 1;
61
+ id: string;
62
+ result: SingleResult;
63
+ }
@@ -0,0 +1,158 @@
1
+ import * as fs from "node:fs";
2
+ import * as path from "node:path";
3
+ import { createHash, createHmac, timingSafeEqual } from "node:crypto";
4
+ import { setTimeout as delay } from "node:timers/promises";
5
+ import { matchesProcess, openTreeConcurrencyStore } from "../storage/tree-concurrency.js";
6
+ import { compactSingleResultForDurableDetails, isResultError, type SingleResult } from "../types.js";
7
+ import type {
8
+ BrokerEndpoint,
9
+ BrokerJobSpec,
10
+ BrokerManifest,
11
+ BrokerReceipt,
12
+ BrokerResult,
13
+ BrokerSubmission,
14
+ } from "./contracts.js";
15
+
16
+ export function brokerPath(endpoint: BrokerEndpoint, kind: string, id: string): string {
17
+ if (!/^[a-f0-9]{64}$/.test(id)) throw new Error("Invalid broker job identity.");
18
+ return path.join(endpoint.directory, kind, `${id}.json`);
19
+ }
20
+ export function writeExclusive(file: string, value: unknown): void {
21
+ fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
22
+ const fd = fs.openSync(file, "wx", 0o600);
23
+ try {
24
+ fs.writeFileSync(fd, JSON.stringify(value));
25
+ fs.fsyncSync(fd);
26
+ } finally {
27
+ fs.closeSync(fd);
28
+ }
29
+ }
30
+ export function readManifest(endpoint: BrokerEndpoint): BrokerManifest {
31
+ const secret = fs.readFileSync(path.join(endpoint.directory, "secret"), "utf8");
32
+ const a = Buffer.from(secret),
33
+ b = Buffer.from(endpoint.secret);
34
+ if (a.length !== b.length || !timingSafeEqual(a, b)) throw new Error("Invalid broker credentials.");
35
+ const manifest = JSON.parse(
36
+ fs.readFileSync(path.join(endpoint.directory, "manifest.json"), "utf8"),
37
+ ) as BrokerManifest;
38
+ if (manifest.version !== 1 || !matchesProcess(manifest.rootPid, manifest.rootStartTime))
39
+ throw new Error("The root worker broker is unavailable. Saved work was not relaunched.");
40
+ return manifest;
41
+ }
42
+ function signature(endpoint: BrokerEndpoint, spec: BrokerJobSpec): string {
43
+ return createHmac("sha256", endpoint.secret).update(JSON.stringify(spec)).digest("hex");
44
+ }
45
+ export function readBrokerJob(endpoint: BrokerEndpoint, id: string): BrokerJobSpec {
46
+ const envelope = JSON.parse(fs.readFileSync(brokerPath(endpoint, "jobs", id), "utf8"));
47
+ const spec = envelope.spec as BrokerJobSpec;
48
+ if (
49
+ spec?.version !== 1 ||
50
+ spec.id !== id ||
51
+ typeof envelope.mac !== "string" ||
52
+ signature(endpoint, spec) !== envelope.mac
53
+ )
54
+ throw new Error("Invalid authenticated broker job.");
55
+ return spec;
56
+ }
57
+ export function listBrokerJobs(endpoint: BrokerEndpoint, pendingOnly = false): BrokerJobSpec[] {
58
+ readManifest(endpoint);
59
+ const ready = path.join(endpoint.directory, "ready");
60
+ if (!fs.existsSync(ready)) return [];
61
+ return fs
62
+ .readdirSync(ready)
63
+ .filter(
64
+ (file) =>
65
+ /^[a-f0-9]{64}\.json$/.test(file) &&
66
+ (!pendingOnly || !fs.existsSync(brokerPath(endpoint, "finished", file.slice(0, -5)))),
67
+ )
68
+ .map((file) => readBrokerJob(endpoint, file.slice(0, -5)));
69
+ }
70
+
71
+ /** Receipt is synchronous and durable. No local admission queue can hide a nested launch. */
72
+ export function submitBrokerJob(
73
+ endpoint: BrokerEndpoint,
74
+ input: BrokerSubmission,
75
+ preparedToken?: string,
76
+ ): BrokerReceipt {
77
+ const manifest = readManifest(endpoint);
78
+ const id = createHash("sha256")
79
+ .update(JSON.stringify([input.ownerToken, input.toolCallId, input.taskIndex]))
80
+ .digest("hex");
81
+ const ready = brokerPath(endpoint, "ready", id);
82
+ if (fs.existsSync(ready)) {
83
+ const previous = readBrokerJob(endpoint, id);
84
+ if (previous.name !== input.name || previous.task.task !== input.task.task)
85
+ throw new Error("Broker submission identity conflicts with existing work.");
86
+ return { id, token: previous.token, name: previous.name, status: "queued" };
87
+ }
88
+ const store = openTreeConcurrencyStore(manifest.concurrencyDirectory);
89
+ const parent = store.get(input.ownerToken);
90
+ if (!parent || parent.pid !== process.pid || !store.isProcessAlive(parent))
91
+ throw new Error("Only the running owner worker may submit nested work.");
92
+ const token = preparedToken ?? store.enqueue(input.name, input.ownerToken);
93
+ const spec: BrokerJobSpec = JSON.parse(JSON.stringify({ ...input, submittedAt: Date.now(), version: 1, id, token }));
94
+ const reservation = store.get(token);
95
+ if (!reservation || reservation.parentToken !== input.ownerToken || reservation.name !== input.name)
96
+ throw new Error("Broker reservation does not belong to the submitting worker.");
97
+ try {
98
+ writeExclusive(brokerPath(endpoint, "jobs", id), { spec, mac: signature(endpoint, spec) });
99
+ writeExclusive(ready, { id });
100
+ } catch (error) {
101
+ store.stopSubtree(token);
102
+ store.release(token);
103
+ throw error;
104
+ }
105
+ return { id, token, name: input.name, status: "queued" };
106
+ }
107
+
108
+ export function readBrokerResult(endpoint: BrokerEndpoint, id: string): SingleResult | undefined {
109
+ const file = brokerPath(endpoint, "results", id);
110
+ if (!fs.existsSync(brokerPath(endpoint, "finished", id))) return undefined;
111
+ const stored = JSON.parse(fs.readFileSync(file, "utf8")) as BrokerResult;
112
+ if (stored.version !== 1 || stored.id !== id) throw new Error("Invalid broker result.");
113
+ return stored.result;
114
+ }
115
+ export function persistBrokerResult(endpoint: BrokerEndpoint, id: string, result: SingleResult): void {
116
+ if (fs.existsSync(brokerPath(endpoint, "finished", id))) return;
117
+ const compact = compactSingleResultForDurableDetails(result);
118
+ if (!compact.errorMessage && result.stderr && isResultError(result)) compact.errorMessage = result.stderr;
119
+ writeExclusive(brokerPath(endpoint, "results", id), { version: 1, id, result: compact });
120
+ writeExclusive(brokerPath(endpoint, "finished", id), { id });
121
+ }
122
+ export async function watchBrokerJob(
123
+ endpoint: BrokerEndpoint,
124
+ id: string,
125
+ signal?: AbortSignal,
126
+ onLead?: (text: string) => void,
127
+ ): Promise<SingleResult> {
128
+ const seen = new Set<string>();
129
+ for (;;) {
130
+ signal?.throwIfAborted();
131
+ const leads = path.join(endpoint.directory, "leads", id);
132
+ if (onLead && fs.existsSync(leads)) {
133
+ const spec = readBrokerJob(endpoint, id);
134
+ const store = openTreeConcurrencyStore(readManifest(endpoint).concurrencyDirectory);
135
+ const parent = store.get(spec.ownerToken);
136
+ for (const file of fs.readdirSync(leads)) {
137
+ if (seen.has(file)) continue;
138
+ seen.add(file);
139
+ const event = JSON.parse(fs.readFileSync(path.join(leads, file), "utf8"));
140
+ if (parent?.status === "running" && parent.pid === process.pid && event.ownerPid === process.pid)
141
+ onLead(String(event.message));
142
+ }
143
+ }
144
+ const result = readBrokerResult(endpoint, id);
145
+ if (result) return result;
146
+ readManifest(endpoint);
147
+ await delay(25, undefined, { signal });
148
+ }
149
+ }
150
+ export function ackBrokerJob(endpoint: BrokerEndpoint, id: string): void {
151
+ const file = brokerPath(endpoint, "acks", id);
152
+ if (!fs.existsSync(file)) writeExclusive(file, { id, at: Date.now() });
153
+ }
154
+ export function pendingBrokerJobs(endpoint: BrokerEndpoint, ownerToken: string): BrokerJobSpec[] {
155
+ return listBrokerJobs(endpoint).filter(
156
+ (spec) => spec.ownerToken === ownerToken && !fs.existsSync(brokerPath(endpoint, "acks", spec.id)),
157
+ );
158
+ }