@yaag/cli 0.3.0 → 0.5.0

package/assets/types/runtime/index.d.ts

@@ -28,6 +28,7 @@ export type { RunContext } from "./run-context.ts";
 export type { DiscoveredSkill, SkillProbeFactory } from "./skill-probe.ts";
 export type { AgentInfo, AgentState, AskingAgentInfo, EndedRunSummary, ExitedAgentInfo, IdleAgentInfo, NodeInfo, RunningRunSummary, RunOutcome, RunState, RunSummary, } from "./summary.ts";
 export { applyEvent, initialSummary } from "./summary.ts";
+export { readSystemPromptSidecar } from "./system-prompt-recorder.ts";
 export type { AgentStats, AgentTransport, AskMarker, AskMarkerContext, AskPlayback, Frame, TokenBreakdown, TransportFactory, TransportStartup, TransportStartupObserver, WorktreeResolution, } from "./transport.ts";
 export type { AskOptions, Handle, ResolvedSpawnOptions, SpawnOptions, SpawnOverrides, StructuredAskOptions, ThinkingLevel, } from "./types.ts";
 export { AGENT_NODE_TABLE_MAX, ASK_OUTPUT_FLUSH_INTERVAL_MS, ASK_OUTPUT_MAX_BYTES, ASK_OUTPUT_TRUNCATION_MARKER, NODE_GIST_MAX_CHARS, PROMPT_GIST_MAX_CHARS, TOOL_ARGS_GIST_MAX_CHARS, } from "./wire-constants.ts";

package/assets/types/runtime/pi-state.d.ts

@@ -10,6 +10,25 @@ export interface AgentProgress {
 }
 /** The command line for one Agent. */
 export declare function piCommand(options: OpenOptions, toolProbeExtensionPath?: string): string[];
+/** The spawn options that decide pi's `--tools` allowlist. */
+export interface ToolSelection {
+    readonly tools?: readonly string[] | undefined;
+    readonly inherit?: boolean | undefined;
+}
+/**
+ * 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
+ * (e2e/report-result-spike.test.ts). The tool stays inactive until a
+ * schema-bearing Ask activates it, so the Agent's effective capability is
+ * unchanged.
+ */
+export declare function toolAllowlist(options: ToolSelection): readonly string[] | null;
 /**
  * `provider/id` from a `get_state` response — what the Agent actually resolved
  * to, not the pattern that was requested. Null when the payload has no model.

package/assets/types/runtime/system-prompt-recorder-extension.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+/** 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 declare 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 declare function systemPromptSidecarPath(sessionFile: string): string;
+export default function (pi: RecorderAPI): void;
+export {};

package/assets/types/runtime/system-prompt-recorder.d.ts

@@ -0,0 +1,17 @@
+import { systemPromptSidecarPath } from "./system-prompt-recorder-extension.ts";
+export { systemPromptSidecarPath };
+/** Filesystem sibling path of the recorder; decodes percent-escapes (e.g. spaces). */
+export declare function systemPromptRecorderExtensionPath(moduleUrl: string): string;
+/** Loadable source path for the private extension that records the system prompt. */
+export declare const SYSTEM_PROMPT_RECORDER_EXTENSION_PATH: string;
+/**
+ * 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 declare function readSystemPromptSidecar(sessionFile: string | null | undefined): Promise<string | null>;

package/assets/types/runtime/tool-probe.d.ts

@@ -1,3 +1,4 @@
+import { type ToolSelection } from "./pi-state.ts";
 import type { Frame } from "./transport.ts";
 /** The private status key used only by yaag's internal pi tool probe extension. */
 export declare const TOOL_PROBE_STATUS_KEY = "yaag.tool-probe.v1";
@@ -14,17 +15,48 @@ export interface ToolProbe {
     /** Rejects startup when the spawned pi process ends before reporting. */
     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;
+}
 /**
- * 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 declare function requestedToolNames(tools: readonly string[] | undefined, disallowedTools?: readonly string[] | undefined): readonly string[] | null;
-/** Creates a startup collector only when a non-empty allowlist promised tool selection. */
-export declare function createToolProbe(tools: readonly string[] | undefined, _disallowedTools?: readonly string[] | undefined, timeoutMs?: number): ToolProbe | null;
+export declare function toolContract(options: ToolContractOptions): ToolContract | 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 declare function createToolProbe(timeoutMs?: number): ToolProbe;
 /** True exactly for a status frame emitted by the private probe extension. */
 export declare function isToolProbeFrame(frame: Frame): boolean;
 /** Parses the private status payload, rejecting every malformed boundary. */
 export declare function parseToolProbeFrame(frame: Frame): readonly string[];
