@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
|
@@ -0,0 +1,318 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Spawn Identity: the one table of spawn fields.
|
|
3
|
+
*
|
|
4
|
+
* Every reader of a spawn's field roster — the Cassette spawn record, the spawn
|
|
5
|
+
* hash, the Divergence changed-fields list, and the argv builder — reads this
|
|
6
|
+
* table. Before this module the roster was written by hand in seven places, and
|
|
7
|
+
* nothing proved the seven agreed.
|
|
8
|
+
*
|
|
9
|
+
* To add one spawn option: add one row here and one property to `OpenOptions`.
|
|
10
|
+
* The two type asserts at the bottom fail the build when the two disagree.
|
|
11
|
+
*/
|
|
12
|
+
import type { OpenOptions } from "../transport/index.ts";
|
|
13
|
+
import type { CassetteSpawn } from "./cassette.ts";
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* `identity` names the Agent across a record and a replay, so the Cassette
|
|
17
|
+
* stores it. `launch` is a fact of one process start that the Cassette never
|
|
18
|
+
* sees; a transport decorator may pass it down freely.
|
|
19
|
+
*/
|
|
20
|
+
export type FieldKind = "identity" | "launch";
|
|
21
|
+
|
|
22
|
+
/** How one field enters the hashed object. Absent means it never enters it. */
|
|
23
|
+
export type HashRule =
|
|
24
|
+
/** Assigned raw, always present. */
|
|
25
|
+
| "always"
|
|
26
|
+
/** Assigned as `value ?? null`; the key is always present. */
|
|
27
|
+
| "nullable"
|
|
28
|
+
/** Present when the value is not `undefined`. */
|
|
29
|
+
| "optional"
|
|
30
|
+
/** Present only when the value is exactly `true`. */
|
|
31
|
+
| "whenTrue"
|
|
32
|
+
/** Present when the value is defined and not empty. */
|
|
33
|
+
| "whenNonEmpty";
|
|
34
|
+
|
|
35
|
+
/** One spawn field and what every reader must know about it. */
|
|
36
|
+
export interface SpawnField {
|
|
37
|
+
readonly field: keyof OpenOptions;
|
|
38
|
+
readonly kind: FieldKind;
|
|
39
|
+
/** Absent when the field never enters the spawn hash. */
|
|
40
|
+
readonly hash?: HashRule;
|
|
41
|
+
/** True for the fields an Ask-marker context also compares (ADR-0039). */
|
|
42
|
+
readonly askContext?: true;
|
|
43
|
+
/** Whether the field may put anything on the pi command line. */
|
|
44
|
+
readonly argv: "flag" | "never";
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* The roster, in Divergence order: `changedFields` reports in this order, so
|
|
49
|
+
* the `changed …` clause of a `REPLAY_DIVERGED` message is unchanged.
|
|
50
|
+
*
|
|
51
|
+
* The `hash` column carries two readings. It says how the field enters the
|
|
52
|
+
* spawn hash, and `recordRule` below derives from it how the field enters a
|
|
53
|
+
* Cassette record. The two agree today except for `nullable`. A future row
|
|
54
|
+
* whose recorded presence differs from its hashed presence needs a column of
|
|
55
|
+
* its own rather than a special case in `fromOpenOptions`.
|
|
56
|
+
*/
|
|
57
|
+
const FIELD_TABLE = [
|
|
58
|
+
{ field: "name", kind: "identity", hash: "always", argv: "never" },
|
|
59
|
+
{ field: "cwd", kind: "identity", hash: "always", askContext: true, argv: "never" },
|
|
60
|
+
{ field: "model", kind: "identity", hash: "nullable", askContext: true, argv: "flag" },
|
|
61
|
+
{ field: "systemPrompt", kind: "identity", hash: "nullable", askContext: true, argv: "flag" },
|
|
62
|
+
{ field: "thinking", kind: "identity", hash: "optional", askContext: true, argv: "flag" },
|
|
63
|
+
{
|
|
64
|
+
field: "appendSystemPrompt",
|
|
65
|
+
kind: "identity",
|
|
66
|
+
hash: "optional",
|
|
67
|
+
askContext: true,
|
|
68
|
+
argv: "never",
|
|
69
|
+
},
|
|
70
|
+
{ field: "tools", kind: "identity", hash: "optional", askContext: true, argv: "flag" },
|
|
71
|
+
{ field: "disallowedTools", kind: "identity", hash: "optional", askContext: true, argv: "flag" },
|
|
72
|
+
{ field: "skills", kind: "identity", hash: "optional", askContext: true, argv: "never" },
|
|
73
|
+
{
|
|
74
|
+
field: "disallowedSkills",
|
|
75
|
+
kind: "identity",
|
|
76
|
+
hash: "optional",
|
|
77
|
+
askContext: true,
|
|
78
|
+
argv: "never",
|
|
79
|
+
},
|
|
80
|
+
{ field: "worktree", kind: "identity", hash: "whenTrue", askContext: true, argv: "never" },
|
|
81
|
+
{ field: "declaredExtensions", kind: "identity", hash: "whenNonEmpty", argv: "never" },
|
|
82
|
+
// `flag` because it loads the injected `request_user_input` extension: the
|
|
83
|
+
// command line gains `-e <fixed path>`, never the value of the field itself
|
|
84
|
+
// (ADR-0023).
|
|
85
|
+
{ field: "canAskUser", kind: "identity", hash: "optional", argv: "flag" },
|
|
86
|
+
// Identity but never hashed: a bumped protocol must refuse the reactivation,
|
|
87
|
+
// and a hash mismatch would start a fresh Agent instead (ADR-0023).
|
|
88
|
+
{ field: "askUserProtocol", kind: "identity", argv: "never" },
|
|
89
|
+
{ field: "parent", kind: "identity", hash: "optional", argv: "never" },
|
|
90
|
+
{ field: "origin", kind: "identity", hash: "optional", argv: "never" },
|
|
91
|
+
{ field: "forkOf", kind: "identity", hash: "optional", argv: "never" },
|
|
92
|
+
{ field: "forkAsks", kind: "identity", hash: "optional", argv: "never" },
|
|
93
|
+
{ field: "inherit", kind: "launch", argv: "flag" },
|
|
94
|
+
{ field: "sessionDir", kind: "launch", argv: "flag" },
|
|
95
|
+
{ field: "sessionFile", kind: "launch", argv: "flag" },
|
|
96
|
+
{ field: "forkSession", kind: "launch", argv: "flag" },
|
|
97
|
+
{ field: "worktreeFrom", kind: "launch", argv: "never" },
|
|
98
|
+
{ field: "resolvedSkillPaths", kind: "launch", argv: "flag" },
|
|
99
|
+
{ field: "resolvedExtensionPaths", kind: "launch", argv: "flag" },
|
|
100
|
+
// Spawn identity: it names the Host Session conversation a Host Fork was
|
|
101
|
+
// taken from. Omitted when undefined, so every Cassette recorded before this
|
|
102
|
+
// row keeps its hash, and never argv. The copy path (`forkSession`) stays a
|
|
103
|
+
// launch row below, because that path is machine-specific.
|
|
104
|
+
{ field: "hostHash", kind: "identity", hash: "optional", argv: "never" },
|
|
105
|
+
] as const satisfies readonly SpawnField[];
|
|
106
|
+
|
|
107
|
+
/** The table as a uniform row list; `FIELD_TABLE` keeps the literal field names. */
|
|
108
|
+
export const SPAWN_FIELDS: readonly SpawnField[] = FIELD_TABLE;
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* The hash key order, frozen. A Cassette recorded before a field existed keeps
|
|
112
|
+
* its hash only while this order and the per-field rules above stay put.
|
|
113
|
+
*/
|
|
114
|
+
const HASH_ORDER = [
|
|
115
|
+
"name",
|
|
116
|
+
"cwd",
|
|
117
|
+
"model",
|
|
118
|
+
"systemPrompt",
|
|
119
|
+
"tools",
|
|
120
|
+
"disallowedTools",
|
|
121
|
+
"skills",
|
|
122
|
+
"disallowedSkills",
|
|
123
|
+
"worktree",
|
|
124
|
+
"thinking",
|
|
125
|
+
"appendSystemPrompt",
|
|
126
|
+
"declaredExtensions",
|
|
127
|
+
"canAskUser",
|
|
128
|
+
"parent",
|
|
129
|
+
"origin",
|
|
130
|
+
"forkOf",
|
|
131
|
+
"forkAsks",
|
|
132
|
+
// Appended last: an absent `hostHash` adds no key, so no recorded hash moves.
|
|
133
|
+
"hostHash",
|
|
134
|
+
] as const;
|
|
135
|
+
|
|
136
|
+
/** The key order of the recorded spawn, frozen for the same reason. */
|
|
137
|
+
const RECORD_ORDER = [
|
|
138
|
+
"name",
|
|
139
|
+
"cwd",
|
|
140
|
+
"model",
|
|
141
|
+
"systemPrompt",
|
|
142
|
+
"thinking",
|
|
143
|
+
"appendSystemPrompt",
|
|
144
|
+
"tools",
|
|
145
|
+
"disallowedTools",
|
|
146
|
+
"skills",
|
|
147
|
+
"disallowedSkills",
|
|
148
|
+
"declaredExtensions",
|
|
149
|
+
"canAskUser",
|
|
150
|
+
"askUserProtocol",
|
|
151
|
+
"parent",
|
|
152
|
+
"origin",
|
|
153
|
+
"forkOf",
|
|
154
|
+
"forkAsks",
|
|
155
|
+
"worktree",
|
|
156
|
+
// Appended last, for the same reason as in `HASH_ORDER`.
|
|
157
|
+
"hostHash",
|
|
158
|
+
] as const;
|
|
159
|
+
|
|
160
|
+
const BY_FIELD = new Map(SPAWN_FIELDS.map((row) => [row.field, row]));
|
|
161
|
+
|
|
162
|
+
/** The orders above, exported so one structural test can check them for drift. */
|
|
163
|
+
export const FIELD_ORDERS: {
|
|
164
|
+
readonly hash: readonly (keyof OpenOptions)[];
|
|
165
|
+
readonly record: readonly (keyof OpenOptions)[];
|
|
166
|
+
} = { hash: HASH_ORDER, record: RECORD_ORDER };
|
|
167
|
+
|
|
168
|
+
type Source = CassetteSpawn | OpenOptions;
|
|
169
|
+
|
|
170
|
+
/**
|
|
171
|
+
* Anything that carries some spawn fields. An Ask-marker context carries a
|
|
172
|
+
* subset of them, so the diff functions read this rather than a whole record.
|
|
173
|
+
*/
|
|
174
|
+
export type SpawnFieldSource = { readonly [Field in keyof OpenOptions]?: unknown };
|
|
175
|
+
|
|
176
|
+
function read<Field extends keyof OpenOptions>(source: SpawnFieldSource, field: Field): unknown {
|
|
177
|
+
return source[field];
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/** True when the rule keeps the value out of the built object. */
|
|
181
|
+
function omits(rule: HashRule, value: unknown): boolean {
|
|
182
|
+
if (rule === "always" || rule === "nullable") return false;
|
|
183
|
+
if (rule === "whenTrue") return value !== true;
|
|
184
|
+
// `Array.isArray` rather than a cast: a future non-array row given this rule
|
|
185
|
+
// is then omitted, not read for a `length` it does not have.
|
|
186
|
+
if (rule === "whenNonEmpty") return !Array.isArray(value) || value.length === 0;
|
|
187
|
+
return value === undefined;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/** Arrays are copied, so a later mutation of the caller's list cannot reach a record. */
|
|
191
|
+
function clone(value: unknown): unknown {
|
|
192
|
+
return Array.isArray(value) ? [...value] : value;
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
/**
|
|
196
|
+
* The Cassette spawn record of one open request: the identity rows, in record
|
|
197
|
+
* order. `name` and `cwd` open the record because `RECORD_ORDER` starts with
|
|
198
|
+
* them, which is what the recorded key order needs.
|
|
199
|
+
*/
|
|
200
|
+
export function fromOpenOptions(options: OpenOptions): CassetteSpawn {
|
|
201
|
+
const record: CassetteSpawn = { name: options.name, cwd: options.cwd };
|
|
202
|
+
for (const field of RECORD_ORDER) {
|
|
203
|
+
if (field === "name" || field === "cwd") continue;
|
|
204
|
+
const value = read(options, field);
|
|
205
|
+
if (omits(recordRule(field), value)) continue;
|
|
206
|
+
Object.assign(record, { [field]: clone(value) });
|
|
207
|
+
}
|
|
208
|
+
return record;
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
/**
|
|
212
|
+
* How one field enters a record. It is derived from the `hash` column, with the
|
|
213
|
+
* one documented shift: a record keeps `model` and `systemPrompt` absent rather
|
|
214
|
+
* than null. A future row whose recorded presence differs from its hashed
|
|
215
|
+
* presence needs its own column here, not a special case.
|
|
216
|
+
*/
|
|
217
|
+
function recordRule(field: keyof OpenOptions): HashRule {
|
|
218
|
+
const rule = BY_FIELD.get(field)?.hash ?? "optional";
|
|
219
|
+
return rule === "nullable" ? "optional" : rule;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/** The hex digest of one spawn identity. The bytes are a frozen contract (story 8). */
|
|
223
|
+
export function hash(identity: Source): string {
|
|
224
|
+
const hashed: Record<string, unknown> = {};
|
|
225
|
+
for (const field of HASH_ORDER) {
|
|
226
|
+
const rule = BY_FIELD.get(field)?.hash;
|
|
227
|
+
if (rule === undefined) continue;
|
|
228
|
+
const value = read(identity, field);
|
|
229
|
+
if (omits(rule, value)) continue;
|
|
230
|
+
hashed[field] = rule === "nullable" ? (value ?? null) : value;
|
|
231
|
+
}
|
|
232
|
+
const hasher = new Bun.CryptoHasher("sha256");
|
|
233
|
+
hasher.update(JSON.stringify(hashed));
|
|
234
|
+
return hasher.digest("hex");
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
/** The listed fields whose canonical JSON differs between two identity records. */
|
|
238
|
+
function changedAmong(
|
|
239
|
+
fields: readonly (keyof OpenOptions)[],
|
|
240
|
+
expected: SpawnFieldSource,
|
|
241
|
+
actual: SpawnFieldSource,
|
|
242
|
+
): readonly string[] {
|
|
243
|
+
return fields.filter(
|
|
244
|
+
(field) => JSON.stringify(read(expected, field)) !== JSON.stringify(read(actual, field)),
|
|
245
|
+
);
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* Every field the spawn hash covers, in Divergence order. Not every identity
|
|
250
|
+
* field: `askUserProtocol` is Spawn Identity that the hash leaves out.
|
|
251
|
+
*/
|
|
252
|
+
export function hashedFields(): readonly (keyof OpenOptions)[] {
|
|
253
|
+
return SPAWN_FIELDS.filter((row) => row.hash !== undefined).map((row) => row.field);
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
/**
|
|
257
|
+
* The identity fields an Ask-marker context compares. Extensions are the
|
|
258
|
+
* deliberate exception: they identify the process start, not an Ask.
|
|
259
|
+
*/
|
|
260
|
+
export function askContextFields(): readonly (keyof OpenOptions)[] {
|
|
261
|
+
return SPAWN_FIELDS.filter((row) => row.askContext === true).map((row) => row.field);
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
/** The rows the argv builder may turn into a pi flag. */
|
|
265
|
+
export function argvFields(): readonly (keyof OpenOptions)[] {
|
|
266
|
+
return SPAWN_FIELDS.filter((row) => row.argv === "flag").map((row) => row.field);
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
/** The Divergence field list of one spawn mismatch. */
|
|
270
|
+
export function changedFields(
|
|
271
|
+
expected: SpawnFieldSource,
|
|
272
|
+
actual: SpawnFieldSource,
|
|
273
|
+
): readonly string[] {
|
|
274
|
+
return changedAmong(hashedFields(), expected, actual);
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
/** The Divergence field list an Ask-marker context reports. */
|
|
278
|
+
export function askContextChangedFields(
|
|
279
|
+
expected: SpawnFieldSource,
|
|
280
|
+
actual: SpawnFieldSource,
|
|
281
|
+
): readonly string[] {
|
|
282
|
+
return changedAmong(askContextFields(), expected, actual);
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
/**
|
|
286
|
+
* True when a live spawn matches the recorded one on every identity field
|
|
287
|
+
* except the resolved model and thinking, so a resume may adopt the recorded
|
|
288
|
+
* selection instead of re-running Model Resolution (ADR-0039).
|
|
289
|
+
*/
|
|
290
|
+
export function matchesExceptModel(expected: CassetteSpawn, actual: OpenOptions): boolean {
|
|
291
|
+
return (
|
|
292
|
+
hash({ ...expected, model: undefined, thinking: undefined }) ===
|
|
293
|
+
hash({ ...actual, model: undefined, thinking: undefined })
|
|
294
|
+
);
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
// A key of `OpenOptions` without a row, or a row that is not a key, is a build
|
|
298
|
+
// failure here rather than a silent gap in the hash (story 3).
|
|
299
|
+
type Row = (typeof FIELD_TABLE)[number]["field"];
|
|
300
|
+
type Assert<A extends B, B> = [A, B] extends [B, A] ? true : never;
|
|
301
|
+
type _EveryKeyHasRow = Assert<keyof OpenOptions, Row>;
|
|
302
|
+
|
|
303
|
+
// `CassetteSpawn` is hand-written, and `fromOpenOptions` builds it field by
|
|
304
|
+
// field, so these two tie the record type back to the table: the record holds
|
|
305
|
+
// exactly the identity rows, and every value an open option carries fits the
|
|
306
|
+
// field the record declares for it.
|
|
307
|
+
type IdentityRow = Extract<(typeof FIELD_TABLE)[number], { kind: "identity" }>["field"];
|
|
308
|
+
type AssertTrue<T extends true> = T;
|
|
309
|
+
type _RecordHoldsEveryIdentityRow = Assert<keyof CassetteSpawn, IdentityRow>;
|
|
310
|
+
type _EveryIdentityRowIsRecorded = Assert<IdentityRow, keyof CassetteSpawn>;
|
|
311
|
+
type _RecordTakesOpenOptionValues = AssertTrue<
|
|
312
|
+
{
|
|
313
|
+
[Field in keyof CassetteSpawn]-?: OpenOptions[Field] extends CassetteSpawn[Field]
|
|
314
|
+
? true
|
|
315
|
+
: false;
|
|
316
|
+
}[keyof CassetteSpawn]
|
|
317
|
+
>;
|
|
318
|
+
type _EveryRowIsAKey = Assert<Row, keyof OpenOptions>;
|
|
@@ -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,15 @@ 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
|
|
60
|
+
| "HOST_SESSION_UNUSABLE" // the host session file cannot start a Run: missing, unreadable, empty, header-less, ill-formed, without the named tool call, or without a tool call id on a live run
|
|
59
61
|
| "REPLAY_DIVERGED" // replayed program differed from its Cassette
|
|
60
|
-
| "RESUME_REFUSED" // resume metadata is absent
|
|
62
|
+
| "RESUME_REFUSED" // resume metadata is absent, the recorded tree moved, or an answer is unknown or conflicting (ADR-0022/0023)
|
|
61
63
|
| "PROFILE_NOT_FOUND" // a selected Profile is not declared by the program (ADR-0052)
|
|
62
64
|
| "PROFILE_REQUIRED" // a Profiled Definition was spawned by a program that declares no Profiles
|
|
63
65
|
| "ROLE_NOT_FOUND" // a factory read a Role the program does not declare
|
|
64
66
|
| "RUN_CLOSED" // spawn or Ask requested after the Run began settling
|
|
65
|
-
| "RUN_PAUSED" // an external pause drain settled the Run (ADR-0024)
|
|
66
67
|
| "RUN_STOPPED" // the Run's abort signal fired before the program completed
|
|
67
68
|
| "WORKTREE_REFUSED" // base cwd is not a clean Git repository
|
|
68
69
|
| "MODEL_RESOLUTION_FAILED" // the resolver gave up, or every candidate failed; carries the history
|
package/src/contract/index.ts
CHANGED
|
@@ -8,6 +8,23 @@ import type { AgentPolicy } from "./agent-policy.ts";
|
|
|
8
8
|
import type { Handle } from "./handle.ts";
|
|
9
9
|
import type { ThinkingLevel } from "./model-spec.ts";
|
|
10
10
|
|
|
11
|
+
/** Not exported, so a HostSource is unreachable outside this module. */
|
|
12
|
+
declare const hostSource: unique symbol;
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* The Host Session's conversation, offered as a fork source.
|
|
16
|
+
*
|
|
17
|
+
* A program reads it as `ctx.host` and passes it back; it cannot build one,
|
|
18
|
+
* because the brand key is private to this module. It follows the fork rules of
|
|
19
|
+
* ADR-0044, with the Host Session in the place of an Agent as the source, and
|
|
20
|
+
* it stays type-only, so the author declaration tree carries no value
|
|
21
|
+
* (ADR-0045).
|
|
22
|
+
*/
|
|
23
|
+
export interface HostSource {
|
|
24
|
+
readonly kind: "host";
|
|
25
|
+
readonly [hostSource]: true;
|
|
26
|
+
}
|
|
27
|
+
|
|
11
28
|
/**
|
|
12
29
|
* Options for spawning one Agent: an Agent Policy plus its topology
|
|
13
30
|
* (ADR-0001, ADR-0009, ADR-0026).
|
|
@@ -22,6 +39,10 @@ export interface SpawnOptions extends AgentPolicy {
|
|
|
22
39
|
* no conversation channel and no lifetime rule.
|
|
23
40
|
*/
|
|
24
41
|
readonly parent?: Handle;
|
|
42
|
+
/** Fork the Host Session's conversation instead of starting a fresh one. */
|
|
43
|
+
readonly fork?: HostSource;
|
|
44
|
+
/** true = pi's default compaction; a string = pi custom instructions. */
|
|
45
|
+
readonly compact?: boolean | string;
|
|
25
46
|
}
|
|
26
47
|
|
|
27
48
|
/**
|
|
@@ -40,9 +61,15 @@ export interface SpawnOptions extends AgentPolicy {
|
|
|
40
61
|
* spawn-request seam, so no consumer of this shape can ever see a function
|
|
41
62
|
* (ADR-0064). An unset prompt stays unset here; the default text is filled in
|
|
42
63
|
* `openRequest` alone, so the Ask hash keeps hashing `systemPrompt: null`.
|
|
64
|
+
*
|
|
65
|
+
* `fork` and `compact` are omitted too: they are spawn verbs, not properties of
|
|
66
|
+
* the Agent, so they never enter Ask identity.
|
|
43
67
|
*/
|
|
44
68
|
export interface ResolvedSpawnOptions
|
|
45
|
-
extends Omit<
|
|
69
|
+
extends Omit<
|
|
70
|
+
SpawnOptions,
|
|
71
|
+
"model" | "thinking" | "parent" | "askDefaults" | "fork" | "compact" | "systemPrompt"
|
|
72
|
+
> {
|
|
46
73
|
readonly model?: string;
|
|
47
74
|
readonly systemPrompt?: string;
|
|
48
75
|
readonly thinking?: ThinkingLevel;
|
|
@@ -63,7 +90,7 @@ export interface ResolvedSpawnOptions
|
|
|
63
90
|
* source's branch, so only committed state transfers. The child re-runs the
|
|
64
91
|
* ADR-0026 Tool Contract probe against its own effective options.
|
|
65
92
|
*/
|
|
66
|
-
export interface ForkOptions extends SpawnOptions {
|
|
93
|
+
export interface ForkOptions extends Omit<SpawnOptions, "fork"> {
|
|
67
94
|
/** true = pi's default compaction; a string = pi custom instructions. */
|
|
68
95
|
readonly compact?: boolean | string;
|
|
69
96
|
}
|
|
@@ -78,4 +105,8 @@ export interface SpawnOverrides {
|
|
|
78
105
|
readonly worktree?: boolean;
|
|
79
106
|
/** Names this Agent's parent in the Run tree (Parent Link). Data only. */
|
|
80
107
|
readonly parent?: Handle;
|
|
108
|
+
/** Fork the Host Session's conversation instead of starting a fresh one. */
|
|
109
|
+
readonly fork?: HostSource;
|
|
110
|
+
/** true = pi's default compaction; a string = pi custom instructions. */
|
|
111
|
+
readonly compact?: boolean | string;
|
|
81
112
|
}
|
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,
|