omkit 0.4.8 → 0.8.1

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

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;