@yaag/runtime 0.31.0 → 0.32.0

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.
@@ -0,0 +1,145 @@
1
+ /**
2
+ * The hc launcher (ADR-0072): it starts each Agent in an Agent Terminal, a
3
+ * child of the Host Terminal, and talks to pi over three FIFOs. The exit watch
4
+ * starts at `terminal.run`, so an exit of the program stops the FIFO open.
5
+ */
6
+
7
+ import { YaagError } from "../errors.ts";
8
+ import {
9
+ FIFO_OPEN_DEADLINE_MS,
10
+ type FifoEnds,
11
+ type FifoOpener,
12
+ makeFifoDir,
13
+ openFifoEnds,
14
+ removeFifoDir,
15
+ } from "./agent-fifos.ts";
16
+ import {
17
+ agentTerminalProcess,
18
+ type TerminalExit,
19
+ watchTerminalExit,
20
+ } from "./agent-terminal-process.ts";
21
+ import { type HcCalls, type HcRunParams, type HcStarted, isHcRpcKind } from "./hc-call.ts";
22
+ import { agentTerminalParams } from "./hc-terminal-request.ts";
23
+ import type { AgentProcess, LaunchRequest, ProcessLauncher } from "./process-launcher.ts";
24
+
25
+ /** Options of `createHcLauncher`. */
26
+ export interface HcLauncherOptions {
27
+ readonly calls: HcCalls;
28
+ /** The `HC_TERMINAL_ID` of the Orchestrator. */
29
+ readonly hostTerminal: string;
30
+ /** The Run id for the `yaag.run` label, when the Orchestrator has one. */
31
+ readonly runId?: string;
32
+ /** Opens the FIFO ends; tests replace it. */
33
+ readonly openFifos?: FifoOpener;
34
+ }
35
+
36
+ /** Starts one terminal; on `name_taken` it tries one more time with no name. */
37
+ async function runTerminal(calls: HcCalls, params: HcRunParams): Promise<HcStarted> {
38
+ try {
39
+ return await calls.run(params);
40
+ } catch (error) {
41
+ if (params.name === undefined || !isHcRpcKind(error, "name_taken")) throw error;
42
+ const { name: _taken, ...unnamed } = params;
43
+ return calls.run(unnamed);
44
+ }
45
+ }
46
+
47
+ /** True for the one pi failure of the hc launcher: `SPAWN_FAILED` for an early exit. */
48
+ export function isPiFailure(error: unknown): error is YaagError {
49
+ return error instanceof YaagError && error.code === "SPAWN_FAILED";
50
+ }
51
+
52
+ /**
53
+ * Opens the FIFO ends, and stops the open when the program exits. A failed
54
+ * open after the exit is a pi failure (`SPAWN_FAILED`); a failed open with no
55
+ * exit is an hc failure, and the error goes through unchanged.
56
+ */
57
+ async function openBeforeExit(options: {
58
+ readonly open: FifoOpener;
59
+ readonly dir: string;
60
+ readonly exit: TerminalExit;
61
+ readonly agent: string;
62
+ }): Promise<FifoEnds> {
63
+ const { open, dir, exit, agent } = options;
64
+ const stop = new AbortController();
65
+ void exit.exited.then(() => stop.abort());
66
+ try {
67
+ return await open(dir, FIFO_OPEN_DEADLINE_MS, stop.signal);
68
+ } catch (error) {
69
+ if (!exit.settled()) throw error;
70
+ const code = await exit.exited;
71
+ throw new YaagError(
72
+ "SPAWN_FAILED",
73
+ `agent "${agent}" exited (${code ?? "unknown"}) before its FIFOs opened`,
74
+ agent,
75
+ undefined,
76
+ error,
77
+ );
78
+ }
79
+ }
80
+
81
+ /**
82
+ * Cleans up after a failure past `terminal.run`: SIGKILL to the pid when
83
+ * `kill` is true, close the FIFO ends, and remove the terminal. The caller
84
+ * then removes the directory and rejects.
85
+ */
86
+ async function abandon(options: {
87
+ readonly calls: HcCalls;
88
+ readonly started: HcStarted;
89
+ readonly fifos: FifoEnds | undefined;
90
+ readonly kill: boolean;
91
+ }): Promise<void> {
92
+ const { calls, started, fifos, kill } = options;
93
+ // After an exit the pid can belong to another process, so no kill then.
94
+ if (kill) {
95
+ try {
96
+ process.kill(started.pid, "SIGKILL");
97
+ } catch {
98
+ // The process is gone already.
99
+ }
100
+ }
101
+ fifos?.close();
102
+ await calls.remove(started.address).catch(() => undefined);
103
+ }
104
+
105
+ /**
106
+ * Builds the hc launcher. On a failure it cleans up first (SIGKILL to the pid,
107
+ * `terminal.rm` when `terminal.run` started a terminal, the directory removed)
108
+ * and then rejects. It rejects with `SPAWN_FAILED` when the program exits
109
+ * before the FIFOs open; then it sends no SIGKILL. Every other rejection is an
110
+ * hc failure. It never falls back itself; `withDirectFallback` does.
111
+ */
112
+ export function createHcLauncher(options: HcLauncherOptions): ProcessLauncher {
113
+ const openFifos = options.openFifos ?? openFifoEnds;
114
+ return {
115
+ async launch(request: LaunchRequest): Promise<AgentProcess> {
116
+ const dir = await makeFifoDir();
117
+ let started: HcStarted | undefined;
118
+ let fifos: FifoEnds | undefined;
119
+ let exit: TerminalExit | undefined;
120
+ try {
121
+ const params = agentTerminalParams({
122
+ cmd: request.cmd,
123
+ cwd: request.cwd,
124
+ env: request.env,
125
+ fifoDir: dir,
126
+ hostTerminal: options.hostTerminal,
127
+ agent: request.agent,
128
+ ...(options.runId === undefined ? {} : { runId: options.runId }),
129
+ });
130
+ started = await runTerminal(options.calls, params);
131
+ exit = watchTerminalExit(options.calls, started);
132
+ fifos = await openBeforeExit({ open: openFifos, dir, exit, agent: request.agent });
133
+ return agentTerminalProcess({ started, fifos, calls: options.calls, dir, exit });
134
+ } catch (error) {
135
+ exit?.stop();
136
+ const piFailed = isPiFailure(error);
137
+ if (started !== undefined) {
138
+ await abandon({ calls: options.calls, started, fifos, kill: !piFailed });
139
+ }
140
+ removeFifoDir(dir);
141
+ throw error;
142
+ }
143
+ },
144
+ };
145
+ }
@@ -0,0 +1,77 @@
1
+ /**
2
+ * The `terminal.run` request of one Agent Terminal (ADR-0072). Pure functions.
3
+ */
4
+
5
+ import type { HcRunParams } from "./hc-call.ts";
6
+
7
+ /**
8
+ * The fixed script `sh -c` runs in the Agent Terminal. `$0 "$@"` is the pi
9
+ * command of the direct launcher; `exec` keeps the pid of `sh`, so the pid hc
10
+ * reports is the pid of pi.
11
+ */
12
+ export const AGENT_TERMINAL_SCRIPT =
13
+ 'exec "$0" "$@" <"$YAAG_FIFO_DIR/stdin" >"$YAAG_FIFO_DIR/stdout" 2>"$YAAG_FIFO_DIR/stderr"';
14
+
15
+ /** The environment variable that names the FIFO directory. */
16
+ export const FIFO_DIR_ENV = "YAAG_FIFO_DIR";
17
+
18
+ const NAME_LIMIT = 32;
19
+
20
+ /**
21
+ * The terminal name of an Agent: lower case, each character outside
22
+ * `a-z 0-9 . _ -` changed to `-`, cut to 32. An empty slug gives `undefined`.
23
+ */
24
+ export function agentTerminalName(agent: string): string | undefined {
25
+ const slug = agent
26
+ .toLowerCase()
27
+ .replace(/[^a-z0-9._-]/g, "-")
28
+ .slice(0, NAME_LIMIT);
29
+ return slug === "" ? undefined : slug;
30
+ }
31
+
32
+ /** The Agent env without any `HC_*` variable, plus `YAAG_FIFO_DIR`. */
33
+ export function agentTerminalEnv(
34
+ env: Readonly<Record<string, string>>,
35
+ fifoDir: string,
36
+ ): Record<string, string> {
37
+ const result: Record<string, string> = {};
38
+ for (const [key, value] of Object.entries(env)) {
39
+ if (!key.startsWith("HC_")) result[key] = value;
40
+ }
41
+ result[FIFO_DIR_ENV] = fifoDir;
42
+ return result;
43
+ }
44
+
45
+ /** What one Agent Terminal request is built from. */
46
+ export interface AgentTerminalInput {
47
+ readonly cmd: readonly string[];
48
+ readonly cwd: string;
49
+ readonly env: Readonly<Record<string, string>>;
50
+ readonly fifoDir: string;
51
+ /** The `HC_TERMINAL_ID` of the Orchestrator. */
52
+ readonly hostTerminal: string;
53
+ readonly agent: string;
54
+ readonly runId?: string;
55
+ }
56
+
57
+ /**
58
+ * Builds the `terminal.run` params. It never sets `outlive_parent` or a
59
+ * `herdr.*` label.
60
+ */
61
+ export function agentTerminalParams(input: AgentTerminalInput): HcRunParams {
62
+ const name = agentTerminalName(input.agent);
63
+ return {
64
+ argv: ["sh", "-c", AGENT_TERMINAL_SCRIPT, ...input.cmd],
65
+ env: agentTerminalEnv(input.env, input.fifoDir),
66
+ cwd: input.cwd,
67
+ caller: input.hostTerminal,
68
+ no_notify: true,
69
+ rm: true,
70
+ labels: {
71
+ "yaag.kind": "agent",
72
+ "yaag.agent": input.agent,
73
+ ...(input.runId === undefined ? {} : { "yaag.run": input.runId }),
74
+ },
75
+ ...(name === undefined ? {} : { name }),
76
+ };
77
+ }
@@ -7,6 +7,7 @@
7
7
  // which `transport/` already depends on (ADR-0039).
