omkit 0.4.8 → 0.8.0

package/dist/mcp/validate.js

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

package/dist/mcp/verdict.d.ts

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

package/dist/mcp/verdict.js

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

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

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

package/dist/output/artifact/ArtifactStore.js

@@ -0,0 +1,49 @@
+import path from "node:path";
+const MIME_BY_EXT = {
+    ".json": "application/json",
+    ".jsonl": "application/x-ndjson",
+    ".log": "text/plain",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".html": "text/html",
+    ".csv": "text/csv",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".pdf": "application/pdf",
+    ".zip": "application/zip",
+};
+/**
+ * The run's curated artifacts — the files an om labelled via `ctx.artifact`, in
+ * registration order. Holds no I/O: the om already wrote the file, this records what it
+ * means. Unregistered files stay in the run folder and stay listed by anything
+ * enumerating it; curation raises signal, it does not gate access.
+ */
+export class ArtifactStore {
+    records = [];
+    register(name, file, nodeId, opts = {}) {
+        // `file` is documented absolute; a caller that passes a relative path still gets
+        // one back — resolved against process.cwd(), same base `path.resolve` uses by
+        // default — so every consumer (the return value, the timeline message, the
+        // on-disk rollups) carries a path that means the same thing without them.
+        const resolved = path.resolve(file);
+        const record = {
+            name,
+            file: resolved,
+            nodeId,
+            mime: opts.mime ?? mimeOf(resolved),
+            ...(opts.description === undefined ? {} : { description: opts.description }),
+        };
+        this.records.push(record);
+        return record;
+    }
+    all() {
+        return this.records;
+    }
+}
+function mimeOf(file) {
+    return MIME_BY_EXT[path.extname(file).toLowerCase()] ?? "application/octet-stream";
+}

package/dist/output/folder/RunFolder.d.ts

@@ -12,10 +12,32 @@ export declare class RunFolder {
     constructor(runName: string, hash: string);
     /** `<name>-<hash8>` — the run's folder name, unique per (defining file, name). */
     name(): string;
-    /** The absolute run directory, computed once and created on first access. */
+    /**
+     * The absolute run directory — claimed on first access, stable thereafter.
+     *
+     * Claiming and knowing the path are the same act: the directory is what makes a run's
+     * identity exclusive, so there is no meaningful "what would the path be" to answer
+     * before it exists.
+     */
     path(): string;
     /** Absolute path to `name` inside the run folder; ensures the folder exists. */
     file(name: string): string;
     /** Create the run folder synchronously (idempotent). */
     ensure(): void;
+    /**
+     * Take exclusive ownership of a `<date>/<time>` directory.
+     *
+     * `hms` has second resolution, so two runs of the same om starting within one second
+     * would otherwise share a folder — and that is not merely "the later one wins":
+     * `RawStream` opens `raw.jsonl` with `flags: "w"`, so two live runs both truncate it and
+     * then write at their own offsets, leaving bytes that are not valid JSONL. The MCP
+     * server makes this easy to reach, since `start_om` can put two children in flight.
+     *
+     * Finer timestamps would only lower the odds. `mkdirSync` without `recursive` throws
+     * `EEXIST` **atomically**, and that atomicity holds between processes — so the directory
+     * creation is itself the lock. The common case keeps a clean `16-39-29`; only a real
+     * collision produces `16-39-29-02`, zero-padded so lexical order stays chronological
+     * (which is what `latest` relies on).
+     */
+    private claim;
 }

package/dist/output/folder/RunFolder.js

@@ -1,7 +1,10 @@
 import { mkdirSync } from "node:fs";
 import path from "node:path";
-import { ymd, hms } from "../../foundation/format.js";
+import { ymd, hms, pad } from "../../foundation/format.js";
 import { fsSafe } from "../../foundation/fsSafe.js";
