@yaag/runtime 0.25.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 (79) hide show
  1. package/package.json +2 -3
  2. package/src/agent/agent.ts +75 -23
  3. package/src/agent/ask-user-capability.ts +36 -0
  4. package/src/agent/fork.ts +40 -12
  5. package/src/agent/host-fork.ts +85 -0
  6. package/src/agent/index.ts +2 -1
  7. package/src/agent/spawn-definition-request.ts +38 -3
  8. package/src/agent/spawn-open.ts +59 -100
  9. package/src/agent/spawn-plan.ts +114 -0
  10. package/src/agent/spawn-request.ts +34 -3
  11. package/src/agent/spawn.ts +41 -5
  12. package/src/ask/ask-exchange-options.ts +8 -6
  13. package/src/ask/ask-exchange.ts +102 -97
  14. package/src/ask/ask-guard.ts +207 -0
  15. package/src/ask/ask-settlement.ts +8 -0
  16. package/src/ask/ask-timing.ts +12 -0
  17. package/src/ask/idle-watch.ts +12 -2
  18. package/src/ask/index.ts +1 -0
  19. package/src/ask/stall-watchdog.ts +13 -3
  20. package/src/ask-contract/ask-limit.ts +24 -6
  21. package/src/ask-contract/index.ts +8 -0
  22. package/src/ask-contract/request-user-input-extension.ts +105 -0
  23. package/src/ask-contract/request-user-input.ts +58 -0
  24. package/src/cassette/cassette-loader.ts +56 -18
  25. package/src/cassette/cassette-schema.ts +37 -1
  26. package/src/cassette/cassette.ts +58 -32
  27. package/src/cassette/checkpoint.ts +306 -0
  28. package/src/cassette/index.ts +25 -7
  29. package/src/cassette/parked-asks.ts +38 -0
  30. package/src/cassette/replay-divergence.ts +7 -97
  31. package/src/cassette/resume-identity.ts +5 -1
  32. package/src/cassette/resume-preconditions.ts +24 -0
  33. package/src/cassette/resume-transport.ts +112 -13
  34. package/src/cassette/run-identity.ts +109 -0
  35. package/src/cassette/session-answer.ts +100 -0
  36. package/src/cassette/spawn-identity.ts +318 -0
  37. package/src/catalog/registry-reader.ts +1 -1
  38. package/src/config/config-schema.ts +33 -0
  39. package/src/config/effective-config.ts +53 -0
  40. package/src/config/index.ts +4 -0
  41. package/src/contract/agent-policy.ts +9 -0
  42. package/src/contract/error-codes.ts +3 -2
  43. package/src/contract/index.ts +1 -0
  44. package/src/contract/spawn-options.ts +33 -2
  45. package/src/control/index.ts +2 -0
  46. package/src/control/pause-drain.ts +81 -24
  47. package/src/error-factories.ts +8 -0
  48. package/src/events.ts +10 -2
  49. package/src/index.ts +15 -1
  50. package/src/model/index.ts +1 -1
  51. package/src/pi-session/append-tool-result.ts +165 -0
  52. package/src/pi-session/index.ts +30 -0
  53. package/src/pi-session/pi-session-error.ts +34 -0
  54. package/src/pi-session/session-copy.ts +113 -0
  55. package/src/pi-session/session-entries.ts +130 -0
  56. package/src/public-api.ts +1 -0
  57. package/src/question-summary/index.ts +18 -0
  58. package/src/question-summary/summarize-question.ts +129 -0
  59. package/src/question-summary/summary-policy.ts +28 -0
  60. package/src/run/agent-questions.ts +157 -0
  61. package/src/run/answers.ts +91 -0
  62. package/src/run/host-session.ts +233 -0
  63. package/src/run/index.ts +12 -0
  64. package/src/run/pause-questions.ts +98 -0
  65. package/src/run/pause-signal.ts +32 -0
  66. package/src/run/question-id.ts +18 -0
  67. package/src/run/questions.ts +31 -0
  68. package/src/run/run-context.ts +21 -0
  69. package/src/run/run-result.ts +21 -0
  70. package/src/run/run-settlement.ts +36 -4
  71. package/src/run/run.ts +248 -139
  72. package/src/system-prompt/agent-system-prompt.ts +1 -1
  73. package/src/transport/live-transport.ts +19 -0
  74. package/src/transport/pi-state.ts +31 -5
  75. package/src/transport/tool-probe.ts +4 -0
  76. package/src/transport/transport.ts +31 -1
  77. package/src/types.ts +1 -0
  78. package/src/cassette/checkpoint-flush.ts +0 -101
  79. package/src/cassette/run-checkpoint.ts +0 -223
