@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
|
@@ -35,10 +35,16 @@ export interface SpawnOptions extends AgentPolicy {
|
|
|
35
35
|
* Link to a name, which travels in `OpenOptions` and stays out of Ask identity.
|
|
36
36
|
* `askDefaults` is omitted too: the Ask hash sees the defaults through the
|
|
37
37
|
* merged Ask options, so they never enter the recorded spawn options.
|
|
38
|
+
*
|
|
39
|
+
* `systemPrompt` narrows to a string: a Prompt Definition renders at the
|
|
40
|
+
* spawn-request seam, so no consumer of this shape can ever see a function
|
|
41
|
+
* (ADR-0064). An unset prompt stays unset here; the default text is filled in
|
|
42
|
+
* `openRequest` alone, so the Ask hash keeps hashing `systemPrompt: null`.
|
|
38
43
|
*/
|
|
39
44
|
export interface ResolvedSpawnOptions
|
|
40
|
-
extends Omit<SpawnOptions, "model" | "thinking" | "parent" | "askDefaults"> {
|
|
45
|
+
extends Omit<SpawnOptions, "model" | "thinking" | "parent" | "askDefaults" | "systemPrompt"> {
|
|
41
46
|
readonly model?: string;
|
|
47
|
+
readonly systemPrompt?: string;
|
|
42
48
|
readonly thinking?: ThinkingLevel;
|
|
43
49
|
}
|
|
44
50
|
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The author surface of a Prompt Definition (ADR-0057, ADR-0058, ADR-0064).
|
|
3
|
+
*
|
|
4
|
+
* Types only, and no import outside this directory (ADR-0045). The values that
|
|
5
|
+
* build a Prompt Definition live in `system-prompt/define-system-prompt.ts`.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
/** Brand of a rendered prompt text; no program can build the symbol. */
|
|
9
|
+
declare const renderedPromptText: unique symbol;
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* What `yaagSystemPrompt` and every `ctx.render*()` call return: a string that
|
|
13
|
+
* holds Render Sentinels. It is a `string` everywhere, except where a literal
|
|
14
|
+
* prompt is expected — that is the compile-time half of ADR-0060.
|
|
15
|
+
*/
|
|
16
|
+
export type PromptText = string & { readonly [renderedPromptText]: "yaag" };
|
|
17
|
+
|
|
18
|
+
/** A `systemPrompt` string a program wrote itself, so not a `PromptText`. */
|
|
19
|
+
export type LiteralPromptText = string & { readonly [renderedPromptText]?: undefined };
|
|
20
|
+
|
|
21
|
+
/** Who reads what an Agent writes. `"user"` is not reachable from a program yet. */
|
|
22
|
+
export type PromptAudience = "program" | "user";
|
|
23
|
+
|
|
24
|
+
/** What a Prompt Definition learns about the Agent it writes the prompt for. */
|
|
25
|
+
export interface SystemPromptAgent {
|
|
26
|
+
/** The Agent name, as the Run allocated it. */
|
|
27
|
+
readonly name: string;
|
|
28
|
+
/** The Run name, the same value `run_start.program` carries. */
|
|
29
|
+
readonly runName: string;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* The Prompt Context: one method per Prompt Variable.
|
|
34
|
+
*
|
|
35
|
+
* Every method is **write-only**. It returns a Render Sentinel, an opaque
|
|
36
|
+
* marker, and not the text behind it: the facts exist only inside the Agent
|
|
37
|
+
* process, and the private prompt extension puts them in there. Put the result
|
|
38
|
+
* in the prompt; do not read it, match it, or split on it.
|
|
39
|
+
*/
|
|
40
|
+
export interface SystemPromptContext {
|
|
41
|
+
/** Writes the model the Agent runs on, as `provider/id`. */
|
|
42
|
+
renderModel(): PromptText;
|
|
43
|
+
/** Writes the Agent process id. */
|
|
44
|
+
renderPid(): PromptText;
|
|
45
|
+
/** Writes the time the Agent started, in ISO 8601. */
|
|
46
|
+
renderStartedAt(): PromptText;
|
|
47
|
+
/** Writes the time of the current turn, in ISO 8601. */
|
|
48
|
+
renderCurrentDateTime(): PromptText;
|
|
49
|
+
/** Writes the Agent working directory. */
|
|
50
|
+
renderCwd(): PromptText;
|
|
51
|
+
/** Writes the tool list of the Agent, one line per tool. */
|
|
52
|
+
renderTools(): PromptText;
|
|
53
|
+
/** Writes the user's `APPEND_SYSTEM.md`. */
|
|
54
|
+
renderAppendSystem(): PromptText;
|
|
55
|
+
/** Writes the text the program set with `appendSystemPrompt`. */
|
|
56
|
+
renderProgramAppend(): PromptText;
|
|
57
|
+
/** Writes the context files pi loaded, in pi's own block format. */
|
|
58
|
+
renderContextFiles(): PromptText;
|
|
59
|
+
/** Writes the skills pi loaded, in pi's own block format. */
|
|
60
|
+
renderSkills(): PromptText;
|
|
61
|
+
/** Writes the default system prompt pi would have built alone. */
|
|
62
|
+
renderPiDefaultPrompt(): PromptText;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** The one object a Prompt Definition builder receives. */
|
|
66
|
+
export interface SystemPromptInput {
|
|
67
|
+
/** The write-only Prompt Context. */
|
|
68
|
+
readonly ctx: SystemPromptContext;
|
|
69
|
+
/** The Agent this prompt is for. */
|
|
70
|
+
readonly agent: SystemPromptAgent;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Builds one Agent's system prompt. It must be pure and synchronous, and it
|
|
75
|
+
* runs in the Orchestrator exactly once per spawn.
|
|
76
|
+
*/
|
|
77
|
+
export type SystemPromptBuilder = (input: SystemPromptInput) => string;
|
|
78
|
+
|
|
79
|
+
/** Brand of a Prompt Definition; no program can build the symbol. */
|
|
80
|
+
declare const systemPromptDefinition: unique symbol;
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* The opaque, frozen result of `defineSystemPrompt`. It is a value a spawn
|
|
84
|
+
* carries, not a string: yaag renders it at the spawn-request seam.
|
|
85
|
+
*/
|
|
86
|
+
export interface SystemPromptDefinition {
|
|
87
|
+
readonly [systemPromptDefinition]: true;
|
|
88
|
+
}
|
package/src/errors.ts
CHANGED
|
@@ -22,7 +22,12 @@ export type {
|
|
|
22
22
|
YaagErrorCode,
|
|
23
23
|
} from "./contract/index.ts";
|
|
24
24
|
|
|
25
|
-
/**
|
|
25
|
+
/**
|
|
26
|
+
* The single error class of the runtime (ADR-0003).
|
|
27
|
+
*
|
|
28
|
+
* The fifth constructor parameter `cause` goes to `Error.prototype.cause`, so
|
|
29
|
+
* a wrapped failure keeps its origin.
|
|
30
|
+
*/
|
|
26
31
|
export class YaagError extends Error {
|
|
27
32
|
readonly code: YaagErrorCode;
|
|
28
33
|
/** Agent name, when the error concerns one. */
|
|
@@ -57,8 +62,9 @@ export class YaagError extends Error {
|
|
|
57
62
|
| AskStalledOutcome
|
|
58
63
|
| AskInvalidOutputOutcome
|
|
59
64
|
| ModelResolutionOutcome,
|
|
65
|
+
cause?: unknown,
|
|
60
66
|
) {
|
|
61
|
-
super(message);
|
|
67
|
+
super(message, { cause });
|
|
62
68
|
this.name = "YaagError";
|
|
63
69
|
this.code = code;
|
|
64
70
|
if (agent !== undefined) this.agent = agent;
|
package/src/index.ts
CHANGED
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
export type { AgentConfig, AgentDefinition } from "./agent/index.ts";
|
|
2
|
-
export {
|
|
2
|
+
export {
|
|
3
|
+
agentDefinitionConfig,
|
|
4
|
+
defineAgent,
|
|
5
|
+
isAgentDefinition,
|
|
6
|
+
isSpawnableDefinition,
|
|
7
|
+
} from "./agent/index.ts";
|
|
3
8
|
export type {
|
|
4
9
|
Cassette,
|
|
5
10
|
CassetteAgent,
|
|
@@ -48,6 +53,7 @@ export {
|
|
|
48
53
|
AGENT_DESCRIBE_TRANSCRIPT,
|
|
49
54
|
agentDescribeArgv,
|
|
50
55
|
CATALOG_FIXTURE,
|
|
56
|
+
createYaagGlobal,
|
|
51
57
|
describedAgent,
|
|
52
58
|
encodeAgentDescribe,
|
|
53
59
|
filterCatalog,
|
|
@@ -181,6 +187,11 @@ export type {
|
|
|
181
187
|
RunSummary,
|
|
182
188
|
} from "./summary/index.ts";
|
|
183
189
|
export { applyEvent, initialSummary } from "./summary/index.ts";
|
|
190
|
+
export type { YaagSystemPromptOptions } from "./system-prompt/index.ts";
|
|
191
|
+
// `isSystemPromptDefinition` and `renderSystemPrompt` stay on
|
|
192
|
+
// `system-prompt/index.ts`: the spawn seam uses them, and no consumer outside
|
|
193
|
+
// this package does.
|
|
194
|
+
export { defineSystemPrompt, yaagSystemPrompt } from "./system-prompt/index.ts";
|
|
184
195
|
export type {
|
|
185
196
|
AgentStats,
|
|
186
197
|
AgentTransport,
|
|
@@ -219,10 +230,18 @@ export type {
|
|
|
219
230
|
AskOptions,
|
|
220
231
|
ForkOptions,
|
|
221
232
|
Handle,
|
|
233
|
+
LiteralPromptText,
|
|
234
|
+
PromptAudience,
|
|
235
|
+
PromptText,
|
|
222
236
|
ResolvedSpawnOptions,
|
|
223
237
|
SpawnOptions,
|
|
224
238
|
SpawnOverrides,
|
|
225
239
|
StructuredAskOptions,
|
|
240
|
+
SystemPromptAgent,
|
|
241
|
+
SystemPromptBuilder,
|
|
242
|
+
SystemPromptContext,
|
|
243
|
+
SystemPromptDefinition,
|
|
244
|
+
SystemPromptInput,
|
|
226
245
|
ThinkingLevel,
|
|
227
246
|
} from "./types.ts";
|
|
228
247
|
export {
|
package/src/public-api.ts
CHANGED
|
@@ -12,13 +12,27 @@
|
|
|
12
12
|
|
|
13
13
|
export type { AgentConfig, AgentDefinition } from "./agent/define-agent.ts";
|
|
14
14
|
export { defineAgent } from "./agent/define-agent.ts";
|
|
15
|
+
export type {
|
|
16
|
+
CatalogScope,
|
|
17
|
+
SpawnableDefinition,
|
|
18
|
+
YaagGlobal,
|
|
19
|
+
YaagGlobalOptions,
|
|
20
|
+
} from "./contract/catalog-resolve.ts";
|
|
15
21
|
export type {
|
|
16
22
|
AgentPolicy,
|
|
17
23
|
AskOptions,
|
|
18
24
|
Handle,
|
|
25
|
+
LiteralPromptText,
|
|
26
|
+
PromptAudience,
|
|
27
|
+
PromptText,
|
|
19
28
|
SpawnOptions,
|
|
20
29
|
SpawnOverrides,
|
|
21
30
|
StructuredAskOptions,
|
|
31
|
+
SystemPromptAgent,
|
|
32
|
+
SystemPromptBuilder,
|
|
33
|
+
SystemPromptContext,
|
|
34
|
+
SystemPromptDefinition,
|
|
35
|
+
SystemPromptInput,
|
|
22
36
|
ThinkingLevel,
|
|
23
37
|
} from "./contract/index.ts";
|
|
24
38
|
export type { YaagErrorCode } from "./errors.ts";
|
|
@@ -46,3 +60,6 @@ export { prompt } from "./prompt/prompt.ts";
|
|
|
46
60
|
export type { OrchestrationProgram, ProgramDefinition } from "./run/define-run.ts";
|
|
47
61
|
export { defineRun } from "./run/define-run.ts";
|
|
48
62
|
export type { RunContext } from "./run/run-context.ts";
|
|
63
|
+
export type { YaagSystemPromptOptions } from "./system-prompt/agent-system-prompt.ts";
|
|
64
|
+
export { yaagSystemPrompt } from "./system-prompt/agent-system-prompt.ts";
|
|
65
|
+
export { defineSystemPrompt } from "./system-prompt/define-system-prompt.ts";
|
package/src/run/run-context.ts
CHANGED
|
@@ -1,7 +1,12 @@
|
|
|
1
1
|
// `../agent/define-agent.ts` is a deep import on purpose: the author
|
|
2
2
|
// declaration tree must not pull the `agent/` barrel (ADR-0045).
|
|
3
3
|
import type { AgentDefinition } from "../agent/define-agent.ts";
|
|
4
|
-
import type {
|
|
4
|
+
import type {
|
|
5
|
+
Handle,
|
|
6
|
+
SpawnableDefinition,
|
|
7
|
+
SpawnOptions,
|
|
8
|
+
SpawnOverrides,
|
|
9
|
+
} from "../contract/index.ts";
|
|
5
10
|
import type { ProfiledDefinition } from "../profile/use-profile.ts";
|
|
6
11
|
|
|
7
12
|
/** What an Orchestration Program is handed. */
|
|
@@ -20,6 +25,8 @@ export interface RunContext<Args = unknown> {
|
|
|
20
25
|
spawn(options?: SpawnOptions): Promise<Handle>;
|
|
21
26
|
spawn(definition: AgentDefinition, overrides?: SpawnOverrides): Promise<Handle>;
|
|
22
27
|
spawn(profiled: ProfiledDefinition, overrides?: SpawnOverrides): Promise<Handle>;
|
|
28
|
+
/** Last on purpose: a union-typed value, e.g. what a Catalog Resolve gave back (ADR-0053). */
|
|
29
|
+
spawn(definition: SpawnableDefinition, overrides?: SpawnOverrides): Promise<Handle>;
|
|
23
30
|
/**
|
|
24
31
|
* The Profile this Run activated (ADR-0052). Defined when the program
|
|
25
32
|
* declares Profiles, undefined otherwise.
|
package/src/run/run.ts
CHANGED
|
@@ -204,6 +204,9 @@ export async function executeRun<Args, Result>(
|
|
|
204
204
|
askAdmission,
|
|
205
205
|
sessionDir: options.sessionDir,
|
|
206
206
|
programFile: options.programFile,
|
|
207
|
+
// The same value `run_start.program` carries, so an Agent's prompt names
|
|
208
|
+
// the Run the reader sees in the Run record.
|
|
209
|
+
runName: definition.name ?? "program",
|
|
207
210
|
configExtensions: options.config?.extensions ?? EMPTY_EFFECTIVE_CONFIG.extensions,
|
|
208
211
|
...(profile === undefined ? {} : { profile }),
|
|
209
212
|
});
|
|
@@ -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);
|