@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/agent/spawn-open.ts
CHANGED
|
@@ -9,23 +9,21 @@ import {
|
|
|
9
9
|
} from "../model/index.ts";
|
|
10
10
|
import type {
|
|
11
11
|
AgentTransport,
|
|
12
|
+
OpenOptions,
|
|
12
13
|
TransportFactory,
|
|
13
14
|
TransportStartup,
|
|
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";
|
|
21
|
+
import { withoutForkVerbs } from "./host-fork.ts";
|
|
20
22
|
import type { SpawnDependencies } from "./spawn.ts";
|
|
21
23
|
import { resolveSpawnExtensions } from "./spawn-extensions.ts";
|
|
22
24
|
import { resolveParent } from "./spawn-parent.ts";
|
|
23
|
-
import {
|
|
24
|
-
|
|
25
|
-
type RenderedSpawnOptions,
|
|
26
|
-
renderPolicyPrompt,
|
|
27
|
-
withSelection,
|
|
28
|
-
} from "./spawn-request.ts";
|
|
25
|
+
import { createSpawnPlan } from "./spawn-plan.ts";
|
|
26
|
+
import { type RenderedSpawnOptions, renderPolicyPrompt } from "./spawn-request.ts";
|
|
29
27
|
|
|
30
28
|
/** One request the open path serves: a plain spawn, or a fork of another Agent. */
|
|
31
29
|
export interface OpenAgentRequest {
|
|
@@ -38,7 +36,7 @@ export interface OpenAgentRequest {
|
|
|
38
36
|
readonly definitionName: string | undefined;
|
|
39
37
|
/** The prompt is a fork's inherited rendered text, not author-written. */
|
|
40
38
|
readonly inheritedPrompt?: boolean;
|
|
41
|
-
/** Present only for a fork;
|
|
39
|
+
/** Present only for a fork; supplies the origin and the `--fork` source. */
|
|
42
40
|
readonly fork?: ForkIdentity;
|
|
43
41
|
/**
|
|
44
42
|
* Id of the active Profile, on a profiled spawn only. It rides the
|
|
@@ -48,6 +46,11 @@ export interface OpenAgentRequest {
|
|
|
48
46
|
readonly profile?: string;
|
|
49
47
|
/** Roles the factory read, in order, duplicates kept; `[]` for none. */
|
|
50
48
|
readonly role?: readonly string[];
|
|
49
|
+
/**
|
|
50
|
+
* An existing pi session this Agent opens on (`pi --session`). Never spawn
|
|
51
|
+
* identity: the path is machine-specific (ADR-0022).
|
|
52
|
+
*/
|
|
53
|
+
readonly sessionFile?: string;
|
|
51
54
|
}
|
|
52
55
|
|
|
53
56
|
/** What the open path needs beyond the Run's spawn dependencies. */
|
|
@@ -65,11 +68,22 @@ export interface OpenAgentContext extends SpawnDependencies {
|
|
|
65
68
|
* A fork walks this very path, so the Tool Contract probe, Model Resolution,
|
|
66
69
|
* the worktree wrapper and the Cassette identity cannot drift between a spawn
|
|
67
70
|
* and a fork (ADR-0044).
|
|
71
|
+
*
|
|
72
|
+
* It resolves with the concrete `Agent`, not with the author-facing `Handle`:
|
|
73
|
+
* the Run's own machinery reaps what it opens, and `close()` lives below the
|
|
74
|
+
* author surface (ADR-0022).
|
|
68
75
|
*/
|
|
69
76
|
export async function openAgent(
|
|
70
77
|
deps: OpenAgentContext,
|
|
71
|
-
|
|
72
|
-
): Promise<
|
|
78
|
+
incoming: OpenAgentRequest,
|
|
79
|
+
): Promise<Agent> {
|
|
80
|
+
// The two fork verbs are read by the spawn gate and stripped here, above the
|
|
81
|
+
// prompt render: `rendered` feeds the peeked request a resume compares with
|
|
82
|
+
// the recorded spawn, so neither key may travel past this line (ADR-0039).
|
|
83
|
+
const request: OpenAgentRequest = {
|
|
84
|
+
...incoming,
|
|
85
|
+
spawnOptions: withoutForkVerbs(incoming.spawnOptions),
|
|
86
|
+
};
|
|
73
87
|
const cwd = resolve(request.spawnOptions.cwd ?? process.cwd());
|
|
74
88
|
const name = uniqueAgentName(request.spawnOptions.name, deps.agents.length, deps.taken);
|
|
75
89
|
// Resolved before any transport work, so a bad Parent Link costs nothing.
|
|
@@ -86,6 +100,9 @@ export async function openAgent(
|
|
|
86
100
|
agent: { name, runName: deps.runName },
|
|
87
101
|
...(request.inheritedPrompt === true ? { inheritedPrompt: true } : {}),
|
|
88
102
|
});
|
|
103
|
+
// A policy that both asks its human and removes the tool is a contradiction:
|
|
104
|
+
// it fails here, before any I/O and before the Agent starts (ADR-0023).
|
|
105
|
+
assertAskUserTools(name, rendered);
|
|
89
106
|
// Extension paths do not vary per candidate, so a bad path fails once, generically.
|
|
90
107
|
const extensions = await resolveSpawnExtensions({
|
|
91
108
|
configExtensions: deps.configExtensions,
|
|
@@ -97,60 +114,32 @@ export async function openAgent(
|
|
|
97
114
|
if (error instanceof YaagError) throw error;
|
|
98
115
|
throw new YaagError("SPAWN_FAILED", `agent "${name}": ${String(error)}`, name);
|
|
99
116
|
});
|
|
100
|
-
// One
|
|
101
|
-
// identity cannot drift apart
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
forkOf: request.fork.forkOf,
|
|
115
|
-
forkAsks: request.fork.forkAsks,
|
|
116
|
-
forkSession: request.fork.forkSession,
|
|
117
|
-
...(request.fork.worktreeFrom === undefined
|
|
118
|
-
? {}
|
|
119
|
-
: { worktreeFrom: request.fork.worktreeFrom }),
|
|
120
|
-
};
|
|
117
|
+
// One plan for both open sites, so the launch arguments and the recorded
|
|
118
|
+
// identity cannot drift apart: the peek and every attempt differ only in the
|
|
119
|
+
// settled model and thinking.
|
|
120
|
+
const plan = createSpawnPlan({
|
|
121
|
+
name,
|
|
122
|
+
runName: deps.runName,
|
|
123
|
+
cwd,
|
|
124
|
+
rendered,
|
|
125
|
+
...(extensions === undefined ? {} : { extensions }),
|
|
126
|
+
...(request.fork === undefined ? {} : { fork: request.fork }),
|
|
127
|
+
...(parent === undefined ? {} : { parent }),
|
|
128
|
+
sessionDir: deps.sessionDir,
|
|
129
|
+
...(request.sessionFile === undefined ? {} : { sessionFile: request.sessionFile }),
|
|
130
|
+
});
|
|
121
131
|
const attempt = async (
|
|
122
132
|
selection: ModelSelection,
|
|
123
133
|
): Promise<{ opened: OpenedTransport; spawnOptions: ResolvedSpawnOptions }> => {
|
|
124
|
-
const settled =
|
|
134
|
+
const settled = plan.attempt(selection);
|
|
125
135
|
return {
|
|
126
|
-
opened: await openTransport(
|
|
127
|
-
|
|
128
|
-
name,
|
|
129
|
-
runName: deps.runName,
|
|
130
|
-
cwd,
|
|
131
|
-
spawnOptions: settled,
|
|
132
|
-
...extensionFields,
|
|
133
|
-
...forkFields,
|
|
134
|
-
...(parent === undefined ? {} : { parent }),
|
|
135
|
-
sessionDir: deps.sessionDir,
|
|
136
|
-
}),
|
|
137
|
-
spawnOptions: settled,
|
|
136
|
+
opened: await openTransport(deps.factory, name, settled.request),
|
|
137
|
+
spawnOptions: settled.spawnOptions,
|
|
138
138
|
};
|
|
139
139
|
};
|
|
140
140
|
// The peek must stay in the same synchronous block as the first open: a
|
|
141
141
|
// Cassette-backed factory claims Agents in open order (ADR-0013).
|
|
142
|
-
const recorded = deps.factory.recordedSpawn?.(
|
|
143
|
-
openRequest({
|
|
144
|
-
name,
|
|
145
|
-
runName: deps.runName,
|
|
146
|
-
cwd,
|
|
147
|
-
spawnOptions: rendered,
|
|
148
|
-
...extensionFields,
|
|
149
|
-
...forkFields,
|
|
150
|
-
...(parent === undefined ? {} : { parent }),
|
|
151
|
-
sessionDir: deps.sessionDir,
|
|
152
|
-
}),
|
|
153
|
-
);
|
|
142
|
+
const recorded = deps.factory.recordedSpawn?.(plan.peek());
|
|
154
143
|
// A Cassette-backed spawn adopts the recorded resolved selection and skips
|
|
155
144
|
// the loop, so a replayed Run emits no spawn-time fallback (ADR-0039).
|
|
156
145
|
const adopted =
|
|
@@ -191,6 +180,10 @@ export async function openAgent(
|
|
|
191
180
|
...(sessionFile === undefined ? {} : { sessionFile }),
|
|
192
181
|
fork: deps.forkSpawner,
|
|
193
182
|
...(deps.askAdmission === undefined ? {} : { askAdmission: deps.askAdmission }),
|
|
183
|
+
// Only an Agent that may ask gets the sink, so no other Ask can park.
|
|
184
|
+
...(deps.questions === undefined || rendered.canAskUser !== true
|
|
185
|
+
? {}
|
|
186
|
+
: { questions: deps.questions }),
|
|
194
187
|
...(request.askDefaults === undefined ? {} : { askDefaults: request.askDefaults }),
|
|
195
188
|
...(request.definitionName === undefined ? {} : { definitionName: request.definitionName }),
|
|
196
189
|
});
|
|
@@ -204,7 +197,7 @@ export async function openAgent(
|
|
|
204
197
|
...(sessionFile === undefined ? {} : { sessionFile }),
|
|
205
198
|
...(thinking === undefined ? {} : { thinking }),
|
|
206
199
|
...(parent === undefined ? {} : { parent }),
|
|
207
|
-
...(
|
|
200
|
+
...(plan.origin === undefined ? {} : { origin: plan.origin }),
|
|
208
201
|
...(request.profile === undefined
|
|
209
202
|
? {}
|
|
210
203
|
: { profile: request.profile, role: request.role ?? [] }),
|
|
@@ -226,57 +219,23 @@ function isSpawnFailure(error: unknown): error is YaagError {
|
|
|
226
219
|
return error instanceof YaagError && error.code === "SPAWN_FAILED";
|
|
227
220
|
}
|
|
228
221
|
|
|
229
|
-
interface OpenTransportOptions {
|
|
230
|
-
readonly factory: TransportFactory;
|
|
231
|
-
readonly name: string;
|
|
232
|
-
/** The Run name; the peek and the open must pass the same one (ADR-0013). */
|
|
233
|
-
readonly runName: string;
|
|
234
|
-
readonly cwd: string;
|
|
235
|
-
readonly spawnOptions: ResolvedSpawnOptions;
|
|
236
|
-
readonly resolvedExtensionPaths?: readonly string[];
|
|
237
|
-
readonly declaredExtensions?: readonly string[];
|
|
238
|
-
readonly parent?: string;
|
|
239
|
-
readonly origin?: "fork";
|
|
240
|
-
readonly forkOf?: string;
|
|
241
|
-
readonly forkAsks?: number;
|
|
242
|
-
readonly forkSession?: string;
|
|
243
|
-
readonly worktreeFrom?: WorktreeResolution;
|
|
244
|
-
readonly sessionDir: string | undefined;
|
|
245
|
-
}
|
|
246
|
-
|
|
247
222
|
interface OpenedTransport {
|
|
248
223
|
readonly transport: AgentTransport;
|
|
249
224
|
readonly startup: TransportStartup;
|
|
250
225
|
}
|
|
251
226
|
|
|
252
|
-
|
|
227
|
+
/** Opens one built request, and turns any foreign failure into a spawn failure. */
|
|
228
|
+
async function openTransport(
|
|
229
|
+
factory: TransportFactory,
|
|
230
|
+
name: string,
|
|
231
|
+
request: OpenOptions,
|
|
232
|
+
): Promise<OpenedTransport> {
|
|
253
233
|
const startup: TransportStartup = {};
|
|
254
234
|
try {
|
|
255
|
-
const transport = await
|
|
256
|
-
openRequest({
|
|
257
|
-
name: options.name,
|
|
258
|
-
runName: options.runName,
|
|
259
|
-
cwd: options.cwd,
|
|
260
|
-
spawnOptions: options.spawnOptions,
|
|
261
|
-
...(options.resolvedExtensionPaths === undefined
|
|
262
|
-
? {}
|
|
263
|
-
: { resolvedExtensionPaths: options.resolvedExtensionPaths }),
|
|
264
|
-
...(options.declaredExtensions === undefined
|
|
265
|
-
? {}
|
|
266
|
-
: { declaredExtensions: options.declaredExtensions }),
|
|
267
|
-
...(options.parent === undefined ? {} : { parent: options.parent }),
|
|
268
|
-
...(options.origin === undefined ? {} : { origin: options.origin }),
|
|
269
|
-
...(options.forkOf === undefined ? {} : { forkOf: options.forkOf }),
|
|
270
|
-
...(options.forkAsks === undefined ? {} : { forkAsks: options.forkAsks }),
|
|
271
|
-
...(options.forkSession === undefined ? {} : { forkSession: options.forkSession }),
|
|
272
|
-
...(options.worktreeFrom === undefined ? {} : { worktreeFrom: options.worktreeFrom }),
|
|
273
|
-
sessionDir: options.sessionDir,
|
|
274
|
-
}),
|
|
275
|
-
(report) => Object.assign(startup, report),
|
|
276
|
-
);
|
|
235
|
+
const transport = await factory.open(request, (report) => Object.assign(startup, report));
|
|
277
236
|
return { transport, startup };
|
|
278
237
|
} catch (error) {
|
|
279
238
|
if (error instanceof YaagError) throw error;
|
|
280
|
-
throw new YaagError("SPAWN_FAILED", `agent "${
|
|
239
|
+
throw new YaagError("SPAWN_FAILED", `agent "${name}": ${String(error)}`, name);
|
|
281
240
|
}
|
|
282
241
|
}
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Spawn Plan: the one open request built for one spawn.
|
|
3
|
+
*
|
|
4
|
+
* The peek a Cassette-backed factory reads and every model attempt read from
|
|
5
|
+
* this value. Before it, the same field list was spread at three sites and
|
|
6
|
+
* mirrored by a fourth type, and only a comment said the three must agree.
|
|
7
|
+
*/
|
|
8
|
+
import type { SpawnOrigin } from "../events.ts";
|
|
9
|
+
import type { ModelSelection } from "../model/index.ts";
|
|
10
|
+
import type { OpenOptions } from "../transport/index.ts";
|
|
11
|
+
import type { ResolvedSpawnOptions } from "../types.ts";
|
|
12
|
+
import type { ForkIdentity } from "./fork.ts";
|
|
13
|
+
import {
|
|
14
|
+
type OpenRequestOptions,
|
|
15
|
+
openRequest,
|
|
16
|
+
type RenderedSpawnOptions,
|
|
17
|
+
withSelection,
|
|
18
|
+
} from "./spawn-request.ts";
|
|
19
|
+
|
|
20
|
+
/** What one spawn knows before a model settles. */
|
|
21
|
+
export interface SpawnPlanInput {
|
|
22
|
+
readonly name: string;
|
|
23
|
+
readonly runName: string;
|
|
24
|
+
readonly cwd: string;
|
|
25
|
+
/** The Prompt Definition, rendered once above the plan (ADR-0064). */
|
|
26
|
+
readonly rendered: RenderedSpawnOptions;
|
|
27
|
+
/** Resolved and declared extension paths, or nothing when the Agent runs none. */
|
|
28
|
+
readonly extensions?: {
|
|
29
|
+
readonly resolvedPaths: readonly string[];
|
|
30
|
+
readonly declared: readonly string[];
|
|
31
|
+
};
|
|
32
|
+
/** Fork facts, present only for a fork of an Agent or of the Host Session. */
|
|
33
|
+
readonly fork?: ForkIdentity;
|
|
34
|
+
readonly parent?: string;
|
|
35
|
+
readonly sessionDir: string | undefined;
|
|
36
|
+
readonly sessionFile?: string;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** One attempt's open request and the settled options the Agent records. */
|
|
40
|
+
export interface SpawnAttempt {
|
|
41
|
+
readonly request: OpenOptions;
|
|
42
|
+
readonly spawnOptions: ResolvedSpawnOptions;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** The open requests of one spawn: the peek, and one per model attempt. */
|
|
46
|
+
export interface SpawnPlan {
|
|
47
|
+
/**
|
|
48
|
+
* The request a Cassette-backed factory peeks at, with the caller's unsettled
|
|
49
|
+
* `model`/`thinking` forms (ADR-0039).
|
|
50
|
+
*/
|
|
51
|
+
peek(): OpenOptions;
|
|
52
|
+
/** The origin this spawn records, absent for an ordinary spawn. */
|
|
53
|
+
readonly origin?: SpawnOrigin;
|
|
54
|
+
/** The same request with one settled selection applied, and nothing else changed. */
|
|
55
|
+
attempt(selection: ModelSelection): SpawnAttempt;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* The open-request fields of one fork. An Agent fork names its source; a Host
|
|
60
|
+
* Fork names the Host Session hash instead, and carries no `forkOf`/`forkAsks`.
|
|
61
|
+
*/
|
|
62
|
+
function forkFields(
|
|
63
|
+
fork: ForkIdentity,
|
|
64
|
+
origin: SpawnOrigin | undefined,
|
|
65
|
+
): Partial<OpenRequestOptions> {
|
|
66
|
+
if (fork.kind === "host") {
|
|
67
|
+
return {
|
|
68
|
+
origin,
|
|
69
|
+
...(fork.forkSession === undefined ? {} : { forkSession: fork.forkSession }),
|
|
70
|
+
hostHash: fork.hostHash,
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
return {
|
|
74
|
+
origin,
|
|
75
|
+
forkOf: fork.forkOf,
|
|
76
|
+
forkAsks: fork.forkAsks,
|
|
77
|
+
forkSession: fork.forkSession,
|
|
78
|
+
...(fork.worktreeFrom === undefined ? {} : { worktreeFrom: fork.worktreeFrom }),
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* Builds one spawn's plan. The base below is the single field roster of the
|
|
84
|
+
* open path: `peek()` and `attempt()` differ only in the spawn options they
|
|
85
|
+
* pass, so the peek and every attempt cannot drift apart (ADR-0013).
|
|
86
|
+
*/
|
|
87
|
+
export function createSpawnPlan(input: SpawnPlanInput): SpawnPlan {
|
|
88
|
+
const origin: SpawnOrigin | undefined =
|
|
89
|
+
input.fork === undefined ? undefined : input.fork.kind === "host" ? "host-fork" : "fork";
|
|
90
|
+
const base = {
|
|
91
|
+
name: input.name,
|
|
92
|
+
runName: input.runName,
|
|
93
|
+
cwd: input.cwd,
|
|
94
|
+
...(input.extensions === undefined
|
|
95
|
+
? {}
|
|
96
|
+
: {
|
|
97
|
+
resolvedExtensionPaths: input.extensions.resolvedPaths,
|
|
98
|
+
declaredExtensions: input.extensions.declared,
|
|
99
|
+
}),
|
|
100
|
+
...(input.fork === undefined ? {} : forkFields(input.fork, origin)),
|
|
101
|
+
...(input.parent === undefined ? {} : { parent: input.parent }),
|
|
102
|
+
sessionDir: input.sessionDir,
|
|
103
|
+
...(input.sessionFile === undefined ? {} : { sessionFile: input.sessionFile }),
|
|
104
|
+
} satisfies Omit<OpenRequestOptions, "spawnOptions">;
|
|
105
|
+
|
|
106
|
+
return {
|
|
107
|
+
...(origin === undefined ? {} : { origin }),
|
|
108
|
+
peek: () => openRequest({ ...base, spawnOptions: input.rendered }),
|
|
109
|
+
attempt: (selection) => {
|
|
110
|
+
const spawnOptions = withSelection(input.rendered, selection);
|
|
111
|
+
return { request: openRequest({ ...base, spawnOptions }), spawnOptions };
|
|
112
|
+
},
|
|
113
|
+
};
|
|
114
|
+
}
|
|
@@ -1,5 +1,7 @@
|
|
|
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";
|
|
4
|
+
import type { SpawnOrigin } from "../events.ts";
|
|
3
5
|
import type { ModelSelection } from "../model/index.ts";
|
|
4
6
|
import {
|
|
5
7
|
assertKnownSentinels,
|
|
@@ -105,12 +107,20 @@ export interface OpenRequestOptions {
|
|
|
105
107
|
/** Resolved parent Agent name (Parent Link); spawn identity only, never argv. */
|
|
106
108
|
readonly parent?: string;
|
|
107
109
|
/** Fork facts (ADR-0044); the first three are spawn identity, the rest are not. */
|
|
108
|
-
readonly origin?:
|
|
110
|
+
readonly origin?: SpawnOrigin;
|
|
109
111
|
readonly forkOf?: string;
|
|
110
112
|
readonly forkAsks?: number;
|
|
111
113
|
readonly forkSession?: string;
|
|
114
|
+
/** Host Session identity of a Host Fork; a launch field, never argv (ADR-0068). */
|
|
115
|
+
readonly hostHash?: string;
|
|
112
116
|
readonly worktreeFrom?: WorktreeResolution;
|
|
113
117
|
readonly sessionDir: string | undefined;
|
|
118
|
+
/**
|
|
119
|
+
* An existing pi session to open on, translated to `pi --session <path>`.
|
|
120
|
+
* Never spawn identity: the path is machine-specific, exactly like
|
|
121
|
+
* `forkSession`. The fork summarizer opens on a copy this way (ADR-0022).
|
|
122
|
+
*/
|
|
123
|
+
readonly sessionFile?: string;
|
|
114
124
|
}
|
|
115
125
|
|
|
116
126
|
/**
|
|
@@ -157,7 +167,11 @@ export function openRequest(options: OpenRequestOptions): OpenOptions {
|
|
|
157
167
|
...(model === undefined ? {} : { model }),
|
|
158
168
|
systemPrompt:
|
|
159
169
|
spawnOptions.systemPrompt ??
|
|
160
|
-
yaagSystemPrompt({
|
|
170
|
+
yaagSystemPrompt({
|
|
171
|
+
agent: { name: options.name, runName: options.runName },
|
|
172
|
+
// An Agent that may ask its human reads the audience line (ADR-0062).
|
|
173
|
+
...(spawnOptions.canAskUser === true ? { audience: "user" as const } : {}),
|
|
174
|
+
}),
|
|
161
175
|
...(thinking === undefined ? {} : { thinking }),
|
|
162
176
|
...(spawnOptions.appendSystemPrompt === undefined
|
|
163
177
|
? {}
|
|
@@ -167,6 +181,11 @@ export function openRequest(options: OpenRequestOptions): OpenOptions {
|
|
|
167
181
|
...(spawnOptions.disallowedTools === undefined
|
|
168
182
|
? {}
|
|
169
183
|
: { disallowedTools: spawnOptions.disallowedTools }),
|
|
184
|
+
// Both fields stay absent for an Agent that cannot ask, so every recorded
|
|
185
|
+
// spawn identity from before ADR-0023 is unchanged.
|
|
186
|
+
...(spawnOptions.canAskUser === true
|
|
187
|
+
? { canAskUser: true as const, askUserProtocol: REQUEST_USER_INPUT_PROTOCOL }
|
|
188
|
+
: {}),
|
|
170
189
|
...(spawnOptions.skills === undefined ? {} : { skills: spawnOptions.skills }),
|
|
171
190
|
...(spawnOptions.disallowedSkills === undefined
|
|
172
191
|
? {}
|
|
@@ -184,9 +203,11 @@ export function openRequest(options: OpenRequestOptions): OpenOptions {
|
|
|
184
203
|
...(options.forkOf === undefined ? {} : { forkOf: options.forkOf }),
|
|
185
204
|
...(options.forkAsks === undefined ? {} : { forkAsks: options.forkAsks }),
|
|
186
205
|
...(options.forkSession === undefined ? {} : { forkSession: options.forkSession }),
|
|
206
|
+
...(options.hostHash === undefined ? {} : { hostHash: options.hostHash }),
|
|
187
207
|
...(options.worktreeFrom === undefined ? {} : { worktreeFrom: options.worktreeFrom }),
|
|
188
208
|
...(spawnOptions.worktree === true ? { worktree: true as const } : {}),
|
|
189
209
|
...(options.sessionDir === undefined ? {} : { sessionDir: options.sessionDir }),
|
|
210
|
+
...(options.sessionFile === undefined ? {} : { sessionFile: options.sessionFile }),
|
|
190
211
|
};
|
|
191
212
|
}
|
|
192
213
|
|
|
@@ -196,7 +217,17 @@ export function withSelection(
|
|
|
196
217
|
selection: ModelSelection,
|
|
197
218
|
): ResolvedSpawnOptions {
|
|
198
219
|
// `parent` is dropped here as well: a Handle must never reach recorded options.
|
|
199
|
-
|
|
220
|
+
// `fork` and `compact` are spawn verbs, not properties of the Agent. The spawn
|
|
221
|
+
// gate already strips them before the render; this line is the second wall, so
|
|
222
|
+
// an inherited one cannot travel into a resolved or recorded spawn request.
|
|
223
|
+
const {
|
|
224
|
+
model: _model,
|
|
225
|
+
thinking: _thinking,
|
|
226
|
+
parent: _parent,
|
|
227
|
+
fork: _fork,
|
|
228
|
+
compact: _compact,
|
|
229
|
+
...rest
|
|
230
|
+
} = options;
|
|
200
231
|
return {
|
|
201
232
|
...rest,
|
|
202
233
|
...(selection.model === undefined ? {} : { model: selection.model }),
|
package/src/agent/spawn.ts
CHANGED
|
@@ -4,14 +4,15 @@ 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
|
+
import { hostForkRequest } from "./host-fork.ts";
|
|
13
14
|
import { resolveRequest } from "./spawn-definition-request.ts";
|
|
14
|
-
import { type OpenAgentContext, openAgent } from "./spawn-open.ts";
|
|
15
|
+
import { type OpenAgentContext, type OpenAgentRequest, openAgent } from "./spawn-open.ts";
|
|
15
16
|
import { profiledRequest } from "./spawn-profiled.ts";
|
|
16
17
|
|
|
17
18
|
/** Dependencies for one Run's Agent-spawn gate. */
|
|
@@ -29,11 +30,22 @@ export interface SpawnDependencies {
|
|
|
29
30
|
readonly profile?: ActiveProfile;
|
|
30
31
|
/** Run-scoped Ask gate handed to every Agent this gate opens (ADR-0024). */
|
|
31
32
|
readonly askAdmission?: AskAdmission;
|
|
33
|
+
/** Run-scoped sink of the questions an Agent asks its human (ADR-0023). */
|
|
34
|
+
readonly questions?: AgentQuestions;
|
|
32
35
|
}
|
|
33
36
|
|
|
34
37
|
/** A RunContext spawn function that can synchronously stop accepting new Agents. */
|
|
35
38
|
export interface SpawnGate {
|
|
36
39
|
readonly spawn: RunContext["spawn"];
|
|
40
|
+
/**
|
|
41
|
+
* Opens one Agent for the Run's own machinery, after the gate closed.
|
|
42
|
+
*
|
|
43
|
+
* The closed flag is ignored on purpose: the fork summarizer runs after
|
|
44
|
+
* settlement, when the author-facing gate must already refuse (ADR-0022).
|
|
45
|
+
* The opened Agent gets neither the Run's Ask admission — which is closed by
|
|
46
|
+
* then — nor its Agent-question sink, so it can neither be refused nor park.
|
|
47
|
+
*/
|
|
48
|
+
readonly openInternal: (request: OpenAgentRequest) => Promise<Agent>;
|
|
37
49
|
close(): void;
|
|
38
50
|
}
|
|
39
51
|
|
|
@@ -65,6 +77,10 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
|
|
|
65
77
|
return handle;
|
|
66
78
|
};
|
|
67
79
|
const context: OpenAgentContext = { ...deps, taken, forkSpawner };
|
|
80
|
+
// Same open path, minus the two Run-scoped gates: `askAdmission` and
|
|
81
|
+
// `questions` are dropped rather than overridden, so nothing can re-add them.
|
|
82
|
+
const { askAdmission: _askAdmission, questions: _questions, ...ungated } = deps;
|
|
83
|
+
const internalContext: OpenAgentContext = { ...ungated, taken, forkSpawner };
|
|
68
84
|
const spawn: RunContext["spawn"] = async (
|
|
69
85
|
definitionOrOptions: SpawnOptions | AgentDefinition | ProfiledDefinition = {},
|
|
70
86
|
overrides?: SpawnOverrides,
|
|
@@ -73,15 +89,35 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
|
|
|
73
89
|
// The Agent Definition branch is explicit, although `resolveRequest` takes
|
|
74
90
|
// a plain options object too: it states the three accepted shapes in order.
|
|
75
91
|
if (isAgentDefinition(definitionOrOptions)) {
|
|
76
|
-
return
|
|
92
|
+
return openRequested(resolveRequest(definitionOrOptions, overrides));
|
|
77
93
|
}
|
|
78
94
|
if (isProfiledDefinition(definitionOrOptions)) {
|
|
79
|
-
return
|
|
95
|
+
return openRequested(profiledRequest(deps.profile, definitionOrOptions, overrides));
|
|
80
96
|
}
|
|
81
|
-
return
|
|
97
|
+
return openRequested(resolveRequest(definitionOrOptions, overrides));
|
|
98
|
+
};
|
|
99
|
+
/**
|
|
100
|
+
* Opens one requested Agent, as a Host Fork when the options carry `ctx.host`.
|
|
101
|
+
* A Host Fork gets no default Parent Link: `parent` stays the program's to
|
|
102
|
+
* give. `compact` is the ADR-0043 sugar — spawn, compact, hand the Handle back.
|
|
103
|
+
*/
|
|
104
|
+
const openRequested = async (request: OpenAgentRequest): Promise<Handle> => {
|
|
105
|
+
const host = hostForkRequest(request.spawnOptions);
|
|
106
|
+
const handle = await openAgent(context, {
|
|
107
|
+
...request,
|
|
108
|
+
...(host.fork === undefined ? {} : { fork: host.fork }),
|
|
109
|
+
});
|
|
110
|
+
if (host.compact !== undefined && host.compact !== false) {
|
|
111
|
+
await handle.compact(typeof host.compact === "string" ? host.compact : undefined);
|
|
112
|
+
}
|
|
113
|
+
return handle;
|
|
82
114
|
};
|
|
83
115
|
return {
|
|
84
116
|
spawn,
|
|
117
|
+
// The concrete Agent, not a Handle: the Run reaps its own machinery itself,
|
|
118
|
+
// and `close()` lives below the author surface.
|
|
119
|
+
openInternal: (request: OpenAgentRequest): Promise<Agent> =>
|
|
120
|
+
openAgent(internalContext, request),
|
|
85
121
|
close: (): void => {
|
|
86
122
|
closed = true;
|
|
87
123
|
},
|
|
@@ -1,9 +1,11 @@
|
|
|
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";
|
|
8
|
+
import type { AskTiming } from "./ask-timing.ts";
|
|
7
9
|
|
|
8
10
|
/** A frame consumer whose lifetime exceeds one Ask; the Agent's AgentUsage satisfies it. */
|
|
9
11
|
export interface FrameObserver {
|
|
@@ -40,10 +42,10 @@ export interface AskExchangeOptions {
|
|
|
40
42
|
readonly modelFallback: AskModelFallback | undefined;
|
|
41
43
|
/** Kills the Agent on ASK_TIMEOUT and destructive stalls — the one upward capability. */
|
|
42
44
|
readonly close: () => void;
|
|
43
|
-
/** Test-only
|
|
44
|
-
readonly
|
|
45
|
-
/**
|
|
46
|
-
readonly
|
|
47
|
-
/**
|
|
48
|
-
readonly
|
|
45
|
+
/** Test-only waits of the Ask Guard's controls; absent in production. */
|
|
46
|
+
readonly timing?: AskTiming;
|
|
47
|
+
/** Records one parked question and raises the Run pause; absent when the Agent cannot ask. */
|
|
48
|
+
readonly questions?: AgentQuestions;
|
|
49
|
+
/** Marks this Ask parked, so the pause drain skips it (ADR-0022 §3, ADR-0023). */
|
|
50
|
+
readonly park?: () => void;
|
|
49
51
|
}
|