omkit 0.8.6 → 0.8.8

package/README.md

@@ -87,7 +87,7 @@ const build = action("build").run(({ proc }) => proc("tsc")`tsc -b`);
 const activity = build(); // calling launches; returns the live Activity
 ```
 
-Chain `.describe({ summary })` before `.run(...)` to attach a human-readable summary — stored on the definition, for `omkit ls` and future tooling to read; nothing reads it yet, so today it is documentation that travels with the code. Same shape as `om`'s, below. `.args(schema)` pins the type of `.run`'s second parameter to a zod schema's inferred type. It's **type-level only**: nothing here resolves, prompts for, or validates the value — an action launched from an om body is passed its arguments directly in code, so the schema exists to type that call site, not to gate it. (Resolving/prompting for arguments is an `om`-level concern, not `action`'s.)
+Chain `.describe({ summary })` before `.run(...)` to attach a human-readable summary — stored on the definition, for `omkit ls` and future tooling to read; nothing reads it yet, so today it is documentation that travels with the code. Same shape as `om`'s, below. `.args(schema)` pins the type of `.run`'s second parameter to a zod schema's inferred type. In code it's **type-level only**: launching neither resolves, prompts for, nor validates the value — an action launched from an om body is passed its arguments directly in code, so the schema types that call site rather than gating it. The exception is an action run as an MCP tool: the JSON an assistant sends is resolved through this same schema before the body runs, so `.default()`s are filled and bad values are refused — the default `list_oms` advertises is the one the body gets. (Prompting for arguments stays an `om`-level concern.)
 
 ```ts
 import { z } from "zod";
@@ -96,7 +96,7 @@ const seed = action("seed")
   .describe({ summary: "Seeds the database" })
   .args(z.object({ rows: z.number() }))
   .run(async (_ctx, { rows }) => {
-    /* rows: number — typed, not validated */
+    /* rows: number — typed; validated only when run as an MCP tool */
   });
 
 seed({ rows: 500 }); // calling launches it; the shape is pinned, not checked at runtime

package/dist/actions/drive-page.d.ts

@@ -48,3 +48,11 @@ export interface DrivePageResult {
  * failing, or being cancelled never tears down the stack it attached to, in either mode.
  */
 export declare const drivePage: import("../core/types.ts").Action<[opts: DrivePageOptions], DrivePageResult, import("../core/types.ts").NoEvents, void>;
+/**
+ * The message for an expression that threw in the page. Leads with what the page said —
+ * the first line of the cause, which is the `TypeError: …` a caller can act on — and names
+ * the expression only briefly: the caller sent it, so echoing all of it adds nothing, and a
+ * page-side stack means little to someone who only handed over a string. The original
+ * error stays attached as the cause.
+ */
+export declare function evaluateErrorMessage(js: string, cause: unknown): string;

package/dist/actions/drive-page.js

@@ -39,6 +39,20 @@ export const drivePage = action("drivePage")
         attached.cancel();
     }
 });
