@yaag/runtime 0.26.0 → 0.28.1

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.
Files changed (66) hide show
  1. package/package.json +1 -1
  2. package/src/agent/agent-name.ts +22 -0
  3. package/src/agent/agent-names.ts +5 -1
  4. package/src/agent/agent.ts +34 -17
  5. package/src/agent/define-agent.ts +4 -0
  6. package/src/agent/fork.ts +50 -12
  7. package/src/agent/host-fork.ts +85 -0
  8. package/src/agent/index.ts +1 -0
  9. package/src/agent/spawn-definition-request.ts +41 -6
  10. package/src/agent/spawn-open.ts +54 -107
  11. package/src/agent/spawn-parent.ts +64 -0
  12. package/src/agent/spawn-plan.ts +120 -0
  13. package/src/agent/spawn-request.ts +26 -6
  14. package/src/agent/spawn.ts +47 -6
  15. package/src/ask/ask-exchange-options.ts +3 -6
  16. package/src/ask/ask-exchange.ts +48 -108
  17. package/src/ask/ask-guard.ts +207 -0
  18. package/src/ask/ask-timing.ts +12 -0
  19. package/src/ask/index.ts +1 -0
  20. package/src/cassette/cassette-loader.ts +9 -20
  21. package/src/cassette/cassette-schema.ts +11 -1
  22. package/src/cassette/cassette.ts +16 -34
  23. package/src/cassette/checkpoint.ts +306 -0
  24. package/src/cassette/index.ts +16 -7
  25. package/src/cassette/parked-asks.ts +38 -0
  26. package/src/cassette/replay-divergence.ts +7 -102
  27. package/src/cassette/resume-identity.ts +5 -1
  28. package/src/cassette/resume-preconditions.ts +14 -0
  29. package/src/cassette/resume-transport.ts +26 -32
  30. package/src/cassette/run-identity.ts +109 -0
  31. package/src/cassette/session-answer.ts +51 -114
  32. package/src/cassette/spawn-identity.ts +328 -0
  33. package/src/contract/error-codes.ts +4 -0
  34. package/src/contract/group.ts +38 -0
  35. package/src/contract/index.ts +2 -0
  36. package/src/contract/spawn-options.ts +48 -7
  37. package/src/error-factories.ts +8 -0
  38. package/src/events.ts +22 -2
  39. package/src/index.ts +7 -0
  40. package/src/pi-session/append-tool-result.ts +165 -0
  41. package/src/pi-session/index.ts +30 -0
  42. package/src/pi-session/pi-session-error.ts +34 -0
  43. package/src/pi-session/session-copy.ts +113 -0
  44. package/src/pi-session/session-entries.ts +130 -0
  45. package/src/public-api.ts +2 -0
  46. package/src/question-summary/index.ts +4 -8
  47. package/src/question-summary/summarize-question.ts +1 -1
  48. package/src/question-summary/summary-policy.ts +5 -2
  49. package/src/run/agent-questions.ts +82 -0
  50. package/src/run/answers.ts +22 -1
  51. package/src/run/groups.ts +111 -0
  52. package/src/run/host-session.ts +233 -0
  53. package/src/run/index.ts +8 -0
  54. package/src/run/run-context.ts +15 -0
  55. package/src/run/run.ts +208 -182
  56. package/src/summary/index.ts +1 -0
  57. package/src/summary/summary-agent.ts +6 -0
  58. package/src/summary/summary-group.ts +31 -0
  59. package/src/summary/summary.ts +12 -0
  60. package/src/transport/live-transport.ts +19 -0
  61. package/src/transport/pi-state.ts +10 -1
  62. package/src/transport/transport.ts +20 -9
  63. package/src/types.ts +3 -0
  64. package/src/cassette/checkpoint-flush.ts +0 -101
  65. package/src/cassette/run-checkpoint.ts +0 -272
  66. package/src/question-summary/session-copy.ts +0 -169
