@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,8 +1,5 @@
1
- import {
2
- isReportResultCommandFrame,
3
- RESUME_NUDGE,
4
- readQuestionFrame,
5
- } from "../ask-contract/index.ts";
1
+ import { isReportResultCommandFrame, RESUME_NUDGE } from "../ask-contract/index.ts";
2
+ import { YaagError } from "../errors.ts";
6
3
  import type {
7
4
  AgentStats,
8
5
  AgentTransport,
@@ -21,12 +18,9 @@ import type {
21
18
  import { FrameQueue } from "../transport/index.ts";
22
19
  import type { Cassette, CassetteAgent, CassetteAsk } from "./cassette.ts";
23
20
  import { CassetteReplay } from "./cassette-replay.ts";
24
- import {
25
- recordedSpawnSelection,
26
- replayMismatch,
27
- spawnMatchesExceptModel,
28
- } from "./replay-divergence.ts";
21
+ import { recordedSpawnSelection, replayMismatch } from "./replay-divergence.ts";
29
22
  import { checkResumePreconditions } from "./resume-preconditions.ts";
23
+ import { matchesExceptModel } from "./spawn-identity.ts";
30
24
 
31
25
  /**
32
26
  * What a resume knows about the human's answers (ADR-0023). A recorded Ask
@@ -57,7 +51,24 @@ export function resumeTransport(
57
51
  ): Promise<AgentTransport> {
58
52
  const agent = cassette.agents[spawnCursor++] ?? null;
59
53
  const mismatch = replayMismatch.spawn(agent, options);
60
- if (mismatch) return live.open(options, observeStartup);
54
+ if (mismatch) {
55
+ // A diverged Host Fork with no copy path cannot go live: the argv
56
+ // builder emits `--fork` only when a `forkSession` exists
57
+ // (`transport/pi-state.ts`), so pi would silently start a fresh
58
+ // conversation instead of forking the human's one. ADR-0068 decision 2
59
+ // states the rule: the spawn side refuses rather than forks. The
60
+ // copy-less source is the Cassette-rebuilt one, and also the
61
+ // `--resume --host-session` one, which has no tool call id and so
62
+ // makes no copy.
63
+ if (options.origin === "host-fork" && options.forkSession === undefined) {
64
+ throw new YaagError(
65
+ "RESUME_REFUSED",
66
+ `resume refused for agent "${options.name}": the recorded host fork diverged and this Run holds no host session copy to fork from`,
67
+ options.name,
68
+ );
69
+ }
70
+ return live.open(options, observeStartup);
71
+ }
61
72
  await checkResumePreconditions(agent);
62
73
  const worktree = worktreeResolution(agent);
63
74
  observeStartup?.({
@@ -71,7 +82,7 @@ export function resumeTransport(
71
82
  // recorded selection is offered only when every other field matches.
72
83
  recordedSpawn(options: OpenOptions): RecordedSpawnSelection | undefined {
73
84
  const agent = cassette.agents[spawnCursor] ?? null;
74
- if (agent === null || !spawnMatchesExceptModel(agent.spawn, options)) return undefined;
85
+ if (agent === null || !matchesExceptModel(agent.spawn, options)) return undefined;
75
86
  return recordedSpawnSelection(agent);
76
87
  },
77
88
  };
@@ -184,23 +195,18 @@ class ResumeTransport implements AgentTransport {
184
195
  * The recorded Ask has no settlement, so it can never replay. With an answer
185
196
  * it is restored: the answer goes into the session, pi respawns on it, and
186
197
  * the nudge replaces the Ask prompt the Agent already saw. Without an answer
187
- * the playback re-opens the same Question, and the Run pauses again.
198
+ * the playback names the parked call and its Question id, the Ask parks on
199
+ * the Question the run block holds, and the Run pauses again (ADR-0022).
188
200
  */
189
201
  #restore(ask: CassetteAsk | undefined): AskPlayback | undefined | null {
190
202
  const incomplete = ask?.incomplete;
191
203
  if (ask === undefined || incomplete === undefined) return null;
192
204
  const answer = this.#restoration?.answerFor(incomplete.questionId);
193
205
  if (answer === undefined) {
194
- const call = recordedQuestion(ask, incomplete.toolCallId);
195
206
  this.#askCursor += 1;
196
207
  return {
197
208
  settles: false,
198
- parked: {
199
- toolCallId: incomplete.toolCallId,
200
- questionId: incomplete.questionId,
201
- question: call?.question ?? "",
202
- ...(call?.context === undefined ? {} : { context: call.context }),
203
- },
209
+ parked: { toolCallId: incomplete.toolCallId, questionId: incomplete.questionId },
204
210
  };
205
211
  }
206
212
  // The answer is already in the session: `restoreSessionAnswers` wrote it
@@ -291,18 +297,6 @@ function recordedPrompt(ask: CassetteAsk): string | null {
291
297
  return null;
292
298
  }
293
299
 
294
- /** The parked call of a recorded Ask, read back from its frames. */
295
- function recordedQuestion(
296
- ask: CassetteAsk,
297
- toolCallId: string,
298
- ): { readonly question: string; readonly context?: string } | undefined {
299
- for (const frame of ask.receivedFrames) {
300
- const call = readQuestionFrame(frame);
301
- if (call !== null && call.toolCallId === toolCallId) return call;
302
- }
303
- return undefined;
304
- }
305
-
306
300
  function continuationOptions(agent: CassetteAgent, original: OpenOptions): OpenOptions {
307
301
  const { worktree: _worktree, ...spawn } = agent.spawn;
308
302
  const worktree = worktreeResolution(agent);
@@ -0,0 +1,109 @@
1
+ import { mkdir } from "node:fs/promises";
2
+ import { dirname } from "node:path";
3
+ import { YaagError } from "../errors.ts";
4
+ import type { CassetteRun } from "./cassette.ts";
5
+ import { sha256Hex } from "./program-hash.ts";
6
+
7
+ /**
8
+ * What a resume is about to re-execute; resolved once, at Run start.
9
+ *
10
+ * The run-level `host` is part of this identity, but it is not resolved here:
11
+ * the Host Source is prepared after the identity (see the order in `run.ts`),
12
+ * so the Checkpoint receives it separately through `identifyHost` (ADR-0068).
13
+ */
14
+ export type RunIdentity = Omit<CassetteRun, "outcome" | "questions" | "answers" | "reason">;
15
+
16
+ /**
17
+ * Creates the directory the Run's artifact goes into. A `--record` path names
18
+ * where the artifact goes, so yaag creates the chain that path implies rather
19
+ * than refusing. ADR-0021 makes `--record` fix the destination path only, and a
20
+ * path yaag can make is a destination yaag makes. The checkpoint directory yaag owns stays
21
+ * private; a user-named `--record` directory takes the process umask, because it
22
+ * lives in the user's own tree.
23
+ */
24
+ export async function ensureCheckpointDirectory(
25
+ record: string | undefined,
26
+ destination: string,
27
+ ): Promise<void> {
28
+ const directory = dirname(destination);
29
+ if (record === undefined) {
30
+ await mkdir(directory, { recursive: true, mode: 0o700 });
31
+ return;
32
+ }
33
+ await mkdir(directory, { recursive: true });
34
+ }
35
+
36
+ /**
37
+ * Makes the directory chain of the `--record` path at Run start, and rejects the
38
+ * Run before the first spawn when that chain cannot exist. It does not prove the
39
+ * destination writable: an existing directory that refuses a write, or a name
40
+ * already taken, still fails later, at publication.
41
+ */
42
+ export async function prepareRecordDestination(record: string): Promise<void> {
43
+ try {
44
+ await ensureCheckpointDirectory(record, record);
45
+ } catch (error) {
46
+ throw new YaagError(
47
+ "RECORD_PATH_UNUSABLE",
48
+ `cannot create the Cassette directory ${dirname(record)}: ${String(error)}`,
49
+ );
50
+ }
51
+ }
52
+
53
+ /** Which program a Run executes: a file on disk, or inline source text (ADR-0033). */
54
+ export interface ProgramIdentity {
55
+ readonly programFile?: string;
56
+ /** Inline source, exactly as the caller gave it; it excludes any loader prelude. */
57
+ readonly programSource?: string;
58
+ }
59
+
60
+ /** What one Run's invocation identity is made of: program, args, and Profile. */
61
+ export interface RunIdentityRequest {
62
+ readonly program: ProgramIdentity;
63
+ readonly args: unknown;
64
+ /** Active Profile id; part of invocation identity, resolved before this call (ADR-0052). */
65
+ readonly profile?: string;
66
+ }
67
+
68
+ /**
69
+ * Resolves what a resume re-executes: the program, its args, and the active
70
+ * Profile. The program hash is advisory only.
71
+ */
72
+ export async function resolveRunIdentity(request: RunIdentityRequest): Promise<RunIdentity> {
73
+ const { program, args, profile } = request;
74
+ const profileKey = profile === undefined ? {} : { profile };
75
+ // An Inline Program's file is a temporary path, and no artifact may name it,
76
+ // so the inline arm drops `programFile` even when the caller supplies one.
77
+ if (program.programSource !== undefined) {
78
+ const programSource = program.programSource;
79
+ return { programSource, args, programHash: sha256Hex(programSource), ...profileKey };
80
+ }
81
+ const programFile = program.programFile;
82
+ // A Run with neither a program file nor inline source still has a Profile.
83
+ if (programFile === undefined) return { ...profileKey };
84
+ const programHash = await hashProgram(programFile);
85
+ return {
86
+ programFile,
87
+ args,
88
+ ...(programHash === null ? {} : { programHash }),
89
+ ...profileKey,
90
+ };
91
+ }
92
+
93
+ /** Advisory only: an unreadable program file omits the hash and never fails the Run. */
94
+ async function hashProgram(programFile: string): Promise<string | null> {
95
+ try {
96
+ return sha256Hex(await Bun.file(programFile).arrayBuffer());
97
+ } catch {
98
+ return null;
99
+ }
100
+ }
101
+
102
+ /** Reports a secondary Cassette publication failure without displacing the Run's primary error. */
103
+ export function writeRecordingDiagnostic(error: unknown): void {
104
+ try {
105
+ process.stderr.write(`[yaag] ${String(error)}\n`);
106
+ } catch {
107
+ // stderr diagnostics are best-effort: a broken stderr must not mask the Run's error either.
108
+ }
109
+ }
@@ -5,14 +5,14 @@
5
5
  * The answer goes back into the session as the tool result of that call, so the
6
6
  * respawned Agent reads it as the result of its own request.
7
7
  *
8
- * The file is JSONL, one entry per line, pi session version 3. Parsing is
9
- * lenient on purpose: an unknown entry type, or one line yaag cannot parse, is
10
- * not this module's business, and must not fail a restoration.
8
+ * The write itself belongs to the pi session editor. This module owns the loop
9
+ * over the Cassette's incomplete marks, and the map from the editor's refusals
10
+ * to `RESUME_REFUSED`.
11
11
  */
12
- import { appendFile } from "node:fs/promises";
13
- import { REQUEST_USER_INPUT_TOOL_NAME } from "../ask-contract/index.ts";
14
12
  import { YaagError } from "../errors.ts";
13
+ import { appendToolResult, isPiSessionError } from "../pi-session/index.ts";
15
14
  import type { Cassette } from "./cassette.ts";
15
+ import { parkedAsks } from "./parked-asks.ts";
16
16
 
17
17
  /** One correlated answer, and the session file it belongs to. */
18
18
  export interface SessionAnswerAppend {
@@ -22,15 +22,6 @@ export interface SessionAnswerAppend {
22
22
  readonly answer: string;
23
23
  }
24
24
 
25
- interface SessionEntry {
26
- readonly id?: unknown;
27
- readonly message?: {
28
- readonly role?: unknown;
29
- readonly toolCallId?: unknown;
30
- readonly content?: unknown;
31
- };
32
- }
33
-
34
25
  /**
35
26
  * Appends the answer as the tool result of the parked call.
36
27
  *
@@ -40,26 +31,15 @@ interface SessionEntry {
40
31
  * the session is not the one the Cassette recorded.
41
32
  */
42
33
  export async function appendSessionAnswer(request: SessionAnswerAppend): Promise<void> {
43
- const entries = await readEntries(request.sessionFile);
44
- const call = entries.find((entry) => holdsToolCall(entry, request.toolCallId));
45
- if (call === undefined) {
46
- throw new YaagError(
47
- "RESUME_REFUSED",
48
- `the session file ${request.sessionFile} holds no tool call "${request.toolCallId}" — ` +
49
- `it is not the session this checkpoint recorded`,
50
- );
51
- }
52
- const present = entries.find((entry) => isToolResult(entry, request.toolCallId));
53
- if (present !== undefined) {
54
- const text = resultText(present);
55
- if (text === request.answer) return;
56
- throw new YaagError(
57
- "RESUME_REFUSED",
58
- `the tool call "${request.toolCallId}" is already answered with "${String(text)}" — ` +
59
- `it cannot be answered with "${request.answer}" as well`,
60
- );
34
+ try {
35
+ await appendToolResult({
36
+ sessionFile: request.sessionFile,
37
+ toolCallId: request.toolCallId,
38
+ text: request.answer,
39
+ });
40
+ } catch (error) {
41
+ throw refusal(error, request);
61
42
  }
62
- await appendFile(request.sessionFile, `${JSON.stringify(resultEntry(request, call))}\n`);
63
43
  }
64
44
 
65
45
  /**
@@ -73,91 +53,48 @@ export async function restoreSessionAnswers(
73
53
  cassette: Cassette,
74
54
  answerFor: (questionId: string) => string | undefined,
75
55
  ): Promise<void> {
76
- for (const agent of cassette.agents) {
77
- const sessionFile = agent.sessionFile;
56
+ for (const mark of parkedAsks(cassette)) {
57
+ const sessionFile = mark.sessionFile;
78
58
  if (sessionFile === undefined) continue;
79
- for (const ask of agent.asks) {
80
- const incomplete = ask.incomplete;
81
- if (incomplete === undefined) continue;
82
- const answer = answerFor(incomplete.questionId);
83
- if (answer === undefined) continue;
84
- await appendSessionAnswer({ sessionFile, toolCallId: incomplete.toolCallId, answer });
85
- }
59
+ const answer = answerFor(mark.questionId);
60
+ if (answer === undefined) continue;
61
+ await appendSessionAnswer({ sessionFile, toolCallId: mark.toolCallId, answer });
86
62
  }
87
63
  }
88
64
 
89
- /** The entry one answer becomes: a `toolResult` message correlated by tool call id. */
90
- function resultEntry(request: SessionAnswerAppend, call: SessionEntry): unknown {
91
- const now = Date.now();
92
- return {
93
- type: "message",
94
- id: entryId(),
95
- parentId: typeof call.id === "string" ? call.id : null,
96
- timestamp: new Date(now).toISOString(),
97
- message: {
98
- role: "toolResult",
99
- toolCallId: request.toolCallId,
100
- toolName: REQUEST_USER_INPUT_TOOL_NAME,
101
- content: [{ type: "text", text: request.answer }],
102
- isError: false,
103
- timestamp: now,
104
- },
105
- };
106
- }
107
-
108
- /** Eight hex digits, pi's own entry id shape; the file never addresses this one. */
109
- function entryId(): string {
110
- return Math.floor(Math.random() * 0x1_0000_0000)
111
- .toString(16)
112
- .padStart(8, "0");
113
- }
114
-
115
- /** Reads the session, and drops every line yaag cannot parse. */
116
- async function readEntries(sessionFile: string): Promise<readonly SessionEntry[]> {
117
- let text: string;
118
- try {
119
- text = await Bun.file(sessionFile).text();
120
- } catch (error) {
121
- throw new YaagError(
122
- "RESUME_REFUSED",
123
- `cannot read the session file ${sessionFile}: ${String(error)}`,
124
- );
125
- }
126
- const entries: SessionEntry[] = [];
127
- for (const line of text.split("\n")) {
128
- if (line.trim() === "") continue;
129
- try {
130
- const parsed: unknown = JSON.parse(line);
131
- if (typeof parsed === "object" && parsed !== null) entries.push(parsed as SessionEntry);
132
- } catch {
133
- // One malformed line is not a malformed session: pi may have died mid-write.
65
+ /**
66
+ * Maps one editor refusal to the resume's own error, with the resume's words.
67
+ *
68
+ * Anything that is not a `PiSessionError` is handed back untouched, so the type
69
+ * is the widest one: only the caller's `throw` gives it a meaning.
70
+ */
71
+ function refusal(error: unknown, request: SessionAnswerAppend): unknown {
72
+ if (!isPiSessionError(error)) return error;
73
+ switch (error.reason) {
74
+ case "no-such-call":
75
+ return new YaagError(
76
+ "RESUME_REFUSED",
77
+ `the session file ${request.sessionFile} holds no tool call "${request.toolCallId}" — ` +
78
+ `it is not the session this checkpoint recorded`,
79
+ );
80
+ case "different-result":
81
+ return new YaagError(
82
+ "RESUME_REFUSED",
83
+ `the tool call "${request.toolCallId}" is already answered with ` +
84
+ `"${String(error.existing)}" — ` +
85
+ `it cannot be answered with "${request.answer}" as well`,
86
+ );
87
+ case "unreadable":
88
+ return new YaagError(
89
+ "RESUME_REFUSED",
90
+ `cannot read the session file ${request.sessionFile}: ${error.message}`,
91
+ );
92
+ case "bad-line":
93
+ return new YaagError("RESUME_REFUSED", error.message);
94
+ default: {
95
+ // A new refusal reason must be mapped here, not thrown without a message.
96
+ const never: never = error.reason;
97
+ return new YaagError("RESUME_REFUSED", `cannot restore the answer: ${String(never)}`);
134
98
  }
135
99
  }
136
- return entries;
137
- }
138
-
139
- function holdsToolCall(entry: SessionEntry, toolCallId: string): boolean {
140
- if (entry.message?.role !== "assistant") return false;
141
- return contentParts(entry).some((part) => part.type === "toolCall" && part.id === toolCallId);
142
- }
143
-
144
- function isToolResult(entry: SessionEntry, toolCallId: string): boolean {
145
- return entry.message?.role === "toolResult" && entry.message.toolCallId === toolCallId;
146
- }
147
-
148
- function resultText(entry: SessionEntry): string | undefined {
149
- const part = contentParts(entry).find((candidate) => candidate.type === "text");
150
- return typeof part?.text === "string" ? part.text : undefined;
151
- }
152
-
153
- interface ContentPart {
154
- readonly type?: unknown;
155
- readonly id?: unknown;
156
- readonly text?: unknown;
157
- }
158
-
159
- function contentParts(entry: SessionEntry): readonly ContentPart[] {
160
- const content = entry.message?.content;
161
- if (!Array.isArray(content)) return [];
162
- return content.filter((part): part is ContentPart => typeof part === "object" && part !== null);
163
100
  }