omkit 0.4.8 → 0.8.1

package/dist/core/schema-json.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+/** A JSON Schema document, kept deliberately loose — consumers read known keys. */
+export type JsonSchema = Record<string, unknown>;
+/**
+ * Convert a zod schema to JSON Schema. The single conversion point in omkit: prompt
+ * hints (`schema-hint.ts`) and any external consumer read the result, so the choice of
+ * converter stays here rather than spreading across callers.
+ *
+ * Uses `io: "input"` to describe the input type where defaulted fields are optional,
+ * correctly excluding them from `required` arrays at all nesting levels.
+ */
+export declare function toJsonSchema(schema: z.ZodType): JsonSchema;

package/dist/core/schema-json.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+/**
+ * Convert a zod schema to JSON Schema. The single conversion point in omkit: prompt
+ * hints (`schema-hint.ts`) and any external consumer read the result, so the choice of
+ * converter stays here rather than spreading across callers.
+ *
+ * Uses `io: "input"` to describe the input type where defaulted fields are optional,
+ * correctly excluding them from `required` arrays at all nesting levels.
+ */
+export function toJsonSchema(schema) {
+    return z.toJSONSchema(schema, { io: "input" });
+}

package/dist/core/types.d.ts

@@ -1,6 +1,12 @@
+import type { z } from "zod";
+import type { JsonSchema } from "./schema-json.ts";
 import type { Emitter, EventHandler } from "../foundation/events.ts";
 import type { ReadableLog } from "../foundation/LogEntry.ts";
 import type { Proc } from "../system/proc.ts";
+/** Any zod schema. Aliased so the rest of the file reads without zod's generics. */
+export type ZodTypeLike = z.ZodType;
+/** The TypeScript type a schema validates to. */
+export type InferSchema<S extends ZodTypeLike> = z.infer<S>;
 /** A value an action's exec may return: a result, or a promise of one. */
 export type Awaitable<T> = T | Promise<T>;
 /** An action that declares no events. */
@@ -34,11 +40,81 @@ export interface ActionContext<Events extends object = NoEvents, Handle = void>
     readonly assert: (condition: boolean, message: string) => void;
     /** Capture a JSON snapshot; drops a timeline line and resolves the file's absolute path. */
     readonly snapshot: (name: string, value: unknown) => Promise<string>;
+    /**
+     * Label a file this action wrote — name, optional description, MIME inferred from the
+     * extension. Drops a timeline line and returns the file's path. Purely descriptive:
+     * the file must already exist (or be written next); this records what it is.
+     */
+    readonly artifact: (name: string, file: string, opts?: {
+        description?: string;
+        mime?: string;
+    }) => string;
     /** Absolute path to this run's output folder — write artifacts (screenshots, dumps, …) here. */
     readonly artifactsFolder: string;
     /** Spawn child processes bound to this action (output → this node's log, killed on teardown). */
     readonly proc: Proc;
 }
