omkit 0.4.7 → 0.8.0

package/dist/mcp/action-identity.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The name the host om runs under: `<action>@<hash8 of the action's defining file>`.
+ *
+ * Shared by the host (which passes it to `om(...)`) and the server (which has to predict
+ * the resulting folder before the run exists). One function so the two cannot drift —
+ * they are the same rule applied from opposite sides of a fork.
+ */
+export declare function hostOmName(action: string, actionFile: string): string;
+/**
+ * Absolute path of the shipped action host, with the extension this build actually uses —
+ * `.ts` under tsx and vitest, `.js` once compiled. `rewriteRelativeImportExtensions`
+ * rewrites import specifiers; this path is data (a fork target), so it does not.
+ */
+export declare function hostFile(): string;
+/**
+ * Where a hosted action's runs land: `<fsSafe(hostName)>-<hash8>`.
+ *
+ * Derived rather than observed, because `start_om` has to answer before the child has
+ * created anything. It reproduces `RunFolder.name()` exactly — including `fsSafe`, which
+ * collapses the `@` to a `-`, so the folder reads `seed-a1b2c3d4-<hash8>`. A test pins
+ * this against a real run: if the derivation ever drifts from the runtime, it fails.
+ */
+export declare function hostFolderName(action: string, actionFile: string): string;

package/dist/mcp/action-identity.js

@@ -0,0 +1,35 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { omHash } from "../foundation/ids.js";
+import { fsSafe } from "../foundation/fsSafe.js";
+/**
+ * The name the host om runs under: `<action>@<hash8 of the action's defining file>`.
+ *
+ * Shared by the host (which passes it to `om(...)`) and the server (which has to predict
+ * the resulting folder before the run exists). One function so the two cannot drift —
+ * they are the same rule applied from opposite sides of a fork.
+ */
+export function hostOmName(action, actionFile) {
+    return `${action}@${omHash(action, actionFile)}`;
+}
+/**
+ * Absolute path of the shipped action host, with the extension this build actually uses —
+ * `.ts` under tsx and vitest, `.js` once compiled. `rewriteRelativeImportExtensions`
+ * rewrites import specifiers; this path is data (a fork target), so it does not.
+ */
+export function hostFile() {
+    const here = fileURLToPath(import.meta.url);
+    return path.join(path.dirname(here), `action-host${path.extname(here)}`);
+}
+/**
+ * Where a hosted action's runs land: `<fsSafe(hostName)>-<hash8>`.
+ *
+ * Derived rather than observed, because `start_om` has to answer before the child has
+ * created anything. It reproduces `RunFolder.name()` exactly — including `fsSafe`, which
+ * collapses the `@` to a `-`, so the folder reads `seed-a1b2c3d4-<hash8>`. A test pins
+ * this against a real run: if the derivation ever drifts from the runtime, it fails.
+ */
+export function hostFolderName(action, actionFile) {
+    const hostName = hostOmName(action, actionFile);
+    return `${fsSafe(hostName)}-${omHash(hostName, hostFile())}`;
+}

package/dist/mcp/progress.d.ts

