omkit 0.4.8 → 0.8.0

package/dist/foundation/canonicalPath.js

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+/**
+ * The operating system's own name for a file — the spelling every other spelling of it
+ * resolves to.
+ *
+ * Windows filesystems are case-insensitive but case-*preserving*, so `d:\repo\om.ts` and
+ * `D:\repo\om.ts` are one file with two names. That is harmless right up until something
+ * keys on the string, and omkit keys on it twice:
+ *
+ * - **Module identity.** Node's ESM loader caches by URL, so `file:///d:/…` and
+ *   `file:///D:/…` load the *same file twice* into two module instances with separate
+ *   module-level state. An action whose file resolved `"omkit"` one way cannot see the run
+ *   started by a host that resolved it the other — the symptom is a bare "no active om() run"
+ *   from a run that is demonstrably in progress.
+ * - **Run identity.** {@link import("./ids.ts").omHash} hashes the defining file's path, so
+ *   the same om launched by two differently-spelled paths writes to two different run
+ *   folders — and `logs/<name>-<hash>/` stops meaning "every run of this om".
+ *
+ * `realpathSync.native` is the OS's answer rather than ours: it fixes drive-letter case, 8.3
+ * short names, and symlinked directories in one step. Resolving symlinks is deliberate, not
+ * incidental — Node realpaths a module before caching it, so canonicalising the same way is
+ * what keeps our identity and Node's agreeing.
+ *
+ * A path that does not exist yet is returned unchanged: there is no canonical name for a file
+ * the filesystem has never seen, and guessing one would be worse than passing it through.
+ */
+export function canonicalPath(file) {
+    try {
+        return fs.realpathSync.native(file);
+    }
+    catch {
+        return file;
+    }
+}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * omkit (refactored core) — the ExecutionTree model.
  *
- * A curated public surface. `om(name, body)` runs a linear orchestration as the root of
+ * A curated public surface. `om(name).run(body)` runs a linear orchestration as the root of
  * one run; `action(...)` defines typed units you launch by **calling** them;
  * `step(name, fn)` is the inline anonymous action. The run's introspectable output
  * is the on-disk `result.json` / `raw.jsonl` / `.log` files — the ExecutionTree
@@ -11,4 +11,4 @@ export { om } from "./core/om.ts";
 export { action } from "./core/action.ts";
 export { step } from "./core/step.ts";
 export { CancelledError, isCancelled } from "./foundation/CancelledError.ts";
-export type { Action, Activity, ActionContext, OmContext } from "./core/types.ts";
+export type { Action, Activity, ActionContext, OmBuilder, OmBuilderArgs, OmContext, OmDescription, } from "./core/types.ts";

package/dist/index.js

@@ -1,7 +1,7 @@
 /**
  * omkit (refactored core) — the ExecutionTree model.
  *
- * A curated public surface. `om(name, body)` runs a linear orchestration as the root of
+ * A curated public surface. `om(name).run(body)` runs a linear orchestration as the root of
  * one run; `action(...)` defines typed units you launch by **calling** them;
  * `step(name, fn)` is the inline anonymous action. The run's introspectable output
  * is the on-disk `result.json` / `raw.jsonl` / `.log` files — the ExecutionTree

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

@@ -0,0 +1 @@
+export {};

package/dist/mcp/action-host.js

@@ -0,0 +1,65 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { pathToFileURL } from "node:url";
+import { om } from "../index.js";
+import { hostOmName } from "./action-identity.js";
+/**
+ * The host om for an action-backed tool. Forked as the om file, with the action to run
+ * named on the environment.
+ *
+ * An action cannot run standalone — `ExecutionTree.require()` throws outside a run — so
+ * something has to host it. Nothing here is forged: `callerSite()` captures this file,
+ * which genuinely is where the run is defined. The disambiguator lives in the **name**:
+ * `seed@a1b2c3d4` is stable across runs, and two same-named actions in different files get
+ * different suffixes and therefore different folders. That satisfies the
+ * run-folder-identity contract through the name rather than around it, and avoids adding
+ * an escape hatch that would let any caller claim another run's identity.
+ *
+ * Known sharp edge: an action declared with `.ref<H>()` publishes a capability for
+ * downstream actions. Standalone it does its work and hands that capability to nobody —
+ * `chromePage` would attach to Chrome and return nothing useful. Such actions make poor
+ * tools. Documented, not prevented.
+ */
+function required(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`${name} must be set — the MCP server sets it when forking this host`);
+    }
+    return value;
+}
+const file = required("OMKIT_ACTION_FILE");
+const name = required("OMKIT_ACTION_NAME");
+const exportName = required("OMKIT_ACTION_EXPORT");
+// Deliberately not OMKIT_ARGS: this om declares no `.args()`, so nothing here would read
+// that variable, and a distinct name keeps a host run from colliding with an om's args.
+const args = JSON.parse(process.env.OMKIT_ACTION_ARGS ?? "{}");
+om(hostOmName(name, file))
+    .describe({ summary: `Standalone host for the ${name} action.` })
+    .run(async () => {
+    const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
+    const launch = mod[exportName];
+    if (typeof launch !== "function") {
+        throw new Error(`${file} has no exported action "${exportName}"`);
+    }
+    // The action reaches `ExecutionTree.require()` through the copy of omkit *its* file
+    // imported, and `current` is a static — so this only works when both resolve to the
+    // same installed omkit. True for a normal install and for the fixtures; false under
+    // `npm link`, a non-hoisted pnpm layout, or two omkit versions in one tree. The bare
+    // error is undiagnosable from a client, so name the cause here.
+    try {
+        await launch(args).result;
+    }
+    catch (e) {
+        if (e instanceof Error && /no active om\(\) run/.test(e.message)) {
+            throw new Error(`${name} could not see this run. Its file resolved a different copy of omkit ` +
+                `than the host did — check for a linked, duplicated, or non-hoisted omkit install.`);
+        }
+        throw e;
+    }
+});

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