omkit 0.8.6 → 0.8.7

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/client/channel.js

@@ -8,6 +8,7 @@ export function createChannel(transport) {
         log: [],
         prompt: [],
         promptDone: [],
+        up: [],
         settled: [],
     };
     let settled = false;
@@ -26,6 +27,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/interaction.d.ts

@@ -25,6 +25,16 @@ export type ChildMessage = {
 } | {
     kind: "log";
     entry: 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;
@@ -56,6 +66,7 @@ export declare class Supervisor {
     constructor(send: Send, onMessage: OnMessage);
     request(spec: PromptSpec, signal: AbortSignal): Promise<AnswerMessage>;
     log(entry: LogEntry): void;
+    up(ok: boolean, folder: string): void;
     settled(ok: boolean, folder: string, summary: string[]): void;
     onCancel(handler: () => void): void;
 }

package/dist/core/interaction.js

@@ -48,6 +48,9 @@ export class Supervisor {
     log(entry) {
         this.send({ kind: "log", entry });
     }
+    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 {

package/dist/mcp/action-host.js

@@ -53,7 +53,9 @@ om(hostOmName(name, file))
     // `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 launch(args).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.7",
   "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",