@@ -0,0 +1,328 @@
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
+ // The Group a spawn landed in (ADR-0070). Spawn identity: a program that
106
+ // moved an Agent to another Group diverges at that spawn, and a resume goes
107
+ // live there. Omitted when undefined, so every Cassette recorded before
108
+ // Groups keeps its hash. Never argv, and never Ask-marker context: a Group
109
+ // is tree position, not Ask behaviour.
110
+ { field: "group", kind: "identity", hash: "optional", argv: "never" },
111
+ ] as const satisfies readonly SpawnField[];
112
+
113
+ /** The table as a uniform row list; `FIELD_TABLE` keeps the literal field names. */
114
+ export const SPAWN_FIELDS: readonly SpawnField[] = FIELD_TABLE;
115
+
116
+ /**
117
+ * The hash key order, frozen. A Cassette recorded before a field existed keeps
118
+ * its hash only while this order and the per-field rules above stay put.
119
+ */
120
+ const HASH_ORDER = [
121
+ "name",
122
+ "cwd",
123
+ "model",
124
+ "systemPrompt",
125
+ "tools",
126
+ "disallowedTools",
127
+ "skills",
128
+ "disallowedSkills",
129
+ "worktree",
130
+ "thinking",
131
+ "appendSystemPrompt",
132
+ "declaredExtensions",
133
+ "canAskUser",
134
+ "parent",
135
+ "origin",
136
+ "forkOf",
137
+ "forkAsks",
138
+ // The rows below are appended, never inserted: each one is optional, so an
139
+ // absent value adds no key and no recorded hash moves.
140
+ "hostHash",
141
+ "group",
142
+ ] as const;
143
+
144
+ /** The key order of the recorded spawn, frozen for the same reason. */
145
+ const RECORD_ORDER = [
146
+ "name",
147
+ "cwd",
148
+ "model",
149
+ "systemPrompt",
150
+ "thinking",
151
+ "appendSystemPrompt",
152
+ "tools",
153
+ "disallowedTools",
154
+ "skills",
155
+ "disallowedSkills",
156
+ "declaredExtensions",
157
+ "canAskUser",
158
+ "askUserProtocol",
159
+ "parent",
160
+ "origin",
161
+ "forkOf",
162
+ "forkAsks",
163
+ "worktree",
164
+ // The rows below are appended, never inserted, for the same reason as in
165
+ // `HASH_ORDER`.
166
+ "hostHash",
167
+ "group",
168
+ ] as const;
169
+
170
+ const BY_FIELD = new Map(SPAWN_FIELDS.map((row) => [row.field, row]));
171
+
172
+ /** The orders above, exported so one structural test can check them for drift. */
173
+ export const FIELD_ORDERS: {
174
+ readonly hash: readonly (keyof OpenOptions)[];
175
+ readonly record: readonly (keyof OpenOptions)[];
176
+ } = { hash: HASH_ORDER, record: RECORD_ORDER };
177
+
178
+ type Source = CassetteSpawn | OpenOptions;
179
+
180
+ /**
181
+ * Anything that carries some spawn fields. An Ask-marker context carries a
182
+ * subset of them, so the diff functions read this rather than a whole record.
183
+ */
184
+ export type SpawnFieldSource = { readonly [Field in keyof OpenOptions]?: unknown };
185
+
186
+ function read<Field extends keyof OpenOptions>(source: SpawnFieldSource, field: Field): unknown {
187
+ return source[field];
188
+ }
189
+
190
+ /** True when the rule keeps the value out of the built object. */
191
+ function omits(rule: HashRule, value: unknown): boolean {
192
+ if (rule === "always" || rule === "nullable") return false;
193
+ if (rule === "whenTrue") return value !== true;
194
+ // `Array.isArray` rather than a cast: a future non-array row given this rule
195
+ // is then omitted, not read for a `length` it does not have.
196
+ if (rule === "whenNonEmpty") return !Array.isArray(value) || value.length === 0;
197
+ return value === undefined;
198
+ }
199
+
200
+ /** Arrays are copied, so a later mutation of the caller's list cannot reach a record. */
201
+ function clone(value: unknown): unknown {
202
+ return Array.isArray(value) ? [...value] : value;
203
+ }
204
+
205
+ /**
206
+ * The Cassette spawn record of one open request: the identity rows, in record
207
+ * order. `name` and `cwd` open the record because `RECORD_ORDER` starts with
208
+ * them, which is what the recorded key order needs.
209
+ */
210
+ export function fromOpenOptions(options: OpenOptions): CassetteSpawn {
211
+ const record: CassetteSpawn = { name: options.name, cwd: options.cwd };
212
+ for (const field of RECORD_ORDER) {
213
+ if (field === "name" || field === "cwd") continue;
214
+ const value = read(options, field);
215
+ if (omits(recordRule(field), value)) continue;
216
+ Object.assign(record, { [field]: clone(value) });
217
+ }
218
+ return record;
219
+ }
220
+
221
+ /**
222
+ * How one field enters a record. It is derived from the `hash` column, with the
223
+ * one documented shift: a record keeps `model` and `systemPrompt` absent rather
224
+ * than null. A future row whose recorded presence differs from its hashed
225
+ * presence needs its own column here, not a special case.
226
+ */
227
+ function recordRule(field: keyof OpenOptions): HashRule {
228
+ const rule = BY_FIELD.get(field)?.hash ?? "optional";
229
+ return rule === "nullable" ? "optional" : rule;
230
+ }
231
+
232
+ /** The hex digest of one spawn identity. The bytes are a frozen contract (story 8). */
233
+ export function hash(identity: Source): string {
234
+ const hashed: Record<string, unknown> = {};
235
+ for (const field of HASH_ORDER) {
236
+ const rule = BY_FIELD.get(field)?.hash;
237
+ if (rule === undefined) continue;
238
+ const value = read(identity, field);
239
+ if (omits(rule, value)) continue;
240
+ hashed[field] = rule === "nullable" ? (value ?? null) : value;
241
+ }
242
+ const hasher = new Bun.CryptoHasher("sha256");
243
+ hasher.update(JSON.stringify(hashed));
244
+ return hasher.digest("hex");
245
+ }
246
+
247
+ /** The listed fields whose canonical JSON differs between two identity records. */
248
+ function changedAmong(
249
+ fields: readonly (keyof OpenOptions)[],
250
+ expected: SpawnFieldSource,
251
+ actual: SpawnFieldSource,
252
+ ): readonly string[] {
253
+ return fields.filter(
254
+ (field) => JSON.stringify(read(expected, field)) !== JSON.stringify(read(actual, field)),
255
+ );
256
+ }
257
+
258
+ /**
259
+ * Every field the spawn hash covers, in Divergence order. Not every identity
260
+ * field: `askUserProtocol` is Spawn Identity that the hash leaves out.
261
+ */
262
+ export function hashedFields(): readonly (keyof OpenOptions)[] {
263
+ return SPAWN_FIELDS.filter((row) => row.hash !== undefined).map((row) => row.field);
264
+ }
265
+
266
+ /**
267
+ * The identity fields an Ask-marker context compares. Extensions are the
268
+ * deliberate exception: they identify the process start, not an Ask.
269
+ */
270
+ export function askContextFields(): readonly (keyof OpenOptions)[] {
271
+ return SPAWN_FIELDS.filter((row) => row.askContext === true).map((row) => row.field);
272
+ }
273
+
274
+ /** The rows the argv builder may turn into a pi flag. */
275
+ export function argvFields(): readonly (keyof OpenOptions)[] {
276
+ return SPAWN_FIELDS.filter((row) => row.argv === "flag").map((row) => row.field);
277
+ }
278
+
279
+ /** The Divergence field list of one spawn mismatch. */
280
+ export function changedFields(
281
+ expected: SpawnFieldSource,
282
+ actual: SpawnFieldSource,
283
+ ): readonly string[] {
284
+ return changedAmong(hashedFields(), expected, actual);
285
+ }
286
+
287
+ /** The Divergence field list an Ask-marker context reports. */
288
+ export function askContextChangedFields(
289
+ expected: SpawnFieldSource,
290
+ actual: SpawnFieldSource,
291
+ ): readonly string[] {
292
+ return changedAmong(askContextFields(), expected, actual);
293
+ }
294
+
295
+ /**
296
+ * True when a live spawn matches the recorded one on every identity field
297
+ * except the resolved model and thinking, so a resume may adopt the recorded
298
+ * selection instead of re-running Model Resolution (ADR-0039).
299
+ */
300
+ export function matchesExceptModel(expected: CassetteSpawn, actual: OpenOptions): boolean {
301
+ return (
302
+ hash({ ...expected, model: undefined, thinking: undefined }) ===
303
+ hash({ ...actual, model: undefined, thinking: undefined })
304
+ );
305
+ }
306
+
307
+ // A key of `OpenOptions` without a row, or a row that is not a key, is a build
308
+ // failure here rather than a silent gap in the hash (story 3).
309
+ type Row = (typeof FIELD_TABLE)[number]["field"];
310
+ type Assert<A extends B, B> = [A, B] extends [B, A] ? true : never;
311
+ type _EveryKeyHasRow = Assert<keyof OpenOptions, Row>;
312
+
313
+ // `CassetteSpawn` is hand-written, and `fromOpenOptions` builds it field by
314
+ // field, so these two tie the record type back to the table: the record holds
315
+ // exactly the identity rows, and every value an open option carries fits the
316
+ // field the record declares for it.
317
+ type IdentityRow = Extract<(typeof FIELD_TABLE)[number], { kind: "identity" }>["field"];
318
+ type AssertTrue<T extends true> = T;
319
+ type _RecordHoldsEveryIdentityRow = Assert<keyof CassetteSpawn, IdentityRow>;
320
+ type _EveryIdentityRowIsRecorded = Assert<IdentityRow, keyof CassetteSpawn>;
321
+ type _RecordTakesOpenOptionValues = AssertTrue<
322
+ {
323
+ [Field in keyof CassetteSpawn]-?: OpenOptions[Field] extends CassetteSpawn[Field]
324
+ ? true
325
+ : false;
326
+ }[keyof CassetteSpawn]
327
+ >;
328
+ type _EveryRowIsAKey = Assert<Row, keyof OpenOptions>;
@@ -55,8 +55,12 @@ 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
+ | "AGENT_NAME_INVALID" // an Agent name contains "/" or ":"
59
+ | "GROUP_NAME_INVALID" // a Group name is empty, or contains "/" or ":" (ADR-0070)
60
+ | "GROUP_EXISTS" // a Group of that name is already open under that parent, or an Agent holds that root name (ADR-0070)
58
61
  | "PAUSE_REFUSED" // two pause questions claim one id (ADR-0022)
