@yaag/runtime 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/runtime",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public"
   },

package/src/index.ts

@@ -72,6 +72,7 @@ export type {
   RunSummary,
 } from "./summary.ts";
 export { applyEvent, initialSummary } from "./summary.ts";
+export { readSystemPromptSidecar } from "./system-prompt-recorder.ts";
 export type {
   AgentStats,
   AgentTransport,

package/src/live-transport.ts

@@ -5,9 +5,10 @@ import { piCommand, readModel, readSessionFile, readStats } from "./pi-state.ts"
 import { reap } from "./reap.ts";
 import {
   createToolProbe,
-  requestedToolNames,
   TOOL_PROBE_EXTENSION_PATH,
+  type ToolContract,
   type ToolProbe,
+  toolContract,
   verifyEffectiveTools,
 } from "./tool-probe.ts";
 import type {
@@ -44,17 +45,18 @@ class LiveTransport implements AgentTransport {
   readonly #process: Bun.Subprocess<"pipe", "pipe", "ignore">;
   readonly #queue = new FrameQueue();
   readonly #pending = new Map<string, (frame: Frame) => void>();
-  readonly #toolProbe: ToolProbe | null;
-  readonly #promisedTools: readonly string[] | null;
+  /** Both halves of tool verification, or null when the spawn promised nothing. */
+  readonly #verification: { readonly contract: ToolContract; readonly probe: ToolProbe } | null;
+
   #nextId = 0;
   #closing: Promise<AgentStats> | null = null;
 
   constructor(options: OpenOptions) {
     this.#name = options.name;
-    this.#promisedTools = requestedToolNames(options.tools, options.disallowedTools);
-    this.#toolProbe = createToolProbe(options.tools, options.disallowedTools);
+    const contract = toolContract(options);
+    this.#verification = contract === null ? null : { contract, probe: createToolProbe() };
     this.#process = Bun.spawn({
-      cmd: piCommand(options, this.#toolProbe ? TOOL_PROBE_EXTENSION_PATH : undefined),
+      cmd: piCommand(options, this.#verification ? TOOL_PROBE_EXTENSION_PATH : undefined),
       cwd: options.cwd,
       stdin: "pipe",
       stdout: "pipe",
@@ -72,8 +74,9 @@ class LiveTransport implements AgentTransport {
       const state = await this.#command({ type: "get_state" }, READY_TIMEOUT_MS);
       const model = readModel(state);
       if (!model) throw new Error(`agent "${this.#name}" reported no model`);
-      if (this.#toolProbe && this.#promisedTools) {
-        verifyEffectiveTools(this.#promisedTools, await this.#toolProbe.wait());
+      if (this.#verification !== null) {
+        const { contract, probe } = this.#verification;
+        verifyEffectiveTools(contract, await probe.wait());
       }
       this.model = model;
       const sessionFile = readSessionFile(state);
@@ -133,7 +136,7 @@ class LiveTransport implements AgentTransport {
       },
     });
     this.#queue.end();
-    this.#toolProbe?.fail(
+    this.#verification?.probe.fail(
       new Error(`agent "${this.#name}" exited before tool verification completed`),
     );
     return stats;
@@ -179,7 +182,7 @@ class LiveTransport implements AgentTransport {
 
   async #read(): Promise<void> {
     for await (const frame of decodeFrames(readChunks(this.#process.stdout))) {
-      if (this.#toolProbe?.accept(frame)) continue;
+      if (this.#verification?.probe.accept(frame)) continue;
       const id = typeof frame.id === "string" ? frame.id : "";
       const waiting = frame.type === "response" ? this.#pending.get(id) : undefined;
       if (waiting) {
@@ -190,7 +193,7 @@ class LiveTransport implements AgentTransport {
       this.#queue.push(frame);
     }
     this.#queue.end();
-    this.#toolProbe?.fail(
+    this.#verification?.probe.fail(
       new Error(`agent "${this.#name}" exited before tool verification completed`),
     );
   }

package/src/pi-state.ts

@@ -1,4 +1,5 @@
 import { REPORT_RESULT_EXTENSION_PATH, REPORT_RESULT_TOOL_NAME } from "./report-result.ts";
+import { SYSTEM_PROMPT_RECORDER_EXTENSION_PATH } from "./system-prompt-recorder.ts";
 import type { AgentStats, Frame, OpenOptions, TokenBreakdown } from "./transport.ts";
 
 /** What the Agent reported about its own work, read from a `get_state` probe. */
@@ -33,7 +34,7 @@ function appendCapabilities(
   toolProbeExtensionPath: string | undefined,
 ): void {
   const hermetic = options.inherit !== true;
-  appendTools(cmd, options, hermetic);
+  appendTools(cmd, options);
   if (options.resolvedSkillPaths === undefined) {
     if (hermetic) cmd.push("--no-skills");
   } else {
@@ -48,13 +49,12 @@ function appendCapabilities(
   // output schema long after the process started and pi loads extensions only
   // at startup (ADR-0032).
   cmd.push("-e", REPORT_RESULT_EXTENSION_PATH);
-  if (
-    options.tools !== undefined &&
-    options.tools.length > 0 &&
-    toolProbeExtensionPath !== undefined
-  ) {
-    cmd.push("-e", toolProbeExtensionPath);
-  }
+  // The caller decides whether the probe runs: it loads the extension only when
+  // the spawn flags promised something verifiable (see toolContract).
+  if (toolProbeExtensionPath !== undefined) cmd.push("-e", toolProbeExtensionPath);
+  // The system-prompt recorder loads last of all: `before_agent_start` handlers
+  // chain in load order, so only the last one sees every other append.
+  cmd.push("-e", SYSTEM_PROMPT_RECORDER_EXTENSION_PATH);
   if (options.disallowedTools !== undefined) {
     // The private tool is never a program's to deny: excluding it would fail
     // every schema-bearing Ask with "agent did not call report_result". A
@@ -66,8 +66,18 @@ function appendCapabilities(
   }
 }
 
+/** The spawn options that decide pi's `--tools` allowlist. */
+export interface ToolSelection {
+  readonly tools?: readonly string[] | undefined;
+  readonly inherit?: boolean | undefined;
+}
+
 /**
- * Expresses the tool baseline as an allowlist that keeps `report_result`.
+ * The names for pi's `--tools` flag, or null when yaag emits no allowlist and
+ * pi composes the toolset itself.
+ *
+ * This is the single source of the allowlist rule: `piCommand` writes the flag
+ * from it, and `toolContract` in tool-probe.ts states its promise from it.
  *
  * `--no-tools` strips extension tools as well, and refuses a tool registered
  * afterwards, so "no tools" becomes an allowlist of exactly yaag's own tool
@@ -75,13 +85,17 @@ function appendCapabilities(
  * schema-bearing Ask activates it, so the Agent's effective capability is
  * unchanged.
  */
-function appendTools(cmd: string[], options: OpenOptions, hermetic: boolean): void {
-  if (options.tools === undefined) {
-    if (hermetic) cmd.push("--tools", REPORT_RESULT_TOOL_NAME);
-    return;
+export function toolAllowlist(options: ToolSelection): readonly string[] | null {
+  const { tools } = options;
+  if (tools === undefined) {
+    return options.inherit === true ? null : [REPORT_RESULT_TOOL_NAME];
   }
-  const allowed = [...new Set([...options.tools, REPORT_RESULT_TOOL_NAME])];
-  cmd.push("--tools", allowed.join(","));
+  return [...new Set([...tools, REPORT_RESULT_TOOL_NAME])];
+}
+
+function appendTools(cmd: string[], options: OpenOptions): void {
+  const allowed = toolAllowlist(options);
+  if (allowed !== null) cmd.push("--tools", allowed.join(","));
 }
 
 /**

package/src/system-prompt-recorder-extension.ts

@@ -0,0 +1,95 @@
+/**
+ * yaag's private system-prompt recorder, loaded into every Agent at spawn.
+ *
+ * pi assembles the system prompt per turn and never persists it in the session
+ * file, so a Peek has nothing to show (observation #1204). This extension
+ * writes the assembled prompt to a sidecar file beside the session file, and pi
+ * loads it last, so the prompt it records holds every other extension's
+ * appends. It records rather than reports, so it is no probe: it sends no frame
+ * and the Orchestrator never waits for it (ADR-0035).
+ *
+ * It is strictly best-effort and silent: an Agent without a session file, or a
+ * write that fails, records nothing. It never changes the prompt, and it emits
+ * no frame, so no Ask can settle differently because of it.
+ *
+ * Types are declared locally rather than imported from pi: this file is passed
+ * to `pi -e` as a path and must load without yaag's dependency graph. pi loads
+ * it through jiti, in Node, so it uses `node:fs/promises` and no Bun-only API.
+ */
+
+import { randomUUID } from "node:crypto";
+import { rename, unlink, writeFile } from "node:fs/promises";
+
+/** The pi event that carries the assembled prompt of one turn. */
+interface BeforeAgentStart {
+  readonly systemPrompt?: unknown;
+}
+
+/** The pi context slice this extension reads. */
+interface RecorderContext {
+  readonly sessionManager: { getSessionFile(): string | undefined };
+}
+
+/** The pi surface this extension registers on. */
+interface RecorderAPI {
+  on(
+    event: "before_agent_start",
+    handler: (event: BeforeAgentStart, context: RecorderContext) => Promise<undefined>,
+  ): void;
+}
+
+/** Extension of the sidecar that holds one Agent's latest system prompt. */
+export const SYSTEM_PROMPT_SIDECAR_SUFFIX = ".system-prompt.md";
+
+/**
+ * The sidecar path for one pi session file.
+ *
+ * The session file's `.jsonl` extension is dropped, so `<id>.jsonl` and its
+ * sidecar `<id>.system-prompt.md` sit next to each other in the session dir.
+ */
+export function systemPromptSidecarPath(sessionFile: string): string {
+  const stem = sessionFile.endsWith(".jsonl")
+    ? sessionFile.slice(0, -".jsonl".length)
+    : sessionFile;
+  return `${stem}${SYSTEM_PROMPT_SIDECAR_SUFFIX}`;
+}
+
+export default function (pi: RecorderAPI): void {
+  pi.on("before_agent_start", async (event, ctx) => {
+    await record(event, ctx);
+    // The prompt is returned unchanged: an undefined result is no edit.
+    return undefined;
+  });
+}
+
+async function record(event: BeforeAgentStart, ctx: RecorderContext): Promise<void> {
+  const prompt = event.systemPrompt;
+  if (typeof prompt !== "string") return;
+  const sessionFile = readSessionFile(ctx);
+  // An ephemeral session has nowhere to put a sidecar, and a Peek of it has no
+  // session file to read either.
+  if (sessionFile === null) return;
+  const target = systemPromptSidecarPath(sessionFile);
+  // A reader must never see half a prompt: the write lands under a temporary
+  // name and the rename publishes it in one step. The name is unique for each
+  // write, so a file left by a killed process is never mistaken for a live one.
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, prompt, "utf8");
+    await rename(temporary, target);
+  } catch {
+    // Best-effort by design: recording a prompt must never fail a turn. A pi
+    // killed between the write and the rename still leaves its temporary file
+    // behind; that window is accepted, and no reader ever opens the file.
+    await unlink(temporary).catch(() => {});
+  }
+}
+
+function readSessionFile(ctx: RecorderContext): string | null {
+  try {
+    const sessionFile = ctx.sessionManager.getSessionFile();
+    return sessionFile === undefined || sessionFile === "" ? null : sessionFile;
+  } catch {
+    return null;
+  }
+}

package/src/system-prompt-recorder.ts

@@ -0,0 +1,45 @@
+/**
+ * Where the private system-prompt recorder lives, and how a Peek reads what it
+ * wrote (ADR-0035).
+ *
+ * `piCommand` loads the extension from here, and every Peek host reads the
+ * sidecar through `readSystemPromptSidecar` here, so the writer and the readers
+ * derive the same path from one place.
+ */
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+import { systemPromptSidecarPath } from "./system-prompt-recorder-extension.ts";
+
+export { systemPromptSidecarPath };
+
+/** Filesystem sibling path of the recorder; decodes percent-escapes (e.g. spaces). */
+export function systemPromptRecorderExtensionPath(moduleUrl: string): string {
+  return fileURLToPath(new URL("./system-prompt-recorder-extension.ts", moduleUrl));
+}
+
+/** Loadable source path for the private extension that records the system prompt. */
+export const SYSTEM_PROMPT_RECORDER_EXTENSION_PATH = systemPromptRecorderExtensionPath(
+  import.meta.url,
+);
+
+/**
+ * Reads the system-prompt sidecar of one Agent, or null when there is none.
+ *
+ * Null covers every case a Peek cannot show a real prompt for: an Agent that
+ * reported no session file, a session whose first turn has not started, and a
+ * session written before yaag recorded a sidecar. A Peek then falls back to the
+ * session file. An Agent of a replayed Run has the recording's session path, so
+ * a Peek on the recording machine reads the original Agent's sidecar, exactly
+ * as it reads the original Agent's transcript.
+ */
+export async function readSystemPromptSidecar(
+  sessionFile: string | null | undefined,
+): Promise<string | null> {
+  if (sessionFile === undefined || sessionFile === null) return null;
+  try {
+    return await readFile(systemPromptSidecarPath(sessionFile), "utf8");
+  } catch {
+    return null;
+  }
+}

package/src/tool-probe.ts

@@ -1,5 +1,7 @@
 import { fileURLToPath } from "node:url";
 
+import { type ToolSelection, toolAllowlist } from "./pi-state.ts";
+import { REPORT_RESULT_TOOL_NAME } from "./report-result.ts";
 import type { Frame } from "./transport.ts";
 
 /** The private status key used only by yaag's internal pi tool probe extension. */
@@ -24,34 +26,64 @@ export interface ToolProbe {
   fail(error: Error): void;
 }
 
+/** What the spawn flags promised about the Agent's effective toolset. */
+export interface ToolContract {
+  /** Names that must be active at startup. Never holds `report_result`. */
+  readonly required: readonly string[];
+  /** The only names that may be active; null when the effective set is unpredictable. */
+  readonly allowed: readonly string[] | null;
+  /** Names that must not be active. */
+  readonly denied: readonly string[];
+}
+
+/** The spawn options that decide what the probe can verify. */
+export interface ToolContractOptions extends ToolSelection {
+  readonly disallowedTools?: readonly string[] | undefined;
+}
+
+function dedupe(names: Iterable<string>): string[] {
+  return [...new Set(names)];
+}
+
 /**
- * Returns promised tools that survive pi's final denylist composition.
+ * Returns what the spawn flags promised, or null when they promised nothing.
+ *
+ * Two promises are verifiable. A spawn that pi gets a `--tools` allowlist for
+ * promises that the allowlist holds every active name. A spawn that only denies
+ * tools promises the absence of every denied name, and nothing about the rest.
+ * An inheriting spawn without `tools` and without `disallowedTools` promises
+ * nothing, so it needs no probe.
  *
- * Null means no tool allowlist promised anything and therefore needs no probe.
+ * `report_result` is allowed but never required: report-result-extension.ts
+ * registers the tool when a schema-bearing Ask activates it, long after startup
+ * (ADR-0032), so at startup the probe reports it as inactive.
  */
-export function requestedToolNames(
-  tools: readonly string[] | undefined,
-  disallowedTools: readonly string[] | undefined = undefined,
-): readonly string[] | null {
-  if (tools === undefined || tools.length === 0) return null;
-  const denied = new Set(disallowedTools);
-  const names: string[] = [];
-  const seen = new Set<string>();
-  for (const tool of tools) {
-    if (denied.has(tool) || seen.has(tool)) continue;
-    seen.add(tool);
-    names.push(tool);
+export function toolContract(options: ToolContractOptions): ToolContract | null {
+  // pi-state.ts strips this name from `--exclude-tools`, so it is never denied.
+  const denied = dedupe(options.disallowedTools ?? []).filter(
+    (name) => name !== REPORT_RESULT_TOOL_NAME,
+  );
+  const allowlisted = toolAllowlist(options);
+  if (allowlisted === null) {
+    if (denied.length === 0) return null;
+    return { required: [], allowed: null, denied };
   }
-  return names;
+  const deniedSet = new Set(denied);
+  const allowed = allowlisted.filter((name) => !deniedSet.has(name));
+  return {
+    required: allowed.filter((name) => name !== REPORT_RESULT_TOOL_NAME),
+    allowed,
+    denied,
+  };
 }
 
-/** Creates a startup collector only when a non-empty allowlist promised tool selection. */
-export function createToolProbe(
-  tools: readonly string[] | undefined,
-  _disallowedTools: readonly string[] | undefined = undefined,
-  timeoutMs = TOOL_PROBE_TIMEOUT_MS,
-): ToolProbe | null {
-  if (tools === undefined || tools.length === 0) return null;
+/**
+ * Creates a startup collector for the probe's report.
+ *
+ * The caller creates one only when `toolContract` returned a contract to verify
+ * it against, and loads the probe extension in the same decision.
+ */
+export function createToolProbe(timeoutMs = TOOL_PROBE_TIMEOUT_MS): ToolProbe {
   let resolveResult: (names: readonly string[]) => void = () => {};
   let rejectResult: (error: Error) => void = () => {};
   let settled = false;
@@ -126,16 +158,34 @@ export function parseToolProbeFrame(frame: Frame): readonly string[] {
   return names;
 }
 
-/** Throws a diagnostic naming every missing requested tool. */
-export function verifyEffectiveTools(
-  promised: readonly string[],
-  effective: readonly string[],
-): void {
+function quoteNames(names: readonly string[]): string {
+  return names.map((name) => JSON.stringify(name)).join(", ");
+}
+
+/**
+ * Throws a diagnostic when the effective toolset breaks the promise.
+ *
+ * A missing required tool, an extra tool outside the allowlist, and a denied
+ * tool that is still active all fail the spawn the same way.
+ */
+export function verifyEffectiveTools(contract: ToolContract, effective: readonly string[]): void {
   const active = new Set(effective);
-  const missing = promised.filter((name) => !active.has(name));
-  if (missing.length === 0) return;
-  const listed = missing.map((name) => JSON.stringify(name)).join(", ");
-  throw new Error(
-    `agent is missing requested tool(s): ${listed}; declare the extension(s) providing these tools via spawn.extensions`,
-  );
+  const missing = contract.required.filter((name) => !active.has(name));
+  if (missing.length > 0) {
+    throw new Error(
+      `agent is missing requested tool(s): ${quoteNames(missing)}; declare the extension(s) providing these tools via spawn.extensions`,
+    );
+  }
+  const stillActive = contract.denied.filter((name) => active.has(name));
+  if (stillActive.length > 0) {
+    throw new Error(`agent has denied tool(s) still active: ${quoteNames(stillActive)}`);
+  }
+  if (contract.allowed === null) return;
+  const allowed = new Set(contract.allowed);
+  const extra = dedupe(effective).filter((name) => !allowed.has(name));
+  if (extra.length > 0) {
+    throw new Error(
+      `agent has unexpected active tool(s): ${quoteNames(extra)}; the spawn allowlist promised only ${quoteNames(contract.allowed)}`,
+    );
+  }
 }