@@ -0,0 +1,61 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LogEntry } from "../foundation/LogEntry.ts";
+import type { PromptSpec } from "../core/interaction.ts";
+import type { RunSession } from "../client/types.ts";
+export declare function isMilestone(entry: LogEntry): boolean;
+/** The slice of the SDK's request context this module needs — narrow, so tests can fake it. */
+export interface ProgressExtra {
+    readonly signal: AbortSignal;
+    readonly _meta?: {
+        progressToken?: string | number;
+    };
+    readonly sendNotification: (n: {
+        method: "notifications/progress";
+        params: {
+            progressToken: string | number;
+            progress: number;
+            message?: string;
+        };
+    }) => Promise<void>;
+}
+/**
+ * Wire a live run to the request that started it: milestones become progress
+ * notifications, and the client cancelling the request tears the run down.
+ *
+ * `progress` is the log store's run-global sequence, which is monotonic by construction —
+ * exactly what the spec requires, with no counter to keep. `total` is omitted, which the
+ * spec permits, because a run does not know how many steps it has left.
+ *
+ * Progress is a courtesy, not a deadline extension: whether a client resets its timeout on
+ * progress is implementation-dependent, so a long run still belongs in `start_om`.
+ */
+export declare function attachProgress(session: RunSession, extra: ProgressExtra): void;
+/** MCP's elicitation schema: top-level primitives only, no nesting. */
+export interface RequestedSchema {
+    type: "object";
+    properties: Record<string, {
+        type: "string";
+        enum?: string[];
+        description: string;
+    }>;
+    required: string[];
+}
+/**
+ * Turn one of omkit's prompt specs into an elicitation request. All three kinds become a
+ * single `value` string: a choice narrows it with `enum` so the client cannot answer
+ * invalidly, and a multiline prompt stays a string because MCP's restricted schema has
+ * nowhere to say "several lines".
+ */
+export declare function toRequestedSchema(spec: PromptSpec): RequestedSchema;
+/**
+ * Forward the run's prompts to the client as elicitations, and its answers back.
+ *
+ * prompt.ts already describes its supervisor as "whoever owns the terminal (Ink app / MCP
+ * client)" — this is that. A declined or cancelled elicitation answers with the prompt's
+ * own default rather than leaving the run to time out three times over: the run has to
+ * make progress either way, and the default is what a timeout would have produced.
+ *
+ * `promptDone` means the child gave up first; the in-flight elicitation is aborted so the
+ * client's dialog does not linger with nothing behind it.
+ */
+export declare function attachElicitation(server: McpServer, session: RunSession): void;

package/dist/mcp/progress.js

@@ -0,0 +1,92 @@
+/**
+ * Which log levels count as "something happened". Forwarding every entry would turn a
+ * chatty run into a notification flood; these are the levels that mark a step, an event,
+ * an assertion, a failure, or a file — the same shape the terminal's live renderer treats
+ * as worth showing.
+ */
+const MILESTONE_LEVELS = new Set(["run", "event", "assert", "error", "artifact", "child"]);
+export function isMilestone(entry) {
+    return MILESTONE_LEVELS.has(entry.level);
+}
+/**
+ * Wire a live run to the request that started it: milestones become progress
+ * notifications, and the client cancelling the request tears the run down.
+ *
+ * `progress` is the log store's run-global sequence, which is monotonic by construction —
+ * exactly what the spec requires, with no counter to keep. `total` is omitted, which the
+ * spec permits, because a run does not know how many steps it has left.
+ *
+ * Progress is a courtesy, not a deadline extension: whether a client resets its timeout on
+ * progress is implementation-dependent, so a long run still belongs in `start_om`.
+ */
+export function attachProgress(session, extra) {
+    const token = extra._meta?.progressToken;
+    if (token !== undefined) {
+        session.on("log", (entry) => {
+            if (!isMilestone(entry))
+                return;
+            void extra
+                .sendNotification({
+                method: "notifications/progress",
+                params: { progressToken: token, progress: entry.sequence, message: entry.message },
+            })
+                .catch(() => {
+                // The client went away mid-run. It is cancelled through `signal` anyway; a
+                // rejected notification must not fault the run itself.
+            });
+        });
+    }
+    extra.signal.addEventListener("abort", () => session.cancel(), { once: true });
+}
+/**
+ * Turn one of omkit's prompt specs into an elicitation request. All three kinds become a
+ * single `value` string: a choice narrows it with `enum` so the client cannot answer
+ * invalidly, and a multiline prompt stays a string because MCP's restricted schema has
+ * nowhere to say "several lines".
+ */
+export function toRequestedSchema(spec) {
+    const description = spec.hint ? `${spec.message} — ${spec.hint}` : spec.message;
+    const value = spec.kind === "choice" && spec.choices
+        ? { type: "string", enum: spec.choices.map((c) => c.value), description }
+        : { type: "string", description };
+    return { type: "object", properties: { value }, required: ["value"] };
+}
+/**
+ * Forward the run's prompts to the client as elicitations, and its answers back.
+ *
+ * prompt.ts already describes its supervisor as "whoever owns the terminal (Ink app / MCP
+ * client)" — this is that. A declined or cancelled elicitation answers with the prompt's
+ * own default rather than leaving the run to time out three times over: the run has to
+ * make progress either way, and the default is what a timeout would have produced.
+ *
+ * `promptDone` means the child gave up first; the in-flight elicitation is aborted so the
+ * client's dialog does not linger with nothing behind it.
+ */
+export function attachElicitation(server, session) {
+    const pending = new Map();
+    session.on("promptDone", (id) => {
+        pending.get(id)?.abort();
+        pending.delete(id);
+    });
+    session.on("prompt", (request) => {
+        const controller = new AbortController();
+        pending.set(request.id, controller);
+        void (async () => {
+            try {
+                const result = await server.server.elicitInput({ message: request.spec.message, requestedSchema: toRequestedSchema(request.spec) }, { signal: controller.signal });
+                const answer = result.content?.value;
+                const value = result.action === "accept" && typeof answer === "string" ? answer : request.spec.default;
+                session.answer(request.id, value, result.action === "accept" ? "elicitation" : "default");
+            }
+            catch {
+                // Aborted, or a client with no elicitation capability. Either way the run must not
+                // hang on us: hand it the default and let it carry on.
+                if (!controller.signal.aborted)
+                    session.answer(request.id, request.spec.default, "default");
+            }
+            finally {
+                pending.delete(request.id);
+            }
+        })();
+    });
+}