+/** Human-readable metadata about an om or action. */
+export interface OmDescription {
+    /** One line saying what this does. */
+    summary: string;
+}
+/** How an om or action behaves when a client runs it as an MCP tool. */
+export type McpMode = "settling" | "long-lived";
+/**
+ * Marks an om or action as exposed over MCP. Absent ⇒ invisible to the server:
+ * `.describe()` and `.args()` alone expose nothing.
+ */
+export interface McpExposure {
+    /**
+     * Whether the run settles on its own. `run_om` accepts only a `"settling"` entry; a
+     * `"long-lived"` one must be started with `start_om`. Omitted ⇒ `"settling"`, so being
+     * wrong surfaces as a timeout rather than a silently orphaned process.
+     */
+    mode?: McpMode;
+}
+/** An {@link McpExposure} after the builder has filled its default. */
+export interface ResolvedMcpExposure {
+    readonly mode: McpMode;
+}
+/** The result of converting a declared schema — one of the two fields is always undefined. */
+export interface DescribedArgs {
+    readonly inputSchema: JsonSchema | undefined;
+    readonly schemaError: string | undefined;
+}
+/** The builder returned by `om(name)`. `.run(body)` launches the run. */
+export interface OmBuilder {
+    /** Attach a human-readable summary — carried for `omkit ls` and future tooling. */
+    describe(description: OmDescription): OmBuilder;
+    /** Expose this om over MCP. Without it the MCP server does not list or run it. */
+    mcp(exposure?: McpExposure): OmBuilder;
+    /**
+     * Declare the run's input shape. Unlike an action's `.args()`, this is resolved at
+     * runtime: the values come from what was supplied, then the schema's defaults, then by
+     * prompting — and the run fails if that is not enough.
+     */
+    args<S extends ZodTypeLike>(schema: S): OmBuilderArgs<S>;
+    /**
+     * Launch the run with `body` as its root. The body runs inside the root node's
+     * ambient scope, so any action call / `step(...)` / `console.*` it reaches attributes
+     * correctly. Resolves once the run has torn down and produced its artifacts; never
+     * rejects (failures are recorded in the tree and set the exit code).
+     */
+    run(body: (ctx: OmContext) => Awaitable<void>): Promise<void>;
+}
+/** After `.args(schema)`: `.run`'s body receives the resolved, typed args. */
+export interface OmBuilderArgs<S extends ZodTypeLike> {
+    describe(description: OmDescription): OmBuilderArgs<S>;
+    /** Expose this om over MCP. Without it the MCP server does not list or run it. */
+    mcp(exposure?: McpExposure): OmBuilderArgs<S>;
+    /**
+     * Launch the run, resolving the declared args first — supplied values, then defaults,
+     * then prompting — and pass them to `body` as its second parameter. Resolution happens
+     * *inside* the run, so a prompt and its answer land on the run's own timeline; an
+     * unresolvable arg fails the run like any other error in the body.
+     */
+    run(body: (ctx: OmContext, args: InferSchema<S>) => Awaitable<void>): Promise<void>;
+}
 /** What the `om` body receives — the run-level counterpart to {@link ActionContext}. */
 export interface OmContext {
     /** The run's (root) abort signal. */
@@ -53,6 +129,15 @@ export interface OmContext {
     readonly assert: (condition: boolean, message: string) => void;
     /** Capture a run-level JSON snapshot; resolves the file's absolute path. */
     readonly snapshot: (name: string, value: unknown) => Promise<string>;
+    /**
+     * Label a file this action wrote — name, optional description, MIME inferred from the
+     * extension. Drops a timeline line and returns the file's path. Purely descriptive:
+     * the file must already exist (or be written next); this records what it is.
+     */
+    readonly artifact: (name: string, file: string, opts?: {
+        description?: string;
+        mime?: string;
+    }) => string;
     /** Absolute path to this run's output folder — write run-level artifacts here. */
     readonly artifactsFolder: string;
 }
@@ -101,13 +186,40 @@ export interface Action<Args extends unknown[], Result, Events extends object =
     readonly actionName: string;
     /** `file:line` where this action was defined (the `.run(...)` site), for the log header. */
     readonly definedAt: string | undefined;
+    /**
+     * The summary from `.describe(…)`, carried across every builder link onto the definition.
+     * Stored so it is retrievable; nothing in the runtime reads it yet.
+     */
+    readonly description: OmDescription | undefined;
+    /** The `.mcp(…)` exposure, carried across every builder link. Undefined ⇒ not exposed. */
+    readonly mcp: ResolvedMcpExposure | undefined;
+    /**
+     * The declared args as JSON Schema, computed on demand. Called by the discovery child
+     * rather than converting the schema itself: the user's file resolves `"omkit"` to the
+     * installed package while the child runs omkit's own module graph, so the two can hold
+     * different zod instances. Converting inside the defining copy sidesteps that. Never
+     * throws — an unconvertible schema comes back as `schemaError`.
+     */
+    readonly describeArgs: () => DescribedArgs;
 }
-/** Intermediate step from `action(name)`: declare events/handle, then provide the impl. */
+/** Intermediate step from `action(name)`: declare metadata/events/handle, then the impl. */
 export interface ActionBuilderEvents<Events extends object, Handle = void> {
+    describe(description: OmDescription): ActionBuilderEvents<Events, Handle>;
+    /** Expose this action over MCP. Without it the MCP server does not list or run it. */
+    mcp(exposure?: McpExposure): ActionBuilderEvents<Events, Handle>;
     emits<E extends object>(): ActionBuilderEvents<E, Handle>;
     ref<H>(): ActionBuilderEvents<Events, H>;
+    /** Pin the first parameter to the schema's inferred type. */
+    args<S extends ZodTypeLike>(schema: S): ActionBuilderArgs<S, Events, Handle>;
     run<Args extends unknown[], Result>(body: (ctx: ActionContext<Events, Handle>, ...args: Args) => Awaitable<Result>): Action<Args, Result, Events, Handle>;
 }
+/** After `.args(schema)`: `.run` takes exactly one typed argument. */
+export interface ActionBuilderArgs<S extends ZodTypeLike, Events extends object, Handle = void> {
+    describe(description: OmDescription): ActionBuilderArgs<S, Events, Handle>;
+    /** Expose this action over MCP. Without it the MCP server does not list or run it. */
+    mcp(exposure?: McpExposure): ActionBuilderArgs<S, Events, Handle>;
+    run<Result>(body: (ctx: ActionContext<Events, Handle>, args: InferSchema<S>) => Awaitable<Result>): Action<[InferSchema<S>], Result, Events, Handle>;
+}
 /** The exec signature bound by `.run(...)` (arg types erased at the boundary). */
 export type Exec<Events extends object, Handle, Result> = (ctx: ActionContext<Events, Handle>, ...args: never[]) => Awaitable<Result>;
 /** What the {@link ExecutionTree} needs to launch an instance — the shape an instance satisfies. */

package/dist/foundation/LogEntry.d.ts

@@ -13,7 +13,7 @@ export interface LogEntry {
     readonly nodeId: string;
     /** The owning node's execution path (`main/chromePage_9f3c`). */
     readonly path: string;
-    /** `info` | `error` | `event` | `assert` | `snapshot` | `tag` | `child` | `run`. */
+    /** `info` | `error` | `event` | `assert` | `snapshot` | `artifact` | `tag` | `child` | `run`. */
     readonly level: string;
     /** Finer origin within the node (proc name, `event`, `run`, …). */
     readonly source: string;

package/dist/foundation/canonicalPath.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 declare function canonicalPath(file: string): string;

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;