@yaag/extension 0.2.1 → 0.4.0

package/src/run-tool.ts

@@ -1,4 +1,3 @@
-import { access } from "node:fs/promises";
 import { resolve } from "node:path";
 import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
@@ -13,14 +12,33 @@ import { RunTreeStore } from "./run-trees.ts";
 export type { RunDetails } from "./run-details.ts";
 
 import { type ProcessIdentity, readProcessStart } from "./process-liveness.ts";
+import { resolveProgramParams } from "./resume-source.ts";
+import type { ProgramTarget } from "./run-argv.ts";
 import { mintRunId } from "./run-id.ts";
+import {
+  confirmProgramTarget,
+  programExpansion,
+  programLabel,
+  programTarget,
+} from "./run-program-param.ts";
+import type { RunLaunch } from "./run-record.ts";
 import type { LiveRun, RunRegistry, RunSettlement } from "./run-registry.ts";
 import { errorText, failure, observedSettlement } from "./run-settlement.ts";
 import { type RunHandle, type RunOutcome, type StartRunOptions, startRun } from "./spawn-run.ts";
 import { statusReport } from "./status.ts";
 
 const parameters = Type.Object({
-  file: Type.String({ description: "Path to the Orchestration Program file" }),
+  file: Type.Optional(
+    Type.String({
+      description: "Path to the Orchestration Program file; use script instead for inline source",
+    }),
+  ),
+  script: Type.Optional(
+    Type.String({
+      description:
+        'The Orchestration Program source text; it can import "@yaag/runtime" and "typebox" only',
+    }),
+  ),
   args: Type.Optional(
     Type.String({ description: "The program's arguments, as a JSON object string" }),
   ),
@@ -33,7 +51,7 @@ const parameters = Type.Object({
   resume: Type.Optional(
     Type.String({
       description:
-        "Resume from this Cassette: matching Asks replay free, then the Run continues live",
+        "Resume from this Cassette: matching Asks replay free, then the Run continues live. For an inline Run, give resume with no file and no script, and yaag reuses the stored source",
     }),
   ),
 });
@@ -72,6 +90,22 @@ const DESCRIPTION = [
   "later message. Every Run gets an id and can be inspected with `yaag_status`;",
   "background Runs may overlap and each is stopped with `yaag_stop({ id })`.",
   "",
+  "`script` runs a program that you give as source text. It needs no file.",
+  "Give `file` or `script` to start a new Run. Do not give both. A call with",
+  "both, or a new Run with neither, fails before yaag starts the Run. A call that",
+  "gives `resume` alone is the one exception: it repeats a stored inline Run.",
+  "A `script` program has the same shape as a file program. It default-exports",
+  "`defineRun(...)`.",
+  'A `script` program can import "@yaag/runtime" and "typebox" only. Make a file',
+  "program if the program needs other modules.",
+  "A `script` program must be 65536 bytes (64 KiB) or smaller. Write a larger",
+  "program to a file and give `file`.",
+  "`args`, `background`, `record` and `resume` work the same way for `script`.",
+  "To resume an inline Run, give `resume` and give no `file` and no `script`.",
+  "yaag reads the program source from its own Run record.",
+  "Give `script` again only when you want to change the program.",
+  "`yaag_describe` reads a file only.",
+  "",
   "Set `record` to write the Run's Cassette artifact. If a recorded Run fails,",
   "pass its artifact as `resume` on the retry: Asks that already succeeded",
   "replay instantly and free, and the Run goes live where it diverges. Record",
@@ -82,9 +116,13 @@ const DESCRIPTION = [
  * The `yaag_run` tool: runs one Orchestration Program through the Bun CLI and
  * returns its value (ADR-0005).
  *
- * `execute` throws on any failure — a missing Bun, a path that is not there, a
- * Run that failed — which is how pi marks a tool result as an error. On failure
- * the message carries the tail of the CLI's own error output.
+ * `execute` throws on any failure, which is how pi marks a tool result as an
+ * error. It refuses the call before any child starts when the parameters are
+ * not one program: both `file` and `script`, a new Run with neither, a blank
+ * or oversize `script`, or a `resume` alone whose Run record holds no Inline
+ * Program source (ADR-0033). It then throws for a missing Bun, a program file
+ * that is not there, or a Run that failed. On a Run failure the message
+ * carries the tail of the CLI's own error output.
  */
 export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof parameters, RunDetails> {
   const { bun, cli, registry, sendMessage } = deps;
@@ -99,9 +137,11 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
     renderCall(params, theme, context) {
       const text =
         context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-      text.setText(
-        theme.fg("toolTitle", theme.bold("yaag_run")) + theme.fg("muted", `(${params.file})`),
-      );
+      const head =
+        theme.fg("toolTitle", theme.bold("yaag_run")) +
+        theme.fg("muted", `(${programLabel(params)})`);
+      const body = context.expanded ? programExpansion(params) : "";
+      text.setText(body === "" ? head : `${head}\n${theme.fg("muted", body)}`);
       return text;
     },
     renderResult(result, _options, _theme, context) {
@@ -115,14 +155,15 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
       return tree;
     },
     async execute(_id, params, signal, onUpdate, ctx) {
+      // Shape only, before the Bun check: an exactly-one-of violation, an empty
+      // or oversize script is refused identically with or without Bun. The file
+      // probe comes after, so a Host Session with no Bun is told to install Bun
+      // instead of being told its path is wrong (ADR-0033).
+      // A resume with no file and no script takes its source from the Run
+      // record, before the shape check, so the shape it produces is valid.
+      const target = programTarget(await resolveProgramParams(params, registry));
       if (bun === null) throw new Error(statusReport(null, cli));
-
-      const file = resolve(params.file);
-      try {
-        await access(file);
-      } catch {
-        throw new Error(`yaag_run: no such Orchestration Program: ${file}`);
-      }
+      const program = await confirmProgramTarget(target);
 
       const id = mintRunId();
       const background = params.background === true;
@@ -133,7 +174,7 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
       const run = registeredRun({
         bun,
         cli,
-        file,
+        program,
         args: params.args,
         ...cassetteOptions(params),
         id,
@@ -169,7 +210,7 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
 }
 
 /**
- * Cassette paths resolved like `file`; the CLI owns every rule about them —
+ * Cassette paths are `resolve`d here; the CLI owns every rule about them —
  * combinations, validation, refusals — and its own message surfaces on failure.
  */
 function cassetteOptions(params: { readonly record?: string; readonly resume?: string }): {
@@ -207,7 +248,7 @@ async function announce(
 function registeredRun(options: {
   readonly bun: string;
   readonly cli: string;
-  readonly file: string;
+  readonly program: ProgramTarget;
   readonly args?: string;
   readonly record?: string;
   readonly resume?: string;
@@ -221,7 +262,7 @@ function registeredRun(options: {
   const handle = options.start({
     bun: options.bun,
     cli: options.cli,
-    file: options.file,
+    program: options.program,
     args: options.args,
     record: options.record,
     resume: options.resume,
@@ -237,12 +278,15 @@ function registeredRun(options: {
     outcome: handle.outcome,
     summary: initialSummary(),
   };
-  const launch = {
-    file: options.file,
+  const context = {
     ...(options.args === undefined ? {} : { args: options.args }),
     ...(options.record === undefined ? {} : { record: options.record }),
     ...(options.resume === undefined ? {} : { resume: options.resume }),
   };
+  const launch: RunLaunch =
+    options.program.kind === "file"
+      ? { kind: "file", file: options.program.file, ...context }
+      : { kind: "inline", script: options.program.source, ...context };
   options.registry.add(run, launch, processIdentity(handle.pid));
   return run;
 }

package/src/run-tree-host.ts

@@ -13,7 +13,7 @@ import type { NamedKeybindings, RunTreeViewHost, TreeState } from "@yaag/tui";
 
 /** The pi services one open view holds. */
 export interface RunTreeHostOptions {
-  readonly ui: Pick<ExtensionUIContext, "notify" | "editor">;
+  readonly ui: Pick<ExtensionUIContext, "notify">;
   readonly tui: TUI;
   readonly keybindings: NamedKeybindings;
   /** The Run's projection; the host only reads it. */
@@ -31,10 +31,11 @@ export function createRunTreeHost(options: RunTreeHostOptions): ReadOnlyRunTreeH
     agentInfo: (agent) => state.summary.agents[agent],
     readSession: (agent) => readSession(state.summary.agents[agent]),
     sessionPath: (agent) => state.summary.agents[agent]?.sessionFile ?? null,
+    // No capability here opens a pi dialog: `ui.editor`, `select`, `input`, and
+    // `confirm` all clear the editor container, which removes the non-overlay
+    // `ctx.ui.custom()` view and stops pi's input loop (ADR-0034). Every drill
+    // layer draws itself instead.
     copyPath: (text) => copyToClipboard(text),
-    openEditor: async (title, body) => {
-      await ui.editor(title, body);
-    },
     notify: (message, level) => ui.notify(message, level),
     requestRender: () => tui.requestRender(),
     rows: () => Math.max(1, tui.terminal.rows - 1),

package/src/spawn-run.ts

@@ -1,6 +1,9 @@
 import { applyEvent, initialSummary, type LifecycleEvent, type RunSummary } from "@yaag/runtime";
 import { startCliChild } from "./cli-child.ts";
 import { readEvents } from "./event-reader.ts";
+import { type ProgramTarget, runArgv } from "./run-argv.ts";
+
+export type { ProgramTarget } from "./run-argv.ts";
 
 /** Everything one Run of the CLI produced, once the child has exited. */
 export interface RunOutcome {
@@ -15,7 +18,8 @@ export interface RunOutcome {
 export interface StartRunOptions {
   readonly bun: string;
   readonly cli: string;
-  readonly file: string;
+  /** A program file, or an Inline Program whose source travels on fd 4 as `--eval-fd` (ADR-0033). */
+  readonly program: ProgramTarget;
   /** Opaque JSON, forwarded untouched: the program validates it (ADR-0010). */
   readonly args?: string;
   /** Cassette path to write, forwarded as `--record` (ADR-0013). */
@@ -44,17 +48,26 @@ export interface RunHandle {
 
 /**
  * Starts one Orchestration Program as a child `bun` process without waiting for
- * it. Descriptor 3 remains exclusive to Run Lifecycle Events (ADR-0016).
+ * it. Descriptor 3 remains exclusive to Run Lifecycle Events out (ADR-0016),
+ * and descriptor 4 carries the Inline Program source in (ADR-0033).
  *
  * Never throws for a failed Run — the exit code and error tail are part of its
  * outcome; callers choose how that failure reaches the Host Session.
  */
 export function startRun(options: StartRunOptions): RunHandle {
-  const argv = ["run", options.file, "--events-fd", "3"];
-  if (options.args !== undefined) argv.push("--args", options.args);
-  if (options.record !== undefined) argv.push("--record", options.record);
-  if (options.resume !== undefined) argv.push("--resume", options.resume);
-  const child = startCliChild({ bun: options.bun, cli: options.cli, argv, events: true });
+  const argv = runArgv({
+    program: options.program,
+    ...(options.args === undefined ? {} : { args: options.args }),
+    ...(options.record === undefined ? {} : { record: options.record }),
+    ...(options.resume === undefined ? {} : { resume: options.resume }),
+  });
+  const child = startCliChild({
+    bun: options.bun,
+    cli: options.cli,
+    argv,
+    events: true,
+    ...(options.program.kind === "inline" ? { evalSource: options.program.source } : {}),
+  });
   let summary: RunSummary = initialSummary();
   let sequence = 0;
   const outcome = Promise.all([

package/src/status-tool.ts

@@ -2,7 +2,7 @@ import type { AgentToolResult, ToolDefinition } from "@earendil-works/pi-coding-
 import type { RunSummary } from "@yaag/runtime";
 import { renderSnapshot, TreeState } from "@yaag/tui";
 import { Type } from "typebox";
-import type { PersistedRunState } from "./run-record.ts";
+import type { RunRecord } from "./run-record.ts";
 import type { RegisteredRun, RestoredRun, RunRegistry } from "./run-registry.ts";
 import { toUsage } from "./usage.ts";
 
@@ -35,6 +35,9 @@ const DESCRIPTION = [
   "",
   "Without an id, lists this session's Runs plus every orphaned or interrupted",
   "Run left by an earlier session.",
+  "",
+  "An interrupted inline Run resumes with `resume` alone: yaag reads the program",
+  "source from its own Run record.",
 ].join("\n");
 
 /**
@@ -114,20 +117,40 @@ function restoredDetails(run: RestoredRun): SnapshotDetails {
     record.state === "orphaned" && record.process !== null
       ? ` Its process ${record.process.pid} is still running; stop it with yaag_stop.`
       : "";
-  const detail = `${alive}${resumeHint(record.state, run.summary.artifact)}`;
+  const detail = `${alive}${resumeHint(record)}`;
   const result = record.outcome?.kind === "fulfilled" ? `\n${record.outcome.result}` : "";
   return { id: record.id, summary: run.summary, result: `${state}${detail}${result}` };
 }
 
 /**
- * Names the Checkpoint an unowned Run left behind (ADR-0031). The Run
- * republishes it at each Ask boundary, so it exists whenever the Run reached
- * one, for a dead Run and for a still-running orphan alike.
+ * Names the Checkpoint an unowned Run left behind (ADR-0031), and the call that
+ * resumes it. The Run republishes the Checkpoint at each Ask boundary, so it
+ * exists whenever the Run reached one, for a dead Run and for a still-running
+ * orphan alike.
+ *
+ * The hint names the Checkpoint path and never the stored program source: the
+ * path is enough, because yaag reads the source back from the Run record
+ * (ADR-0033). A whole source here would flood the transcript and repeat a
+ * private text the record already holds.
  */
-function resumeHint(state: PersistedRunState, artifact: string | null): string {
-  if (artifact === null) return "";
-  if (state !== "interrupted" && state !== "orphaned") return "";
-  return ` Resume it from its checkpoint: ${artifact}.`;
+function resumeHint(record: RunRecord): string {
+  const artifact = record.summary.artifact;
+  if (artifact === null || artifact === undefined) return "";
+  if (record.state !== "interrupted" && record.state !== "orphaned") return "";
+  // Each path becomes a JSON string literal: a path can hold a quote, a
+  // backslash, or a newline, and the hint must stay a call the model can copy.
+  const resume = JSON.stringify(artifact);
+  const { launch } = record;
+  switch (launch.kind) {
+    case "inline":
+      return ` Resume it with yaag_run({ resume: ${resume} }) and no file and no script; yaag reuses the program source it stored.`;
+    case "file":
+      return ` Resume it with yaag_run({ file: ${JSON.stringify(launch.file)}, resume: ${resume} }).`;
+    default: {
+      const never: never = launch;
+      return never;
+    }
+  }
 }
 
 function snapshot(

package/src/test-tui-context.ts

@@ -7,12 +7,7 @@
  * covers the rpc/json path, where every `ui` access must throw.
  */
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import {
-  FakeExtensionUi,
-  type Notice,
-  type OpenedComponent,
-  type OpenedEditor,
-} from "./fake-extension-ui.ts";
+import { FakeExtensionUi, type Notice, type OpenedComponent } from "./fake-extension-ui.ts";
 
 export type { OpenedComponent } from "./fake-extension-ui.ts";
 
@@ -22,9 +17,9 @@ export interface TestTuiContextOptions {
 }
 
 /**
- * A tui context whose UI is `FakeExtensionUi`: `custom`, `notify`, and
- * `editor` work, and every other capability throws on access, so an
- * accidental dependency fails loudly.
+ * A tui context whose UI is `FakeExtensionUi`: `custom` and `notify` work, and
+ * every other capability throws on access, so an accidental dependency fails
+ * loudly. `ui.editor` throws with the rest (ADR-0034).
  */
 export class TestTuiContext implements ExtensionContext {
   readonly mode: ExtensionContext["mode"] = "tui";
@@ -53,11 +48,6 @@ export class TestTuiContext implements ExtensionContext {
     return this.ui.notices;
   }
 
-  /** Editors the view opened. */
-  get edits(): readonly OpenedEditor[] {
-    return this.ui.edits;
-  }
-
   /** The latest inline widget frame per key. */
   get widgets(): ReadonlyMap<string, string[] | undefined> {
     return this.ui.widgets;

package/src/yaag-command.ts

@@ -33,7 +33,7 @@ export interface YaagCommandOptions {
 /** Everything `/yaag` needs from its pi context, and nothing more. */
 export interface YaagContext {
   readonly mode: ExtensionContext["mode"];
-  readonly ui: Pick<ExtensionUIContext, "notify" | "select" | "custom" | "editor">;
+  readonly ui: Pick<ExtensionUIContext, "notify" | "select" | "custom">;
 }
 
 /** Builds the `/yaag` command bound to this session's registry and projections. */