-/** Throws a diagnostic naming every missing requested tool. */
-export declare function verifyEffectiveTools(promised: readonly string[], effective: readonly string[]): void;
+/**
+ * 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 declare function verifyEffectiveTools(contract: ToolContract, effective: readonly string[]): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public"
   },
@@ -21,8 +21,8 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/runtime": "0.3.0",
-    "@yaag/tui": "0.3.0",
+    "@yaag/runtime": "0.5.0",
+    "@yaag/tui": "0.5.0",
     "typebox": "1.3.7"
   }
 }

package/src/argv.ts

@@ -7,6 +7,7 @@ import { resolve } from "node:path";
 export const USAGE = `usage:
   yaag run <program.ts> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>]
   yaag run --eval <source> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>]
+  yaag run --eval-fd <n> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>]
   yaag describe <program.ts>
   yaag setup-workspace [dir]
 
@@ -15,8 +16,12 @@ program file or --eval, but do not give both. A program that --eval runs can
 import "@yaag/runtime" and "typebox" only. A program that imports other modules
 must be a file.
 
-A --resume or --replay Run also needs the program: give the program file, or
---eval <source>. A Cassette holds the history of a Run, and never the program
+--eval-fd reads the program source from descriptor <n>, and needs the writer to
+close that descriptor. It keeps the source out of the process argument list,
+where every local user can read it. The yaag extension always uses it.
+
+A --resume or --replay Run also needs the program: give the program file,
+--eval <source>, or --eval-fd <n>. A Cassette holds the history of a Run, and never the program
 to run.
 
 Warning: describe imports the module and executes its top level. Keep program module top level side-effect free.`;
@@ -24,7 +29,8 @@ Warning: describe imports the module and executes its top level. Keep program mo
 /** The program one `run` invocation names: a file, or source text (ADR-0033). */
 export type ProgramSource =
   | { readonly kind: "file"; readonly file: string }