package/src/run/run.ts CHANGED
@@ -10,29 +10,32 @@ import {
10
10
  type CassetteSink,
11
11
  checkpointFileName,
12
12
  cleanStaleCheckpointTemp,
13
- createCheckpointFlusher,
14
- flushingSink,
15
- interruptedResumeWarning,
16
- keepsCheckpoint,
13
+ createCheckpoint,
17
14
  loadCassette,
18
15
  type ProgramIdentity,
16
+ parkedAsks,
19
17
  prepareRecordDestination,
20
18
  profileIdentityWarning,
21
19
  programIdentityWarning,
22
- publishRunCheckpoint,
23
- type RunCheckpointResult,
20
+ readableCassette,
24
21
  recordingTransport,
25
22
  replayTransport,
26
23
  resolveCheckpointDirectory,
27
24
  resolveRunIdentity,
25
+ restoreSessionAnswers,
28
26
  resumeTransport,
29
27
  writeRecordingDiagnostic,
30
28
  } from "../cassette/index.ts";
31
- import { type EffectiveConfig, EMPTY_EFFECTIVE_CONFIG } from "../config/index.ts";
29
+ import {
30
+ type EffectiveConfig,
31
+ EMPTY_EFFECTIVE_CONFIG,
32
+ questionSummaryOf,
33
+ } from "../config/index.ts";
32
34
  import { controlRequests, createAskAdmission, type RunController } from "../control/index.ts";
33
35
  import { YaagError } from "../errors.ts";
34
36
  import type { EventSink, LifecycleEvent, RunOutcome, StampedEventSink } from "../events.ts";
35
37
  import { selectProfile } from "../profile/index.ts";
38
+ import { summarizeQuestions } from "../question-summary/index.ts";
36
39
  import { applyEvent, initialSummary, type RunSummary } from "../summary/index.ts";
37
40
  import type { TransportFactory } from "../transport/index.ts";
