@yaag/cli 0.2.1 → 0.4.0

package/assets/types/runtime/cassette-schema.d.ts

@@ -13,6 +13,7 @@ export declare const CassetteSchema: Type.TObject<{
     run: Type.TOptional<Type.TObject<{
         outcome: Type.TUnion<Type.TLiteral<"completed" | "failed" | "interrupted" | "paused" | "stopped">[]>;
         programFile: Type.TOptional<Type.TString>;
+        programSource: Type.TOptional<Type.TString>;
         args: Type.TOptional<Type.TUnknown>;
         programHash: Type.TOptional<Type.TString>;
     }>>;

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

@@ -11,8 +11,10 @@ export interface CassetteRun {
     readonly outcome: RunOutcome;
     /** Invocation identity: what a resume is about to re-execute. */
     readonly programFile?: string;
+    /** Inline Program source text; identity for a Run with no program file (ADR-0033). */
+    readonly programSource?: string;
     readonly args?: unknown;
-    /** Advisory content hash of the program file; SHA-256 hex. */
+    /** Advisory content hash of the program file, or of the inline source; SHA-256 hex. */
     readonly programHash?: string;
 }
 /** Versioned JSON artifact containing the frames exchanged during one Run. */

package/assets/types/runtime/program-hash.d.ts

@@ -0,0 +1,6 @@
+/**
+ * One advisory content hash, shared by the modules that record a program's
+ * identity and the modules that compare it (ADR-0033).
+ */
+/** Advisory content hash of a program's bytes or inline source; SHA-256 hex. */
+export declare function sha256Hex(input: string | ArrayBuffer): string;

package/assets/types/runtime/resume-identity.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The advisory comparison between a loaded Cassette's recorded program identity
+ * and the program this Run executes (ADR-0033).
+ */
+import type { Cassette } from "./cassette.ts";
+import type { ProgramIdentity } from "./run-checkpoint.ts";
+/**
+ * Warns when a Cassette's recorded program identity does not match the program
+ * this Run executes. Advisory only: the caller always supplies the program and
+ * the Cassette supplies the history, so a mismatch never stops the Run
+ * (ADR-0033). Returns null when nothing inline is involved, so file-to-file
+ * resume behaviour is unchanged.
+ */
+export declare function programIdentityWarning(cassette: Cassette, path: string, program: ProgramIdentity): string | null;

package/assets/types/runtime/run-checkpoint.d.ts

@@ -44,7 +44,13 @@ export declare function publishRunCheckpoint(options: RunCheckpointOptions): Pro
  * today's rule that its directory must already exist.
  */
 export declare function ensureCheckpointDirectory(record: string | undefined, destination: string): Promise<void>;
+/** Which program a Run executes: a file on disk, or inline source text (ADR-0033). */
+export interface ProgramIdentity {
+    readonly programFile?: string;
+    /** Inline source, exactly as the caller gave it; it excludes any loader prelude. */
+    readonly programSource?: string;
+}
 /** Resolves what a resume re-executes. The program hash is advisory only. */
-export declare function resolveRunIdentity(programFile: string | undefined, args: unknown): Promise<RunIdentity>;
+export declare function resolveRunIdentity(program: ProgramIdentity, args: unknown): Promise<RunIdentity>;
 /** Reports a secondary Cassette publication failure without displacing the Run's primary error. */
 export declare function writeRecordingDiagnostic(error: unknown): void;

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

@@ -16,6 +16,11 @@ export interface RunOptions {
      * extension declarations. This is Run context, never an Agent working directory.
      */
     readonly programFile?: string;
+    /**
+     * Inline Program source text, recorded as the Run's identity when there is no
+     * program file (ADR-0033). It never resolves extension paths.
+     */
+    readonly programSource?: string;
     /** Resolves pi's enabled skills for live restriction requests. */
     readonly skillProbe?: SkillProbeFactory;
     /** Write every public transport-seam frame once the Run settles. */

package/package.json

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

package/src/argv.ts

@@ -6,16 +6,37 @@ 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]
 
+--eval runs an Orchestration Program that you give as source text. Give a
+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.
+
+--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.`;
 
+/** 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-fd"; readonly fd: number };
+
 export type ParsedArgv =
   | {
       readonly ok: true;
       readonly command: "run";
-      readonly file: string;
+      readonly program: ProgramSource;
       /** Opaque: parsed JSON, never validated here (ADR-0010). */
       readonly args: unknown;
       readonly quiet: boolean;
@@ -44,6 +65,8 @@ 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;
@@ -57,6 +80,8 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
       quiet = true;
     } else if (
       token === "--args" ||
+      token === "--eval" ||
+      token === "--eval-fd" ||
       token === "--events-fd" ||
       token === "--record" ||
       token === "--replay" ||
@@ -69,6 +94,12 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
         const parsed = parseJson(value);
         if (!parsed.ok) return parsed;
         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;
@@ -89,20 +120,14 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
     }
   }
 
-  if (file === undefined) return failure(USAGE);
-  if (record !== undefined && replay !== undefined) {
-    return failure(`--record and --replay cannot be used together\n${USAGE}`);
-  }
-  if (resume !== undefined && replay !== undefined) {
-    return failure(`--resume and --replay cannot be used together\n${USAGE}`);
-  }
-  if (resume !== undefined && record !== undefined && resolve(resume) === resolve(record)) {
-    return failure(`--resume and --record must use different paths\n${USAGE}`);
-  }
+  const clash = conflict({ file, evalSource, evalFd, eventsFd, record, replay, resume });
+  if (clash !== null) return failure(`${clash}\n${USAGE}`);
+  const program = programSource(file, evalSource, evalFd);
+  if (program === undefined) return missingProgram(resume, replay);
   return {
     ok: true,
     command: "run",
-    file,
+    program,
     args,
     quiet,
     ...(eventsFd === undefined ? {} : { eventsFd }),
@@ -112,6 +137,66 @@ 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;
+}
+
+/** Names the first pair of options that cannot appear in one invocation. */
+function conflict(flags: RunFlags): string | null {
+  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";
+  }
+  if (resume !== undefined && replay !== undefined) {
+    return "--resume and --replay cannot be used together";
+  }
+  if (resume !== undefined && record !== undefined && resolve(resume) === resolve(record)) {
+    return "--resume and --record must use different paths";
+  }
+  return null;
+}
+
+/** A Cassette is history, never an execution source, so the caller gives the program (ADR-0033). */
+function missingProgram(
+  resume: string | undefined,
+  replay: string | undefined,
+): { readonly ok: false; readonly error: string } {
+  if (resume === undefined && replay === undefined) return failure(USAGE);
+  const flag = resume !== undefined ? "--resume" : "--replay";
+  return failure(
+    `${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}`,
+  );
+}
+
+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 };
+}
+
 function parseDescribe(tokens: readonly string[]): ParsedArgv {
   if (tokens.length !== 1 || tokens[0]?.startsWith("-")) return failure(USAGE);
   return { ok: true, command: "describe", file: tokens[0] };
@@ -142,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,9 +6,7 @@
  * 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 { cliKeybindings, type RunTreeViewHost, type TreeState } from "@yaag/tui";
@@ -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. */
@@ -41,17 +37,6 @@ export function createCliTreeHost(options: CliTreeHostOptions): ReadOnlyCliHost
     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 +55,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/cli.ts

@@ -3,7 +3,6 @@ import { resolve } from "node:path";
 import {
   assertReplayable,
   executeRun,
-  isOrchestrationProgram,
   isYaagError,
   loadCassette,
   type OrchestrationProgram,
@@ -15,7 +14,9 @@ import { parseArgv } from "./argv.ts";
 import { runInteractive } from "./interactive-run.ts";
 import { writeChannel, writeChannelFd } from "./output-channel.ts";
 import { createPlainPresenter } from "./presenter.ts";
+import { loadProgram } from "./program-loader.ts";
 import { executeOptions, formatResult, type RunFlags } from "./run-invocation.ts";
+import { loadRunProgram } from "./run-program.ts";
 import { registerRuntimeAlias } from "./runtime-alias.ts";
 import { setupWorkspace } from "./setup-workspace.ts";
 
@@ -42,11 +43,11 @@ export async function main(argv: readonly string[]): Promise<number> {
     if (parsed.command === "run" && parsed.resume !== undefined) {
       await loadCassette(parsed.resume);
     }
-    const programFile = resolve(parsed.file);
-    const program = await loadProgram(programFile);
-    if (parsed.command === "describe") return describe(program);
+    if (parsed.command === "describe") return describe(await loadProgram(resolve(parsed.file)));
+    const { program, programFile, programSource } = await loadRunProgram(parsed.program);
     return await run(program, {
       programFile,
+      programSource,
       args: parsed.args,
       eventsFd: parsed.eventsFd,
       record: parsed.record,
@@ -142,19 +143,6 @@ function eventSink(fd: number | undefined, present: StampedEventSink): StampedEv
   };
 }
 
-/** The program is the module's default export, and nothing else will do. */
-async function loadProgram(path: string): Promise<OrchestrationProgram> {
-  const module: unknown = await import(path);
-  const program =
-    typeof module === "object" && module !== null && "default" in module
-      ? module.default
-      : undefined;
-  if (!isOrchestrationProgram(program)) {
-    throw new Error(`${path}: export defineRun({ run }) as the default export`);
-  }
-  return program;
-}
-
 if (import.meta.main) {
   const code = await main(process.argv.slice(2));
   // Exit rather than wait for the loop to drain: a stopped Run may leave the

package/src/computed-imports.ts

@@ -0,0 +1,101 @@
+/**
+ * Finds a dynamic `import(...)` whose specifier is not one plain string
+ * literal.
+ *
+ * The specifier of such a call only exists while the program runs, so a scan
+ * of the literal specifiers cannot see it, and Bun resolves a built-in module
+ * and an absolute path without asking a resolver plugin. The call is refused
+ * as syntax, before the source becomes a module (ADR-0033). The `require`
+ * binding needs no scan here: `inline-program.ts` replaces it when the module
+ * loads, so every `require` call is checked when it runs.
+ *
+ * The scan reads the raw text and does not tokenize. `import` is a reserved
+ * word: real code cannot write it with escape sequences, cannot split it, and
+ * cannot put an identifier character or a `.` directly before a dynamic
+ * import. So each dynamic import in real code is an occurrence of the word
+ * `import` in the raw text, and a check of every occurrence misses none — no
+ * reading of a comment, string, or regular expression can hide one. The cost
+ * is the reverse case: text that only looks like a computed dynamic import,
+ * for example in a prompt string, is also refused. That refusal is safe, and
+ * the caller fixes it by making the program a file.
+ */
+
+/** One `import(...)` shape whose specifier is not one plain string literal. */
+export interface ComputedImport {
+  /** 1-based line of the `import` word in the scanned source. */
+  readonly line: number;
+}
+
+/** Returns the first computed dynamic `import(...)` shape, or `undefined`. */
+export function findComputedImport(source: string): ComputedImport | undefined {
+  for (let from = 0; ; ) {
+    const at = source.indexOf("import", from);
+    if (at === -1) return undefined;
+    from = at + "import".length;
+    if (isWordChar(source[at - 1]) || source[at - 1] === "." || isWordChar(source[from])) continue;
+    const open = skipTrivia(source, from);
+    if (source[open] !== "(") continue;
+    if (!takesOneStringLiteral(source, open + 1)) return { line: lineAt(source, at) };
+  }
+}
+
+/**
+ * True when the argument list that starts at `from` opens with one plain
+ * string literal, followed by `)` or by a `,` and more arguments.
+ *
+ * When the occurrence is real code, the trivia around the literal is real
+ * trivia, so this reads exactly what Bun reads. When the occurrence is inert
+ * text, a wrong reading can only refuse a harmless program.
+ */
+function takesOneStringLiteral(source: string, from: number): boolean {
+  const start = skipTrivia(source, from);
+  const quote = source[start];
+  if (quote !== '"' && quote !== "'") return false;
+  const end = endOfQuoted(source, start);
+  if (end === undefined) return false;
+  const next = source[skipTrivia(source, end)];
+  return next === ")" || next === ",";
+}
+
+/** True for a character that can continue an identifier. */
+function isWordChar(char: string | undefined): boolean {
+  return char !== undefined && /[\w$]/.test(char);
+}
+
+/** The index after the whitespace and comments that start at `index`. */
+function skipTrivia(source: string, index: number): number {
+  let cursor = index;
+  for (;;) {
+    while (/\s/.test(source[cursor] ?? "")) cursor += 1;
+    if (source[cursor] === "/" && source[cursor + 1] === "/") {
+      const line = source.indexOf("\n", cursor);
+      cursor = line === -1 ? source.length : line + 1;
+    } else if (source[cursor] === "/" && source[cursor + 1] === "*") {
+      const end = source.indexOf("*/", cursor + 2);
+      cursor = end === -1 ? source.length : end + 2;
+    } else {
+      return cursor;
+    }
+  }
+}
+
+/** The index after a `'` or `"` string, or `undefined` when the line ends first. */
+function endOfQuoted(source: string, start: number): number | undefined {
+  const quote = source[start];
+  for (let index = start + 1; index < source.length; index += 1) {
+    const char = source[index];
+    if (char === "\\") {
+      index += 1;
+      continue;
+    }
+    if (char === "\n") return undefined;
+    if (char === quote) return index + 1;
+  }
+  return undefined;
+}
+
+function lineAt(source: string, index: number): number {
+  let line = 1;
+  for (let cursor = 0; cursor < index; cursor += 1) if (source[cursor] === "\n") line += 1;
+  return line;
+}

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