+/** Longest slice of the expression an error message repeats back. */
+const JS_EXCERPT = 160;
+/**
+ * The message for an expression that threw in the page. Leads with what the page said —
+ * the first line of the cause, which is the `TypeError: …` a caller can act on — and names
+ * the expression only briefly: the caller sent it, so echoing all of it adds nothing, and a
+ * page-side stack means little to someone who only handed over a string. The original
+ * error stays attached as the cause.
+ */
+export function evaluateErrorMessage(js, cause) {
+    const said = (cause instanceof Error ? cause.message : String(cause)).split("\n")[0].trim();
+    const excerpt = js.length > JS_EXCERPT ? `${js.slice(0, JS_EXCERPT)}…` : js;
+    return `the expression threw in the page: ${said} · expression: ${excerpt}`;
+}
 /** The work itself, split out so the daemon handle above has one obvious release point. */
 async function evaluateIn(page, opts, { snapshot, artifact, artifactsFolder }) {
     const { js, screenshot = true } = opts;
@@ -52,9 +66,7 @@ async function evaluateIn(page, opts, { snapshot, artifact, artifactsFolder }) {
         value = await page.evaluate(js);
     }
     catch (cause) {
-        // A page-side stack means little to a caller who only sent a string, so lead with the
-        // expression that failed and keep the original as the cause.
-        throw new Error(`the expression threw in the page: ${js}`, { cause });
+        throw new Error(evaluateErrorMessage(js, cause), { cause });
     }
     void snapshot("result", { js, value });
     console.log(`result: ${JSON.stringify(value) ?? "undefined"}`);

package/dist/cli/ui/app.js

@@ -5,6 +5,7 @@ import { RunModel } from "../../output/RunModel.js";
 import { OmList } from "./views/OmList.js";
 import { RunView } from "./views/RunView.js";
 import { Spinner } from "./Spinner.js";
+import { redrawLoop } from "./redrawLoop.js";
 /**
  * How often the run screen redraws while the log streams in.
  *
@@ -13,7 +14,8 @@ import { Spinner } from "./Spinner.js";
  * dev server emits. The app then falls permanently behind: `settled` is the *last* message on
  * the channel, so it only arrives once every backlogged entry has been drawn, and the run looks
  * hung long after the child has finished. Folding into the model is cheap; drawing is not, so
- * the two run at different rates.
+ * the two run at different rates — and the gap is kept *after* each frame (see {@link redrawLoop}),
+ * since a frame slower than this would otherwise leave no time between frames for the log at all.
  */
 const REDRAW_MS = 80;
 /** The interactive app: discover → list/search → run → live milestones + prompts. */
@@ -34,9 +36,7 @@ export function App({ client, onExit, oms: initialOms, }) {
     const tearingRef = useRef(false);
     const redrawTimer = useRef(undefined);
     const stopRedraw = () => {
-        if (redrawTimer.current === undefined)
-            return;
-        clearInterval(redrawTimer.current);
+        redrawTimer.current?.stop();
         redrawTimer.current = undefined;
     };
     // The redraw timer holds the event loop open, so it must not outlive the app — an unmount
@@ -69,7 +69,7 @@ export function App({ client, onExit, oms: initialOms, }) {
             setLines(model.milestones());
             setStatus(model.summary());
         };
-        redrawTimer.current = setInterval(redraw, REDRAW_MS);
+        redrawTimer.current = redrawLoop(redraw, REDRAW_MS);
         s.on("log", (entry) => {
             model.apply(entry);
             dirty = true;

package/dist/cli/ui/redrawLoop.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Call `draw` repeatedly, leaving `everyMs` of free event-loop time **after** each frame
+ * finishes — not every `everyMs` from when the last one started, as `setInterval` does.
+ *
+ * The difference only shows when a frame is slower than the cadence, which a full Ink milestone
+ * tail is. A fixed-rate timer is then overdue the moment a frame ends, so the loop alternates one
+ * frame with one turn of I/O — and on Windows a turn of fork IPC is a single message. The
+ * interactive app then drains its log backlog a frame per entry, and a run that finished minutes
+ * ago is still "streaming" on screen, with `settled` stuck behind the backlog.
+ *
+ * The next frame is armed from a `setImmediate`, so the gap is measured from after anything the
+ * frame deferred to microtasks (React's commit, Ink's write) has run too.
+ */
+export declare function redrawLoop(draw: () => void, everyMs: number): {
+    stop(): void;
+};

package/dist/cli/ui/redrawLoop.js

@@ -0,0 +1,40 @@
+/**
+ * Call `draw` repeatedly, leaving `everyMs` of free event-loop time **after** each frame
+ * finishes — not every `everyMs` from when the last one started, as `setInterval` does.
+ *
+ * The difference only shows when a frame is slower than the cadence, which a full Ink milestone
+ * tail is. A fixed-rate timer is then overdue the moment a frame ends, so the loop alternates one
+ * frame with one turn of I/O — and on Windows a turn of fork IPC is a single message. The
+ * interactive app then drains its log backlog a frame per entry, and a run that finished minutes
+ * ago is still "streaming" on screen, with `settled` stuck behind the backlog.
+ *
+ * The next frame is armed from a `setImmediate`, so the gap is measured from after anything the
+ * frame deferred to microtasks (React's commit, Ink's write) has run too.
+ */
+export function redrawLoop(draw, everyMs) {
+    let stopped = false;
+    let timer;
+    let immediate;
+    const arm = () => {
+        immediate = undefined;
+        if (!stopped)
+            timer = setTimeout(tick, everyMs);
+    };
+    const tick = () => {
+        timer = undefined;
+        if (stopped)
+            return;
+        draw();
+        immediate = setImmediate(arm);
+    };
+    timer = setTimeout(tick, everyMs);
+    return {
+        stop: () => {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            if (immediate)
+                clearImmediate(immediate);
+        },
+    };
+}

package/dist/client/channel.js

@@ -8,15 +8,18 @@ export function createChannel(transport) {
         log: [],
         prompt: [],
         promptDone: [],
+        up: [],
         settled: [],
     };
     let settled = false;
     let resolveResult;
     const result = new Promise((resolve) => (resolveResult = resolve));
     transport.onMessage((message) => {
-        if (message.kind === "log") {
-            for (const h of handlers.log)
-                h(message.entry);
+        if (message.kind === "logs") {
+            // Batched on the wire (see Supervisor.log); consumers still see one `log` per entry.
+            for (const entry of message.entries)
+                for (const h of handlers.log)
+                    h(entry);
         }
         else if (message.kind === "prompt") {
             for (const h of handlers.prompt)
@@ -26,6 +29,11 @@ export function createChannel(transport) {
             for (const h of handlers.promptDone)
                 h(message.id);
         }
+        else if (message.kind === "up") {
+            const info = { ok: message.ok, folder: message.folder };
+            for (const h of handlers.up)
+                h(info);
+        }
         else if (message.kind === "settled") {
             settled = true;
             const verdict = { ok: message.ok, folder: message.folder, summary: message.summary };

package/dist/client/types.d.ts

@@ -15,6 +15,16 @@ export interface Verdict {
      *  block a bare run prints to its terminal. Empty if the child closed without settling. */
     readonly summary: readonly string[];
 }
+/**
+ * The run's body has returned. For a long-lived run this is "the stack is up": a caller
+ * that wants to drive it (attach to its browser, hit its server) waits for this, not for
+ * `settled`, which never comes on its own. `ok` is the verdict so far; `folder` is the
+ * dated run folder, known from here on.
+ */
+export interface RunUp {
+    readonly ok: boolean;
+    readonly folder: string;
+}
 /** A typecheck diagnostic from `check()`. */
 export interface Diagnostic {
     readonly file: string;
@@ -46,6 +56,8 @@ export interface RunEvents {
     prompt: (request: PromptRequest) => void;
     /** A pending prompt was withdrawn by the child (timed out or torn down) — clear it from the UI. */
     promptDone: (id: string) => void;
+    /** The root body returned — see {@link RunUp}. Fires at most once, before `settled`. */
+    up: (info: RunUp) => void;
     settled: (verdict: Verdict) => void;
 }
 /** A live handle to one supervised run. */

package/dist/core/ExecutionTree.js

@@ -247,6 +247,11 @@ export class ExecutionTree {
         const rootPromise = currentNode.run(this.root, () => this.root.run(body, []));
         this.trackNode(rootPromise);
         await rootPromise;
+        // The body has returned. A long-lived run is "up" from here — its daemons keep it
+        // open — and a supervisor that started it wants to know, because nothing else on the
+        // channel distinguishes "still booting" from "up and driveable" before `settled`.
+        if (supervisor)
+            supervisor.up(this.verdictOk(), this.folder.path());
         await this.drive();
         await this.finalize();
     }
@@ -377,6 +382,7 @@ export class ExecutionTree {
         return this.store.entries();
     }
     runView() {
+        const value = serialisable(this.root.value);
         return {
             ok: this.faults.length === 0,
             failures: [...this.faults],
@@ -387,6 +393,7 @@ export class ExecutionTree {
             rawStream: this.rawStreamPath(),
             root: this.nodeView(this.root),
             artifacts: this.curatedArtifacts(),
+            ...(value === undefined ? {} : { value }),
         };
     }
     /**
@@ -440,3 +447,18 @@ export class ExecutionTree {
     }
 }
 const messageOf = (error) => error instanceof Error ? (error.stack ?? error.message) : String(error);
+/**
+ * The value as `result.json` will carry it, or undefined when it cannot be carried. A
+ * body may hand back anything — a capability handle, a cyclic object — and the run must
+ * still write its record; a value that does not survive JSON is dropped, not fatal.
+ */
+function serialisable(value) {
+    if (value === undefined)
+        return undefined;
+    try {
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/action.js

@@ -1,6 +1,7 @@
 import { ExecutionTree } from "./ExecutionTree.js";
 import { callerSite } from "../foundation/callsite.js";
 import { describeSchema } from "./discovery-mode.js";
+import { formatIssues } from "./args.js";
 /**
  * The builder returned by `action(name)`: declare metadata (`.describe(…)`), events
  * (`.emits<…>()`), an imperative handle (`.ref<…>()`), and/or pin the args type
@@ -45,8 +46,9 @@ class Builder {
         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.
+        // No `.args()` on this path, so there is nothing to describe — or to resolve against.
         const describeArgs = () => describeSchema(undefined);
+        const parseArgs = (supplied) => supplied;
         const exec = body;
         const create = (...args) => {
             const spec = { name, args, tags: [], body: exec, definedAt };
@@ -58,13 +60,16 @@ class Builder {
             description,
             mcp,
             describeArgs,
+            parseArgs,
         });
     }
 }
 /**
- * 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.)
+ * The builder after `.args(schema)`. The schema pins `.run`'s parameter type; launching is
+ * not validated — an action invoked from an om body is passed its args directly in code,
+ * and the type already holds. The one untyped caller is the MCP action host, which hands
+ * the JSON it was sent through `parseArgs` first, so defaults and validation come from
+ * this same schema rather than from nothing.
  */
 class ArgsBuilder {
     name;
@@ -72,7 +77,7 @@ class ArgsBuilder {
     description;
     exposure;
     constructor(name, 
-    /** Type-level only: `S` pins `.run`'s parameter. Nothing reads the value at runtime. */
+    /** `S` pins `.run`'s parameter; the value backs `describeArgs` and `parseArgs`. */
     schema, description, exposure) {
         this.name = name;
         this.schema = schema;
@@ -97,6 +102,14 @@ class ArgsBuilder {
         // that built it — rather than in whichever copy the discovery child is running.
         const schema = this.schema;
         const describeArgs = () => describeSchema(schema);
+        // `safeParse` is what applies `.default()`s, so this is where an advertised default
+        // becomes the effective one. A refusal names the action and every failing field.
+        const parseArgs = (supplied) => {
+            const parsed = schema.safeParse(supplied);
+            if (parsed.success)
+                return parsed.data;
+            throw new Error(`invalid args for ${name}: ${formatIssues(parsed.error)}`);
+        };
         const exec = body;
         const create = (...args) => {
             const spec = { name, args, tags: [], body: exec, definedAt };
@@ -108,6 +121,7 @@ class ArgsBuilder {
             description,
             mcp,
             describeArgs,
+            parseArgs,
         });
     }
 }

package/dist/core/args.d.ts

@@ -37,6 +37,8 @@ export interface ResolveOptions {
  * the second is unanswerable.
  */
 export declare function resolveArgs(schema: z.ZodType, opts: ResolveOptions): Promise<unknown>;
+/** Every issue on one line, `path — reason`, for an error message a caller can act on. */
+export declare function formatIssues(error: z.ZodError): string;
 /**
  * True once a JSON-kind answer is finished. A `{`/`[` opener is a pasted blob and is done
  * when it parses; anything else is a path to a JSON file, and one line is the whole answer.

package/dist/core/args.js

@@ -45,13 +45,13 @@ export async function resolveArgs(schema, opts) {
         // refinement, or a schema that isn't an object at all). No question would make progress,
         // so fail now with the real reason instead of looping silently to the attempt cap.
         if (blocking.length === 0)
-            throw new Error(`could not resolve args: ${message(parsed.error)}`);
+            throw new Error(`could not resolve args: ${formatIssues(parsed.error)}`);
         if (!opts.interactive) {
             const anySupplied = blocking.some((field) => current[field] !== undefined);
-            throw new MissingArgsError(blocking, anySupplied ? message(parsed.error) : undefined);
+            throw new MissingArgsError(blocking, anySupplied ? formatIssues(parsed.error) : undefined);
         }
         if (attempt >= MAX_ATTEMPTS) {
-            throw new Error(`could not resolve args after ${MAX_ATTEMPTS} attempts: ${message(parsed.error)}`);
+            throw new Error(`could not resolve args after ${MAX_ATTEMPTS} attempts: ${formatIssues(parsed.error)}`);
         }
         for (const field of blocking) {
             const fieldSchema = propertySchema(root(), field);
@@ -85,7 +85,8 @@ function blockingFields(error) {
     const names = error.issues.map((i) => String(i.path[0] ?? "")).filter((n) => n !== "");
     return [...new Set(names)];
 }
-function message(error) {
+/** Every issue on one line, `path — reason`, for an error message a caller can act on. */
+export function formatIssues(error) {
     return error.issues.map((i) => `${i.path.join(".") || "(root)"} — ${i.message}`).join("; ");
 }
 function propertySchema(root, field) {

package/dist/core/interaction.d.ts

@@ -22,9 +22,21 @@ export type ChildMessage = {
 } | {
     kind: "prompt-done";
     id: string;
-} | {
-    kind: "log";
-    entry: LogEntry;
+}
+/** Log entries, oldest first — batched, see {@link Supervisor.log}. */
+ | {
+    kind: "logs";
+    entries: LogEntry[];
+}
+/**
+ * The root body has returned. For a long-lived run this is the moment its stack is up
+ * and can be reached from outside; the run itself goes on until it is torn down.
+ * Carries the dated folder, which exists by now — the body ran inside it.
+ */
+ | {
+    kind: "up";
+    ok: boolean;
+    folder: string;
 } | {
     kind: "settled";
     ok: boolean;
@@ -49,13 +61,26 @@ type OnMessage = (handler: (message: SupervisorMessage) => void) => void;
  * decides nothing (the child keeps its own prompt timeout; see the `prompt` action).
  */
 export declare class Supervisor {
-    private readonly send;
+    private readonly sendRaw;
     private seq;
     private readonly pending;
     private cancelHandler;
-    constructor(send: Send, onMessage: OnMessage);
+    private batch;
+    private flushTimer;
+    private readonly send;
+    constructor(sendRaw: Send, onMessage: OnMessage);
     request(spec: PromptSpec, signal: AbortSignal): Promise<AnswerMessage>;
+    /**
+     * Queue a log entry; it goes up with whatever else arrives within {@link LOG_BATCH_MS}.
+     *
+     * Batched because each IPC message costs the supervisor an event-loop turn (on Windows, Node
+     * delivers at most one per turn), and a frontend with slow frames can only take so many turns
+     * a second. A message per entry let a chatty run outpace the interactive app, which then kept
+     * replaying the log long after the run had finished, with `settled` stuck behind it.
+     */
     log(entry: LogEntry): void;
+    private flush;
+    up(ok: boolean, folder: string): void;
     settled(ok: boolean, folder: string, summary: string[]): void;
     onCancel(handler: () => void): void;
 }

package/dist/core/interaction.js

@@ -1,3 +1,9 @@
+/**
+ * How long log entries wait to share one message. Short enough to read as live on screen; long
+ * enough that a burst — a build or test suite printing hundreds of lines — crosses as a handful
+ * of messages rather than hundreds.
+ */
+const LOG_BATCH_MS = 25;
 /**
  * The child-side handle to an out-of-process supervisor. Sends prompt requests, live log
  * entries, and the final verdict up the channel; resolves prompts when the matching answer
@@ -5,12 +11,22 @@
  * decides nothing (the child keeps its own prompt timeout; see the `prompt` action).
  */
 export class Supervisor {
-    send;
+    sendRaw;
     seq = 0;
     pending = new Map();
     cancelHandler;
-    constructor(send, onMessage) {
-        this.send = send;
+    batch = [];
+    flushTimer;
+    send;
+    constructor(sendRaw, onMessage) {
+        this.sendRaw = sendRaw;
+        // Every other message leaves through here, so a pending batch always goes first: the entries
+        // that led to a prompt are the context it is read in, and a run's closing entries must land
+        // before its verdict.
+        this.send = (message) => {
+            this.flush();
+            sendRaw(message);
+        };
         onMessage((message) => {
             if (message.kind === "answer") {
                 const resolve = this.pending.get(message.id);
@@ -45,8 +61,30 @@ export class Supervisor {
             this.send({ kind: "prompt", id, spec });
         });
     }
+    /**
+     * Queue a log entry; it goes up with whatever else arrives within {@link LOG_BATCH_MS}.
+     *
+     * Batched because each IPC message costs the supervisor an event-loop turn (on Windows, Node
+     * delivers at most one per turn), and a frontend with slow frames can only take so many turns
+     * a second. A message per entry let a chatty run outpace the interactive app, which then kept
+     * replaying the log long after the run had finished, with `settled` stuck behind it.
+     */
     log(entry) {
-        this.send({ kind: "log", entry });
+        this.batch.push(entry);
+        this.flushTimer ??= setTimeout(() => this.flush(), LOG_BATCH_MS);
+    }
+    flush() {
+        if (this.flushTimer)
+            clearTimeout(this.flushTimer);
+        this.flushTimer = undefined;
+        if (this.batch.length === 0)
+            return;
+        const entries = this.batch;
+        this.batch = [];
+        this.sendRaw({ kind: "logs", entries });
+    }
+    up(ok, folder) {
+        this.send({ kind: "up", ok, folder });
     }
     settled(ok, folder, summary) {
         this.send({ kind: "settled", ok, folder, summary });

package/dist/core/om.js

@@ -117,7 +117,7 @@ class ArgsBuilder {
                 ask: askForArg,
             }));
             ExecutionTree.current?.setRootArgs(args);
-            await body(ctx, args);
+            return body(ctx, args);
         }, 
         // Handed to `launch` for discovery only: in a real run the schema is resolved above,
         // inside the body. Discovery never reaches that body, so it converts the schema here.

package/dist/core/types.d.ts

@@ -98,9 +98,10 @@ export interface OmBuilder {
      * Launch the run with `body` as its root. The body runs inside the root node's
      * ambient scope, so any action call / `step(...)` / `console.*` it reaches attributes
      * correctly. Resolves once the run has torn down and produced its artifacts; never
-     * rejects (failures are recorded in the tree and set the exit code).
+     * rejects (failures are recorded in the tree and set the exit code). Whatever the body
+     * returns is recorded as the run's `value` in `result.json`.
      */
-    run(body: (ctx: OmContext) => Awaitable<void>): Promise<void>;
+    run(body: (ctx: OmContext) => Awaitable<unknown>): Promise<void>;
 }
 /** After `.args(schema)`: `.run`'s body receives the resolved, typed args. */
 export interface OmBuilderArgs<S extends ZodTypeLike> {
@@ -111,9 +112,10 @@ export interface OmBuilderArgs<S extends ZodTypeLike> {
      * Launch the run, resolving the declared args first — supplied values, then defaults,
      * then prompting — and pass them to `body` as its second parameter. Resolution happens
      * *inside* the run, so a prompt and its answer land on the run's own timeline; an
-     * unresolvable arg fails the run like any other error in the body.
+     * unresolvable arg fails the run like any other error in the body. Whatever the body
+     * returns is recorded as the run's `value` in `result.json`.
      */
-    run(body: (ctx: OmContext, args: InferSchema<S>) => Awaitable<void>): Promise<void>;
+    run(body: (ctx: OmContext, args: InferSchema<S>) => Awaitable<unknown>): Promise<void>;
 }
 /** What the `om` body receives — the run-level counterpart to {@link ActionContext}. */
 export interface OmContext {
@@ -201,6 +203,13 @@ export interface Action<Args extends unknown[], Result, Events extends object =
      * throws — an unconvertible schema comes back as `schemaError`.
      */
     readonly describeArgs: () => DescribedArgs;
+    /**
+     * Resolve args that arrived as untyped JSON — the MCP host's — against the declared
+     * schema: defaults filled, everything validated, or a throw naming the field. Identity
+     * without `.args()`. Runs in the defining copy of omkit for the same reason
+     * `describeArgs` does. In-code callers never need it: their args are typed.
+     */
+    readonly parseArgs: (supplied: unknown) => unknown;
 }
 /** Intermediate step from `action(name)`: declare metadata/events/handle, then the impl. */
 export interface ActionBuilderEvents<Events extends object, Handle = void> {

package/dist/mcp/action-host.js

@@ -47,13 +47,21 @@ om(hostOmName(name, file))
     if (typeof launch !== "function") {
         throw new Error(`${file} has no exported action "${exportName}"`);
     }
+    const action = launch;
+    // The server only checked that the JSON *looked* right (`checkArgs`). The schema that
+    // list_oms advertised — defaults included — lives on the action, so the action applies
+    // it: what the caller was told is what the body receives. An om does the same through
+    // `resolveArgs` before its body runs.
+    const resolved = action.parseArgs(args);
     // The action reaches `ExecutionTree.require()` through the copy of omkit *its* file
     // imported, and `current` is a static — so this only works when both resolve to the
     // same installed omkit. True for a normal install and for the fixtures; false under
     // `npm link`, a non-hoisted pnpm layout, or two omkit versions in one tree. The bare
     // error is undiagnosable from a client, so name the cause here.
     try {
-        await launch(args).result;
+        // The action's result becomes the run's `value`: the one thing an action-backed tool
+        // call exists to hand back, read from `result.json` by the server's verdict.
+        return await action(resolved).result;
     }
     catch (e) {
         if (e instanceof Error && /no active om\(\) run/.test(e.message)) {

package/dist/mcp/runs.d.ts

@@ -1,5 +1,5 @@
 import type { LogEntry } from "../foundation/LogEntry.ts";
-import type { RunSession, Verdict } from "../client/types.ts";
+import type { RunSession, RunUp, Verdict } from "../client/types.ts";
 export interface LiveRun {
     readonly id: string;
     /** The om or action name the client asked for. */
@@ -9,6 +9,13 @@ export interface LiveRun {
     readonly session: RunSession;
     readonly startedAt: number;
     status: "running" | "settled";
+    /** Set once the body has returned — for a long-lived run, once its stack is up. */
+    up?: RunUp;
+    /**
+     * Resolves with the `up` report, or with undefined if the run settles (or dies) without
+     * ever getting there — so a caller waiting to drive the stack is never left hanging.
+     */
+    readonly whenUp: Promise<RunUp | undefined>;
     verdict?: Verdict;
     /** The tail buffer. Entries are appended in sequence order, oldest dropped first. */
     readonly entries: LogEntry[];

package/dist/mcp/runs.js

@@ -20,6 +20,8 @@ export class RunRegistry {
      * starts at the tool boundary has already missed the run's opening lines.
      */
     start(name, folderName, session) {
+        let resolveUp;
+        const whenUp = new Promise((resolve) => (resolveUp = resolve));
         const run = {
             id: shortId(newUuid()),
             name,
@@ -29,7 +31,12 @@ export class RunRegistry {
             status: "running",
             entries: [],
             dropped: 0,
+            whenUp,
         };
+        session.on("up", (info) => {
+            run.up = info;
+            resolveUp(info);
+        });
         session.on("log", (entry) => {
             run.entries.push(entry);
             if (run.entries.length > BUFFER_LIMIT) {
@@ -40,6 +47,7 @@ export class RunRegistry {
         void session.result.then((verdict) => {
             run.status = "settled";
             run.verdict = verdict;
+            resolveUp(run.up); // no-op if `up` already resolved it; otherwise: never got there
         });
         this.runs.set(run.id, run);
         return run;

package/dist/mcp/tools.js

@@ -17,6 +17,25 @@ import { attachElicitation, attachProgress } from "./progress.js";
 const SETTLE_TIMEOUT_MS = 10 * 60 * 1000;
 /** How long teardown gets to finish writing the run folder after a backstop cancel. */
 const TEARDOWN_GRACE_MS = 10_000;
+/**
+ * How long `start_om` waits for a run to come up when asked to. A dev stack that cold-starts
+ * a bundler and a browser can take a minute; past this the handle comes back with
+ * `up: false` and the run carries on — the wait is a convenience, not a gate.
+ */
+const UP_TIMEOUT_MS = 2 * 60 * 1000;
+/** `run.whenUp`, bounded: resolves undefined once `ms` have passed without an `up` report. */
+async function upWithin(run, ms) {
+    let timer;
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(undefined), ms);
+    });
+    try {
+        return await Promise.race([run.whenUp, expired]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 /**
  * Wait for a run to settle, or cancel it and report that it did not.
  *
@@ -120,6 +139,19 @@ export function both(structuredContent) {
 export function toolError(message) {
     return { content: [{ type: "text", text: message }], isError: true };
 }
+/**
+ * What `get_run` says about a run that has not settled. The dated folder is stamped inside
+ * the child on first access and reported with `up`; until then there is genuinely nothing
+ * to name — not an empty string standing in for one.
+ */
+function runningReport(live) {
+    return {
+        status: "running",
+        name: live.name,
+        up: live.up !== undefined,
+        folder: live.up?.folder ?? "",
+    };
+}
 export function registerTools(server, ctx) {
     const registry = createRegistryCache(ctx.client);
     server.registerTool("list_oms", {
@@ -155,6 +187,28 @@ export function registerTools(server, ctx) {
             return `"${name}" is unavailable: ${entry.unavailable}`;
         return undefined;
     };
+    /**
+     * The gate both launching tools pass through: the entry must exist, be callable, be of a
+     * mode the tool accepts, and be handed arguments that at least look right — all before
+     * anything is forked. Mode is checked ahead of arguments on purpose: "use start_om" is
+     * the answer a caller needs first, and a missing argument would only bury it.
+     */
+    const admit = async (name, args, accepts = {}) => {
+        const entry = await findEntry(name);
+        const refusal = notRunnable(name, entry);
+        if (refusal || !entry)
+            return { ok: false, refusal: refusal };
+        if (accepts.settlingOnly && entry.mode === "long-lived") {
+            return {
+                ok: false,
+                refusal: `"${name}" is long-lived — start it with start_om, not run_om.`,
+            };
+        }
+        const problems = checkArgs(entry.inputSchema, args);
+        if (problems.length)
+            return { ok: false, refusal: problems.join("\n") };
+        return { ok: true, entry };
+    };
     /**
      * Launch an entry as a supervised run.
      *
@@ -188,9 +242,10 @@ export function registerTools(server, ctx) {
     server.registerTool("run_om", {
         title: "Run an om and wait for its verdict",
         description: "Runs a settling om (or an exposed action) to completion and returns whether it " +
-            "passed, where its run folder is, its assert tally, and any failures. Call " +
-            "list_oms first to learn what `args` to pass. A long-lived entry is refused — use " +
-            "start_om for those, and for anything that takes more than about a minute.",
+            "passed, where its run folder is, its assert tally, any failures, and — as `value` — " +
+            "what it returned (an action's result travels back here). Call list_oms first to " +
+            "learn what `args` to pass. A long-lived entry is refused — use start_om for those, " +
+            "and for anything that takes more than about a minute.",
         inputSchema: {
             name: z.string().describe("The om or action name, as reported by list_oms."),
             args: z
@@ -210,19 +265,17 @@ export function registerTools(server, ctx) {
             assertions: z.object({ passed: z.number(), failed: z.number() }),
             failures: z.array(z.object({ action: z.string(), error: z.string() })),
             summary: z.array(z.string()),
+            value: z
+                .unknown()
+                .optional()
+                .describe("What the om body (or the hosted action) returned, when it returned something."),
         },
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     }, async ({ name, args, settleTimeoutMs }, extra) => {
-        const entry = await findEntry(name);
-        const refusal = notRunnable(name, entry);
-        if (refusal || !entry)
-            return toolError(refusal);
-        if (entry.mode === "long-lived") {
-            return toolError(`"${name}" is long-lived — start it with start_om, not run_om.`);
-        }
-        const problems = checkArgs(entry.inputSchema, args ?? {});
-        if (problems.length)
-            return toolError(problems.join("\n"));
+        const admitted = await admit(name, args ?? {}, { settlingOnly: true });
+        if (!admitted.ok)
+            return toolError(admitted.refusal);
+        const { entry } = admitted;
         const run = launch(entry, args ?? {});
         // This request lives for the whole run, so it can carry progress and it owns the
         // run's cancellation: `extra.signal` aborting means the client withdrew the call.
@@ -239,12 +292,26 @@ export function registerTools(server, ctx) {
     });
     server.registerTool("start_om", {
         title: "Start an om without waiting for it",
-        description: "Starts an om or exposed action and returns a handle straight away. Use this for a " +
-            "long-lived entry (a server, a watcher), or for a long suite you want to check on " +
-            "later. Follow up with get_run, tail_run and cancel_run.",
+        description: "Starts an om or exposed action and returns a handle. Use this for a long-lived " +
+            "entry (a server, a watcher), or for a long suite you want to check on later. Pass " +
+            "`waitUntilUp: true` to return only once the om's body has returned — for a dev " +
+            "stack, once it is up and can be driven — rather than as soon as it is forked. " +
+            "Follow up with get_run, tail_run and cancel_run.",
         inputSchema: {
             name: z.string().describe("The om or action name, as reported by list_oms."),
             args: z.record(z.string(), z.unknown()).optional(),
+            waitUntilUp: z
+                .boolean()
+                .optional()
+                .describe("Wait for the body to return before answering. The result then says `up: true` " +
+                "and names the run folder; if it takes longer than upTimeoutMs the handle comes " +
+                "back anyway with `up: false` and the run keeps going."),
+            upTimeoutMs: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("How long waitUntilUp waits. Default 2 minutes."),
         },
         outputSchema: {
             runId: z.string(),
@@ -252,52 +319,59 @@ export function registerTools(server, ctx) {
             // The dated run folder does not exist yet — this is the folder *family*.
             folderName: z.string(),
             mode: z.enum(["settling", "long-lived"]),
+            up: z.boolean().describe("Whether the om's body had returned when this answered."),
+            folder: z.string().describe("The dated run folder — known once the run is up, else empty."),
         },
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
-    }, async ({ name, args }) => {
-        const entry = await findEntry(name);
-        const refusal = notRunnable(name, entry);
-        if (refusal || !entry)
-            return toolError(refusal);
-        const problems = checkArgs(entry.inputSchema, args ?? {});
-        if (problems.length)
-            return toolError(problems.join("\n"));
+    }, async ({ name, args, waitUntilUp, upTimeoutMs }) => {
+        const admitted = await admit(name, args ?? {});
+        if (!admitted.ok)
+            return toolError(admitted.refusal);
+        const { entry } = admitted;
         const run = launch(entry, args ?? {});
         // Elicitation only — deliberately no `attachProgress`. This request ends as soon as
         // the handle is returned, so its `extra.signal` aborts immediately, and wiring that
         // to `session.cancel()` would kill the run this tool exists to keep alive. A client
         // that wants progress from a started run polls `tail_run`.
         attachElicitation(server, run.session);
+        // Optionally hold the answer until the body has returned. Bounded, and never an
+        // error: the run is not at fault for a client that would not wait long enough.
+        const up = waitUntilUp ? await upWithin(run, upTimeoutMs ?? UP_TIMEOUT_MS) : undefined;
         return both({
             runId: run.id,
             name: entry.name,
             folderName: run.folderName,
             mode: entry.mode,
+            up: up !== undefined,
+            folder: up?.folder ?? "",
         });
     });
     server.registerTool("get_run", {
         title: "Check on a run",
-        description: "Reports whether a run is still going and, once it has settled, its verdict and " +
-            "links to the files it produced. `run` is a runId from start_om, or a run folder " +
-            "path under logs/.",
+        description: "Reports whether a run is still going — and, for one still going, whether its body " +
+            "has returned yet (`up`, the moment a long-lived stack can be driven) — and, once it " +
+            "has settled, its verdict and links to the files it produced. `run` is a runId from " +
+            "start_om, or a run folder path under logs/.",
         inputSchema: { run: z.string() },
         outputSchema: {
             status: z.enum(["running", "settled"]),
             name: z.string(),
             folder: z.string(),
+            up: z
+                .boolean()
+                .optional()
+                .describe("While running: whether the om's body has returned. Absent once settled."),
             ok: z.boolean().optional(),
             assertions: z.object({ passed: z.number(), failed: z.number() }).optional(),
             failures: z.array(z.object({ action: z.string(), error: z.string() })).optional(),
             summary: z.array(z.string()).optional(),
+            value: z.unknown().optional(),
         },
         annotations: { readOnlyHint: true, openWorldHint: false },
     }, async ({ run }) => {
         const live = ctx.runs.get(run);
-        if (live?.status === "running") {
-            // The dated folder is stamped inside the child on first access, so there is
-            // genuinely nothing to report here yet — not an empty string standing in for one.
-            return both({ status: "running", name: live.name, folder: "" });
-        }
+        if (live?.status === "running")
+            return both(runningReport(live));
         // A run this server started, or a folder already on disk — confined either way.
         const folder = live?.verdict?.folder ?? resolveRunFolder(ctx.root, run);
         if (!folder) {

package/dist/mcp/verdict.d.ts

@@ -21,6 +21,8 @@ export type RunVerdict = {
     }>;
     /** The recap block the terminal would have printed. */
     readonly summary: readonly string[];
+    /** What the run's body returned — for an action-backed tool, the action's result. */
+    readonly value?: unknown;
 };
 export declare function readVerdict(verdict: Verdict): Promise<RunVerdict>;
 /**

package/dist/mcp/verdict.js

@@ -28,6 +28,7 @@ export async function readVerdict(verdict) {
         ...base,
         assertions: parsed.assertions ?? base.assertions,
         failures: parsed.failures ?? base.failures,
+        ...(parsed.value === undefined ? {} : { value: parsed.value }),
     };
 }
 /**
@@ -43,5 +44,6 @@ export async function readVerdictAt(folder) {
         summary: [],
         assertions: parsed?.assertions ?? { passed: 0, failed: 0 },
         failures: parsed?.failures ?? [],
+        ...(parsed?.value === undefined ? {} : { value: parsed.value }),
     };
 }

package/dist/output/writers/views.d.ts

@@ -47,4 +47,9 @@ export interface RunView {
     readonly root: NodeView;
     /** Files the run labelled via `ctx.artifact`, in registration order. */
     readonly artifacts: readonly ArtifactView[];
+    /**
+     * What the om body returned, when it returned something JSON can carry. Absent
+     * otherwise — most bodies return nothing; an action host returns its action's result.
+     */
+    readonly value?: unknown;
 }

package/dist/skill/render.js

@@ -66,8 +66,10 @@ function howToRun(model) {
         "receive is filled from the schema's defaults, and only then by asking.",
         "",
         '**MCP — if configured:** `run_om("<name>", { …args })` runs a settling workflow to',
-        "completion and returns its verdict; `start_om` starts a long-lived one and returns a run id",
-        "to poll with `get_run`, read with `tail_run`, and end with `cancel_run`.",
+        "completion and returns its verdict — with what it returned as `value` (an action's result",
+        "comes back this way). `start_om` starts a long-lived one and returns a run id to poll with",
+        "`get_run`, read with `tail_run`, and end with `cancel_run`; pass `waitUntilUp: true` to get",
+        "the id back only once the workflow's body has returned — for a dev stack, once it is up.",
         "",
         `To wire it up: \`claude mcp add omkit -- npx omkit mcp${config}\``,
         "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "description": "A tiny runtime for developer workflows: typed actions that pass runtime capabilities and emit typed events, under one run and one shared log. The operational/runtime layer to tskb's knowledge layer.",
   "type": "module",
   "main": "./dist/index.js",