@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 +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
|
@@ -58,6 +58,9 @@ export type YaagErrorCode =
|
|
|
58
58
|
| "RECORD_PATH_UNUSABLE" // the --record directory could not be created at Run start
|
|
59
59
|
| "REPLAY_DIVERGED" // replayed program differed from its Cassette
|
|
60
60
|
| "RESUME_REFUSED" // resume metadata is absent or the recorded tree moved
|
|
61
|
+
| "PROFILE_NOT_FOUND" // a selected Profile is not declared by the program (ADR-0052)
|
|
62
|
+
| "PROFILE_REQUIRED" // a Profiled Definition was spawned by a program that declares no Profiles
|
|
63
|
+
| "ROLE_NOT_FOUND" // a factory read a Role the program does not declare
|
|
61
64
|
| "RUN_CLOSED" // spawn was requested after the Run began settling
|
|
62
65
|
| "RUN_STOPPED" // the Run's abort signal fired before the program completed
|
|
63
66
|
| "WORKTREE_REFUSED" // base cwd is not a clean Git repository
|
package/src/events.ts
CHANGED
|
@@ -56,6 +56,11 @@ export type LifecycleEventBody =
|
|
|
56
56
|
* outcome `interrupted`, so an observer can name the resume source.
|
|
57
57
|
*/
|
|
58
58
|
readonly artifact?: string;
|
|
59
|
+
/**
|
|
60
|
+
* Id of the Profile this Run activated (ADR-0052). Absent for a program
|
|
61
|
+
* that declares no Profiles, and for events from an older CLI.
|
|
62
|
+
*/
|
|
63
|
+
readonly profile?: string;
|
|
59
64
|
}
|
|
60
65
|
| {
|
|
61
66
|
readonly type: "agent_spawn";
|
|
@@ -81,6 +86,10 @@ export type LifecycleEventBody =
|
|
|
81
86
|
* Cassette-playback Agents; a renderer then shows the model alone.
|
|
82
87
|
*/
|
|
83
88
|
readonly thinking?: ThinkingLevel;
|
|
89
|
+
/** Id of the active Profile; present only on a profiled spawn, never on a fork. */
|
|
90
|
+
readonly profile?: string;
|
|
91
|
+
/** Roles the factory read, in order, duplicates kept; `[]` for none. */
|
|
92
|
+
readonly role?: readonly string[];
|
|
84
93
|
}
|
|
85
94
|
| {
|
|
86
95
|
readonly type: "ask_start";
|
package/src/index.ts
CHANGED
|
@@ -115,6 +115,26 @@ export {
|
|
|
115
115
|
NodeTracker,
|
|
116
116
|
sanitizeNodeName,
|
|
117
117
|
} from "./node/index.ts";
|
|
118
|
+
export type {
|
|
119
|
+
BindingBuilder,
|
|
120
|
+
ModelCandidate,
|
|
121
|
+
ProfileBuilder,
|
|
122
|
+
ProfiledDefinition,
|
|
123
|
+
Profiles,
|
|
124
|
+
ProfilesSnapshot,
|
|
125
|
+
ProfileView,
|
|
126
|
+
Role,
|
|
127
|
+
RoleBinding,
|
|
128
|
+
} from "./profile/index.ts";
|
|
129
|
+
// `selectProfile`, `profileViewRecorder` and `profiledDefinitionFactory` stay
|
|
130
|
+
// on `profile/index.ts`: the Run and the spawn gate use them, and no consumer
|
|
131
|
+
// outside this package does.
|
|
132
|
+
export {
|
|
133
|
+
defineProfiles,
|
|
134
|
+
isProfiledDefinition,
|
|
135
|
+
profilesSnapshot,
|
|
136
|
+
useProfile,
|
|
137
|
+
} from "./profile/index.ts";
|
|
118
138
|
export { prompt, promptGist } from "./prompt/index.ts";
|
|
119
139
|
export type {
|
|
120
140
|
OrchestrationProgram,
|
|
@@ -149,7 +169,9 @@ export type {
|
|
|
149
169
|
CompactionPlayback,
|
|
150
170
|
CompactionResult,
|
|
151
171
|
DiscoveredSkill,
|
|
172
|
+
FakeTransportOptions,
|
|
152
173
|
Frame,
|
|
174
|
+
OpenOptions,
|
|
153
175
|
ReapPath,
|
|
154
176
|
ReapTarget,
|
|
155
177
|
SkillProbeFactory,
|
|
@@ -159,7 +181,17 @@ export type {
|
|
|
159
181
|
TransportStartupObserver,
|
|
160
182
|
WorktreeResolution,
|
|
161
183
|
} from "./transport/index.ts";
|
|
162
|
-
|
|
184
|
+
// `FakeTransport` (with `FakeTransportOptions` and `OpenOptions`) is consumer-
|
|
185
|
+
// visible on purpose: another package in this repo runs a shipped example
|
|
186
|
+
// offline, and a fake stays with the interface it fakes (ADR-0011 amendment).
|
|
187
|
+
// It is not on the author surface: `public-api.ts` does not carry it, so no
|
|
188
|
+
// Orchestration Program can import it.
|
|
189
|
+
export {
|
|
190
|
+
FakeTransport,
|
|
191
|
+
readSystemPromptSidecar,
|
|
192
|
+
reap,
|
|
193
|
+
worktreeTransport,
|
|
194
|
+
} from "./transport/index.ts";
|
|
163
195
|
export type {
|
|
164
196
|
AskOptions,
|
|
165
197
|
ForkOptions,
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
import { lowerCandidate, type ModelCandidate } from "./lowering.ts";
|
|
2
|
+
|
|
3
|
+
export type { ModelCandidate } from "./lowering.ts";
|
|
4
|
+
|
|
5
|
+
/** Not exported, so a Role is opaque and traceable to the Profiles value that made it. */
|
|
6
|
+
const roleSymbol = Symbol("yaag.role");
|
|
7
|
+
/** Not exported, so only this directory reaches the declaration state. */
|
|
8
|
+
const stateSymbol = Symbol("yaag.profiles");
|
|
9
|
+
|
|
10
|
+
/** A declared Role. Opaque: only `bind()` reads it. */
|
|
11
|
+
export interface Role {
|
|
12
|
+
readonly [roleSymbol]: { readonly owner: ProfilesState; readonly name: string };
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/** Declares one Profile: its default provider and its Role Bindings. */
|
|
16
|
+
export interface ProfileBuilder {
|
|
17
|
+
/** Default provider for later object specs on this Profile. A repeat replaces it. */
|
|
18
|
+
provider(name: string): ProfileBuilder;
|
|
19
|
+
/** Opens a Role Binding. A second bind() of the same Role throws a TypeError. */
|
|
20
|
+
bind(role: Role): BindingBuilder;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** Declares the model candidates of one Role Binding. */
|
|
24
|
+
export interface BindingBuilder extends ProfileBuilder {
|
|
25
|
+
/** Replaces the Profile default provider, and keeps this Role Binding open. */
|
|
26
|
+
provider(name: string): BindingBuilder;
|
|
27
|
+
/** First candidate. Required. A second call throws a TypeError. */
|
|
28
|
+
model(spec: ModelCandidate): BindingBuilder;
|
|
29
|
+
/** Appends one candidate. Repeatable. Order is kept. Before model() throws a TypeError. */
|
|
30
|
+
fallback(spec: ModelCandidate): BindingBuilder;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** The value `defineProfiles()` returns and `defineRun({ profiles })` seals. */
|
|
34
|
+
export interface Profiles {
|
|
35
|
+
/** Declares a Role. A duplicate name throws a TypeError. */
|
|
36
|
+
role(name: string): Role;
|
|
37
|
+
/** Declares a Profile. A duplicate id throws a TypeError. */
|
|
38
|
+
register(profile: { readonly id: string }): ProfileBuilder;
|
|
39
|
+
readonly [stateSymbol]: ProfilesState;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** The sealed, frozen picture of a Profiles value: what describe prints. */
|
|
43
|
+
export interface ProfilesSnapshot {
|
|
44
|
+
/** The resolved default: `defaultProfile` when given, else the first registered id. */
|
|
45
|
+
readonly default: string;
|
|
46
|
+
/** Declared Role names, in declaration order. */
|
|
47
|
+
readonly roles: readonly string[];
|
|
48
|
+
/** Profile id to Role name to lowered model candidates. */
|
|
49
|
+
readonly entries: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
export interface BindingRecord {
|
|
53
|
+
readonly role: string;
|
|
54
|
+
hasModel: boolean;
|
|
55
|
+
readonly candidates: string[];
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
export interface ProfileRecord {
|
|
59
|
+
readonly id: string;
|
|
60
|
+
defaultProvider?: string;
|
|
61
|
+
readonly bindings: Map<string, BindingRecord>;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export interface ProfilesState {
|
|
65
|
+
readonly roles: string[];
|
|
66
|
+
readonly profiles: Map<string, ProfileRecord>;
|
|
67
|
+
sealed: boolean;
|
|
68
|
+
snapshot?: ProfilesSnapshot;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** Internal accessor: the declaration state behind a Profiles value, or undefined. */
|
|
72
|
+
export function profilesState(value: unknown): ProfilesState | undefined {
|
|
73
|
+
if (typeof value !== "object" || value === null || !(stateSymbol in value)) return undefined;
|
|
74
|
+
return (value as Profiles)[stateSymbol];
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
function assertUnsealed(state: ProfilesState, call: string): void {
|
|
78
|
+
if (state.sealed) {
|
|
79
|
+
throw new TypeError(`${call}: the Profiles value is sealed — declare it before defineRun`);
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
function roleName(state: ProfilesState, role: Role): string {
|
|
84
|
+
const identity = typeof role === "object" && role !== null ? role[roleSymbol] : undefined;
|
|
85
|
+
if (identity === undefined) {
|
|
86
|
+
throw new TypeError("bind: expected a Role from profiles.role(name)");
|
|
87
|
+
}
|
|
88
|
+
if (identity.owner !== state) {
|
|
89
|
+
throw new TypeError(`bind: Role "${identity.name}" belongs to another Profiles value`);
|
|
90
|
+
}
|
|
91
|
+
return identity.name;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
function bindingBuilder(
|
|
95
|
+
state: ProfilesState,
|
|
96
|
+
profile: ProfileRecord,
|
|
97
|
+
binding: BindingRecord,
|
|
98
|
+
): BindingBuilder {
|
|
99
|
+
const parent = profileBuilder(state, profile);
|
|
100
|
+
const builder: BindingBuilder = {
|
|
101
|
+
bind: parent.bind,
|
|
102
|
+
provider(name: string): BindingBuilder {
|
|
103
|
+
parent.provider(name);
|
|
104
|
+
return builder;
|
|
105
|
+
},
|
|
106
|
+
model(spec: ModelCandidate): BindingBuilder {
|
|
107
|
+
assertUnsealed(state, "model");
|
|
108
|
+
if (binding.hasModel) {
|
|
109
|
+
throw new TypeError(`model: Role "${binding.role}" already has a model on this Profile`);
|
|
110
|
+
}
|
|
111
|
+
binding.hasModel = true;
|
|
112
|
+
binding.candidates.push(lowerCandidate(spec, profile.defaultProvider));
|
|
113
|
+
return builder;
|
|
114
|
+
},
|
|
115
|
+
fallback(spec: ModelCandidate): BindingBuilder {
|
|
116
|
+
assertUnsealed(state, "fallback");
|
|
117
|
+
if (!binding.hasModel) {
|
|
118
|
+
throw new TypeError(`fallback: call model() before fallback() on Role "${binding.role}"`);
|
|
119
|
+
}
|
|
120
|
+
binding.candidates.push(lowerCandidate(spec, profile.defaultProvider));
|
|
121
|
+
return builder;
|
|
122
|
+
},
|
|
123
|
+
};
|
|
124
|
+
return Object.freeze(builder);
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
function profileBuilder(state: ProfilesState, profile: ProfileRecord): ProfileBuilder {
|
|
128
|
+
const builder: ProfileBuilder = {
|
|
129
|
+
provider(name: string): ProfileBuilder {
|
|
130
|
+
assertUnsealed(state, "provider");
|
|
131
|
+
profile.defaultProvider = name;
|
|
132
|
+
return builder;
|
|
133
|
+
},
|
|
134
|
+
bind(role: Role): BindingBuilder {
|
|
135
|
+
assertUnsealed(state, "bind");
|
|
136
|
+
const name = roleName(state, role);
|
|
137
|
+
if (profile.bindings.has(name)) {
|
|
138
|
+
throw new TypeError(`bind: Role "${name}" is already bound on Profile "${profile.id}"`);
|
|
139
|
+
}
|
|
140
|
+
const binding: BindingRecord = { role: name, hasModel: false, candidates: [] };
|
|
141
|
+
profile.bindings.set(name, binding);
|
|
142
|
+
return bindingBuilder(state, profile, binding);
|
|
143
|
+
},
|
|
144
|
+
};
|
|
145
|
+
return Object.freeze(builder);
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* Declares the Profiles of an Orchestration Program (ADR-0052).
|
|
150
|
+
*
|
|
151
|
+
* Every builder method throws a TypeError at the call that breaks a
|
|
152
|
+
* declaration rule, and every method throws once `defineRun` sealed the value.
|
|
153
|
+
*/
|
|
154
|
+
export function defineProfiles(): Profiles {
|
|
155
|
+
const state: ProfilesState = { roles: [], profiles: new Map(), sealed: false };
|
|
156
|
+
const profiles: Profiles = {
|
|
157
|
+
role(name: string): Role {
|
|
158
|
+
assertUnsealed(state, "role");
|
|
159
|
+
if (state.roles.includes(name)) {
|
|
160
|
+
throw new TypeError(`role: Role "${name}" is already declared`);
|
|
161
|
+
}
|
|
162
|
+
state.roles.push(name);
|
|
163
|
+
return Object.freeze({ [roleSymbol]: { owner: state, name } });
|
|
164
|
+
},
|
|
165
|
+
register(profile: { readonly id: string }): ProfileBuilder {
|
|
166
|
+
assertUnsealed(state, "register");
|
|
167
|
+
const { id } = profile;
|
|
168
|
+
if (state.profiles.has(id)) {
|
|
169
|
+
throw new TypeError(`register: Profile "${id}" is already registered`);
|
|
170
|
+
}
|
|
171
|
+
const record: ProfileRecord = { id, bindings: new Map() };
|
|
172
|
+
state.profiles.set(id, record);
|
|
173
|
+
return profileBuilder(state, record);
|
|
174
|
+
},
|
|
175
|
+
[stateSymbol]: state,
|
|
176
|
+
};
|
|
177
|
+
return Object.freeze(profiles);
|
|
178
|
+
}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Public surface of the `profile/` module: Profiles, Roles, Role Bindings and
|
|
3
|
+
* their lowering (ADR-0052).
|
|
4
|
+
*/
|
|
5
|
+
export type {
|
|
6
|
+
BindingBuilder,
|
|
7
|
+
ModelCandidate,
|
|
8
|
+
ProfileBuilder,
|
|
9
|
+
Profiles,
|
|
10
|
+
ProfilesSnapshot,
|
|
11
|
+
Role,
|
|
12
|
+
} from "./define-profiles.ts";
|
|
13
|
+
export { defineProfiles } from "./define-profiles.ts";
|
|
14
|
+
export type { ActiveProfile, ProfileViewRecorder } from "./profile-view.ts";
|
|
15
|
+
export { profileViewRecorder, roleNotFoundMessage } from "./profile-view.ts";
|
|
16
|
+
export { profilesSnapshot, sealProfiles } from "./seal.ts";
|
|
17
|
+
export { selectProfile } from "./select-profile.ts";
|
|
18
|
+
export type { ProfiledDefinition, ProfileView, RoleBinding } from "./use-profile.ts";
|
|
19
|
+
export {
|
|
20
|
+
isProfiledDefinition,
|
|
21
|
+
profiledDefinitionFactory,
|
|
22
|
+
useProfile,
|
|
23
|
+
} from "./use-profile.ts";
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import type { ThinkingLevel } from "../contract/index.ts";
|
|
2
|
+
|
|
3
|
+
/** One model candidate of a Role Binding, before lowering (ADR-0052). */
|
|
4
|
+
export type ModelCandidate =
|
|
5
|
+
| string
|
|
6
|
+
| { readonly provider?: string; readonly name: string; readonly thinking?: ThinkingLevel };
|
|
7
|
+
|
|
8
|
+
function isCandidateObject(
|
|
9
|
+
spec: ModelCandidate,
|
|
10
|
+
): spec is { provider?: string; name: string; thinking?: ThinkingLevel } {
|
|
11
|
+
return typeof spec === "object" && spec !== null;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Lowers one candidate of a Role Binding to the pattern string `AgentConfig.model` takes.
|
|
16
|
+
*
|
|
17
|
+
* A string is kept verbatim. An object takes its own `provider`, else the
|
|
18
|
+
* Profile default, else no prefix, and appends `:thinking` when set.
|
|
19
|
+
* Throws a TypeError for a value that is neither, or for a blank `name`.
|
|
20
|
+
*/
|
|
21
|
+
export function lowerCandidate(spec: ModelCandidate, defaultProvider: string | undefined): string {
|
|
22
|
+
if (typeof spec === "string") {
|
|
23
|
+
if (spec.trim() === "")
|
|
24
|
+
throw new TypeError("model candidate: a pattern string must not be blank");
|
|
25
|
+
return spec;
|
|
26
|
+
}
|
|
27
|
+
if (!isCandidateObject(spec)) {
|
|
28
|
+
throw new TypeError("model candidate: expected a pattern string or { name } object");
|
|
29
|
+
}
|
|
30
|
+
const { name, provider, thinking } = spec;
|
|
31
|
+
if (typeof name !== "string" || name.trim() === "") {
|
|
32
|
+
throw new TypeError("model candidate: name is required and must be non-empty");
|
|
33
|
+
}
|
|
34
|
+
const prefix = provider ?? defaultProvider;
|
|
35
|
+
const model = prefix === undefined ? name : `${prefix}/${name}`;
|
|
36
|
+
return thinking === undefined ? model : `${model}:${thinking}`;
|
|
37
|
+
}
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The runtime side of a Profile: the Profile a Run activated, and the recorded
|
|
3
|
+
* view a Profiled Definition factory reads (ADR-0052).
|
|
4
|
+
*/
|
|
5
|
+
import { YaagError } from "../errors.ts";
|
|
6
|
+
import type { ProfilesSnapshot } from "./define-profiles.ts";
|
|
7
|
+
import type { ProfileView, RoleBinding } from "./use-profile.ts";
|
|
8
|
+
|
|
9
|
+
/** The Profile a Run activated, plus the sealed bindings it reads. */
|
|
10
|
+
export interface ActiveProfile {
|
|
11
|
+
readonly id: string;
|
|
12
|
+
/** Role name to lowered model candidates, from the sealed snapshot. */
|
|
13
|
+
readonly bindings: Readonly<Record<string, readonly string[]>>;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Builds the Active Profile of one id from a sealed snapshot. One place, so the
|
|
18
|
+
* frozen shape and the empty-bindings fallback cannot drift between callers.
|
|
19
|
+
* `selectProfile` is the only caller: it owns which id a Run activates.
|
|
20
|
+
*/
|
|
21
|
+
export function activeProfileOf(snapshot: ProfilesSnapshot, id: string): ActiveProfile {
|
|
22
|
+
return Object.freeze({ id, bindings: snapshot.entries[id] ?? Object.freeze({}) });
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** A ProfileView plus the read log the spawn gate inspects after the factory returns. */
|
|
26
|
+
export interface ProfileViewRecorder {
|
|
27
|
+
readonly view: ProfileView;
|
|
28
|
+
/** Successful reads, in order, duplicates kept. */
|
|
29
|
+
readonly reads: readonly string[];
|
|
30
|
+
/** Undeclared reads; a non-empty list makes the spawn reject. */
|
|
31
|
+
readonly failures: readonly string[];
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** Message of the undeclared-Role rejection, in one place so docs can quote it. */
|
|
35
|
+
export function roleNotFoundMessage(name: string): string {
|
|
36
|
+
return `spawn: Role "${name}" is not declared by this program`;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** Builds a recording view of one active Profile. Each view serves one spawn. */
|
|
40
|
+
export function profileViewRecorder(active: ActiveProfile): ProfileViewRecorder {
|
|
41
|
+
const reads: string[] = [];
|
|
42
|
+
const failures: string[] = [];
|
|
43
|
+
const view: ProfileView = {
|
|
44
|
+
id: active.id,
|
|
45
|
+
role(name: string): RoleBinding {
|
|
46
|
+
const candidates = active.bindings[name];
|
|
47
|
+
if (candidates === undefined) {
|
|
48
|
+
failures.push(name);
|
|
49
|
+
throw new YaagError("ROLE_NOT_FOUND", roleNotFoundMessage(name));
|
|
50
|
+
}
|
|
51
|
+
reads.push(name);
|
|
52
|
+
return Object.freeze({ model: Object.freeze([...candidates]) });
|
|
53
|
+
},
|
|
54
|
+
};
|
|
55
|
+
return { view: Object.freeze(view), reads, failures };
|
|
56
|
+
}
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import type { ProfileRecord, ProfilesSnapshot, ProfilesState } from "./define-profiles.ts";
|
|
2
|
+
import { profilesState } from "./define-profiles.ts";
|
|
3
|
+
|
|
4
|
+
export type { ProfilesSnapshot } from "./define-profiles.ts";
|
|
5
|
+
|
|
6
|
+
/** What `defineRun` hands to the seal: the declared value and the chosen default. */
|
|
7
|
+
export interface SealRequest {
|
|
8
|
+
readonly profiles: unknown;
|
|
9
|
+
readonly defaultProfile?: string;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
function assertComplete(state: ProfilesState, profile: ProfileRecord): void {
|
|
13
|
+
for (const role of state.roles) {
|
|
14
|
+
const binding = profile.bindings.get(role);
|
|
15
|
+
if (binding === undefined) {
|
|
16
|
+
throw new TypeError(`defineRun: profile "${profile.id}" leaves Role "${role}" unbound`);
|
|
17
|
+
}
|
|
18
|
+
if (!binding.hasModel) {
|
|
19
|
+
throw new TypeError(
|
|
20
|
+
`defineRun: profile "${profile.id}" binds Role "${role}" with no model()`,
|
|
21
|
+
);
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
function buildSnapshot(state: ProfilesState, defaultProfile: string): ProfilesSnapshot {
|
|
27
|
+
const entries: Record<string, Readonly<Record<string, readonly string[]>>> = {};
|
|
28
|
+
for (const profile of state.profiles.values()) {
|
|
29
|
+
assertComplete(state, profile);
|
|
30
|
+
const roles: Record<string, readonly string[]> = {};
|
|
31
|
+
for (const role of state.roles) {
|
|
32
|
+
const binding = profile.bindings.get(role);
|
|
33
|
+
if (binding !== undefined) roles[role] = Object.freeze([...binding.candidates]);
|
|
34
|
+
}
|
|
35
|
+
entries[profile.id] = Object.freeze(roles);
|
|
36
|
+
}
|
|
37
|
+
return Object.freeze({
|
|
38
|
+
default: defaultProfile,
|
|
39
|
+
roles: Object.freeze([...state.roles]),
|
|
40
|
+
entries: Object.freeze(entries),
|
|
41
|
+
});
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Validates a Profiles value, seals it, and stores a frozen snapshot on it.
|
|
46
|
+
*
|
|
47
|
+
* Throws a TypeError when the value did not come from `defineProfiles`, when it
|
|
48
|
+
* registers zero Profiles, when a Profile leaves a Role unbound or binds one
|
|
49
|
+
* with no `model()`, or when `defaultProfile` names no registered Profile.
|
|
50
|
+
*
|
|
51
|
+
* A Profiles value carries one snapshot, so a second seal that resolves a
|
|
52
|
+
* different default throws too: two programs that shared the value would
|
|
53
|
+
* otherwise describe the same default, the one sealed last.
|
|
54
|
+
*/
|
|
55
|
+
export function sealProfiles(request: SealRequest): ProfilesSnapshot {
|
|
56
|
+
const state = profilesState(request.profiles);
|
|
57
|
+
if (state === undefined) {
|
|
58
|
+
throw new TypeError("defineRun: profiles must be a defineProfiles() value");
|
|
59
|
+
}
|
|
60
|
+
const [firstRegistered] = state.profiles.keys();
|
|
61
|
+
if (firstRegistered === undefined) {
|
|
62
|
+
throw new TypeError("defineRun: profiles registers no Profile — call register({ id })");
|
|
63
|
+
}
|
|
64
|
+
const { defaultProfile } = request;
|
|
65
|
+
if (defaultProfile !== undefined && !state.profiles.has(defaultProfile)) {
|
|
66
|
+
throw new TypeError(
|
|
67
|
+
`defineRun: defaultProfile "${defaultProfile}" names no registered Profile`,
|
|
68
|
+
);
|
|
69
|
+
}
|
|
70
|
+
const resolved = defaultProfile ?? firstRegistered;
|
|
71
|
+
const sealed = state.snapshot;
|
|
72
|
+
if (sealed !== undefined && sealed.default !== resolved) {
|
|
73
|
+
throw new TypeError(
|
|
74
|
+
`defineRun: these profiles are already sealed with default "${sealed.default}" — declare a Profiles value per program`,
|
|
75
|
+
);
|
|
76
|
+
}
|
|
77
|
+
const snapshot = buildSnapshot(state, resolved);
|
|
78
|
+
state.sealed = true;
|
|
79
|
+
state.snapshot = snapshot;
|
|
80
|
+
return snapshot;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* Reads the sealed snapshot of a Profiles value.
|
|
85
|
+
*
|
|
86
|
+
* Throws a TypeError when the value did not come from `defineProfiles`, or when
|
|
87
|
+
* no `defineRun` sealed it yet.
|
|
88
|
+
*/
|
|
89
|
+
export function profilesSnapshot(value: unknown): ProfilesSnapshot {
|
|
90
|
+
const state = profilesState(value);
|
|
91
|
+
if (state === undefined) {
|
|
92
|
+
throw new TypeError("not a Profiles value — build it with defineProfiles()");
|
|
93
|
+
}
|
|
94
|
+
if (state.snapshot === undefined) {
|
|
95
|
+
throw new TypeError("Profiles were never sealed — pass them to defineRun");
|
|
96
|
+
}
|
|
97
|
+
return state.snapshot;
|
|
98
|
+
}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Selects the Profile of one Run: the launch outranks the id a resumed Cassette
|
|
3
|
+
* stored, the stored id outranks a config preference, and a config preference
|
|
4
|
+
* outranks the program default (ADR-0052).
|
|
5
|
+
*/
|
|
6
|
+
import { YaagError } from "../errors.ts";
|
|
7
|
+
import type { Profiles } from "./define-profiles.ts";
|
|
8
|
+
import { type ActiveProfile, activeProfileOf } from "./profile-view.ts";
|
|
9
|
+
import { profilesSnapshot } from "./seal.ts";
|
|
10
|
+
|
|
11
|
+
/** What the Run knows about the Profile of this launch. */
|
|
12
|
+
export interface ProfileSelectionRequest {
|
|
13
|
+
/** The Profiles the program declares; absent for a program that declares none. */
|
|
14
|
+
readonly profiles: Profiles | undefined;
|
|
15
|
+
/** The id the launch selected: `--profile` or `yaag_run({ profile })`. */
|
|
16
|
+
readonly launch?: string;
|
|
17
|
+
/** The id the resumed Cassette recorded; it outranks a config preference (ADR-0052). */
|
|
18
|
+
readonly stored?: string;
|
|
19
|
+
/** The id the Effective Config selected, from the last layer that stated one. */
|
|
20
|
+
readonly config?: string;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** Where a stated Profile id came from; it names the origin in the rejection. */
|
|
24
|
+
type ProfileOrigin = "the launch" | "the cassette" | "a config file";
|
|
25
|
+
|
|
26
|
+
/** Message of the unknown-Profile rejection. */
|
|
27
|
+
function profileNotFoundMessage(
|
|
28
|
+
id: string,
|
|
29
|
+
known: readonly string[],
|
|
30
|
+
origin: ProfileOrigin,
|
|
31
|
+
): string {
|
|
32
|
+
return (
|
|
33
|
+
`run: profile "${id}" from ${origin} is not declared by this program` +
|
|
34
|
+
` — declared: ${known.join(", ")}`
|
|
35
|
+
);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** Message of a launch selection made on a program that declares no Profiles. */
|
|
39
|
+
function noProfilesMessage(id: string): string {
|
|
40
|
+
return `run: profile "${id}": this program declares no Profiles`;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Resolves the Active Profile of a Run, or rejects with `PROFILE_NOT_FOUND`.
|
|
45
|
+
*
|
|
46
|
+
* A config selection is a preference: it is ignored by a program that declares
|
|
47
|
+
* no Profiles, because a Global preference may not break an opt-out program. A
|
|
48
|
+
* launch selection is an instruction: it stops such a Run instead (ADR-0052).
|
|
49
|
+
*/
|
|
50
|
+
export function selectProfile(request: ProfileSelectionRequest): ActiveProfile | undefined {
|
|
51
|
+
const { profiles, launch, stored, config } = request;
|
|
52
|
+
if (profiles === undefined) {
|
|
53
|
+
if (launch !== undefined) throw new YaagError("PROFILE_NOT_FOUND", noProfilesMessage(launch));
|
|
54
|
+
// A resume of a program that dropped its Profiles must not fail on the
|
|
55
|
+
// stored id, and a config preference is ignored the same way.
|
|
56
|
+
return undefined;
|
|
57
|
+
}
|
|
58
|
+
const snapshot = profilesSnapshot(profiles);
|
|
59
|
+
const known = Object.keys(snapshot.entries);
|
|
60
|
+
// A resume keeps the Profile of the Run it continues unless the launch names one.
|
|
61
|
+
const stated = launch ?? stored ?? config;
|
|
62
|
+
const origin: ProfileOrigin =
|
|
63
|
+
launch !== undefined ? "the launch" : stored !== undefined ? "the cassette" : "a config file";
|
|
64
|
+
if (stated === undefined) return activeProfileOf(snapshot, snapshot.default);
|
|
65
|
+
if (!known.includes(stated)) {
|
|
66
|
+
throw new YaagError("PROFILE_NOT_FOUND", profileNotFoundMessage(stated, known, origin));
|
|
67
|
+
}
|
|
68
|
+
return activeProfileOf(snapshot, stated);
|
|
69
|
+
}
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The author surface of a Profiled Definition (ADR-0052).
|
|
3
|
+
*
|
|
4
|
+
* Types only beyond this module's own symbol: it is reachable from
|
|
5
|
+
* `public-api.ts`, so every value import here would grow the vendored
|
|
6
|
+
* declaration tree (ADR-0045).
|
|
7
|
+
*/
|
|
8
|
+
// `../agent/define-agent.ts` is a deep import on purpose, as `run-context.ts` does.
|
|
9
|
+
import type { AgentConfig } from "../agent/define-agent.ts";
|
|
10
|
+
|
|
11
|
+
/** What one Profile gives one Role. Today only `model`; later more Agent policy. */
|
|
12
|
+
export type RoleBinding = Partial<AgentConfig>;
|
|
13
|
+
|
|
14
|
+
/** The active Profile as a factory sees it. Every `role()` read is recorded. */
|
|
15
|
+
export interface ProfileView {
|
|
16
|
+
readonly id: string;
|
|
17
|
+
/** The Role Binding of this Profile. An undeclared name throws ROLE_NOT_FOUND. */
|
|
18
|
+
role(name: string): RoleBinding;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** Not exported, so the factory is unreachable outside this directory. */
|
|
22
|
+
const profiled = Symbol("yaag.profiled");
|
|
23
|
+
|
|
24
|
+
/** Opaque, frozen result of `useProfile`. It is not an Agent Definition. */
|
|
25
|
+
export interface ProfiledDefinition {
|
|
26
|
+
readonly [profiled]: (profile: ProfileView) => AgentConfig;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* Declares an Agent whose policy the active Profile completes.
|
|
31
|
+
*
|
|
32
|
+
* The factory runs once per spawn, with a view of the Profile the Run
|
|
33
|
+
* activated. Its result passes through `defineAgent`, so the ordinary
|
|
34
|
+
* definition rules still hold.
|
|
35
|
+
*/
|
|
36
|
+
export function useProfile(factory: (profile: ProfileView) => AgentConfig): ProfiledDefinition {
|
|
37
|
+
if (typeof factory !== "function") {
|
|
38
|
+
throw new TypeError("useProfile: expected a factory function (profile) => AgentConfig");
|
|
39
|
+
}
|
|
40
|
+
return Object.freeze({ [profiled]: factory });
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** True only for values produced by `useProfile`. */
|
|
44
|
+
export function isProfiledDefinition(value: unknown): value is ProfiledDefinition {
|
|
45
|
+
return typeof value === "object" && value !== null && profiled in value;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Recovers the factory behind a Profiled Definition.
|
|
50
|
+
* Throws a TypeError when the value did not come from `useProfile`.
|
|
51
|
+
*/
|
|
52
|
+
export function profiledDefinitionFactory(value: unknown): (profile: ProfileView) => AgentConfig {
|
|
53
|
+
if (!isProfiledDefinition(value)) {
|
|
54
|
+
throw new TypeError("not a Profiled Definition — build it with useProfile(factory)");
|
|
55
|
+
}
|
|
56
|
+
return value[profiled];
|
|
57
|
+
}
|
package/src/public-api.ts
CHANGED
|
@@ -22,6 +22,20 @@ export type {
|
|
|
22
22
|
} from "./contract/index.ts";
|
|
23
23
|
export type { YaagErrorCode } from "./errors.ts";
|
|
24
24
|
export { isYaagError, YaagError } from "./errors.ts";
|
|
25
|
+
export type {
|
|
26
|
+
BindingBuilder,
|
|
27
|
+
ModelCandidate,
|
|
28
|
+
ProfileBuilder,
|
|
29
|
+
Profiles,
|
|
30
|
+
Role,
|
|
31
|
+
} from "./profile/define-profiles.ts";
|
|
32
|
+
export { defineProfiles } from "./profile/define-profiles.ts";
|
|
33
|
+
export type {
|
|
34
|
+
ProfiledDefinition,
|
|
35
|
+
ProfileView,
|
|
36
|
+
RoleBinding,
|
|
37
|
+
} from "./profile/use-profile.ts";
|
|
38
|
+
export { isProfiledDefinition, useProfile } from "./profile/use-profile.ts";
|
|
25
39
|
export { prompt } from "./prompt/prompt.ts";
|
|
26
40
|
export type { OrchestrationProgram, ProgramDefinition } from "./run/define-run.ts";
|
|
27
41
|
export { defineRun } from "./run/define-run.ts";
|
package/src/run/define-run.ts
CHANGED
|
@@ -1,4 +1,8 @@
|
|
|
1
1
|
import type { Static, TSchema } from "typebox";
|
|
2
|
+
// Deep import: the author surface must not pull the profile/ directory index,
|
|
3
|
+
// which also holds runtime-only names (ADR-0045).
|
|
4
|
+
import type { Profiles } from "../profile/define-profiles.ts";
|
|
5
|
+
import { sealProfiles } from "../profile/seal.ts";
|
|
2
6
|
import type { RunContext } from "./run-context.ts";
|
|
3
7
|
|
|
4
8
|
/** What `defineRun` is given. */
|
|
@@ -7,6 +11,10 @@ export interface ProgramDefinition<Args = unknown, Result = unknown> {
|
|
|
7
11
|
readonly description?: string;
|
|
8
12
|
/** Optional Typebox contract for arguments delivered to `run`. */
|
|
9
13
|
readonly args?: TSchema;
|
|
14
|
+
/** Profiles declared with `defineProfiles()`. Absent means the program has no Profiles. */
|
|
15
|
+
readonly profiles?: Profiles;
|
|
16
|
+
/** Which Profile is active by default. Absent means the first registered Profile. */
|
|
17
|
+
readonly defaultProfile?: string;
|
|
10
18
|
readonly run: (ctx: RunContext<Args>) => Result | Promise<Result>;
|
|
11
19
|
}
|
|
12
20
|
|
|
@@ -45,6 +53,15 @@ export function defineRun<Args = unknown, Result = unknown>(
|
|
|
45
53
|
export function defineRun<Args, Result>(
|
|
46
54
|
program: ProgramDefinition<Args, Result>,
|
|
47
55
|
): OrchestrationProgram<Args, Result> {
|
|
56
|
+
if (program.defaultProfile !== undefined && program.profiles === undefined) {
|
|
57
|
+
throw new TypeError("defineRun: defaultProfile needs profiles");
|
|
58
|
+
}
|
|
59
|
+
if (program.profiles !== undefined) {
|
|
60
|
+
sealProfiles({
|
|
61
|
+
profiles: program.profiles,
|
|
62
|
+
...(program.defaultProfile === undefined ? {} : { defaultProfile: program.defaultProfile }),
|
|
63
|
+
});
|
|
64
|
+
}
|
|
48
65
|
return { [definition]: program };
|
|
49
66
|
}
|
|
50
67
|
|