+import { newUuid, shortId } from "../../foundation/ids.js";
+/** Suffixed attempts (`-02` … `-99`) before falling back to a random, certainly-unique one. */
+const MAX_NUMBERED_ATTEMPTS = 99;
 /**
  * Owns this run's single output directory — `logs/<name>-<hash>/<date>/<time>/` —
  * where `raw.jsonl`, the per-action `.log` files, rollups, and `result.json` all
@@ -21,24 +24,65 @@ export class RunFolder {
     name() {
         return `${fsSafe(this.runName)}-${this.hash}`;
     }
-    /** The absolute run directory, computed once and created on first access. */
+    /**
+     * The absolute run directory — claimed on first access, stable thereafter.
+     *
+     * Claiming and knowing the path are the same act: the directory is what makes a run's
+     * identity exclusive, so there is no meaningful "what would the path be" to answer
+     * before it exists.
+     */
     path() {
-        if (this.dir)
-            return this.dir;
-        const now = new Date();
-        this.dir = path.resolve("logs", this.name(), ymd(now), hms(now, "-"));
+        if (!this.dir)
+            this.claim();
         return this.dir;
     }
     /** Absolute path to `name` inside the run folder; ensures the folder exists. */
     file(name) {
-        this.ensure();
         return path.join(this.path(), name);
     }
     /** Create the run folder synchronously (idempotent). */
     ensure() {
-        if (this.ensured)
-            return;
-        mkdirSync(this.path(), { recursive: true });
-        this.ensured = true;
+        this.path();
+    }
+    /**
+     * Take exclusive ownership of a `<date>/<time>` directory.
+     *
+     * `hms` has second resolution, so two runs of the same om starting within one second
+     * would otherwise share a folder — and that is not merely "the later one wins":
+     * `RawStream` opens `raw.jsonl` with `flags: "w"`, so two live runs both truncate it and
+     * then write at their own offsets, leaving bytes that are not valid JSONL. The MCP
+     * server makes this easy to reach, since `start_om` can put two children in flight.
+     *
+     * Finer timestamps would only lower the odds. `mkdirSync` without `recursive` throws
+     * `EEXIST` **atomically**, and that atomicity holds between processes — so the directory
+     * creation is itself the lock. The common case keeps a clean `16-39-29`; only a real
+     * collision produces `16-39-29-02`, zero-padded so lexical order stays chronological
+     * (which is what `latest` relies on).
+     */
+    claim() {
+        const now = new Date();
+        const parent = path.resolve("logs", this.name(), ymd(now));
+        mkdirSync(parent, { recursive: true });
+        const base = hms(now, "-");
+        for (let attempt = 0; attempt <= MAX_NUMBERED_ATTEMPTS; attempt += 1) {
+            // A random suffix as the last resort: bounded loops beat an unbounded one, and a
+            // hundred collisions inside one second means something stranger is going on.
+            const suffix = attempt === 0
+                ? ""
+                : attempt === MAX_NUMBERED_ATTEMPTS
+                    ? `-${shortId(newUuid())}`
+                    : `-${pad(attempt + 1)}`;
+            const candidate = path.join(parent, `${base}${suffix}`);
+            try {
+                mkdirSync(candidate); // deliberately not recursive — EEXIST is the lock
+                this.dir = candidate;
+                this.ensured = true;
+                return;
+            }
+            catch (e) {
+                if (e.code !== "EEXIST")
+                    throw e;
+            }
+        }
     }
 }

package/dist/output/writers/views.d.ts

@@ -21,6 +21,14 @@ export interface NodeView {
     readonly logFile: string;
     readonly children: readonly NodeView[];
 }
