omkit 0.4.8 → 0.8.0

package/dist/mcp/runs.js

@@ -0,0 +1,60 @@
+import { newUuid, shortId } from "../foundation/ids.js";
+/**
+ * How many log entries a live run keeps for `tail_run`. A watch-mode om can emit for
+ * hours, so the buffer is bounded and the oldest entries are dropped; `raw.jsonl` on disk
+ * remains the complete record, and a settled run is read from there instead.
+ */
+const BUFFER_LIMIT = 5000;
+/**
+ * Every run this server started, live or settled.
+ *
+ * Runs are kept after settling so a client that started one can still ask what happened
+ * without knowing its folder — the dated folder only becomes knowable once the child has
+ * created it, which is why the tools key on a `runId` at all.
+ */
+export class RunRegistry {
+    runs = new Map();
+    /**
+     * Take ownership of a session. Subscription happens here, not at the call site, because
+     * `session.on("log")` must be attached before the first entry arrives — a tail that
+     * starts at the tool boundary has already missed the run's opening lines.
+     */
+    start(name, folderName, session) {
+        const run = {
+            id: shortId(newUuid()),
+            name,
+            folderName,
+            session,
+            startedAt: Date.now(),
+            status: "running",
+            entries: [],
+            dropped: 0,
+        };
+        session.on("log", (entry) => {
+            run.entries.push(entry);
+            if (run.entries.length > BUFFER_LIMIT) {
+                run.entries.splice(0, run.entries.length - BUFFER_LIMIT);
+                run.dropped = run.entries[0].sequence;
+            }
+        });
+        void session.result.then((verdict) => {
+            run.status = "settled";
+            run.verdict = verdict;
+        });
+        this.runs.set(run.id, run);
+        return run;
+    }
+    get(id) {
+        return this.runs.get(id);
+    }
+    all() {
+        return [...this.runs.values()];
+    }
+    /** Cancel every live run — the server is going away and its children must not outlive it. */
+    cancelAll() {
+        for (const run of this.runs.values()) {
+            if (run.status === "running")
+                run.session.cancel();
+        }
+    }
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,19 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { OmkitClient } from "../client/index.ts";
+export interface McpServerOptions {
+    /** The engine every omkit frontend goes through — the MCP server is the third one. */
+    readonly client: OmkitClient;
+    /** Project root: run folders resolve under `<root>/logs`. */
+    readonly root: string;
+}
+/**
+ * Build the server without binding a transport, so tests can connect it to an in-memory
+ * pair and a real launch can hand it stdio. Registration is assembly only: what each tool
+ * and resource does lives in its own module.
+ */
+export declare function createMcpServer(opts: McpServerOptions): McpServer;
+/**
+ * Bind the server to stdio and serve until the client disconnects. Nothing on this path
+ * may write to stdout: it *is* the JSON-RPC stream. Diagnostics go to stderr.
+ */
+export declare function startMcpServer(opts: McpServerOptions): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,38 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools.js";
+import { registerResources } from "./resources.js";
+import { RunRegistry } from "./runs.js";
+/**
+ * Kept in step with package.json by hand. It is only the version this server reports to a
+ * client in `initialize`, so drifting is cosmetic — but bump both together.
+ */
+const VERSION = "0.7.0";
+/**
+ * Build the server without binding a transport, so tests can connect it to an in-memory
+ * pair and a real launch can hand it stdio. Registration is assembly only: what each tool
+ * and resource does lives in its own module.
+ */
+export function createMcpServer(opts) {
+    const server = new McpServer({ name: "omkit", version: VERSION }, { capabilities: { tools: {}, resources: {} } });
+    const runs = new RunRegistry();
+    registerTools(server, { client: opts.client, root: opts.root, runs });
+    registerResources(server, { root: opts.root });
+    // The client hung up. Its runs are children of this process and must not outlive it.
+    // Chain rather than assign: `onclose` is a single slot on the SDK's Protocol base, so a
+    // bare assignment would silently drop whatever the SDK (or a future us) put there.
+    const previousOnClose = server.server.onclose;
+    server.server.onclose = () => {
+        runs.cancelAll();
+        previousOnClose?.();
+    };
+    return server;
+}
+/**
+ * Bind the server to stdio and serve until the client disconnects. Nothing on this path
+ * may write to stdout: it *is* the JSON-RPC stream. Diagnostics go to stderr.
+ */
+export async function startMcpServer(opts) {
+    const server = createMcpServer(opts);
+    await server.connect(new StdioServerTransport());
+}

package/dist/mcp/tail.d.ts

@@ -0,0 +1,37 @@
+import type { LogEntry } from "../foundation/LogEntry.ts";
+export interface TailPage {
+    readonly entries: LogEntry[];
+    /** Pass this back as `cursor` to continue where this page stopped. */
+    readonly nextCursor: number;
+    /** The oldest sequence still available, when the live buffer has dropped older lines. */
+    readonly dropped: number;
+}
+/**
+ * A page from a live run's buffer. `sequence` is the run-global monotonic key the log
+ * store stamps, so it doubles as the cursor with nothing extra to track.
+ */
+export declare function tailLive(run: {
+    entries: readonly LogEntry[];
+    dropped: number;
+}, cursor: number, limit: number): TailPage;
+/**
+ * A page from a settled run's `raw.jsonl` — the complete record, which the bounded live
+ * buffer is not. Read whole and filtered: run logs are bounded by the run, and a streaming
+ * reader would buy little for a lot of machinery.
+ *
+ * An unparseable line is skipped rather than fatal: `raw.jsonl` is appended to during the
+ * run, so a tail can catch a line mid-write.
+ */
+export declare function tailFile(folder: string, cursor: number, limit: number): TailPage;
+/**
+ * Trim an entry to what a client can act on. `nodeId` is an internal attribution key and
+ * says nothing a reader can use — `path` already names the node readably.
+ */
+export declare function publicEntry(e: LogEntry): {
+    sequence: number;
+    ts: number;
+    path: string;
+    level: string;
+    source: string;
+    message: string;
+};

package/dist/mcp/tail.js

@@ -0,0 +1,64 @@
+import fs from "node:fs";
+import path from "node:path";
+const page = (entries, cursor, dropped) => ({
+    entries,
+    nextCursor: entries.length ? entries[entries.length - 1].sequence : cursor,
+    dropped,
+});
+/**
+ * A page from a live run's buffer. `sequence` is the run-global monotonic key the log
+ * store stamps, so it doubles as the cursor with nothing extra to track.
+ */
+export function tailLive(run, cursor, limit) {
+    const after = run.entries.filter((e) => e.sequence > cursor).slice(0, limit);
+    return page(after, cursor, run.dropped);
+}
+/**
+ * A page from a settled run's `raw.jsonl` — the complete record, which the bounded live
+ * buffer is not. Read whole and filtered: run logs are bounded by the run, and a streaming
+ * reader would buy little for a lot of machinery.
+ *
+ * An unparseable line is skipped rather than fatal: `raw.jsonl` is appended to during the
+ * run, so a tail can catch a line mid-write.
+ */
+export function tailFile(folder, cursor, limit) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(folder, "raw.jsonl"), "utf8");
+    }
+    catch {
+        return { entries: [], nextCursor: cursor, dropped: 0 };
+    }
+    const entries = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (typeof parsed.sequence !== "number" || parsed.sequence <= cursor)
+            continue;
+        entries.push(parsed);
+        if (entries.length >= limit)
+            break;
+    }
+    return page(entries, cursor, 0);
+}
+/**
+ * Trim an entry to what a client can act on. `nodeId` is an internal attribution key and
+ * says nothing a reader can use — `path` already names the node readably.
+ */
+export function publicEntry(e) {
+    return {
+        sequence: e.sequence,
+        ts: e.ts,
+        path: e.path,
+        level: e.level,
+        source: e.source,
+        message: e.message,
+    };
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,54 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RunRegistry } from "./runs.ts";
+import type { OmkitClient } from "../client/index.ts";
+import type { RegistrationSet } from "../client/registry.ts";
+/** Everything the tools need. Passed in so the server stays assembly and these stay logic. */
+export interface ToolContext {
+    readonly client: OmkitClient;
+    /** Project root — run folders resolve under `<root>/logs`. */
+    readonly root: string;
+    /** Every run this server started, live or settled. */
+    readonly runs: RunRegistry;
+}
+/**
+ * One entry in `list_oms`: an om or an exposed action, flattened into a single list so a
+ * client has one place to look for "what can I call". `kind` says which it is, because an
+ * action's caveats differ — see the action-host notes in the spec.
+ */
+export interface ToolEntry {
+    readonly kind: "om" | "action";
+    readonly name: string;
+    readonly mode: "settling" | "long-lived";
+    readonly file: string;
+    readonly summary?: string;
+    /** `<name>-<hash8>` — where this entry's runs land under `logs/`. Oms only. */
+    readonly folderName?: string;
+    /** The exported binding an action-backed tool is invoked through. Actions only. */
+    readonly exportName?: string;
+    readonly inputSchema?: Record<string, unknown>;
+    /** Set when the entry cannot be called, with the reason. */
+    readonly unavailable?: string;
+}
+/** Flatten a registration set into the entries a client may call, dropping the rest. */
+export declare function toEntries(set: RegistrationSet): ToolEntry[];
+/**
+ * Every tool result carries a text block as well as `structuredContent`: a client that
+ * ignores structured output still sees the answer. Return types are inferred so they stay
+ * assignable to the SDK's `CallToolResult` union — annotating them as tuples does not.
+ */
+export declare function both<T>(structuredContent: T): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: T;
+};
+/** A tool failure, in MCP's shape: a message the model can act on, not a thrown stack. */
+export declare function toolError(message: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};
+export declare function registerTools(server: McpServer, ctx: ToolContext): void;

