omkit 0.4.8 → 0.8.0

package/dist/client/discover-child.d.ts

@@ -0,0 +1,12 @@
+import type { ActionRegistration } from "./registry.ts";
+/** The parent's opening message: sent over IPC, so no argv length limit applies. */
+export interface ScanMessage {
+    readonly kind: "scan";
+    readonly files: string[];
+}
+/** The child's closing message. Om registrations arrive separately, as each om is reached. */
+export interface ActionsMessage {
+    readonly kind: "actions";
+    readonly actions: ActionRegistration[];
+    readonly warnings: string[];
+}

package/dist/client/discover-child.js

@@ -0,0 +1,71 @@
+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";
+function asAction(value) {
+    if (typeof value !== "function")
+        return undefined;
+    const candidate = value;
+    if (typeof candidate.actionName !== "string")
+        return undefined;
+    if (typeof candidate.describeArgs !== "function")
+        return undefined;
+    return candidate;
+}
+/**
+ * The discovery child. Forked with `OMKIT_DISCOVER=1`, so importing a file makes every
+ * `om(...).run(...)` in it post a registration up this same channel instead of launching
+ * (see core/discovery-mode.ts). Actions post nothing — they are plain values — so their
+ * metadata is read off each module's exports here, afterwards.
+ */
+async function scan(files) {
+    const actions = [];
+    const warnings = [];
+    for (const file of files) {
+        let mod;
+        try {
+            mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
+        }
+        catch (e) {
+            warnings.push(`${file}: ${e instanceof Error ? e.message : String(e)}`);
+            continue;
+        }
+        for (const [exportName, value] of Object.entries(mod)) {
+            const found = asAction(value);
+            if (!found)
+                continue;
+            const { inputSchema, schemaError } = found.describeArgs();
+            actions.push({
+                name: found.actionName,
+                exportName,
+                file,
+                ...(found.description ? { summary: found.description.summary } : {}),
+                ...(found.mcp ? { mcp: found.mcp } : {}),
+                ...(inputSchema ? { inputSchema } : {}),
+                ...(schemaError ? { unavailable: schemaError } : {}),
+            });
+        }
+    }
+    // Exit only once the message has actually flushed. `process.send` is asynchronous —
+    // exiting on the next line can drop the payload before it reaches the parent, and the
+    // parent would see a `close` with no `actions` message and report an empty project.
+    // A user module may also have started a server or a timer at import; nothing here is
+    // supervised and nothing will tear it down, so leave deliberately rather than linger.
+    const done = () => process.exit(0);
+    if (process.send) {
+        process.send({ kind: "actions", actions, warnings }, done);
+    }
+    else {
+        done();
+    }
+}
+process.on("message", (message) => {
+    if (message?.kind === "scan") {
+        void scan(message.files);
+    }
+});

package/dist/client/discovery.d.ts

@@ -1,4 +1,4 @@
-import type { Registry } from "./registry.ts";
+import type { Registry, RegistrationSet } from "./registry.ts";
 /**
  * Statically scan the project described by `tsconfigPath` for runnable oms and inspectable
  * actions. Type errors in the user's oms/actions degrade to `warnings` (an editor-in-progress
@@ -6,3 +6,23 @@ import type { Registry } from "./registry.ts";
  * tsconfig — throws, so the CLI crashes visibly instead of silently returning an empty project.
  */
 export declare function discover(tsconfigPath: string): Registry;
+/**
+ * Import `files` in a throwaway child with `OMKIT_DISCOVER=1` and collect what they
+ * declare. Exposed separately from {@link discoverRegistrations} so the fork can be driven
+ * with an explicit file list — by tests, and by anything that already knows its candidates.
+ *
+ * Never rejects for user-code problems: an import failure, a crashed child, or a child
+ * that outstays its timeout all come back as warnings on an otherwise usable set.
+ */
+export declare function readRegistrations(files: string[], opts?: {
+    cwd?: string;
+    timeoutMs?: number;
+}): Promise<RegistrationSet>;
+/**
+ * The full pass: the AST scan picks the candidate files — it stays the only cheap,
+ * never-executing phase — then {@link readRegistrations} imports just those. AST warnings
+ * are carried through so nothing is lost between the two phases.
+ */
+export declare function discoverRegistrations(tsconfigPath: string, opts?: {
+    timeoutMs?: number;
+}): Promise<RegistrationSet>;