+/** A curated artifact, as projected into `result.json`. Data-only — no core import. */
+export interface ArtifactView {
+    readonly name: string;
+    /** Absolute path to the file. */
+    readonly file: string;
+    readonly description?: string;
+    readonly mime: string;
+}
 export interface RunView {
     readonly ok: boolean;
     readonly failures: ReadonlyArray<{
@@ -37,4 +45,6 @@ export interface RunView {
     /** Absolute path to `raw.jsonl`. */
     readonly rawStream: string;
     readonly root: NodeView;
+    /** Files the run labelled via `ctx.artifact`, in registration order. */
+    readonly artifacts: readonly ArtifactView[];
 }

package/dist/skill/file.d.ts

@@ -0,0 +1,26 @@
+/** Where the skill lands, relative to the project root that owns the tsconfig. */
+export declare const SKILL_RELATIVE_PATH: string;
+/**
+ * The `description` written into a file that does not exist yet.
+ *
+ * This field is the skill's loading trigger, so its wording decides whether an assistant reads
+ * the file at the right moment. A generated summary of contents ("lists 2 oms…") would be the
+ * wrong shape — the field has to say *when to use this*. So it is authored, and this is only
+ * the starting point: {@link readExisting} preserves whatever the author changes it to.
+ */
+export declare const DEFAULT_DESCRIPTION = "Runnable workflows in this repo (oms and actions) \u2014 what each does, its arguments, and how to run it. Load before running or debugging any project workflow.";
+/** What a previously generated file still has to say for itself. */
+export interface ExistingSkill {
+    /** The `description:` value, verbatim — continuation lines and all. */
+    readonly description?: string;
+    /** The `registry-hash` from the generated-by marker, when the file carries one. */
+    readonly hash?: string;
+}
+/**
+ * Read back the two things a regeneration must not lose: the authored description, and the
+ * hash to compare against. A missing or unreadable file is not an error — it is the "generate
+ * fresh" case, and returns an empty result.
+ */
+export declare function readExisting(file: string): ExistingSkill;
+/** Write the skill, creating its directory. The parent may not exist on a first generation. */
+export declare function writeSkill(file: string, content: string): void;

package/dist/skill/file.js

@@ -0,0 +1,58 @@
+import fs from "node:fs";
+import path from "node:path";
+import { SKILL_NAME } from "./render.js";
+/** Where the skill lands, relative to the project root that owns the tsconfig. */
+export const SKILL_RELATIVE_PATH = path.join(".claude", "skills", SKILL_NAME, "SKILL.md");
+/**
+ * The `description` written into a file that does not exist yet.
+ *
+ * This field is the skill's loading trigger, so its wording decides whether an assistant reads
+ * the file at the right moment. A generated summary of contents ("lists 2 oms…") would be the
+ * wrong shape — the field has to say *when to use this*. So it is authored, and this is only
+ * the starting point: {@link readExisting} preserves whatever the author changes it to.
+ */
+export const DEFAULT_DESCRIPTION = "Runnable workflows in this repo (oms and actions) — what each does, its arguments, and how to run it. Load before running or debugging any project workflow.";
+/**
+ * Read back the two things a regeneration must not lose: the authored description, and the
+ * hash to compare against. A missing or unreadable file is not an error — it is the "generate
+ * fresh" case, and returns an empty result.
+ */
+export function readExisting(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return {};
+    }
+    const hash = /registry-hash:\s*([0-9a-f]{8})/.exec(text)?.[1];
+    const description = frontmatterDescription(text);
+    return { ...(description !== undefined ? { description } : {}), ...(hash ? { hash } : {}) };
+}
+/**
+ * Pull `description` out of the leading frontmatter, keeping any folded continuation lines
+ * exactly as written — they are re-emitted verbatim, so a wrapped description survives
+ * regeneration byte-for-byte instead of being reflowed into one long line.
+ */
+function frontmatterDescription(text) {
+    const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1];
+    if (block === undefined)
+        return undefined;
+    const lines = block.split(/\r?\n/);
+    const start = lines.findIndex((l) => l.startsWith("description:"));
+    if (start === -1)
+        return undefined;
+    const value = [lines[start].slice("description:".length).trimStart()];
+    // A continuation is any indented line; the next unindented line starts a new key.
+    for (const line of lines.slice(start + 1)) {
+        if (!/^\s+\S/.test(line))
+            break;
+        value.push(line);
+    }
+    return value.join("\n");
+}
+/** Write the skill, creating its directory. The parent may not exist on a first generation. */
+export function writeSkill(file, content) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, content, "utf8");
+}

package/dist/skill/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The generated-skill layer: turn a project's registrations into `.claude/skills/omkit-runs/`.
+ *
+ * Split so that everything except {@link module:./file.ts} is pure — the model and the renderer
+ * take data and return data, which is what makes determinism testable without touching a disk.
+ */
+export { buildSkillModel, registryHash } from "./model.ts";
+export type { SkillCall, SkillEntry, SkillModel } from "./model.ts";
+export { renderSkill, generatedBy, SKILL_NAME } from "./render.ts";
+export { readExisting, writeSkill, DEFAULT_DESCRIPTION, SKILL_RELATIVE_PATH } from "./file.ts";
+export type { ExistingSkill } from "./file.ts";

package/dist/skill/index.js

@@ -0,0 +1,9 @@
+/**
+ * The generated-skill layer: turn a project's registrations into `.claude/skills/omkit-runs/`.
+ *
+ * Split so that everything except {@link module:./file.ts} is pure — the model and the renderer
+ * take data and return data, which is what makes determinism testable without touching a disk.
+ */
+export { buildSkillModel, registryHash } from "./model.js";
+export { renderSkill, generatedBy, SKILL_NAME } from "./render.js";
+export { readExisting, writeSkill, DEFAULT_DESCRIPTION, SKILL_RELATIVE_PATH } from "./file.js";

