@yaag/runtime 0.18.2 → 0.19.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 +1 -1
- package/src/agent/spawn-definition-request.ts +108 -0
- package/src/agent/spawn-open.ts +11 -0
- package/src/agent/spawn-profiled.ts +67 -0
- package/src/agent/spawn.ts +15 -95
- package/src/cassette/cassette-schema.ts +1 -0
- package/src/cassette/cassette.ts +2 -0
- package/src/cassette/index.ts +6 -1
- package/src/cassette/replay-divergence.ts +5 -4
- package/src/cassette/resume-identity.ts +61 -2
- package/src/cassette/run-checkpoint.ts +24 -8
- package/src/catalog/agent-describe-fixture.ts +21 -1
- package/src/catalog/agent-describe.ts +10 -3
- package/src/config/config-schema.ts +5 -0
- package/src/config/effective-config.ts +11 -0
- package/src/contract/error-codes.ts +3 -0
- package/src/events.ts +9 -0
- package/src/index.ts +33 -1
- package/src/profile/define-profiles.ts +178 -0
- package/src/profile/index.ts +23 -0
- package/src/profile/lowering.ts +37 -0
- package/src/profile/profile-view.ts +56 -0
- package/src/profile/seal.ts +98 -0
- package/src/profile/select-profile.ts +69 -0
- package/src/profile/use-profile.ts +57 -0
- package/src/public-api.ts +14 -0
- package/src/run/define-run.ts +17 -0
- package/src/run/run-context.ts +7 -0
- package/src/run/run.ts +43 -3
- package/src/summary/summary-agent.ts +14 -0
- package/src/summary/summary.ts +4 -0
package/package.json
CHANGED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* How a spawn request is built from a plain options object or an Agent
|
|
3
|
+
* Definition, with its override validation. Separate from `spawn.ts` so the
|
|
4
|
+
* profiled path can reuse it without a cycle.
|
|
5
|
+
*/
|
|
6
|
+
import type { SpawnOptions, SpawnOverrides } from "../types.ts";
|
|
7
|
+
import { type AgentDefinition, agentDefinitionConfig, isAgentDefinition } from "./define-agent.ts";
|
|
8
|
+
import type { OpenAgentRequest } from "./spawn-open.ts";
|
|
9
|
+
|
|
10
|
+
/** Topology overrides after validation; `parent` stays raw for `resolveParent`. */
|
|
11
|
+
type SpawnTopology = Omit<SpawnOverrides, "parent">;
|
|
12
|
+
|
|
13
|
+
type MutableSpawnOverrides = { -readonly [Key in keyof SpawnTopology]: SpawnTopology[Key] };
|
|
14
|
+
|
|
15
|
+
/** One validated override object: checked topology plus the unchecked Parent Link. */
|
|
16
|
+
interface ValidatedOverrides {
|
|
17
|
+
readonly topology: SpawnTopology;
|
|
18
|
+
readonly parent: unknown;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Builds the open request of one ordinary spawn.
|
|
23
|
+
*
|
|
24
|
+
* A plain options object passes through as topology. An Agent Definition
|
|
25
|
+
* supplies the policy, and the overrides supply the topology (ADR-0019).
|
|
26
|
+
* Throws a TypeError when the overrides are not an object, when they name a
|
|
27
|
+
* key that is not `name`, `cwd`, `worktree` or `parent`, or when one of those
|
|
28
|
+
* carries the wrong type. `parent` stays raw: `resolveParent` checks it.
|
|
29
|
+
*/
|
|
30
|
+
export function resolveRequest(
|
|
31
|
+
definitionOrOptions: SpawnOptions | AgentDefinition,
|
|
32
|
+
overrides: SpawnOverrides | undefined,
|
|
33
|
+
): OpenAgentRequest {
|
|
34
|
+
if (!isAgentDefinition(definitionOrOptions)) {
|
|
35
|
+
const { parent, ...spawnOptions } = definitionOrOptions;
|
|
36
|
+
return { spawnOptions, parent, askDefaults: undefined, definitionName: undefined };
|
|
37
|
+
}
|
|
38
|
+
const { topology, parent } = validateOverrides(overrides);
|
|
39
|
+
const config = agentDefinitionConfig(definitionOrOptions);
|
|
40
|
+
return {
|
|
41
|
+
spawnOptions: {
|
|
42
|
+
name: topology.name ?? config.name,
|
|
43
|
+
...(topology.cwd === undefined ? {} : { cwd: topology.cwd }),
|
|
44
|
+
...(topology.worktree === undefined ? {} : { worktree: topology.worktree }),
|
|
45
|
+
...(config.model === undefined ? {} : { model: config.model }),
|
|
46
|
+
...(config.thinking === undefined ? {} : { thinking: config.thinking }),
|
|
47
|
+
...(config.tools === undefined ? {} : { tools: config.tools }),
|
|
48
|
+
...(config.disallowedTools === undefined ? {} : { disallowedTools: config.disallowedTools }),
|
|
49
|
+
...(config.skills === undefined ? {} : { skills: config.skills }),
|
|
50
|
+
...(config.configExtensions === undefined
|
|
51
|
+
? {}
|
|
52
|
+
: { configExtensions: config.configExtensions }),
|
|
53
|
+
...(config.disallowedSkills === undefined
|
|
54
|
+
? {}
|
|
55
|
+
: { disallowedSkills: config.disallowedSkills }),
|
|
56
|
+
...(config.prompt === undefined
|
|
57
|
+
? {}
|
|
58
|
+
: config.overrideSystemPrompt === true
|
|
59
|
+
? { systemPrompt: config.prompt }
|
|
60
|
+
: { appendSystemPrompt: config.prompt }),
|
|
61
|
+
},
|
|
62
|
+
parent,
|
|
63
|
+
askDefaults: config.askDefaults,
|
|
64
|
+
definitionName: config.name,
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
function validateOverrides(overrides: unknown): ValidatedOverrides {
|
|
69
|
+
if (overrides === undefined) return { topology: {}, parent: undefined };
|
|
70
|
+
if (typeof overrides !== "object" || overrides === null || Array.isArray(overrides)) {
|
|
71
|
+
throw new TypeError(
|
|
72
|
+
"spawn overrides must be an object: definitions own policy and spawn overrides own topology",
|
|
73
|
+
);
|
|
74
|
+
}
|
|
75
|
+
for (const key of Object.keys(overrides)) {
|
|
76
|
+
if (key !== "name" && key !== "cwd" && key !== "worktree" && key !== "parent") {
|
|
77
|
+
throw new TypeError(
|
|
78
|
+
`spawn override "${key}" is not allowed: definitions own policy and spawn overrides own topology`,
|
|
79
|
+
);
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
const topology: MutableSpawnOverrides = {};
|
|
83
|
+
// `parent` is never narrowed here: `resolveParent` owns that check, so the
|
|
84
|
+
// error text stays in one place and no unchecked value becomes a Handle.
|
|
85
|
+
let parent: unknown;
|
|
86
|
+
for (const [key, value] of Object.entries(overrides)) {
|
|
87
|
+
if (key === "parent") parent = value;
|
|
88
|
+
if (key === "name") {
|
|
89
|
+
if (value !== undefined && typeof value !== "string") {
|
|
90
|
+
throw new TypeError('spawn override "name" must be a string when present');
|
|
91
|
+
}
|
|
92
|
+
topology.name = value;
|
|
93
|
+
}
|
|
94
|
+
if (key === "cwd") {
|
|
95
|
+
if (value !== undefined && typeof value !== "string") {
|
|
96
|
+
throw new TypeError('spawn override "cwd" must be a string when present');
|
|
97
|
+
}
|
|
98
|
+
topology.cwd = value;
|
|
99
|
+
}
|
|
100
|
+
if (key === "worktree") {
|
|
101
|
+
if (value !== undefined && typeof value !== "boolean") {
|
|
102
|
+
throw new TypeError('spawn override "worktree" must be a boolean when present');
|
|
103
|
+
}
|
|
104
|
+
topology.worktree = value;
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
return { topology, parent };
|
|
108
|
+
}
|
package/src/agent/spawn-open.ts
CHANGED
|
@@ -33,6 +33,14 @@ export interface OpenAgentRequest {
|
|
|
33
33
|
readonly definitionName: string | undefined;
|
|
34
34
|
/** Present only for a fork; adds `origin: "fork"` and the `--fork` source. */
|
|
35
35
|
readonly fork?: ForkIdentity;
|
|
36
|
+
/**
|
|
37
|
+
* Id of the active Profile, on a profiled spawn only. It rides the
|
|
38
|
+
* `agent_spawn` event alone: the transport-seam request and the Cassette
|
|
39
|
+
* spawn identity must stay byte-identical (ADR-0013).
|
|
40
|
+
*/
|
|
41
|
+
readonly profile?: string;
|
|
42
|
+
/** Roles the factory read, in order, duplicates kept; `[]` for none. */
|
|
43
|
+
readonly role?: readonly string[];
|
|
36
44
|
}
|
|
37
45
|
|
|
38
46
|
/** What the open path needs beyond the Run's spawn dependencies. */
|
|
@@ -180,6 +188,9 @@ export async function openAgent(
|
|
|
180
188
|
...(thinking === undefined ? {} : { thinking }),
|
|
181
189
|
...(parent === undefined ? {} : { parent }),
|
|
182
190
|
...(request.fork === undefined ? {} : { origin: "fork" as const }),
|
|
191
|
+
...(request.profile === undefined
|
|
192
|
+
? {}
|
|
193
|
+
: { profile: request.profile, role: request.role ?? [] }),
|
|
183
194
|
});
|
|
184
195
|
return agent;
|
|
185
196
|
} catch (error) {
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The spawn path of a Profiled Definition: it calls the factory once with the
|
|
3
|
+
* active Profile, checks what it read, and hands the result to the ordinary
|
|
4
|
+
* Definition path (ADR-0052).
|
|
5
|
+
*/
|
|
6
|
+
import { YaagError } from "../errors.ts";
|
|
7
|
+
import type { ActiveProfile, ProfiledDefinition } from "../profile/index.ts";
|
|
8
|
+
import {
|
|
9
|
+
profiledDefinitionFactory,
|
|
10
|
+
profileViewRecorder,
|
|
11
|
+
roleNotFoundMessage,
|
|
12
|
+
} from "../profile/index.ts";
|
|
13
|
+
import type { SpawnOverrides } from "../types.ts";
|
|
14
|
+
import type { AgentConfig } from "./define-agent.ts";
|
|
15
|
+
import { defineAgent } from "./define-agent.ts";
|
|
16
|
+
import { resolveRequest } from "./spawn-definition-request.ts";
|
|
17
|
+
import type { OpenAgentRequest } from "./spawn-open.ts";
|
|
18
|
+
|
|
19
|
+
/** Message of the rejection a program without Profiles gets, quoted by the docs. */
|
|
20
|
+
const PROFILE_REQUIRED_MESSAGE =
|
|
21
|
+
"spawn: this program declares no Profiles — a Profiled Definition needs defineRun({ profiles })";
|
|
22
|
+
|
|
23
|
+
function isConfigObject(value: unknown): value is AgentConfig {
|
|
24
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Builds the open request of one profiled spawn.
|
|
29
|
+
*
|
|
30
|
+
* An undeclared Role read rejects the spawn even when the factory caught the
|
|
31
|
+
* throw: a factory may not silently drop the policy a Profile owns. Any other
|
|
32
|
+
* factory error passes through unwrapped.
|
|
33
|
+
*/
|
|
34
|
+
export function profiledRequest(
|
|
35
|
+
active: ActiveProfile | undefined,
|
|
36
|
+
profiled: ProfiledDefinition,
|
|
37
|
+
overrides: SpawnOverrides | undefined,
|
|
38
|
+
): OpenAgentRequest {
|
|
39
|
+
if (active === undefined) {
|
|
40
|
+
throw new YaagError("PROFILE_REQUIRED", PROFILE_REQUIRED_MESSAGE);
|
|
41
|
+
}
|
|
42
|
+
const recorder = profileViewRecorder(active);
|
|
43
|
+
const factory = profiledDefinitionFactory(profiled);
|
|
44
|
+
let result: unknown;
|
|
45
|
+
let thrown: unknown;
|
|
46
|
+
let threw = false;
|
|
47
|
+
try {
|
|
48
|
+
result = factory(recorder.view);
|
|
49
|
+
} catch (error) {
|
|
50
|
+
threw = true;
|
|
51
|
+
thrown = error;
|
|
52
|
+
}
|
|
53
|
+
const [failed] = recorder.failures;
|
|
54
|
+
if (failed !== undefined) {
|
|
55
|
+
throw new YaagError("ROLE_NOT_FOUND", roleNotFoundMessage(failed));
|
|
56
|
+
}
|
|
57
|
+
if (threw) throw thrown;
|
|
58
|
+
if (!isConfigObject(result)) {
|
|
59
|
+
throw new TypeError("useProfile factory must return an AgentConfig object");
|
|
60
|
+
}
|
|
61
|
+
const definition = defineAgent(result);
|
|
62
|
+
return {
|
|
63
|
+
...resolveRequest(definition, overrides),
|
|
64
|
+
profile: active.id,
|
|
65
|
+
role: Object.freeze([...recorder.reads]),
|
|
66
|
+
};
|
|
67
|
+
}
|
package/src/agent/spawn.ts
CHANGED
|
@@ -1,13 +1,17 @@
|
|
|
1
1
|
import type { ConfigExtension } from "../config/index.ts";
|
|
2
2
|
import { YaagError } from "../errors.ts";
|
|
3
3
|
import type { EventSink } from "../events.ts";
|
|
4
|
+
import type { ActiveProfile, ProfiledDefinition } from "../profile/index.ts";
|
|
5
|
+
import { isProfiledDefinition } from "../profile/index.ts";
|
|
4
6
|
import type { RunContext } from "../run/index.ts";
|
|
5
7
|
import type { TransportFactory } from "../transport/index.ts";
|
|
6
8
|
import type { Handle, SpawnOptions, SpawnOverrides } from "../types.ts";
|
|
7
9
|
import type { Agent } from "./agent.ts";
|
|
8
|
-
import {
|
|
10
|
+
import type { AgentDefinition } from "./define-agent.ts";
|
|
9
11
|
import { type ForkSpawner, forkRequest } from "./fork.ts";
|
|
10
|
-
import {
|
|
12
|
+
import { resolveRequest } from "./spawn-definition-request.ts";
|
|
13
|
+
import { type OpenAgentContext, openAgent } from "./spawn-open.ts";
|
|
14
|
+
import { profiledRequest } from "./spawn-profiled.ts";
|
|
11
15
|
|
|
12
16
|
/** Dependencies for one Run's Agent-spawn gate. */
|
|
13
17
|
export interface SpawnDependencies {
|
|
@@ -18,6 +22,8 @@ export interface SpawnDependencies {
|
|
|
18
22
|
readonly programFile: string | undefined;
|
|
19
23
|
/** Effective Config entries, in merge order; empty when the Run has no config. */
|
|
20
24
|
readonly configExtensions: readonly ConfigExtension[];
|
|
25
|
+
/** The Profile this Run activated; absent for a program without Profiles. */
|
|
26
|
+
readonly profile?: ActiveProfile;
|
|
21
27
|
}
|
|
22
28
|
|
|
23
29
|
/** A RunContext spawn function that can synchronously stop accepting new Agents. */
|
|
@@ -54,11 +60,16 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
|
|
|
54
60
|
};
|
|
55
61
|
const context: OpenAgentContext = { ...deps, taken, forkSpawner };
|
|
56
62
|
const spawn: RunContext["spawn"] = async (
|
|
57
|
-
definitionOrOptions: SpawnOptions | AgentDefinition = {},
|
|
63
|
+
definitionOrOptions: SpawnOptions | AgentDefinition | ProfiledDefinition = {},
|
|
58
64
|
overrides?: SpawnOverrides,
|
|
59
65
|
): Promise<Handle> => {
|
|
60
66
|
if (closed) throw new YaagError("RUN_CLOSED", "run has already settled");
|
|
61
|
-
return openAgent(
|
|
67
|
+
return openAgent(
|
|
68
|
+
context,
|
|
69
|
+
isProfiledDefinition(definitionOrOptions)
|
|
70
|
+
? profiledRequest(deps.profile, definitionOrOptions, overrides)
|
|
71
|
+
: resolveRequest(definitionOrOptions, overrides),
|
|
72
|
+
);
|
|
62
73
|
};
|
|
63
74
|
return {
|
|
64
75
|
spawn,
|
|
@@ -67,94 +78,3 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
|
|
|
67
78
|
},
|
|
68
79
|
};
|
|
69
80
|
}
|
|
70
|
-
|
|
71
|
-
/** Topology overrides after validation; `parent` stays raw for `resolveParent`. */
|
|
72
|
-
type SpawnTopology = Omit<SpawnOverrides, "parent">;
|
|
73
|
-
|
|
74
|
-
type MutableSpawnOverrides = { -readonly [Key in keyof SpawnTopology]: SpawnTopology[Key] };
|
|
75
|
-
|
|
76
|
-
/** One validated override object: checked topology plus the unchecked Parent Link. */
|
|
77
|
-
interface ValidatedOverrides {
|
|
78
|
-
readonly topology: SpawnTopology;
|
|
79
|
-
readonly parent: unknown;
|
|
80
|
-
}
|
|
81
|
-
|
|
82
|
-
function resolveRequest(
|
|
83
|
-
definitionOrOptions: SpawnOptions | AgentDefinition,
|
|
84
|
-
overrides: SpawnOverrides | undefined,
|
|
85
|
-
): OpenAgentRequest {
|
|
86
|
-
if (!isAgentDefinition(definitionOrOptions)) {
|
|
87
|
-
const { parent, ...spawnOptions } = definitionOrOptions;
|
|
88
|
-
return { spawnOptions, parent, askDefaults: undefined, definitionName: undefined };
|
|
89
|
-
}
|
|
90
|
-
const { topology, parent } = validateOverrides(overrides);
|
|
91
|
-
const config = agentDefinitionConfig(definitionOrOptions);
|
|
92
|
-
return {
|
|
93
|
-
spawnOptions: {
|
|
94
|
-
name: topology.name ?? config.name,
|
|
95
|
-
...(topology.cwd === undefined ? {} : { cwd: topology.cwd }),
|
|
96
|
-
...(topology.worktree === undefined ? {} : { worktree: topology.worktree }),
|
|
97
|
-
...(config.model === undefined ? {} : { model: config.model }),
|
|
98
|
-
...(config.thinking === undefined ? {} : { thinking: config.thinking }),
|
|
99
|
-
...(config.tools === undefined ? {} : { tools: config.tools }),
|
|
100
|
-
...(config.disallowedTools === undefined ? {} : { disallowedTools: config.disallowedTools }),
|
|
101
|
-
...(config.skills === undefined ? {} : { skills: config.skills }),
|
|
102
|
-
...(config.configExtensions === undefined
|
|
103
|
-
? {}
|
|
104
|
-
: { configExtensions: config.configExtensions }),
|
|
105
|
-
...(config.disallowedSkills === undefined
|
|
106
|
-
? {}
|
|
107
|
-
: { disallowedSkills: config.disallowedSkills }),
|
|
108
|
-
...(config.prompt === undefined
|
|
109
|
-
? {}
|
|
110
|
-
: config.overrideSystemPrompt === true
|
|
111
|
-
? { systemPrompt: config.prompt }
|
|
112
|
-
: { appendSystemPrompt: config.prompt }),
|
|
113
|
-
},
|
|
114
|
-
parent,
|
|
115
|
-
askDefaults: config.askDefaults,
|
|
116
|
-
definitionName: config.name,
|
|
117
|
-
};
|
|
118
|
-
}
|
|
119
|
-
|
|
120
|
-
function validateOverrides(overrides: unknown): ValidatedOverrides {
|
|
121
|
-
if (overrides === undefined) return { topology: {}, parent: undefined };
|
|
122
|
-
if (typeof overrides !== "object" || overrides === null || Array.isArray(overrides)) {
|
|
123
|
-
throw new TypeError(
|
|
124
|
-
"spawn overrides must be an object: definitions own policy and spawn overrides own topology",
|
|
125
|
-
);
|
|
126
|
-
}
|
|
127
|
-
for (const key of Object.keys(overrides)) {
|
|
128
|
-
if (key !== "name" && key !== "cwd" && key !== "worktree" && key !== "parent") {
|
|
129
|
-
throw new TypeError(
|
|
130
|
-
`spawn override "${key}" is not allowed: definitions own policy and spawn overrides own topology`,
|
|
131
|
-
);
|
|
132
|
-
}
|
|
133
|
-
}
|
|
134
|
-
const topology: MutableSpawnOverrides = {};
|
|
135
|
-
// `parent` is never narrowed here: `resolveParent` owns that check, so the
|
|
136
|
-
// error text stays in one place and no unchecked value becomes a Handle.
|
|
137
|
-
let parent: unknown;
|
|
138
|
-
for (const [key, value] of Object.entries(overrides)) {
|
|
139
|
-
if (key === "parent") parent = value;
|
|
140
|
-
if (key === "name") {
|
|
141
|
-
if (value !== undefined && typeof value !== "string") {
|
|
142
|
-
throw new TypeError('spawn override "name" must be a string when present');
|
|
143
|
-
}
|
|
144
|
-
topology.name = value;
|
|
145
|
-
}
|
|
146
|
-
if (key === "cwd") {
|
|
147
|
-
if (value !== undefined && typeof value !== "string") {
|
|
148
|
-
throw new TypeError('spawn override "cwd" must be a string when present');
|
|
149
|
-
}
|
|
150
|
-
topology.cwd = value;
|
|
151
|
-
}
|
|
152
|
-
if (key === "worktree") {
|
|
153
|
-
if (value !== undefined && typeof value !== "boolean") {
|
|
154
|
-
throw new TypeError('spawn override "worktree" must be a boolean when present');
|
|
155
|
-
}
|
|
156
|
-
topology.worktree = value;
|
|
157
|
-
}
|
|
158
|
-
}
|
|
159
|
-
return { topology, parent };
|
|
160
|
-
}
|
package/src/cassette/cassette.ts
CHANGED
|
@@ -30,6 +30,8 @@ export interface CassetteRun {
|
|
|
30
30
|
readonly args?: unknown;
|
|
31
31
|
/** Advisory content hash of the program file, or of the inline source; SHA-256 hex. */
|
|
32
32
|
readonly programHash?: string;
|
|
33
|
+
/** Id of the active Profile; absent for a program with no Profiles and for an older Cassette. */
|
|
34
|
+
readonly profile?: string;
|
|
33
35
|
}
|
|
34
36
|
|
|
35
37
|
/** Versioned JSON artifact containing the frames exchanged during one Run. */
|
package/src/cassette/index.ts
CHANGED
|
@@ -27,13 +27,18 @@ export { createCheckpointFlusher, flushingSink } from "./checkpoint-flush.ts";
|
|
|
27
27
|
export { recordingTransport } from "./recording-transport.ts";
|
|
28
28
|
export { replayMismatch } from "./replay-divergence.ts";
|
|
29
29
|
export { replayTransport } from "./replay-transport.ts";
|
|
30
|
-
export {
|
|
30
|
+
export {
|
|
31
|
+
assertReplayProfile,
|
|
32
|
+
profileIdentityWarning,
|
|
33
|
+
programIdentityWarning,
|
|
34
|
+
} from "./resume-identity.ts";
|
|
31
35
|
export { resumeTransport } from "./resume-transport.ts";
|
|
32
36
|
export {
|
|
33
37
|
type ProgramIdentity,
|
|
34
38
|
prepareRecordDestination,
|
|
35
39
|
publishRunCheckpoint,
|
|
36
40
|
type RunCheckpointResult,
|
|
41
|
+
type RunIdentityRequest,
|
|
37
42
|
resolveRunIdentity,
|
|
38
43
|
writeRecordingDiagnostic,
|
|
39
44
|
} from "./run-checkpoint.ts";
|
|
@@ -106,8 +106,9 @@ export const replayMismatch = {
|
|
|
106
106
|
},
|
|
107
107
|
};
|
|
108
108
|
|
|
109
|
-
/** Where a user reads what a
|
|
110
|
-
const
|
|
109
|
+
/** Where a user reads what a replay or resume mismatch means and what to do about it. */
|
|
110
|
+
export const REPLAY_DOCS_POINTER =
|
|
111
|
+
"; see @yaag/extension docs/troubleshooting.md#replay-or-resume-mismatch";
|
|
111
112
|
|
|
112
113
|
/** Converts a detected mismatch into strict replay's public failure. */
|
|
113
114
|
export function strictReplay(mismatch: ReplayMismatch): never {
|
|
@@ -115,7 +116,7 @@ export function strictReplay(mismatch: ReplayMismatch): never {
|
|
|
115
116
|
const fields = mismatch.changedFields?.join(", ") ?? "hash inputs";
|
|
116
117
|
throw new YaagError(
|
|
117
118
|
"REPLAY_DIVERGED",
|
|
118
|
-
`replay diverged for agent "${mismatch.agent}" at ask #${mismatch.index}: definition "${mismatch.definitionName}" changed since recording (${fields})${
|
|
119
|
+
`replay diverged for agent "${mismatch.agent}" at ask #${mismatch.index}: definition "${mismatch.definitionName}" changed since recording (${fields})${REPLAY_DOCS_POINTER}`,
|
|
119
120
|
mismatch.agent,
|
|
120
121
|
);
|
|
121
122
|
}
|
|
@@ -127,7 +128,7 @@ export function strictReplay(mismatch: ReplayMismatch): never {
|
|
|
127
128
|
: "";
|
|
128
129
|
throw new YaagError(
|
|
129
130
|
"REPLAY_DIVERGED",
|
|
130
|
-
`replay diverged for agent "${mismatch.agent}" at ${at}:${changed} expected ${mismatch.expectedHash}, actual ${mismatch.actualHash}${
|
|
131
|
+
`replay diverged for agent "${mismatch.agent}" at ${at}:${changed} expected ${mismatch.expectedHash}, actual ${mismatch.actualHash}${REPLAY_DOCS_POINTER}`,
|
|
131
132
|
mismatch.agent,
|
|
132
133
|
);
|
|
133
134
|
}
|
|
@@ -1,11 +1,70 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The
|
|
3
|
-
*
|
|
2
|
+
* The comparisons between the invocation a Cassette recorded and the one this
|
|
3
|
+
* Run performs: the program (ADR-0033) and the active Profile (ADR-0052).
|
|
4
|
+
*
|
|
5
|
+
* The program comparison is advisory, and so is the Profile comparison of a
|
|
6
|
+
* resume: both warn once and let the Run continue. The Profile comparison of a
|
|
7
|
+
* strict replay is not: it refuses the Run with `REPLAY_DIVERGED`, because a
|
|
8
|
+
* strict replay re-executes one recorded invocation.
|
|
4
9
|
*/
|
|
10
|
+
import { YaagError } from "../errors.ts";
|
|
5
11
|
import type { Cassette } from "./cassette.ts";
|
|
6
12
|
import { sha256Hex } from "./program-hash.ts";
|
|
13
|
+
import { REPLAY_DOCS_POINTER } from "./replay-divergence.ts";
|
|
7
14
|
import type { ProgramIdentity } from "./run-checkpoint.ts";
|
|
8
15
|
|
|
16
|
+
/**
|
|
17
|
+
* Warns when a resumed Cassette recorded another Profile than the one this Run
|
|
18
|
+
* activates. Advisory: the resume continues under the Profile selected now, and
|
|
19
|
+
* the old id survives only in this trace. Silent for an artifact that records no
|
|
20
|
+
* Profile, because absent means unknown, not none.
|
|
21
|
+
*/
|
|
22
|
+
export function profileIdentityWarning(
|
|
23
|
+
cassette: Cassette,
|
|
24
|
+
path: string,
|
|
25
|
+
selected: string | undefined,
|
|
26
|
+
): string | null {
|
|
27
|
+
const mismatch = profileMismatch(cassette, path, selected);
|
|
28
|
+
if (mismatch === null) return null;
|
|
29
|
+
return `${mismatch}; a Role whose binding changed diverges at its spawn and runs live`;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* What both comparisons say about a changed Profile, or null when there is
|
|
34
|
+
* nothing to compare: an artifact that records no Profile states an unknown id,
|
|
35
|
+
* not the absence of one, so it matches every selection.
|
|
36
|
+
*/
|
|
37
|
+
function profileMismatch(
|
|
38
|
+
cassette: Cassette,
|
|
39
|
+
path: string,
|
|
40
|
+
selected: string | undefined,
|
|
41
|
+
): string | null {
|
|
42
|
+
const recorded = cassette.run.profile;
|
|
43
|
+
if (recorded === undefined || recorded === selected) return null;
|
|
44
|
+
return (
|
|
45
|
+
`cassette "${path}" recorded profile "${recorded}", ` +
|
|
46
|
+
`and this Run activates profile "${selected ?? "none"}"`
|
|
47
|
+
);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Refuses a strict replay whose Profile differs from the recorded one. A strict
|
|
52
|
+
* replay re-executes one recorded invocation, and the Profile is part of it.
|
|
53
|
+
* Skipped for an artifact that records no Profile.
|
|
54
|
+
*/
|
|
55
|
+
export function assertReplayProfile(
|
|
56
|
+
cassette: Cassette,
|
|
57
|
+
path: string,
|
|
58
|
+
selected: string | undefined,
|
|
59
|
+
): void {
|
|
60
|
+
const mismatch = profileMismatch(cassette, path, selected);
|
|
61
|
+
if (mismatch === null) return;
|
|
62
|
+
throw new YaagError(
|
|
63
|
+
"REPLAY_DIVERGED",
|
|
64
|
+
`replay diverged before the first spawn: ${mismatch}${REPLAY_DOCS_POINTER}`,
|
|
65
|
+
);
|
|
66
|
+
}
|
|
67
|
+
|
|
9
68
|
/**
|
|
10
69
|
* Warns when a Cassette's recorded program identity does not match the program
|
|
11
70
|
* this Run executes. Advisory only: the caller always supplies the program and
|
|
@@ -136,21 +136,37 @@ export interface ProgramIdentity {
|
|
|
136
136
|
readonly programSource?: string;
|
|
137
137
|
}
|
|
138
138
|
|
|
139
|
-
/**
|
|
140
|
-
export
|
|
141
|
-
program: ProgramIdentity
|
|
142
|
-
args: unknown
|
|
143
|
-
)
|
|
139
|
+
/** What one Run's invocation identity is made of: program, args, and Profile. */
|
|
140
|
+
export interface RunIdentityRequest {
|
|
141
|
+
readonly program: ProgramIdentity;
|
|
142
|
+
readonly args: unknown;
|
|
143
|
+
/** Active Profile id; part of invocation identity, resolved before this call (ADR-0052). */
|
|
144
|
+
readonly profile?: string;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* Resolves what a resume re-executes: the program, its args, and the active
|
|
149
|
+
* Profile. The program hash is advisory only.
|
|
150
|
+
*/
|
|
151
|
+
export async function resolveRunIdentity(request: RunIdentityRequest): Promise<RunIdentity> {
|
|
152
|
+
const { program, args, profile } = request;
|
|
153
|
+
const profileKey = profile === undefined ? {} : { profile };
|
|
144
154
|
// An Inline Program's file is a temporary path, and no artifact may name it,
|
|
145
155
|
// so the inline arm drops `programFile` even when the caller supplies one.
|
|
146
156
|
if (program.programSource !== undefined) {
|
|
147
157
|
const programSource = program.programSource;
|
|
148
|
-
return { programSource, args, programHash: sha256Hex(programSource) };
|
|
158
|
+
return { programSource, args, programHash: sha256Hex(programSource), ...profileKey };
|
|
149
159
|
}
|
|
150
160
|
const programFile = program.programFile;
|
|
151
|
-
|
|
161
|
+
// A Run with neither a program file nor inline source still has a Profile.
|
|
162
|
+
if (programFile === undefined) return { ...profileKey };
|
|
152
163
|
const programHash = await hashProgram(programFile);
|
|
153
|
-
return {
|
|
164
|
+
return {
|
|
165
|
+
programFile,
|
|
166
|
+
args,
|
|
167
|
+
...(programHash === null ? {} : { programHash }),
|
|
168
|
+
...profileKey,
|
|
169
|
+
};
|
|
154
170
|
}
|
|
155
171
|
|
|
156
172
|
/**
|
|
@@ -9,7 +9,13 @@ import {
|
|
|
9
9
|
/** One recorded describe exchange with the CLI child (ADR-0047). */
|
|
10
10
|
export interface AgentDescribeTranscriptEntry {
|
|
11
11
|
/** Names the case, so a consumer test can pick one by intent. */
|
|
12
|
-
readonly label:
|
|
12
|
+
readonly label:
|
|
13
|
+
| "healthy"
|
|
14
|
+
| "deviates"
|
|
15
|
+
| "export-not-found"
|
|
16
|
+
| "module-threw"
|
|
17
|
+
| "not-a-definition"
|
|
18
|
+
| "profiled-definition";
|
|
13
19
|
readonly argv: readonly string[];
|
|
14
20
|
/** Always `0`: a finding is a payload, not a failure. */
|
|
15
21
|
readonly code: 0;
|
|
@@ -20,6 +26,7 @@ export interface AgentDescribeTranscriptEntry {
|
|
|
20
26
|
|
|
21
27
|
const HEALTHY_FILE = "/repo/programs/agents/reviewer.ts";
|
|
22
28
|
const RENAMED_FILE = "/repo/programs/agents/renamed.ts";
|
|
29
|
+
const PROFILED_FILE = "/repo/programs/agents/planner.ts";
|
|
23
30
|
|
|
24
31
|
function record(
|
|
25
32
|
label: AgentDescribeTranscriptEntry["label"],
|
|
@@ -105,6 +112,19 @@ export const AGENT_DESCRIBE_TRANSCRIPT: readonly AgentDescribeTranscriptEntry[]
|
|
|
105
112
|
},
|
|
106
113
|
},
|
|
107
114
|
),
|
|
115
|
+
record(
|
|
116
|
+
"profiled-definition",
|
|
117
|
+
{ file: PROFILED_FILE, exportName: "plannerAgent" },
|
|
118
|
+
{
|
|
119
|
+
outcome: "finding",
|
|
120
|
+
file: PROFILED_FILE,
|
|
121
|
+
exportName: "plannerAgent",
|
|
122
|
+
finding: {
|
|
123
|
+
code: "PROFILED_DEFINITION",
|
|
124
|
+
detail: "the export is a Profiled Definition and has no static Agent metadata",
|
|
125
|
+
},
|
|
126
|
+
},
|
|
127
|
+
),
|
|
108
128
|
]);
|
|
109
129
|
|
|
110
130
|
/** Looks a recorded exchange up by the argv a fake child was called with. */
|
|
@@ -13,10 +13,15 @@
|
|
|
13
13
|
* surfaces still emit the Orchestration Program shape `{ name, description,
|
|
14
14
|
* args }`. The two shapes are separate documents, and nothing merges them.
|
|
15
15
|
*
|
|
16
|
-
* **A finding is not a failure.** The child exits `0` for each of the
|
|
16
|
+
* **A finding is not a failure.** The child exits `0` for each of the four
|
|
17
17
|
* finding codes. A non-zero exit stays reserved for a real CLI failure, such
|
|
18
18
|
* as bad argv, which exits 2.
|
|
19
19
|
*
|
|
20
|
+
* **A Profiled Definition is the fourth code.** An export that `useProfile`
|
|
21
|
+
* made is not an Agent Definition, and it holds no static metadata until a
|
|
22
|
+
* Profile is active (ADR-0052). The describe answers `PROFILED_DEFINITION`,
|
|
23
|
+
* and the caller reads the Profile to learn more.
|
|
24
|
+
*
|
|
20
25
|
* **`deviates` semantics.** The field is present only when the module's
|
|
21
26
|
* declared `name` differs from the Registry File entry's `name`. It is absent
|
|
22
27
|
* when the two names are equal, and absent when the caller supplied no
|
|
@@ -60,7 +65,8 @@ export interface NameDeviation {
|
|
|
60
65
|
export type AgentDescribeFindingCode =
|
|
61
66
|
| "EXPORT_NOT_FOUND"
|
|
62
67
|
| "MODULE_IMPORT_THREW"
|
|
63
|
-
| "NOT_AN_AGENT_DEFINITION"
|
|
68
|
+
| "NOT_AN_AGENT_DEFINITION"
|
|
69
|
+
| "PROFILED_DEFINITION";
|
|
64
70
|
|
|
65
71
|
export interface AgentDescribeFinding {
|
|
66
72
|
readonly code: AgentDescribeFindingCode;
|
|
@@ -92,11 +98,12 @@ export interface AgentDescribeFindingResult {
|
|
|
92
98
|
/** A described Definition, or one finding. Never both. */
|
|
93
99
|
export type AgentDescribeResult = DescribedAgent | AgentDescribeFindingResult;
|
|
94
100
|
|
|
95
|
-
/** The
|
|
101
|
+
/** The four finding codes, in declaration order. */
|
|
96
102
|
export const AGENT_DESCRIBE_FINDING_CODES: readonly AgentDescribeFindingCode[] = Object.freeze([
|
|
97
103
|
"EXPORT_NOT_FOUND",
|
|
98
104
|
"MODULE_IMPORT_THREW",
|
|
99
105
|
"NOT_AN_AGENT_DEFINITION",
|
|
106
|
+
"PROFILED_DEFINITION",
|
|
100
107
|
] as const);
|
|
101
108
|
|
|
102
109
|
/**
|
|
@@ -8,6 +8,10 @@ import { type Static, Type } from "typebox";
|
|
|
8
8
|
* opposite choice from `cassette-schema.ts`, which tolerates unknown fields so
|
|
9
9
|
* a newer artifact still loads. A config file is hand-written, so an unknown
|
|
10
10
|
* key is a typo the author wants named, not forward compatibility.
|
|
11
|
+
*
|
|
12
|
+
* `profile` is the one top-level scalar key. Unlike `agents.extensions`, which
|
|
13
|
+
* concatenates across the layers, it does not concatenate: the last layer that
|
|
14
|
+
* states it wins (ADR-0052).
|
|
11
15
|
*/
|
|
12
16
|
export const YaagConfigSchema = Type.Object(
|
|
13
17
|
{
|
|
@@ -17,6 +21,7 @@ export const YaagConfigSchema = Type.Object(
|
|
|
17
21
|
{ additionalProperties: false },
|
|
18
22
|
),
|
|
19
23
|
),
|
|
24
|
+
profile: Type.Optional(Type.String()),
|
|
20
25
|
},
|
|
21
26
|
{ additionalProperties: false },
|
|
22
27
|
);
|
|
@@ -25,6 +25,11 @@ export interface EffectiveConfig {
|
|
|
25
25
|
readonly extensions: readonly ConfigExtension[];
|
|
26
26
|
/** Config files that contributed, in merge order. */
|
|
27
27
|
readonly files: readonly string[];
|
|
28
|
+
/**
|
|
29
|
+
* The Profile id the last layer that stated one selected (ADR-0052); absent
|
|
30
|
+
* when no layer stated one.
|
|
31
|
+
*/
|
|
32
|
+
readonly profile?: string;
|
|
28
33
|
}
|
|
29
34
|
|
|
30
35
|
/** What to discover and read. */
|
|
@@ -109,8 +114,14 @@ function mergeLayers(found: readonly LoadedLayer[]): EffectiveConfig {
|
|
|
109
114
|
}),
|
|
110
115
|
),
|
|
111
116
|
);
|
|
117
|
+
// Last wins, in merge order: a Profile selection replaces, it never appends.
|
|
118
|
+
const profile = found.reduce<string | undefined>(
|
|
119
|
+
(last, { layer }) => layer.document.profile ?? last,
|
|
120
|
+
undefined,
|
|
121
|
+
);
|
|
112
122
|
return Object.freeze({
|
|
113
123
|
extensions: Object.freeze(extensions),
|
|
114
124
|
files: Object.freeze(found.map(({ layer }) => layer.file)),
|
|
125
|
+
...(profile === undefined ? {} : { profile }),
|
|
115
126
|
});
|
|
116
127
|
}
|