omkit 0.4.8 → 0.8.1

package/dist/client/registry.d.ts

@@ -1,3 +1,10 @@
+import type { JsonSchema } from "../core/schema-json.ts";
+/** One step in an om's static outline: an imported call, with the tag authored on its chain. */
+export interface OmCall {
+    readonly name: string;
+    /** The `.tag("…")` literal from the same fluent chain, when the author wrote one. */
+    readonly tag?: string;
+}
 /** A runnable om discovered from a top-level `om("name", …)` call. */
 export interface DiscoveredOm {
     /** The om's name — its first string argument. */
@@ -6,6 +13,12 @@ export interface DiscoveredOm {
     readonly file: string;
     /** 1-based line of the `om(...)` call (informational). */
     readonly line: number;
+    /**
+     * A static approximation of what the body calls, in source order. Absent when the walk
+     * found nothing recognisable. Never a contract — see {@link import("./outline.ts").outlineBody}
+     * for what it deliberately cannot see.
+     */
+    readonly calls?: readonly OmCall[];
 }
 /** An inspectable action discovered from an exported `action("name")…` builder. */
 export interface DiscoveredAction {
@@ -27,3 +40,49 @@ export interface Registry {
     /** Non-fatal diagnostics (type errors, unresolved config) — discovery never throws for these. */
     readonly warnings: string[];
 }
+/**
+ * What importing a file in discovery mode reveals — the metadata the AST scan cannot see,
+ * because `.describe()`, `.args()` and `.mcp()` only have values once the module has been
+ * evaluated. Produced by `discoverRegistrations`, never by `discover`.
+ */
+export interface Registration {
+    readonly name: string;
+    /** Absolute path of the defining file. */
+    readonly file: string;
+    /** The `.describe({ summary })` line, when the author wrote one. */
+    readonly summary?: string;
+    /** Present only when the author called `.mcp()`. Absent ⇒ not exposed over MCP. */
+    readonly mcp?: {
+        readonly mode: "settling" | "long-lived";
+    };
+    /** The declared args as JSON Schema. Absent when none were declared. */
+    readonly inputSchema?: JsonSchema;
+    /** Why this entry cannot be called — currently only "its schema would not convert". */
+    readonly unavailable?: string;
+}
+export interface OmRegistration extends Registration {
+    /**
+     * `<name>-<hash8>` — the run's log folder, derived from the name and the defining file
+     * by the same rule the runtime uses, so it is known before the om has ever run.
+     */
+    readonly folderName: string;
+}
+export interface ActionRegistration extends Registration {
+    /** The exported binding (`export const <exportName> = action(...)`). */
+    readonly exportName: string;
+}
+/** The result of importing a project's candidate files in discovery mode. */
+export interface RegistrationSet {
+    readonly oms: OmRegistration[];
+    readonly actions: ActionRegistration[];
+    /** Import failures and AST warnings — registration discovery never throws for these. */
+    readonly warnings: string[];
+    /**
+     * The AST scan that chose the candidate files, carried through so a caller wanting both
+     * halves — the outline and capability flags from the AST, the summaries and schemas from
+     * the fork — does not pay to build a second TypeScript program.
+     *
+     * Absent when the fork was driven with an explicit file list, since there was no scan.
+     */
+    readonly registry?: Registry;
+}

package/dist/client/runner.d.ts

@@ -1,4 +1,10 @@
 import type { RunSession, RunOptions, InspectOptions } from "./types.ts";
+/**
+ * The `tsx` loader, resolved to an absolute URL from omkit's own location. Resolving it here
+ * (not as the bare specifier `--import tsx`) keeps the child's `tsx` independent of its cwd —
+ * a run in any directory still finds the loader shipped with omkit.
+ */
+export declare const tsxLoader: string;
 /**
  * The inspector flag to prepend to a child's `execArgv` — empty when no inspector is requested.
  * Plain `--inspect` opens the port without stopping, so the child still installs its teardown
@@ -10,6 +16,12 @@ export declare function inspectArgs(inspect: InspectOptions | undefined): string
  * `OMKIT_SUPERVISED=1` flips the child into channel mode (see core/interaction.ts), and its
  * IPC channel is wrapped into a {@link RunSession}. stdout/stderr are piped (not inherited)
  * so the child never writes to the supervisor's terminal.
+ *
+ * The path is canonicalised first, and that is load-bearing rather than tidy — see
+ * {@link canonicalPath}. The child resolves `"omkit"` through `node_modules`, which is a
+ * symlink Node realpaths to the package's true on-disk name; forking with any other spelling
+ * of the same file gives the child a *second* copy of omkit, with its own module state. The
+ * run then exists in one copy while the om's actions look for it in the other.
  */
 export declare function runOm(omFile: string, opts?: RunOptions): RunSession;
 /**

package/dist/client/runner.js

@@ -1,12 +1,13 @@
 import { fork } from "node:child_process";
 import path from "node:path";
+import { canonicalPath } from "../foundation/canonicalPath.js";
 import { createChannel } from "./channel.js";
 /**
  * The `tsx` loader, resolved to an absolute URL from omkit's own location. Resolving it here
  * (not as the bare specifier `--import tsx`) keeps the child's `tsx` independent of its cwd —
  * a run in any directory still finds the loader shipped with omkit.
  */
-const tsxLoader = import.meta.resolve("tsx");
+export const tsxLoader = import.meta.resolve("tsx");
 /**
  * The inspector flag to prepend to a child's `execArgv` — empty when no inspector is requested.
  * Plain `--inspect` opens the port without stopping, so the child still installs its teardown
@@ -22,12 +23,19 @@ export function inspectArgs(inspect) {
  * `OMKIT_SUPERVISED=1` flips the child into channel mode (see core/interaction.ts), and its
  * IPC channel is wrapped into a {@link RunSession}. stdout/stderr are piped (not inherited)
  * so the child never writes to the supervisor's terminal.
+ *
+ * The path is canonicalised first, and that is load-bearing rather than tidy — see
+ * {@link canonicalPath}. The child resolves `"omkit"` through `node_modules`, which is a
+ * symlink Node realpaths to the package's true on-disk name; forking with any other spelling
+ * of the same file gives the child a *second* copy of omkit, with its own module state. The
+ * run then exists in one copy while the om's actions look for it in the other.
  */
 export function runOm(omFile, opts = {}) {
-    const child = fork(omFile, [], {
+    const file = canonicalPath(omFile);
+    const child = fork(file, [], {
         execArgv: [...inspectArgs(opts.inspect), "--import", tsxLoader],
-        cwd: opts.cwd ?? path.dirname(omFile),
-        env: { ...process.env, OMKIT_SUPERVISED: "1" },
+        cwd: opts.cwd ?? path.dirname(file),
+        env: { ...process.env, OMKIT_SUPERVISED: "1", ...opts.env },
         stdio: ["ignore", "pipe", "pipe", "ipc"],
     });
     const transport = {
@@ -57,11 +65,12 @@ export function runOm(omFile, opts = {}) {
 export function spawnBare(omFile, opts = {}) {
     // A bare run is unsupervised even if the parent process happens to carry the flag (e.g. a
     // test runner spawned from inside a supervised run) — clear it so the child stays bare.
-    const env = { ...process.env };
+    const env = { ...process.env, ...opts.env };
     delete env.OMKIT_SUPERVISED;
-    const child = fork(omFile, [], {
+    const file = canonicalPath(omFile);
+    const child = fork(file, [], {
         execArgv: [...inspectArgs(opts.inspect), "--import", tsxLoader],
-        cwd: opts.cwd ?? path.dirname(omFile),
+        cwd: opts.cwd ?? path.dirname(file),
         stdio: "inherit",
         env,
     });

package/dist/client/types.d.ts

@@ -1,6 +1,11 @@
 import type { LogEntry } from "../foundation/LogEntry.ts";
 import type { PromptSpec } from "../core/interaction.ts";
-import type { Registry } from "./registry.ts";
+import type { Registry, RegistrationSet } from "./registry.ts";
+/**
+ * The config file omkit looks for when nobody names one — resolved against the working
+ * directory, which is why anything generated for a reader elsewhere has to say so explicitly.
+ */
+export declare const DEFAULT_TSCONFIG = "tsconfig.omkit.json";
 /** A run's terminal verdict, resolved when the child settles. */
 export interface Verdict {
     readonly ok: boolean;
@@ -27,6 +32,8 @@ export interface RunOptions {
     readonly cwd?: string;
     /** When set, fork the child with the Node inspector open so a debugger can attach. */
     readonly inspect?: InspectOptions;
+    /** Extra environment for the child, merged over the parent's — how `OMKIT_ARGS` travels. */
+    readonly env?: Record<string, string>;
 }
 /** A prompt the running om is waiting on — surfaced to the frontend, answered via `answer`. */
 export interface PromptRequest {
@@ -57,6 +64,12 @@ export interface OmkitClient {
     readonly tsconfig: string;
     /** Statically scan the project's `tsconfig.omkit.json` for oms and actions. */
     discover(): Promise<Registry>;
+    /**
+     * Read what the project's oms and actions declare, by importing them in a throwaway
+     * child. Unlike {@link OmkitClient.discover} this executes user code, so it is never on
+     * the `omkit ls` path — only a caller that needs real schemas should ask for it.
+     */
+    discoverRegistrations(): Promise<RegistrationSet>;
     /** Spawn an om file as a supervised child and return its live session (the Ink UI drives this). */
     run(omFile: string, opts?: RunOptions): RunSession;
     /** Spawn an om file bare — inherited stdio, no supervision — and resolve its exit code. */

package/dist/client/types.js

@@ -1 +1,5 @@
-export {};
+/**
+ * The config file omkit looks for when nobody names one — resolved against the working
+ * directory, which is why anything generated for a reader elsewhere has to say so explicitly.
+ */
+export const DEFAULT_TSCONFIG = "tsconfig.omkit.json";

package/dist/core/ActionRun.d.ts

@@ -2,6 +2,7 @@ import { type EventHandler } from "../foundation/events.ts";
 import type { ActionRef } from "../foundation/ActionRef.ts";
 import type { LogStore } from "../output/log/LogStore.ts";
 import type { SnapshotStore } from "../output/snapshot/SnapshotStore.ts";
+import type { ArtifactStore } from "../output/artifact/ArtifactStore.ts";
 import type { Activity, Exec, InstanceEvents, NodeStatus } from "./types.ts";
 /** Everything a node needs to exist, minus its behavior. */
 export interface NodeInit {
@@ -19,6 +20,8 @@ export interface NodeInit {
     readonly parentSignal: AbortSignal | null;
     /** The run's snapshot store — backs `ctx.snapshot`. */
     readonly snapshots: SnapshotStore;
+    /** The run's artifact registry — backs `ctx.artifact`. */
+    readonly artifacts: ArtifactStore;
     /** Absolute path to the run's output folder — backs `ctx.artifactsFolder`. */
     readonly artifactsFolder: string;
     /** Report an assertion outcome to the run verdict. */
@@ -54,6 +57,7 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
     duration: number;
     private readonly store;
     private readonly snapshots;
+    private readonly artifacts;
     private readonly artifactsFolder;
     private readonly onAssert;
     private readonly onUnhandledFailure;
@@ -101,6 +105,7 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
     private context;
     private assertInvariant;
     private captureSnapshot;
+    private registerArtifact;
     private attach;
     private succeed;
     private fail;

package/dist/core/ActionRun.js

@@ -30,6 +30,7 @@ export class ActionRun {
     duration = 0;
     store;
     snapshots;
+    artifacts;
     artifactsFolder;
     onAssert;
     onUnhandledFailure;
@@ -59,6 +60,7 @@ export class ActionRun {
         this.parentId = init.parentId;
         this.store = init.store;
         this.snapshots = init.snapshots;
+        this.artifacts = init.artifacts;
         this.artifactsFolder = init.artifactsFolder;
         this.onAssert = init.onAssert;
         this.onUnhandledFailure = init.onUnhandledFailure;
@@ -228,6 +230,7 @@ export class ActionRun {
             tag: (name) => void this.tag(name),
             assert: (condition, message) => this.assertInvariant(condition, message),
             snapshot: (name, value) => this.captureSnapshot(name, value),
+            artifact: (name, file, opts) => this.registerArtifact(name, file, opts),
             artifactsFolder: this.artifactsFolder,
             proc: createProc((source, level, message) => this.store.append({ nodeId: this.id, path: this.path, level, source, message }), this.signal),
         };
@@ -244,6 +247,12 @@ export class ActionRun {
         this.bubble(`📸 ${name} → ${file}`);
         return file;
     }
+    registerArtifact(name, file, opts) {
+        const record = this.artifacts.register(name, file, this.id, opts);
+        this.log("artifact", "artifact", `${name} → ${record.file}`);
+        this.bubble(`📎 ${name} → ${record.file}`);
+        return record.file;
+    }
     attach(handle) {
         if (this.attached)
             return;

package/dist/core/ExecutionTree.d.ts

@@ -1,8 +1,10 @@
 import { LogStore } from "../output/log/LogStore.ts";
 import { RunFolder } from "../output/folder/RunFolder.ts";
+import { type ArtifactRecord } from "../output/artifact/ArtifactStore.ts";
 import type { RunView } from "../output/writers/views.ts";
 import { ActionRun } from "./ActionRun.ts";
-import type { Exec, LaunchSpec } from "./types.ts";
+import type { Exec, LaunchSpec, OmDescription, ResolvedMcpExposure } from "./types.ts";
+import type { LogEntry } from "../foundation/LogEntry.ts";
 /**
  * The run: a module singleton that owns the log store, the run folder, the node
  * registry, and the process-wide teardown. `launch` creates a child node under the
@@ -20,9 +22,22 @@ export declare class ExecutionTree {
     readonly store: LogStore;
     readonly folder: RunFolder;
     readonly root: ActionRun;
+    /**
+     * The om's `.describe(…)` summary, carried here from the builder so it survives the
+     * terminal `.run(...)` call. Stored so it is retrievable; nothing reads it yet.
+     */
+    readonly description: OmDescription | undefined;
+    /**
+     * The om's `.mcp(…)` exposure, carried here from the builder for the same reason
+     * `description` is: `.run(...)` is the terminal call, and an om has no definition object
+     * to hang it on. The MCP server reads its own copy from the discovery fork, not from
+     * here — this is what makes the carry observable, and therefore testable, at all.
+     */
+    readonly mcp: ResolvedMcpExposure | undefined;
     private readonly rawStream;
     private readonly consoleCapture;
     private readonly snapshotStore;
+    private readonly artifactStore;
     private readonly registry;
     private readonly unsettled;
     private readonly originalLog;
@@ -31,6 +46,7 @@ export declare class ExecutionTree {
     private forwarding;
     private assertionsPassed;
     private assertionsFailed;
+    private rootArgs;
     private readonly faults;
     static graceMs: number;
     private phase;
@@ -40,7 +56,9 @@ export declare class ExecutionTree {
     private readonly onSigint;
     private readonly onUncaught;
     private readonly onUnhandled;
-    constructor(name: string, definedAt?: string);
+    constructor(name: string, definedAt?: string, description?: OmDescription, mcp?: ResolvedMcpExposure);
+    /** Record the run's resolved args, so the root's log header reports them. */
+    setRootArgs(args: unknown): void;
     /** Launch an instance under the ambient current node (or the root). */
     launch(spec: LaunchSpec): ActionRun;
     private append;
@@ -83,7 +101,27 @@ export declare class ExecutionTree {
     private nodeView;
     /** Test seam: the projected run view (same object written to result.json). */
     runViewForTest(): RunView;
+    /** Test seam: the run's curated artifacts. */
+    artifactsForTest(): readonly ArtifactRecord[];
+    /** Test seam: every log entry recorded for this run. */
+    entriesForTest(): readonly LogEntry[];
     private runView;
+    /**
+     * The run's curated artifacts, keyed by `(nodeId, name)`: one action re-registering
+     * a name (e.g. re-labelling the same file after regenerating it) updates that entry
+     * in place rather than appending a second one, so `result.json` always reflects the
+     * latest registration per name. Keying on the pair — not `name` alone — matters
+     * because two *different* actions can independently choose the same name (two
+     * screenshot steps both calling `ctx.artifact("screenshot", …)`); those describe two
+     * distinct files and both must survive into `result.json`, not collapse into one.
+     * Position follows first registration; `artifacts.log` (a chronological rollup, like
+     * `events.log`/`asserts.log`) is unaffected either way and still lists every call.
+     *
+     * The pair is joined with `\0` — the same separator `omHash` uses, and for the same
+     * reason: a step name may legitimately contain colons (`TSKB:root:watch:docs`) and an
+     * artifact name is free-form, so any printable separator can be forged inside a key.
+     */
+    private curatedArtifacts;
     /**
      * Absolute `.log` path for a node — root is `main.log`, children drop the `main/`
      * prefix. Each id segment is sanitized so names with filesystem-illegal characters

package/dist/core/ExecutionTree.js

@@ -7,6 +7,7 @@ import { LogStore } from "../output/log/LogStore.js";
 import { RunFolder } from "../output/folder/RunFolder.js";
 import { RawStream } from "../output/log/RawStream.js";
 import { SnapshotStore } from "../output/snapshot/SnapshotStore.js";
+import { ArtifactStore } from "../output/artifact/ArtifactStore.js";
 import { ConsoleCapture } from "../output/console/ConsoleCapture.js";
 import { LiveRenderer } from "../output/LiveRenderer.js";
 import { writeNodeLogs } from "../output/writers/NodeLogWriter.js";
@@ -40,9 +41,22 @@ export class ExecutionTree {
     store = new LogStore();
     folder;
     root;
+    /**
+     * The om's `.describe(…)` summary, carried here from the builder so it survives the
+     * terminal `.run(...)` call. Stored so it is retrievable; nothing reads it yet.
+     */
+    description;
+    /**
+     * The om's `.mcp(…)` exposure, carried here from the builder for the same reason
+     * `description` is: `.run(...)` is the terminal call, and an om has no definition object
+     * to hang it on. The MCP server reads its own copy from the discovery fork, not from
+     * here — this is what makes the carry observable, and therefore testable, at all.
+     */
+    mcp;
     rawStream;
     consoleCapture;
     snapshotStore;
+    artifactStore = new ArtifactStore();
     registry = [];
     unsettled = new Set();
     originalLog = console.log.bind(console);
@@ -51,6 +65,10 @@ export class ExecutionTree {
     forwarding;
     assertionsPassed = 0;
     assertionsFailed = 0;
+    // The root's args are resolved *inside* its body (prompting is async), so unlike a
+    // child node's they cannot be handed to `run()` up front — they are recorded here
+    // instead and projected onto the root by `nodeView`.
+    rootArgs = [];
     faults = [];
     static graceMs = 5000; // teardown waits this long for nodes to settle, then finalizes anyway
     phase = "open";
@@ -65,7 +83,9 @@ export class ExecutionTree {
     // Process hooks — installed at run start, removed at finalize (they must not outlive the run).
     onUncaught = (e) => this.onFatal("uncaughtException", e);
     onUnhandled = (e) => this.onFatal("unhandledRejection", e);
-    constructor(name, definedAt) {
+    constructor(name, definedAt, description, mcp) {
+        this.description = description;
+        this.mcp = mcp;
         // The run's identity: its name + where om() is written (not how it was launched),
         // so same-named oms in different files get distinct log folders.
         this.folder = new RunFolder(name, omHash(name, siteFile(definedAt)));
@@ -87,6 +107,10 @@ export class ExecutionTree {
         this.consoleCapture = new ConsoleCapture(this.store, () => (currentNode.getStore() ?? this.root).toRef());
         ExecutionTree.last = this;
     }
+    /** Record the run's resolved args, so the root's log header reports them. */
+    setRootArgs(args) {
+        this.rootArgs = [args];
+    }
     /** Launch an instance under the ambient current node (or the root). */
     launch(spec) {
         if (this.phase !== "open") {
@@ -137,6 +161,7 @@ export class ExecutionTree {
         return {
             store: this.store,
             snapshots: this.snapshotStore,
+            artifacts: this.artifactStore,
             artifactsFolder: this.folder.path(),
             onAssert: (pass, actionPath, message) => this.recordAssert(pass, actionPath, message),
             onUnhandledFailure: (actionPath, error) => {
@@ -276,6 +301,7 @@ export class ExecutionTree {
         await writeRollup(at("events.log"), flat, entries, (e) => e.level === "event");
         await writeRollup(at("asserts.log"), flat, entries, (e) => e.level === "assert", assertSummary);
         await writeRollup(at("snapshots.log"), flat, entries, (e) => e.level === "snapshot");
+        await writeRollup(at("artifacts.log"), flat, entries, (e) => e.level === "artifact");
         await writeResult(at("result.json"), this.runView());
         // Only now let go of the process hooks — a Ctrl+C during the writes must still be
         // caught (as a no-op) so it can't fall through to Node's kill-without-log default.
@@ -306,6 +332,7 @@ export class ExecutionTree {
             `  events    → ${at("events.log")}`,
             `  asserts   → ${at("asserts.log")}   ${assertSummary}`,
             `  snapshots → ${at("snapshots.log")}`,
+            `  artifacts → ${at("artifacts.log")}`,
         ];
     }
     /** The recap to the terminal (files are already written). */
@@ -327,7 +354,8 @@ export class ExecutionTree {
             path: node.path,
             parentId: node.parentId,
             tags: [...node.tags],
-            args: [...node.args],
+            // The root never has args passed to `run()`; its own are resolved mid-body.
+            args: [...(node.parentId === null ? this.rootArgs : node.args)],
             status: node.status,
             startedAt: node.startedAt,
             endedAt: node.endedAt,
@@ -340,6 +368,14 @@ export class ExecutionTree {
     runViewForTest() {
         return this.runView();
     }
+    /** Test seam: the run's curated artifacts. */
+    artifactsForTest() {
+        return this.artifactStore.all();
+    }
+    /** Test seam: every log entry recorded for this run. */
+    entriesForTest() {
+        return this.store.entries();
+    }
     runView() {
         return {
             ok: this.faults.length === 0,
@@ -350,8 +386,36 @@ export class ExecutionTree {
             duration: this.root.duration,
             rawStream: this.rawStreamPath(),
             root: this.nodeView(this.root),
+            artifacts: this.curatedArtifacts(),
         };
     }
+    /**
+     * The run's curated artifacts, keyed by `(nodeId, name)`: one action re-registering
+     * a name (e.g. re-labelling the same file after regenerating it) updates that entry
+     * in place rather than appending a second one, so `result.json` always reflects the
+     * latest registration per name. Keying on the pair — not `name` alone — matters
+     * because two *different* actions can independently choose the same name (two
+     * screenshot steps both calling `ctx.artifact("screenshot", …)`); those describe two
+     * distinct files and both must survive into `result.json`, not collapse into one.
+     * Position follows first registration; `artifacts.log` (a chronological rollup, like
+     * `events.log`/`asserts.log`) is unaffected either way and still lists every call.
+     *
+     * The pair is joined with `\0` — the same separator `omHash` uses, and for the same
+     * reason: a step name may legitimately contain colons (`TSKB:root:watch:docs`) and an
+     * artifact name is free-form, so any printable separator can be forged inside a key.
+     */
+    curatedArtifacts() {
+        const byKey = new Map();
+        for (const { name, file, description, mime, nodeId } of this.artifactStore.all()) {
+            byKey.set(`${nodeId}\0${name}`, {
+                name,
+                file,
+                mime,
+                ...(description === undefined ? {} : { description }),
+            });
+        }
+        return [...byKey.values()];
+    }
     /**
      * Absolute `.log` path for a node — root is `main.log`, children drop the `main/`
      * prefix. Each id segment is sanitized so names with filesystem-illegal characters

package/dist/core/action.d.ts

@@ -1,7 +1,8 @@
 import type { ActionBuilderEvents, NoEvents } from "./types.ts";
 /**
  * Define an action. Provide the impl via `.run(…)`, optionally after declaring
- * events (`.emits<…>()`) and/or an imperative handle (`.ref<…>()`). Call the result
+ * metadata (`.describe(…)`), events (`.emits<…>()`), an imperative handle
+ * (`.ref<…>()`), and/or pinning the args type (`.args(schema)`). Call the result
  * to launch it.
  */
 export declare function action(name: string): ActionBuilderEvents<NoEvents, void>;

package/dist/core/action.js

@@ -1,36 +1,120 @@
 import { ExecutionTree } from "./ExecutionTree.js";
 import { callerSite } from "../foundation/callsite.js";
+import { describeSchema } from "./discovery-mode.js";
 /**
- * The builder returned by `action(name)`: declare events (`.emits<…>()`) and/or an
- * imperative handle (`.ref<…>()`), then bind the impl with `.run(…)`. `.run` returns a
- * callable {@link Action} — **invoking it launches** the action under the ambient current
- * node and returns the live {@link Activity}, on which `withCache`/`tag`/… chain.
+ * The builder returned by `action(name)`: declare metadata (`.describe(…)`), events
+ * (`.emits<…>()`), an imperative handle (`.ref<…>()`), and/or pin the args type
+ * (`.args(schema)`), then bind the impl with `.run(…)`. `.run` returns a callable
+ * {@link Action} — **invoking it launches** the action under the ambient current node
+ * and returns the live {@link Activity}, on which `withCache`/`tag`/… chain.
  */
 class Builder {
     name;
-    constructor(name) {
+    description;
+    exposure;
+    constructor(name, 
+    /** Carried across `.emits()`/`.ref()`, which otherwise rebuild the builder. */
+    description = undefined, 
+    /** Carried the same way, for the same reason. */
+    exposure = undefined) {
         this.name = name;
+        this.description = description;
+        this.exposure = exposure;
+    }
+    describe(description) {
+        this.description = description;
+        return this;
+    }
+    mcp(exposure = {}) {
+        // The default is filled here, not at the reader, so every consumer sees one shape.
+        this.exposure = { mode: exposure.mode ?? "settling" };
+        return this;
     }
     emits() {
-        return new Builder(this.name);
+        return new Builder(this.name, this.description, this.exposure);
     }
     ref() {
-        return new Builder(this.name);
+        return new Builder(this.name, this.description, this.exposure);
+    }
+    args(schema) {
+        return new ArgsBuilder(this.name, schema, this.description, this.exposure);
     }
     run(body) {
         const name = this.name;
+        // Carried onto the definition for `omkit ls` and the MCP server; not read by the runtime.
+        const description = this.description;
+        const mcp = this.exposure;
         const definedAt = callerSite(); // the `.run(...)` call site — where this action lives
+        // No `.args()` on this path, so there is nothing to describe.
+        const describeArgs = () => describeSchema(undefined);
+        const exec = body;
+        const create = (...args) => {
+            const spec = { name, args, tags: [], body: exec, definedAt };
+            return ExecutionTree.require().launch(spec);
+        };
+        return Object.assign(create, {
+            actionName: name,
+            definedAt,
+            description,
+            mcp,
+            describeArgs,
+        });
+    }
+}
+/**
+ * The builder after `.args(schema)`. The schema pins `.run`'s parameter type; it is not
+ * validated here — an action invoked from an om body is passed its args directly in code.
+ * (Spec B's MCP server validates before it ever reaches this point.)
+ */
+class ArgsBuilder {
+    name;
+    schema;
+    description;
+    exposure;
+    constructor(name, 
+    /** Type-level only: `S` pins `.run`'s parameter. Nothing reads the value at runtime. */
+    schema, description, exposure) {
+        this.name = name;
+        this.schema = schema;
+        this.description = description;
+        this.exposure = exposure;
+    }
+    describe(description) {
+        this.description = description;
+        return this;
+    }
+    mcp(exposure = {}) {
+        this.exposure = { mode: exposure.mode ?? "settling" };
+        return this;
+    }
+    run(body) {
+        const name = this.name;
+        // Carried onto the definition for `omkit ls` and the MCP server; not read by the runtime.
+        const description = this.description;
+        const mcp = this.exposure;
+        const definedAt = callerSite();
+        // The schema is captured so the conversion happens in *this* copy of omkit — the one
+        // that built it — rather than in whichever copy the discovery child is running.
+        const schema = this.schema;
+        const describeArgs = () => describeSchema(schema);
         const exec = body;
         const create = (...args) => {
             const spec = { name, args, tags: [], body: exec, definedAt };
             return ExecutionTree.require().launch(spec);
         };
-        return Object.assign(create, { actionName: name, definedAt });
+        return Object.assign(create, {
+            actionName: name,
+            definedAt,
+            description,
+            mcp,
+            describeArgs,
+        });
     }
 }
 /**
  * Define an action. Provide the impl via `.run(…)`, optionally after declaring
- * events (`.emits<…>()`) and/or an imperative handle (`.ref<…>()`). Call the result
+ * metadata (`.describe(…)`), events (`.emits<…>()`), an imperative handle
+ * (`.ref<…>()`), and/or pinning the args type (`.args(schema)`). Call the result
  * to launch it.
  */
 export function action(name) {