@yaag/runtime 0.18.2 → 0.20.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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yaag/runtime",
3
- "version": "0.18.2",
3
+ "version": "0.20.0",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -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
+ }
@@ -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
+ }
@@ -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 { type AgentDefinition, agentDefinitionConfig, isAgentDefinition } from "./define-agent.ts";
10
+ import type { AgentDefinition } from "./define-agent.ts";
9
11
  import { type ForkSpawner, forkRequest } from "./fork.ts";
10
- import { type OpenAgentContext, type OpenAgentRequest, openAgent } from "./spawn-open.ts";
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(context, resolveRequest(definitionOrOptions, overrides));
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
- }
@@ -164,6 +164,7 @@ const CassetteRunSchema = Type.Object({
164
164
  programSource: Type.Optional(Type.String()),
165
165
  args: Type.Optional(Type.Unknown()),
166
166
  programHash: Type.Optional(Type.String()),
167
+ profile: Type.Optional(Type.String()),
167
168
  });
168
169
 
169
170
  /**
@@ -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. */
@@ -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 { programIdentityWarning } from "./resume-identity.ts";
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 Divergence means and what to do about it. */
110
- const DOCS_POINTER = "; see @yaag/extension docs/troubleshooting.md#replay-or-resume-mismatch";
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})${DOCS_POINTER}`,
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}${DOCS_POINTER}`,
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 advisory comparison between a loaded Cassette's recorded program identity
3
- * and the program this Run executes (ADR-0033).
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
- /** Resolves what a resume re-executes. The program hash is advisory only. */
140
- export async function resolveRunIdentity(
141
- program: ProgramIdentity,
142
- args: unknown,
143
- ): Promise<RunIdentity> {
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
- if (programFile === undefined) return {};
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 { programFile, args, ...(programHash === null ? {} : { programHash }) };
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: "healthy" | "deviates" | "export-not-found" | "module-threw" | "not-a-definition";
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 three
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 three finding codes, in declaration order. */
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
  }