@yaag/cli 0.4.0 → 0.5.2

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.4.0",
+  "version": "0.5.2",
   "publishConfig": {
     "access": "public"
   },
@@ -21,8 +21,8 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/runtime": "0.4.0",
-    "@yaag/tui": "0.4.0",
+    "@yaag/runtime": "0.5.2",
+    "@yaag/tui": "0.5.2",
     "typebox": "1.3.7"
   }
 }

package/src/cli-tree-host.ts

@@ -8,7 +8,7 @@
  */
 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. */
@@ -31,6 +31,8 @@ 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.