@yaag/runtime 0.23.0 → 0.25.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/fork.ts +7 -0
- package/src/agent/index.ts +1 -0
- package/src/agent/spawn-open.ts +24 -5
- package/src/agent/spawn-request.ts +123 -3
- package/src/agent/spawn.ts +13 -7
- package/src/agent/spawnable-definition.ts +9 -0
- package/src/ask/ask-hash.ts +7 -0
- package/src/catalog/index.ts +5 -3
- package/src/catalog/resolve.ts +184 -0
- package/src/contract/agent-policy.ts +15 -4
- package/src/contract/catalog-resolve.ts +33 -0
- package/src/contract/error-codes.ts +4 -1
- package/src/contract/index.ts +20 -2
- package/src/contract/spawn-options.ts +7 -1
- package/src/contract/system-prompt.ts +88 -0
- package/src/errors.ts +8 -2
- package/src/index.ts +20 -1
- package/src/public-api.ts +17 -0
- package/src/run/run-context.ts +8 -1
- package/src/run/run.ts +3 -0
- package/src/system-prompt/agent-prompt-extension.ts +337 -0
- package/src/system-prompt/agent-prompt.ts +15 -0
- package/src/system-prompt/agent-system-prompt.ts +90 -0
- package/src/system-prompt/append-channel.ts +69 -0
- package/src/system-prompt/define-system-prompt.ts +112 -0
- package/src/system-prompt/index.ts +48 -0
- package/src/system-prompt/prompt-guards.ts +60 -0
- package/src/system-prompt/render-sentinel.ts +75 -0
- package/src/transport/append-env.ts +69 -0
- package/src/transport/index.ts +2 -0
- package/src/transport/live-transport.ts +50 -26
- package/src/transport/pi-state.ts +38 -4
- package/src/transport/transport.ts +4 -1
- package/src/types.ts +8 -0
package/package.json
CHANGED
package/src/agent/fork.ts
CHANGED
|
@@ -45,6 +45,12 @@ export interface ForkRequest {
|
|
|
45
45
|
readonly askDefaults: AskOptions | undefined;
|
|
46
46
|
readonly fork: ForkIdentity;
|
|
47
47
|
readonly compact: boolean | string | undefined;
|
|
48
|
+
/**
|
|
49
|
+
* True when the fork carries the text its source already rendered. An
|
|
50
|
+
* explicit `fork({ systemPrompt: … })` override is author-written and stays
|
|
51
|
+
* guarded (ADR-0060).
|
|
52
|
+
*/
|
|
53
|
+
readonly inheritedPrompt: boolean;
|
|
48
54
|
}
|
|
49
55
|
|
|
50
56
|
/**
|
|
@@ -73,6 +79,7 @@ export function forkRequest(source: ForkSource, overrides?: ForkOptions): ForkRe
|
|
|
73
79
|
...(source.worktree === undefined ? {} : { worktreeFrom: source.worktree }),
|
|
74
80
|
},
|
|
75
81
|
compact,
|
|
82
|
+
inheritedPrompt: explicit.systemPrompt === undefined && inherited.systemPrompt !== undefined,
|
|
76
83
|
};
|
|
77
84
|
}
|
|
78
85
|
|
package/src/agent/index.ts
CHANGED
package/src/agent/spawn-open.ts
CHANGED
|
@@ -20,7 +20,12 @@ import type { ForkIdentity, ForkSpawner } from "./fork.ts";
|
|
|
20
20
|
import type { SpawnDependencies } from "./spawn.ts";
|
|
21
21
|
import { resolveSpawnExtensions } from "./spawn-extensions.ts";
|
|
22
22
|
import { resolveParent } from "./spawn-parent.ts";
|
|
23
|
-
import {
|
|
23
|
+
import {
|
|
24
|
+
openRequest,
|
|
25
|
+
type RenderedSpawnOptions,
|
|
26
|
+
renderPolicyPrompt,
|
|
27
|
+
withSelection,
|
|
28
|
+
} from "./spawn-request.ts";
|
|
24
29
|
|
|
25
30
|
/** One request the open path serves: a plain spawn, or a fork of another Agent. */
|
|
26
31
|
export interface OpenAgentRequest {
|
|
@@ -31,6 +36,8 @@ export interface OpenAgentRequest {
|
|
|
31
36
|
readonly askDefaults: AskOptions | undefined;
|
|
32
37
|
/** Definition identity stays separate from a topology-overridden Agent name. */
|
|
33
38
|
readonly definitionName: string | undefined;
|
|
39
|
+
/** The prompt is a fork's inherited rendered text, not author-written. */
|
|
40
|
+
readonly inheritedPrompt?: boolean;
|
|
34
41
|
/** Present only for a fork; adds `origin: "fork"` and the `--fork` source. */
|
|
35
42
|
readonly fork?: ForkIdentity;
|
|
36
43
|
/**
|
|
@@ -72,11 +79,18 @@ export async function openAgent(
|
|
|
72
79
|
// append to it, so a resolver sees every candidate that already failed.
|
|
73
80
|
const history = new ModelErrorHistory();
|
|
74
81
|
try {
|
|
82
|
+
// The Prompt Definition renders once, above every other spawn step, so the
|
|
83
|
+
// peek, the fallback loop and every attempt share one text (ADR-0064).
|
|
84
|
+
const rendered: RenderedSpawnOptions = renderPolicyPrompt({
|
|
85
|
+
options: request.spawnOptions,
|
|
86
|
+
agent: { name, runName: deps.runName },
|
|
87
|
+
...(request.inheritedPrompt === true ? { inheritedPrompt: true } : {}),
|
|
88
|
+
});
|
|
75
89
|
// Extension paths do not vary per candidate, so a bad path fails once, generically.
|
|
76
90
|
const extensions = await resolveSpawnExtensions({
|
|
77
91
|
configExtensions: deps.configExtensions,
|
|
78
|
-
declared:
|
|
79
|
-
useConfigExtensions:
|
|
92
|
+
declared: rendered.extensions,
|
|
93
|
+
useConfigExtensions: rendered.configExtensions !== false,
|
|
80
94
|
...(deps.programFile === undefined ? {} : { programFile: deps.programFile }),
|
|
81
95
|
projectRoot: cwd,
|
|
82
96
|
}).catch((error: unknown) => {
|
|
@@ -107,11 +121,12 @@ export async function openAgent(
|
|
|
107
121
|
const attempt = async (
|
|
108
122
|
selection: ModelSelection,
|
|
109
123
|
): Promise<{ opened: OpenedTransport; spawnOptions: ResolvedSpawnOptions }> => {
|
|
110
|
-
const settled = withSelection(
|
|
124
|
+
const settled = withSelection(rendered, selection);
|
|
111
125
|
return {
|
|
112
126
|
opened: await openTransport({
|
|
113
127
|
factory: deps.factory,
|
|
114
128
|
name,
|
|
129
|
+
runName: deps.runName,
|
|
115
130
|
cwd,
|
|
116
131
|
spawnOptions: settled,
|
|
117
132
|
...extensionFields,
|
|
@@ -127,8 +142,9 @@ export async function openAgent(
|
|
|
127
142
|
const recorded = deps.factory.recordedSpawn?.(
|
|
128
143
|
openRequest({
|
|
129
144
|
name,
|
|
145
|
+
runName: deps.runName,
|
|
130
146
|
cwd,
|
|
131
|
-
spawnOptions:
|
|
147
|
+
spawnOptions: rendered,
|
|
132
148
|
...extensionFields,
|
|
133
149
|
...forkFields,
|
|
134
150
|
...(parent === undefined ? {} : { parent }),
|
|
@@ -213,6 +229,8 @@ function isSpawnFailure(error: unknown): error is YaagError {
|
|
|
213
229
|
interface OpenTransportOptions {
|
|
214
230
|
readonly factory: TransportFactory;
|
|
215
231
|
readonly name: string;
|
|
232
|
+
/** The Run name; the peek and the open must pass the same one (ADR-0013). */
|
|
233
|
+
readonly runName: string;
|
|
216
234
|
readonly cwd: string;
|
|
217
235
|
readonly spawnOptions: ResolvedSpawnOptions;
|
|
218
236
|
readonly resolvedExtensionPaths?: readonly string[];
|
|
@@ -237,6 +255,7 @@ async function openTransport(options: OpenTransportOptions): Promise<OpenedTrans
|
|
|
237
255
|
const transport = await options.factory.open(
|
|
238
256
|
openRequest({
|
|
239
257
|
name: options.name,
|
|
258
|
+
runName: options.runName,
|
|
240
259
|
cwd: options.cwd,
|
|
241
260
|
spawnOptions: options.spawnOptions,
|
|
242
261
|
...(options.resolvedExtensionPaths === undefined
|
|
@@ -1,12 +1,105 @@
|
|
|
1
|
+
import type { SystemPromptAgent } from "../contract/index.ts";
|
|
2
|
+
import { YaagError } from "../errors.ts";
|
|
1
3
|
import type { ModelSelection } from "../model/index.ts";
|
|
4
|
+
import {
|
|
5
|
+
assertKnownSentinels,
|
|
6
|
+
assertNoLeakedSentinel,
|
|
7
|
+
dropsProgramAppend,
|
|
8
|
+
isSystemPromptDefinition,
|
|
9
|
+
programAppendWarning,
|
|
10
|
+
renderSystemPrompt,
|
|
11
|
+
yaagSystemPrompt,
|
|
12
|
+
} from "../system-prompt/index.ts";
|
|
2
13
|
import type { OpenOptions, WorktreeResolution } from "../transport/index.ts";
|
|
3
14
|
import type { ResolvedSpawnOptions, SpawnOptions } from "../types.ts";
|
|
4
15
|
|
|
16
|
+
/** Spawn options whose `systemPrompt`, if set, is already a plain string. */
|
|
17
|
+
export type RenderedSpawnOptions = Omit<SpawnOptions, "systemPrompt"> & {
|
|
18
|
+
readonly systemPrompt?: string;
|
|
19
|
+
};
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Renders a Prompt Definition into its text, once per spawn (ADR-0064).
|
|
23
|
+
*
|
|
24
|
+
* The open path calls this above every other spawn step, so the peek, the model
|
|
25
|
+
* fallback loop and every attempt share one rendered text and the builder runs
|
|
26
|
+
* exactly once. Options with no prompt, or with a plain string, pass through
|
|
27
|
+
* untouched: rendering only replaces a definition with its string and never
|
|
28
|
+
* fills the default.
|
|
29
|
+
*
|
|
30
|
+
* This seam is also where a leaked or an unknown Render Sentinel rejects the
|
|
31
|
+
* spawn, before any Agent process starts (ADR-0060, ADR-0063), and where a
|
|
32
|
+
* spawn whose prompt drops `appendSystemPrompt` writes its one warning.
|
|
33
|
+
*/
|
|
34
|
+
export function renderPolicyPrompt(request: RenderPolicyPromptOptions): RenderedSpawnOptions {
|
|
35
|
+
const { options, agent } = request;
|
|
36
|
+
const warn = request.warn ?? writeSpawnDiagnostic;
|
|
37
|
+
// The one place the guard policy lives: both branches below route through it,
|
|
38
|
+
// so the append warning cannot drift between a string and a definition.
|
|
39
|
+
const guard = (text: string, rendered: boolean): string => {
|
|
40
|
+
// Text yaag rendered itself — a definition's output, or a fork's inherited
|
|
41
|
+
// string — legitimately holds sentinels, so the leak guard must not fire.
|
|
42
|
+
if (rendered) assertKnownSentinels(text, agent.name);
|
|
43
|
+
else assertNoLeakedSentinel(text, agent.name);
|
|
44
|
+
if (options.appendSystemPrompt !== undefined && dropsProgramAppend(text)) {
|
|
45
|
+
warn(programAppendWarning(agent.name));
|
|
46
|
+
}
|
|
47
|
+
return text;
|
|
48
|
+
};
|
|
49
|
+
// Destructured rather than cast: `rest` has no `systemPrompt` at all, so each
|
|
50
|
+
// branch below builds the rendered shape from proven parts. An absent prompt
|
|
51
|
+
// stays absent, and no key with an `undefined` value enters recorded options.
|
|
52
|
+
const { systemPrompt: value, ...rest } = options;
|
|
53
|
+
// The default Agent System Prompt fills later in `openRequest`, and it always
|
|
54
|
+
// carries the `programAppend` sentinel, so no guard and no warning is due.
|
|
55
|
+
if (value === undefined) return rest;
|
|
56
|
+
if (typeof value === "string") {
|
|
57
|
+
return { ...rest, systemPrompt: guard(value, request.inheritedPrompt === true) };
|
|
58
|
+
}
|
|
59
|
+
if (!isSystemPromptDefinition(value)) {
|
|
60
|
+
throw new YaagError(
|
|
61
|
+
"SPAWN_FAILED",
|
|
62
|
+
`agent "${agent.name}": systemPrompt must be a string or a defineSystemPrompt definition`,
|
|
63
|
+
agent.name,
|
|
64
|
+
);
|
|
65
|
+
}
|
|
66
|
+
return { ...rest, systemPrompt: guard(renderSystemPrompt({ definition: value, agent }), true) };
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Writes one spawn diagnostic line, best effort.
|
|
71
|
+
*
|
|
72
|
+
* Own writer rather than the recording one: `cassette/` is the wrong owner for
|
|
73
|
+
* a spawn diagnostic, and a closed stderr must never fail a spawn.
|
|
74
|
+
*/
|
|
75
|
+
function writeSpawnDiagnostic(line: string): void {
|
|
76
|
+
try {
|
|
77
|
+
process.stderr.write(`${line}\n`);
|
|
78
|
+
} catch {
|
|
79
|
+
// best effort
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/** What one prompt render needs: the options, the Agent, and where a warning goes. */
|
|
84
|
+
export interface RenderPolicyPromptOptions {
|
|
85
|
+
readonly options: SpawnOptions;
|
|
86
|
+
readonly agent: SystemPromptAgent;
|
|
87
|
+
/**
|
|
88
|
+
* True when `systemPrompt` is the text a fork's source already rendered. The
|
|
89
|
+
* leak guard is then skipped: the sentinels in it are yaag's own.
|
|
90
|
+
*/
|
|
91
|
+
readonly inheritedPrompt?: boolean;
|
|
92
|
+
/** Where one warning line goes; the seam's own stderr writer by default. */
|
|
93
|
+
readonly warn?: (line: string) => void;
|
|
94
|
+
}
|
|
95
|
+
|
|
5
96
|
/** Everything one spawn needs to build its open request, before a model settles. */
|
|
6
97
|
export interface OpenRequestOptions {
|
|
7
98
|
readonly name: string;
|
|
99
|
+
/** The Run name, printed in the Agent System Prompt; `run_start.program`. */
|
|
100
|
+
readonly runName: string;
|
|
8
101
|
readonly cwd: string;
|
|
9
|
-
readonly spawnOptions:
|
|
102
|
+
readonly spawnOptions: RenderedSpawnOptions;
|
|
10
103
|
readonly resolvedExtensionPaths?: readonly string[];
|
|
11
104
|
readonly declaredExtensions?: readonly string[];
|
|
12
105
|
/** Resolved parent Agent name (Parent Link); spawn identity only, never argv. */
|
|
@@ -28,6 +121,31 @@ export interface OpenRequestOptions {
|
|
|
28
121
|
* array or resolver spec. That request is what a Cassette-backed factory peeks
|
|
29
122
|
* at, which is why the resume peek blanks model and thinking before it compares
|
|
30
123
|
* the request with the recorded spawn (ADR-0039).
|
|
124
|
+
*
|
|
125
|
+
* A spawn that sets no `systemPrompt` gets the Agent System Prompt here, so the
|
|
126
|
+
* consumers downstream of this seam — the Cassette spawn options, the replay
|
|
127
|
+
* divergence fields, and the Run record — see a plain string (ADR-0055,
|
|
128
|
+
* ADR-0064).
|
|
129
|
+
*
|
|
130
|
+
* The **Ask hash is deliberately not one of them.** `askHash` reads
|
|
131
|
+
* `ResolvedSpawnOptions`, the output of `withSelection`, which this function
|
|
132
|
+
* never touches, so a default spawn hashes `systemPrompt: null` while its spawn
|
|
133
|
+
* identity records the rendered text. That is on purpose: the default text
|
|
134
|
+
* prints `Agent: <name>` and `Run: <runName>`, so feeding it to `askHash` would
|
|
135
|
+
* make Ask identity depend on the Agent name and the Run name — exactly the two
|
|
136
|
+
* things `askMarkerContext` strips from Ask identity. Nothing is lost, because
|
|
137
|
+
* spawn identity already covers the prompt (`replay-divergence.ts`), and a
|
|
138
|
+
* changed prompt therefore diverges at spawn rather than at Ask 0.
|
|
139
|
+
*
|
|
140
|
+
* A value the program did set travels literally. Note the empty string is a
|
|
141
|
+
* value a program set and it survives this seam unchanged, but `piCommand`
|
|
142
|
+
* tests `options.systemPrompt` for truthiness, so `""` drops `--system-prompt`
|
|
143
|
+
* and the Agent falls back to pi's own prompt. The guarantee here is a seam
|
|
144
|
+
* guarantee, not an end-to-end one.
|
|
145
|
+
*
|
|
146
|
+
* A Prompt Definition never reaches this function: `renderPolicyPrompt` above
|
|
147
|
+
* replaced it with its text once, at the top of the open path, so no consumer —
|
|
148
|
+
* the Ask hash included — can ever see a function (ADR-0064).
|
|
31
149
|
*/
|
|
32
150
|
export function openRequest(options: OpenRequestOptions): OpenOptions {
|
|
33
151
|
const spawnOptions = options.spawnOptions;
|
|
@@ -37,7 +155,9 @@ export function openRequest(options: OpenRequestOptions): OpenOptions {
|
|
|
37
155
|
cwd: options.cwd,
|
|
38
156
|
name: options.name,
|
|
39
157
|
...(model === undefined ? {} : { model }),
|
|
40
|
-
|
|
158
|
+
systemPrompt:
|
|
159
|
+
spawnOptions.systemPrompt ??
|
|
160
|
+
yaagSystemPrompt({ agent: { name: options.name, runName: options.runName } }),
|
|
41
161
|
...(thinking === undefined ? {} : { thinking }),
|
|
42
162
|
...(spawnOptions.appendSystemPrompt === undefined
|
|
43
163
|
? {}
|
|
@@ -72,7 +192,7 @@ export function openRequest(options: OpenRequestOptions): OpenOptions {
|
|
|
72
192
|
|
|
73
193
|
/** Replaces the caller's `model`/`thinking` forms with one attempt's settled selection. */
|
|
74
194
|
export function withSelection(
|
|
75
|
-
options:
|
|
195
|
+
options: RenderedSpawnOptions,
|
|
76
196
|
selection: ModelSelection,
|
|
77
197
|
): ResolvedSpawnOptions {
|
|
78
198
|
// `parent` is dropped here as well: a Handle must never reach recorded options.
|
package/src/agent/spawn.ts
CHANGED
|
@@ -8,7 +8,7 @@ import type { RunContext } from "../run/index.ts";
|
|
|
8
8
|
import type { TransportFactory } from "../transport/index.ts";
|
|
9
9
|
import type { Handle, SpawnOptions, SpawnOverrides } from "../types.ts";
|
|
10
10
|
import type { Agent } from "./agent.ts";
|
|
11
|
-
import type
|
|
11
|
+
import { type AgentDefinition, isAgentDefinition } from "./define-agent.ts";
|
|
12
12
|
import { type ForkSpawner, forkRequest } from "./fork.ts";
|
|
13
13
|
import { resolveRequest } from "./spawn-definition-request.ts";
|
|
14
14
|
import { type OpenAgentContext, openAgent } from "./spawn-open.ts";
|
|
@@ -21,6 +21,8 @@ export interface SpawnDependencies {
|
|
|
21
21
|
readonly emit: EventSink;
|
|
22
22
|
readonly sessionDir: string | undefined;
|
|
23
23
|
readonly programFile: string | undefined;
|
|
24
|
+
/** The Run name every Agent System Prompt of this Run prints. */
|
|
25
|
+
readonly runName: string;
|
|
24
26
|
/** Effective Config entries, in merge order; empty when the Run has no config. */
|
|
25
27
|
readonly configExtensions: readonly ConfigExtension[];
|
|
26
28
|
/** The Profile this Run activated; absent for a program without Profiles. */
|
|
@@ -54,6 +56,7 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
|
|
|
54
56
|
parent: request.parent,
|
|
55
57
|
askDefaults: request.askDefaults,
|
|
56
58
|
definitionName: undefined,
|
|
59
|
+
inheritedPrompt: request.inheritedPrompt,
|
|
57
60
|
fork: request.fork,
|
|
58
61
|
});
|
|
59
62
|
if (request.compact !== undefined && request.compact !== false) {
|
|
@@ -67,12 +70,15 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
|
|
|
67
70
|
overrides?: SpawnOverrides,
|
|
68
71
|
): Promise<Handle> => {
|
|
69
72
|
if (closed) throw new YaagError("RUN_CLOSED", "run has already settled");
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
)
|
|
73
|
+
// The Agent Definition branch is explicit, although `resolveRequest` takes
|
|
74
|
+
// a plain options object too: it states the three accepted shapes in order.
|
|
75
|
+
if (isAgentDefinition(definitionOrOptions)) {
|
|
76
|
+
return openAgent(context, resolveRequest(definitionOrOptions, overrides));
|
|
77
|
+
}
|
|
78
|
+
if (isProfiledDefinition(definitionOrOptions)) {
|
|
79
|
+
return openAgent(context, profiledRequest(deps.profile, definitionOrOptions, overrides));
|
|
80
|
+
}
|
|
81
|
+
return openAgent(context, resolveRequest(definitionOrOptions, overrides));
|
|
76
82
|
};
|
|
77
83
|
return {
|
|
78
84
|
spawn,
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/** The shared Spawnable Definition predicate (ADR-0053). */
|
|
2
|
+
import type { SpawnableDefinition } from "../contract/index.ts";
|
|
3
|
+
import { isProfiledDefinition } from "../profile/index.ts";
|
|
4
|
+
import { isAgentDefinition } from "./define-agent.ts";
|
|
5
|
+
|
|
6
|
+
/** True for an Agent Definition and for a Profiled Definition, and for nothing else. */
|
|
7
|
+
export function isSpawnableDefinition(value: unknown): value is SpawnableDefinition {
|
|
8
|
+
return isAgentDefinition(value) || isProfiledDefinition(value);
|
|
9
|
+
}
|
package/src/ask/ask-hash.ts
CHANGED
|
@@ -32,6 +32,13 @@ export function askHash(options: AskHashOptions): string {
|
|
|
32
32
|
JSON.stringify({
|
|
33
33
|
cwd: spawnOptions.cwd ?? null,
|
|
34
34
|
model: spawnOptions.model ?? null,
|
|
35
|
+
// An unset `systemPrompt` hashes as null on purpose, even though the
|
|
36
|
+
// Agent really reads the Agent System Prompt: that default is filled in
|
|
37
|
+
// downstream, at the open-request seam, and never reaches
|
|
38
|
+
// `ResolvedSpawnOptions`. Hashing it would make Ask identity depend on
|
|
39
|
+
// the Agent name and the Run name the text embeds, which the Ask marker
|
|
40
|
+
// context strips deliberately. Spawn identity, not Ask identity, carries
|
|
41
|
+
// the Agent System Prompt (ADR-0055, ADR-0064).
|
|
35
42
|
systemPrompt: spawnOptions.systemPrompt ?? null,
|
|
36
43
|
...(spawnOptions.thinking === undefined ? {} : { thinking: spawnOptions.thinking }),
|
|
37
44
|
...(spawnOptions.appendSystemPrompt === undefined
|
package/src/catalog/index.ts
CHANGED
|
@@ -4,9 +4,10 @@
|
|
|
4
4
|
* fixture Catalog consumer tests assert against, plus the on-demand describe
|
|
5
5
|
* contract for a registered Agent Definition (ADR-0047) and its recorded
|
|
6
6
|
* CLI-child transcript, plus the reader, the program
|
|
7
|
-
* scanner,
|
|
8
|
-
* `registry-reader.ts`, and `program-scan.ts`
|
|
9
|
-
* and import no
|
|
7
|
+
* scanner, the layer merge, and the Catalog Resolve resolver. The contract
|
|
8
|
+
* half is pure; `load-catalog.ts`, `registry-reader.ts`, and `program-scan.ts`
|
|
9
|
+
* — the readers and the scanner — import no module; `resolve.ts` is the one
|
|
10
|
+
* file that imports a Definition module, on a program's request (ADR-0053).
|
|
10
11
|
*/
|
|
11
12
|
|
|
12
13
|
export type {
|
|
@@ -56,3 +57,4 @@ export {
|
|
|
56
57
|
parseRegistryFile,
|
|
57
58
|
readRegistryDocument,
|
|
58
59
|
} from "./registry-schema.ts";
|
|
60
|
+
export { createYaagGlobal } from "./resolve.ts";
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Catalog Resolve resolver (ADR-0053). It is the one file in `catalog/`
|
|
3
|
+
* that imports an Orchestration Program's Definition module, and only on a
|
|
4
|
+
* program's request.
|
|
5
|
+
*
|
|
6
|
+
* It calls `readFile` and `parseRegistryFile` directly and never
|
|
7
|
+
* `readRegistryLayer`: the reader turns every failure into a diagnostic, and
|
|
8
|
+
* this call must throw.
|
|
9
|
+
*/
|
|
10
|
+
import { readFile, stat } from "node:fs/promises";
|
|
11
|
+
import { dirname, resolve } from "node:path";
|
|
12
|
+
import { isSpawnableDefinition } from "../agent/index.ts";
|
|
13
|
+
import type {
|
|
14
|
+
CatalogScope,
|
|
15
|
+
SpawnableDefinition,
|
|
16
|
+
YaagGlobal,
|
|
17
|
+
YaagGlobalOptions,
|
|
18
|
+
} from "../contract/index.ts";
|
|
19
|
+
import { YaagError } from "../errors.ts";
|
|
20
|
+
import type { AgentDefinitionEntry } from "./catalog-entry.ts";
|
|
21
|
+
import { parseRegistryFile } from "./registry-schema.ts";
|
|
22
|
+
|
|
23
|
+
/** Builds the `$yaag` global: two independent Catalog Scopes, never `undefined`. */
|
|
24
|
+
export function createYaagGlobal(options: YaagGlobalOptions): YaagGlobal {
|
|
25
|
+
return {
|
|
26
|
+
global: scope("global", options.globalRegistryPath),
|
|
27
|
+
project: scope("project", options.projectRegistryPath),
|
|
28
|
+
};
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
function scope(name: "global" | "project", registryPath: string | undefined): CatalogScope {
|
|
32
|
+
return { importAgent: (agent) => importAgent({ scope: name, registryPath, name: agent }) };
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** One resolve request: which scope asked, which Registry File, which name. */
|
|
36
|
+
interface ResolveRequest {
|
|
37
|
+
readonly scope: "global" | "project";
|
|
38
|
+
readonly registryPath: string | undefined;
|
|
39
|
+
readonly name: string;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** Runs the fixed check order of the spec (decision 9). */
|
|
43
|
+
async function importAgent(request: ResolveRequest): Promise<SpawnableDefinition> {
|
|
44
|
+
if (request.registryPath === undefined) {
|
|
45
|
+
throw notFound(request, "this Run has no Program Directory");
|
|
46
|
+
}
|
|
47
|
+
const registry = resolve(request.registryPath);
|
|
48
|
+
const text = await readRegistry(request, registry);
|
|
49
|
+
const entries = parseEntries(request, registry, text);
|
|
50
|
+
|
|
51
|
+
const matches = entries.filter((entry) => entry.name === request.name);
|
|
52
|
+
if (matches.length > 1) {
|
|
53
|
+
const files = matches.map((entry) => JSON.stringify(entry.file)).join(", ");
|
|
54
|
+
throw new YaagError(
|
|
55
|
+
"CATALOG_ENTRY_AMBIGUOUS",
|
|
56
|
+
`${prefix(request)}: ${matches.length} agent entries have this name in ${registry}: ${files}`,
|
|
57
|
+
);
|
|
58
|
+
}
|
|
59
|
+
const [entry] = matches;
|
|
60
|
+
if (entry === undefined) {
|
|
61
|
+
throw notFound(request, `no agent entry has this name in ${registry}`);
|
|
62
|
+
}
|
|
63
|
+
const malformed =
|
|
64
|
+
entry.file === ""
|
|
65
|
+
? "file is empty"
|
|
66
|
+
: entry.exportName === ""
|
|
67
|
+
? "exportName is empty"
|
|
68
|
+
: undefined;
|
|
69
|
+
if (malformed !== undefined) {
|
|
70
|
+
throw unresolvable(request, `the entry in ${registry} is malformed: ${malformed}`, malformed);
|
|
71
|
+
}
|
|
72
|
+
return await loadEntry(request, resolve(dirname(registry), entry.file), entry.exportName);
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* Step 1, the read. ENOENT alone is `NOT_FOUND`; every other errno is
|
|
77
|
+
* `cannot be read`. This deviates from `readRegistryLayer`, which also
|
|
78
|
+
* swallows ENOTDIR: the spec names ENOENT only, thus a registry path under a
|
|
79
|
+
* file reads as `cannot be read`.
|
|
80
|
+
*/
|
|
81
|
+
async function readRegistry(request: ResolveRequest, registry: string): Promise<string> {
|
|
82
|
+
try {
|
|
83
|
+
return await readFile(registry, "utf8");
|
|
84
|
+
} catch (cause) {
|
|
85
|
+
if ((cause as NodeJS.ErrnoException).code === "ENOENT") {
|
|
86
|
+
throw notFound(request, `no Registry File at ${registry}`);
|
|
87
|
+
}
|
|
88
|
+
throw unresolvable(request, `${registry} did not parse: cannot be read`, "cannot be read");
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* Step 1, the parse. The file-scoped diagnostic prose comes from
|
|
94
|
+
* `registry-schema.ts`; this maps it to the spec's three remaining reasons. A
|
|
95
|
+
* `programs`-section diagnostic is ignored on purpose: a broken `programs`
|
|
96
|
+
* array never fails an agent resolve.
|
|
97
|
+
*/
|
|
98
|
+
function parseEntries(
|
|
99
|
+
request: ResolveRequest,
|
|
100
|
+
registry: string,
|
|
101
|
+
text: string,
|
|
102
|
+
): readonly AgentDefinitionEntry[] {
|
|
103
|
+
const parsed = parseRegistryFile(text, registry);
|
|
104
|
+
for (const diagnostic of parsed.diagnostics) {
|
|
105
|
+
if (diagnostic.scope !== "file") continue;
|
|
106
|
+
const reason = parseReason(diagnostic.message);
|
|
107
|
+
if (reason === undefined) continue;
|
|
108
|
+
throw unresolvable(request, `${registry} did not parse: ${reason}`, reason);
|
|
109
|
+
}
|
|
110
|
+
return parsed.entries;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
function parseReason(message: string): string | undefined {
|
|
114
|
+
if (message.includes("is not valid JSON")) return "is not valid JSON";
|
|
115
|
+
if (message.includes("must contain a JSON object")) return "root is not an object";
|
|
116
|
+
if (message.includes('"agents" must be an array')) return "agents is not an array";
|
|
117
|
+
return undefined;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/** Steps 5 to 8: the target file, the import, the export, the predicate. */
|
|
121
|
+
async function loadEntry(
|
|
122
|
+
request: ResolveRequest,
|
|
123
|
+
target: string,
|
|
124
|
+
exportName: string,
|
|
125
|
+
): Promise<SpawnableDefinition> {
|
|
126
|
+
if (!(await isFile(target))) {
|
|
127
|
+
throw unresolvable(request, targetTail(target, "file not found"), "file not found");
|
|
128
|
+
}
|
|
129
|
+
let namespace: unknown;
|
|
130
|
+
try {
|
|
131
|
+
namespace = await import(target);
|
|
132
|
+
} catch (cause) {
|
|
133
|
+
throw failed(request, targetTail(target, "module threw on import"), cause);
|
|
134
|
+
}
|
|
135
|
+
if (typeof namespace !== "object" || namespace === null || !(exportName in namespace)) {
|
|
136
|
+
const reason = `export "${exportName}" not found`;
|
|
137
|
+
throw unresolvable(request, targetTail(target, reason), reason);
|
|
138
|
+
}
|
|
139
|
+
const value = Reflect.get(namespace, exportName);
|
|
140
|
+
if (!isSpawnableDefinition(value)) {
|
|
141
|
+
const reason = `export "${exportName}" is not a Spawnable Definition`;
|
|
142
|
+
throw unresolvable(request, targetTail(target, reason), reason);
|
|
143
|
+
}
|
|
144
|
+
return value;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
async function isFile(target: string): Promise<boolean> {
|
|
148
|
+
try {
|
|
149
|
+
return (await stat(target)).isFile();
|
|
150
|
+
} catch {
|
|
151
|
+
return false;
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
function prefix(request: ResolveRequest): string {
|
|
156
|
+
return `$yaag.${request.scope}.importAgent("${request.name}")`;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
function notFound(request: ResolveRequest, tail: string): YaagError {
|
|
160
|
+
return new YaagError("CATALOG_ENTRY_NOT_FOUND", `${prefix(request)}: ${tail}`);
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/**
|
|
164
|
+
* An UNRESOLVABLE whose cause is a plain `Error` with the reason fragment as
|
|
165
|
+
* its message, and nothing else (decision 10).
|
|
166
|
+
*/
|
|
167
|
+
function unresolvable(request: ResolveRequest, tail: string, reason: string): YaagError {
|
|
168
|
+
return failed(request, tail, new Error(reason));
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/** An UNRESOLVABLE whose cause is the failure it wraps, for step 6. */
|
|
172
|
+
function failed(request: ResolveRequest, tail: string, cause: unknown): YaagError {
|
|
173
|
+
return new YaagError(
|
|
174
|
+
"CATALOG_ENTRY_UNRESOLVABLE",
|
|
175
|
+
`${prefix(request)}: ${tail}`,
|
|
176
|
+
undefined,
|
|
177
|
+
undefined,
|
|
178
|
+
cause,
|
|
179
|
+
);
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
function targetTail(target: string, reason: string): string {
|
|
183
|
+
return `${target} did not resolve: ${reason}`;
|
|
184
|
+
}
|
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
|
|
9
9
|
import type { AskOptions } from "./handle.ts";
|
|
10
10
|
import type { ModelSpec, ThinkingSpec } from "./model-spec.ts";
|
|
11
|
+
import type { LiteralPromptText, SystemPromptDefinition } from "./system-prompt.ts";
|
|
11
12
|
|
|
12
13
|
/** What one Agent is, independent of where it runs. */
|
|
13
14
|
export interface AgentPolicy {
|
|
@@ -33,11 +34,21 @@ export interface AgentPolicy {
|
|
|
33
34
|
*/
|
|
34
35
|
readonly thinking?: ThinkingSpec;
|
|
35
36
|
/**
|
|
36
|
-
* Replaces
|
|
37
|
-
*
|
|
37
|
+
* Replaces the Agent System Prompt, the text an Agent reads by default. The
|
|
38
|
+
* text is passed to the Agent literally, so it also removes the runtime
|
|
39
|
+
* facts, the tool list and the Rules the Agent System Prompt states.
|
|
40
|
+
*
|
|
41
|
+
* A `defineSystemPrompt(...)` definition instead builds the text at spawn
|
|
42
|
+
* time, with the Agent name and the Render Sentinels of the Prompt Context
|
|
43
|
+
* (ADR-0064). yaag renders it once per spawn; every consumer downstream of
|
|
44
|
+
* the spawn-request seam sees the rendered string.
|
|
45
|
+
*
|
|
46
|
+
* A value from `yaagSystemPrompt()` or from a `ctx.render*()` call belongs
|
|
47
|
+
* inside a `defineSystemPrompt` definition: the type rejects it here, and
|
|
48
|
+
* yaag also rejects it at run time, before the Agent starts (ADR-0060).
|
|
38
49
|
*/
|
|
39
|
-
readonly systemPrompt?:
|
|
40
|
-
/** Adds text
|
|
50
|
+
readonly systemPrompt?: LiteralPromptText | SystemPromptDefinition;
|
|
51
|
+
/** Adds text inside the Agent System Prompt, which stays. */
|
|
41
52
|
readonly appendSystemPrompt?: string;
|
|
42
53
|
/**
|
|
43
54
|
* Restores pi discovery. Omission or false selects ADR-0026's hermetic baseline.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Catalog Resolve author contract (ADR-0053): what `$yaag.<scope>.importAgent`
|
|
3
|
+
* returns, and the options `createYaagGlobal` takes.
|
|
4
|
+
*
|
|
5
|
+
* Type-only. It is the one file in this directory that names a type from
|
|
6
|
+
* outside it: `SpawnableDefinition` is the union of the two Definition shapes,
|
|
7
|
+
* and both already sit in the emitted author tree (ADR-0045).
|
|
8
|
+
*/
|
|
9
|
+
import type { AgentDefinition } from "../agent/define-agent.ts";
|
|
10
|
+
import type { ProfiledDefinition } from "../profile/use-profile.ts";
|
|
11
|
+
|
|
12
|
+
/** An Agent Definition or a Profiled Definition: what a Catalog Resolve gives back. */
|
|
13
|
+
export type SpawnableDefinition = AgentDefinition | ProfiledDefinition;
|
|
14
|
+
|
|
15
|
+
/** One Catalog scope, global or project. */
|
|
16
|
+
export interface CatalogScope {
|
|
17
|
+
/** Resolves the Spawnable Definition registered under `name` in this scope. */
|
|
18
|
+
importAgent(name: string): Promise<SpawnableDefinition>;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** The `$yaag` global an Orchestration Program reads. */
|
|
22
|
+
export interface YaagGlobal {
|
|
23
|
+
readonly global: CatalogScope;
|
|
24
|
+
readonly project: CatalogScope;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** What `createYaagGlobal` needs to build the two scopes. */
|
|
28
|
+
export interface YaagGlobalOptions {
|
|
29
|
+
/** Absolute path of the global Registry File. The file may not exist. */
|
|
30
|
+
readonly globalRegistryPath: string;
|
|
31
|
+
/** Absolute path of the project Registry File. `undefined` when the Run has no Program Directory. */
|
|
32
|
+
readonly projectRegistryPath: string | undefined;
|
|
33
|
+
}
|
|
@@ -66,4 +66,7 @@ export type YaagErrorCode =
|
|
|
66
66
|
| "RUN_STOPPED" // the Run's abort signal fired before the program completed
|
|
67
67
|
| "WORKTREE_REFUSED" // base cwd is not a clean Git repository
|
|
68
68
|
| "MODEL_RESOLUTION_FAILED" // the resolver gave up, or every candidate failed; carries the history
|
|
69
|
-
| "
|
|
69
|
+
| "CATALOG_ENTRY_NOT_FOUND" // no Registry File, no Program Directory, or no entry with that name (ADR-0053)
|
|
70
|
+
| "CATALOG_ENTRY_AMBIGUOUS" // two or more registry entries carry that name
|
|
71
|
+
| "CATALOG_ENTRY_UNRESOLVABLE" // the entry exists but did not yield a Spawnable Definition
|
|
72
|
+
| "SPAWN_FAILED"; // the spawn was refused, e.g. a guarded system prompt, a broken tool contract or a startup timeout
|
package/src/contract/index.ts
CHANGED
|
@@ -3,11 +3,19 @@
|
|
|
3
3
|
* Program author reads (ADR-0045).
|
|
4
4
|
*
|
|
5
5
|
* Every file here is type-only and imports nothing outside this directory
|
|
6
|
-
* except `typebox
|
|
7
|
-
*
|
|
6
|
+
* except `typebox`, with one exception: `catalog-resolve.ts` names
|
|
7
|
+
* `AgentDefinition` and `ProfiledDefinition`, type-only, because both already
|
|
8
|
+
* sit in the emitted author tree. That keeps the declaration tree a workspace
|
|
9
|
+
* gets small. Files inside this directory import each other directly.
|
|
8
10
|
*/
|
|
9
11
|
export type { AgentPolicy } from "./agent-policy.ts";
|
|
10
12
|
export type { AgentProgress, CompactionResult, TokenBreakdown } from "./agent-report.ts";
|
|
13
|
+
export type {
|
|
14
|
+
CatalogScope,
|
|
15
|
+
SpawnableDefinition,
|
|
16
|
+
YaagGlobal,
|
|
17
|
+
YaagGlobalOptions,
|
|
18
|
+
} from "./catalog-resolve.ts";
|
|
11
19
|
export type {
|
|
12
20
|
AskInvalidOutputOutcome,
|
|
13
21
|
AskLimitKind,
|
|
@@ -33,3 +41,13 @@ export type {
|
|
|
33
41
|
SpawnOptions,
|
|
34
42
|
SpawnOverrides,
|
|
35
43
|
} from "./spawn-options.ts";
|
|
44
|
+
export type {
|
|
45
|
+
LiteralPromptText,
|
|
46
|
+
PromptAudience,
|
|
47
|
+
PromptText,
|
|
48
|
+
SystemPromptAgent,
|
|
49
|
+
SystemPromptBuilder,
|
|
50
|
+
SystemPromptContext,
|
|
51
|
+
SystemPromptDefinition,
|
|
52
|
+
SystemPromptInput,
|
|
53
|
+
} from "./system-prompt.ts";
|