@yaag/runtime 0.26.0 → 0.27.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.
Files changed (54) hide show
  1. package/package.json +1 -1
  2. package/src/agent/agent.ts +29 -17
  3. package/src/agent/fork.ts +40 -12
  4. package/src/agent/host-fork.ts +85 -0
  5. package/src/agent/spawn-definition-request.ts +38 -3
  6. package/src/agent/spawn-open.ts +43 -103
  7. package/src/agent/spawn-plan.ts +114 -0
  8. package/src/agent/spawn-request.ts +16 -2
  9. package/src/agent/spawn.ts +20 -3
  10. package/src/ask/ask-exchange-options.ts +3 -6
  11. package/src/ask/ask-exchange.ts +48 -108
  12. package/src/ask/ask-guard.ts +207 -0
  13. package/src/ask/ask-timing.ts +12 -0
  14. package/src/ask/index.ts +1 -0
  15. package/src/cassette/cassette-loader.ts +9 -20
  16. package/src/cassette/cassette-schema.ts +10 -1
  17. package/src/cassette/cassette.ts +11 -34
  18. package/src/cassette/checkpoint.ts +306 -0
  19. package/src/cassette/index.ts +16 -7
  20. package/src/cassette/parked-asks.ts +38 -0
  21. package/src/cassette/replay-divergence.ts +7 -102
  22. package/src/cassette/resume-identity.ts +5 -1
  23. package/src/cassette/resume-preconditions.ts +14 -0
  24. package/src/cassette/resume-transport.ts +26 -32
  25. package/src/cassette/run-identity.ts +109 -0
  26. package/src/cassette/session-answer.ts +51 -114
  27. package/src/cassette/spawn-identity.ts +318 -0
  28. package/src/contract/error-codes.ts +1 -0
  29. package/src/contract/index.ts +1 -0
  30. package/src/contract/spawn-options.ts +33 -2
  31. package/src/error-factories.ts +8 -0
  32. package/src/events.ts +4 -2
  33. package/src/index.ts +4 -0
  34. package/src/pi-session/append-tool-result.ts +165 -0
  35. package/src/pi-session/index.ts +30 -0
  36. package/src/pi-session/pi-session-error.ts +34 -0
  37. package/src/pi-session/session-copy.ts +113 -0
  38. package/src/pi-session/session-entries.ts +130 -0
  39. package/src/question-summary/index.ts +4 -8
  40. package/src/question-summary/summarize-question.ts +1 -1
  41. package/src/question-summary/summary-policy.ts +5 -2
  42. package/src/run/agent-questions.ts +82 -0
  43. package/src/run/answers.ts +22 -1
  44. package/src/run/host-session.ts +233 -0
  45. package/src/run/index.ts +7 -0
  46. package/src/run/run-context.ts +3 -0
  47. package/src/run/run.ts +191 -181
  48. package/src/transport/live-transport.ts +19 -0
  49. package/src/transport/pi-state.ts +10 -1
  50. package/src/transport/transport.ts +13 -9
  51. package/src/types.ts +1 -0
  52. package/src/cassette/checkpoint-flush.ts +0 -101
  53. package/src/cassette/run-checkpoint.ts +0 -272
  54. package/src/question-summary/session-copy.ts +0 -169