38
41
  import {
@@ -42,9 +45,14 @@ import {
42
45
  skillRestrictionTransport,
43
46
  worktreeTransport,
44
47
  } from "../transport/index.ts";
48
+ import { createAgentQuestions, seedFromResume } from "./agent-questions.ts";
49
+ import { type AnswerLedger, createAnswerLedger, emptyAnswerLedger } from "./answers.ts";
45
50
  import { validateArgs } from "./args-validation.ts";
46
51
  import { type OrchestrationProgram, programDefinition } from "./define-run.ts";
52
+ import { adoptedHostSource, type HostSessionOptions, prepareHostSource } from "./host-session.ts";
53
+ import { createPauseRequests } from "./pause-questions.ts";
47
54
  import type { RunContext } from "./run-context.ts";
55
+ import type { RunResult } from "./run-result.ts";
48
56
  import { type RunSettlement, settleRun } from "./run-settlement.ts";
49
57
 
50
58
  export interface RunOptions {
@@ -73,6 +81,12 @@ export interface RunOptions {
73
81
  readonly replay?: string;
74
82
  /** Replay a matching Cassette prefix, then continue live from its session. */
75
83
  readonly resume?: string;
84
+ /**
85
+ * The human's answers of one resume, keyed by Question id (ADR-0022). Every
86
+ * answer resolves one recorded Question; an unmatched Question stays open and
87
+ * the Run pauses again.
88
+ */
89
+ readonly answers?: Readonly<Record<string, string>>;
76
90
  /** Ends the Run early; every Agent is still reaped and costed. */
77
91
  readonly signal?: AbortSignal;
78
92
  /**
@@ -83,6 +97,14 @@ export interface RunOptions {
83
97
  readonly control?: RunController;
84
98
  /** Overrides the default checkpoint directory a stopped Run publishes into (ADR-0021). */
85
99
  readonly checkpointDir?: string;
100
+ /**
101
+ * The Host Session this Run was started from (ADR-0068). The runtime hashes
102
+ * the file, copies it once, and offers the copy as `ctx.host`.
103
+ *
104
+ * `toolCallId` is optional: a live Run requires it, because it must close
105
+ * that call in the copy; a --replay or --resume only hashes and compares.
106
+ */
107
+ readonly host?: HostSessionOptions;
86
108
  /**
87
109
  * Effective Config for this Run, read once by the launcher (ADR-0040). The
88
110
  * Run never loads it itself: omission runs config-free, so no Run picks up a
@@ -98,22 +120,28 @@ export interface RunOptions {
98
120
  }
99
121
 
100
122
  /**
101
- * Executes one Orchestration Program and resolves with its return value.
123
+ * Executes one Orchestration Program and resolves with its outcome: the
124
+ * program's value, or a paused Run with its questions and its Checkpoint
125
+ * (ADR-0022).
102
126
  *
103
127
  * Every Agent is dead by the time this settles — on success, on failure, and on
104
- * abort (ADR-0002) — and every Agent's cost has been emitted. Rejects with
105
- * ARGS_INVALID before emitting an event when declared argument schema validation fails.
128
+ * abort (ADR-0002) — and every Agent's cost has been emitted. A failed Run and
129
+ * a stopped Run reject with a `YaagError`. Rejects with ARGS_INVALID before
130
+ * emitting an event when declared argument schema validation fails.
106
131
  */
107
132
  export async function executeRun<Args, Result>(
108
133
  program: OrchestrationProgram<Args, Result>,
109
134
  options: RunOptions = {},
110
- ): Promise<Result> {
135
+ ): Promise<RunResult<Result>> {
111
136
  if (options.record !== undefined && options.replay !== undefined) {
112
137
  throw new YaagError("OPTIONS_CONFLICT", "cannot use record and replay together");
113
138
  }
114
139
  if (options.resume !== undefined && options.replay !== undefined) {
115
140
  throw new YaagError("OPTIONS_CONFLICT", "cannot use resume and replay together");
116
141
  }
142
+ if (options.answers !== undefined && options.resume === undefined) {
143
+ throw new YaagError("OPTIONS_CONFLICT", "cannot use answers without resume");
144
+ }
117
145
  const checkpointDir = options.checkpointDir ?? resolveCheckpointDirectory();
118
146
  try {
119
147
  // Best-effort, and emits no event, so the ARGS_INVALID "no events before
@@ -163,98 +191,202 @@ export async function executeRun<Args, Result>(
163
191
  args,
164
192
  ...(profile === undefined ? {} : { profile: profile.id }),
165
193
  });
166
- const checkpoint = { collector, record: options.record, destination, identity };
194
+ // The Checkpoint owns the whole publish policy: when the artifact flushes,
195
+ // what each outcome keeps, and what run_end may name (ADR-0021/0031/0054).
196
+ // Building it does no I/O, so the ARGS_INVALID "no events before rejection"
197
+ // rule still holds.
198
+ const checkpoint = createCheckpoint({
199
+ collector,
200
+ record: options.record,
201
+ destination,
202
+ identity,
203
+ });
167
204
  try {
168
205
  assertArgs<Args>(definition.args, args);
169
206
  } catch (error) {
170
207
  // The result is discarded on purpose: this rejection precedes run_start, and
171
208
  // no event may precede an ARGS_INVALID rejection, so a lost Checkpoint here
172
209
  // stays a stderr diagnostic (ticket 04).
173
- await publishRunCheckpoint({ outcome: "failed", ...checkpoint });
210
+ await checkpoint.settle("failed");
174
211
  throw error;
175
212
  }
176
213
  // The directory of the --record path is made before any Agent starts, so a Run
177
214
  // whose Cassette can never land does not do its work first and fail last.
178
215
  if (options.record !== undefined) await prepareRecordDestination(options.record);
216
+ // Before the first emit, so a HOST_SESSION_UNUSABLE refusal precedes every
217
+ // Lifecycle Event, exactly like RECORD_PATH_UNUSABLE. A strict replay makes no
218
+ // copy — no live child can consume it — and it needs no tool call id, while a
219
+ // live Run does (ADR-0068).
220
+ const recordedHost = replay?.run.host ?? resume?.run.host;
221
+ const host =
222
+ options.host !== undefined
223
+ ? await prepareHostSource({
224
+ host: options.host,
225
+ live: options.replay === undefined && options.resume === undefined,
226
+ copies: options.replay === undefined,
227
+ })
228
+ : recordedHost === undefined
229
+ ? undefined
230
+ : // A replay never spawns pi and a resume re-opens each Host Fork from
231
+ // its recorded session file, so the adopted source needs no copy path.
232
+ {
233
+ source: adoptedHostSource(recordedHost.hostHash),
234
+ remove: async (): Promise<void> => {},
235
+ };
236
+ if (host !== undefined) checkpoint.identifyHost({ hostHash: host.source.hostHash });
179
237
 
180
- let summary: RunSummary = initialSummary();
181
- const sink: StampedEventSink = options.events ?? (() => {});
182
- // Every event the Run emits also feeds the fold, so its own final accounting
183
- // is derived exactly the way an outside observer would derive it. `at` is
184
- // stamped here, once, so no individual emitter touches the wall clock.
185
- const emit: EventSink = (body) => {
186
- const event: LifecycleEvent = { ...body, at: Date.now() };
187
- summary = applyEvent(summary, event);
188
- sink(event);
189
- };
190
- const flusher = createCheckpointFlusher(checkpoint);
191
- const factory = selectFactory({
192
- options,
193
- collector: flushingSink(collector, flusher),
194
- replay,
195
- resume,
196
- });
197
- const agents: Agent[] = [];
198
- const startedAt = Date.now();
199
- const askAdmission = createAskAdmission();
200
- const spawnGate = makeSpawn({
201
- factory,
202
- agents,
203
- emit,
204
- askAdmission,
205
- sessionDir: options.sessionDir,
206
- programFile: options.programFile,
207
- // The same value `run_start.program` carries, so an Agent's prompt names
208
- // the Run the reader sees in the Run record.
209
- runName: definition.name ?? "program",
210
- configExtensions: options.config?.extensions ?? EMPTY_EFFECTIVE_CONFIG.extensions,
211
- ...(profile === undefined ? {} : { profile }),
212
- });
238
+ // Everything below can throw with the copy already on disk — a refused
239
+ // resume, a failed session restore, a failed spawn gate — so the removal
240
+ // guards from here. Every exit path removes it; a killed process leaks it,
241
+ // and that is a stated limit (ADR-0068).
242
+ try {
243
+ let summary: RunSummary = initialSummary();
244
+ const sink: StampedEventSink = options.events ?? (() => {});
245
+ // Every event the Run emits also feeds the fold, so its own final accounting
246
+ // is derived exactly the way an outside observer would derive it. `at` is
247
+ // stamped here, once, so no individual emitter touches the wall clock.
248
+ const emit: EventSink = (body) => {
249
+ const event: LifecycleEvent = { ...body, at: Date.now() };
250
+ summary = applyEvent(summary, event);
251
+ sink(event);
252
+ };
253
+ // Built before the first Agent starts, so every refusal of the answer
254
+ // contract precedes the Run's work (ADR-0022).
255
+ const parked = resume === null ? [] : parkedAsks(resume);
256
+ const answers: AnswerLedger =
257
+ resume === null
258
+ ? emptyAnswerLedger()
259
+ : createAnswerLedger({
260
+ supplied: options.answers ?? {},
261
+ questions: resume.run.questions ?? [],
262
+ inherited: resume.run.answers ?? [],
263
+ parked,
264
+ });
265
+ // Every answered park is restored into its session before the first Agent
266
+ // starts, so a conflicting answer refuses the resume before any work (ADR-0023).
267
+ if (resume !== null) await restoreSessionAnswers(resume, (id) => answers.take(id));
268
+ const factory = selectFactory({
269
+ options,
270
+ collector: checkpoint.sink,
271
+ replay,
272
+ resume,
273
+ answers,
274
+ });
275
+ const agents: Agent[] = [];
276
+ const startedAt = Date.now();
277
+ const askAdmission = createAskAdmission();
278
+ const agentQuestions = createAgentQuestions();
279
+ // The open Questions of the Checkpoint are the Questions of this resume: a
280
+ // re-opened Question keeps its id, text, context and summary (ADR-0022/0023).
281
+ if (resume !== null) {
282
+ seedFromResume({ questions: agentQuestions, open: answers.open(), parked });
283
+ }
284
+ const spawnGate = makeSpawn({
285
+ factory,
286
+ agents,
287
+ emit,
288
+ askAdmission,
289
+ questions: agentQuestions,
290
+ sessionDir: options.sessionDir,
291
+ programFile: options.programFile,
292
+ // The same value `run_start.program` carries, so an Agent's prompt names
293
+ // the Run the reader sees in the Run record.
294
+ runName: definition.name ?? "program",
295
+ configExtensions: options.config?.extensions ?? EMPTY_EFFECTIVE_CONFIG.extensions,
296
+ ...(profile === undefined ? {} : { profile }),
297
+ });
213
298
 
214
- const ctx: RunContext<Args> = {
215
- args,
216
- spawn: spawnGate.spawn,
217
- ...(profile === undefined ? {} : { profile: { id: profile.id } }),
218
- };
219
- emit({
220
- type: "run_start",
221
- program: definition.name ?? "program",
222
- artifact: destination,
223
- ...(profile === undefined ? {} : { profile: profile.id }),
224
- });
299
+ const pauseRequests = createPauseRequests(answers);
300
+ const ctx: RunContext<Args> = {
301
+ args,
302
+ spawn: spawnGate.spawn,
303
+ askUser: pauseRequests.askUser,
304
+ pause: pauseRequests.pause,
305
+ ...(profile === undefined ? {} : { profile: { id: profile.id } }),
306
+ ...(host === undefined ? {} : { host: host.source }),
307
+ };
308
+ emit({
309
+ type: "run_start",
310
+ program: definition.name ?? "program",
311
+ artifact: destination,
312
+ ...(profile === undefined ? {} : { profile: profile.id }),
313
+ });
225
314
 
226
- // The program's settlement is held rather than rethrown from a `finally`, so
227
- // publication can displace it when the checkpoint fails (ADR-0021).
228
- const settlement = await settleRun({
229
- program: () => definition.run(ctx),
230
- requests: controlRequests(options.control, options.signal),
231
- agents,
232
- closeAdmission: () => {
233
- askAdmission.close();
234
- spawnGate.close();
235
- },
236
- });
237
- const outcome: RunOutcome = settlement.outcome;
238
- const settled = heldSettlement(settlement);
239
- // Idempotent: a settlement that never drained has not closed admission yet.
240
- askAdmission.close();
241
- spawnGate.close();
242
- await reapAll({ agents, emit });
243
- // No flush may land after the settled artifact, or an acknowledged Run would
244
- // be overwritten by an `interrupted` one.
245
- await flusher.quiesce();
246
- // run_end is the acknowledgement: nothing may report an outcome before the
247
- // checkpoint's destination-directory fsync has landed (ADR-0021).
248
- const publication = await publishRunCheckpoint({ outcome, ...checkpoint });
249
- emitRunEnd({
250
- emit,
251
- durationMs: Date.now() - startedAt,
252
- summary,
253
- ...endingFrom({ publication, outcome, destination, record: options.record }),
254
- });
255
- if (publication.kind === "displaced") throw publication.error;
256
- if (!settled.ok) throw settled.error;
257
- return settled.value;
315
+ // The program's settlement is held rather than rethrown from a `finally`, so
316
+ // publication can displace it when the checkpoint fails (ADR-0021).
317
+ const settlement = await settleRun({
318
+ program: () => definition.run(ctx),
319
+ requests: controlRequests(options.control, options.signal),
320
+ agents,
321
+ closeAdmission: () => {
322
+ askAdmission.close();
323
+ spawnGate.close();
324
+ },
325
+ questionRaised: agentQuestions.raised,
326
+ });
327
+ const outcome: RunOutcome = settlement.outcome;
328
+ const settled = heldSettlement(settlement);
329
+ // Idempotent: a settlement that never drained has not closed admission yet.
330
+ askAdmission.close();
331
+ spawnGate.close();
332
+ await reapAll({ agents, emit });
333
+ // The summarizer runs here and nowhere else: after every Agent is reaped, so
334
+ // it reads a session file pi has finished writing, and before settlement, so
335
+ // each summary is durable in the Cassette (ADR-0022). `settle()` quiesces the
336
+ // in-flight flushes itself, so no flush can land after the settled artifact.
337
+ // The summarizer's own Agent runs before that quiescence, so it can flush one
338
+ // more `interrupted` artifact; the settled publication supersedes it.
339
+ const summarized =
340
+ outcome === "paused"
341
+ ? await summarizeQuestions({
342
+ questions: agentQuestions,
343
+ agents,
344
+ policy: questionSummaryOf(options.config),
345
+ openAgent: spawnGate.openInternal,
346
+ ...(options.replay === undefined ? {} : { replaying: true }),
347
+ })
348
+ : { warnings: [] };
349
+ // Built once, after the summaries landed, so the wake payload and the returned
350
+ // result carry the same questions. The program's own questions come first;
351
+ // both registries are Run-scoped and neither can key a question of the other.
352
+ const openQuestions = [...pauseRequests.questions, ...agentQuestions.questions];
353
+ const pausedWarnings = [
354
+ ...(settled.ok === "paused" ? settled.warnings : []),
355
+ ...summarized.warnings,
356
+ ];
357
+ // run_end is the acknowledgement: nothing may report an outcome before the
358
+ // checkpoint's destination-directory fsync has landed (ADR-0021).
359
+ const { displacedBy, ...ending } = await checkpoint.settle(outcome, {
360
+ // The program's own Questions first, then the Agents': the same order the
361
+ // RunResult carries, so an artifact and a reader agree (ADR-0022).
362
+ questions: openQuestions,
363
+ answers: answers.resolved(),
364
+ ...(pauseRequests.reason === undefined ? {} : { reason: pauseRequests.reason }),
365
+ });
366
+ emitRunEnd({
367
+ emit,
368
+ durationMs: Date.now() - startedAt,
369
+ summary,
370
+ ...ending,
371
+ ...(settled.ok === "paused" && pausedWarnings.length > 0 ? { warnings: pausedWarnings } : {}),
372
+ });
373
+ if (displacedBy !== undefined) throw displacedBy;
374
+ if (settled.ok === "paused") {
375
+ // Built after publication, so `checkpoint` always names a file that is on
376
+ // disk and fsynced (ADR-0021).
377
+ return {
378
+ outcome: "paused",
379
+ questions: openQuestions,
380
+ ...(pauseRequests.reason === undefined ? {} : { reason: pauseRequests.reason }),
381
+ checkpoint: destination,
382
+ ...(pausedWarnings.length > 0 ? { warnings: pausedWarnings } : {}),
383
+ };
384
+ }
385
+ if (!settled.ok) throw settled.error;
386
+ return { outcome: "completed", value: settled.value };
387
+ } finally {
388
+ await host?.remove();
389
+ }
258
390
  }
259
391
 
260
392
  /**
@@ -284,8 +416,8 @@ async function loadResume(
284
416
  ): Promise<Cassette | null> {
285
417
  if (path === undefined) return null;
286
418
  const cassette = await loadCassette(path);
287
- const warning = interruptedResumeWarning(cassette, path);
288
- if (warning !== null) writeRecordingDiagnostic(warning);
419
+ const readable = readableCassette(cassette, path, "resume");
420
+ if (readable.ok && readable.warning !== undefined) writeRecordingDiagnostic(readable.warning);
289
421
  warnOnIdentity(cassette, path, program);
290
422
  return cassette;
291
423
  }
@@ -299,12 +431,14 @@ function warnOnIdentity(cassette: Cassette, path: string, program: ProgramIdenti
299
431
  /** What the Orchestration Program body produced, before the Run acknowledges it. */
300
432
  type Settlement<Result> =
301
433
  | { readonly ok: true; readonly value: Result }
302
- | { readonly ok: false; readonly error: unknown };
434
+ | { readonly ok: false; readonly error: unknown }
435
+ | { readonly ok: "paused"; readonly warnings: readonly string[] };
303
436
 
304
437
  /**
305
438
  * Turns one settlement into the result the Run holds until its Checkpoint has
306
- * landed. A stopped or paused Run rejects with its own code, so the caller can
307
- * tell an ended Run from a failed one (ADR-0024).
439
+ * landed. A stopped Run rejects with its own code (ADR-0024); a paused Run is
440
+ * a third state, and becomes a return value once the Checkpoint is on disk
441
+ * (ADR-0022).
308
442
  */
309
443
  function heldSettlement<Result>(settlement: RunSettlement<Result>): Settlement<Result> {
310
444
  switch (settlement.outcome) {
@@ -313,19 +447,20 @@ function heldSettlement<Result>(settlement: RunSettlement<Result>): Settlement<R
313
447
  case "failed":
314
448
  return { ok: false, error: settlement.error };
315
449
  case "paused":
316
- // The cut-short Agents are named here, so the rejection says which Asks
317
- // the deadline ended rather than leaving that to the Checkpoint alone.
318
- return { ok: false, error: new YaagError("RUN_PAUSED", pauseMessage(settlement.cutShort)) };
450
+ // The cut-short Agents ride as warnings, so the paused result says which
451
+ // Asks a deadline ended rather than leaving that to the Checkpoint alone.
452
+ return {
453
+ ok: "paused",
454
+ warnings: [
455
+ ...settlement.warnings,
456
+ ...settlement.cutShort.map((agent) => `${agent}: Ask cut short by the pause deadline`),
457
+ ],
458
+ };
319
459
  case "stopped":
320
460
  return { ok: false, error: new YaagError("RUN_STOPPED", "run stopped") };
321
461
  }
322
462
  }
323
463
 
324
- /** Names the Asks a pause deadline cut short, or reports a clean drain. */
325
- function pauseMessage(cutShort: readonly string[]): string {
326
- return cutShort.length === 0 ? "run paused" : `run paused, cutting short: ${cutShort.join(", ")}`;
327
- }
328
-
329
464
  /**
330
465
  * Narrows the Run's incoming args to the program's declared Args at the one
331
466
  * boundary where untyped input enters typed code. Schema programs are proven
@@ -348,6 +483,8 @@ export interface FactorySelection {
348
483
  readonly collector: CassetteSink;
349
484
  readonly replay: Cassette | null;
350
485
  readonly resume: Cassette | null;
486
+ /** The answers of this resume; a recorded parked Ask reads its own here. */
487
+ readonly answers?: AnswerLedger;
351
488
  }
352
489
 
353
490
  /**
@@ -371,7 +508,11 @@ function selectLiveFactory(selection: FactorySelection): TransportFactory {
371
508
  selection.options.skillProbe ?? liveSkillProbe,
372
509
  );
373
510
  const live = worktreeTransport(restricted);
374
- return selection.resume === null ? live : resumeTransport(selection.resume, live);
511
+ if (selection.resume === null) return live;
512
+ const answers = selection.answers;
513
+ return resumeTransport(selection.resume, live, {
514
+ answerFor: (questionId) => answers?.take(questionId),
515
+ });
375
516
  }
376
517
 
377
518
  interface ReapOptions {
@@ -413,42 +554,8 @@ interface RunEndOptions {
413
554
  readonly checkpointLost?: string;
414
555
  /** Path of the published Checkpoint a paused or stopped Run resumes from (ADR-0054). */
415
556
  readonly checkpoint?: string;
416
- }
417
-
418
- /**
419
- * Folds one publication result into how the Run ends. A displaced publication
420
- * takes the outcome; a lost Checkpoint keeps it and reports the loss instead.
421
- */
422
- function endingFrom(options: {
423
- readonly publication: RunCheckpointResult;
424
- readonly outcome: RunOutcome;
425
- readonly destination: string;
426
- /** The `--record` destination, or undefined; it decides what is kept. */
427
- readonly record: string | undefined;
428
- }): {
429
- readonly outcome: RunOutcome;
430
- readonly checkpointLost?: string;
431
- readonly checkpoint?: string;
432
- } {
433
- const { publication, outcome, destination, record } = options;
434
- switch (publication.kind) {
435
- case "published":
436
- // A Run names a Checkpoint only when publication kept the artifact, and
437
- // only a paused or stopped Run resumes from one (ADR-0054). `keepsCheckpoint`
438
- // is the one rule for the first half, so no Run can name a file that
439
- // publication just deleted.
440
- return {
441
- outcome,
442
- ...((outcome === "paused" || outcome === "stopped") &&
443
- keepsCheckpoint({ outcome, ...(record === undefined ? {} : { record }) })
444
- ? { checkpoint: destination }
445
- : {}),
446
- };
447
- case "lost":
448
- return { outcome, checkpointLost: publication.message };
449
- case "displaced":
450
- return { outcome: "failed" };
451
- }
557
+ /** Ask rejections observed during a pause drain; they never change the outcome. */
558
+ readonly warnings?: readonly string[];
452
559
  }
453
560
 
454
561
  /** Emits the Run's acknowledgement, the last Lifecycle Event of every Run. */
@@ -459,11 +566,13 @@ function emitRunEnd({
459
566
  summary,
460
567
  checkpointLost,
461
568
  checkpoint,
569
+ warnings,
462
570
  }: RunEndOptions): void {
463
571
  emit({
464
572
  type: "run_end",
465
573
  ...(checkpointLost === undefined ? {} : { checkpointLost }),
466
574
  ...(checkpoint === undefined ? {} : { checkpoint }),
575
+ ...(warnings === undefined ? {} : { warnings }),
467
576
  ok: outcome === "completed",
468
577
  outcome,
469
578
  durationMs,
@@ -11,7 +11,7 @@ import type { PromptAudience, PromptText, SystemPromptAgent } from "../contract/
11
11
  // `public-api.ts`, and the vendored author declaration tree follows source
12
12
  // imports, so an index import would pull `prompt/index.d.ts` and
13
13
  // `prompt-gist.d.ts` into the ADR-0045 surface that
14
- // `apps/yaag/scripts/runtime-dts.test.ts` guards.
14
+ // `apps/yaag/test/scripts/runtime-dts.test.ts` guards.
15
15
  import { prompt } from "../prompt/prompt.ts";
16
16
  import { renderSentinel } from "./render-sentinel.ts";
17
17
 
@@ -36,12 +36,31 @@ export const liveTransport: TransportFactory = {
36
36
  options: OpenOptions,
37
37
  observeStartup?: TransportStartupObserver,
38
38
  ): Promise<AgentTransport> {
39
+ assertHostForkSource(options);
39
40
  const transport = new LiveTransport(options);
40
41
  await transport.ready(observeStartup);
41
42
  return transport;
42
43
  },
43
44
  };
44
45
 
46
+ /**
47
+ * Refuses a Host Fork that has no path to fork from, before any process work.
48
+ *
49
+ * The guard sits here and not at the spawn gate, because a replay legitimately
50
+ * holds no copy: it never spawns pi at all. Only a live open is a real `pi`
51
+ * process. A recorded `sessionFile` exempts the open: a resume continues a
52
+ * recorded Host Fork with `--session`, which is not a fork (ADR-0068).
53
+ */
54
+ function assertHostForkSource(options: OpenOptions): void {
55
+ if (options.origin !== "host-fork") return;
56
+ if (options.forkSession !== undefined || options.sessionFile !== undefined) return;
57
+ throw new YaagError(
58
+ "FORK_REFUSED",
59
+ `agent "${options.name}": this Run holds no host session copy to fork from`,
60
+ options.name,
61
+ );
62
+ }
63
+
45
64
  class LiveTransport implements AgentTransport {
46
65
  model = "";
47
66
 
@@ -1,4 +1,9 @@
1
- import { REPORT_RESULT_EXTENSION_PATH, REPORT_RESULT_TOOL_NAME } from "../ask-contract/index.ts";
1
+ import {
2
+ REPORT_RESULT_EXTENSION_PATH,
3
+ REPORT_RESULT_TOOL_NAME,
4
+ REQUEST_USER_INPUT_EXTENSION_PATH,
5
+ REQUEST_USER_INPUT_TOOL_NAME,
6
+ } from "../ask-contract/index.ts";
2
7
  import type { AgentProgress } from "../contract/index.ts";
3
8
  import { isThinkingLevel, type ThinkingLevel } from "../model/index.ts";
4
9
  import {
@@ -18,7 +23,16 @@ import type {
18
23
 
19
24
  export type { AgentProgress } from "../contract/index.ts";
20
25
 
21
- /** The command line for one Agent. */
26
+ /**
27
+ * The command line for one Agent.
28
+ *
29
+ * Which fields may appear here is not decided in this file: the spawn field
30
+ * table (`cassette/spawn-identity.ts`) marks each row `argv: "flag"` or
31
+ * `argv: "never"`, and `open-options-classification.test.ts` fails when a row
32
+ * marked `never` reaches this command line. The direction of the dependency is
33
+ * deliberate: `transport/` must not import `cassette/` at runtime, so the test
34
+ * is the reader of the table, not this function.
35
+ */
22
36
  export function piCommand(options: OpenOptions, toolProbeExtensionPath?: string): string[] {
23
37
  const cmd = ["pi", "--mode", "rpc"];
24
38
  if (options.model) cmd.push("--model", options.model);
@@ -72,7 +86,8 @@ function appendCapabilities(
72
86
  cmd.push("--no-extensions", "--no-context-files", "--no-prompt-templates");
73
87
  }
74
88
  // Load order is fixed (ADR-0063): the prompt extension first, then the
75
- // program extensions, `report_result`, the tool probe, and the recorder last.
89
+ // program extensions, `report_result`, `request_user_input`, the tool probe,
90
+ // and the recorder last.
76
91
  // `before_agent_start` handlers chain in load order, so first means a program
77
92
  // extension appends to the already assembled Agent System Prompt.
78
93
  //
@@ -87,6 +102,9 @@ function appendCapabilities(
87
102
  // output schema long after the process started and pi loads extensions only
88
103
  // at startup (ADR-0032).
89
104
  cmd.push("-e", REPORT_RESULT_EXTENSION_PATH);
105
+ // The user-question tool loads before the probe, so the probe reports it: it
106
+ // registers at startup and is a required tool of this spawn (ADR-0023).
107
+ if (options.canAskUser === true) cmd.push("-e", REQUEST_USER_INPUT_EXTENSION_PATH);
90
108
  // The caller decides whether the probe runs: it loads the extension only when
91
109
  // the spawn flags promised something verifiable (see toolContract).
92
110
  if (toolProbeExtensionPath !== undefined) cmd.push("-e", toolProbeExtensionPath);
@@ -108,6 +126,7 @@ function appendCapabilities(
108
126
  export interface ToolSelection {
109
127
  readonly tools?: readonly string[] | undefined;
110
128
  readonly inherit?: boolean | undefined;
129
+ readonly canAskUser?: boolean | undefined;
111
130
  }
112
131
 
113
132
  /**
@@ -125,10 +144,17 @@ export interface ToolSelection {
125
144
  */
126
145
  export function toolAllowlist(options: ToolSelection): readonly string[] | null {
127
146
  const { tools } = options;
147
+ // Note the asymmetry with `report_result`: this name is added to yaag's own
148
+ // implicit list, or to a list the spawn guard already proved names it, so no
149
+ // program's allowlist is ever widened behind its back (ADR-0023).
150
+ const asked = options.canAskUser === true ? [REQUEST_USER_INPUT_TOOL_NAME] : [];
128
151
  if (tools === undefined) {
129
- return options.inherit === true ? null : [REPORT_RESULT_TOOL_NAME];
152
+ // An inheriting spawn emits no allowlist, also when it may ask: pi composes
153
+ // the toolset itself and keeps every extension tool.
154
+ if (options.inherit === true) return null;
155
+ return [REPORT_RESULT_TOOL_NAME, ...asked];
130
156
  }
131
- return [...new Set([...tools, REPORT_RESULT_TOOL_NAME])];
157
+ return [...new Set([...tools, REPORT_RESULT_TOOL_NAME, ...asked])];
132
158
  }
133
159
 
134
160
  function appendTools(cmd: string[], options: OpenOptions): void {