@@ -0,0 +1,76 @@
+/**
+ * The closed import contract of an Inline Program (ADR-0033).
+ *
+ * An Inline Program can import `@yaag/runtime` and `typebox` only. Placement
+ * in `os.tmpdir()` stops relative and project-package resolution, but it stops
+ * neither a built-in module such as `node:fs` nor an absolute path, and
+ * removal of the module file stops neither one either. Three checks close the
+ * contract. Before the source becomes a module: each literal specifier that
+ * Bun's parser reports must be allowed, and a dynamic `import(...)` whose
+ * specifier is not one plain string literal is refused as syntax. While the
+ * module runs: `inlineRequirePrelude` replaces the `require` binding and
+ * `import.meta.require`, so every `require` call — direct, aliased, or
+ * computed — is checked with its real specifier when it runs.
+ */
+import { findComputedImport } from "./computed-imports.ts";
+
+/** The only specifiers an Inline Program can import. */
+export const ALLOWED_INLINE_IMPORTS: readonly string[] = ["@yaag/runtime", "typebox"];
+
+/**
+ * Rejects an Inline Program that imports outside the closed contract.
+ *
+ * Refuses a dynamic `import(...)` whose specifier is not one plain string
+ * literal, then reads each literal specifier — static import, export-from,
+ * `require` call, and dynamic `import()` — and refuses one that is not
+ * allowed. Throws `Error` on the first refusal, and on source text that does
+ * not parse. The refusal happens before the source becomes a module, so no
+ * disallowed module is loaded. A `require` call that computes its specifier
+ * passes this check; `inlineRequirePrelude` refuses it when it runs, before
+ * any module resolves.
+ */
+export function assertClosedImports(source: string): void {
+  const computed = findComputedImport(source);
+  if (computed !== undefined) {
+    throw new Error(
+      `inline program cannot import a computed specifier ` +
+        `(import call on line ${computed.line}): ` +
+        `an Inline Program allows ${allowedText()} only, each one as a string literal`,
+    );
+  }
+  const transpiler = new Bun.Transpiler({ loader: "ts" });
+  for (const scanned of transpiler.scanImports(source)) {
+    if (ALLOWED_INLINE_IMPORTS.includes(scanned.path)) continue;
+    throw new Error(
+      `inline program cannot import ${JSON.stringify(scanned.path)}: ` +
+        `an Inline Program allows ${allowedText()} only`,
+    );
+  }
+}
+
+/**
+ * One line of code that `inline-program.ts` puts before an Inline Program.
+ *
+ * The line shadows the module-scope `require` binding with a wrapper that
+ * refuses every specifier outside `ALLOWED_INLINE_IMPORTS`, and puts the same
+ * wrapper on `import.meta.require`. Every `require` call — direct, aliased,
+ * stored in a variable, written with identifier escape sequences, or reached
+ * through `import.meta` — runs the wrapper, so this check does not depend on
+ * a reading of the source. An allowed specifier goes to the real `require`
+ * unchanged. The line holds no line break, so it moves each source line down
+ * by exactly one.
+ */
+export function inlineRequirePrelude(): string {
+  const suffix = JSON.stringify(`: an Inline Program allows ${allowedText()} only`);
+  return [
+    "const require = ((real, allowed) => (id) => {",
+    " if (allowed.includes(id)) return real(id);",
+    ` throw new Error("inline program cannot require " + JSON.stringify(id) + ${suffix});`,
+    ` })(import.meta.require, ${JSON.stringify(ALLOWED_INLINE_IMPORTS)});`,
+    " import.meta.require = require;",
+  ].join("");
+}
+
+function allowedText(): string {
+  return ALLOWED_INLINE_IMPORTS.map((name) => JSON.stringify(name)).join(" and ");
+}

