omkit 0.8.7 → 0.8.9

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/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

@@ -15,9 +15,11 @@ export function createChannel(transport) {
     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)

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,11 @@ 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
@@ -59,13 +61,25 @@ 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,27 @@ 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 });

package/dist/core/types.d.ts

@@ -203,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,6 +47,12 @@ 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
@@ -55,7 +61,7 @@ om(hostOmName(name, file))
     try {
         // 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;
+        return await action(resolved).result;
     }
     catch (e) {
         if (e instanceof Error && /no active om\(\) run/.test(e.message)) {

package/dist/output/writers/NodeLogWriter.js

@@ -39,9 +39,9 @@ const legend = [
     "#",
     "# ── legend ──────────────────────────────────────────────────────────",
     "#   [n]              global sequence — the merge/order key across every .log",
-    "#   indented rows    a child action's milestones, bubbled up here",
+    "#   launch ACTION_RUN(id) · → · ….log   a child started — open that file for its full output",
+    "#   indented rows    a child action's milestones, bubbled up here (one level under launches)",
     "#   name [tags]      the action and its tags   ·   defined …  where its code lives",
-    "#   launch · → ….log a child started — open that file for its full output",
     "#   ⚡ event   ✓ done ok   ⊘ cancelled   ✗ failed   ⊨/⊭ assert pass/fail   📸 snapshot   ▪ output",
 ];
 const stamp = (ms) => (ms ? new Date(ms).toISOString() : "-");

package/dist/output/writers/entryLine.js

@@ -6,10 +6,20 @@ import { label } from "../../foundation/ActionRef.js";
  * the child by its {@link label} (name + tags) via `refOf`; everything else keeps its
  * `source` (proc name, `console`, …).
  */
-export const entryLine = (e, refOf) => {
-    // Bubbled child rows are nested a level in — the whole row, `[seq]` included.
-    const indent = e.level === "child" ? "    " : "";
-    return `${indent}[${e.sequence}] ${bodyOf(e, refOf)}`;
+export const entryLine = (e, refOf) => `${indentOf(e)}[${e.sequence}] ${bodyOf(e, refOf)}`;
+/**
+ * Bubbled child rows are nested in — the whole row, `[seq]` included. The launch pointer
+ * sits one level in; the child's own milestones sit one level deeper, under their launch.
+ */
+const indentOf = (e) => {
+    if (e.level !== "child")
+        return "";
+    return e.source === "launch" ? "    " : "        ";
+};
+/** `→ <id> · <logfile> · …` → `ACTION_RUN(<id>) · → · <logfile> · …`, so a launch stands out. */
+const launchBody = (message) => {
+    const [head = "", ...rest] = message.replace(/^→\s*/, "").split(" · ");
+    return [`ACTION_RUN(${head})`, "→", ...rest].join(" · ");
 };
 const bodyOf = (e, refOf) => {
     switch (e.level) {
@@ -28,11 +38,11 @@ const bodyOf = (e, refOf) => {
             // output. (Cancellation no longer logs at this level — it's a clean stop.)
             return e.source === "error" ? `✗ ${e.message}` : `▪ ${e.message}`;
         case "child": {
-            // A bubbled child line (indented at the row level by `entryLine`). The launch pointer
-            // (`source === "launch"`) keeps its `→ id · logfile` message; a milestone names the
-            // child by its label (name + tags) via `refOf`.
+            // A bubbled child line (indented at the row level by `indentOf`). The launch pointer
+            // (`source === "launch"`) reads `launch ACTION_RUN(id) · → · logfile`; a milestone
+            // names the child by its label (name + tags) via `refOf`.
             if (e.source === "launch")
-                return `${e.source} · ${e.message}`;
+                return `${e.source} ${launchBody(e.message)}`;
             const ref = refOf?.(e.source);
             return `${ref ? label(ref) : e.source} · ${e.message}`;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "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",