omkit 0.4.7 → 0.8.0

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

package/dist/mcp/validate.js

@@ -0,0 +1,54 @@
+const typeName = (value) => Array.isArray(value) ? "array" : value === null ? "null" : typeof value;
+/** True when `value` satisfies a JSON Schema `type` keyword. Unknown types always pass. */
+function matches(type, value) {
+    switch (type) {
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number";
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "array":
+            return Array.isArray(value);
+        case "object":
+            return typeof value === "object" && value !== null && !Array.isArray(value);
+        default:
+            return true;
+    }
+}
+/** Required fields the caller left out. `null` counts as supplied — and wrongly typed. */
+function missingRequired(schema, args) {
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    return required
+        .filter((key) => args[key] === undefined)
+        .map((key) => `missing required argument "${key}"`);
+}
+/** Supplied fields whose value contradicts the schema's `type` keyword. */
+function wrongTypes(schema, args) {
+    const properties = (schema.properties ?? {});
+    const problems = [];
+    for (const [key, definition] of Object.entries(properties)) {
+        const value = args[key];
+        if (value === undefined)
+            continue;
+        const type = definition?.type;
+        if (typeof type !== "string")
+            continue; // unions, $ref, anyOf — the child's problem
+        if (!matches(type, value)) {
+            problems.push(`argument "${key}" must be a ${type}, got ${typeName(value)}`);
+        }
+    }
+    return problems;
+}
+/** Every problem found, in schema order. Empty means "worth spawning". */
+export function checkArgs(schema, args) {
+    if (!schema)
+        return [];
+    if (typeof args !== "object" || args === null || Array.isArray(args)) {
+        return ["arguments must be a JSON object"];
+    }
+    const supplied = args;
+    return [...missingRequired(schema, supplied), ...wrongTypes(schema, supplied)];
+}

package/dist/mcp/verdict.d.ts

@@ -0,0 +1,31 @@
+import type { Verdict } from "../client/types.ts";
+/**
+ * The structured outcome of a settled run — the verdict a client can act on.
+ *
+ * A `type`, not an `interface`, on purpose: the SDK types `structuredContent` as
+ * `{ [x: string]: unknown }`, and TypeScript gives an implicit index signature to type
+ * aliases but not to interfaces. As an interface this is not assignable and the tool
+ * cannot return it.
+ */
+export type RunVerdict = {
+    readonly ok: boolean;
+    /** Absolute path of the run folder, or "" when the child died before settling. */
+    readonly folder: string;
+    readonly assertions: {
+        readonly passed: number;
+        readonly failed: number;
+    };
+    readonly failures: ReadonlyArray<{
+        action: string;
+        error: string;
+    }>;
+    /** The recap block the terminal would have printed. */
+    readonly summary: readonly string[];
+};
+export declare function readVerdict(verdict: Verdict): Promise<RunVerdict>;
+/**
+ * The verdict of a run this process never supervised — read entirely from disk. There is
+ * no channel to trust here, so `ok` comes from the file; a folder without a readable
+ * `result.json` is reported as not ok, because a run that never wrote one did not finish.
+ */
+export declare function readVerdictAt(folder: string): Promise<RunVerdict>;

package/dist/mcp/verdict.js

@@ -0,0 +1,47 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+/** The run's own `result.json`, or undefined when there isn't a readable one. */
+async function readResult(folder) {
+    try {
+        return JSON.parse(await readFile(path.join(folder, "result.json"), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function readVerdict(verdict) {
+    const base = {
+        // The channel's `ok` wins over the file's: it also covers a child that died before
+        // writing one, which `result.json` by definition cannot report.
+        ok: verdict.ok,
+        folder: verdict.folder,
+        summary: verdict.summary,
+        assertions: { passed: 0, failed: 0 },
+        failures: [],
+    };
+    if (!verdict.folder)
+        return base;
+    const parsed = await readResult(verdict.folder);
+    if (!parsed)
+        return base;
+    return {
+        ...base,
+        assertions: parsed.assertions ?? base.assertions,
+        failures: parsed.failures ?? base.failures,
+    };
+}
+/**
+ * The verdict of a run this process never supervised — read entirely from disk. There is
+ * no channel to trust here, so `ok` comes from the file; a folder without a readable
+ * `result.json` is reported as not ok, because a run that never wrote one did not finish.
+ */
+export async function readVerdictAt(folder) {
+    const parsed = await readResult(folder);
+    return {
+        ok: parsed?.ok ?? false,
+        folder,
+        summary: [],
+        assertions: parsed?.assertions ?? { passed: 0, failed: 0 },
+        failures: parsed?.failures ?? [],
+    };
+}

package/dist/output/artifact/ArtifactStore.d.ts

@@ -0,0 +1,24 @@
+/** One curated artifact — a file the om chose to label. */
+export interface ArtifactRecord {
+    readonly name: string;
+    /** Absolute path to the file. */
+    readonly file: string;
+    readonly description?: string;
+    readonly mime: string;
+    /** The node that registered it. */
+    readonly nodeId: string;
+}
+/**
+ * The run's curated artifacts — the files an om labelled via `ctx.artifact`, in
+ * registration order. Holds no I/O: the om already wrote the file, this records what it
+ * means. Unregistered files stay in the run folder and stay listed by anything
+ * enumerating it; curation raises signal, it does not gate access.
+ */
+export declare class ArtifactStore {
+    private readonly records;
+    register(name: string, file: string, nodeId: string, opts?: {
+        description?: string;
+        mime?: string;
+    }): ArtifactRecord;
+    all(): readonly ArtifactRecord[];
+}