package/dist/mcp/resources.d.ts

@@ -0,0 +1,55 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function mimeOf(file: string): string;
+/**
+ * Resolve a path and refuse anything that is not strictly inside `<root>/logs`.
+ *
+ * URIs are untrusted input — a model can propose any string — so this runs on every read,
+ * not just at the template. Two checks, because `..` and a symlink escape by different
+ * routes: the lexical one catches `logs/../secret`, and the realpath one catches
+ * `logs/link → /etc`. `logs/` itself is refused: it is the root, not a run.
+ */
+export declare function resolveUnderLogs(root: string, target: string): string | undefined;
+/** A run folder the caller named directly (a path from `get_run`, or one a client kept). */
+export declare function resolveRunFolder(root: string, candidate: string): string | undefined;
+/**
+ * The newest run of one om. Folder names are `<date>/<time>` with zero-padded, fixed-width
+ * components (`2026-08-04/11-30-00`), so lexical sort is chronological sort — no parsing,
+ * and no dependence on filesystem mtime.
+ *
+ * This is what the run-folder-identity constraint is *for*: "a script or an assistant can
+ * always find the latest run of X without parsing scrollback".
+ */
+export declare function latestRun(root: string, folderName: string): string | undefined;
+export interface RunFileRead {
+    readonly path: string;
+    readonly mimeType: string;
+    readonly text?: string;
+    readonly blob?: string;
+}
+/** Read one file from a run folder, confined, size-capped, and typed by extension. */
+export declare function readRunFile(root: string, segments: string[]): RunFileRead | undefined;
+export interface ResourceLink {
+    readonly type: "resource_link";
+    readonly uri: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly mimeType: string;
+}
+/**
+ * The run's files as `resource_link` blocks rather than inlined content, so a model reads
+ * only what it needs — `raw.jsonl` on a long run is megabytes. Curated artifacts come
+ * first, carrying the name and description the om gave them; the rest of the folder
+ * follows, unlabelled. Curation raises signal; it does not gate access.
+ */
+export declare function runFileLinks(root: string, folder: string): ResourceLink[];
+/**
+ * Publish the two templates. Read-only by construction: there is no write path here, and
+ * no way to delete a run folder through MCP.
+ *
+ * `list` is `undefined` deliberately — enumerating every file of every historical run
+ * would be a large, mostly-useless listing. `get_run` returns resource links for the run a
+ * client actually asked about, which is the path that matters.
+ */
+export declare function registerResources(server: McpServer, opts: {
+    root: string;
+}): void;

package/dist/mcp/resources.js

