@yaag/runtime 0.22.0 → 0.24.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.
Files changed (42) hide show
  1. package/package.json +1 -1
  2. package/src/agent/agent.ts +52 -2
  3. package/src/agent/fork.ts +7 -0
  4. package/src/agent/spawn-open.ts +25 -5
  5. package/src/agent/spawn-request.ts +123 -3
  6. package/src/agent/spawn.ts +6 -0
  7. package/src/ask/ask-hash.ts +7 -0
  8. package/src/ask-contract/ask-limit.ts +2 -4
  9. package/src/ask-contract/index.ts +2 -1
  10. package/src/ask-contract/wrap-up-steer.ts +17 -0
  11. package/src/cassette/index.ts +1 -0
  12. package/src/cassette/run-checkpoint.ts +17 -5
  13. package/src/contract/agent-policy.ts +15 -4
  14. package/src/contract/error-codes.ts +3 -2
  15. package/src/contract/index.ts +10 -0
  16. package/src/contract/spawn-options.ts +7 -1
  17. package/src/contract/system-prompt.ts +88 -0
  18. package/src/control/ask-admission.ts +24 -0
  19. package/src/control/control-commands.ts +300 -0
  20. package/src/control/index.ts +31 -0
  21. package/src/control/pause-drain.ts +105 -0
  22. package/src/control/run-controller.ts +88 -0
  23. package/src/events.ts +40 -0
  24. package/src/index.ts +30 -0
  25. package/src/public-api.ts +11 -0
  26. package/src/run/run-settlement.ts +93 -0
  27. package/src/run/run.ts +86 -32
  28. package/src/summary/summary.ts +6 -0
  29. package/src/system-prompt/agent-prompt-extension.ts +337 -0
  30. package/src/system-prompt/agent-prompt.ts +15 -0
  31. package/src/system-prompt/agent-system-prompt.ts +90 -0
  32. package/src/system-prompt/append-channel.ts +69 -0
  33. package/src/system-prompt/define-system-prompt.ts +112 -0
  34. package/src/system-prompt/index.ts +48 -0
  35. package/src/system-prompt/prompt-guards.ts +60 -0
  36. package/src/system-prompt/render-sentinel.ts +75 -0
  37. package/src/transport/append-env.ts +69 -0
  38. package/src/transport/index.ts +2 -0
  39. package/src/transport/live-transport.ts +50 -26
  40. package/src/transport/pi-state.ts +38 -4
  41. package/src/transport/transport.ts +4 -1
  42. package/src/types.ts +8 -0