package/dist/skill/model.d.ts

@@ -0,0 +1,55 @@
+import type { McpMode } from "../core/types.ts";
+import type { JsonSchema } from "../core/schema-json.ts";
+import type { OmCall, RegistrationSet, Registry } from "../client/registry.ts";
+/** One step in a rendered outline. Structurally an {@link OmCall}; named for the skill's vocabulary. */
+export type SkillCall = OmCall;
+/** One runnable thing the generated skill documents. */
+export interface SkillEntry {
+    readonly kind: "om" | "action";
+    readonly name: string;
+    /** Project-relative, forward slashes on every platform — so the file does not churn per-OS. */
+    readonly file: string;
+    readonly mode: McpMode;
+    /** The `.describe({ summary })` line. Absent when the author wrote none; never invented. */
+    readonly summary?: string;
+    /** A one-line sketch of the declared args, from {@link shapeHint}. */
+    readonly argHint?: string;
+    /** The raw schema, present only when `shapeHint` could not sketch it (per C7). */
+    readonly argSchema?: JsonSchema;
+    /** The static outline of the body. Absent when the walk found nothing recognisable. */
+    readonly calls?: readonly SkillCall[];
+    /** Why this entry cannot be called — carried through from discovery, rendered as a warning. */
+    readonly unavailable?: string;
+    /** Actions only: the exported binding a host om imports. */
+    readonly exportName?: string;
+    /** Actions only: true when the chain includes `.ref<…>()`, so it publishes a capability. */
+    readonly publishesCapability?: boolean;
+}
+/** Everything the renderer needs, plus the hash that detects drift against it. */
+export interface SkillModel {
+    readonly oms: readonly SkillEntry[];
+    readonly actions: readonly SkillEntry[];
+    /** First 8 hex of sha256 over the registry data below — never over the rendered markdown. */
+    readonly hash: string;
+}
+/**
+ * Fold a project's registrations and its AST scan into the model the skill renders from.
+ *
+ * The two inputs answer different halves: the fork knows summaries, modes, and arg schemas
+ * (values that only exist once a module has been evaluated), while the AST scan knows the
+ * body outline and whether an action publishes a capability. Neither alone is enough.
+ *
+ * Only `.mcp()`-marked entries survive — exposure is opt-in, exactly as it is for the MCP
+ * server, so generating a skill can never widen what an assistant will attempt.
+ */
+export declare function buildSkillModel(registrations: RegistrationSet, registry: Registry, root: string): SkillModel;
+/**
+ * The staleness hash: first 8 hex of sha256 over the registry data, deliberately **not** over
+ * the rendered markdown, so reformatting the file does not read as drift.
+ *
+ * The outline is included even though the spec's list of inputs predates it: an edited om body
+ * changes what the file claims the run does, and leaving that undetected is exactly the silent
+ * drift the hash exists to catch. Keys are sorted before hashing so a schema serialised in a
+ * different property order cannot masquerade as a change.
+ */
+export declare function registryHash(entries: readonly SkillEntry[]): string;

package/dist/skill/model.js

