@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.
- package/package.json +1 -1
- package/src/agent/agent.ts +52 -2
- package/src/agent/fork.ts +7 -0
- package/src/agent/spawn-open.ts +25 -5
- package/src/agent/spawn-request.ts +123 -3
- package/src/agent/spawn.ts +6 -0
- package/src/ask/ask-hash.ts +7 -0
- package/src/ask-contract/ask-limit.ts +2 -4
- package/src/ask-contract/index.ts +2 -1
- package/src/ask-contract/wrap-up-steer.ts +17 -0
- package/src/cassette/index.ts +1 -0
- package/src/cassette/run-checkpoint.ts +17 -5
- package/src/contract/agent-policy.ts +15 -4
- package/src/contract/error-codes.ts +3 -2
- package/src/contract/index.ts +10 -0
- package/src/contract/spawn-options.ts +7 -1
- package/src/contract/system-prompt.ts +88 -0
- package/src/control/ask-admission.ts +24 -0
- package/src/control/control-commands.ts +300 -0
- package/src/control/index.ts +31 -0
- package/src/control/pause-drain.ts +105 -0
- package/src/control/run-controller.ts +88 -0
- package/src/events.ts +40 -0
- package/src/index.ts +30 -0
- package/src/public-api.ts +11 -0
- package/src/run/run-settlement.ts +93 -0
- package/src/run/run.ts +86 -32
- package/src/summary/summary.ts +6 -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,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, "&")
|
|
333
|
+
.replace(/</g, "<")
|
|
334
|
+
.replace(/>/g, ">")
|
|
335
|
+
.replace(/"/g, """)
|
|
336
|
+
.replace(/'/g, "'");
|
|
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";
|