package/dist/mcp/tools.js

@@ -0,0 +1,374 @@
+import path from "node:path";
+import { z } from "zod";
+import { checkArgs } from "./validate.js";
+import { readVerdict, readVerdictAt } from "./verdict.js";
+import { resolveRunFolder, runFileLinks } from "./resources.js";
+import { hostFile, hostFolderName } from "./action-identity.js";
+import { publicEntry, tailFile, tailLive } from "./tail.js";
+import { attachElicitation, attachProgress } from "./progress.js";
+/**
+ * How long a "settling" run gets before the server gives up on it. Generous: a real smoke
+ * suite can take minutes, and a backstop that fires early is worse than none.
+ *
+ * This is a server-side safety net, not a promise the call will be awaited — MCP client
+ * timeouts are client-side and typically far shorter. Anything routinely over about a
+ * minute belongs in `start_om`.
+ */
+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;
+/**
+ * Wait for a run to settle, or cancel it and report that it did not.
+ *
+ * `mode` is the author's claim, and a wrong claim would otherwise hang the tool call until
+ * the *client* times out — which surfaces as a transport error with no run folder and
+ * nothing to read. Cancelling instead turns the mistake into a message that names it, and
+ * the run still writes its folder on the way down, so there is something to inspect.
+ */
+async function settleWithin(session, ms) {
+    let timer;
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(undefined), ms);
+    });
+    try {
+        const winner = await Promise.race([session.result, expired]);
+        if (winner)
+            return winner;
+        session.cancel();
+        // Give teardown a chance to finish writing before reporting; the run is already lost
+        // either way, so a slow teardown must not extend the wait indefinitely.
+        await Promise.race([
+            session.result,
+            new Promise((resolve) => setTimeout(resolve, TEARDOWN_GRACE_MS)),
+        ]);
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const entryShape = {
+    kind: z.enum(["om", "action"]),
+    name: z.string(),
+    mode: z.enum(["settling", "long-lived"]),
+    file: z.string(),
+    summary: z.string().optional(),
+    folderName: z.string().optional(),
+    exportName: z.string().optional(),
+    inputSchema: z.record(z.string(), z.unknown()).optional(),
+    unavailable: z.string().optional(),
+};
+/**
+ * The process-lifetime registry cache. Discovery forks a child and imports user code, so
+ * it is far too expensive to repeat per tool call; a client that has changed a file asks
+ * for `refresh: true`. (Watching for changes and emitting `tools/list_changed` is
+ * deferred — the tool list itself never changes, only what `list_oms` returns.)
+ */
+function createRegistryCache(client) {
+    let cached;
+    return (refresh = false) => {
+        if (refresh || !cached)
+            cached = client.discoverRegistrations();
+        return cached;
+    };
+}
+/** Flatten a registration set into the entries a client may call, dropping the rest. */
+export function toEntries(set) {
+    const entries = [];
+    for (const om of set.oms) {
+        if (!om.mcp)
+            continue; // exposure is opt-in
+        entries.push({
+            kind: "om",
+            name: om.name,
+            mode: om.mcp.mode,
+            file: om.file,
+            folderName: om.folderName,
+            ...(om.summary ? { summary: om.summary } : {}),
+            ...(om.inputSchema ? { inputSchema: om.inputSchema } : {}),
+            ...(om.unavailable ? { unavailable: om.unavailable } : {}),
+        });
+    }
+    for (const a of set.actions) {
+        if (!a.mcp)
+            continue;
+        entries.push({
+            kind: "action",
+            name: a.name,
+            mode: a.mcp.mode,
+            file: a.file,
+            exportName: a.exportName,
+            ...(a.summary ? { summary: a.summary } : {}),
+            ...(a.inputSchema ? { inputSchema: a.inputSchema } : {}),
+            ...(a.unavailable ? { unavailable: a.unavailable } : {}),
+        });
+    }
+    return entries;
+}
+/**
+ * Every tool result carries a text block as well as `structuredContent`: a client that
+ * ignores structured output still sees the answer. Return types are inferred so they stay
+ * assignable to the SDK's `CallToolResult` union — annotating them as tuples does not.
+ */
+export function both(structuredContent) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(structuredContent, null, 2) }],
+        structuredContent,
+    };
+}
+/** A tool failure, in MCP's shape: a message the model can act on, not a thrown stack. */
+export function toolError(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+export function registerTools(server, ctx) {
+    const registry = createRegistryCache(ctx.client);
+    server.registerTool("list_oms", {
+        title: "List runnable omkit oms and actions",
+        description: "Lists everything this project exposes over MCP: its name, what it does, whether " +
+            "it settles on its own, and the JSON Schema for its arguments. Call this before " +
+            "run_om or start_om — their `args` are not described by their own input schemas.",
+        inputSchema: {
+            refresh: z
+                .boolean()
+                .optional()
+                .describe("Re-import the project's files. Use after editing an om or action."),
+        },
+        outputSchema: {
+            entries: z.array(z.object(entryShape)),
+            warnings: z.array(z.string()),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ refresh }) => {
+        const set = await registry(refresh);
+        return both({ entries: toEntries(set), warnings: set.warnings });
+    });
+    /** Find an exposed entry by name. Oms win a collision — they are the primary surface. */
+    const findEntry = async (name) => {
+        const entries = toEntries(await registry());
+        return (entries.find((e) => e.kind === "om" && e.name === name) ??
+            entries.find((e) => e.name === name));
+    };
+    const notRunnable = (name, entry) => {
+        if (!entry)
+            return `no om or action named "${name}" is exposed. Call list_oms.`;
+        if (entry.unavailable)
+            return `"${name}" is unavailable: ${entry.unavailable}`;
+        return undefined;
+    };
+    /**
+     * Launch an entry as a supervised run.
+     *
+     * cwd is the project **root**, not the om file's directory. `omkit run` uses the file's
+     * directory, but resources here resolve under `<root>/logs` — a run launched elsewhere
+     * writes its folder somewhere this same server cannot serve, so `get_run`'s resource
+     * links would point at nothing.
+     */
+    const launch = (entry, args) => {
+        // An action cannot run standalone, so an action-backed tool forks omkit's shipped host
+        // om instead of the action's own file — which defines no om at all.
+        const isAction = entry.kind === "action";
+        const file = isAction ? hostFile() : entry.file;
+        const env = isAction
+            ? {
+                OMKIT_ACTION_FILE: entry.file,
+                OMKIT_ACTION_NAME: entry.name,
+                OMKIT_ACTION_EXPORT: entry.exportName,
+                OMKIT_ACTION_ARGS: JSON.stringify(args),
+            }
+            : { OMKIT_ARGS: JSON.stringify(args) };
+        const folderName = isAction
+            ? hostFolderName(entry.name, entry.file)
+            : (entry.folderName ?? entry.name);
+        return ctx.runs.start(entry.name, folderName, ctx.client.run(file, { cwd: ctx.root, env }));
+    };
+    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.",
+        inputSchema: {
+            name: z.string().describe("The om or action name, as reported by list_oms."),
+            args: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Arguments matching the entry's inputSchema from list_oms."),
+            settleTimeoutMs: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("How long to wait for the run to settle before giving up. Default 10 minutes."),
+        },
+        outputSchema: {
+            ok: z.boolean(),
+            folder: z.string(),
+            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()),
+        },
+        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 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.
+        attachProgress(run.session, extra);
+        attachElicitation(server, run.session);
+        const timeout = settleTimeoutMs ?? SETTLE_TIMEOUT_MS;
+        const settled = await settleWithin(run.session, timeout);
+        if (!settled) {
+            return toolError(`"${name}" is declared settling but did not settle within ${timeout}ms, so it ` +
+                `was cancelled. If it is meant to stay up, declare ` +
+                `.mcp({ mode: "long-lived" }) and start it with start_om.`);
+        }
+        return both(await readVerdict(settled));
+    });
+    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.",
+        inputSchema: {
+            name: z.string().describe("The om or action name, as reported by list_oms."),
+            args: z.record(z.string(), z.unknown()).optional(),
+        },
+        outputSchema: {
+            runId: z.string(),
+            name: z.string(),
+            // The dated run folder does not exist yet — this is the folder *family*.
+            folderName: z.string(),
+            mode: z.enum(["settling", "long-lived"]),
+        },
+        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"));
+        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);
+        return both({
+            runId: run.id,
+            name: entry.name,
+            folderName: run.folderName,
+            mode: entry.mode,
+        });
+    });
+    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/.",
+        inputSchema: { run: z.string() },
+        outputSchema: {
+            status: z.enum(["running", "settled"]),
+            name: z.string(),
+            folder: z.string(),
+            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(),
+        },
+        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: "" });
+        }
+        // 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) {
+            return toolError(`no run "${run}" — pass a runId from start_om, or a folder under logs/.`);
+        }
+        const name = live?.name ?? path.basename(path.resolve(folder, "../.."));
+        const verdict = live?.verdict ? await readVerdict(live.verdict) : await readVerdictAt(folder);
+        // Links, not inlined content: `raw.jsonl` on a long run is megabytes, and a model
+        // should read only what it turns out to need.
+        const structuredContent = { status: "settled", name, ...verdict };
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(structuredContent, null, 2) },
+                ...runFileLinks(ctx.root, folder),
+            ],
+            structuredContent,
+        };
+    });
+    server.registerTool("cancel_run", {
+        title: "Cancel a running om",
+        description: "Tears a run down gracefully. It still finishes writing its run folder, so the " +
+            "logs and verdict of a cancelled run stay readable afterwards.",
+        inputSchema: { runId: z.string() },
+        outputSchema: { runId: z.string(), cancelled: z.boolean() },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+    }, async ({ runId }) => {
+        const live = ctx.runs.get(runId);
+        if (!live)
+            return toolError(`no run "${runId}".`);
+        // Already settled is not an error — cancelling twice, or cancelling something that
+        // finished on its own, is a reasonable thing for a client to do.
+        if (live.status === "settled")
+            return both({ runId, cancelled: false });
+        live.session.cancel();
+        return both({ runId, cancelled: true });
+    });
+    server.registerTool("tail_run", {
+        title: "Read a run's log from a cursor",
+        description: "Returns log lines after `cursor`, from the live run while it is going and from " +
+            "its raw.jsonl once it has settled. Pass the returned nextCursor back to continue. " +
+            "`run` is a runId from start_om, or a run folder path under logs/.",
+        inputSchema: {
+            run: z.string(),
+            cursor: z.number().int().nonnegative().optional().describe("0, or the last nextCursor."),
+            limit: z.number().int().positive().max(1000).optional().describe("Default 200."),
+        },
+        outputSchema: {
+            entries: z.array(z.object({
+                sequence: z.number(),
+                ts: z.number(),
+                path: z.string(),
+                level: z.string(),
+                source: z.string(),
+                message: z.string(),
+            })),
+            nextCursor: z.number(),
+            dropped: z.number(),
+            status: z.enum(["running", "settled"]),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ run, cursor = 0, limit = 200 }) => {
+        const live = ctx.runs.get(run);
+        if (live?.status === "running") {
+            const tail = tailLive(live, cursor, limit);
+            return both({
+                ...tail,
+                entries: tail.entries.map(publicEntry),
+                status: "running",
+            });
+        }
+        const folder = live?.verdict?.folder ?? resolveRunFolder(ctx.root, run);
+        if (!folder) {
+            return toolError(`no run "${run}" — pass a runId from start_om, or a folder under logs/.`);
+        }
+        const tail = tailFile(folder, cursor, limit);
+        return both({ ...tail, entries: tail.entries.map(publicEntry), status: "settled" });
+    });
+}

package/dist/mcp/validate.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A shallow check of a tool call's `args` against the declared JSON Schema: required
+ * fields present, top-level primitives the right type. Deliberately not a validator.
+ *
+ * The real schema is a zod object living in the om's own process; the server holds only
+ * its JSON Schema projection. `resolveArgs` is what actually validates, fills defaults,
+ * and — when something is still missing — prompts, which reaches the client as an
+ * elicitation. This check exists so an obviously-wrong call fails immediately with a
+ * message naming every problem, instead of spending a fork to find out.
+ */
+type JsonSchemaLike = Record<string, unknown> | undefined;
+/** Every problem found, in schema order. Empty means "worth spawning". */
+export declare function checkArgs(schema: JsonSchemaLike, args: unknown): string[];
+export {};