59
62
  | "RECORD_PATH_UNUSABLE" // the --record directory could not be created at Run start
63
+ | "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
60
64
  | "REPLAY_DIVERGED" // replayed program differed from its Cassette
61
65
  | "RESUME_REFUSED" // resume metadata is absent, the recorded tree moved, or an answer is unknown or conflicting (ADR-0022/0023)
62
66
  | "PROFILE_NOT_FOUND" // a selected Profile is not declared by the program (ADR-0052)
@@ -0,0 +1,38 @@
1
+ /**
2
+ * The Group declarations of the author contract (ADR-0070).
3
+ *
4
+ * Types only, and no import outside this directory (ADR-0045). A Group is a
5
+ * tree position with no process, so it lives here and not in
6
+ * `spawn-options.ts`, which is the home of the spawn verbs.
7
+ */
8
+
9
+ import type { Handle } from "./handle.ts";
10
+
11
+ /** Not exported, so a Group is unreachable outside this module. */
12
+ declare const group: unique symbol;
13
+
14
+ /**
15
+ * One Group of the Run tree.
16
+ *
17
+ * A program reads it back from `ctx.group()` and passes it on; it cannot build
18
+ * one, because the brand key is private to this module. It stays type-only, so
19
+ * the author declaration tree carries no value (ADR-0045).
20
+ */
21
+ export interface Group {
22
+ readonly kind: "group";
23
+ readonly name: string;
24
+ /**
25
+ * The `/`-joined chain from the top of the Group's branch down; an Agent name
26
+ * is the first segment when the Group sits under an Agent (ADR-0070).
27
+ */
28
+ readonly path: string;
29
+ readonly [group]: true;
30
+ }
31
+
32
+ /** What `ctx.group()` accepts: a name, and the position the Group opens at. */
33
+ export interface GroupOptions {
34
+ /** Must not be empty, and must not contain `/` or `:`. */
35
+ readonly name: string;
36
+ /** A Group or a Handle of this Run; absent opens a root Group. */
37
+ readonly parent?: Handle | Group;
38
+ }
@@ -24,6 +24,7 @@ export type {
24
24
  ModelResolutionOutcome,
25
25
  YaagErrorCode,
26
26
  } from "./error-codes.ts";
