@yaag/runtime 0.25.0 → 0.26.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 +46 -6
- package/src/agent/ask-user-capability.ts +36 -0
- package/src/agent/index.ts +2 -1
- package/src/agent/spawn-open.ts +24 -5
- package/src/agent/spawn-request.ts +18 -1
- package/src/agent/spawn.ts +21 -2
- package/src/ask/ask-exchange-options.ts +5 -0
- package/src/ask/ask-exchange.ts +67 -2
- package/src/ask/ask-settlement.ts +8 -0
- package/src/ask/idle-watch.ts +12 -2
- 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 +50 -1
- package/src/cassette/cassette-schema.ts +27 -0
- package/src/cassette/cassette.ts +49 -0
- package/src/cassette/index.ts +10 -1
- package/src/cassette/replay-divergence.ts +5 -0
- package/src/cassette/resume-preconditions.ts +10 -0
- package/src/cassette/resume-transport.ts +111 -6
- package/src/cassette/run-checkpoint.ts +52 -3
- package/src/cassette/session-answer.ts +163 -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 +2 -2
- package/src/control/index.ts +2 -0
- package/src/control/pause-drain.ts +81 -24
- package/src/events.ts +6 -0
- package/src/index.ts +11 -1
- package/src/model/index.ts +1 -1
- package/src/public-api.ts +1 -0
- package/src/question-summary/index.ts +22 -0
- package/src/question-summary/session-copy.ts +169 -0
- package/src/question-summary/summarize-question.ts +129 -0
- package/src/question-summary/summary-policy.ts +25 -0
- package/src/run/agent-questions.ts +75 -0
- package/src/run/answers.ts +70 -0
- package/src/run/index.ts +5 -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 +18 -0
- package/src/run/run-result.ts +21 -0
- package/src/run/run-settlement.ts +36 -4
- package/src/run/run.ts +119 -20
- package/src/system-prompt/agent-system-prompt.ts +1 -1
- package/src/transport/pi-state.ts +21 -4
- package/src/transport/tool-probe.ts +4 -0
- package/src/transport/transport.ts +26 -0
|
@@ -1,3 +1,8 @@
|
|
|
1
|
+
import {
|
|
2
|
+
isReportResultCommandFrame,
|
|
3
|
+
RESUME_NUDGE,
|
|
4
|
+
readQuestionFrame,
|
|
5
|
+
} from "../ask-contract/index.ts";
|
|
1
6
|
import type {
|
|
2
7
|
AgentStats,
|
|
3
8
|
AgentTransport,
|
|
@@ -14,7 +19,7 @@ import type {
|
|
|
14
19
|
TransportStartupObserver,
|
|
15
20
|
} from "../transport/index.ts";
|
|
16
21
|
import { FrameQueue } from "../transport/index.ts";
|
|
17
|
-
import type { Cassette, CassetteAgent } from "./cassette.ts";
|
|
22
|
+
import type { Cassette, CassetteAgent, CassetteAsk } from "./cassette.ts";
|
|
18
23
|
import { CassetteReplay } from "./cassette-replay.ts";
|
|
19
24
|
import {
|
|
20
25
|
recordedSpawnSelection,
|
|
@@ -23,13 +28,27 @@ import {
|
|
|
23
28
|
} from "./replay-divergence.ts";
|
|
24
29
|
import { checkResumePreconditions } from "./resume-preconditions.ts";
|
|
25
30
|
|
|
31
|
+
/**
|
|
32
|
+
* What a resume knows about the human's answers (ADR-0023). A recorded Ask
|
|
33
|
+
* that parked on `request_user_input` reads its answer here: with one, the Ask
|
|
34
|
+
* is restored; without one, it parks again and the Run pauses.
|
|
35
|
+
*/
|
|
36
|
+
export interface AskUserRestoration {
|
|
37
|
+
/** The answer of a recorded parked Ask, or undefined when it stays open. */
|
|
38
|
+
answerFor(questionId: string): string | undefined;
|
|
39
|
+
}
|
|
40
|
+
|
|
26
41
|
/**
|
|
27
42
|
* Creates a Cassette-prefix transport that continues with live pi at divergence.
|
|
28
43
|
*
|
|
29
44
|
* Matched Agents validate their recorded continuation point before replaying.
|
|
30
45
|
* Spawn mismatches intentionally bypass those checks and start a fresh Agent.
|
|
31
46
|
*/
|
|
32
|
-
export function resumeTransport(
|
|
47
|
+
export function resumeTransport(
|
|
48
|
+
cassette: Cassette,
|
|
49
|
+
live: TransportFactory,
|
|
50
|
+
restoration?: AskUserRestoration,
|
|
51
|
+
): TransportFactory {
|
|
33
52
|
let spawnCursor = 0;
|
|
34
53
|
return {
|
|
35
54
|
async open(
|
|
@@ -45,7 +64,7 @@ export function resumeTransport(cassette: Cassette, live: TransportFactory): Tra
|
|
|
45
64
|
...(agent.sessionFile === undefined ? {} : { sessionFile: agent.sessionFile }),
|
|
46
65
|
...(worktree === undefined ? {} : { worktree }),
|
|
47
66
|
});
|
|
48
|
-
return new ResumeTransport(agent, live, options);
|
|
67
|
+
return new ResumeTransport(agent, live, options, restoration);
|
|
49
68
|
},
|
|
50
69
|
|
|
51
70
|
// A changed spawn must not silently inherit the recorded model, so the
|
|
@@ -64,6 +83,9 @@ class ResumeTransport implements AgentTransport {
|
|
|
64
83
|
readonly #liveFactory: TransportFactory;
|
|
65
84
|
readonly #continuation: OpenOptions;
|
|
66
85
|
readonly #replay: CassetteReplay;
|
|
86
|
+
readonly #restoration: AskUserRestoration | undefined;
|
|
87
|
+
/** The Ask prompt the nudge replaces, while a restored Ask still awaits it. */
|
|
88
|
+
#nudgePrompt: string | null = null;
|
|
67
89
|
readonly #frames = new FrameQueue();
|
|
68
90
|
readonly #buffered: Frame[] = [];
|
|
69
91
|
#askCursor = 0;
|
|
@@ -74,8 +96,14 @@ class ResumeTransport implements AgentTransport {
|
|
|
74
96
|
#activationFailed = false;
|
|
75
97
|
#closed: Promise<AgentStats> | null = null;
|
|
76
98
|
|
|
77
|
-
constructor(
|
|
99
|
+
constructor(
|
|
100
|
+
agent: CassetteAgent,
|
|
101
|
+
liveFactory: TransportFactory,
|
|
102
|
+
options: OpenOptions,
|
|
103
|
+
restoration?: AskUserRestoration,
|
|
104
|
+
) {
|
|
78
105
|
this.#agent = agent;
|
|
106
|
+
this.#restoration = restoration;
|
|
79
107
|
this.#liveFactory = liveFactory;
|
|
80
108
|
this.#continuation = continuationOptions(agent, options);
|
|
81
109
|
this.#replay = new CassetteReplay(agent);
|
|
@@ -92,7 +120,7 @@ class ResumeTransport implements AgentTransport {
|
|
|
92
120
|
this.#buffered.push(frame);
|
|
93
121
|
return;
|
|
94
122
|
}
|
|
95
|
-
this.#live?.send(frame);
|
|
123
|
+
this.#live?.send(this.#nudged(frame));
|
|
96
124
|
}
|
|
97
125
|
|
|
98
126
|
frames(): AsyncIterable<Frame> {
|
|
@@ -104,6 +132,10 @@ class ResumeTransport implements AgentTransport {
|
|
|
104
132
|
if (this.#mode === "activating") return undefined;
|
|
105
133
|
const mismatch = replayMismatch.ask(this.#agent, this.#askCursor, marker);
|
|
106
134
|
if (!mismatch) {
|
|
135
|
+
// The restoration comes after the match: a parked Ask whose marker moved
|
|
136
|
+
// is a diverged Ask, and it must never inherit another Ask's question.
|
|
137
|
+
const restored = this.#restore(this.#agent.asks[this.#askCursor]);
|
|
138
|
+
if (restored !== null) return restored;
|
|
107
139
|
this.#askCursor += 1;
|
|
108
140
|
return this.#replay.beginAsk(marker);
|
|
109
141
|
}
|
|
@@ -146,6 +178,53 @@ class ResumeTransport implements AgentTransport {
|
|
|
146
178
|
return this.#closed;
|
|
147
179
|
}
|
|
148
180
|
|
|
181
|
+
/**
|
|
182
|
+
* Handles a recorded Ask that parked on `request_user_input` (ADR-0023).
|
|
183
|
+
*
|
|
184
|
+
* The recorded Ask has no settlement, so it can never replay. With an answer
|
|
185
|
+
* it is restored: the answer goes into the session, pi respawns on it, and
|
|
186
|
+
* 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.
|
|
188
|
+
*/
|
|
189
|
+
#restore(ask: CassetteAsk | undefined): AskPlayback | undefined | null {
|
|
190
|
+
const incomplete = ask?.incomplete;
|
|
191
|
+
if (ask === undefined || incomplete === undefined) return null;
|
|
192
|
+
const answer = this.#restoration?.answerFor(incomplete.questionId);
|
|
193
|
+
if (answer === undefined) {
|
|
194
|
+
const call = recordedQuestion(ask, incomplete.toolCallId);
|
|
195
|
+
this.#askCursor += 1;
|
|
196
|
+
return {
|
|
197
|
+
settles: false,
|
|
198
|
+
parked: {
|
|
199
|
+
toolCallId: incomplete.toolCallId,
|
|
200
|
+
questionId: incomplete.questionId,
|
|
201
|
+
question: call?.question ?? "",
|
|
202
|
+
...(call?.context === undefined ? {} : { context: call.context }),
|
|
203
|
+
},
|
|
204
|
+
};
|
|
205
|
+
}
|
|
206
|
+
// The answer is already in the session: `restoreSessionAnswers` wrote it
|
|
207
|
+
// before the Run started. This side only respawns and nudges (ADR-0023).
|
|
208
|
+
// The latch names the recorded Ask prompt, so the substitution hits that
|
|
209
|
+
// one frame and never the `report_result` schema command beside it.
|
|
210
|
+
this.#nudgePrompt = recordedPrompt(ask);
|
|
211
|
+
this.#mode = "activating";
|
|
212
|
+
this.#activation = this.#activate(null);
|
|
213
|
+
return undefined;
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/**
|
|
217
|
+
* Substitutes the nudge for the Ask prompt of a restored Ask, one time. Every
|
|
218
|
+
* other frame, the `report_result` schema command included, passes through
|
|
219
|
+
* unchanged, and the frame id stays, so the Ask's command still settles.
|
|
220
|
+
*/
|
|
221
|
+
#nudged(frame: Frame): Frame {
|
|
222
|
+
if (this.#nudgePrompt === null) return frame;
|
|
223
|
+
if (frame.type !== "prompt" || frame.message !== this.#nudgePrompt) return frame;
|
|
224
|
+
this.#nudgePrompt = null;
|
|
225
|
+
return { ...frame, message: RESUME_NUDGE };
|
|
226
|
+
}
|
|
227
|
+
|
|
149
228
|
async #activate(marker: AskMarker | null): Promise<void> {
|
|
150
229
|
// End the old source before attaching the new one, but keep the outward
|
|
151
230
|
// queue open so Connection remains attached across the handoff.
|
|
@@ -157,7 +236,7 @@ class ResumeTransport implements AgentTransport {
|
|
|
157
236
|
const live = await this.#liveFactory.open(this.#continuation);
|
|
158
237
|
this.#live = live;
|
|
159
238
|
if (marker !== null) live.beginAsk(marker);
|
|
160
|
-
for (const frame of this.#buffered.splice(0)) live.send(frame);
|
|
239
|
+
for (const frame of this.#buffered.splice(0)) live.send(this.#nudged(frame));
|
|
161
240
|
this.#mode = "live";
|
|
162
241
|
void this.#forward(live.frames());
|
|
163
242
|
} catch {
|
|
@@ -198,6 +277,32 @@ class ResumeTransport implements AgentTransport {
|
|
|
198
277
|
}
|
|
199
278
|
}
|
|
200
279
|
|
|
280
|
+
/**
|
|
281
|
+
* The Ask prompt of a recorded Ask, read back from its sent frames. The private
|
|
282
|
+
* `report_result` schema command is a prompt frame too, and it is not the Ask
|
|
283
|
+
* prompt, so it is skipped (ADR-0032).
|
|
284
|
+
*/
|
|
285
|
+
function recordedPrompt(ask: CassetteAsk): string | null {
|
|
286
|
+
for (const frame of ask.sentFrames) {
|
|
287
|
+
if (frame.type !== "prompt" || typeof frame.message !== "string") continue;
|
|
288
|
+
if (isReportResultCommandFrame(frame)) continue;
|
|
289
|
+
return frame.message;
|
|
290
|
+
}
|
|
291
|
+
return null;
|
|
292
|
+
}
|
|
293
|
+
|
|
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
|
+
|
|
201
306
|
function continuationOptions(agent: CassetteAgent, original: OpenOptions): OpenOptions {
|
|
202
307
|
const { worktree: _worktree, ...spawn } = agent.spawn;
|
|
203
308
|
const worktree = worktreeResolution(agent);
|
|
@@ -2,12 +2,28 @@ import { mkdir, unlink } from "node:fs/promises";
|
|
|
2
2
|
import { dirname } from "node:path";
|
|
3
3
|
import { YaagError } from "../errors.ts";
|
|
4
4
|
import type { RunOutcome } from "../events.ts";
|
|
5
|
-
import type {
|
|
5
|
+
import type {
|
|
6
|
+
CassetteAnswer,
|
|
7
|
+
CassetteCollector,
|
|
8
|
+
CassetteQuestion,
|
|
9
|
+
CassetteRun,
|
|
10
|
+
} from "./cassette.ts";
|
|
6
11
|
import { publishCassette } from "./cassette-publish.ts";
|
|
7
12
|
import { sha256Hex } from "./program-hash.ts";
|
|
8
13
|
|
|
9
14
|
/** What a resume is about to re-execute; resolved once, at Run start. */
|
|
10
|
-
export type RunIdentity = Omit<CassetteRun, "outcome">;
|
|
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
|
+
}
|
|
11
27
|
|
|
12
28
|
/**
|
|
13
29
|
* One Run's publication request: what settled, what it collected, and where the
|
|
@@ -24,6 +40,14 @@ export interface RunCheckpointOptions {
|
|
|
24
40
|
readonly destination: string;
|
|
25
41
|
/** Invocation identity written into the artifact's run block. */
|
|
26
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;
|
|
27
51
|
}
|
|
28
52
|
|
|
29
53
|
/**
|
|
@@ -56,7 +80,11 @@ export async function publishRunCheckpoint(
|
|
|
56
80
|
await ensureCheckpointDirectory(options.record, options.destination);
|
|
57
81
|
await publishCassette(
|
|
58
82
|
options.destination,
|
|
59
|
-
options.collector.cassette({
|
|
83
|
+
options.collector.cassette({
|
|
84
|
+
outcome: options.outcome,
|
|
85
|
+
...options.identity,
|
|
86
|
+
...wakePayload(options.outcome, options.wake),
|
|
87
|
+
}),
|
|
60
88
|
);
|
|
61
89
|
return { kind: "published" };
|
|
62
90
|
} catch (error) {
|
|
@@ -88,6 +116,27 @@ export async function publishRunCheckpoint(
|
|
|
88
116
|
}
|
|
89
117
|
}
|
|
90
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
|
+
|
|
91
140
|
/**
|
|
92
141
|
* Whether a Run keeps its artifact: `--record` names a destination, or the Run
|
|
93
142
|
* paused or stopped. Every other Run discards the in-flight artifact, so it
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Restoration of one human answer into a pi session file (ADR-0023).
|
|
3
|
+
*
|
|
4
|
+
* The Agent parked on a `request_user_input` tool call and the process died.
|
|
5
|
+
* The answer goes back into the session as the tool result of that call, so the
|
|
6
|
+
* respawned Agent reads it as the result of its own request.
|
|
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.
|
|
11
|
+
*/
|
|
12
|
+
import { appendFile } from "node:fs/promises";
|
|
13
|
+
import { REQUEST_USER_INPUT_TOOL_NAME } from "../ask-contract/index.ts";
|
|
14
|
+
import { YaagError } from "../errors.ts";
|
|
15
|
+
import type { Cassette } from "./cassette.ts";
|
|
16
|
+
|
|
17
|
+
/** One correlated answer, and the session file it belongs to. */
|
|
18
|
+
export interface SessionAnswerAppend {
|
|
19
|
+
readonly sessionFile: string;
|
|
20
|
+
/** The tool call id of the parked `request_user_input` call. */
|
|
21
|
+
readonly toolCallId: string;
|
|
22
|
+
readonly answer: string;
|
|
23
|
+
}
|
|
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
|
+
/**
|
|
35
|
+
* Appends the answer as the tool result of the parked call.
|
|
36
|
+
*
|
|
37
|
+
* The same answer already in the file is a skip, so retrying a resume changes
|
|
38
|
+
* nothing. A different answer for the same call is a refusal: an answered
|
|
39
|
+
* question has one answer (ADR-0022). An absent tool call is a refusal too —
|
|
40
|
+
* the session is not the one the Cassette recorded.
|
|
41
|
+
*/
|
|
42
|
+
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
|
+
);
|
|
61
|
+
}
|
|
62
|
+
await appendFile(request.sessionFile, `${JSON.stringify(resultEntry(request, call))}\n`);
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* Restores every answered park of a resume source, before the Run starts.
|
|
67
|
+
*
|
|
68
|
+
* The restoration runs first, and not at the respawn, so a refused answer stops
|
|
69
|
+
* the resume before it does any work (ADR-0023). It is same-or-refuse, so a
|
|
70
|
+
* retried resume changes nothing.
|
|
71
|
+
*/
|
|
72
|
+
export async function restoreSessionAnswers(
|
|
73
|
+
cassette: Cassette,
|
|
74
|
+
answerFor: (questionId: string) => string | undefined,
|
|
75
|
+
): Promise<void> {
|
|
76
|
+
for (const agent of cassette.agents) {
|
|
77
|
+
const sessionFile = agent.sessionFile;
|
|
78
|
+
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
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
|
|
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.
|
|
134
|
+
}
|
|
135
|
+
}
|
|
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
|
+
}
|
|
@@ -31,7 +31,7 @@ const EMPTY: CatalogResult = { rows: [], diagnostics: [] };
|
|
|
31
31
|
* This function imports no Orchestration Program module and reads no target
|
|
32
32
|
* file. Two guards keep that honest: `registry-reader.test.ts` writes a module
|
|
33
33
|
* with a top-level side effect and asserts the marker file was never created,
|
|
34
|
-
* and `apps/yaag/
|
|
34
|
+
* and `apps/yaag/test/program/runtime-alias.test.ts` guards the
|
|
35
35
|
* program-visible surface.
|
|
36
36
|
*/
|
|
37
37
|
export async function readRegistryLayer(request: RegistryLayerRequest): Promise<CatalogResult> {
|
|
@@ -1,4 +1,11 @@
|
|
|
1
1
|
import { type Static, Type } from "typebox";
|
|
2
|
+
import { THINKING_LEVELS } from "../model/index.ts";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* The thinking union, built from `THINKING_LEVELS`, so a level pi adds cannot
|
|
6
|
+
* drift out of the config schema.
|
|
7
|
+
*/
|
|
8
|
+
const ThinkingLevelSchema = Type.Union(THINKING_LEVELS.map((level) => Type.Literal(level)));
|
|
2
9
|
|
|
3
10
|
/**
|
|
4
11
|
* The config document of one layer (spec rule 1): plain JSON, namespaced as
|
|
@@ -9,6 +16,9 @@ import { type Static, Type } from "typebox";
|
|
|
9
16
|
* a newer artifact still loads. A config file is hand-written, so an unknown
|
|
10
17
|
* key is a typo the author wants named, not forward compatibility.
|
|
11
18
|
*
|
|
19
|
+
* `askUser.summary` configures the Question Summary the fork summarizer writes
|
|
20
|
+
* (ADR-0022). Like `profile`, each of its keys is last-layer-wins.
|
|
21
|
+
*
|
|
12
22
|
* `profile` is the one top-level scalar key. Unlike `agents.extensions`, which
|
|
13
23
|
* concatenates across the layers, it does not concatenate: the last layer that
|
|
14
24
|
* states it wins (ADR-0052).
|
|
@@ -22,6 +32,29 @@ export const YaagConfigSchema = Type.Object(
|
|
|
22
32
|
),
|
|
23
33
|
),
|
|
24
34
|
profile: Type.Optional(Type.String()),
|
|
35
|
+
askUser: Type.Optional(
|
|
36
|
+
Type.Object(
|
|
37
|
+
{
|
|
38
|
+
summary: Type.Optional(
|
|
39
|
+
Type.Object(
|
|
40
|
+
{
|
|
41
|
+
policy: Type.Optional(
|
|
42
|
+
Type.Union([
|
|
43
|
+
Type.Literal("never"),
|
|
44
|
+
Type.Literal("always"),
|
|
45
|
+
Type.Literal("when-missing"),
|
|
46
|
+
]),
|
|
47
|
+
),
|
|
48
|
+
model: Type.Optional(Type.String()),
|
|
49
|
+
thinking: Type.Optional(ThinkingLevelSchema),
|
|
50
|
+
},
|
|
51
|
+
{ additionalProperties: false },
|
|
52
|
+
),
|
|
53
|
+
),
|
|
54
|
+
},
|
|
55
|
+
{ additionalProperties: false },
|
|
56
|
+
),
|
|
57
|
+
),
|
|
25
58
|
},
|
|
26
59
|
{ additionalProperties: false },
|
|
27
60
|
);
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { ThinkingLevel } from "../model/index.ts";
|
|
1
2
|
import { type ConfigLayer, readConfigLayer } from "./config-file.ts";
|
|
2
3
|
import {
|
|
3
4
|
type ConfigEnvironment,
|
|
@@ -5,6 +6,28 @@ import {
|
|
|
5
6
|
resolveGlobalConfigPath,
|
|
6
7
|
} from "./config-paths.ts";
|
|
7
8
|
|
|
9
|
+
/** When the fork summarizer runs for one Agent Question (ADR-0022). */
|
|
10
|
+
export type QuestionSummaryPolicy = "never" | "always" | "when-missing";
|
|
11
|
+
|
|
12
|
+
/** The resolved `askUser.summary` block; every default is already applied. */
|
|
13
|
+
export interface QuestionSummaryConfig {
|
|
14
|
+
readonly policy: QuestionSummaryPolicy;
|
|
15
|
+
/** Model pattern for the summarizer; absent means the parked Agent's own model. */
|
|
16
|
+
readonly model?: string;
|
|
17
|
+
readonly thinking: ThinkingLevel;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** Reads the Question Summary settings of one config, defaults included. */
|
|
21
|
+
export function questionSummaryOf(config: EffectiveConfig | undefined): QuestionSummaryConfig {
|
|
22
|
+
return config?.askUserSummary ?? DEFAULT_QUESTION_SUMMARY;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** The Question Summary settings of a Run that configured none. */
|
|
26
|
+
export const DEFAULT_QUESTION_SUMMARY: QuestionSummaryConfig = Object.freeze({
|
|
27
|
+
policy: "when-missing" as const,
|
|
28
|
+
thinking: "low" as const,
|
|
29
|
+
});
|
|
30
|
+
|
|
8
31
|
/** Which of the three layers a config value came from. */
|
|
9
32
|
export type ConfigLayerName = "global" | "project" | "run";
|
|
10
33
|
|
|
@@ -30,6 +53,12 @@ export interface EffectiveConfig {
|
|
|
30
53
|
* when no layer stated one.
|
|
31
54
|
*/
|
|
32
55
|
readonly profile?: string;
|
|
56
|
+
/**
|
|
57
|
+
* Resolved Question Summary settings (ADR-0022). Optional on purpose: an
|
|
58
|
+
* `EffectiveConfig` built outside this module stays valid, and every reader
|
|
59
|
+
* goes through `questionSummaryOf`, which applies the defaults.
|
|
60
|
+
*/
|
|
61
|
+
readonly askUserSummary?: QuestionSummaryConfig;
|
|
33
62
|
}
|
|
34
63
|
|
|
35
64
|
/** What to discover and read. */
|
|
@@ -48,6 +77,7 @@ export interface EffectiveConfigRequest {
|
|
|
48
77
|
export const EMPTY_EFFECTIVE_CONFIG: EffectiveConfig = Object.freeze({
|
|
49
78
|
extensions: Object.freeze([]) as readonly ConfigExtension[],
|
|
50
79
|
files: Object.freeze([]) as readonly string[],
|
|
80
|
+
askUserSummary: DEFAULT_QUESTION_SUMMARY,
|
|
51
81
|
});
|
|
52
82
|
|
|
53
83
|
interface LoadedLayer {
|
|
@@ -123,5 +153,28 @@ function mergeLayers(found: readonly LoadedLayer[]): EffectiveConfig {
|
|
|
123
153
|
extensions: Object.freeze(extensions),
|
|
124
154
|
files: Object.freeze(found.map(({ layer }) => layer.file)),
|
|
125
155
|
...(profile === undefined ? {} : { profile }),
|
|
156
|
+
askUserSummary: mergeQuestionSummary(found),
|
|
157
|
+
});
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/** Last-layer-wins per key, exactly like `profile`; it never concatenates. */
|
|
161
|
+
function mergeQuestionSummary(found: readonly LoadedLayer[]): QuestionSummaryConfig {
|
|
162
|
+
const merged = found.reduce<{
|
|
163
|
+
policy?: QuestionSummaryPolicy;
|
|
164
|
+
model?: string;
|
|
165
|
+
thinking?: ThinkingLevel;
|
|
166
|
+
}>((last, { layer }) => {
|
|
167
|
+
const summary = layer.document.askUser?.summary;
|
|
168
|
+
if (summary === undefined) return last;
|
|
169
|
+
return {
|
|
170
|
+
policy: summary.policy ?? last.policy,
|
|
171
|
+
model: summary.model ?? last.model,
|
|
172
|
+
thinking: summary.thinking ?? last.thinking,
|
|
173
|
+
};
|
|
174
|
+
}, {});
|
|
175
|
+
return Object.freeze({
|
|
176
|
+
policy: merged.policy ?? DEFAULT_QUESTION_SUMMARY.policy,
|
|
177
|
+
...(merged.model === undefined ? {} : { model: merged.model }),
|
|
178
|
+
thinking: merged.thinking ?? DEFAULT_QUESTION_SUMMARY.thinking,
|
|
126
179
|
});
|
|
127
180
|
}
|
package/src/config/index.ts
CHANGED
|
@@ -16,8 +16,12 @@ export type { YaagConfigDocument } from "./config-schema.ts";
|
|
|
16
16
|
export {
|
|
17
17
|
type ConfigExtension,
|
|
18
18
|
type ConfigLayerName,
|
|
19
|
+
DEFAULT_QUESTION_SUMMARY,
|
|
19
20
|
type EffectiveConfig,
|
|
20
21
|
type EffectiveConfigRequest,
|
|
21
22
|
EMPTY_EFFECTIVE_CONFIG,
|
|
22
23
|
loadEffectiveConfig,
|
|
24
|
+
type QuestionSummaryConfig,
|
|
25
|
+
type QuestionSummaryPolicy,
|
|
26
|
+
questionSummaryOf,
|
|
23
27
|
} from "./effective-config.ts";
|
|
@@ -84,6 +84,15 @@ export interface AgentPolicy {
|
|
|
84
84
|
readonly skills?: readonly string[];
|
|
85
85
|
/** Skill-name denylist discovered from pi and applied last (ADR-0026). */
|
|
86
86
|
readonly disallowedSkills?: readonly string[];
|
|
87
|
+
/**
|
|
88
|
+
* Loads yaag's injected `request_user_input` tool, so this Agent can ask the
|
|
89
|
+
* human one question and park its turn on the answer (ADR-0023).
|
|
90
|
+
*
|
|
91
|
+
* The capability is never widened and never dropped in silence: a `tools`
|
|
92
|
+
* allowlist that omits the tool, or a `disallowedTools` that denies it, fails
|
|
93
|
+
* the spawn before the Agent starts.
|
|
94
|
+
*/
|
|
95
|
+
readonly canAskUser?: boolean;
|
|
87
96
|
/**
|
|
88
97
|
* Ask options applied to every Ask on this Agent unless overridden per call.
|
|
89
98
|
* They never enter the recorded spawn options: the Ask hash sees them through
|
|
@@ -55,14 +55,14 @@ export type YaagErrorCode =
|
|
|
55
55
|
| "ARGS_INVALID" // arguments failed schema validation before the Run started
|
|
56
56
|
| "CONFIG_INVALID" // a config layer is missing, unparsable, or violates the schema
|
|
57
57
|
| "OPTIONS_CONFLICT" // incompatible Run options were supplied
|
|
58
|
+
| "PAUSE_REFUSED" // two pause questions claim one id (ADR-0022)
|
|
58
59
|
| "RECORD_PATH_UNUSABLE" // the --record directory could not be created at Run start
|
|
59
60
|
| "REPLAY_DIVERGED" // replayed program differed from its Cassette
|
|
60
|
-
| "RESUME_REFUSED" // resume metadata is absent
|
|
61
|
+
| "RESUME_REFUSED" // resume metadata is absent, the recorded tree moved, or an answer is unknown or conflicting (ADR-0022/0023)
|
|
61
62
|
| "PROFILE_NOT_FOUND" // a selected Profile is not declared by the program (ADR-0052)
|
|
62
63
|
| "PROFILE_REQUIRED" // a Profiled Definition was spawned by a program that declares no Profiles
|
|
63
64
|
| "ROLE_NOT_FOUND" // a factory read a Role the program does not declare
|
|
64
65
|
| "RUN_CLOSED" // spawn or Ask requested after the Run began settling
|
|
65
|
-
| "RUN_PAUSED" // an external pause drain settled the Run (ADR-0024)
|
|
66
66
|
| "RUN_STOPPED" // the Run's abort signal fired before the program completed
|
|
67
67
|
| "WORKTREE_REFUSED" // base cwd is not a clean Git repository
|
|
68
68
|
| "MODEL_RESOLUTION_FAILED" // the resolver gave up, or every candidate failed; carries the history
|
package/src/control/index.ts
CHANGED
|
@@ -16,10 +16,12 @@ export {
|
|
|
16
16
|
} from "./control-commands.ts";
|
|
17
17
|
export {
|
|
18
18
|
type AskInFlight,
|
|
19
|
+
type AskSettled,
|
|
19
20
|
type DrainableAgent,
|
|
20
21
|
drainForPause,
|
|
21
22
|
type PauseDrainOptions,
|
|
22
23
|
type PauseDrainResult,
|
|
24
|
+
type PauseGrace,
|
|
23
25
|
} from "./pause-drain.ts";
|
|
24
26
|
export {
|
|
25
27
|
type ControlRequest,
|