@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
package/package.json
CHANGED
|
@@ -1,12 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@yaag/runtime",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.26.0",
|
|
4
4
|
"publishConfig": {
|
|
5
5
|
"access": "public"
|
|
6
6
|
},
|
|
7
7
|
"files": [
|
|
8
8
|
"src",
|
|
9
|
-
"!src/**/*.test.ts",
|
|
10
9
|
"!src/fixtures"
|
|
11
10
|
],
|
|
12
11
|
"type": "module",
|
|
@@ -16,7 +15,7 @@
|
|
|
16
15
|
},
|
|
17
16
|
"scripts": {
|
|
18
17
|
"typecheck": "tsc --noEmit",
|
|
19
|
-
"test": "bun test --timeout 30000
|
|
18
|
+
"test": "bun test --timeout 30000 ./test",
|
|
20
19
|
"test:e2e": "bun test --timeout 30000 e2e"
|
|
21
20
|
},
|
|
22
21
|
"dependencies": {
|
package/src/agent/agent.ts
CHANGED
|
@@ -2,10 +2,11 @@ import type { Static, TSchema } from "typebox";
|
|
|
2
2
|
import type { EffectiveAskOptions } from "../ask/index.ts";
|
|
3
3
|
import { exchangeAsk } from "../ask/index.ts";
|
|
4
4
|
import { REPORT_RESULT_WRAP_UP, ReportResultTool, wrapUpMessage } from "../ask-contract/index.ts";
|
|
5
|
-
import type { AskAdmission, AskInFlight } from "../control/index.ts";
|
|
5
|
+
import type { AskAdmission, AskInFlight, AskSettled } from "../control/index.ts";
|
|
6
6
|
import { agentError } from "../error-factories.ts";
|
|
7
7
|
import type { EventSink } from "../events.ts";
|
|
8
8
|
import type { ModelErrorHistory, ModelResolution } from "../model/index.ts";
|
|
9
|
+
import type { AgentQuestions } from "../run/index.ts";
|
|
9
10
|
import type {
|
|
10
11
|
AgentStats,
|
|
11
12
|
AgentTransport,
|
|
@@ -62,6 +63,8 @@ export interface AgentOptions {
|
|
|
62
63
|
readonly stallProbeSettleMs?: number;
|
|
63
64
|
/** Run-scoped Ask gate; a closed gate refuses every later Ask (ADR-0024). */
|
|
64
65
|
readonly askAdmission?: AskAdmission;
|
|
66
|
+
/** Run-scoped sink of Agent questions; absent when this Agent cannot ask (ADR-0023). */
|
|
67
|
+
readonly questions?: AgentQuestions;
|
|
65
68
|
}
|
|
66
69
|
|
|
67
70
|
/** One Agent as an Orchestration Program sees it. Lives above the transport seam. */
|
|
@@ -87,6 +90,7 @@ export class Agent implements Handle {
|
|
|
87
90
|
readonly #sessionFile: string | undefined;
|
|
88
91
|
readonly #fork: ForkSpawner | undefined;
|
|
89
92
|
readonly #askAdmission: AskAdmission | undefined;
|
|
93
|
+
readonly #questions: AgentQuestions | undefined;
|
|
90
94
|
#busy = false;
|
|
91
95
|
#inFlight: AskInFlight | null = null;
|
|
92
96
|
#incomplete = false;
|
|
@@ -113,6 +117,7 @@ export class Agent implements Handle {
|
|
|
113
117
|
this.#idleAbortSettleMs = options.idleAbortSettleMs;
|
|
114
118
|
this.#stallProbeSettleMs = options.stallProbeSettleMs;
|
|
115
119
|
this.#askAdmission = options.askAdmission;
|
|
120
|
+
this.#questions = options.questions;
|
|
116
121
|
this.#usage = new AgentUsage((snapshot) =>
|
|
117
122
|
this.#emit({ type: "agent_usage", agent: this.name, ...snapshot }),
|
|
118
123
|
);
|
|
@@ -124,6 +129,15 @@ export class Agent implements Handle {
|
|
|
124
129
|
return this.#model;
|
|
125
130
|
}
|
|
126
131
|
|
|
132
|
+
/**
|
|
133
|
+
* pi's session file for this Agent; the fork summarizer copies it (ADR-0022).
|
|
134
|
+
* Absent during playback. `Handle` does not carry it: this is Run machinery,
|
|
135
|
+
* not an author surface.
|
|
136
|
+
*/
|
|
137
|
+
get sessionFile(): string | undefined {
|
|
138
|
+
return this.#sessionFile;
|
|
139
|
+
}
|
|
140
|
+
|
|
127
141
|
async ask<Schema extends TSchema>(
|
|
128
142
|
prompt: string,
|
|
129
143
|
options: StructuredAskOptions<Schema>,
|
|
@@ -146,6 +160,8 @@ export class Agent implements Handle {
|
|
|
146
160
|
const inFlight = this.#openInFlight(effective);
|
|
147
161
|
this.#inFlight = inFlight;
|
|
148
162
|
const index = this.#askIndex++;
|
|
163
|
+
// Kept, so the drain sees why an Ask left flight and can warn about it.
|
|
164
|
+
let failure: unknown;
|
|
149
165
|
try {
|
|
150
166
|
return await exchangeAsk({
|
|
151
167
|
agent: this.name,
|
|
@@ -175,11 +191,17 @@ export class Agent implements Handle {
|
|
|
175
191
|
askLimitGraceMs: this.#askLimitGraceMs,
|
|
176
192
|
idleAbortSettleMs: this.#idleAbortSettleMs,
|
|
177
193
|
stallProbeSettleMs: this.#stallProbeSettleMs,
|
|
194
|
+
...(this.#questions === undefined
|
|
195
|
+
? {}
|
|
196
|
+
: { questions: this.#questions, park: () => inFlight.park() }),
|
|
178
197
|
});
|
|
198
|
+
} catch (error) {
|
|
199
|
+
failure = error;
|
|
200
|
+
throw error;
|
|
179
201
|
} finally {
|
|
180
202
|
this.#busy = false;
|
|
181
203
|
this.#inFlight = null;
|
|
182
|
-
inFlight.settle();
|
|
204
|
+
inFlight.settle(failure);
|
|
183
205
|
// A failed Ask settles the conversation as much as a successful one: the
|
|
184
206
|
// fork point is the boundary, not the outcome.
|
|
185
207
|
this.#settledAsks += 1;
|
|
@@ -198,10 +220,20 @@ export class Agent implements Handle {
|
|
|
198
220
|
* Builds the drain's controls of one Ask. Both commands report a refusal as
|
|
199
221
|
* false and never throw, so a dead Agent cannot throw into the drain.
|
|
200
222
|
*/
|
|
201
|
-
#openInFlight(
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
223
|
+
#openInFlight(
|
|
224
|
+
ask: EffectiveAskOptions,
|
|
225
|
+
): AskInFlight & { settle(error?: unknown): void; park(): void } {
|
|
226
|
+
let settle: (error?: unknown) => void = () => {};
|
|
227
|
+
// A getter, not a snapshot: the drain reads `parked` at its start and again
|
|
228
|
+
// when it aborts what remains, and an Ask may park between the two. The
|
|
229
|
+
// signal covers the drain that is already waiting (ADR-0023).
|
|
230
|
+
let parked = false;
|
|
231
|
+
let raiseParked: () => void = () => {};
|
|
232
|
+
const parkedSignal = new Promise<void>((resolve) => {
|
|
233
|
+
raiseParked = resolve;
|
|
234
|
+
});
|
|
235
|
+
const settled = new Promise<AskSettled>((resolve) => {
|
|
236
|
+
settle = (error?: unknown) => resolve(error === undefined ? {} : { error });
|
|
205
237
|
});
|
|
206
238
|
// A structured Ask keeps reporting through report_result, so its wrap-up
|
|
207
239
|
// carries the same suffix the soft-budget path uses (ADR-0032). Legacy
|
|
@@ -218,6 +250,14 @@ export class Agent implements Handle {
|
|
|
218
250
|
agent: this.name,
|
|
219
251
|
settled,
|
|
220
252
|
settle,
|
|
253
|
+
get parked(): boolean {
|
|
254
|
+
return parked;
|
|
255
|
+
},
|
|
256
|
+
parkedSignal,
|
|
257
|
+
park: (): void => {
|
|
258
|
+
parked = true;
|
|
259
|
+
raiseParked();
|
|
260
|
+
},
|
|
221
261
|
wrapUp: () => send({ type: "steer", message: wrapUpMessage(ask, suffix) }),
|
|
222
262
|
abort: () => send({ type: "abort" }),
|
|
223
263
|
};
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The fail-fast guard of the `canAskUser` capability (ADR-0023).
|
|
3
|
+
*
|
|
4
|
+
* The `report_result` precedent is deliberately inverted here: that allowlist
|
|
5
|
+
* widens itself in silence, this one does not. An Agent that may ask its human
|
|
6
|
+
* and whose tool flags remove the tool has a contradiction in its policy, so
|
|
7
|
+
* the spawn fails rather than losing the capability without a word.
|
|
8
|
+
*/
|
|
9
|
+
import { REQUEST_USER_INPUT_TOOL_NAME } from "../ask-contract/index.ts";
|
|
10
|
+
import { YaagError } from "../errors.ts";
|
|
11
|
+
|
|
12
|
+
/** The tool flags of one spawn, as this guard reads them. */
|
|
13
|
+
export interface AskUserToolFlags {
|
|
14
|
+
readonly canAskUser?: boolean;
|
|
15
|
+
readonly tools?: readonly string[];
|
|
16
|
+
readonly disallowedTools?: readonly string[];
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/** Rejects a spawn whose tool flags remove the tool `canAskUser` needs. */
|
|
20
|
+
export function assertAskUserTools(agent: string, options: AskUserToolFlags): void {
|
|
21
|
+
if (options.canAskUser !== true) return;
|
|
22
|
+
if (options.disallowedTools?.includes(REQUEST_USER_INPUT_TOOL_NAME) === true) {
|
|
23
|
+
throw refuse(agent, "and disallowedTools denies it");
|
|
24
|
+
}
|
|
25
|
+
if (options.tools !== undefined && !options.tools.includes(REQUEST_USER_INPUT_TOOL_NAME)) {
|
|
26
|
+
throw refuse(agent, "and the tools allowlist omits it");
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
function refuse(agent: string, cause: string): YaagError {
|
|
31
|
+
return new YaagError(
|
|
32
|
+
"SPAWN_FAILED",
|
|
33
|
+
`agent "${agent}": canAskUser needs the tool "${REQUEST_USER_INPUT_TOOL_NAME}", ${cause}`,
|
|
34
|
+
agent,
|
|
35
|
+
);
|
|
36
|
+
}
|
package/src/agent/index.ts
CHANGED
|
@@ -13,5 +13,6 @@ export {
|
|
|
13
13
|
isAgentDefinition,
|
|
14
14
|
} from "./define-agent.ts";
|
|
15
15
|
export { type ForkSource, type ForkSpawner, forkRequest } from "./fork.ts";
|
|
16
|
-
export { makeSpawn } from "./spawn.ts";
|
|
16
|
+
export { makeSpawn, type SpawnDependencies, type SpawnGate } from "./spawn.ts";
|
|
17
|
+
export type { OpenAgentRequest } from "./spawn-open.ts";
|
|
17
18
|
export { isSpawnableDefinition } from "./spawnable-definition.ts";
|
package/src/agent/spawn-open.ts
CHANGED
|
@@ -13,9 +13,10 @@ import type {
|
|
|
13
13
|
TransportStartup,
|
|
14
14
|
WorktreeResolution,
|
|
15
15
|
} from "../transport/index.ts";
|
|
16
|
-
import type { AskOptions,
|
|
16
|
+
import type { AskOptions, ResolvedSpawnOptions, SpawnOptions } from "../types.ts";
|
|
17
17
|
import { Agent } from "./agent.ts";
|
|
18
18
|
import { uniqueAgentName } from "./agent-names.ts";
|
|
19
|
+
import { assertAskUserTools } from "./ask-user-capability.ts";
|
|
19
20
|
import type { ForkIdentity, ForkSpawner } from "./fork.ts";
|
|
20
21
|
import type { SpawnDependencies } from "./spawn.ts";
|
|
21
22
|
import { resolveSpawnExtensions } from "./spawn-extensions.ts";
|
|
@@ -48,6 +49,11 @@ export interface OpenAgentRequest {
|
|
|
48
49
|
readonly profile?: string;
|
|
49
50
|
/** Roles the factory read, in order, duplicates kept; `[]` for none. */
|
|
50
51
|
readonly role?: readonly string[];
|
|
52
|
+
/**
|
|
53
|
+
* An existing pi session this Agent opens on (`pi --session`). Never spawn
|
|
54
|
+
* identity: the path is machine-specific (ADR-0022).
|
|
55
|
+
*/
|
|
56
|
+
readonly sessionFile?: string;
|
|
51
57
|
}
|
|
52
58
|
|
|
53
59
|
/** What the open path needs beyond the Run's spawn dependencies. */
|
|
@@ -65,11 +71,12 @@ export interface OpenAgentContext extends SpawnDependencies {
|
|
|
65
71
|
* A fork walks this very path, so the Tool Contract probe, Model Resolution,
|
|
66
72
|
* the worktree wrapper and the Cassette identity cannot drift between a spawn
|
|
67
73
|
* and a fork (ADR-0044).
|
|
74
|
+
*
|
|
75
|
+
* It resolves with the concrete `Agent`, not with the author-facing `Handle`:
|
|
76
|
+
* the Run's own machinery reaps what it opens, and `close()` lives below the
|
|
77
|
+
* author surface (ADR-0022).
|
|
68
78
|
*/
|
|
69
|
-
export async function openAgent(
|
|
70
|
-
deps: OpenAgentContext,
|
|
71
|
-
request: OpenAgentRequest,
|
|
72
|
-
): Promise<Handle> {
|
|
79
|
+
export async function openAgent(deps: OpenAgentContext, request: OpenAgentRequest): Promise<Agent> {
|
|
73
80
|
const cwd = resolve(request.spawnOptions.cwd ?? process.cwd());
|
|
74
81
|
const name = uniqueAgentName(request.spawnOptions.name, deps.agents.length, deps.taken);
|
|
75
82
|
// Resolved before any transport work, so a bad Parent Link costs nothing.
|
|
@@ -86,6 +93,9 @@ export async function openAgent(
|
|
|
86
93
|
agent: { name, runName: deps.runName },
|
|
87
94
|
...(request.inheritedPrompt === true ? { inheritedPrompt: true } : {}),
|
|
88
95
|
});
|
|
96
|
+
// A policy that both asks its human and removes the tool is a contradiction:
|
|
97
|
+
// it fails here, before any I/O and before the Agent starts (ADR-0023).
|
|
98
|
+
assertAskUserTools(name, rendered);
|
|
89
99
|
// Extension paths do not vary per candidate, so a bad path fails once, generically.
|
|
90
100
|
const extensions = await resolveSpawnExtensions({
|
|
91
101
|
configExtensions: deps.configExtensions,
|
|
@@ -133,6 +143,7 @@ export async function openAgent(
|
|
|
133
143
|
...forkFields,
|
|
134
144
|
...(parent === undefined ? {} : { parent }),
|
|
135
145
|
sessionDir: deps.sessionDir,
|
|
146
|
+
...(request.sessionFile === undefined ? {} : { sessionFile: request.sessionFile }),
|
|
136
147
|
}),
|
|
137
148
|
spawnOptions: settled,
|
|
138
149
|
};
|
|
@@ -149,6 +160,7 @@ export async function openAgent(
|
|
|
149
160
|
...forkFields,
|
|
150
161
|
...(parent === undefined ? {} : { parent }),
|
|
151
162
|
sessionDir: deps.sessionDir,
|
|
163
|
+
...(request.sessionFile === undefined ? {} : { sessionFile: request.sessionFile }),
|
|
152
164
|
}),
|
|
153
165
|
);
|
|
154
166
|
// A Cassette-backed spawn adopts the recorded resolved selection and skips
|
|
@@ -191,6 +203,10 @@ export async function openAgent(
|
|
|
191
203
|
...(sessionFile === undefined ? {} : { sessionFile }),
|
|
192
204
|
fork: deps.forkSpawner,
|
|
193
205
|
...(deps.askAdmission === undefined ? {} : { askAdmission: deps.askAdmission }),
|
|
206
|
+
// Only an Agent that may ask gets the sink, so no other Ask can park.
|
|
207
|
+
...(deps.questions === undefined || rendered.canAskUser !== true
|
|
208
|
+
? {}
|
|
209
|
+
: { questions: deps.questions }),
|
|
194
210
|
...(request.askDefaults === undefined ? {} : { askDefaults: request.askDefaults }),
|
|
195
211
|
...(request.definitionName === undefined ? {} : { definitionName: request.definitionName }),
|
|
196
212
|
});
|
|
@@ -242,6 +258,8 @@ interface OpenTransportOptions {
|
|
|
242
258
|
readonly forkSession?: string;
|
|
243
259
|
readonly worktreeFrom?: WorktreeResolution;
|
|
244
260
|
readonly sessionDir: string | undefined;
|
|
261
|
+
/** An existing pi session to open on; never spawn identity (ADR-0022). */
|
|
262
|
+
readonly sessionFile?: string;
|
|
245
263
|
}
|
|
246
264
|
|
|
247
265
|
interface OpenedTransport {
|
|
@@ -271,6 +289,7 @@ async function openTransport(options: OpenTransportOptions): Promise<OpenedTrans
|
|
|
271
289
|
...(options.forkSession === undefined ? {} : { forkSession: options.forkSession }),
|
|
272
290
|
...(options.worktreeFrom === undefined ? {} : { worktreeFrom: options.worktreeFrom }),
|
|
273
291
|
sessionDir: options.sessionDir,
|
|
292
|
+
...(options.sessionFile === undefined ? {} : { sessionFile: options.sessionFile }),
|
|
274
293
|
}),
|
|
275
294
|
(report) => Object.assign(startup, report),
|
|
276
295
|
);
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { REQUEST_USER_INPUT_PROTOCOL } from "../ask-contract/index.ts";
|
|
1
2
|
import type { SystemPromptAgent } from "../contract/index.ts";
|
|
2
3
|
import { YaagError } from "../errors.ts";
|
|
3
4
|
import type { ModelSelection } from "../model/index.ts";
|
|
@@ -111,6 +112,12 @@ export interface OpenRequestOptions {
|
|
|
111
112
|
readonly forkSession?: string;
|
|
112
113
|
readonly worktreeFrom?: WorktreeResolution;
|
|
113
114
|
readonly sessionDir: string | undefined;
|
|
115
|
+
/**
|
|
116
|
+
* An existing pi session to open on, translated to `pi --session <path>`.
|
|
117
|
+
* Never spawn identity: the path is machine-specific, exactly like
|
|
118
|
+
* `forkSession`. The fork summarizer opens on a copy this way (ADR-0022).
|
|
119
|
+
*/
|
|
120
|
+
readonly sessionFile?: string;
|
|
114
121
|
}
|
|
115
122
|
|
|
116
123
|
/**
|
|
@@ -157,7 +164,11 @@ export function openRequest(options: OpenRequestOptions): OpenOptions {
|
|
|
157
164
|
...(model === undefined ? {} : { model }),
|
|
158
165
|
systemPrompt:
|
|
159
166
|
spawnOptions.systemPrompt ??
|
|
160
|
-
yaagSystemPrompt({
|
|
167
|
+
yaagSystemPrompt({
|
|
168
|
+
agent: { name: options.name, runName: options.runName },
|
|
169
|
+
// An Agent that may ask its human reads the audience line (ADR-0062).
|
|
170
|
+
...(spawnOptions.canAskUser === true ? { audience: "user" as const } : {}),
|
|
171
|
+
}),
|
|
161
172
|
...(thinking === undefined ? {} : { thinking }),
|
|
162
173
|
...(spawnOptions.appendSystemPrompt === undefined
|
|
163
174
|
? {}
|
|
@@ -167,6 +178,11 @@ export function openRequest(options: OpenRequestOptions): OpenOptions {
|
|
|
167
178
|
...(spawnOptions.disallowedTools === undefined
|
|
168
179
|
? {}
|
|
169
180
|
: { disallowedTools: spawnOptions.disallowedTools }),
|
|
181
|
+
// Both fields stay absent for an Agent that cannot ask, so every recorded
|
|
182
|
+
// spawn identity from before ADR-0023 is unchanged.
|
|
183
|
+
...(spawnOptions.canAskUser === true
|
|
184
|
+
? { canAskUser: true as const, askUserProtocol: REQUEST_USER_INPUT_PROTOCOL }
|
|
185
|
+
: {}),
|
|
170
186
|
...(spawnOptions.skills === undefined ? {} : { skills: spawnOptions.skills }),
|
|
171
187
|
...(spawnOptions.disallowedSkills === undefined
|
|
172
188
|
? {}
|
|
@@ -187,6 +203,7 @@ export function openRequest(options: OpenRequestOptions): OpenOptions {
|
|
|
187
203
|
...(options.worktreeFrom === undefined ? {} : { worktreeFrom: options.worktreeFrom }),
|
|
188
204
|
...(spawnOptions.worktree === true ? { worktree: true as const } : {}),
|
|
189
205
|
...(options.sessionDir === undefined ? {} : { sessionDir: options.sessionDir }),
|
|
206
|
+
...(options.sessionFile === undefined ? {} : { sessionFile: options.sessionFile }),
|
|
190
207
|
};
|
|
191
208
|
}
|
|
192
209
|
|
package/src/agent/spawn.ts
CHANGED
|
@@ -4,14 +4,14 @@ import { YaagError } from "../errors.ts";
|
|
|
4
4
|
import type { EventSink } from "../events.ts";
|
|
5
5
|
import type { ActiveProfile, ProfiledDefinition } from "../profile/index.ts";
|
|
6
6
|
import { isProfiledDefinition } from "../profile/index.ts";
|
|
7
|
-
import type { RunContext } from "../run/index.ts";
|
|
7
|
+
import type { AgentQuestions, RunContext } from "../run/index.ts";
|
|
8
8
|
import type { TransportFactory } from "../transport/index.ts";
|
|
9
9
|
import type { Handle, SpawnOptions, SpawnOverrides } from "../types.ts";
|
|
10
10
|
import type { Agent } from "./agent.ts";
|
|
11
11
|
import { type AgentDefinition, isAgentDefinition } from "./define-agent.ts";
|
|
12
12
|
import { type ForkSpawner, forkRequest } from "./fork.ts";
|
|
13
13
|
import { resolveRequest } from "./spawn-definition-request.ts";
|
|
14
|
-
import { type OpenAgentContext, openAgent } from "./spawn-open.ts";
|
|
14
|
+
import { type OpenAgentContext, type OpenAgentRequest, openAgent } from "./spawn-open.ts";
|
|
15
15
|
import { profiledRequest } from "./spawn-profiled.ts";
|
|
16
16
|
|
|
17
17
|
/** Dependencies for one Run's Agent-spawn gate. */
|
|
@@ -29,11 +29,22 @@ export interface SpawnDependencies {
|
|
|
29
29
|
readonly profile?: ActiveProfile;
|
|
30
30
|
/** Run-scoped Ask gate handed to every Agent this gate opens (ADR-0024). */
|
|
31
31
|
readonly askAdmission?: AskAdmission;
|
|
32
|
+
/** Run-scoped sink of the questions an Agent asks its human (ADR-0023). */
|
|
33
|
+
readonly questions?: AgentQuestions;
|
|
32
34
|
}
|
|
33
35
|
|
|
34
36
|
/** A RunContext spawn function that can synchronously stop accepting new Agents. */
|
|
35
37
|
export interface SpawnGate {
|
|
36
38
|
readonly spawn: RunContext["spawn"];
|
|
39
|
+
/**
|
|
40
|
+
* Opens one Agent for the Run's own machinery, after the gate closed.
|
|
41
|
+
*
|
|
42
|
+
* The closed flag is ignored on purpose: the fork summarizer runs after
|
|
43
|
+
* settlement, when the author-facing gate must already refuse (ADR-0022).
|
|
44
|
+
* The opened Agent gets neither the Run's Ask admission — which is closed by
|
|
45
|
+
* then — nor its Agent-question sink, so it can neither be refused nor park.
|
|
46
|
+
*/
|
|
47
|
+
readonly openInternal: (request: OpenAgentRequest) => Promise<Agent>;
|
|
37
48
|
close(): void;
|
|
38
49
|
}
|
|
39
50
|
|
|
@@ -65,6 +76,10 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
|
|
|
65
76
|
return handle;
|
|
66
77
|
};
|
|
67
78
|
const context: OpenAgentContext = { ...deps, taken, forkSpawner };
|
|
79
|
+
// Same open path, minus the two Run-scoped gates: `askAdmission` and
|
|
80
|
+
// `questions` are dropped rather than overridden, so nothing can re-add them.
|
|
81
|
+
const { askAdmission: _askAdmission, questions: _questions, ...ungated } = deps;
|
|
82
|
+
const internalContext: OpenAgentContext = { ...ungated, taken, forkSpawner };
|
|
68
83
|
const spawn: RunContext["spawn"] = async (
|
|
69
84
|
definitionOrOptions: SpawnOptions | AgentDefinition | ProfiledDefinition = {},
|
|
70
85
|
overrides?: SpawnOverrides,
|
|
@@ -82,6 +97,10 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
|
|
|
82
97
|
};
|
|
83
98
|
return {
|
|
84
99
|
spawn,
|
|
100
|
+
// The concrete Agent, not a Handle: the Run reaps its own machinery itself,
|
|
101
|
+
// and `close()` lives below the author surface.
|
|
102
|
+
openInternal: (request: OpenAgentRequest): Promise<Agent> =>
|
|
103
|
+
openAgent(internalContext, request),
|
|
85
104
|
close: (): void => {
|
|
86
105
|
closed = true;
|
|
87
106
|
},
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type { ReportResultTool } from "../ask-contract/index.ts";
|
|
2
2
|
import type { EventSink } from "../events.ts";
|
|
3
3
|
import type { ModelErrorHistory, ModelResolution } from "../model/index.ts";
|
|
4
|
+
import type { AgentQuestions } from "../run/index.ts";
|
|
4
5
|
import type { AgentTransport, Connection, Frame } from "../transport/index.ts";
|
|
5
6
|
import type { ResolvedSpawnOptions } from "../types.ts";
|
|
6
7
|
import type { EffectiveAskOptions } from "./ask-hash.ts";
|
|
@@ -46,4 +47,8 @@ export interface AskExchangeOptions {
|
|
|
46
47
|
readonly idleAbortSettleMs: number | undefined;
|
|
47
48
|
/** Test-only override for the bounded wait for the Stall Watchdog probe. */
|
|
48
49
|
readonly stallProbeSettleMs: number | undefined;
|
|
50
|
+
/** Records one parked question and raises the Run pause; absent when the Agent cannot ask. */
|
|
51
|
+
readonly questions?: AgentQuestions;
|
|
52
|
+
/** Marks this Ask parked, so the pause drain skips it (ADR-0022 §3, ADR-0023). */
|
|
53
|
+
readonly park?: () => void;
|
|
49
54
|
}
|
package/src/ask/ask-exchange.ts
CHANGED
|
@@ -6,6 +6,7 @@ import {
|
|
|
6
6
|
REPORT_RESULT_WRAP_UP,
|
|
7
7
|
ReportResultCall,
|
|
8
8
|
ReportResultSteering,
|
|
9
|
+
readQuestionFrame,
|
|
9
10
|
resolvePlaybackAskOutput,
|
|
10
11
|
resolvePlaybackReportedResult,
|
|
11
12
|
} from "../ask-contract/index.ts";
|
|
@@ -13,7 +14,7 @@ import { agentError, askLimitError, askStalledError } from "../error-factories.t
|
|
|
13
14
|
import { type AskLimitOutcome, type AskStalledOutcome, isYaagError } from "../errors.ts";
|
|
14
15
|
import { retryOnModelFailure, swapModel } from "../model/index.ts";
|
|
15
16
|
import { NodeTracker } from "../node/index.ts";
|
|
16
|
-
import type { AskPlayback } from "../transport/index.ts";
|
|
17
|
+
import type { AskPlayback, Frame } from "../transport/index.ts";
|
|
17
18
|
import { FrameGapTracker } from "../transport/index.ts";
|
|
18
19
|
import { AskActivityTracker } from "./ask-activity.ts";
|
|
19
20
|
import { type AskEndOutcome, AskEvents } from "./ask-exchange-events.ts";
|
|
@@ -58,6 +59,13 @@ class AskExchange {
|
|
|
58
59
|
#onSettled: () => void = () => {};
|
|
59
60
|
#controlFailure: Promise<never> = new Promise<never>(() => {});
|
|
60
61
|
#timeoutDeadline: number | undefined;
|
|
62
|
+
#isParked = false;
|
|
63
|
+
/** The parked `request_user_input` call of this Ask, when it parked (ADR-0021). */
|
|
64
|
+
#parkedCall: { readonly toolCallId: string; readonly questionId: string } | undefined;
|
|
65
|
+
#resolveParked: () => void = () => {};
|
|
66
|
+
readonly #parked: Promise<void> = new Promise<void>((resolve) => {
|
|
67
|
+
this.#resolveParked = resolve;
|
|
68
|
+
});
|
|
61
69
|
#maxFrameGapMs: number | undefined;
|
|
62
70
|
#cause: SettlementCause = "normal";
|
|
63
71
|
#drainStaleFrames = false;
|
|
@@ -180,6 +188,7 @@ class AskExchange {
|
|
|
180
188
|
});
|
|
181
189
|
this.#began = true;
|
|
182
190
|
this.#playback = playback;
|
|
191
|
+
if (playback?.parked !== undefined) this.#reopenParked(playback.parked);
|
|
183
192
|
// `timeoutMs` is the Ask's hard ceiling and kills the Agent (ADR-0003), so
|
|
184
193
|
// it is Ask-scoped: retries share one deadline, unlike the soft limits.
|
|
185
194
|
this.#timeoutDeadline = this.#deadline();
|
|
@@ -292,6 +301,7 @@ class AskExchange {
|
|
|
292
301
|
this.#options.connection.observe((frame) => {
|
|
293
302
|
this.#turn.observe(frame);
|
|
294
303
|
this.#limit?.observe(frame);
|
|
304
|
+
this.#observeQuestion(frame);
|
|
295
305
|
if (frame.type !== "agent_settled" || this.#idle?.tripped) this.#idle?.observe(frame);
|
|
296
306
|
this.#stall?.observe(frame);
|
|
297
307
|
this.#gap?.observe();
|
|
@@ -313,6 +323,53 @@ class AskExchange {
|
|
|
313
323
|
});
|
|
314
324
|
}
|
|
315
325
|
|
|
326
|
+
/**
|
|
327
|
+
* Parks this Ask on one `request_user_input` call (ADR-0023).
|
|
328
|
+
*
|
|
329
|
+
* Order matters: every budget suspends before the question is raised, so no
|
|
330
|
+
* limit can trip between the two. First signal wins, so an Ask whose limit
|
|
331
|
+
* already tripped keeps its ASK_LIMIT and raises nothing. Replay never parks.
|
|
332
|
+
*/
|
|
333
|
+
#observeQuestion(frame: Frame): void {
|
|
334
|
+
if (this.#playback !== undefined || this.#options.questions === undefined) return;
|
|
335
|
+
if (this.#isParked) return;
|
|
336
|
+
const call = readQuestionFrame(frame);
|
|
337
|
+
if (call === null) return;
|
|
338
|
+
if (this.#limit?.tripped === true) return;
|
|
339
|
+
this.#isParked = true;
|
|
340
|
+
this.#limit?.suspend();
|
|
341
|
+
this.#idle?.suspend();
|
|
342
|
+
this.#stall?.suspend();
|
|
343
|
+
// Suspends the Ask's hard timeout: the wait is the human's from here.
|
|
344
|
+
this.#resolveParked();
|
|
345
|
+
this.#options.park?.();
|
|
346
|
+
const questionId = this.#options.questions.raise({ agent: this.#options.agent, ...call });
|
|
347
|
+
// The incomplete-Ask marker of the artifact: this Ask has no settlement,
|
|
348
|
+
// and the Question it waits for names the way back (ADR-0021/0023).
|
|
349
|
+
this.#parkedCall = { toolCallId: call.toolCallId, questionId };
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
/**
|
|
353
|
+
* Re-opens the Question of a recorded parked Ask this resume did not answer
|
|
354
|
+
* (ADR-0023). No live Agent exists, so nothing can park again by itself: the
|
|
355
|
+
* Ask raises the same Question and stays open, and the Run pauses with it.
|
|
356
|
+
*/
|
|
357
|
+
#reopenParked(parked: NonNullable<AskPlayback["parked"]>): void {
|
|
358
|
+
this.#isParked = true;
|
|
359
|
+
this.#resolveParked();
|
|
360
|
+
this.#options.park?.();
|
|
361
|
+
// The registry's own id wins: the Question the Run advertises and the
|
|
362
|
+
// incomplete marker the successor records must name one id (ADR-0022).
|
|
363
|
+
const questionId =
|
|
364
|
+
this.#options.questions?.raise({
|
|
365
|
+
agent: this.#options.agent,
|
|
366
|
+
toolCallId: parked.toolCallId,
|
|
367
|
+
question: parked.question,
|
|
368
|
+
...(parked.context === undefined ? {} : { context: parked.context }),
|
|
369
|
+
}) ?? parked.questionId;
|
|
370
|
+
this.#parkedCall = { toolCallId: parked.toolCallId, questionId };
|
|
371
|
+
}
|
|
372
|
+
|
|
316
373
|
#createControlFailure(): Promise<never> {
|
|
317
374
|
const controls = [
|
|
318
375
|
this.#limit?.failed,
|
|
@@ -387,7 +444,13 @@ class AskExchange {
|
|
|
387
444
|
// A recorded Ask that never settled has no settlement frame to wait for.
|
|
388
445
|
// Waiting for one would reproduce, in replay, the exact stall this
|
|
389
446
|
// watchdog exists to end.
|
|
390
|
-
|
|
447
|
+
// A re-opened parked Ask has no settlement either, and must not surface
|
|
448
|
+
// the recorded outcome: it waits for the human, exactly as it did before.
|
|
449
|
+
if (
|
|
450
|
+
this.#playback?.settles === false &&
|
|
451
|
+
this.#playback.recovered !== true &&
|
|
452
|
+
this.#playback.parked === undefined
|
|
453
|
+
) {
|
|
391
454
|
throw this.#recordedOutcome();
|
|
392
455
|
}
|
|
393
456
|
await awaitAskSettlement({
|
|
@@ -400,6 +463,7 @@ class AskExchange {
|
|
|
400
463
|
controlFailure: this.#controlFailure,
|
|
401
464
|
error: (code, message) => agentError(this.#options.agent, code, message),
|
|
402
465
|
close: this.#options.close,
|
|
466
|
+
parked: this.#parked,
|
|
403
467
|
});
|
|
404
468
|
this.#outcome = this.#playback?.limit ?? this.#limit?.abortOutcome ?? undefined;
|
|
405
469
|
if (this.#outcome !== undefined) throw askLimitError(this.#options.agent, this.#outcome);
|
|
@@ -520,6 +584,7 @@ class AskExchange {
|
|
|
520
584
|
...(this.#stalled === undefined ? {} : { stalled: this.#stalled }),
|
|
521
585
|
...(this.#invalidOutput === undefined ? {} : { invalidOutput: this.#invalidOutput }),
|
|
522
586
|
...(this.#cause === "recovered" ? { recovered: true as const } : {}),
|
|
587
|
+
...(this.#parkedCall === undefined ? {} : { parked: this.#parkedCall }),
|
|
523
588
|
});
|
|
524
589
|
} catch {
|
|
525
590
|
// Recording must not hide the Ask outcome it was observing.
|
|
@@ -7,6 +7,11 @@ export interface AwaitAskSettlementOptions {
|
|
|
7
7
|
readonly controlFailure: Promise<never>;
|
|
8
8
|
readonly error: (code: YaagError["code"], message: string) => YaagError;
|
|
9
9
|
readonly close: () => void;
|
|
10
|
+
/**
|
|
11
|
+
* Resolves when the Ask parks on a user question; the Ask's hard timeout
|
|
12
|
+
* suspends, because the wait is the human's, not the Agent's (ADR-0023).
|
|
13
|
+
*/
|
|
14
|
+
readonly parked?: Promise<void>;
|
|
10
15
|
}
|
|
11
16
|
|
|
12
17
|
/** Waits for one effort's settlement while preserving the Ask-wide timeout and death semantics. */
|
|
@@ -24,6 +29,9 @@ export async function awaitAskSettlement(options: AwaitAskSettlementOptions): Pr
|
|
|
24
29
|
options.timeoutMs,
|
|
25
30
|
);
|
|
26
31
|
});
|
|
32
|
+
void options.parked?.then(() => {
|
|
33
|
+
clearTimeout(timer);
|
|
34
|
+
});
|
|
27
35
|
try {
|
|
28
36
|
await Promise.race([options.settled, death, expiry, options.controlFailure]);
|
|
29
37
|
} catch (error) {
|
package/src/ask/idle-watch.ts
CHANGED
|
@@ -43,6 +43,7 @@ export class IdleWatch {
|
|
|
43
43
|
#killTimer: ReturnType<typeof setTimeout> | undefined;
|
|
44
44
|
#tripped = false;
|
|
45
45
|
#done = false;
|
|
46
|
+
#suspended = false;
|
|
46
47
|
#result: AskStalledOutcome | null = null;
|
|
47
48
|
|
|
48
49
|
constructor(options: IdleWatchOptions) {
|
|
@@ -67,7 +68,7 @@ export class IdleWatch {
|
|
|
67
68
|
|
|
68
69
|
/** Resets the silence timer; after escalation, watches for `agent_settled`. */
|
|
69
70
|
observe(frame: Frame): void {
|
|
70
|
-
if (this.#done) return;
|
|
71
|
+
if (this.#done || this.#suspended) return;
|
|
71
72
|
if (this.#tripped) {
|
|
72
73
|
if (frame.type === "agent_settled") this.#finish(false);
|
|
73
74
|
return;
|
|
@@ -86,6 +87,15 @@ export class IdleWatch {
|
|
|
86
87
|
this.cleanup();
|
|
87
88
|
}
|
|
88
89
|
|
|
90
|
+
/**
|
|
91
|
+
* Suspends the watch while the Ask parks on a user question (ADR-0023). The
|
|
92
|
+
* silence that follows is the human thinking, not a hung Agent.
|
|
93
|
+
*/
|
|
94
|
+
suspend(): void {
|
|
95
|
+
this.#suspended = true;
|
|
96
|
+
this.cleanup();
|
|
97
|
+
}
|
|
98
|
+
|
|
89
99
|
/** Cancels timers on every other Ask exit path. Idempotent. */
|
|
90
100
|
cleanup(): void {
|
|
91
101
|
clearTimeout(this.#idleTimer);
|
|
@@ -120,7 +130,7 @@ export class IdleWatch {
|
|
|
120
130
|
}
|
|
121
131
|
|
|
122
132
|
#trip(): void {
|
|
123
|
-
if (this.#done || this.#tripped) return;
|
|
133
|
+
if (this.#done || this.#suspended || this.#tripped) return;
|
|
124
134
|
this.#tripped = true;
|
|
125
135
|
clearTimeout(this.#idleTimer);
|
|
126
136
|
this.#idleTimer = undefined;
|
|
@@ -63,6 +63,7 @@ export class StallWatchdog {
|
|
|
63
63
|
#probeTimer: ReturnType<typeof setTimeout> | undefined;
|
|
64
64
|
#tripped = false;
|
|
65
65
|
#done = false;
|
|
66
|
+
#suspended = false;
|
|
66
67
|
#cause: SettlementCause = "normal";
|
|
67
68
|
#result: AskStalledOutcome | null = null;
|
|
68
69
|
|
|
@@ -86,7 +87,7 @@ export class StallWatchdog {
|
|
|
86
87
|
|
|
87
88
|
/** Resets the silence timer. Frames that arrive after the probe are ignored. */
|
|
88
89
|
observe(_frame: Frame): void {
|
|
89
|
-
if (this.#done || this.#tripped) return;
|
|
90
|
+
if (this.#done || this.#suspended || this.#tripped) return;
|
|
90
91
|
this.#arm();
|
|
91
92
|
}
|
|
92
93
|
|
|
@@ -100,9 +101,18 @@ export class StallWatchdog {
|
|
|
100
101
|
this.cleanup();
|
|
101
102
|
}
|
|
102
103
|
|
|
104
|
+
/**
|
|
105
|
+
* Suspends the watchdog while the Ask parks on a user question (ADR-0023).
|
|
106
|
+
* The Agent is silent because it waits for the human, which is not a stall.
|
|
107
|
+
*/
|
|
108
|
+
suspend(): void {
|
|
109
|
+
this.#suspended = true;
|
|
110
|
+
this.cleanup();
|
|
111
|
+
}
|
|
112
|
+
|
|
103
113
|
/** Re-arms the timer for a further effort in the same Ask. Inert after a trip. */
|
|
104
114
|
rearm(): void {
|
|
105
|
-
if (this.#done || this.#tripped) return;
|
|
115
|
+
if (this.#done || this.#suspended || this.#tripped) return;
|
|
106
116
|
this.#arm();
|
|
107
117
|
}
|
|
108
118
|
|
|
@@ -135,7 +145,7 @@ export class StallWatchdog {
|
|
|
135
145
|
}
|
|
136
146
|
|
|
137
147
|
#trip(): void {
|
|
138
|
-
if (this.#done || this.#tripped) return;
|
|
148
|
+
if (this.#done || this.#suspended || this.#tripped) return;
|
|
139
149
|
this.#tripped = true;
|
|
140
150
|
clearTimeout(this.#stallTimer);
|
|
141
151
|
this.#stallTimer = undefined;
|