@@ -0,0 +1,208 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+/** Files above this are truncated (text) or described rather than inlined (binary). */
+const MAX_BYTES = 256 * 1024;
+const MIME_BY_EXT = {
+    ".json": "application/json",
+    ".jsonl": "application/x-ndjson",
+    ".log": "text/plain",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".html": "text/html",
+    ".csv": "text/csv",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".pdf": "application/pdf",
+};
+const TEXT_MIME = /^(text\/|application\/(json|x-ndjson|xml))/;
+export function mimeOf(file) {
+    return MIME_BY_EXT[path.extname(file).toLowerCase()] ?? "application/octet-stream";
+}
+/** True when `candidate` sits strictly inside `root` — not equal to it, not above it. */
+function inside(root, candidate) {
+    const rel = path.relative(root, candidate);
+    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+/**
+ * Resolve a path and refuse anything that is not strictly inside `<root>/logs`.
+ *
+ * URIs are untrusted input — a model can propose any string — so this runs on every read,
+ * not just at the template. Two checks, because `..` and a symlink escape by different
+ * routes: the lexical one catches `logs/../secret`, and the realpath one catches
+ * `logs/link → /etc`. `logs/` itself is refused: it is the root, not a run.
+ */
+export function resolveUnderLogs(root, target) {
+    const logs = path.resolve(root, "logs");
+    if (!inside(logs, path.resolve(target)))
+        return undefined;
+    try {
+        const realLogs = fs.realpathSync.native(logs);
+        const real = fs.realpathSync.native(path.resolve(target));
+        return inside(realLogs, real) ? real : undefined;
+    }
+    catch {
+        return undefined; // does not exist — nothing to read either way
+    }
+}
+/** A run folder the caller named directly (a path from `get_run`, or one a client kept). */
+export function resolveRunFolder(root, candidate) {
+    const resolved = resolveUnderLogs(root, candidate);
+    if (!resolved)
+        return undefined;
+    try {
+        return fs.statSync(resolved).isDirectory() ? resolved : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The newest child directory of `dir`, by name. */
+function newestChild(dir) {
+    return fs
+        .readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .sort()
+        .pop();
+}
+/**
+ * The newest run of one om. Folder names are `<date>/<time>` with zero-padded, fixed-width
+ * components (`2026-08-04/11-30-00`), so lexical sort is chronological sort — no parsing,
+ * and no dependence on filesystem mtime.
+ *
+ * This is what the run-folder-identity constraint is *for*: "a script or an assistant can
+ * always find the latest run of X without parsing scrollback".
+ */
+export function latestRun(root, folderName) {
+    const base = resolveUnderLogs(root, path.join(root, "logs", folderName));
+    if (!base)
+        return undefined;
+    try {
+        const date = newestChild(base);
+        if (!date)
+            return undefined;
+        const time = newestChild(path.join(base, date));
+        return time ? path.join(base, date, time) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read one file from a run folder, confined, size-capped, and typed by extension. */
+export function readRunFile(root, segments) {
+    const target = resolveUnderLogs(root, path.join(root, "logs", ...segments));
+    if (!target)
+        return undefined;
+    let stat;
+    try {
+        stat = fs.statSync(target);
+    }
+    catch {
+        return undefined;
+    }
+    if (!stat.isFile())
+        return undefined;
+    const mimeType = mimeOf(target);
+    if (!TEXT_MIME.test(mimeType)) {
+        // Binary is all-or-nothing: half a PNG is not a smaller PNG. Too large comes back as a
+        // plain-text explanation rather than an error — the client asked a reasonable question
+        // and deserves an answer, and a read with neither `text` nor `blob` is not a valid
+        // MCP result.
+        if (stat.size > MAX_BYTES) {
+            return {
+                path: target,
+                mimeType: "text/plain",
+                text: `${path.basename(target)} is ${stat.size} bytes, over the ${MAX_BYTES}-byte inline cap. Read it from disk at ${target}.`,
+            };
+        }
+        return { path: target, mimeType, blob: fs.readFileSync(target).toString("base64") };
+    }
+    const raw = fs.readFileSync(target, "utf8");
+    const text = stat.size > MAX_BYTES
+        ? `${raw.slice(0, MAX_BYTES)}\n\n… truncated at ${MAX_BYTES} bytes of ${stat.size}. ` +
+            `Use tail_run with a cursor to page through this run's log.`
+        : raw;
+    return { path: target, mimeType, text };
+}
+/**
+ * The run's files as `resource_link` blocks rather than inlined content, so a model reads
+ * only what it needs — `raw.jsonl` on a long run is megabytes. Curated artifacts come
+ * first, carrying the name and description the om gave them; the rest of the folder
+ * follows, unlabelled. Curation raises signal; it does not gate access.
+ */
+export function runFileLinks(root, folder) {
+    const resolved = resolveRunFolder(root, folder);
+    if (!resolved)
+        return [];
+    const logs = fs.realpathSync.native(path.resolve(root, "logs"));
+    const rel = path.relative(logs, resolved).split(path.sep);
+    const uriFor = (file) => `omkit://runs/${[...rel, file].join("/")}`;
+    let curated = [];
+    try {
+        const result = JSON.parse(fs.readFileSync(path.join(resolved, "result.json"), "utf8"));
+        curated = result.artifacts ?? [];
+    }
+    catch {
+        curated = [];
+    }
+    const links = curated.map((a) => ({
+        type: "resource_link",
+        uri: uriFor(path.basename(a.file)),
+        name: a.name,
+        ...(a.description ? { description: a.description } : {}),
+        mimeType: a.mime,
+    }));
+    const named = new Set(curated.map((a) => path.basename(a.file)));
+    for (const item of fs.readdirSync(resolved, { withFileTypes: true })) {
+        if (!item.isFile() || named.has(item.name))
+            continue;
+        links.push({
+            type: "resource_link",
+            uri: uriFor(item.name),
+            name: item.name,
+            mimeType: mimeOf(item.name),
+        });
+    }
+    return links;
+}
+/**
+ * Publish the two templates. Read-only by construction: there is no write path here, and
+ * no way to delete a run folder through MCP.
+ *
+ * `list` is `undefined` deliberately — enumerating every file of every historical run
+ * would be a large, mostly-useless listing. `get_run` returns resource links for the run a
+ * client actually asked about, which is the path that matters.
+ */
+export function registerResources(server, opts) {
+    const respond = (uri, read) => {
+        if (!read) {
+            throw new Error(`no such run file, or it is outside this project's logs/: ${uri.href}`);
+        }
+        // A resource's contents are a discriminated union — `text` or `blob`, never both as
+        // optionals — so the two shapes are built separately rather than spread conditionally.
+        const base = { uri: uri.href, mimeType: read.mimeType };
+        return {
+            contents: [
+                read.blob !== undefined ? { ...base, blob: read.blob } : { ...base, text: read.text ?? "" },
+            ],
+        };
+    };
+    server.registerResource("run-latest", new ResourceTemplate("omkit://runs/{run}/latest/{file}", { list: undefined }), {
+        title: "The newest run of one om",
+        description: "A file from the most recent run of `{run}` (the `folderName` from list_oms). Try " +
+            "main.log for the narrative, result.json for the verdict, artifacts.log for files.",
+    }, async (uri, { run, file }) => {
+        const folder = latestRun(opts.root, String(run));
+        if (!folder)
+            throw new Error(`no runs recorded for ${String(run)}`);
+        const logs = fs.realpathSync.native(path.resolve(opts.root, "logs"));
+        const rel = path.relative(logs, folder).split(path.sep);
+        return respond(uri, readRunFile(opts.root, [...rel, String(file)]));
+    });
+    server.registerResource("run-at", new ResourceTemplate("omkit://runs/{run}/{date}/{time}/{file}", { list: undefined }), { title: "A file from one specific run" }, async (uri, { run, date, time, file }) => respond(uri, readRunFile(opts.root, [run, date, time, file].map(String))));
+}

package/dist/mcp/runs.d.ts

@@ -0,0 +1,37 @@
+import type { LogEntry } from "../foundation/LogEntry.ts";
+import type { RunSession, Verdict } from "../client/types.ts";
+export interface LiveRun {
+    readonly id: string;
+    /** The om or action name the client asked for. */
+    readonly name: string;
+    /** `<name>-<hash8>` — known before the run creates its dated folder. */
+    readonly folderName: string;
+    readonly session: RunSession;
+    readonly startedAt: number;
+    status: "running" | "settled";
+    verdict?: Verdict;
+    /** The tail buffer. Entries are appended in sequence order, oldest dropped first. */
+    readonly entries: LogEntry[];
+    /** The oldest sequence still buffered, so `tail_run` can say it dropped lines. */
+    dropped: number;
+}
+/**
+ * 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 declare class RunRegistry {
+    private readonly runs;
+    /**
+     * 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: string, folderName: string, session: RunSession): LiveRun;
+    get(id: string): LiveRun | undefined;
+    all(): LiveRun[];
+    /** Cancel every live run — the server is going away and its children must not outlive it. */
+    cancelAll(): void;
+}

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;
+};