-  | { readonly kind: "inline"; readonly source: string };
+  | { readonly kind: "inline"; readonly source: string }
+  | { readonly kind: "inline-fd"; readonly fd: number };
 
 export type ParsedArgv =
   | {
@@ -60,6 +66,7 @@ export function parseArgv(argv: readonly string[]): ParsedArgv {
 function parseRun(tokens: readonly string[]): ParsedArgv {
   let file: string | undefined;
   let evalSource: string | undefined;
+  let evalFd: number | undefined;
   let args: unknown = {};
   let eventsFd: number | undefined;
   let record: string | undefined;
@@ -74,6 +81,7 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
     } else if (
       token === "--args" ||
       token === "--eval" ||
+      token === "--eval-fd" ||
       token === "--events-fd" ||
       token === "--record" ||
       token === "--replay" ||
@@ -88,6 +96,10 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
         args = parsed.value;
       } else if (token === "--eval") {
         evalSource = value;
+      } else if (token === "--eval-fd") {
+        const parsed = parseEvalDescriptor(value);
+        if (!parsed.ok) return parsed;
+        evalFd = parsed.value;
       } else if (token === "--events-fd") {
         const parsed = parseDescriptor(value);
         if (!parsed.ok) return parsed;
@@ -108,9 +120,9 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
     }
   }
 
-  const clash = conflict({ file, evalSource, record, replay, resume });
+  const clash = conflict({ file, evalSource, evalFd, eventsFd, record, replay, resume });
   if (clash !== null) return failure(`${clash}\n${USAGE}`);
-  const program = programSource(file, evalSource);
+  const program = programSource(file, evalSource, evalFd);
   if (program === undefined) return missingProgram(resume, replay);
   return {
     ok: true,
@@ -128,6 +140,8 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
 interface RunFlags {
   readonly file?: string;
   readonly evalSource?: string;
+  readonly evalFd?: number;
+  readonly eventsFd?: number;
   readonly record?: string;
   readonly replay?: string;
   readonly resume?: string;
@@ -135,10 +149,19 @@ interface RunFlags {
 
 /** Names the first pair of options that cannot appear in one invocation. */
 function conflict(flags: RunFlags): string | null {
-  const { file, evalSource, record, replay, resume } = flags;
+  const { file, evalSource, evalFd, eventsFd, record, replay, resume } = flags;
   if (file !== undefined && evalSource !== undefined) {
     return "--eval and a program file cannot be used together";
   }
+  if (evalSource !== undefined && evalFd !== undefined) {
+    return "--eval and --eval-fd cannot be used together";
+  }
+  if (file !== undefined && evalFd !== undefined) {
+    return "--eval-fd and a program file cannot be used together";
+  }
+  if (evalFd !== undefined && eventsFd !== undefined && evalFd === eventsFd) {
+    return "--eval-fd and --events-fd must use different descriptors";
+  }
   if (record !== undefined && replay !== undefined) {
     return "--record and --replay cannot be used together";
   }
@@ -159,7 +182,7 @@ function missingProgram(
   if (resume === undefined && replay === undefined) return failure(USAGE);
   const flag = resume !== undefined ? "--resume" : "--replay";
   return failure(
-    `${flag} needs the program too: give <program.ts> or --eval <source>. ` +
+    `${flag} needs the program too: give <program.ts>, --eval <source>, or --eval-fd <n>. ` +
       `A cassette holds the history of a Run, and never the program to run.\n${USAGE}`,
   );
 }
@@ -167,8 +190,10 @@ function missingProgram(
 function programSource(
   file: string | undefined,
   source: string | undefined,
+  fd: number | undefined,
 ): ProgramSource | undefined {
   if (source !== undefined) return { kind: "inline", source };
+  if (fd !== undefined) return { kind: "inline-fd", fd };
   return file === undefined ? undefined : { kind: "file", file };
 }
 
@@ -202,6 +227,14 @@ function parseDescriptor(value: string): ParsedValue<number> {
     : failure(`--events-fd must be a descriptor number\n${USAGE}`);
 }
 
+/** 0, 1 and 2 are stdin, stdout and stderr, so an Inline Program needs 3 or higher. */
+function parseEvalDescriptor(value: string): ParsedValue<number> {
+  const fd = Number(value);
+  return Number.isInteger(fd) && fd >= 3
+    ? { ok: true, value: fd }
+    : failure(`--eval-fd must be a descriptor number of 3 or higher\n${USAGE}`);
+}
+
 function failure(error: string): { readonly ok: false; readonly error: string } {
   return { ok: false, error };
 }

package/src/cli-tree-host.ts

@@ -6,11 +6,9 @@
  * caller adds `stop` and `done`: nothing in this module can prompt
  * an Agent (ADR — a Peek observes, it never sends).
  */
-import { readFile, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { readFile } from "node:fs/promises";
 import type { Terminal } from "@earendil-works/pi-tui";
-import type { AgentInfo } from "@yaag/runtime";
+import { type AgentInfo, readSystemPromptSidecar } from "@yaag/runtime";
 import { cliKeybindings, type RunTreeViewHost, type TreeState } from "@yaag/tui";
 
 /** The terminal services one open CLI view holds. */
@@ -21,8 +19,6 @@ export interface CliTreeHostOptions {
   /** Shows a transient message; `tree-app.ts` routes it to the TUI. */
   notify(message: string, level: "info" | "warning" | "error"): void;
   requestRender(): void;
-  /** Where `openEditor` puts the body; defaults to the system temp directory. */
-  readonly scratchDir?: string;
 }
 
 /** The read-only capabilities the CLI Run view has. */
@@ -35,23 +31,14 @@ export function createCliTreeHost(options: CliTreeHostOptions): ReadOnlyCliHost
     keybindings: cliKeybindings(),
     agentInfo: (agent) => state.summary.agents[agent],
     readSession: (agent) => readSession(state.summary.agents[agent]),
+    readSystemPromptSidecar: (agent) =>
+      readSystemPromptSidecar(state.summary.agents[agent]?.sessionFile),
     sessionPath: (agent) => state.summary.agents[agent]?.sessionFile ?? null,
     // OSC 52 is the only copy path that works over SSH without a child
     // process, and it is what pi-tui itself uses for its own copy gesture.
     copyPath: async (text) => {
       terminal.write(`\u001b]52;c;${Buffer.from(text, "utf8").toString("base64")}\u0007`);
     },
-    // Spawning $EDITOR inside a live alt-screen would fight the TUI for the
-    // terminal, so the body lands in a file and the path is reported instead.
-    openEditor: async (title, body) => {
-      const path = join(options.scratchDir ?? tmpdir(), scratchName(title));
-      try {
-        await writeFile(path, body, "utf8");
-        options.notify(`Wrote ${title} to ${path}`, "info");
-      } catch (error) {
-        options.notify(`Could not write ${title}: ${message(error)}`, "error");
-      }
-    },
     notify: (text, level) => options.notify(text, level),
     requestRender: () => options.requestRender(),
     rows: () => Math.max(1, terminal.rows - 1),
@@ -70,12 +57,3 @@ async function readSession(info: AgentInfo | undefined): Promise<string | null>
     return null;
   }
 }
-
-function scratchName(title: string): string {
-  const slug = title.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "");
-  return `yaag-${slug === "" ? "note" : slug}.txt`;
-}
-
-function message(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}

package/src/eval-fd.ts

@@ -0,0 +1,35 @@
+/**
+ * Reads the source of an Inline Program from a file descriptor (ADR-0033).
+ *
+ * An argv element is readable by every local user through `ps` and
+ * `/proc/<pid>/cmdline`, so the source of an Inline Program travels on a
+ * descriptor instead. Descriptor 3 stays exclusive to Run Lifecycle Events
+ * (ADR-0016), so the extension writes the source to descriptor 4.
+ */
+
+/** The descriptor the extension writes an Inline Program to; fd 3 is events. */
+export const DEFAULT_EVAL_FD = 4;
+
+/**
+ * Reads the whole Inline Program source from `fd`, until end of file.
+ *
+ * The read stops when the writer closes the descriptor, so a caller that
+ * keeps the descriptor open parks the Run before the program loads.
+ *
+ * Throws an `Error` that names the descriptor when the read fails, and when
+ * the descriptor gives no source.
+ */
+export async function readEvalSource(fd: number): Promise<string> {
+  let source: string;
+  try {
+    source = await Bun.file(fd).text();
+  } catch (error) {
+    throw new Error(`--eval-fd ${fd} cannot be read: ${String(error)}`);
+  }
+  if (source === "") {
+    throw new Error(
+      `--eval-fd ${fd} gave no source; write the Orchestration Program to the descriptor and close it`,
+    );
+  }
+  return source;
+}

package/src/inline-imports.ts

@@ -35,7 +35,7 @@ export function assertClosedImports(source: string): void {
     throw new Error(
       `inline program cannot import a computed specifier ` +
         `(import call on line ${computed.line}): ` +
-        `--eval allows ${allowedText()} only, each one as a string literal`,
+        `an Inline Program allows ${allowedText()} only, each one as a string literal`,
     );
   }
   const transpiler = new Bun.Transpiler({ loader: "ts" });
@@ -43,7 +43,7 @@ export function assertClosedImports(source: string): void {
     if (ALLOWED_INLINE_IMPORTS.includes(scanned.path)) continue;
     throw new Error(
       `inline program cannot import ${JSON.stringify(scanned.path)}: ` +
-        `--eval allows ${allowedText()} only`,
+        `an Inline Program allows ${allowedText()} only`,
     );
   }
 }
@@ -61,7 +61,7 @@ export function assertClosedImports(source: string): void {
  * by exactly one.
  */
 export function inlineRequirePrelude(): string {
-  const suffix = JSON.stringify(`: --eval allows ${allowedText()} only`);
+  const suffix = JSON.stringify(`: an Inline Program allows ${allowedText()} only`);
   return [
     "const require = ((real, allowed) => (id) => {",
     " if (allowed.includes(id)) return real(id);",

package/src/run-program.ts

@@ -1,6 +1,7 @@
 /**
- * Composes the two ways `yaag run` gets its Orchestration Program: a file, or
- * the source text of an Inline Program.
+ * Composes the ways `yaag run` gets its Orchestration Program: a file, or the
+ * source of an Inline Program. That source arrives as text, or on a
+ * descriptor (ADR-0033); the loader below does not know which.
  *
  * The composition sits above both loaders, so neither loader knows the other
  * and the imports stay a DAG.
@@ -8,6 +9,7 @@
 import { resolve } from "node:path";
 import type { OrchestrationProgram } from "@yaag/runtime";
 import type { ProgramSource } from "./argv.ts";
+import { readEvalSource } from "./eval-fd.ts";
 import { loadInlineProgram } from "./inline-program.ts";
 import { loadProgram } from "./program-loader.ts";
 
@@ -25,7 +27,9 @@ export interface LoadedProgram {
  * A file path is resolved against the working directory, and its
  * `programFile` is that absolute path. An Inline Program reports no
  * `programFile`, because its temporary module is unlinked after the import; it
- * reports its source text as its identity instead.
+ * reports its source text as its identity instead. A `--eval-fd` program is
+ * read to end of file first, so a writer that never closes the descriptor
+ * parks the Run (see `eval-fd.ts`).
  * Each failure of `loadProgram` or `loadInlineProgram` — a missing file, a
  * specifier outside the closed contract, a module that is not a program —
  * passes through unchanged.
@@ -42,5 +46,13 @@ export async function loadRunProgram(source: ProgramSource): Promise<LoadedProgr
         programFile: undefined,
         programSource: source.source,
       };
+    case "inline-fd": {
+      const text = await readEvalSource(source.fd);
+      return {
+        program: await loadInlineProgram(text),
+        programFile: undefined,
+        programSource: text,
+      };
+    }
   }
 }