27
+ export type { Group, GroupOptions } from "./group.ts";
27
28
  export type { AskOptions, Handle, StructuredAskOptions } from "./handle.ts";
28
29
  export type {
29
30
  ModelError,
@@ -37,6 +38,7 @@ export type {
37
38
  } from "./model-spec.ts";
38
39
  export type {
39
40
  ForkOptions,
41
+ HostSource,
40
42
  ResolvedSpawnOptions,
41
43
  SpawnOptions,
42
44
  SpawnOverrides,
@@ -5,9 +5,27 @@
5
5
  */
6
6
 
7
7
  import type { AgentPolicy } from "./agent-policy.ts";
8
+ import type { Group } from "./group.ts";
8
9
  import type { Handle } from "./handle.ts";
9
10
  import type { ThinkingLevel } from "./model-spec.ts";
10
11
 
12
+ /** Not exported, so a HostSource is unreachable outside this module. */
13
+ declare const hostSource: unique symbol;
14
+
15
+ /**
16
+ * The Host Session's conversation, offered as a fork source.
17
+ *
18
+ * A program reads it as `ctx.host` and passes it back; it cannot build one,
19
+ * because the brand key is private to this module. It follows the fork rules of
20
+ * ADR-0044, with the Host Session in the place of an Agent as the source, and
21
+ * it stays type-only, so the author declaration tree carries no value
22
+ * (ADR-0045).
23
+ */
24
+ export interface HostSource {
25
+ readonly kind: "host";
26
+ readonly [hostSource]: true;
27
+ }
28
+
11
29
  /**
12
30
  * Options for spawning one Agent: an Agent Policy plus its topology
13
31
  * (ADR-0001, ADR-0009, ADR-0026).
@@ -18,10 +36,16 @@ export interface SpawnOptions extends AgentPolicy {
18
36
  /** Request a fresh Git worktree. The requested cwd remains the base until spawn resolves. */
19
37
  readonly worktree?: boolean;
20
38
  /**
21
- * Names this Agent's parent in the Run tree (Parent Link). Data only: it is
22
- * no conversation channel and no lifetime rule.
39
+ * Names this Agent's position in the Run tree (Parent Link). Data only: it is
40
+ * no conversation channel and no lifetime rule. A Handle names a parent
41
+ * Agent, a Group names a position with no process (ADR-0070); a spawn carries
42
+ * at most one of the two.
23
43
  */
24
- readonly parent?: Handle;
44
+ readonly parent?: Handle | Group;
45
+ /** Fork the Host Session's conversation instead of starting a fresh one. */
46
+ readonly fork?: HostSource;
47
+ /** true = pi's default compaction; a string = pi custom instructions. */
48
+ readonly compact?: boolean | string;
25
49
  }
26
50
 
27
51
  /**
@@ -40,9 +64,15 @@ export interface SpawnOptions extends AgentPolicy {
40
64
  * spawn-request seam, so no consumer of this shape can ever see a function
41
65
  * (ADR-0064). An unset prompt stays unset here; the default text is filled in
42
66
  * `openRequest` alone, so the Ask hash keeps hashing `systemPrompt: null`.
67
+ *
68
+ * `fork` and `compact` are omitted too: they are spawn verbs, not properties of
69
+ * the Agent, so they never enter Ask identity.
43
70
  */
44
71
  export interface ResolvedSpawnOptions
45
- extends Omit<SpawnOptions, "model" | "thinking" | "parent" | "askDefaults" | "systemPrompt"> {
72
+ extends Omit<
73
+ SpawnOptions,
74
+ "model" | "thinking" | "parent" | "askDefaults" | "fork" | "compact" | "systemPrompt"
75
+ > {
46
76
  readonly model?: string;
47
77
  readonly systemPrompt?: string;
48
78
  readonly thinking?: ThinkingLevel;
@@ -57,13 +87,16 @@ export interface ResolvedSpawnOptions
57
87
  * names one. The fork source becomes the child's default `parent`. An
58
88
  * `askDefaults` given here replaces the source's object; it does not merge.
59
89
  *
90
+ * A fork keeps its source's Group unless `parent` names another Group
91
+ * (ADR-0070).
92
+ *
60
93
  * The inherited model is the concrete one the source settled on, so the child
61
94
  * never re-runs the source's fallback list; `fork({ model })` is the way out.
62
95
  * A fork of a Worktree Agent gets its own fresh worktree, branched from the
63
96
  * source's branch, so only committed state transfers. The child re-runs the
64
97
  * ADR-0026 Tool Contract probe against its own effective options.
65
98
  */
66
- export interface ForkOptions extends SpawnOptions {
99
+ export interface ForkOptions extends Omit<SpawnOptions, "fork"> {
67
100
  /** true = pi's default compaction; a string = pi custom instructions. */
68
101
  readonly compact?: boolean | string;
69
102
  }
@@ -76,6 +109,14 @@ export interface SpawnOverrides {
76
109
  readonly cwd?: string;
77
110
  /** Request a fresh Git worktree. */
78
111
  readonly worktree?: boolean;
79
- /** Names this Agent's parent in the Run tree (Parent Link). Data only. */
80
- readonly parent?: Handle;
112
+ /**
113
+ * Names this Agent's position in the Run tree (Parent Link). Data only. A
114
+ * Handle names a parent Agent, a Group names a position with no process
115
+ * (ADR-0070); a spawn carries at most one of the two.
116
+ */
117
+ readonly parent?: Handle | Group;
118
+ /** Fork the Host Session's conversation instead of starting a fresh one. */
119
+ readonly fork?: HostSource;
120
+ /** true = pi's default compaction; a string = pi custom instructions. */
121
+ readonly compact?: boolean | string;
81
122
  }
@@ -68,3 +68,11 @@ export function modelResolutionError(
68
68
  { modelErrors: errors },
69
69
  );
70
70
  }
71
+
72
+ /** The HOST_SESSION_UNUSABLE refusal: it names the reason and the file. */
73
+ export function hostSessionUnusableError(sessionFile: string, reason: string): YaagError {
74
+ return new YaagError(
75
+ "HOST_SESSION_UNUSABLE",
76
+ `host session ${sessionFile} is unusable: ${reason}`,
77
+ );
78
+ }
package/src/events.ts CHANGED
@@ -22,9 +22,11 @@ export type RunOutcome = "completed" | "failed" | "stopped" | "paused" | "interr
22
22
 
23
23
  /**
24
24
  * How an Agent came to be. An absent value on an event means "spawn"; "fork"
25
- * marks an Agent created from a copy of another Agent's session (ADR-0044).
25
+ * marks an Agent created from a copy of another Agent's session (ADR-0044);
26
+ * "host-fork" marks one created from a copy of the Host Session's conversation.
27
+ * Every reader accepts all three.
26
28
  */
27
- export type SpawnOrigin = "spawn" | "fork";
29
+ export type SpawnOrigin = "spawn" | "fork" | "host-fork";
28
30
 
29
31
  /**
30
32
  * Why a control request failed, or `BUSY` when a second Control Channel client
@@ -97,6 +99,12 @@ export type LifecycleEventBody =
97
99
  readonly sessionFile?: string;
98
100
  /** Resolved name of the Agent named as this Agent's parent (Parent Link). */
99
101
  readonly parent?: string;
102
+ /**
103
+ * Path of the Group this Agent sits in (ADR-0070). `parent` names an
104
+ * Agent, `group` names a Group; a plain spawn carries at most one of the
105
+ * two, and a Fork inherits `group` beside its source's `parent`.
106
+ */
107
+ readonly group?: string;
100
108
  /** How the Agent came to be; absent means "spawn". */
101
109
  readonly origin?: SpawnOrigin;
102
110
  /**
@@ -110,6 +118,18 @@ export type LifecycleEventBody =
110
118
  /** Roles the factory read, in order, duplicates kept; `[]` for none. */
111
119
  readonly role?: readonly string[];
112
120
  }
121
+ | {
122
+ /**
123
+ * A Group this Run opened (ADR-0070). It owns no process and it never
124
+ * closes. `path` is the `/`-joined name chain, so the parent Group is
125
+ * implicit in it. `parent` is the Agent name when the Group sits under an
126
+ * Agent, and it is absent in all other cases.
127
+ */
128
+ readonly type: "group_open";
129
+ readonly path: string;
130
+ readonly name: string;
131
+ readonly parent?: string;
132
+ }
113
133
  | {
114
134
  readonly type: "ask_start";
115
135
  readonly agent: string;
package/src/index.ts CHANGED
@@ -22,6 +22,7 @@ export {
22
22
  loadCassette,
23
23
  recordingTransport,
24
24
  replayTransport,
25
+ resolveCheckpointDirectory,
25
26
  resumeTransport,
26
27
  } from "./cassette/index.ts";
27
28
  export type {
@@ -80,7 +81,9 @@ export {
80
81
  EMPTY_EFFECTIVE_CONFIG,
81
82
  loadEffectiveConfig,
82
83
  PROJECT_CONFIG_DIR,
84
+ projectConfigPath,
83
85
  resolveGlobalConfigDirectory,
86
+ resolveGlobalConfigPath,
84
87
  } from "./config/index.ts";
85
88
  export type {
86
89
  ControlCommand,
@@ -188,6 +191,7 @@ export type {
188
191
  CompactionInfo,
189
192
  EndedRunSummary,
190
193
  ExitedAgentInfo,
194
+ GroupInfo,
191
195
  IdleAgentInfo,
192
196
  ModelFallbackInfo,
193
197
  NodeInfo,
@@ -239,7 +243,10 @@ export type {
239
243
  AgentPolicy,
240
244
  AskOptions,
241
245
  ForkOptions,
246
+ Group,
247
+ GroupOptions,
242
248
  Handle,
249
+ HostSource,
243
250
  LiteralPromptText,
244
251
  PromptAudience,
245
252
  PromptText,