@@ -0,0 +1,337 @@
1
+ /**
2
+ * yaag's private prompt extension, loaded first into every Agent (ADR-0063).
3
+ *
4
+ * The Orchestrator cannot render the Agent System Prompt: the tool snippets,
5
+ * the context files, the skills and the pid exist only inside the Agent
6
+ * process. So the Orchestrator sends a text full of Render Sentinels through
7
+ * `--system-prompt`, and this extension replaces each sentinel with real text
8
+ * on every `before_agent_start` (ADR-0055, ADR-0056).
9
+ *
10
+ * It loads before every program extension, so a program extension appends to
11
+ * the assembled Agent System Prompt, and the recorder still records the final
12
+ * text (ADR-0063).
13
+ *
14
+ * The prompt reaches this extension on one of two channels. When it asks for
15
+ * `piDefaultPrompt`, yaag spends no `--system-prompt` and sends the text in
16
+ * `YAAG_SYSTEM_PROMPT` instead; pi then builds its own default prompt, this
17
+ * extension receives it as `event.systemPrompt`, and `piDefaultPrompt` is
18
+ * exact (ADR-0063 amendment 2). The two channels fail differently, and the env
19
+ * channel fails quietly: a broken or unloaded extension leaves the flag channel
20
+ * showing raw `<<<yaag:render:…>>>` markers to the model, while on the env
21
+ * channel the Agent silently runs on pi's own default prompt and the program's
22
+ * text is dropped. Otherwise the text arrives on the flag, and
23
+ * the paragraph below states what `piDefaultPrompt` would mean there.
24
+ *
25
+ * On the flag channel `event.systemPrompt` as received is *not* pi's guideline-bearing default
26
+ * prompt, and `piDefaultPrompt` therefore does not print one. On this channel
27
+ * yaag passed `--system-prompt`, so pi takes its `customPrompt` branch
28
+ * (`dist/core/system-prompt.js:15-33`), which emits
29
+ * `customPrompt + append + context + skills + cwd line` and no tool or
30
+ * guideline text at all. What arrives here is this module's own still
31
+ * *unexpanded* sentinel text plus those tails — so `piDefaultPrompt` expands to
32
+ * text that still contains raw `<<<yaag:render:...>>>` markers, and
33
+ * `expandPrompt` does not re-scan what it inserted. That is harmless only
34
+ * because the default text has no `piDefaultPrompt` slot today. The flag
35
+ * channel therefore never carries pi's guideline prompt. This is why a prompt
36
+ * that asks for `piDefaultPrompt` takes the env channel described above, where
37
+ * pi builds its default prompt itself and the helper is exact
38
+ * (ADR-0063 amendment 2, `pi-state.ts:piEnv`).
39
+ *
40
+ * Types are declared locally rather than imported from pi: this file is passed
41
+ * to `pi -e` as a path and must load without yaag's dependency graph. pi loads
42
+ * it through jiti, in Node, so it uses no Bun-only API. Its two relative
43
+ * imports are sibling files that are import-free by design.
44
+ *
45
+ * It reads two environment variables: `YAAG_SYSTEM_PROMPT` carries the prompt
46
+ * on the env channel described above, and the Append Channel carries the
47
+ * program's append text from the Orchestrator (ADR-0061), inline or as a temp
48
+ * file path.
49
+ */
50
+
51
+ import { readFileSync } from "node:fs";
52
+ import { APPEND_SYSTEM_PROMPT_ENV, readProgramAppend } from "./append-channel.ts";
53
+ import { isPromptVariable, SYSTEM_PROMPT_ENV, sentinelPattern } from "./render-sentinel.ts";
54
+
55
+ /** A context file pi loaded (`AGENTS.md` and friends). */
56
+ interface ContextFile {
57
+ readonly path?: unknown;
58
+ readonly content?: unknown;
59
+ }
60
+
61
+ /** One skill pi loaded. */
62
+ interface LoadedSkill {
63
+ readonly name?: unknown;
64
+ readonly description?: unknown;
65
+ readonly filePath?: unknown;
66
+ readonly disableModelInvocation?: unknown;
67
+ }
68
+
69
+ /** The structured options pi used to build the system prompt. */
70
+ interface SystemPromptOptions {
71
+ readonly customPrompt?: unknown;
72
+ readonly selectedTools?: unknown;
73
+ readonly toolSnippets?: unknown;
74
+ readonly appendSystemPrompt?: unknown;
75
+ readonly cwd?: unknown;
76
+ readonly contextFiles?: unknown;
77
+ readonly skills?: unknown;
78
+ }
79
+
80
+ /** The pi event that carries the assembled prompt of one turn. */
81
+ interface BeforeAgentStart {
82
+ readonly systemPrompt?: unknown;
83
+ readonly systemPromptOptions?: SystemPromptOptions | undefined;
84
+ }
85
+
86
+ /** The pi context slice this extension reads. */
87
+ interface PromptContext {
88
+ readonly model?: unknown;
89
+ }
90
+
91
+ /** The pi surface this extension registers on. */
92
+ interface PromptAPI {
93
+ on(
94
+ event: "before_agent_start",
95
+ handler: (
96
+ event: BeforeAgentStart,
97
+ context: PromptContext,
98
+ ) => { systemPrompt: string } | undefined,
99
+ ): void;
100
+ }
101
+
102
+ /** Fixed at load, so `startedAt` is the Agent's start and never a turn's time. */
103
+ const STARTED_AT = new Date();
104
+
105
+ export default function (pi: PromptAPI): void {
106
+ pi.on("before_agent_start", (event, ctx) => handleBeforeAgentStart(event, ctx));
107
+ }
108
+
109
+ /**
110
+ * Expands the Agent System Prompt for one turn, or leaves the prompt alone.
111
+ *
112
+ * The test is purely syntactic: **any** `customPrompt` holding a well-formed
113
+ * marker is expanded, including one a program wrote itself. This extension runs
114
+ * inside the Agent and cannot tell yaag's own text from a program's, so it does
115
+ * not try. A program-set prompt with no marker in it — the normal case — is
116
+ * left exactly as it is.
117
+ *
118
+ * That a program can reach this path at all is temporary. ADR-0060 rejects a
119
+ * leaked Sentinel in the Orchestrator, at spawn time, so no such prompt ever
120
+ * reaches an Agent; until that lands, the expansion here is the observed
121
+ * behaviour and `agent-prompt-extension.test.ts` pins it.
122
+ */
123
+ export function handleBeforeAgentStart(
124
+ event: BeforeAgentStart,
125
+ ctx: PromptContext,
126
+ sources: PromptSources = {},
127
+ ): { systemPrompt: string } | undefined {
128
+ const fromEnv = process.env[SYSTEM_PROMPT_ENV];
129
+ const custom =
130
+ typeof fromEnv === "string" && fromEnv !== ""
131
+ ? fromEnv
132
+ : event.systemPromptOptions?.customPrompt;
133
+ if (typeof custom !== "string" || !sentinelPattern().test(custom)) return undefined;
134
+ return { systemPrompt: expandPrompt(custom, promptFacts(event, ctx, sources), sources.warn) };
135
+ }
136
+
137
+ /** What one turn's facts come from. Every part is injectable, so a test can pin it. */
138
+ export interface PromptSources {
139
+ readonly now?: () => Date;
140
+ readonly warn?: (line: string) => void;
141
+ readonly env?: Readonly<Record<string, string | undefined>>;
142
+ readonly readFile?: (path: string) => string;
143
+ }
144
+
145
+ /**
146
+ * The program's append text, read once per Agent: a multi-turn Agent must not
147
+ * re-read the temp file every turn. An injected environment bypasses the cache.
148
+ */
149
+ let programAppendCache: string | undefined;
150
+
151
+ function programAppendText(sources: PromptSources): string {
152
+ const readFile = sources.readFile ?? ((path: string) => readFileSync(path, "utf8"));
153
+ if (sources.env !== undefined || sources.readFile !== undefined) {
154
+ const env = sources.env ?? process.env;
155
+ return readProgramAppend(env[APPEND_SYSTEM_PROMPT_ENV], readFile, sources.warn);
156
+ }
157
+ programAppendCache ??= readProgramAppend(
158
+ process.env[APPEND_SYSTEM_PROMPT_ENV],
159
+ readFile,
160
+ sources.warn,
161
+ );
162
+ return programAppendCache;
163
+ }
164
+
165
+ /** The real text behind each Prompt Variable, for one turn of one Agent. */
166
+ export interface PromptFacts {
167
+ readonly model: string;
168
+ readonly pid: string;
169
+ readonly startedAt: string;
170
+ readonly currentDateTime: string;
171
+ readonly cwd: string;
172
+ readonly tools: string;
173
+ readonly appendSystem: string;
174
+ readonly programAppend: string;
175
+ readonly contextFiles: string;
176
+ readonly skills: string;
177
+ readonly piDefaultPrompt: string;
178
+ }
179
+
180
+ /**
181
+ * Reads every Prompt Variable's text out of one `before_agent_start`.
182
+ *
183
+ * The clock is a parameter so a test can prove the claim the prompt makes:
184
+ * `Now` moves between turns while `Started` does not.
185
+ */
186
+ export function promptFacts(
187
+ event: BeforeAgentStart,
188
+ ctx: PromptContext,
189
+ sources: PromptSources = {},
190
+ ): PromptFacts {
191
+ const options = event.systemPromptOptions ?? {};
192
+ const now = sources.now ?? (() => new Date());
193
+ return {
194
+ model: readModelName(ctx.model),
195
+ pid: String(process.pid),
196
+ startedAt: STARTED_AT.toISOString(),
197
+ // Moves per turn, because the extension rebuilds the prompt every turn
198
+ // (ADR-0058).
199
+ currentDateTime: now().toISOString(),
200
+ cwd: readString(options.cwd),
201
+ tools: renderTools(options),
202
+ // The two append sources are separate now (ADR-0059, ADR-0061). yaag passes
203
+ // no `--append-system-prompt`, so `options.appendSystemPrompt` is exactly
204
+ // what pi discovered under its own trust rule — `.pi/APPEND_SYSTEM.md` in a
205
+ // trusted project, else `~/.pi/agent/APPEND_SYSTEM.md` — while the
206
+ // program's own text arrives through the Append Channel in the environment.
207
+ programAppend: programAppendText(sources),
208
+ appendSystem: readString(options.appendSystemPrompt),
209
+ contextFiles: renderContextFiles(options.contextFiles),
210
+ skills: renderSkills(options),
211
+ piDefaultPrompt: readString(event.systemPrompt),
212
+ };
213
+ }
214
+
215
+ /**
216
+ * Replaces every Render Sentinel with its text.
217
+ *
218
+ * An unknown marker is stripped and reported once, so a prompt written by a
219
+ * newer yaag never reaches a model with raw markers in it (ADR-0063).
220
+ */
221
+ export function expandPrompt(
222
+ text: string,
223
+ facts: PromptFacts,
224
+ warn: (line: string) => void = (line) => {
225
+ process.stderr.write(line);
226
+ },
227
+ ): string {
228
+ const unknown: string[] = [];
229
+ const expanded = text.replace(sentinelPattern(), (_match, name: string) => {
230
+ if (isPromptVariable(name)) return facts[name];
231
+ unknown.push(name);
232
+ return "";
233
+ });
234
+ if (unknown.length > 0) {
235
+ warn(`yaag: unknown system prompt marker removed: ${unknown.join(", ")}\n`);
236
+ }
237
+ return tidy(expanded);
238
+ }
239
+
240
+ /** Collapses the holes an empty Prompt Variable leaves behind. */
241
+ function tidy(text: string): string {
242
+ return text
243
+ .replace(/[ \t]+$/gm, "")
244
+ .replace(/\n{3,}/g, "\n\n")
245
+ .trim();
246
+ }
247
+
248
+ /** `provider/id` when pi resolved both, else the id, else `"unknown"`. */
249
+ function readModelName(model: unknown): string {
250
+ if (typeof model !== "object" || model === null || !("id" in model)) return "unknown";
251
+ const id: unknown = model.id;
252
+ if (typeof id !== "string") return "unknown";
253
+ const provider: unknown = "provider" in model ? model.provider : undefined;
254
+ return typeof provider === "string" ? `${provider}/${id}` : id;
255
+ }
256
+
257
+ function readString(value: unknown): string {
258
+ return typeof value === "string" ? value : "";
259
+ }
260
+
261
+ function readStrings(value: unknown): readonly string[] {
262
+ return Array.isArray(value)
263
+ ? value.filter((item): item is string => typeof item === "string")
264
+ : [];
265
+ }
266
+
267
+ /**
268
+ * The tool lines, in pi's own format: a tool appears only when the caller gave
269
+ * it a one-line snippet (pi `dist/core/system-prompt.js` lines 42-44).
270
+ */
271
+ function renderTools(options: SystemPromptOptions): string {
272
+ const snippets: Record<string, unknown> =
273
+ typeof options.toolSnippets === "object" && options.toolSnippets !== null
274
+ ? { ...options.toolSnippets }
275
+ : {};
276
+ const lines = readStrings(options.selectedTools)
277
+ .filter((name) => typeof snippets[name] === "string" && snippets[name] !== "")
278
+ .map((name) => `- ${name}: ${String(snippets[name])}`);
279
+ return lines.length > 0 ? lines.join("\n") : "(none)";
280
+ }
281
+
282
+ /**
283
+ * The `<project_context>` block, byte-for-byte with pi
284
+ * `dist/core/system-prompt.js` lines 20-27.
285
+ */
286
+ function renderContextFiles(value: unknown): string {
287
+ const files = Array.isArray(value) ? (value as ContextFile[]) : [];
288
+ if (files.length === 0) return "";
289
+ let block = "<project_context>\n\nProject-specific instructions and guidelines:\n\n";
290
+ for (const file of files) {
291
+ const path = readString(file.path);
292
+ const content = readString(file.content);
293
+ block += `<project_instructions path="${path}">\n${content}\n</project_instructions>\n\n`;
294
+ }
295
+ return `${block}</project_context>`;
296
+ }
297
+
298
+ /**
299
+ * The `<available_skills>` block, in pi's format (`dist/core/skills.js` lines
300
+ * 275-305). Skills appear only when a tool that can read their files is active.
301
+ */
302
+ function renderSkills(options: SystemPromptOptions): string {
303
+ const tools = readStrings(options.selectedTools);
304
+ const fileReadTool = ["read", "bash"].find((tool) => tools.includes(tool));
305
+ if (fileReadTool === undefined) return "";
306
+ const skills = (Array.isArray(options.skills) ? (options.skills as LoadedSkill[]) : []).filter(
307
+ (skill) => skill.disableModelInvocation !== true,
308
+ );
309
+ if (skills.length === 0) return "";
310
+ const lines = [
311
+ "The following skills provide specialized instructions for specific tasks.",
312
+ fileReadTool === "read"
313
+ ? "Use the read tool to load a skill's file when the task matches its description."
314
+ : "Use bash to load a skill's file when the task matches its description.",
315
+ "When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
316
+ "",
317
+ "<available_skills>",
318
+ ];
319
+ for (const skill of skills) {
320
+ lines.push(" <skill>");
321
+ lines.push(` <name>${escapeXml(readString(skill.name))}</name>`);
322
+ lines.push(` <description>${escapeXml(readString(skill.description))}</description>`);
323
+ lines.push(` <location>${escapeXml(readString(skill.filePath))}</location>`);
324
+ lines.push(" </skill>");
325
+ }
326
+ lines.push("</available_skills>");
327
+ return lines.join("\n");
328
+ }
329
+
330
+ function escapeXml(value: string): string {
331
+ return value
332
+ .replace(/&/g, "&amp;")
333
+ .replace(/</g, "&lt;")
334
+ .replace(/>/g, "&gt;")
335
+ .replace(/"/g, "&quot;")
336
+ .replace(/'/g, "&apos;");
337
+ }
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Where the private prompt extension lives (ADR-0063).
3
+ *
4
+ * `piCommand` loads the extension from here, so the writer of the command line
5
+ * and the file on disk derive from one place, exactly as the recorder does.
6
+ */
7
+ import { fileURLToPath } from "node:url";
8
+
9
+ /** Filesystem sibling path of the prompt extension; decodes percent-escapes. */
10
+ export function agentPromptExtensionPath(moduleUrl: string): string {
11
+ return fileURLToPath(new URL("./agent-prompt-extension.ts", moduleUrl));
12
+ }
13
+
14
+ /** Loadable source path for the private extension that expands the prompt. */
15
+ export const AGENT_PROMPT_EXTENSION_PATH = agentPromptExtensionPath(import.meta.url);
@@ -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";