@@ -0,0 +1,116 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { shapeHint } from "../core/schema-hint.js";
+/**
+ * Fold a project's registrations and its AST scan into the model the skill renders from.
+ *
+ * The two inputs answer different halves: the fork knows summaries, modes, and arg schemas
+ * (values that only exist once a module has been evaluated), while the AST scan knows the
+ * body outline and whether an action publishes a capability. Neither alone is enough.
+ *
+ * Only `.mcp()`-marked entries survive — exposure is opt-in, exactly as it is for the MCP
+ * server, so generating a skill can never widen what an assistant will attempt.
+ */
+export function buildSkillModel(registrations, registry, root) {
+    const outlines = new Map(registry.oms.map((o) => [key(o.name, o.file), o.calls]));
+    const capabilities = new Map(registry.actions.map((a) => [key(a.name, a.file), a.publishesCapability]));
+    const oms = registrations.oms
+        .filter(isExposed)
+        .map((om) => omEntry(om, outlines.get(key(om.name, om.file)), root))
+        .sort(byName);
+    const actions = registrations.actions
+        .filter(isExposed)
+        .map((a) => actionEntry(a, capabilities.get(key(a.name, a.file)), root))
+        .sort(byName);
+    return { oms, actions, hash: registryHash([...oms, ...actions]) };
+}
+function isExposed(r) {
+    return r.mcp !== undefined;
+}
+/** Identity for cross-referencing the two discovery passes: an om is its name in its file. */
+function key(name, file) {
+    return `${name}\0${path.resolve(file)}`;
+}
+/** Alphabetical by name, then by file — so two same-named oms in different files stay ordered. */
+function byName(a, b) {
+    return a.name.localeCompare(b.name) || a.file.localeCompare(b.file);
+}
+function omEntry(om, calls, root) {
+    return {
+        kind: "om",
+        name: om.name,
+        file: relative(om.file, root),
+        mode: om.mcp?.mode ?? "settling",
+        ...describeArgs(om.inputSchema),
+        ...(om.summary ? { summary: om.summary } : {}),
+        ...(calls?.length ? { calls } : {}),
+        ...(om.unavailable ? { unavailable: om.unavailable } : {}),
+    };
+}
+function actionEntry(action, publishesCapability, root) {
+    return {
+        kind: "action",
+        name: action.name,
+        file: relative(action.file, root),
+        mode: action.mcp?.mode ?? "settling",
+        exportName: action.exportName,
+        ...(publishesCapability ? { publishesCapability: true } : {}),
+        ...describeArgs(action.inputSchema),
+        ...(action.summary ? { summary: action.summary } : {}),
+        ...(action.unavailable ? { unavailable: action.unavailable } : {}),
+    };
+}
+/**
+ * Sketch a schema, falling back to the schema itself. `shapeHint` is all-or-nothing by design,
+ * so a `undefined` return means the shape would have been misleading — the honest answer then
+ * is the raw JSON Schema the caller actually has to satisfy, not a partial sketch.
+ */
+function describeArgs(schema) {
+    if (!schema)
+        return {};
+    const hint = shapeHint(schema);
+    return hint === undefined ? { argSchema: schema } : { argHint: hint };
+}
+/** Project-relative with forward slashes; absolute only if the file lies outside the root. */
+function relative(file, root) {
+    const rel = path.relative(root, file);
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel))
+        return posix(file);
+    return posix(rel);
+}
+const posix = (p) => p.split(path.sep).join("/").split("\\").join("/");
+/**
+ * The staleness hash: first 8 hex of sha256 over the registry data, deliberately **not** over
+ * the rendered markdown, so reformatting the file does not read as drift.
+ *
+ * The outline is included even though the spec's list of inputs predates it: an edited om body
+ * changes what the file claims the run does, and leaving that undetected is exactly the silent
+ * drift the hash exists to catch. Keys are sorted before hashing so a schema serialised in a
+ * different property order cannot masquerade as a change.
+ */
+export function registryHash(entries) {
+    const material = entries.map((e) => [
+        e.kind,
+        e.name,
+        e.file,
+        e.mode,
+        e.summary ?? "",
+        e.exportName ?? "",
+        e.unavailable ?? "",
+        e.publishesCapability === true,
+        e.argSchema ?? e.argHint ?? "",
+        (e.calls ?? []).map((c) => [c.name, c.tag ?? ""]),
+    ]);
+    return createHash("sha256").update(canonical(material)).digest("hex").slice(0, 8);
+}
+/** JSON with object keys sorted at every depth, so key order can never change the hash. */
+function canonical(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(",")}}`;
+}

package/dist/skill/render.d.ts

@@ -0,0 +1,18 @@
+import type { SkillModel } from "./model.ts";
+/** The skill's directory name, and so the `name:` in its frontmatter. */
+export declare const SKILL_NAME = "omkit-runs";
+/**
+ * The marker line that carries the staleness hash. Written by {@link renderSkill} and read
+ * back by the file layer, so the two agree on one format rather than two regexes.
+ */
+export declare const generatedBy: (hash: string) => string;
+/**
+ * Render the model as the skill's markdown.
+ *
+ * Deterministic by construction: no timestamps, no absolute paths, no iteration over unordered
+ * collections — the model arrives sorted. A generated file that is committed and churns on
+ * every run is a file people stop reading.
+ */
+export declare function renderSkill(model: SkillModel, opts: {
+    description: string;
+}): string;