@@ -1,272 +0,0 @@
1
- import { mkdir, unlink } from "node:fs/promises";
2
- import { dirname } from "node:path";
3
- import { YaagError } from "../errors.ts";
4
- import type { RunOutcome } from "../events.ts";
5
- import type {
6
- CassetteAnswer,
7
- CassetteCollector,
8
- CassetteQuestion,
9
- CassetteRun,
10
- } from "./cassette.ts";
11
- import { publishCassette } from "./cassette-publish.ts";
12
- import { sha256Hex } from "./program-hash.ts";
13
-
14
- /** What a resume is about to re-execute; resolved once, at Run start. */
15
- export type RunIdentity = Omit<CassetteRun, "outcome" | "questions" | "answers" | "reason">;
16
-
17
- /**
18
- * The wake payload of a paused or stopped Run (ADR-0021). It is settlement
19
- * data, never invocation identity, so it travels beside `RunIdentity`.
20
- */
21
- export interface RunWakePayload {
22
- readonly questions: readonly CassetteQuestion[];
23
- /** Questions this Run resolved, plus every answer it inherited (ADR-0022). */
24
- readonly answers?: readonly CassetteAnswer[];
25
- readonly reason?: string;
26
- }
27
-
28
- /**
29
- * One Run's publication request: what settled, what it collected, and where the
30
- * artifact goes. The destination is fixed at Run start (ADR-0031): the
31
- * `--record` path itself, or one name in the checkpoint directory.
32
- */
33
- export interface RunCheckpointOptions {
34
- /** Terminal outcome; `stopped` and `paused` keep the artifact without `record`. */
35
- readonly outcome: RunOutcome;
36
- readonly collector: CassetteCollector;
37
- /** Explicit `--record` destination, or undefined when the Run only checkpoints. */
38
- readonly record: string | undefined;
39
- /** Where this Run's artifact lives, in-flight and at settlement. */
40
- readonly destination: string;
41
- /** Invocation identity written into the artifact's run block. */
42
- readonly identity: RunIdentity;
43
- /**
44
- * Wake payload: the Questions and the pause reason collected at settlement.
45
- * They ride a `paused`
46
- * and a `stopped` artifact only: a stop that overrides a drain must not
47
- * discard collected Questions (ADR-0021). An in-flight `interrupted` flush
48
- * carries neither, and a hard death mid-pause loses them.
49
- */
50
- readonly wake?: RunWakePayload;
51
- }
52
-
53
- /**
54
- * What one publication attempt did. `published` covers both a written artifact
55
- * and a Run that keeps none. `displaced` carries the error that must become the
56
- * Run's outcome. `lost` reports a Checkpoint the Run asked for and did not get,
57
- * while the Run keeps its own outcome — a completed result, or a primary
58
- * program error (ADR-0021 amendment).
59
- */
60
- export type RunCheckpointResult =
61
- | { readonly kind: "published" }
62
- | { readonly kind: "displaced"; readonly error: unknown }
63
- | { readonly kind: "lost"; readonly message: string };
64
-
65
- /**
66
- * Publishes the collected Cassette when the Run must be restorable: always under
67
- * `--record`, and additionally into the checkpoint directory when the Run
68
- * stopped or paused (ADR-0021/0024).
69
- */
70
- export async function publishRunCheckpoint(
71
- options: RunCheckpointOptions,
72
- ): Promise<RunCheckpointResult> {
73
- if (!keepsCheckpoint(options)) {
74
- // A clean settlement without --record publishes nothing, so the in-flight
75
- // artifact this Run flushed goes away with it (ADR-0031).
76
- await discardCheckpoint(options.destination);
77
- return { kind: "published" };
78
- }
79
- try {
80
- await ensureCheckpointDirectory(options.record, options.destination);
81
- await publishCassette(
82
- options.destination,
83
- options.collector.cassette({
84
- outcome: options.outcome,
85
- ...options.identity,
86
- ...wakePayload(options.outcome, options.wake),
87
- }),
88
- );
89
- return { kind: "published" };
90
- } catch (error) {
91
- // A secondary publication failure must not displace a primary program error,
92
- // so the loss rides on run_end instead (ticket 04). The stderr diagnostic
93
- // stays: it is the CLI user's own trace of the loss.
94
- if (options.outcome === "failed") {
95
- writeRecordingDiagnostic(error);
96
- return { kind: "lost", message: String(error) };
97
- }
98
- // A completed Run keeps its outcome and its result: the work is done, and
99
- // no restorability promise is broken. The lost Cassette rides
100
- // run_end.checkpointLost and the stderr diagnostic instead of displacing
101
- // the outcome (ADR-0021 amendment).
102
- if (options.outcome === "completed") {
103
- const message = `run completed but its Cassette could not be written: ${String(error)}`;
104
- writeRecordingDiagnostic(message);
105
- return { kind: "lost", message };
106
- }
107
- // A pausing or stopped Run promises restorability, and a Checkpoint that
108
- // did not land makes that acknowledgement a lie, so the failure takes the
109
- // outcome (ADR-0021: a flush failure is a hard failure there).
110
- return {
111
- kind: "displaced",
112
- error: new Error(`run ${options.outcome} but is not restorable: ${String(error)}`, {
113
- cause: error,
114
- }),
115
- };
116
- }
117
- }
118
-
119
- /**
120
- * The wake payload of a run block. Empty for every outcome other than `paused`
121
- * and `stopped`, and minimal for a plain `ctx.pause()`, so an artifact that
122
- * collected nothing keeps the bytes it had before this field existed.
123
- *
124
- * A `failed` artifact keeps no answers either, exactly as it keeps no
125
- * Questions: it is not a resume source of the answer contract, and a resume of
126
- * the Checkpoint that preceded it takes the answers again (ADR-0022).
127
- */
128
- function wakePayload(
129
- outcome: RunOutcome,
130
- wake: RunWakePayload | undefined,
131
- ): Pick<CassetteRun, "questions" | "answers" | "reason"> {
132
- if (wake === undefined || (outcome !== "paused" && outcome !== "stopped")) return {};
133
- return {
134
- ...(wake.questions.length === 0 ? {} : { questions: wake.questions }),
135
- ...(wake.answers === undefined || wake.answers.length === 0 ? {} : { answers: wake.answers }),
136
- ...(wake.reason === undefined ? {} : { reason: wake.reason }),
137
- };
138
- }
139
-
140
- /**
141
- * Whether a Run keeps its artifact: `--record` names a destination, or the Run
142
- * paused or stopped. Every other Run discards the in-flight artifact, so it
143
- * names no Checkpoint on `run_end` either — `run.ts` reads this same rule
144
- * (ADR-0054). A paused Run promises restorability, so it keeps its artifact
145
- * and can name its path.
146
- */
147
- export function keepsCheckpoint(options: {
148
- readonly record?: string;
149
- readonly outcome: RunOutcome;
150
- }): boolean {
151
- return (
152
- options.record !== undefined || options.outcome === "stopped" || options.outcome === "paused"
153
- );
154
- }
155
-
156
- /**
157
- * Creates the directory the Run's artifact goes into. A `--record` path names
158
- * where the artifact goes, so yaag creates the chain that path implies rather
159
- * than refusing. ADR-0021 makes `--record` fix the destination path only, and a
160
- * path yaag can make is a destination yaag makes. The checkpoint directory yaag owns stays
161
- * private; a user-named `--record` directory takes the process umask, because it
162
- * lives in the user's own tree.
163
- */
164
- export async function ensureCheckpointDirectory(
165
- record: string | undefined,
166
- destination: string,
167
- ): Promise<void> {
168
- const directory = dirname(destination);
169
- if (record === undefined) {
170
- await mkdir(directory, { recursive: true, mode: 0o700 });
171
- return;
172
- }
173
- await mkdir(directory, { recursive: true });
174
- }
175
-
176
- /**
177
- * Makes the directory chain of the `--record` path at Run start, and rejects the
178
- * Run before the first spawn when that chain cannot exist. It does not prove the
179
- * destination writable: an existing directory that refuses a write, or a name
180
- * already taken, still fails later, at publication.
181
- */
182
- export async function prepareRecordDestination(record: string): Promise<void> {
183
- try {
184
- await ensureCheckpointDirectory(record, record);
185
- } catch (error) {
186
- throw new YaagError(
187
- "RECORD_PATH_UNUSABLE",
188
- `cannot create the Cassette directory ${dirname(record)}: ${String(error)}`,
189
- );
190
- }
191
- }
192
-
193
- /** Which program a Run executes: a file on disk, or inline source text (ADR-0033). */
194
- export interface ProgramIdentity {
195
- readonly programFile?: string;
196
- /** Inline source, exactly as the caller gave it; it excludes any loader prelude. */
197
- readonly programSource?: string;
198
- }
199
-
200
- /** What one Run's invocation identity is made of: program, args, and Profile. */
201
- export interface RunIdentityRequest {
202
- readonly program: ProgramIdentity;
203
- readonly args: unknown;
204
- /** Active Profile id; part of invocation identity, resolved before this call (ADR-0052). */
205
- readonly profile?: string;
206
- }
207
-
208
- /**
209
- * Resolves what a resume re-executes: the program, its args, and the active
210
- * Profile. The program hash is advisory only.
211
- */
212
- export async function resolveRunIdentity(request: RunIdentityRequest): Promise<RunIdentity> {
213
- const { program, args, profile } = request;
214
- const profileKey = profile === undefined ? {} : { profile };
215
- // An Inline Program's file is a temporary path, and no artifact may name it,
216
- // so the inline arm drops `programFile` even when the caller supplies one.
217
- if (program.programSource !== undefined) {
218
- const programSource = program.programSource;
219
- return { programSource, args, programHash: sha256Hex(programSource), ...profileKey };
220
- }
221
- const programFile = program.programFile;
222
- // A Run with neither a program file nor inline source still has a Profile.
223
- if (programFile === undefined) return { ...profileKey };
224
- const programHash = await hashProgram(programFile);
225
- return {
226
- programFile,
227
- args,
228
- ...(programHash === null ? {} : { programHash }),
229
- ...profileKey,
230
- };
231
- }
232
-
233
- /**
234
- * Removes the in-progress artifact of a Run that publishes nothing. A missing
235
- * file is the normal case: the Run may never have reached an Ask boundary. Any
236
- * other failure is a diagnostic, because the file left behind states
237
- * `interrupted` and a reader trusts that word (ADR-0031).
238
- */
239
- async function discardCheckpoint(destination: string): Promise<void> {
240
- try {
241
- await unlink(destination);
242
- } catch (error) {
243
- if (!isMissingFile(error)) writeRecordingDiagnostic(error);
244
- }
245
- }
246
-
247
- function isMissingFile(error: unknown): boolean {
248
- return (
249
- typeof error === "object" &&
250
- error !== null &&
251
- "code" in error &&
252
- (error as { readonly code?: unknown }).code === "ENOENT"
253
- );
254
- }
255
-
256
- /** Advisory only: an unreadable program file omits the hash and never fails the Run. */
257
- async function hashProgram(programFile: string): Promise<string | null> {
258
- try {
259
- return sha256Hex(await Bun.file(programFile).arrayBuffer());
260
- } catch {
261
- return null;
262
- }
263
- }
264
-
265
- /** Reports a secondary Cassette publication failure without displacing the Run's primary error. */
266
- export function writeRecordingDiagnostic(error: unknown): void {
267
- try {
268
- process.stderr.write(`[yaag] ${String(error)}\n`);
269
- } catch {
270
- // stderr diagnostics are best-effort: a broken stderr must not mask the Run's error either.
271
- }
272
- }
@@ -1,169 +0,0 @@
1
- /**
2
- * The session copy the fork summarizer reads (ADR-0022).
3
- *
4
- * The parked Agent is incomplete, so it cannot be forked: yaag copies its pi
5
- * session file instead, and closes the pending `request_user_input` call with a
6
- * synthetic `toolResult`. pi refuses to continue a session whose last assistant
7
- * message has an unanswered tool call, and the copy keeps the parked Agent's
8
- * own file untouched.
9
- */
10
- import { copyFile, readFile, rm, writeFile } from "node:fs/promises";
11
- import { tmpdir } from "node:os";
12
- import { join } from "node:path";
13
-
14
- /**
15
- * What the summarizer session reads in place of the human's answer. It states
16
- * three facts: no answer arrived, this session is a copy, and the task is over.
17
- */
18
- export const SYNTHETIC_TOOL_RESULT_TEXT =
19
- "The human has not answered yet. This session is a copy of your session, made " +
20
- "only to summarize your question. Do not continue your task.";
21
-
22
- /** One prepared copy: where it is, and how to remove it again. */
23
- export interface SessionCopy {
24
- /** Absolute path of the copy; hand it to `pi --session`. */
25
- readonly path: string;
26
- /** Removes the copy. Best effort: it never throws. */
27
- remove(): Promise<void>;
28
- }
29
-
30
- /** What one copy needs: the source session and the call to close. */
31
- export interface SessionCopyRequest {
32
- readonly sessionFile: string;
33
- readonly toolCallId: string;
34
- /** Where the copy goes; the OS temp directory by default. */
35
- readonly directory?: string;
36
- }
37
-
38
- /**
39
- * Copies one pi session and appends the synthetic `toolResult`.
40
- *
41
- * Rejects when the source cannot be read, when its last
42
- * line is not a complete JSON entry, or when no entry carries the parked tool
43
- * call: a dangling result would corrupt the copy, and the summary is
44
- * best-effort, so a refusal here is the correct outcome.
45
- */
46
- export async function prepareSessionCopy(request: SessionCopyRequest): Promise<SessionCopy> {
47
- const text = await readSession(request.sessionFile);
48
- const entries = parseEntries(text, request.sessionFile);
49
- if (!carriesToolCall(entries, request.toolCallId)) {
50
- throw new Error(`session ${request.sessionFile} has no tool call ${request.toolCallId}`);
51
- }
52
- // The appended entry hangs below the current leaf. A leaf with no string id
53
- // would detach it from pi's session tree, which is the very corruption the
54
- // refusals above exist to prevent, so it refuses too.
55
- const leaf = entries.at(-1);
56
- if (typeof leaf?.id !== "string") {
57
- throw new Error(`session ${request.sessionFile} ends with an entry that has no id`);
58
- }
59
- const parentId: string = leaf.id;
60
- const path = join(
61
- request.directory ?? tmpdir(),
62
- `yaag-summary-${Date.now()}-${Math.random().toString(16).slice(2)}.jsonl`,
63
- );
64
- const copy: SessionCopy = {
65
- path,
66
- remove: async (): Promise<void> => {
67
- try {
68
- await rm(path, { force: true });
69
- } catch {
70
- // best effort: a leftover temp file must never fail a Run
71
- }
72
- },
73
- };
74
- try {
75
- await copyFile(request.sessionFile, path);
76
- const line = JSON.stringify(syntheticEntry({ toolCallId: request.toolCallId, parentId }));
77
- await writeFile(path, `${text.endsWith("\n") ? "" : "\n"}${line}\n`, { flag: "a" });
78
- } catch (error) {
79
- await copy.remove();
80
- throw new Error(`cannot prepare a session copy: ${String(error)}`);
81
- }
82
- return copy;
83
- }
84
-
85
- /** One parsed session entry; only the fields this module reads are named. */
86
- interface SessionEntry {
87
- readonly id?: unknown;
88
- readonly message?: unknown;
89
- }
90
-
91
- /** One assistant tool call, as pi writes it into a session entry. */
92
- interface ToolCallPart {
93
- readonly type?: unknown;
94
- readonly id?: unknown;
95
- }
96
-
97
- function isRecord(value: unknown): value is Record<string, unknown> {
98
- return typeof value === "object" && value !== null && !Array.isArray(value);
99
- }
100
-
101
- async function readSession(path: string): Promise<string> {
102
- try {
103
- return await readFile(path, "utf8");
104
- } catch (error) {
105
- throw new Error(`cannot read session ${path}: ${String(error)}`);
106
- }
107
- }
108
-
109
- /** Every non-empty line, parsed. A truncated tail line fails the whole copy. */
110
- function parseEntries(text: string, path: string): readonly SessionEntry[] {
111
- const lines = text.split("\n").filter((line) => line.trim().length > 0);
112
- return lines.map((line, index) => {
113
- let parsed: unknown;
114
- try {
115
- parsed = JSON.parse(line);
116
- } catch {
117
- throw new Error(`session ${path} line ${index + 1} is not valid JSON`);
118
- }
119
- // Checked, never cast blind: a JSONL line is untrusted input, and a scalar
120
- // or an array here would read as an entry with no id and no message.
121
- if (!isRecord(parsed)) {
122
- throw new Error(`session ${path} line ${index + 1} is not a session entry`);
123
- }
124
- return parsed;
125
- });
126
- }
127
-
128
- /**
129
- * True when an entry holds the parked call as a real `toolCall` content part.
130
- *
131
- * Structural, never a substring scan of the serialized entry: the same id can
132
- * appear inside message text, and this predicate carries the whole safety
133
- * argument of the module — a false positive appends a dangling result.
134
- */
135
- function carriesToolCall(entries: readonly SessionEntry[], toolCallId: string): boolean {
136
- return entries.some((entry) => {
137
- const message = entry.message;
138
- if (!isRecord(message)) return false;
139
- const content = message.content;
140
- if (!Array.isArray(content)) return false;
141
- return content.some((part: ToolCallPart) => part.type === "toolCall" && part.id === toolCallId);
142
- });
143
- }
144
-
145
- function syntheticEntry(options: {
146
- readonly toolCallId: string;
147
- readonly parentId?: string;
148
- }): unknown {
149
- const now = new Date();
150
- return {
151
- type: "message",
152
- id: randomEntryId(),
153
- ...(options.parentId === undefined ? {} : { parentId: options.parentId }),
154
- timestamp: now.toISOString(),
155
- message: {
156
- role: "toolResult",
157
- toolCallId: options.toolCallId,
158
- toolName: "request_user_input",
159
- content: [{ type: "text", text: SYNTHETIC_TOOL_RESULT_TEXT }],
160
- isError: false,
161
- timestamp: now.getTime(),
162
- },
163
- };
164
- }
165
-
166
- /** pi's entry ids are 8 hex characters. */
167
- function randomEntryId(): string {
168
- return Math.random().toString(16).slice(2, 10).padEnd(8, "0");
169
- }