package/dist/client/discovery.js

@@ -1,5 +1,12 @@
 import ts from "typescript";
 import path from "node:path";
+import { fork } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { omHash } from "../foundation/ids.js";
+import { fsSafe } from "../foundation/fsSafe.js";
+import { canonicalPath } from "../foundation/canonicalPath.js";
+import { tsxLoader } from "./runner.js";
+import { chainRoot, importedNames, outlineBody } from "./outline.js";
 /**
  * Statically scan the project described by `tsconfigPath` for runnable oms and inspectable
  * actions. Type errors in the user's oms/actions degrade to `warnings` (an editor-in-progress
@@ -20,16 +27,28 @@ export function discover(tsconfigPath) {
     for (const sf of program.getSourceFiles()) {
         if (!fileSet.has(canonical(sf.fileName)))
             continue;
+        // TypeScript hands back its own spelling of the path — on Windows it lowercases the drive
+        // letter — and every consumer downstream keys on this string: the discovery fork imports
+        // it, `omHash` hashes it, and Node caches modules by it. Canonicalise once here so the
+        // whole chain agrees with the filesystem, and with the paths a real run reports.
+        const file = canonicalPath(sf.fileName);
         for (const d of program.getSemanticDiagnostics(sf))
             warnings.push(formatDiagnostic(d));
         const names = omkitImports(sf);
+        const outlines = outlinesIn(sf, names.om, importedNames(sf));
         const visit = (node) => {
             if (ts.isCallExpression(node) &&
                 ts.isIdentifier(node.expression) &&
                 (node.expression.text === names.om || node.expression.text === names.step)) {
                 const arg = node.arguments[0];
                 if (arg && ts.isStringLiteralLike(arg)) {
-                    oms.push({ name: arg.text, file: sf.fileName, line: lineOf(sf, node) });
+                    const calls = outlines.get(arg.text);
+                    oms.push({
+                        name: arg.text,
+                        file,
+                        line: lineOf(sf, node),
+                        ...(calls?.length ? { calls } : {}),
+                    });
                 }
             }
             ts.forEachChild(node, visit);
@@ -45,7 +64,7 @@ export function discover(tsconfigPath) {
                 if (info) {
                     actions.push({
                         name: info.name,
-                        file: sf.fileName,
+                        file,
                         exportName: decl.name.text,
                         publishesCapability: info.ref,
                         events: info.emits,
@@ -56,6 +75,124 @@ export function discover(tsconfigPath) {
     }
     return { oms, actions, warnings };
 }
+/**
+ * Outline every `om("name")…​.run(body)` chain in a file, keyed by om name.
+ *
+ * Collected in its own pass rather than alongside the `om(...)` match, because a body is only
+ * reachable from the `.run` end of the chain and the om name only from the other — and the
+ * chain is walked downward (see {@link chainRoot}), so one pass cannot have both.
+ */
+function outlinesIn(sf, omName, imported) {
+    const outlines = new Map();
+    if (omName === undefined)
+        return outlines;
+    const visit = (node) => {
+        if (ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression) &&
+            node.expression.name.text === "run") {
+            const root = chainRoot(node);
+            const body = node.arguments[0];
+            const name = root?.call.arguments[0];
+            if (root?.name === omName && name && ts.isStringLiteralLike(name) && body) {
+                if (ts.isFunctionLike(body))
+                    outlines.set(name.text, outlineBody(body, imported));
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return outlines;
+}
+/** How long the child gets to import every file before it is killed and reported. */
+const DISCOVER_TIMEOUT_MS = 30_000;
+/**
+ * Absolute path of a sibling module, carrying 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.
+ */
+function siblingScript(name) {
+    const here = fileURLToPath(import.meta.url);
+    return path.join(path.dirname(here), `${name}${path.extname(here)}`);
+}
+/** Project an om's registration message onto the client-facing shape, folder name and all. */
+function toOmRegistration(m) {
+    return {
+        name: m.name,
+        file: m.file ?? "",
+        folderName: `${fsSafe(m.name)}-${omHash(m.name, m.file)}`,
+        ...(m.description ? { summary: m.description.summary } : {}),
+        ...(m.mcp ? { mcp: m.mcp } : {}),
+        ...(m.inputSchema ? { inputSchema: m.inputSchema } : {}),
+        ...(m.schemaError ? { unavailable: m.schemaError } : {}),
+    };
+}
+/**
+ * Import `files` in a throwaway child with `OMKIT_DISCOVER=1` and collect what they
+ * declare. Exposed separately from {@link discoverRegistrations} so the fork can be driven
+ * with an explicit file list — by tests, and by anything that already knows its candidates.
+ *
+ * Never rejects for user-code problems: an import failure, a crashed child, or a child
+ * that outstays its timeout all come back as warnings on an otherwise usable set.
+ */
+export function readRegistrations(files, opts = {}) {
+    if (files.length === 0)
+        return Promise.resolve({ oms: [], actions: [], warnings: [] });
+    const timeoutMs = opts.timeoutMs ?? DISCOVER_TIMEOUT_MS;
+    return new Promise((resolve) => {
+        const oms = [];
+        const warnings = [];
+        const child = fork(siblingScript("discover-child"), [], {
+            execArgv: ["--import", tsxLoader],
+            cwd: opts.cwd ?? path.dirname(files[0]),
+            env: { ...process.env, OMKIT_DISCOVER: "1" },
+            stdio: ["ignore", "pipe", "pipe", "ipc"],
+        });
+        let settled = false;
+        const finish = (actions) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill();
+            resolve({ oms, actions, warnings });
+        };
+        const timer = setTimeout(() => {
+            warnings.push(`discovery timed out after ${timeoutMs}ms`);
+            finish([]);
+        }, timeoutMs);
+        child.on("message", (message) => {
+            const m = message;
+            if (m.kind === "om-registration")
+                oms.push(toOmRegistration(m));
+            else if (m.kind === "actions") {
+                warnings.push(...m.warnings);
+                finish(m.actions);
+            }
+        });
+        // A child that dies before reporting still yields whatever streamed in before it did.
+        child.on("close", () => finish([]));
+        child.on("error", (e) => {
+            warnings.push(`discovery child failed: ${e.message}`);
+            finish([]);
+        });
+        child.send({ kind: "scan", files });
+    });
+}
+/**
+ * The full pass: the AST scan picks the candidate files — it stays the only cheap,
+ * never-executing phase — then {@link readRegistrations} imports just those. AST warnings
+ * are carried through so nothing is lost between the two phases.
+ */
+export async function discoverRegistrations(tsconfigPath, opts = {}) {
+    const ast = discover(tsconfigPath);
+    const files = [...new Set([...ast.oms.map((o) => o.file), ...ast.actions.map((a) => a.file)])];
+    const set = await readRegistrations(files, {
+        cwd: path.dirname(path.resolve(tsconfigPath)),
+        ...opts,
+    });
+    return { ...set, warnings: [...ast.warnings, ...set.warnings], registry: ast };
+}
 /**
  * Load and validate the tsconfig, throwing on a fatal config problem — a missing/unparseable file,
  * or a config-level error (bad compilerOptions, an unresolvable `extends`). The benign "no inputs

package/dist/client/index.d.ts

@@ -1,6 +1,7 @@
 import type { OmkitClient } from "./types.ts";
+export { readRegistrations, discoverRegistrations } from "./discovery.ts";
 export type { OmkitClient, RunSession, RunOptions, InspectOptions, Verdict, Diagnostic, PromptRequest, RunEvents, } from "./types.ts";
-export type { Registry, DiscoveredOm, DiscoveredAction } from "./registry.ts";
+export type { Registry, DiscoveredOm, DiscoveredAction, Registration, OmRegistration, ActionRegistration, RegistrationSet, } from "./registry.ts";
 import type { InspectOptions } from "./types.ts";
 /** Configuration for a client — the project's `tsconfig.omkit.json` and optional debugging. */
 export interface OmkitConfig {

package/dist/client/index.js

@@ -1,6 +1,7 @@
-import { discover } from "./discovery.js";
+import { discover, discoverRegistrations } from "./discovery.js";
 import { runOm, spawnBare } from "./runner.js";
 import { runCheck } from "./check.js";
+export { readRegistrations, discoverRegistrations } from "./discovery.js";
 /** Build the headless engine: discovery + supervised/bare run + typecheck over one config. */
 export function createOmkitClient(config) {
     // A per-call inspect wins; the client's construction-time inspect is the fallback.
@@ -11,6 +12,7 @@ export function createOmkitClient(config) {
     return {
         tsconfig: config.tsconfig,
         discover: async () => discover(config.tsconfig),
+        discoverRegistrations: async () => discoverRegistrations(config.tsconfig),
         run: (omFile, opts) => runOm(omFile, withInspect(opts)),
         runBare: (omFile, opts) => spawnBare(omFile, withInspect(opts)),
         check: async () => runCheck(config.tsconfig),

package/dist/client/outline.d.ts

@@ -0,0 +1,35 @@
+import ts from "typescript";
+import type { OmCall } from "./registry.ts";
+/**
+ * Every identifier a file binds through an import — the whole allow-list for the outline.
+ * An action always arrives by import (`omkit/actions`, or a local actions module), so
+ * "was imported" is a cheap stand-in for "is a step" that never needs the type checker.
+ */
+export declare function importedNames(sf: ts.SourceFile): ReadonlySet<string>;
+/** A fluent chain resolved down to the call that starts it: `a(…).b().c()` → the `a(…)`. */
+export interface ChainRoot {
+    /** The identifier the chain is rooted in. */
+    readonly name: string;
+    /** The base call itself, so a caller can read its arguments. */
+    readonly call: ts.CallExpression;
+    /** Every call in the chain, outermost first. */
+    readonly calls: readonly ts.CallExpression[];
+}
+/**
+ * Walk a fluent chain down from any of its calls to the identifier call at its root.
+ *
+ * Descends through `.expression` rather than climbing through `.parent`: a `SourceFile` from
+ * `ts.createProgram` only has parent pointers once its file has been bound, so climbing would
+ * work or not depending on whether the caller happened to ask for diagnostics first.
+ */
+export declare function chainRoot(node: ts.CallExpression): ChainRoot | undefined;
+/**
+ * A static sketch of what an om body calls: imported identifiers invoked directly inside
+ * `.run(body)`, in source order, each paired with the `.tag("…")` from its own fluent chain.
+ *
+ * Deliberately an approximation, and labelled as one wherever it is rendered. A conditional
+ * call appears unconditionally, a loop appears once, an action picked dynamically does not
+ * appear at all, and a call made inside a module-level helper is invisible — the walk does
+ * not follow indirection. It answers "roughly what happens in here" and nothing stronger.
+ */
+export declare function outlineBody(body: ts.Node, imported: ReadonlySet<string>): OmCall[];

package/dist/client/outline.js

@@ -0,0 +1,100 @@
+import ts from "typescript";
+/**
+ * Every identifier a file binds through an import — the whole allow-list for the outline.
+ * An action always arrives by import (`omkit/actions`, or a local actions module), so
+ * "was imported" is a cheap stand-in for "is a step" that never needs the type checker.
+ */
+export function importedNames(sf) {
+    const names = new Set();
+    for (const stmt of sf.statements) {
+        if (!ts.isImportDeclaration(stmt) || !stmt.importClause)
+            continue;
+        const clause = stmt.importClause;
+        if (clause.name)
+            names.add(clause.name.text);
+        const bindings = clause.namedBindings;
+        if (!bindings)
+            continue;
+        if (ts.isNamespaceImport(bindings))
+            names.add(bindings.name.text);
+        else
+            for (const el of bindings.elements)
+                names.add(el.name.text);
+    }
+    return names;
+}
+/**
+ * Walk a fluent chain down from any of its calls to the identifier call at its root.
+ *
+ * Descends through `.expression` rather than climbing through `.parent`: a `SourceFile` from
+ * `ts.createProgram` only has parent pointers once its file has been bound, so climbing would
+ * work or not depending on whether the caller happened to ask for diagnostics first.
+ */
+export function chainRoot(node) {
+    const calls = [];
+    let current = node;
+    while (ts.isCallExpression(current)) {
+        calls.push(current);
+        const callee = current.expression;
+        if (ts.isPropertyAccessExpression(callee)) {
+            current = callee.expression;
+            continue;
+        }
+        if (ts.isIdentifier(callee))
+            return { name: callee.text, call: current, calls };
+        return undefined;
+    }
+    return undefined;
+}
+/**
+ * A static sketch of what an om body calls: imported identifiers invoked directly inside
+ * `.run(body)`, in source order, each paired with the `.tag("…")` from its own fluent chain.
+ *
+ * Deliberately an approximation, and labelled as one wherever it is rendered. A conditional
+ * call appears unconditionally, a loop appears once, an action picked dynamically does not
+ * appear at all, and a call made inside a module-level helper is invisible — the walk does
+ * not follow indirection. It answers "roughly what happens in here" and nothing stronger.
+ */
+export function outlineBody(body, imported) {
+    const calls = [];
+    const seen = new Set();
+    const visit = (node) => {
+        const chain = ts.isCallExpression(node) ? chainRoot(node) : undefined;
+        if (chain && imported.has(chain.name)) {
+            const tag = tagOf(chain);
+            // Name and tag together are the identity: three `command` calls with distinct tags are
+            // three steps, while the same call written twice is one.
+            const key = `${chain.name} ${tag ?? ""}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                calls.push(tag === undefined ? { name: chain.name } : { name: chain.name, tag });
+            }
+            // The chain's own spine is now accounted for; only its arguments can hold further steps.
+            // Walking it again would re-enter each inner call and record the same step repeatedly.
+            for (const call of chain.calls)
+                for (const arg of call.arguments)
+                    visit(arg);
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(body);
+    return calls;
+}
+/**
+ * The `.tag("…")` on a chain, taken nearest its root. `calls` is outermost-first, so the last
+ * match is the innermost — the tag attached directly to the action rather than to something
+ * further along the chain.
+ */
+function tagOf(chain) {
+    let tag;
+    for (const call of chain.calls) {
+        const callee = call.expression;
+        if (!ts.isPropertyAccessExpression(callee) || callee.name.text !== "tag")
+            continue;
+        const arg = call.arguments[0];
+        if (arg && ts.isStringLiteralLike(arg))
+            tag = arg.text;
+    }
+    return tag;
+}

package/dist/client/registry.d.ts

@@ -1,3 +1,10 @@
+import type { JsonSchema } from "../core/schema-json.ts";
+/** One step in an om's static outline: an imported call, with the tag authored on its chain. */
+export interface OmCall {
+    readonly name: string;
+    /** The `.tag("…")` literal from the same fluent chain, when the author wrote one. */
+    readonly tag?: string;
+}
 /** A runnable om discovered from a top-level `om("name", …)` call. */
 export interface DiscoveredOm {
     /** The om's name — its first string argument. */
@@ -6,6 +13,12 @@ export interface DiscoveredOm {
     readonly file: string;
     /** 1-based line of the `om(...)` call (informational). */
     readonly line: number;
+    /**
+     * A static approximation of what the body calls, in source order. Absent when the walk
+     * found nothing recognisable. Never a contract — see {@link import("./outline.ts").outlineBody}
+     * for what it deliberately cannot see.
+     */
+    readonly calls?: readonly OmCall[];
 }
 /** An inspectable action discovered from an exported `action("name")…` builder. */
 export interface DiscoveredAction {
@@ -27,3 +40,49 @@ export interface Registry {
     /** Non-fatal diagnostics (type errors, unresolved config) — discovery never throws for these. */
     readonly warnings: string[];
 }
+/**
+ * What importing a file in discovery mode reveals — the metadata the AST scan cannot see,
+ * because `.describe()`, `.args()` and `.mcp()` only have values once the module has been
+ * evaluated. Produced by `discoverRegistrations`, never by `discover`.
+ */
+export interface Registration {
+    readonly name: string;
+    /** Absolute path of the defining file. */
+    readonly file: string;
+    /** The `.describe({ summary })` line, when the author wrote one. */
+    readonly summary?: string;
+    /** Present only when the author called `.mcp()`. Absent ⇒ not exposed over MCP. */
+    readonly mcp?: {
+        readonly mode: "settling" | "long-lived";
+    };
+    /** The declared args as JSON Schema. Absent when none were declared. */
+    readonly inputSchema?: JsonSchema;
+    /** Why this entry cannot be called — currently only "its schema would not convert". */
+    readonly unavailable?: string;
+}
+export interface OmRegistration extends Registration {
+    /**
+     * `<name>-<hash8>` — the run's log folder, derived from the name and the defining file
+     * by the same rule the runtime uses, so it is known before the om has ever run.
+     */
+    readonly folderName: string;
+}
+export interface ActionRegistration extends Registration {
+    /** The exported binding (`export const <exportName> = action(...)`). */
+    readonly exportName: string;
+}
+/** The result of importing a project's candidate files in discovery mode. */
+export interface RegistrationSet {
+    readonly oms: OmRegistration[];
+    readonly actions: ActionRegistration[];
+    /** Import failures and AST warnings — registration discovery never throws for these. */
+    readonly warnings: string[];
+    /**
+     * The AST scan that chose the candidate files, carried through so a caller wanting both
+     * halves — the outline and capability flags from the AST, the summaries and schemas from
+     * the fork — does not pay to build a second TypeScript program.
+     *
+     * Absent when the fork was driven with an explicit file list, since there was no scan.
+     */
+    readonly registry?: Registry;
+}

package/dist/client/runner.d.ts

@@ -1,4 +1,10 @@
 import type { RunSession, RunOptions, InspectOptions } from "./types.ts";
+/**
+ * The `tsx` loader, resolved to an absolute URL from omkit's own location. Resolving it here
+ * (not as the bare specifier `--import tsx`) keeps the child's `tsx` independent of its cwd —
+ * a run in any directory still finds the loader shipped with omkit.
+ */
+export declare const tsxLoader: string;
 /**
  * The inspector flag to prepend to a child's `execArgv` — empty when no inspector is requested.
  * Plain `--inspect` opens the port without stopping, so the child still installs its teardown
@@ -10,6 +16,12 @@ export declare function inspectArgs(inspect: InspectOptions | undefined): string
  * `OMKIT_SUPERVISED=1` flips the child into channel mode (see core/interaction.ts), and its
  * IPC channel is wrapped into a {@link RunSession}. stdout/stderr are piped (not inherited)
  * so the child never writes to the supervisor's terminal.
+ *
+ * The path is canonicalised first, and that is load-bearing rather than tidy — see
+ * {@link canonicalPath}. The child resolves `"omkit"` through `node_modules`, which is a
+ * symlink Node realpaths to the package's true on-disk name; forking with any other spelling
+ * of the same file gives the child a *second* copy of omkit, with its own module state. The
+ * run then exists in one copy while the om's actions look for it in the other.
  */
 export declare function runOm(omFile: string, opts?: RunOptions): RunSession;
 /**

package/dist/client/runner.js

@@ -1,12 +1,13 @@
 import { fork } from "node:child_process";
 import path from "node:path";
+import { canonicalPath } from "../foundation/canonicalPath.js";
 import { createChannel } from "./channel.js";
 /**
  * The `tsx` loader, resolved to an absolute URL from omkit's own location. Resolving it here
  * (not as the bare specifier `--import tsx`) keeps the child's `tsx` independent of its cwd —
  * a run in any directory still finds the loader shipped with omkit.
  */
-const tsxLoader = import.meta.resolve("tsx");
+export const tsxLoader = import.meta.resolve("tsx");
 /**
  * The inspector flag to prepend to a child's `execArgv` — empty when no inspector is requested.
  * Plain `--inspect` opens the port without stopping, so the child still installs its teardown
@@ -22,12 +23,19 @@ export function inspectArgs(inspect) {
  * `OMKIT_SUPERVISED=1` flips the child into channel mode (see core/interaction.ts), and its
  * IPC channel is wrapped into a {@link RunSession}. stdout/stderr are piped (not inherited)
  * so the child never writes to the supervisor's terminal.
+ *
+ * The path is canonicalised first, and that is load-bearing rather than tidy — see
+ * {@link canonicalPath}. The child resolves `"omkit"` through `node_modules`, which is a
+ * symlink Node realpaths to the package's true on-disk name; forking with any other spelling
+ * of the same file gives the child a *second* copy of omkit, with its own module state. The
+ * run then exists in one copy while the om's actions look for it in the other.
  */
 export function runOm(omFile, opts = {}) {
-    const child = fork(omFile, [], {
+    const file = canonicalPath(omFile);
+    const child = fork(file, [], {
         execArgv: [...inspectArgs(opts.inspect), "--import", tsxLoader],
-        cwd: opts.cwd ?? path.dirname(omFile),
-        env: { ...process.env, OMKIT_SUPERVISED: "1" },
+        cwd: opts.cwd ?? path.dirname(file),
+        env: { ...process.env, OMKIT_SUPERVISED: "1", ...opts.env },
         stdio: ["ignore", "pipe", "pipe", "ipc"],
     });
     const transport = {
@@ -57,11 +65,12 @@ export function runOm(omFile, opts = {}) {
 export function spawnBare(omFile, opts = {}) {
     // A bare run is unsupervised even if the parent process happens to carry the flag (e.g. a
     // test runner spawned from inside a supervised run) — clear it so the child stays bare.
-    const env = { ...process.env };
+    const env = { ...process.env, ...opts.env };
     delete env.OMKIT_SUPERVISED;
-    const child = fork(omFile, [], {
+    const file = canonicalPath(omFile);
+    const child = fork(file, [], {
         execArgv: [...inspectArgs(opts.inspect), "--import", tsxLoader],
-        cwd: opts.cwd ?? path.dirname(omFile),
+        cwd: opts.cwd ?? path.dirname(file),
         stdio: "inherit",
         env,
     });

package/dist/client/types.d.ts

@@ -1,6 +1,6 @@
 import type { LogEntry } from "../foundation/LogEntry.ts";
 import type { PromptSpec } from "../core/interaction.ts";
-import type { Registry } from "./registry.ts";
+import type { Registry, RegistrationSet } from "./registry.ts";
 /** A run's terminal verdict, resolved when the child settles. */
 export interface Verdict {
     readonly ok: boolean;
@@ -27,6 +27,8 @@ export interface RunOptions {
     readonly cwd?: string;
     /** When set, fork the child with the Node inspector open so a debugger can attach. */
     readonly inspect?: InspectOptions;
+    /** Extra environment for the child, merged over the parent's — how `OMKIT_ARGS` travels. */
+    readonly env?: Record<string, string>;
 }
 /** A prompt the running om is waiting on — surfaced to the frontend, answered via `answer`. */
 export interface PromptRequest {
@@ -57,6 +59,12 @@ export interface OmkitClient {
     readonly tsconfig: string;
     /** Statically scan the project's `tsconfig.omkit.json` for oms and actions. */
     discover(): Promise<Registry>;
+    /**
+     * Read what the project's oms and actions declare, by importing them in a throwaway
+     * child. Unlike {@link OmkitClient.discover} this executes user code, so it is never on
+     * the `omkit ls` path — only a caller that needs real schemas should ask for it.
+     */
+    discoverRegistrations(): Promise<RegistrationSet>;
     /** Spawn an om file as a supervised child and return its live session (the Ink UI drives this). */
     run(omFile: string, opts?: RunOptions): RunSession;
     /** Spawn an om file bare — inherited stdio, no supervision — and resolve its exit code. */