@yaag/extension 0.2.1 → 0.3.0

package/README.md

@@ -35,12 +35,17 @@ For a throwaway session instead: `pi -e ./packages/extension`.
 
 | Parameter | Type | Meaning |
 |---|---|---|
-| `file` | `string` | Path to the Orchestration Program file |
+| `file` | `string?` | Path to the Orchestration Program file |
+| `script` | `string?` | Orchestration Program source text (Inline Program) |
 | `args` | `string?` | The program's arguments, as a JSON object string |
 | `background` | `boolean?` | Start the Run in the background and return its Run id |
 | `record` | `string?` | Write this Run's Cassette artifact to this path |
 | `resume` | `string?` | Replay a matching Cassette prefix, then continue live |
 
+Give `file` or `script`, and not both; a violation is a parameter error raised
+before any process starts. A `script` program can import `@yaag/runtime` and
+`typebox` only (ADR-0033).
+
 Blocking by default: the call returns when the Run ends, and its content is the
 Run's return value. With `background: true` it returns at once with a short Run
 id (`r1`, `r2`, …) and the result arrives later as a follow-up message that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/extension",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public"
   },
@@ -24,9 +24,9 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/cli": "0.2.1",
-    "@yaag/runtime": "0.2.1",
-    "@yaag/tui": "0.2.1",
+    "@yaag/cli": "0.3.0",
+    "@yaag/runtime": "0.3.0",
+    "@yaag/tui": "0.3.0",
     "nanoid": "^6.0.1"
   },
   "peerDependencies": {

package/src/run-argv.ts

@@ -0,0 +1,34 @@
+/** What a Run runs: a program file, or Inline Program source text (ADR-0033). */
+export type ProgramTarget =
+  | { readonly kind: "file"; readonly file: string }
+  | { readonly kind: "inline"; readonly source: string };
+
+/** The parts of a Run the CLI argv carries. */
+export interface RunArgvOptions {
+  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). */
+  readonly record?: string;
+  /** Cassette path to resume from, forwarded as `--resume` (ADR-0014). */
+  readonly resume?: string;
+  /** The descriptor Run Lifecycle Events travel on; 3 by default (ADR-0016). */
+  readonly eventsFd?: number;
+}
+
+/**
+ * Builds the CLI argv for one Run.
+ *
+ * An Inline Program travels as one `--eval` argument holding the source text
+ * verbatim (ADR-0033); this function never quotes, escapes or validates it —
+ * the CLI owns the closed import contract.
+ */
+export function runArgv(options: RunArgvOptions): readonly string[] {
+  const { program } = options;
+  const argv = program.kind === "file" ? ["run", program.file] : ["run", "--eval", program.source];
+  argv.push("--events-fd", String(options.eventsFd ?? 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);
+  return argv;
+}

package/src/run-program-param.ts

@@ -0,0 +1,64 @@
+import { access } from "node:fs/promises";
+import { resolve } from "node:path";
+import { sanitizeTerminalLine } from "@yaag/tui";
+import type { ProgramTarget } from "./run-argv.ts";
+
+/** The `yaag_run` parameters that name the program; exactly one is given. */
+export interface ProgramParams {
+  readonly file?: string;
+  readonly script?: string;
+}
+
+const LABEL_LIMIT = 60;
+
+/**
+ * Resolves the program the caller named to a {@link ProgramTarget}.
+ *
+ * `file` and `script` are exactly-one-of (ADR-0033): a violation throws a
+ * parameter error, so the refusal happens before any process starts. A `script`
+ * touches no filesystem; the CLI writes and owns its temp module.
+ */
+export async function resolveProgramTarget(params: ProgramParams): Promise<ProgramTarget> {
+  const { file, script } = params;
+  if (file !== undefined && script !== undefined) {
+    throw new Error("yaag_run: give file or script, and not both");
+  }
+  if (script !== undefined) {
+    if (script.trim() === "") throw new Error("yaag_run: script is empty");
+    return { kind: "inline", source: script };
+  }
+  if (file === undefined) throw new Error("yaag_run: give file or script");
+  const resolved = resolve(file);
+  try {
+    await access(resolved);
+  } catch {
+    throw new Error(`yaag_run: no such Orchestration Program: ${resolved}`);
+  }
+  return { kind: "file", file: resolved };
+}
+
+/**
+ * A one-line label for the call render. Total by design: the render runs before
+ * `execute` validates, so an invalid parameter pair must still produce a label.
+ *
+ * An Inline Program shows its declared name, else its first line — never a temp
+ * path, which exists only inside the CLI.
+ */
+export function programLabel(params: ProgramParams): string {
+  const { file, script } = params;
+  if (file !== undefined && script !== undefined) return "(invalid call)";
+  if (script !== undefined) return truncate(inlineLabel(script));
+  if (file !== undefined) return file;
+  return "(invalid call)";
+}
+
+function inlineLabel(source: string): string {
+  const declared = /name:\s*["'`]([^"'`]+)/.exec(source);
+  const line = declared?.[1] ?? source.split("\n").find((one) => one.trim() !== "") ?? "";
+  return sanitizeTerminalLine(line).replace(/\s+/g, " ").trim();
+}
+
+function truncate(label: string): string {
+  if (label === "") return "(empty script)";
+  return label.length <= LABEL_LIMIT ? label : `${label.slice(0, LABEL_LIMIT)}…`;
+}

package/src/run-record.ts

@@ -18,7 +18,14 @@ export type PersistedOutcome =
 
 /** What starting a Run said about it; enough to describe it in a later session. */
 export interface RunLaunch {
-  readonly file: string;
+  /**
+   * Exactly one of `file` and `script` is present: `file` for a program file,
+   * `script` for an Inline Program (ADR-0033). The pair stays a tolerant
+   * optional pair rather than a union, because a record written by an older
+   * yaag must still narrow.
+   */
+  readonly file?: string;
+  readonly script?: string;
   readonly args?: string;
   readonly record?: string;
   readonly resume?: string;
@@ -82,7 +89,10 @@ function isState(value: unknown): value is PersistedRunState {
 
 function isLaunch(value: unknown): value is RunLaunch {
   return (
-    typeof value === "object" && value !== null && "file" in value && typeof value.file === "string"
+    typeof value === "object" &&
+    value !== null &&
+    (("file" in value && typeof value.file === "string") ||
+      ("script" in value && typeof value.script === "string"))
   );
 }
 

package/src/run-tool-test-support.ts

@@ -1,13 +1,16 @@
 import { dirname, join } from "node:path";
 import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { stripTerminalSequences } from "@earendil-works/pi-tui";
+import { initialSummary } from "@yaag/runtime";
 import type { BackgroundStatus } from "./background-status.ts";
+import { fakeTheme } from "./fake-theme.ts";
 import { resolveBun } from "./resolve-bun.ts";
 import { resolveCliEntry } from "./resolve-cli.ts";
 import type { RunDetails } from "./run-details.ts";
 import { RunRegistry } from "./run-registry.ts";
 import { createRunTool, type SendMessage } from "./run-tool.ts";
 import type { RunTreeStore } from "./run-trees.ts";
-import type { RunHandle } from "./spawn-run.ts";
+import type { RunHandle, StartRunOptions } from "./spawn-run.ts";
 import { createStopTool, type StopDetails } from "./stop-tool.ts";
 import { TestExtensionContext } from "./test-extension-context.ts";
 
@@ -19,9 +22,60 @@ const ctx = new TestExtensionContext(dirname(cli));
 export const fixture = (name: string): string => join(dirname(cli), "fixtures", `${name}.ts`);
 
 export interface RunParams {
-  readonly file: string;
+  readonly file?: string;
+  readonly script?: string;
   readonly args?: string;
   readonly background?: boolean;
+  readonly record?: string;
+  readonly resume?: string;
+}
+
+/** Renders the tool's call line, stripped of styling, as the transcript shows it. */
+export function renderCallLabel(params: RunParams): string {
+  const tool = createRunTool({
+    bun,
+    cli,
+    registry: new RunRegistry(),
+    sendMessage: () => undefined,
+  });
+  const component = tool.renderCall?.(params, fakeTheme(), {
+    args: params,
+    toolCallId: "call-1",
+    invalidate: () => {},
+    lastComponent: undefined,
+    state: undefined,
+    cwd: process.cwd(),
+    executionStarted: false,
+    argsComplete: true,
+    isPartial: false,
+    expanded: false,
+    showImages: false,
+    isError: false,
+  });
+  return stripTerminalSequences(component?.render(80)[0] ?? "");
+}
+
+/** A start seam that never spawns: it captures its options and ends the Run at once. */
+export function fakeStart(stdout = "{}"): {
+  readonly start: (options: StartRunOptions) => RunHandle;
+  readonly seen: StartRunOptions[];
+} {
+  const seen: StartRunOptions[] = [];
+  return {
+    seen,
+    start: (options) => {
+      seen.push(options);
+      return {
+        stop: () => {},
+        outcome: Promise.resolve({
+          code: 0,
+          stdout,
+          stderr: "",
+          summary: initialSummary(),
+        }),
+      };
+    },
+  };
 }
 
 export interface Sent {

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,26 @@ import { RunTreeStore } from "./run-trees.ts";
 export type { RunDetails } from "./run-details.ts";
 
 import { type ProcessIdentity, readProcessStart } from "./process-liveness.ts";
+import type { ProgramTarget } from "./run-argv.ts";
 import { mintRunId } from "./run-id.ts";
+import { programLabel, resolveProgramTarget } from "./run-program-param.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" }),
   ),
@@ -72,6 +83,17 @@ 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`. Do not give both. A call with both, or with neither,",
+  "fails before yaag starts the 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.",
+  "`args`, `background`, `record` and `resume` work the same way for `script`.",
+  "Give the same script when you resume a recorded `script` Run.",
+  "`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",
@@ -100,7 +122,8 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
       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})`),
+        theme.fg("toolTitle", theme.bold("yaag_run")) +
+          theme.fg("muted", `(${programLabel(params)})`),
       );
       return text;
     },
@@ -115,15 +138,11 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
       return tree;
     },
     async execute(_id, params, signal, onUpdate, ctx) {
+      // Parameter validation precedes the Bun check, so an exactly-one-of
+      // violation is refused identically with or without Bun (ADR-0033).
+      const program = await resolveProgramTarget(params);
       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 id = mintRunId();
       const background = params.background === true;
       const inline = inlineAvailable(ctx, background);
@@ -133,7 +152,7 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
       const run = registeredRun({
         bun,
         cli,
-        file,
+        program,
         args: params.args,
         ...cassetteOptions(params),
         id,
@@ -207,7 +226,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 +240,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,
@@ -238,7 +257,9 @@ function registeredRun(options: {
     summary: initialSummary(),
   };
   const launch = {
-    file: options.file,
+    ...(options.program.kind === "file"
+      ? { file: options.program.file }
+      : { script: options.program.source }),
     ...(options.args === undefined ? {} : { args: options.args }),
     ...(options.record === undefined ? {} : { record: options.record }),
     ...(options.resume === undefined ? {} : { resume: options.resume }),

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 that travels as `--eval` (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). */
@@ -50,10 +54,12 @@ export interface RunHandle {
  * 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 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 });
   let summary: RunSummary = initialSummary();
   let sequence = 0;