8
8
  export type { RecordedSpawnSelection } from "../model/index.ts";
9
9
  export { clearQueueThenAbort } from "./abort-command.ts";
10
+ export { type AgentLauncherOptions, liveTransportFor } from "./agent-launcher.ts";
10
11
  export { type AppendChannel, openAppendChannel } from "./append-env.ts";
11
12
  export { type CommandResponse, Connection } from "./connection.ts";
12
13
  export {
@@ -1,8 +1,10 @@
1
1
  import { YaagError } from "../errors.ts";
2
2
  import { type AppendChannel, openAppendChannel } from "./append-env.ts";
3
+ import { directLauncher } from "./direct-launcher.ts";
3
4
  import { FrameQueue } from "./frame-queue.ts";
4
5
  import { decodeFrames } from "./jsonl.ts";
5
6
  import { piCommand, piEnv, readModel, readStartup, readStats } from "./pi-state.ts";
7
+ import type { AgentProcess, ProcessLauncher } from "./process-launcher.ts";
6
8
  import { reap } from "./reap.ts";
7
9
  import { appendStderrTail, stderrDiagnostic } from "./stderr-tail.ts";
8
10
  import {
@@ -30,18 +32,26 @@ const STATS_TIMEOUT_MS = 2_000;
30
32
  /** How long an exit message waits for stderr, which grandchildren may hold open. */
31
33
  const STDERR_DRAIN_MS = 100;
32
34
 
35
+ /**
36
+ * Builds a live transport that gets each started `pi --mode rpc` process from
37
+ * `launcher`. A launch that rejects makes `open` reject with the same error.
38
+ */
39
+ export function createLiveTransport(launcher: ProcessLauncher): TransportFactory {
40
+ return {
41
+ async open(
42
+ options: OpenOptions,
43
+ observeStartup?: TransportStartupObserver,
44
+ ): Promise<AgentTransport> {
45
+ assertHostForkSource(options);
46
+ const transport = await LiveTransport.start(options, launcher);
47
+ await transport.ready(observeStartup);
48
+ return transport;
49
+ },
50
+ };
51
+ }
52
+
33
53
  /** Agents are real `pi --mode rpc` child processes (ADR-0001). */
34
- export const liveTransport: TransportFactory = {
35
- async open(
36
- options: OpenOptions,
37
- observeStartup?: TransportStartupObserver,
38
- ): Promise<AgentTransport> {
39
- assertHostForkSource(options);
40
- const transport = new LiveTransport(options);
41
- await transport.ready(observeStartup);
42
- return transport;
43
- },
44
- };
54
+ export const liveTransport: TransportFactory = createLiveTransport(directLauncher);
45
55
 
46
56
  /**
47
57
  * Refuses a Host Fork that has no path to fork from, before any process work.
@@ -65,7 +75,7 @@ class LiveTransport implements AgentTransport {
65
75
  model = "";
66
76
 
67
77
  readonly #name: string;
68
- readonly #process: Bun.Subprocess<"pipe", "pipe", "pipe">;
78
+ readonly #process: AgentProcess;
69
79
  /** Last bytes pi wrote to stderr; the only classification signal a spawn gets (ADR-0037). */
70
80
  #stderrTail = "";
71
81
  /** Settles when stderr reaches EOF, so an exit message can wait for the diagnostic. */
@@ -84,35 +94,41 @@ class LiveTransport implements AgentTransport {
84
94
  #nextId = 0;
85
95
  #closing: Promise<AgentStats> | null = null;
86
96
 
87
- constructor(options: OpenOptions) {
88
- this.#name = options.name;
97
+ /** Launches the process and builds the transport. Disposes the Append Channel on a failed launch. */
98
+ static async start(options: OpenOptions, launcher: ProcessLauncher): Promise<LiveTransport> {
89
99
  const contract = toolContract(options);
90
- this.#verification = contract === null ? null : { contract, probe: createToolProbe() };
91
- this.#append = openAppendChannel(options.appendSystemPrompt);
100
+ const append = openAppendChannel(options.appendSystemPrompt);
101
+ let child: AgentProcess;
92
102
  try {
93
- this.#process = Bun.spawn({
94
- cmd: piCommand(options, this.#verification ? TOOL_PROBE_EXTENSION_PATH : undefined),
103
+ child = await launcher.launch({
104
+ cmd: piCommand(options, contract ? TOOL_PROBE_EXTENSION_PATH : undefined),
95
105
  cwd: options.cwd,
106
+ agent: options.name,
96
107
  // The Append Channel builds the base environment (ADR-0061); the prompt
97
108
  // channel of ADR-0063 adds its own variable, always written, so no
98
109
  // nested pi inherits a stale one.
99
- env: { ...this.#append.env, ...piEnv(options) },
100
- stdin: "pipe",
101
- stdout: "pipe",
102
- // pi prints model and startup diagnostics to stderr and exits 1 (main() →
103
- // reportDiagnostics → process.exit(1)), so stderr carries the only reason
104
- // yaag can classify. The reader below drains it so pi never blocks.
105
- stderr: "pipe",
106
- // Its own process group, so the Agent sees stdin EOF rather than a signal
107
- // when the Orchestrator dies — EOF is the path that reaps grandchildren.
108
- detached: true,
110
+ env: { ...append.env, ...piEnv(options) },
109
111
  });
110
112
  } catch (error) {
111
113
  // No Agent exists to dispose the channel later: a missing `pi` or a bad
112
114
  // cwd would otherwise leave its temp directory behind forever.
113
- this.#append.dispose();
115
+ append.dispose();
114
116
  throw error;
115
117
  }
118
+ return new LiveTransport(options.name, child, append, contract);
119
+ }
120
+
121
+ private constructor(
122
+ name: string,
123
+ child: AgentProcess,
124
+ append: AppendChannel,
125
+ contract: ToolContract | null,
126
+ ) {
127
+ this.#name = name;
128
+ this.#process = child;
129
+ this.#append = append;
130
+ // Made after the launch, so a start that fails leaves no probe timer.
131
+ this.#verification = contract === null ? null : { contract, probe: createToolProbe() };
116
132
  void this.#read();
117
133
  // A stream error must not surface as an unhandled rejection: the tail is a
118
134
  // best-effort diagnostic, never a reason to fail an Agent that started.
@@ -194,22 +210,12 @@ class LiveTransport implements AgentTransport {
194
210
  async #shutdown(): Promise<AgentStats> {
195
211
  // Stats first: they are unavailable once the process is gone (ticket 02).
196
212
  const stats = await this.#readStats();
197
- const pid = this.#process.pid;
198
213
  try {
199
- await reap({
200
- exited: this.#process.exited,
201
- endStdin: () => this.#process.stdin.end(),
202
- terminate: () => this.#process.kill("SIGTERM"),
203
- destroyGroup: () => {
204
- try {
205
- process.kill(-pid, "SIGKILL");
206
- } catch {
207
- this.#process.kill("SIGKILL");
208
- }
209
- },
210
- });
214
+ await reap(this.#process);
211
215
  } finally {
212
- // A reap that throws must still release the Append Channel's temp file.
216
+ // A reap that throws must still release the Append Channel's temp file
217
+ // and what the launcher holds (an Agent Terminal and its FIFOs).
218
+ await this.#process.release();
213
219
  this.#append.dispose();
214
220
  }
215
221
  this.#queue.end();
@@ -257,7 +263,7 @@ class LiveTransport implements AgentTransport {
257
263
  await Promise.race([this.#stderrDone, Bun.sleep(STDERR_DRAIN_MS)]);
258
264
  throw new YaagError(
259
265
  "SPAWN_FAILED",
260
- `agent "${this.#name}" exited (${code})${stderrDiagnostic(this.#stderrTail)}`,
266
+ `agent "${this.#name}" exited (${code ?? "unknown"})${stderrDiagnostic(this.#stderrTail)}`,
261
267
  this.#name,
262
268
  );
263
269
  });
@@ -0,0 +1,39 @@
1
+ import type { ReapTarget } from "./reap.ts";
2
+
3
+ /** The stdin operations the live transport uses. */
4
+ export interface ProcessInput {
5
+ write(chunk: string): unknown;
6
+ flush(): unknown;
7
+ end(): unknown;
8
+ }
9
+
10
+ /** What a launcher needs to start one Agent process. */
11
+ export interface LaunchRequest {
12
+ readonly cmd: readonly string[];
13
+ readonly cwd: string;
14
+ readonly env: Readonly<Record<string, string>>;
15
+ /** The Agent name. The hc launcher uses it for the terminal name and a label. */
16
+ readonly agent: string;
17
+ }
18
+
19
+ /** One started Agent process. It is also the target of the reap ladder. */
20
+ export interface AgentProcess extends ReapTarget {
21
+ readonly pid: number;
22
+ readonly stdin: ProcessInput;
23
+ readonly stdout: ReadableStream<Uint8Array>;
24
+ readonly stderr: ReadableStream<Uint8Array>;
25
+ /** Settles at exit with the exit code, or null when the code is not known. */
26
+ readonly exited: Promise<number | null>;
27
+ /**
28
+ * Releases what the launcher holds for this process after the reap ladder:
29
+ * for an Agent Terminal, the `terminal.wait` call, the terminal, and the FIFO
30
+ * directory. The live transport calls it once, at the end of its shutdown,
31
+ * because only it knows when the ladder ends. It never throws.
32
+ */
33
+ release(): Promise<void>;
34
+ }
35
+
36
+ /** Starts one Agent process. Rejects when the process does not start. */
37
+ export interface ProcessLauncher {
38
+ launch(request: LaunchRequest): Promise<AgentProcess>;
39
+ }