@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,188 @@
1
+ /**
2
+ * The `AgentProcess` of one Agent Terminal (ADR-0072): frames over the FIFOs,
3
+ * the exit from `terminal.wait`, and the reap ladder by pid.
4
+ */
5
+
6
+ import { rm } from "node:fs/promises";
7
+ import type { FifoEnds } from "./agent-fifos.ts";
8
+ import type { HcCalls, HcStarted } from "./hc-call.ts";
9
+ import type { AgentProcess } from "./process-launcher.ts";
10
+
11
+ /** How often the pid is checked after `terminal.wait` fails. */
12
+ const PID_POLL_MS = 100;
13
+ /** The pause before the next wait after a reason that is not `timeout`. */
14
+ const WAIT_BACKOFF_MS = 1000;
15
+
16
+ /** What one Agent Terminal process is built from. */
17
+ export interface AgentTerminalParts {
18
+ readonly started: HcStarted;
19
+ readonly fifos: FifoEnds;
20
+ readonly calls: HcCalls;
21
+ /** The FIFO directory; `release()` removes it. */
22
+ readonly dir: string;
23
+ /** The exit watch, started at `terminal.run`. */
24
+ readonly exit: TerminalExit;
25
+ }
26
+
27
+ /** A stream that passes `source` through and resolves `ended` at its end. */
28
+ export function watchEnd(source: ReadableStream<Uint8Array>): {
29
+ stream: ReadableStream<Uint8Array>;
30
+ ended: Promise<void>;
31
+ } {
32
+ let resolve: () => void = () => {};
33
+ const ended = new Promise<void>((done) => {
34
+ resolve = done;
35
+ });
36
+ // `cancel` and a read error also settle `ended`, so the pid poll always starts.
37
+ const reader = source.getReader();
38
+ const stream = new ReadableStream<Uint8Array>({
39
+ async pull(controller) {
40
+ try {
41
+ const { done, value } = await reader.read();
42
+ if (done) {
43
+ resolve();
44
+ controller.close();
45
+ } else controller.enqueue(value);
46
+ } catch (error) {
47
+ resolve();
48
+ controller.error(error);
49
+ }
50
+ },
51
+ async cancel(reason) {
52
+ resolve();
53
+ await reader.cancel(reason).catch(() => undefined);
54
+ },
55
+ });
56
+ return { stream, ended };
57
+ }
58
+
59
+ function alive(pid: number): boolean {
60
+ try {
61
+ process.kill(pid, 0);
62
+ return true;
63
+ } catch (error) {
64
+ // EPERM means the process is there, owned by someone else.
65
+ return typeof error === "object" && error !== null && "code" in error && error.code === "EPERM";
66
+ }
67
+ }
68
+
69
+ function signal(pid: number, name: NodeJS.Signals): boolean {
70
+ try {
71
+ process.kill(pid, name);
72
+ return true;
73
+ } catch {
74
+ return false;
75
+ }
76
+ }
77
+
78
+ /** The exit watch of one Agent Terminal: `terminal.wait`, then the pid. */
79
+ export interface TerminalExit {
80
+ /** The exit code from hc, or `null` when only the pid told the exit. */
81
+ readonly exited: Promise<number | null>;
82
+ /** True once `exited` settled. */
83
+ settled(): boolean;
84
+ /** A later failed wait polls the pid only after `gate`; until then it polls at once. */
85
+ pollAfter(gate: Promise<void>): void;
86
+ /** Stops the wait and the pid poll. Idempotent. */
87
+ stop(): void;
88
+ }
89
+
90
+ /** Starts the `terminal.wait` loop of `started` at once. */
91
+ export function watchTerminalExit(calls: HcCalls, started: HcStarted): TerminalExit {
92
+ const { pid, address } = started;
93
+ const abort = new AbortController();
94
+ let gate: Promise<void> = Promise.resolve();
95
+ let done = false;
96
+ let timer: ReturnType<typeof setInterval> | undefined;
97
+ let settle: (code: number | null) => void = () => {};
98
+ const exited = new Promise<number | null>((resolve) => {
99
+ settle = (code) => {
100
+ clearInterval(timer);
101
+ done = true;
102
+ resolve(code);
103
+ };
104
+ });
105
+
106
+ const pollPid = (): void => {
107
+ timer = setInterval(() => {
108
+ if (!alive(pid)) settle(null);
109
+ }, PID_POLL_MS);
110
+ };
111
+
112
+ const waitLoop = async (): Promise<void> => {
113
+ while (!abort.signal.aborted) {
114
+ let result: Awaited<ReturnType<HcCalls["wait"]>>;
115
+ try {
116
+ result = await calls.wait(address, abort.signal);
117
+ } catch {
118
+ if (abort.signal.aborted) return;
119
+ // hc lost the terminal (for example `rm: true` removed it first):
120
+ // after the gate (at once before the FIFOs open, then the end of stdout),
121
+ // the pid tells when pi is gone.
122
+ await gate;
123
+ if (!abort.signal.aborted) pollPid();
124
+ return;
125
+ }
126
+ if (result.kind === "exit") {
127
+ settle(result.code);
128
+ return;
129
+ }
130
+ // A status reason returns at once; the pause keeps it from a hot loop.
131
+ if (result.reason !== "timeout") await Bun.sleep(WAIT_BACKOFF_MS);
132
+ }
133
+ };
134
+ void waitLoop();
135
+
136
+ return {
137
+ exited,
138
+ settled: () => done,
139
+ pollAfter: (next) => {
140
+ gate = next;
141
+ },
142
+ stop: () => {
143
+ abort.abort();
144
+ clearInterval(timer);
145
+ },
146
+ };
147
+ }
148
+
149
+ /** Builds the process over the exit watch that the launcher started. */
150
+ export function agentTerminalProcess(parts: AgentTerminalParts): AgentProcess {
151
+ const { started, fifos, calls, dir, exit } = parts;
152
+ const { pid, address } = started;
153
+ const out = watchEnd(fifos.stdout);
154
+ exit.pollAfter(out.ended);
155
+
156
+ let released: Promise<void> | null = null;
157
+ const release = async (): Promise<void> => {
158
+ exit.stop();
159
+ fifos.close();
160
+ try {
161
+ await calls.remove(address);
162
+ } catch {
163
+ // `not_found` means hc removed it already; other failures are ignored.
164
+ }
165
+ await rm(dir, { recursive: true, force: true }).catch(() => undefined);
166
+ };
167
+
168
+ return {
169
+ pid,
170
+ stdin: fifos.stdin,
171
+ stdout: out.stream,
172
+ stderr: fifos.stderr,
173
+ exited: exit.exited,
174
+ endStdin: () => {
175
+ fifos.stdin.end();
176
+ },
177
+ terminate: () => {
178
+ signal(pid, "SIGTERM");
179
+ },
180
+ destroyGroup: () => {
181
+ if (!signal(-pid, "SIGKILL")) signal(pid, "SIGKILL");
182
+ },
183
+ release: () => {
184
+ released ??= release();
185
+ return released;
186
+ },
187
+ };
188
+ }
@@ -0,0 +1,48 @@
1
+ import type { AgentProcess, LaunchRequest, ProcessLauncher } from "./process-launcher.ts";
2
+
3
+ /**
4
+ * Starts pi as a direct child process with `Bun.spawn`, in its own process group.
5
+ *
6
+ * `launch` rejects when `Bun.spawn` throws, for example on a missing `pi`
7
+ * binary or a `cwd` that does not exist.
8
+ */
9
+ export const directLauncher: ProcessLauncher = {
10
+ async launch(request: LaunchRequest): Promise<AgentProcess> {
11
+ const child = Bun.spawn({
12
+ cmd: [...request.cmd],
13
+ cwd: request.cwd,
14
+ env: { ...request.env },
15
+ stdin: "pipe",
16
+ stdout: "pipe",
17
+ // pi prints model and startup diagnostics to stderr and exits 1 (main() →
18
+ // reportDiagnostics → process.exit(1)), so stderr carries the only reason
19
+ // yaag can classify. The live transport's stderr reader drains the pipe, so pi
20
+ // never blocks.
21
+ stderr: "pipe",
22
+ // Its own process group, so the Agent sees stdin EOF rather than a signal
23
+ // when the Orchestrator dies — EOF is the path that reaps grandchildren.
24
+ detached: true,
25
+ });
26
+ const pid = child.pid;
27
+ return {
28
+ pid,
29
+ stdin: child.stdin,
30
+ stdout: child.stdout,
31
+ stderr: child.stderr,
32
+ exited: child.exited,
33
+ endStdin: () => {
34
+ child.stdin.end();
35
+ },
36
+ terminate: () => child.kill("SIGTERM"),
37
+ // A direct child holds nothing past its exit.
38
+ release: async () => {},
39
+ destroyGroup: () => {
40
+ try {
41
+ process.kill(-pid, "SIGKILL");
42
+ } catch {
43
+ child.kill("SIGKILL");
44
+ }
45
+ },
46
+ };
47
+ },
48
+ };
@@ -0,0 +1,115 @@
1
+ /**
2
+ * The hc call interface (ADR-0072): the three hc operations the hc launcher
3
+ * uses, and the narrowing of an hc response. A test replaces `HcCalls` with a
4
+ * fake; production uses `hc-connect.ts`.
5
+ */
6
+
7
+ /** The params of one `terminal.run` request for an Agent Terminal. */
8
+ export interface HcRunParams {
9
+ readonly argv: readonly string[];
10
+ readonly env: Readonly<Record<string, string>>;
11
+ readonly cwd: string;
12
+ /** The Host Terminal id: the Agent Terminal becomes its child. */
13
+ readonly caller: string;
14
+ readonly no_notify: true;
15
+ readonly rm: true;
16
+ readonly labels: Readonly<Record<string, string>>;
17
+ /** The slug of the Agent name; absent when the slug is empty or taken. */
18
+ readonly name?: string;
19
+ }
20
+
21
+ /** What `terminal.run` gives back. */
22
+ export interface HcStarted {
23
+ readonly address: string;
24
+ readonly pid: number;
25
+ }
26
+
27
+ /** One `terminal.wait` result: the program exited, or the wait must run again. */
28
+ export type HcWaitResult =
29
+ | { readonly kind: "exit"; readonly code: number | null }
30
+ | { readonly kind: "pending"; readonly reason: string };
31
+
32
+ /** Why one hc call failed. The `rpc` kind drives the `name_taken` retry. */
33
+ export type HcFailure =
34
+ | { readonly type: "rpc"; readonly kind: string }
35
+ | { readonly type: "timeout" }
36
+ /** The caller aborted the call; not an hc failure. */
37
+ | { readonly type: "aborted" }
38
+ | { readonly type: "start" }
39
+ | { readonly type: "protocol" };
40
+
41
+ /** An hc call that failed. The message never holds the request text. */
42
+ export class HcCallError extends Error {
43
+ readonly failure: HcFailure;
44
+
45
+ constructor(failure: HcFailure, message: string) {
46
+ super(message);
47
+ this.name = "HcCallError";
48
+ this.failure = failure;
49
+ }
50
+ }
51
+
52
+ /** The three hc operations of an Agent Terminal. */
53
+ export interface HcCalls {
54
+ run(params: HcRunParams): Promise<HcStarted>;
55
+ /** One `terminal.wait`; `signal` stops the call. */
56
+ wait(terminal: string, signal: AbortSignal): Promise<HcWaitResult>;
57
+ remove(terminal: string): Promise<void>;
58
+ }
59
+
60
+ /** True when `error` is an hc RPC failure of the given kind. */
61
+ export function isHcRpcKind(error: unknown, kind: string): boolean {
62
+ return (
63
+ error instanceof HcCallError && error.failure.type === "rpc" && error.failure.kind === kind
64
+ );
65
+ }
66
+
67
+ function isRecord(value: unknown): value is Record<string, unknown> {
68
+ return typeof value === "object" && value !== null && !Array.isArray(value);
69
+ }
70
+
71
+ function protocolError(method: string): HcCallError {
72
+ return new HcCallError({ type: "protocol" }, `hc ${method}: the response is not valid`);
73
+ }
74
+
75
+ /**
76
+ * Parses one response line and gives its `result`. An `error` member becomes
77
+ * an `rpc` failure with `data.kind`; anything else that is not JSON-RPC is a
78
+ * `protocol` failure.
79
+ */
80
+ export function responseResult(line: string, method: string): Record<string, unknown> {
81
+ let parsed: unknown;
82
+ try {
83
+ parsed = JSON.parse(line);
84
+ } catch {
85
+ throw protocolError(method);
86
+ }
87
+ if (!isRecord(parsed)) throw protocolError(method);
88
+ const { error, result } = parsed;
89
+ if (isRecord(error)) {
90
+ const data = error.data;
91
+ const kind = isRecord(data) && typeof data.kind === "string" ? data.kind : "unknown";
92
+ const text = typeof error.message === "string" ? `: ${error.message}` : "";
93
+ throw new HcCallError({ type: "rpc", kind }, `hc ${method} failed (${kind})${text}`);
94
+ }
95
+ if (!isRecord(result)) throw protocolError(method);
96
+ return result;
97
+ }
98
+
99
+ /** Narrows a `terminal.run` result. A pid that is not a positive integer is a protocol failure. */
100
+ export function startedOf(result: Record<string, unknown>): HcStarted {
101
+ const { address, pid } = result;
102
+ if (typeof address !== "string" || address === "") throw protocolError("terminal.run");
103
+ if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) {
104
+ throw protocolError("terminal.run");
105
+ }
106
+ return { address, pid };
107
+ }
108
+
109
+ /** Narrows a `terminal.wait` result. Only `reason: "exit"` is an exit. */
110
+ export function waitResultOf(result: Record<string, unknown>): HcWaitResult {
111
+ const { reason, exit_code: code } = result;
112
+ if (typeof reason !== "string") throw protocolError("terminal.wait");
113
+ if (reason !== "exit") return { kind: "pending", reason };
114
+ return { kind: "exit", code: typeof code === "number" && Number.isInteger(code) ? code : null };
115
+ }
@@ -0,0 +1,137 @@
1
+ /**
2
+ * The production hc call interface: one `hc connect` child for each call
3
+ * (ADR-0072). The child gets the Orchestrator's environment, which holds the
4
+ * socket and the session of the hc core.
5
+ *
6
+ * The request line holds the Agent environment, API keys included. It goes
7
+ * only through the stdin pipe; no error message, log, or file holds it.
8
+ */
9
+
10
+ import {
11
+ HcCallError,
12
+ type HcCalls,
13
+ type HcRunParams,
14
+ type HcStarted,
15
+ type HcWaitResult,
16
+ responseResult,
17
+ startedOf,
18
+ waitResultOf,
19
+ } from "./hc-call.ts";
20
+
21
+ /** The time limit of `terminal.run` and `terminal.rm`. */
22
+ export const HC_CALL_TIMEOUT_MS = 5000;
23
+ /** The server-side `timeout` of one `terminal.wait`, in seconds. */
24
+ export const HC_WAIT_SECONDS = 60;
25
+
26
+ /** Options of `createHcConnectCalls`. */
27
+ export interface HcConnectOptions {
28
+ /** The time limit of `run` and `remove`; tests make it small. */
29
+ readonly timeoutMs?: number;
30
+ }
31
+
32
+ interface CallLimit {
33
+ readonly timeoutMs?: number;
34
+ readonly signal?: AbortSignal;
35
+ }
36
+
37
+ /** Builds the hc call interface over `hcPath connect`. */
38
+ export function createHcConnectCalls(hcPath: string, options: HcConnectOptions = {}): HcCalls {
39
+ const timeoutMs = options.timeoutMs ?? HC_CALL_TIMEOUT_MS;
40
+ return {
41
+ async run(params: HcRunParams): Promise<HcStarted> {
42
+ return startedOf(await call(hcPath, "terminal.run", params, { timeoutMs }));
43
+ },
44
+ async wait(terminal: string, signal: AbortSignal): Promise<HcWaitResult> {
45
+ const params = { terminal, timeout: HC_WAIT_SECONDS };
46
+ return waitResultOf(await call(hcPath, "terminal.wait", params, { signal }));
47
+ },
48
+ async remove(terminal: string): Promise<void> {
49
+ await call(hcPath, "terminal.rm", { terminal }, { timeoutMs });
50
+ },
51
+ };
52
+ }
53
+
54
+ /** Starts `hc connect`, writes one request line, and reads one response line. */
55
+ async function call(
56
+ hcPath: string,
57
+ method: string,
58
+ params: unknown,
59
+ limit: CallLimit,
60
+ ): Promise<Record<string, unknown>> {
61
+ if (limit.signal?.aborted) throw new HcCallError({ type: "aborted" }, `hc ${method}: aborted`);
62
+ let child: Bun.Subprocess<"pipe", "pipe", "pipe">;
63
+ try {
64
+ child = Bun.spawn({
65
+ cmd: [hcPath, "connect"],
66
+ env: { ...process.env },
67
+ stdin: "pipe",
68
+ stdout: "pipe",
69
+ stderr: "pipe",
70
+ });
71
+ } catch {
72
+ throw new HcCallError({ type: "start" }, `hc ${method}: hc connect did not start`);
73
+ }
74
+ void drain(child.stderr);
75
+ let timer: ReturnType<typeof setTimeout> | undefined;
76
+ let onAbort: (() => void) | undefined;
77
+ const stopped = new Promise<never>((_resolve, reject) => {
78
+ const stop = (type: "timeout" | "aborted", message: string): void => {
79
+ child.kill("SIGKILL");
80
+ reject(new HcCallError({ type }, `hc ${method}: ${message}`));
81
+ };
82
+ if (limit.timeoutMs !== undefined) {
83
+ const ms = limit.timeoutMs;
84
+ timer = setTimeout(() => stop("timeout", `no answer in ${ms} ms`), ms);
85
+ }
86
+ onAbort = () => stop("aborted", "aborted");
87
+ limit.signal?.addEventListener("abort", onAbort, { once: true });
88
+ });
89
+ stopped.catch(() => undefined);
90
+ try {
91
+ child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: 1, method, params })}\n`);
92
+ child.stdin.flush();
93
+ const line = await Promise.race([firstLine(child.stdout, method), stopped]);
94
+ return responseResult(line, method);
95
+ } finally {
96
+ clearTimeout(timer);
97
+ if (onAbort !== undefined) limit.signal?.removeEventListener("abort", onAbort);
98
+ try {
99
+ child.stdin.end();
100
+ } catch {
101
+ // The child may be gone already.
102
+ }
103
+ child.kill("SIGKILL");
104
+ }
105
+ }
106
+
107
+ /** Reads up to the first newline. A stream that ends first is a protocol failure. */
108
+ async function firstLine(stream: ReadableStream<Uint8Array>, method: string): Promise<string> {
109
+ const decoder = new TextDecoder();
110
+ const reader = stream.getReader();
111
+ let text = "";
112
+ try {
113
+ for (;;) {
114
+ const { done, value } = await reader.read();
115
+ if (done) break;
116
+ text += decoder.decode(value, { stream: true });
117
+ const end = text.indexOf("\n");
118
+ if (end >= 0) return text.slice(0, end);
119
+ }
120
+ } catch {
121
+ // A read failure is the same as no line.
122
+ } finally {
123
+ reader.releaseLock();
124
+ }
125
+ if (text.trim() !== "") return text;
126
+ throw new HcCallError({ type: "protocol" }, `hc ${method}: no response line`);
127
+ }
128
+
129
+ async function drain(stream: ReadableStream<Uint8Array>): Promise<void> {
130
+ try {
131
+ for await (const _chunk of stream) {
132
+ // stderr of hc connect is not used.
133
+ }
134
+ } catch {
135
+ // Ignored.
136
+ }
137
+ }
@@ -0,0 +1,77 @@
1
+ /**
2
+ * The hc failure rule (ADR-0072): no hc failure fails a Run. The first hc failure of the hc
3
+ * launcher writes one warning and turns Agent Terminals off for the Run; that Agent and every
4
+ * later Agent start with the direct launcher, with no more hc calls. A `SPAWN_FAILED` for a
5
+ * program that exits before its FIFOs open is a pi failure, not an hc failure.
6
+ */
7
+
8
+ import { isPiFailure } from "./hc-launcher.ts";
9
+ import type { AgentProcess, LaunchRequest, ProcessLauncher } from "./process-launcher.ts";
10
+
11
+ /** The launchers the fallback wraps, and the warning sink. */
12
+ export interface HcFallbackOptions {
13
+ /** The hc launcher; it cleans up before it rejects. */
14
+ readonly hc: ProcessLauncher;
15
+ readonly direct: ProcessLauncher;
16
+ /** Takes one warning line; best-effort stderr by default. */
17
+ readonly warn?: (line: string) => void;
18
+ }
19
+
20
+ const REASON_LIMIT = 200;
21
+
22
+ /** The one warning line of a fallback. */
23
+ export function hcFallbackWarning(reason: string): string {
24
+ return `yaag: hc agent terminals are off for this run: ${reason}`;
25
+ }
26
+
27
+ /** One printable line from an error: no control characters, bounded length. */
28
+ function reasonOf(error: unknown): string {
29
+ const raw = error instanceof Error ? error.message : String(error);
30
+ // biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what we strip.
31
+ const line = raw.replace(/[\u0000-\u001f\u007f]+/g, " ").trim();
32
+ const text = line === "" ? "unknown hc failure" : line;
33
+ return text.length > REASON_LIMIT ? `${text.slice(0, REASON_LIMIT)}…` : text;
34
+ }
35
+
36
+ function writeStderr(line: string): void {
37
+ try {
38
+ process.stderr.write(`${line}\n`);
39
+ } catch {
40
+ // A warning must never fail the Run.
41
+ }
42
+ }
43
+
44
+ /**
45
+ * Wraps the hc launcher for one Run. A `SPAWN_FAILED` from `hc.launch` for a program that exits
46
+ * before its FIFOs open passes through with no warning and no change. Every other rejection is
47
+ * an hc failure: it writes one warning per Run, sets the Run's "off" state, and
48
+ * launches the same request with `direct`. Launches already in flight finish
49
+ * their own hc sequence; a launch that starts after "off" makes no hc call.
50
+ * It never rejects for an hc reason; it rejects only with that `SPAWN_FAILED`
51
+ * or when the direct launch rejects.
52
+ */
53
+ export function withDirectFallback(options: HcFallbackOptions): ProcessLauncher {
54
+ const warn = options.warn ?? writeStderr;
55
+ let off = false;
56
+ let warned = false;
57
+ return {
58
+ async launch(request: LaunchRequest): Promise<AgentProcess> {
59
+ if (off) return options.direct.launch(request);
60
+ try {
61
+ return await options.hc.launch(request);
62
+ } catch (error) {
63
+ if (isPiFailure(error)) throw error;
64
+ off = true;
65
+ if (!warned) {
66
+ warned = true;
67
+ try {
68
+ warn(hcFallbackWarning(reasonOf(error)));
69
+ } catch {
70
+ // A warning must never fail the Run.
71
+ }
72
+ }
73
+ return options.direct.launch(request);
74
+ }
75
+ },
76
+ };
77
+ }