@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.
- package/package.json +2 -3
- package/src/agent/agent.ts +75 -23
- package/src/agent/ask-user-capability.ts +36 -0
- package/src/agent/fork.ts +40 -12
- package/src/agent/host-fork.ts +85 -0
- package/src/agent/index.ts +2 -1
- package/src/agent/spawn-definition-request.ts +38 -3
- package/src/agent/spawn-open.ts +59 -100
- package/src/agent/spawn-plan.ts +114 -0
- package/src/agent/spawn-request.ts +34 -3
- package/src/agent/spawn.ts +41 -5
- package/src/ask/ask-exchange-options.ts +8 -6
- package/src/ask/ask-exchange.ts +102 -97
- package/src/ask/ask-guard.ts +207 -0
- package/src/ask/ask-settlement.ts +8 -0
- package/src/ask/ask-timing.ts +12 -0
- package/src/ask/idle-watch.ts +12 -2
- package/src/ask/index.ts +1 -0
- package/src/ask/stall-watchdog.ts +13 -3
- package/src/ask-contract/ask-limit.ts +24 -6
- package/src/ask-contract/index.ts +8 -0
- package/src/ask-contract/request-user-input-extension.ts +105 -0
- package/src/ask-contract/request-user-input.ts +58 -0
- package/src/cassette/cassette-loader.ts +56 -18
- package/src/cassette/cassette-schema.ts +37 -1
- package/src/cassette/cassette.ts +58 -32
- package/src/cassette/checkpoint.ts +306 -0
- package/src/cassette/index.ts +25 -7
- package/src/cassette/parked-asks.ts +38 -0
- package/src/cassette/replay-divergence.ts +7 -97
- package/src/cassette/resume-identity.ts +5 -1
- package/src/cassette/resume-preconditions.ts +24 -0
- package/src/cassette/resume-transport.ts +112 -13
- package/src/cassette/run-identity.ts +109 -0
- package/src/cassette/session-answer.ts +100 -0
- package/src/cassette/spawn-identity.ts +318 -0
- package/src/catalog/registry-reader.ts +1 -1
- package/src/config/config-schema.ts +33 -0
- package/src/config/effective-config.ts +53 -0
- package/src/config/index.ts +4 -0
- package/src/contract/agent-policy.ts +9 -0
- package/src/contract/error-codes.ts +3 -2
- package/src/contract/index.ts +1 -0
- package/src/contract/spawn-options.ts +33 -2
- package/src/control/index.ts +2 -0
- package/src/control/pause-drain.ts +81 -24
- package/src/error-factories.ts +8 -0
- package/src/events.ts +10 -2
- package/src/index.ts +15 -1
- package/src/model/index.ts +1 -1
- package/src/pi-session/append-tool-result.ts +165 -0
- package/src/pi-session/index.ts +30 -0
- package/src/pi-session/pi-session-error.ts +34 -0
- package/src/pi-session/session-copy.ts +113 -0
- package/src/pi-session/session-entries.ts +130 -0
- package/src/public-api.ts +1 -0
- package/src/question-summary/index.ts +18 -0
- package/src/question-summary/summarize-question.ts +129 -0
- package/src/question-summary/summary-policy.ts +28 -0
- package/src/run/agent-questions.ts +157 -0
- package/src/run/answers.ts +91 -0
- package/src/run/host-session.ts +233 -0
- package/src/run/index.ts +12 -0
- package/src/run/pause-questions.ts +98 -0
- package/src/run/pause-signal.ts +32 -0
- package/src/run/question-id.ts +18 -0
- package/src/run/questions.ts +31 -0
- package/src/run/run-context.ts +21 -0
- package/src/run/run-result.ts +21 -0
- package/src/run/run-settlement.ts +36 -4
- package/src/run/run.ts +248 -139
- package/src/system-prompt/agent-system-prompt.ts +1 -1
- package/src/transport/live-transport.ts +19 -0
- package/src/transport/pi-state.ts +31 -5
- package/src/transport/tool-probe.ts +4 -0
- package/src/transport/transport.ts +31 -1
- package/src/types.ts +1 -0
- package/src/cassette/checkpoint-flush.ts +0 -101
- 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
|
-
|
|
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
|
-
|
|
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 {
|
|
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
|
|
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.
|
|
105
|
-
*
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
181
|
-
|
|
182
|
-
//
|
|
183
|
-
//
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
const
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
//
|
|
208
|
-
//
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
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
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
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
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
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
|
|
288
|
-
if (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
|
|
307
|
-
*
|
|
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
|
|
317
|
-
//
|
|
318
|
-
return {
|
|
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
|
-
|
|
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 {
|
|
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
|
-
/**
|
|
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,
|
|
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
|
-
|
|
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 {
|