@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
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Agent System Prompt: the text every Agent reads in place of pi's default
|
|
3
|
+
* prompt (ADR-0055, ADR-0056).
|
|
4
|
+
*
|
|
5
|
+
* The text is pure and holds Render Sentinels, not facts: the facts exist only
|
|
6
|
+
* inside the Agent process, and the private prompt extension puts them in on
|
|
7
|
+
* every turn.
|
|
8
|
+
*/
|
|
9
|
+
import type { PromptAudience, PromptText, SystemPromptAgent } from "../contract/index.ts";
|
|
10
|
+
// A deep import, not `../prompt/index.ts`: this file is reachable from
|
|
11
|
+
// `public-api.ts`, and the vendored author declaration tree follows source
|
|
12
|
+
// imports, so an index import would pull `prompt/index.d.ts` and
|
|
13
|
+
// `prompt-gist.d.ts` into the ADR-0045 surface that
|
|
14
|
+
// `apps/yaag/scripts/runtime-dts.test.ts` guards.
|
|
15
|
+
import { prompt } from "../prompt/prompt.ts";
|
|
16
|
+
import { renderSentinel } from "./render-sentinel.ts";
|
|
17
|
+
|
|
18
|
+
/** What the default text needs from the Orchestrator. */
|
|
19
|
+
export interface YaagSystemPromptOptions {
|
|
20
|
+
/**
|
|
21
|
+
* Who the Agent talks to. `"user"` exists for ADR-0062 (the user-input tool)
|
|
22
|
+
* and is not reachable from a program yet.
|
|
23
|
+
*/
|
|
24
|
+
readonly audience?: PromptAudience;
|
|
25
|
+
/**
|
|
26
|
+
* The Agent this text is for. With it the text prints an `Agent: … Run: …`
|
|
27
|
+
* line; without it that line is omitted, which is what a program gets when it
|
|
28
|
+
* composes the default text inside its own Prompt Definition.
|
|
29
|
+
*/
|
|
30
|
+
readonly agent?: SystemPromptAgent;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* The default Agent System Prompt, with a Render Sentinel in every braced
|
|
35
|
+
* position of the spec's "The default text".
|
|
36
|
+
*
|
|
37
|
+
* Deterministic in `name` and `runName` alone, so the Cassette peek path and
|
|
38
|
+
* the open path produce the same bytes and a replay on another machine matches.
|
|
39
|
+
*/
|
|
40
|
+
export function yaagSystemPrompt(options: YaagSystemPromptOptions = {}): PromptText {
|
|
41
|
+
// The one cast of this file: the text holds Render Sentinels, so it belongs
|
|
42
|
+
// inside a `defineSystemPrompt` definition and not in a plain `systemPrompt`
|
|
43
|
+
// (ADR-0060). The brand has no runtime value.
|
|
44
|
+
return prompt`
|
|
45
|
+
You are an Agent. A yaag Orchestration Program started you and drives you.
|
|
46
|
+
|
|
47
|
+
${audienceParagraph(options.audience ?? "program")}
|
|
48
|
+
|
|
49
|
+
${identityLine(options.agent)}
|
|
50
|
+
Model: ${renderSentinel("model")} Process: ${renderSentinel("pid")}
|
|
51
|
+
Started: ${renderSentinel("startedAt")} Directory: ${renderSentinel("cwd")}
|
|
52
|
+
Now: ${renderSentinel("currentDateTime")}
|
|
53
|
+
|
|
54
|
+
Available tools:
|
|
55
|
+
${renderSentinel("tools")}
|
|
56
|
+
|
|
57
|
+
Rules:
|
|
58
|
+
- Do the task the prompt states. Do not do more than it states.
|
|
59
|
+
- Report what you did and what you found. Be short and be exact.
|
|
60
|
+
- Say when you could not do something, and say why.
|
|
61
|
+
|
|
62
|
+
${renderSentinel("programAppend")}
|
|
63
|
+
|
|
64
|
+
${renderSentinel("appendSystem")}
|
|
65
|
+
|
|
66
|
+
${renderSentinel("contextFiles")}
|
|
67
|
+
|
|
68
|
+
${renderSentinel("skills")}
|
|
69
|
+
` as PromptText;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** The `Agent: … Run: …` line, present only when the caller names the Agent. */
|
|
73
|
+
function identityLine(agent: SystemPromptAgent | undefined): string {
|
|
74
|
+
return agent === undefined ? "" : `Agent: ${agent.name} Run: ${agent.runName}`;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** The second paragraph, which states who reads the Agent's answer. */
|
|
78
|
+
function audienceParagraph(audience: PromptAudience): string {
|
|
79
|
+
if (audience === "user") {
|
|
80
|
+
return prompt`
|
|
81
|
+
A person can read what you write. Use the user-input tool when you must
|
|
82
|
+
ask that person a question. Each prompt you receive comes from the
|
|
83
|
+
program.
|
|
84
|
+
`;
|
|
85
|
+
}
|
|
86
|
+
return prompt`
|
|
87
|
+
You are not talking to a human. Each prompt you receive comes from the
|
|
88
|
+
program. Your answer goes back to the program.
|
|
89
|
+
`;
|
|
90
|
+
}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Append Channel wire protocol: how a spawn's `appendSystemPrompt` travels
|
|
3
|
+
* from the Orchestrator to the Agent through the environment (ADR-0061).
|
|
4
|
+
*
|
|
5
|
+
* This file has no imports at all, by design — exactly like
|
|
6
|
+
* `render-sentinel.ts`. The writer half runs in the Orchestrator
|
|
7
|
+
* (`transport/append-env.ts`); the reader half runs inside the Agent, in the
|
|
8
|
+
* private prompt extension that jiti loads without yaag's dependency graph. It
|
|
9
|
+
* uses no Bun-only API and no `Buffer`, so it stays portable between Bun and
|
|
10
|
+
* Node: `TextEncoder` and `process` exist in both.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
/** The one variable the Append Channel uses. A value carries a mandatory prefix. */
|
|
14
|
+
export const APPEND_SYSTEM_PROMPT_ENV = "YAAG_APPEND_SYSTEM_PROMPT";
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* The largest append text that travels inline, in UTF-8 bytes.
|
|
18
|
+
*
|
|
19
|
+
* Linux allows 128 KiB per environment entry (`MAX_ARG_STRLEN`), Windows caps
|
|
20
|
+
* the whole environment block at 32 767 characters, and macOS caps `ARG_MAX` at
|
|
21
|
+
* 256 KiB in total. 32 KiB for one variable is below every one of them and
|
|
22
|
+
* leaves room for the rest of the environment. The threshold protects one
|
|
23
|
+
* variable, not the total block: on Windows a large environment plus a large
|
|
24
|
+
* append text can still fail. yaag targets POSIX today.
|
|
25
|
+
*/
|
|
26
|
+
export const APPEND_INLINE_LIMIT_BYTES = 32_768;
|
|
27
|
+
|
|
28
|
+
const TEXT_PREFIX = "text:";
|
|
29
|
+
const FILE_PREFIX = "file:";
|
|
30
|
+
|
|
31
|
+
/** The `text:` form when the text fits the platform-safe limit, else null: use the file form. */
|
|
32
|
+
export function inlineAppendValue(text: string): string | null {
|
|
33
|
+
const bytes = new TextEncoder().encode(text).length;
|
|
34
|
+
return bytes <= APPEND_INLINE_LIMIT_BYTES ? `${TEXT_PREFIX}${text}` : null;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** The `file:` form: the value names an absolute path that holds the text. */
|
|
38
|
+
export function fileAppendValue(path: string): string {
|
|
39
|
+
return `${FILE_PREFIX}${path}`;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* The program's append text as the Agent sees it: `""` when the variable is
|
|
44
|
+
* absent, the inline text, or the contents of the file the value names.
|
|
45
|
+
*
|
|
46
|
+
* A value with no known prefix, and a file read that throws, both give `""` and
|
|
47
|
+
* one warning line: a prompt with a hole in it beats a dead Agent.
|
|
48
|
+
*/
|
|
49
|
+
export function readProgramAppend(
|
|
50
|
+
value: string | undefined,
|
|
51
|
+
readFile: (path: string) => string,
|
|
52
|
+
warn: (line: string) => void = (line) => {
|
|
53
|
+
process.stderr.write(line);
|
|
54
|
+
},
|
|
55
|
+
): string {
|
|
56
|
+
if (value === undefined) return "";
|
|
57
|
+
if (value.startsWith(TEXT_PREFIX)) return value.slice(TEXT_PREFIX.length);
|
|
58
|
+
if (value.startsWith(FILE_PREFIX)) {
|
|
59
|
+
const path = value.slice(FILE_PREFIX.length);
|
|
60
|
+
try {
|
|
61
|
+
return readFile(path);
|
|
62
|
+
} catch (error) {
|
|
63
|
+
warn(`yaag: cannot read append system prompt file ${path}: ${String(error)}\n`);
|
|
64
|
+
return "";
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
warn(`yaag: ignored ${APPEND_SYSTEM_PROMPT_ENV} value with no known prefix\n`);
|
|
68
|
+
return "";
|
|
69
|
+
}
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Prompt Definition: a program shapes an Agent's system prompt with a
|
|
3
|
+
* function (ADR-0057, ADR-0058, ADR-0064).
|
|
4
|
+
*
|
|
5
|
+
* The builder runs in the Orchestrator, once per spawn, and writes Render
|
|
6
|
+
* Sentinels for the facts it cannot know. The private prompt extension replaces
|
|
7
|
+
* each sentinel inside the Agent process.
|
|
8
|
+
*/
|
|
9
|
+
import type {
|
|
10
|
+
PromptText,
|
|
11
|
+
SystemPromptAgent,
|
|
12
|
+
SystemPromptBuilder,
|
|
13
|
+
SystemPromptContext,
|
|
14
|
+
SystemPromptDefinition,
|
|
15
|
+
} from "../contract/index.ts";
|
|
16
|
+
import { YaagError } from "../errors.ts";
|
|
17
|
+
import { type PromptVariable, renderSentinel } from "./render-sentinel.ts";
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* One cast for the whole Prompt Context: `renderSentinel` returns a plain
|
|
21
|
+
* string, and the brand of `PromptText` is a declared `unique symbol` with no
|
|
22
|
+
* runtime value (ADR-0060).
|
|
23
|
+
*/
|
|
24
|
+
const write = (variable: PromptVariable): PromptText => renderSentinel(variable) as PromptText;
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* The one Prompt Context every definition receives. It is frozen and stateless:
|
|
28
|
+
* each method writes the Render Sentinel of its Prompt Variable.
|
|
29
|
+
*/
|
|
30
|
+
export const PROMPT_CONTEXT: SystemPromptContext = Object.freeze({
|
|
31
|
+
renderModel: () => write("model"),
|
|
32
|
+
renderPid: () => write("pid"),
|
|
33
|
+
renderStartedAt: () => write("startedAt"),
|
|
34
|
+
renderCurrentDateTime: () => write("currentDateTime"),
|
|
35
|
+
renderCwd: () => write("cwd"),
|
|
36
|
+
renderTools: () => write("tools"),
|
|
37
|
+
renderAppendSystem: () => write("appendSystem"),
|
|
38
|
+
renderProgramAppend: () => write("programAppend"),
|
|
39
|
+
renderContextFiles: () => write("contextFiles"),
|
|
40
|
+
renderSkills: () => write("skills"),
|
|
41
|
+
renderPiDefaultPrompt: () => write("piDefaultPrompt"),
|
|
42
|
+
});
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* The builders, by definition. A module-private WeakMap, so the builder is
|
|
46
|
+
* unreachable outside this file and the definition itself carries no callable.
|
|
47
|
+
*/
|
|
48
|
+
const builders = new WeakMap<object, SystemPromptBuilder>();
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Declares a system prompt yaag builds at spawn time.
|
|
52
|
+
*
|
|
53
|
+
* The builder takes `{ ctx, agent }`, must be pure and synchronous, and runs
|
|
54
|
+
* once per spawn in the Orchestrator. A Fork inherits the rendered text of its
|
|
55
|
+
* source, so the builder does not run again for a fork.
|
|
56
|
+
*/
|
|
57
|
+
export function defineSystemPrompt(builder: SystemPromptBuilder): SystemPromptDefinition {
|
|
58
|
+
if (typeof builder !== "function") {
|
|
59
|
+
throw new TypeError(
|
|
60
|
+
"defineSystemPrompt: expected a builder function ({ ctx, agent }) => string",
|
|
61
|
+
);
|
|
62
|
+
}
|
|
63
|
+
const carrier = Object.freeze({});
|
|
64
|
+
builders.set(carrier, builder);
|
|
65
|
+
// The one cast of this module: the brand of `SystemPromptDefinition` is a
|
|
66
|
+
// declared `unique symbol` with no runtime value, so the carrier can carry
|
|
67
|
+
// the type but never the key. Membership is decided by the WeakMap alone.
|
|
68
|
+
return carrier as SystemPromptDefinition;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** True only for values produced by `defineSystemPrompt`. */
|
|
72
|
+
export function isSystemPromptDefinition(value: unknown): value is SystemPromptDefinition {
|
|
73
|
+
return typeof value === "object" && value !== null && builders.has(value);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** What one render needs: the definition and the Agent it is for. */
|
|
77
|
+
export interface RenderSystemPromptOptions {
|
|
78
|
+
readonly definition: SystemPromptDefinition;
|
|
79
|
+
readonly agent: SystemPromptAgent;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* Runs one Prompt Definition and returns its text.
|
|
84
|
+
*
|
|
85
|
+
* A builder that throws, or that returns something other than a string, fails
|
|
86
|
+
* the spawn with `SPAWN_FAILED` naming the Agent and `defineSystemPrompt`.
|
|
87
|
+
*/
|
|
88
|
+
export function renderSystemPrompt(options: RenderSystemPromptOptions): string {
|
|
89
|
+
const builder = builders.get(options.definition);
|
|
90
|
+
if (builder === undefined) {
|
|
91
|
+
throw new TypeError("not a Prompt Definition — build it with defineSystemPrompt(builder)");
|
|
92
|
+
}
|
|
93
|
+
const name = options.agent.name;
|
|
94
|
+
let text: unknown;
|
|
95
|
+
try {
|
|
96
|
+
text = builder({ ctx: PROMPT_CONTEXT, agent: options.agent });
|
|
97
|
+
} catch (error) {
|
|
98
|
+
throw new YaagError(
|
|
99
|
+
"SPAWN_FAILED",
|
|
100
|
+
`agent "${name}": defineSystemPrompt threw: ${String(error)}`,
|
|
101
|
+
name,
|
|
102
|
+
);
|
|
103
|
+
}
|
|
104
|
+
if (typeof text !== "string") {
|
|
105
|
+
throw new YaagError(
|
|
106
|
+
"SPAWN_FAILED",
|
|
107
|
+
`agent "${name}": defineSystemPrompt returned ${typeof text}, expected a string`,
|
|
108
|
+
name,
|
|
109
|
+
);
|
|
110
|
+
}
|
|
111
|
+
return text;
|
|
112
|
+
}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Public surface of the `system-prompt/` module.
|
|
3
|
+
*
|
|
4
|
+
* The Render Sentinel vocabulary is private to this directory: `PromptVariable`,
|
|
5
|
+
* `PROMPT_VARIABLES`, `isPromptVariable`, `sentinelPattern` and
|
|
6
|
+
* `agentPromptExtensionPath` have no consumer outside it and are deliberately
|
|
7
|
+
* not re-exported, so the vocabulary cannot spread. Files inside this directory
|
|
8
|
+
* import each other directly; the private prompt extension imports
|
|
9
|
+
* `render-sentinel.ts` as a sibling, never through this index, because pi loads
|
|
10
|
+
* it without yaag's dependency graph.
|
|
11
|
+
*
|
|
12
|
+
* The four spawn-time guards in `prompt-guards.ts` do cross this boundary:
|
|
13
|
+
* they run in the Orchestrator, at the spawn-request seam, and they are the
|
|
14
|
+
* only way the seam can decide what a prompt string may hold (ADR-0060,
|
|
15
|
+
* ADR-0063). They take and return plain strings, so the vocabulary itself
|
|
16
|
+
* still does not spread.
|
|
17
|
+
*
|
|
18
|
+
* `renderSentinel` is exported for tests that must build a marker to prove it
|
|
19
|
+
* survives a seam untouched.
|
|
20
|
+
*
|
|
21
|
+
* The Append Channel is the one exception to the privacy rule above: its
|
|
22
|
+
* writer half lives in `transport/` (ADR-0061), so the variable name, the
|
|
23
|
+
* limit and the two value forms are exported. `readProgramAppend` is not: only
|
|
24
|
+
* the sibling prompt extension reads a value.
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
export { AGENT_PROMPT_EXTENSION_PATH } from "./agent-prompt.ts";
|
|
28
|
+
export { type YaagSystemPromptOptions, yaagSystemPrompt } from "./agent-system-prompt.ts";
|
|
29
|
+
export {
|
|
30
|
+
APPEND_INLINE_LIMIT_BYTES,
|
|
31
|
+
APPEND_SYSTEM_PROMPT_ENV,
|
|
32
|
+
fileAppendValue,
|
|
33
|
+
inlineAppendValue,
|
|
34
|
+
} from "./append-channel.ts";
|
|
35
|
+
// `PROMPT_CONTEXT` stays private to this directory: only the render path and
|
|
36
|
+
// its own sibling test read it.
|
|
37
|
+
export {
|
|
38
|
+
defineSystemPrompt,
|
|
39
|
+
isSystemPromptDefinition,
|
|
40
|
+
renderSystemPrompt,
|
|
41
|
+
} from "./define-system-prompt.ts";
|
|
42
|
+
export {
|
|
43
|
+
assertKnownSentinels,
|
|
44
|
+
assertNoLeakedSentinel,
|
|
45
|
+
dropsProgramAppend,
|
|
46
|
+
programAppendWarning,
|
|
47
|
+
} from "./prompt-guards.ts";
|
|
48
|
+
export { promptNeedsPiDefault, renderSentinel, SYSTEM_PROMPT_ENV } from "./render-sentinel.ts";
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The three spawn-time prompt guards (ADR-0060, ADR-0063).
|
|
3
|
+
*
|
|
4
|
+
* They run in the Orchestrator, at the spawn-request seam, before any Agent
|
|
5
|
+
* process starts. Two of them reject the spawn; the third writes one warning
|
|
6
|
+
* and lets the spawn proceed.
|
|
7
|
+
*/
|
|
8
|
+
import { YaagError } from "../errors.ts";
|
|
9
|
+
import { isPromptVariable, renderSentinel, sentinelPattern } from "./render-sentinel.ts";
|
|
10
|
+
|
|
11
|
+
/** Every marker name a text holds, known or not, in the order they appear. */
|
|
12
|
+
function markerNames(text: string): readonly string[] {
|
|
13
|
+
const names: string[] = [];
|
|
14
|
+
for (const match of text.matchAll(sentinelPattern())) {
|
|
15
|
+
const name = match[1];
|
|
16
|
+
if (name !== undefined && !names.includes(name)) names.push(name);
|
|
17
|
+
}
|
|
18
|
+
return names;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Rejects a plain-string `systemPrompt` that holds a Render Sentinel.
|
|
23
|
+
*
|
|
24
|
+
* This is what a program hits when it writes `systemPrompt: yaagSystemPrompt()`
|
|
25
|
+
* without the `defineSystemPrompt` wrapper (ADR-0060).
|
|
26
|
+
*/
|
|
27
|
+
export function assertNoLeakedSentinel(text: string, agent: string): void {
|
|
28
|
+
const names = markerNames(text);
|
|
29
|
+
if (names.length === 0) return;
|
|
30
|
+
throw new YaagError(
|
|
31
|
+
"SPAWN_FAILED",
|
|
32
|
+
`agent "${agent}": systemPrompt is a plain string that holds a render marker (${names.join(", ")}). Render Sentinels are expanded inside a defineSystemPrompt definition only.`,
|
|
33
|
+
agent,
|
|
34
|
+
);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Rejects a rendered prompt that holds a marker yaag did not generate
|
|
39
|
+
* (ADR-0063). A typo in a hand-written marker is a program fault, and it is
|
|
40
|
+
* cheapest to learn about it before the Agent is up.
|
|
41
|
+
*/
|
|
42
|
+
export function assertKnownSentinels(text: string, agent: string): void {
|
|
43
|
+
const unknown = markerNames(text).filter((name) => !isPromptVariable(name));
|
|
44
|
+
if (unknown.length === 0) return;
|
|
45
|
+
throw new YaagError(
|
|
46
|
+
"SPAWN_FAILED",
|
|
47
|
+
`agent "${agent}": the system prompt holds an unknown render marker (${unknown.join(", ")}). Only a ctx.render*() call of this yaag version writes a marker.`,
|
|
48
|
+
agent,
|
|
49
|
+
);
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** True when the program's append text would be dropped (spec decision 19). */
|
|
53
|
+
export function dropsProgramAppend(text: string): boolean {
|
|
54
|
+
return !text.includes(renderSentinel("programAppend"));
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** The one line a dropped append text writes; the seam owns who calls it. */
|
|
58
|
+
export function programAppendWarning(agent: string): string {
|
|
59
|
+
return `[yaag] agent "${agent}": appendSystemPrompt is set, and the system prompt calls no ctx.renderProgramAppend(), so that text is dropped.`;
|
|
60
|
+
}
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Render Sentinel vocabulary: one opaque marker per Prompt Variable
|
|
3
|
+
* (ADR-0056, ADR-0058).
|
|
4
|
+
*
|
|
5
|
+
* This file has no imports at all, by design. The Orchestrator side and the
|
|
6
|
+
* private pi extension both read it, and the extension is loaded by jiti inside
|
|
7
|
+
* the Agent process, where yaag's dependency graph does not exist.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
/** One Prompt Variable of the Agent System Prompt (ADR-0056, ADR-0058). */
|
|
11
|
+
export type PromptVariable =
|
|
12
|
+
| "model"
|
|
13
|
+
| "pid"
|
|
14
|
+
| "startedAt"
|
|
15
|
+
| "currentDateTime"
|
|
16
|
+
| "cwd"
|
|
17
|
+
| "tools"
|
|
18
|
+
| "appendSystem"
|
|
19
|
+
| "programAppend"
|
|
20
|
+
| "contextFiles"
|
|
21
|
+
| "skills"
|
|
22
|
+
| "piDefaultPrompt";
|
|
23
|
+
|
|
24
|
+
/** Every Prompt Variable, in the order the default text mentions them. */
|
|
25
|
+
export const PROMPT_VARIABLES: readonly PromptVariable[] = [
|
|
26
|
+
"model",
|
|
27
|
+
"pid",
|
|
28
|
+
"startedAt",
|
|
29
|
+
"currentDateTime",
|
|
30
|
+
"cwd",
|
|
31
|
+
"tools",
|
|
32
|
+
"appendSystem",
|
|
33
|
+
"programAppend",
|
|
34
|
+
"contextFiles",
|
|
35
|
+
"skills",
|
|
36
|
+
"piDefaultPrompt",
|
|
37
|
+
];
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* The opaque marker one Prompt Variable travels as.
|
|
41
|
+
*
|
|
42
|
+
* The form survives argv, JSON, `prompt` interpolation and a regex sweep, and
|
|
43
|
+
* it is private to yaag: no program can build one yet.
|
|
44
|
+
*/
|
|
45
|
+
export function renderSentinel(variable: PromptVariable): string {
|
|
46
|
+
return `<<<yaag:render:${variable}:1>>>`;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* A fresh global pattern that matches every well-formed marker, known or not.
|
|
51
|
+
*
|
|
52
|
+
* A fresh regex per call, so no caller inherits another caller's `lastIndex`.
|
|
53
|
+
*/
|
|
54
|
+
export function sentinelPattern(): RegExp {
|
|
55
|
+
return /<<<yaag:render:([a-zA-Z]+):1>>>/g;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* The environment variable that carries the system prompt to an Agent whose
|
|
60
|
+
* prompt needs pi's own default text (ADR-0063 amendment 2).
|
|
61
|
+
*
|
|
62
|
+
* yaag then spends no `--system-prompt`, so pi builds its default prompt and
|
|
63
|
+
* the prompt extension receives it as `event.systemPrompt`.
|
|
64
|
+
*/
|
|
65
|
+
export const SYSTEM_PROMPT_ENV = "YAAG_SYSTEM_PROMPT";
|
|
66
|
+
|
|
67
|
+
/** Whether a prompt asks for pi's own default prompt, and so needs the env channel. */
|
|
68
|
+
export function promptNeedsPiDefault(text: string): boolean {
|
|
69
|
+
return text.includes(renderSentinel("piDefaultPrompt"));
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** Whether a marker name is a Prompt Variable this version knows. */
|
|
73
|
+
export function isPromptVariable(name: string): name is PromptVariable {
|
|
74
|
+
return (PROMPT_VARIABLES as readonly string[]).includes(name);
|
|
75
|
+
}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The writer half of the Append Channel: it decides the child's environment
|
|
3
|
+
* variable for one spawn (ADR-0061).
|
|
4
|
+
*
|
|
5
|
+
* A small text travels inline. A text past the platform-safe limit travels as a
|
|
6
|
+
* temp file the Agent reads. The channel owns that file and removes it when the
|
|
7
|
+
* Agent is gone — the prompt extension re-reads it on every turn, so it may not
|
|
8
|
+
* be removed after startup.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
|
|
12
|
+
import { tmpdir } from "node:os";
|
|
13
|
+
import { join } from "node:path";
|
|
14
|
+
import {
|
|
15
|
+
APPEND_SYSTEM_PROMPT_ENV,
|
|
16
|
+
fileAppendValue,
|
|
17
|
+
inlineAppendValue,
|
|
18
|
+
} from "../system-prompt/index.ts";
|
|
19
|
+
|
|
20
|
+
/** One spawn's Append Channel: the child environment, plus the temp file it may own. */
|
|
21
|
+
export interface AppendChannel {
|
|
22
|
+
/** The child's full environment, with the append variable set or removed. */
|
|
23
|
+
readonly env: Record<string, string>;
|
|
24
|
+
/** Removes the temp file, if this channel made one. Idempotent, never throws. */
|
|
25
|
+
dispose(): void;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Builds the child environment for one spawn.
|
|
30
|
+
*
|
|
31
|
+
* When the spawn sets no append text the variable is *removed* rather than
|
|
32
|
+
* inherited: an Orchestrator that itself runs under a stale value would
|
|
33
|
+
* otherwise feed it to every Agent it starts.
|
|
34
|
+
*/
|
|
35
|
+
export function openAppendChannel(
|
|
36
|
+
appendSystemPrompt: string | undefined,
|
|
37
|
+
base: NodeJS.ProcessEnv = process.env,
|
|
38
|
+
): AppendChannel {
|
|
39
|
+
const env: Record<string, string> = {};
|
|
40
|
+
for (const [key, value] of Object.entries(base)) {
|
|
41
|
+
if (value !== undefined) env[key] = value;
|
|
42
|
+
}
|
|
43
|
+
if (appendSystemPrompt === undefined) {
|
|
44
|
+
delete env[APPEND_SYSTEM_PROMPT_ENV];
|
|
45
|
+
return { env, dispose: () => {} };
|
|
46
|
+
}
|
|
47
|
+
const inline = inlineAppendValue(appendSystemPrompt);
|
|
48
|
+
if (inline !== null) {
|
|
49
|
+
env[APPEND_SYSTEM_PROMPT_ENV] = inline;
|
|
50
|
+
return { env, dispose: () => {} };
|
|
51
|
+
}
|
|
52
|
+
const dir = mkdtempSync(join(tmpdir(), "yaag-append-"));
|
|
53
|
+
const path = join(dir, "append-system.md");
|
|
54
|
+
writeFileSync(path, appendSystemPrompt, "utf8");
|
|
55
|
+
env[APPEND_SYSTEM_PROMPT_ENV] = fileAppendValue(path);
|
|
56
|
+
let disposed = false;
|
|
57
|
+
return {
|
|
58
|
+
env,
|
|
59
|
+
dispose: () => {
|
|
60
|
+
if (disposed) return;
|
|
61
|
+
disposed = true;
|
|
62
|
+
try {
|
|
63
|
+
rmSync(dir, { recursive: true, force: true });
|
|
64
|
+
} catch {
|
|
65
|
+
// A leftover file in the temp directory is not worth failing a shutdown.
|
|
66
|
+
}
|
|
67
|
+
},
|
|
68
|
+
};
|
|
69
|
+
}
|
package/src/transport/index.ts
CHANGED
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
// One name for one concept: the recorded selection type lives in `model/`,
|
|
7
7
|
// which `transport/` already depends on (ADR-0039).
|
|
8
8
|
export type { RecordedSpawnSelection } from "../model/index.ts";
|
|
9
|
+
export { type AppendChannel, openAppendChannel } from "./append-env.ts";
|
|
9
10
|
export { type CommandResponse, Connection } from "./connection.ts";
|
|
10
11
|
export {
|
|
11
12
|
FakeTransport,
|
|
@@ -20,6 +21,7 @@ export { liveTransport } from "./live-transport.ts";
|
|
|
20
21
|
export {
|
|
21
22
|
type AgentProgress,
|
|
22
23
|
piCommand,
|
|
24
|
+
piEnv,
|
|
23
25
|
readAgentProgress,
|
|
24
26
|
readCompaction,
|
|
25
27
|
} from "./pi-state.ts";
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
import { YaagError } from "../errors.ts";
|
|
2
|
+
import { type AppendChannel, openAppendChannel } from "./append-env.ts";
|
|
2
3
|
import { FrameQueue } from "./frame-queue.ts";
|
|
3
4
|
import { decodeFrames } from "./jsonl.ts";
|
|
4
|
-
import { piCommand, readModel, readStartup, readStats } from "./pi-state.ts";
|
|
5
|
+
import { piCommand, piEnv, readModel, readStartup, readStats } from "./pi-state.ts";
|
|
5
6
|
import { reap } from "./reap.ts";
|
|
6
7
|
import { appendStderrTail, stderrDiagnostic } from "./stderr-tail.ts";
|
|
7
8
|
import {
|
|
@@ -55,6 +56,12 @@ class LiveTransport implements AgentTransport {
|
|
|
55
56
|
/** Both halves of tool verification, or null when the spawn promised nothing. */
|
|
56
57
|
readonly #verification: { readonly contract: ToolContract; readonly probe: ToolProbe } | null;
|
|
57
58
|
|
|
59
|
+
/**
|
|
60
|
+
* The Append Channel of this Agent (ADR-0061). It is disposed at exit, not
|
|
61
|
+
* after startup: the prompt extension re-reads its temp file on every turn.
|
|
62
|
+
*/
|
|
63
|
+
readonly #append: AppendChannel;
|
|
64
|
+
|
|
58
65
|
#nextId = 0;
|
|
59
66
|
#closing: Promise<AgentStats> | null = null;
|
|
60
67
|
|
|
@@ -62,19 +69,31 @@ class LiveTransport implements AgentTransport {
|
|
|
62
69
|
this.#name = options.name;
|
|
63
70
|
const contract = toolContract(options);
|
|
64
71
|
this.#verification = contract === null ? null : { contract, probe: createToolProbe() };
|
|
65
|
-
this.#
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
72
|
+
this.#append = openAppendChannel(options.appendSystemPrompt);
|
|
73
|
+
try {
|
|
74
|
+
this.#process = Bun.spawn({
|
|
75
|
+
cmd: piCommand(options, this.#verification ? TOOL_PROBE_EXTENSION_PATH : undefined),
|
|
76
|
+
cwd: options.cwd,
|
|
77
|
+
// The Append Channel builds the base environment (ADR-0061); the prompt
|
|
78
|
+
// channel of ADR-0063 adds its own variable, always written, so no
|
|
79
|
+
// nested pi inherits a stale one.
|
|
80
|
+
env: { ...this.#append.env, ...piEnv(options) },
|
|
81
|
+
stdin: "pipe",
|
|
82
|
+
stdout: "pipe",
|
|
83
|
+
// pi prints model and startup diagnostics to stderr and exits 1 (main() →
|
|
84
|
+
// reportDiagnostics → process.exit(1)), so stderr carries the only reason
|
|
85
|
+
// yaag can classify. The reader below drains it so pi never blocks.
|
|
86
|
+
stderr: "pipe",
|
|
87
|
+
// Its own process group, so the Agent sees stdin EOF rather than a signal
|
|
88
|
+
// when the Orchestrator dies — EOF is the path that reaps grandchildren.
|
|
89
|
+
detached: true,
|
|
90
|
+
});
|
|
91
|
+
} catch (error) {
|
|
92
|
+
// No Agent exists to dispose the channel later: a missing `pi` or a bad
|
|
93
|
+
// cwd would otherwise leave its temp directory behind forever.
|
|
94
|
+
this.#append.dispose();
|
|
95
|
+
throw error;
|
|
96
|
+
}
|
|
78
97
|
void this.#read();
|
|
79
98
|
// A stream error must not surface as an unhandled rejection: the tail is a
|
|
80
99
|
// best-effort diagnostic, never a reason to fail an Agent that started.
|
|
@@ -157,18 +176,23 @@ class LiveTransport implements AgentTransport {
|
|
|
157
176
|
// Stats first: they are unavailable once the process is gone (ticket 02).
|
|
158
177
|
const stats = await this.#readStats();
|
|
159
178
|
const pid = this.#process.pid;
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
179
|
+
try {
|
|
180
|
+
await reap({
|
|
181
|
+
exited: this.#process.exited,
|
|
182
|
+
endStdin: () => this.#process.stdin.end(),
|
|
183
|
+
terminate: () => this.#process.kill("SIGTERM"),
|
|
184
|
+
destroyGroup: () => {
|
|
185
|
+
try {
|
|
186
|
+
process.kill(-pid, "SIGKILL");
|
|
187
|
+
} catch {
|
|
188
|
+
this.#process.kill("SIGKILL");
|
|
189
|
+
}
|
|
190
|
+
},
|
|
191
|
+
});
|
|
192
|
+
} finally {
|
|
193
|
+
// A reap that throws must still release the Append Channel's temp file.
|
|
194
|
+
this.#append.dispose();
|
|
195
|
+
}
|
|
172
196
|
this.#queue.end();
|
|
173
197
|
this.#verification?.probe.fail(
|
|
174
198
|
new Error(`agent "${this.#name}" exited before tool verification completed`),
|