package/src/inline-program.ts

@@ -0,0 +1,49 @@
+/**
+ * Loads an Inline Program: source text that a caller gives instead of a file.
+ *
+ * The source goes to a temporary `.ts` file in `os.tmpdir()`, through the same
+ * loader a file program uses, and the file is unlinked whether the import
+ * succeeds or throws. A real file gives real module resolution and real stack
+ * traces. The import contract is closed (ADR-0033): before the source becomes
+ * a module, `inline-imports.ts` rejects each literal specifier other than
+ * `@yaag/runtime` and `typebox` and each computed `import(...)`; while the
+ * module runs, a one-line prelude before the source checks every `require`
+ * call with its real specifier.
+ */
+import { randomUUID } from "node:crypto";
+import { unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { OrchestrationProgram } from "@yaag/runtime";
+import { assertClosedImports, inlineRequirePrelude } from "./inline-imports.ts";
+import { loadProgram } from "./program-loader.ts";
+
+/**
+ * Writes the source to a temporary module, imports it, and removes the file.
+ *
+ * Throws `Error` when the source imports outside the closed contract, and
+ * whatever `writeFile` throws when `os.tmpdir()` cannot take the file. Each
+ * import and validation failure of `loadProgram` passes through unchanged, so
+ * the guidance is the guidance a bad file gives. The temporary file is
+ * unlinked on each path, and a failed unlink never replaces the primary error.
+ * Removal of the file does not keep a running program from resolving a
+ * built-in module or an absolute path, so the contract is enforced by the
+ * check on the source and by the `require` prelude, not by the removal. The
+ * prelude is one line before the source, so each stack line the module
+ * reports is one below the line the caller wrote; a source that declares its
+ * own top-level `require` binding fails to load.
+ */
+export async function loadInlineProgram(source: string): Promise<OrchestrationProgram> {
+  assertClosedImports(source);
+  // A unique name per Run keeps Bun's module cache from aliasing two different
+  // Inline Programs when `main()` runs more than one time in one process.
+  const path = join(tmpdir(), `yaag-inline-${randomUUID()}.ts`);
+  await writeFile(path, `${inlineRequirePrelude()}\n${source}`, { mode: 0o600 });
+  try {
+    return await loadProgram(path);
+  } finally {
+    // The program's own error is the primary diagnostic, so a failed unlink
+    // must not replace it.
+    await unlink(path).catch(() => {});
+  }
+}

package/src/program-loader.ts

@@ -0,0 +1,28 @@
+/**
+ * Loads an Orchestration Program module from a file.
+ *
+ * One loader keeps a file program and an Inline Program on identical guidance
+ * when a module is not a program.
+ */
+import { isOrchestrationProgram, type OrchestrationProgram } from "@yaag/runtime";
+
+/**
+ * Imports `path` and returns its default export as an Orchestration Program.
+ *
+ * The program is the module's default export, and nothing else will do.
+ * Throws what Bun throws when the module is missing, does not parse, resolves
+ * no import, or throws at its top level. Throws `Error` with the guidance
+ * `export defineRun({ run }) as the default export` when the module imports
+ * but its default export is not an Orchestration Program.
+ */
+export async function loadProgram(path: string): Promise<OrchestrationProgram> {
+  const module: unknown = await import(path);
+  const program =
+    typeof module === "object" && module !== null && "default" in module
+      ? module.default
+      : undefined;
+  if (!isOrchestrationProgram(program)) {
+    throw new Error(`${path}: export defineRun({ run }) as the default export`);
+  }
+  return program;
+}

package/src/run-invocation.ts

@@ -9,7 +9,10 @@ import type { RunOptions, StampedEventSink } from "@yaag/runtime";
 
 /** Everything `yaag run` parsed for one Run. */
 export interface RunFlags {
-  readonly programFile: string;
+  /** Absent for an Inline Program, which has no file to record (ADR-0033). */
+  readonly programFile: string | undefined;
+  /** Present only for an Inline Program; becomes the Run's recorded identity (ADR-0033). */
+  readonly programSource: string | undefined;
   readonly args: unknown;
   readonly eventsFd: number | undefined;
   readonly record: string | undefined;
@@ -27,7 +30,8 @@ export function executeOptions(
   return {
     events,
     args: flags.args,
-    programFile: flags.programFile,
+    ...(flags.programFile === undefined ? {} : { programFile: flags.programFile }),
+    ...(flags.programSource === undefined ? {} : { programSource: flags.programSource }),
     ...(flags.record === undefined ? {} : { record: flags.record }),
     ...(flags.replay === undefined ? {} : { replay: flags.replay }),
     ...(flags.resume === undefined ? {} : { resume: flags.resume }),

package/src/run-program.ts

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+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";
+
+/** What one Run loaded. An Inline Program has no program file (ADR-0033). */
+export interface LoadedProgram {
+  readonly program: OrchestrationProgram;
+  readonly programFile: string | undefined;
+  /** Present only for an Inline Program: its source is the Run's identity (ADR-0033). */
+  readonly programSource: string | undefined;
+}
+
+/**
+ * Loads the program a `run` invocation names, from a file or from source text.
+ *
+ * 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. 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.
+ */
+export async function loadRunProgram(source: ProgramSource): Promise<LoadedProgram> {
+  switch (source.kind) {
+    case "file": {
+      const programFile = resolve(source.file);
+      return { program: await loadProgram(programFile), programFile, programSource: undefined };
+    }
+    case "inline":
+      return {
+        program: await loadInlineProgram(source.source),
+        programFile: undefined,
+        programSource: source.source,
+      };
+    case "inline-fd": {
+      const text = await readEvalSource(source.fd);
+      return {
+        program: await loadInlineProgram(text),
+        programFile: undefined,
+        programSource: text,
+      };
+    }
+  }
+}