omkit 0.4.7 → 0.8.0

package/dist/core/om.js

@@ -1,22 +1,41 @@
 import { ExecutionTree } from "./ExecutionTree.js";
-import { callerSite } from "../foundation/callsite.js";
-/**
- * Runs a linear orchestration as the root of a fresh {@link ExecutionTree}. The
- * required `name` plus the absolute path of the file calling `om()` form the run's
- * identity — its log folder is `logs/<name>-<hash8>/…`, so same-named oms defined
- * in different files never share a folder. 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).
- */
-export function om(name, body) {
+import { callerSite, siteFile } from "../foundation/callsite.js";
+import { describeSchema, isDiscovering, reportOm } from "./discovery-mode.js";
+import { activeSupervisor } from "./interaction.js";
+import { jsonAnswerComplete, resolveArgs } from "./args.js";
+import { OPAQUE } from "./schema-hint.js";
+function assertName(name) {
     if (typeof name !== "string" || name.trim() === "") {
-        throw new Error("om(name, body) requires a non-empty name — it identifies the run in logs/");
+        throw new Error("om(name) requires a non-empty name — it identifies the run in logs/");
+    }
+}
+/** Start the run: build the tree with the captured site and drive the body as the root. */
+function launch(name, site, description, exposure, body, schema) {
+    // Discovery: report what this om declares and start nothing.
+    //
+    // The guard belongs *here*, at the single choke point both `run()` methods funnel
+    // through, for two reasons. `OmBuilderArgs.run` resolves args inside the run body, so a
+    // guard one level up would reach `resolveArgs` first and prompt into a child nobody can
+    // answer (or throw MissingArgsError) — neither is a discovery outcome. And
+    // `new ExecutionTree(...)` creates the run's log folder in its constructor, so the
+    // guard has to precede it or discovery litters `logs/` with empty runs.
+    if (isDiscovering()) {
+        const { inputSchema, schemaError } = describeSchema(schema);
+        reportOm({
+            kind: "om-registration",
+            name,
+            file: siteFile(site),
+            description,
+            mcp: exposure,
+            inputSchema,
+            schemaError,
+        });
+        return Promise.resolve();
     }
     if (ExecutionTree.current) {
         throw new Error("an om() run is already active in this process");
     }
-    const tree = new ExecutionTree(name, callerSite()); // callerSite: where om() was called — the run's script
+    const tree = new ExecutionTree(name, site, description, exposure);
     ExecutionTree.current = tree;
     const rootBody = (ctx) => body({
         signal: ctx.signal,
@@ -25,7 +44,157 @@ export function om(name, body) {
         cancel: () => tree.cancel(),
         assert: ctx.assert,
         snapshot: ctx.snapshot,
+        artifact: ctx.artifact,
         artifactsFolder: ctx.artifactsFolder,
     });
     return tree.runRoot(rootBody);
 }
+class Builder {
+    name;
+    site;
+    /** Carried into `ArgsBuilder` by `.args()`, which otherwise rebuilds the builder. */
+    description;
+    /** Carried the same way, for the same reason — `.args()` returns a new object. */
+    exposure;
+    constructor(name, 
+    /** Captured in `om()`, not here — the defining file must be the caller's, not om.ts. */
+    site) {
+        this.name = name;
+        this.site = site;
+    }
+    describe(description) {
+        this.description = description;
+        return this;
+    }
+    mcp(exposure = {}) {
+        // The default is filled here, not at the reader, so every consumer sees one shape.
+        this.exposure = { mode: exposure.mode ?? "settling" };
+        return this;
+    }
+    args(schema) {
+        return new ArgsBuilder(this.name, this.site, schema, this.description, this.exposure);
+    }
+    run(body) {
+        // Carried onto the run for `omkit ls` and the MCP server; not read by the runtime yet.
+        return launch(this.name, this.site, this.description, this.exposure, body);
+    }
+}
+/**
+ * The builder after `.args(schema)`. Unlike an action's, the schema here is live: `.run`
+ * resolves it before calling the body, so an om declares what it needs and omkit fills it
+ * in. The site is the one `om()` captured — threaded through, never re-taken.
+ */
+class ArgsBuilder {
+    name;
+    site;
+    schema;
+    description;
+    exposure;
+    constructor(name, site, schema, description, exposure) {
+        this.name = name;
+        this.site = site;
+        this.schema = schema;
+        this.description = description;
+        this.exposure = exposure;
+    }
+    describe(description) {
+        this.description = description;
+        return this;
+    }
+    mcp(exposure = {}) {
+        this.exposure = { mode: exposure.mode ?? "settling" };
+        return this;
+    }
+    run(body) {
+        // Resolution happens inside the run, not before it: prompting is async, and the run
+        // must already exist for the prompt and its answer to land on the timeline. A failure
+        // to resolve is therefore an ordinary failure of the root node — logged, and the run
+        // is marked failed — rather than a throw out of `om(...)`.
+        return launch(this.name, this.site, this.description, this.exposure, async (ctx) => {
+            const args = (await resolveArgs(this.schema, {
+                supplied: parseSuppliedArgs(),
+                interactive: isInteractive(),
+                ask: askForArg,
+            }));
+            ExecutionTree.current?.setRootArgs(args);
+            await body(ctx, args);
+        }, 
+        // Handed to `launch` for discovery only: in a real run the schema is resolved above,
+        // inside the body. Discovery never reaches that body, so it converts the schema here.
+        this.schema);
+    }
+}
+/** `OMKIT_ARGS` carries JSON — the only channel readable synchronously at `.run()`. */
+function parseSuppliedArgs() {
+    const raw = process.env.OMKIT_ARGS;
+    // Read it once, then clear it from the environment so any subprocess this run spawns
+    // (`command("npx omkit run other-om")`, a nested npm script, …) does not inherit this
+    // run's args and resolve them against a completely different schema. Whoever launches an
+    // omkit child sets that child's args explicitly.
+    delete process.env.OMKIT_ARGS;
+    if (!raw)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error("OMKIT_ARGS is not valid JSON");
+    }
+}
+/**
+ * Supervised, or a real terminal. Otherwise nobody can answer a prompt and resolution must
+ * fail fast instead of blocking on a question no one will see.
+ */
+function isInteractive() {
+    return activeSupervisor() !== null || process.stdin.isTTY === true;
+}
+/**
+ * Ask the user for one arg, via the `prompt` battery.
+ *
+ * The import is dynamic so that `import { om }` does not pull readline in, and because
+ * `core` is otherwise not allowed to import `actions`. Be clear about what that costs: this
+ * is a **deliberate, unenforced** runtime edge, not a permitted one. ESLint's
+ * `no-restricted-imports` has no `ImportExpression` visitor, so a dynamic import is
+ * *invisible* to the rule rather than allowed by it — the linter will not catch the next one
+ * either, and nothing but this comment stands between here and a real dependency cycle.
+ */
+async function askForArg(spec) {
+    const { prompt } = await import("../actions/prompt.js");
+    if (spec.kind === "json") {
+        return prompt({
+            kind: "multiline",
+            message: `${spec.path} — JSON`,
+            // No sketch means `shapeHint` could not express the shape; a placeholder would tell
+            // the user nothing about what to type, so the schema itself goes in its place.
+            hint: spec.hint ?? JSON.stringify(spec.jsonSchema),
+            // Not `"json"`: a JSON-kind arg may also be answered with the path to a JSON file, and
+            // a path is not JSON, so a JSON-only terminator would never end the read. At a bare
+            // terminal there is no EOF to fall back on, so the user would wait out the timeout —
+            // three times. This is the same rule `coerce` reads the answer back with.
+            until: jsonAnswerComplete,
+            timeoutMs: 120_000,
+        }).result;
+    }
+    // One line has no room for a raw schema, so an unsketchable scalar shows the placeholder.
+    return prompt({ message: `${spec.path} (${spec.hint ?? OPAQUE})`, timeoutMs: 120_000 }).result;
+}
+/**
+ * Define a run. `om(name)` returns a builder — chain `.describe(…)` and/or `.args(schema)`
+ * and finish with `.run(body)`, which launches it as the root of a fresh
+ * {@link ExecutionTree}. The name plus the absolute path of the calling file identify the
+ * run; its log folder is `logs/<name>-<hash8>/…`, so same-named oms in different files
+ * never share a folder.
+ *
+ * The call site is captured **here**, not in `.run()` (nor in `.args()`): `om(name)` is
+ * where a run is defined, so a builder handed to (and run from) another file still hashes
+ * to the file that defined it — see the run-folder-identity constraint doc.
+ */
+export function om(name) {
+    assertName(name);
+    // The removed two-argument form: JS callers would otherwise silently lose their body
+    // to a builder nobody runs. TypeScript callers get a compile error before this.
+    if (arguments.length > 1) {
+        throw new Error("om(name, body) was removed — use om(name).run(body). See the omkit CHANGELOG.");
+    }
+    return new Builder(name, callerSite()); // the om() call site — the run's defining script
+}

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

@@ -0,0 +1,20 @@
+import type { JsonSchema } from "./schema-json.ts";
+/**
+ * Placeholder text for a schema that cannot be sketched, for the one-line prompts where
+ * printing the raw JSON Schema instead would not fit. Callers do **not** detect degradation
+ * by comparing against it — {@link shapeHint} returns `undefined` for that.
+ */
+export declare const OPAQUE = "see schema";
+/**
+ * Render a JSON Schema as a one-line type sketch for a prompt — `{ host: string,
+ * port?: number }` — or `undefined` when it cannot express the shape (deep unions,
+ * tuples, recursion).
+ *
+ * Deliberately partial, and **all-or-nothing**: an unsketchable type anywhere in the tree
+ * degrades the whole sketch rather than leaving a placeholder inside an otherwise-valid
+ * one. `{ mode: see schema }` reads as a field whose type is the string "see schema", which
+ * is exactly the misleading output this is supposed to refuse to print. Degradation is
+ * signalled by the return type so a caller cannot miss it by string-matching the wrong
+ * shape of sentinel.
+ */
+export declare function shapeHint(schema: JsonSchema): string | undefined;

package/dist/core/schema-hint.js

@@ -0,0 +1,73 @@
+/**
+ * Placeholder text for a schema that cannot be sketched, for the one-line prompts where
+ * printing the raw JSON Schema instead would not fit. Callers do **not** detect degradation
+ * by comparing against it — {@link shapeHint} returns `undefined` for that.
+ */
+export const OPAQUE = "see schema";
+/**
+ * Render a JSON Schema as a one-line type sketch for a prompt — `{ host: string,
+ * port?: number }` — or `undefined` when it cannot express the shape (deep unions,
+ * tuples, recursion).
+ *
+ * Deliberately partial, and **all-or-nothing**: an unsketchable type anywhere in the tree
+ * degrades the whole sketch rather than leaving a placeholder inside an otherwise-valid
+ * one. `{ mode: see schema }` reads as a field whose type is the string "see schema", which
+ * is exactly the misleading output this is supposed to refuse to print. Degradation is
+ * signalled by the return type so a caller cannot miss it by string-matching the wrong
+ * shape of sentinel.
+ */
+export function shapeHint(schema) {
+    return render(schema);
+}
+function render(node) {
+    if (typeof node !== "object" || node === null)
+        return undefined;
+    const s = node;
+    const enumValues = s.enum;
+    if (Array.isArray(enumValues) && enumValues.length > 0) {
+        return enumValues.map((v) => JSON.stringify(v)).join(" | ");
+    }
+    switch (s.type) {
+        case "string":
+        case "number":
+        case "integer":
+        case "boolean":
+        case "null":
+            return String(s.type);
+        case "array":
+            return renderArray(s);
+        case "object":
+            return renderObject(s);
+        default:
+            return undefined;
+    }
+}
+/**
+ * A tuple's `items` is absent (it uses `prefixItems`), and an opaque element type renders
+ * to nothing — either way there is no element sketch, so there is no array sketch.
+ * Propagating `undefined` here is what stops `see schema[]` being printed.
+ */
+function renderArray(s) {
+    const items = render(s.items);
+    return items === undefined ? undefined : `${items}[]`;
+}
+function renderObject(s) {
+    const properties = s.properties;
+    if (typeof properties !== "object" || properties === null)
+        return undefined;
+    const required = new Set(Array.isArray(s.required) ? s.required : []);
+    const entries = Object.entries(properties);
+    if (entries.length === 0)
+        return undefined;
+    const fields = [];
+    for (const [key, value] of entries) {
+        const rendered = render(value);
+        // One field we cannot sketch makes the whole line untrustworthy: the reader has no way
+        // to tell the interpolated placeholder from a real type. Degrade the object instead, so
+        // the caller falls back to printing the schema the user actually has to satisfy.
+        if (rendered === undefined)
+            return undefined;
+        fields.push(`${key}${required.has(key) ? "" : "?"}: ${rendered}`);
+    }
+    return `{ ${fields.join(", ")} }`;
+}

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