omkit 0.4.8 → 0.8.0

package/dist/skill/render.js

@@ -0,0 +1,133 @@
+/** The skill's directory name, and so the `name:` in its frontmatter. */
+export 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 const generatedBy = (hash) => `<!-- GENERATED by \`omkit skill\`. Do not edit. registry-hash: ${hash} -->`;
+/**
+ * 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 function renderSkill(model, opts) {
+    const lines = [
+        "---",
+        `name: ${SKILL_NAME}`,
+        `description: ${opts.description}`,
+        "---",
+        "",
+        "# omkit — runnable workflows",
+        "",
+        generatedBy(model.hash),
+        "",
+        ...howToRun(model),
+        ...workflows(model),
+        ...actions(model),
+        ...whereOutputLands(),
+    ];
+    return `${lines.join("\n")}\n`;
+}
+function howToRun(model) {
+    const example = model.oms[0]?.name ?? "<om>";
+    const withArgs = model.oms.find((o) => o.argHint !== undefined) ?? model.oms[0];
+    return [
+        "## How to run",
+        "",
+        "**Shell — always available:**",
+        "",
+        "```bash",
+        `npx omkit run ${example}`,
+        `OMKIT_ARGS='${exampleArgs(withArgs)}' npx omkit run ${withArgs?.name ?? example}`,
+        "```",
+        "",
+        "Arguments travel as one JSON object in `OMKIT_ARGS`. Anything an om declares but does not",
+        "receive is filled from the schema's defaults, and only then by asking.",
+        "",
+        '**MCP — if configured:** `run_om("<name>", { …args })` runs a settling workflow to',
+        "completion and returns its verdict; `start_om` starts a long-lived one and returns a run id",
+        "to poll with `get_run`, read with `tail_run`, and end with `cancel_run`.",
+        "",
+        "To wire it up: `claude mcp add omkit -- npx omkit mcp`",
+        "",
+        "At runtime `list_oms` is authoritative — this file is orientation, and can drift.",
+        "",
+    ];
+}
+/**
+ * A plausible `OMKIT_ARGS` value built from the first declared field, so the example shows the
+ * real shape rather than a placeholder. Falls back to an empty object when nothing is declared.
+ */
+function exampleArgs(entry) {
+    const match = entry?.argHint?.match(/\{ (\w+)\??: (\w+)/);
+    if (!match)
+        return "{}";
+    const [, field, type] = match;
+    const value = type === "string" ? '"…"' : type === "boolean" ? "false" : "0";
+    return `{"${field}":${value}}`;
+}
+function workflows(model) {
+    if (model.oms.length === 0) {
+        return ["## Workflows", "", "_None exposed. Mark an om with `.mcp()` to list it here._", ""];
+    }
+    return ["## Workflows", "", ...model.oms.flatMap((om) => entry(om, omHeading(om)))];
+}
+function actions(model) {
+    if (model.actions.length === 0)
+        return [];
+    return [
+        "## Actions",
+        "",
+        "An action is a step, not a run. It cannot execute on its own — omkit hosts it in a",
+        "generated om so it has a run to belong to, which means it gets its own run folder and",
+        "verdict like anything else.",
+        "",
+        ...model.actions.flatMap((a) => entry(a, `### \`${a.name}\``)),
+    ];
+}
+function omHeading(om) {
+    const mode = om.mode === "long-lived" ? "long-lived · `start_om` only, it does not finish" : "settling";
+    return `### \`${om.name}\` — ${mode}`;
+}
+function entry(e, heading) {
+    const lines = [heading, ""];
+    lines.push(e.summary ?? "_No summary. The author can add one with `.describe({ summary })`._", "");
+    lines.push(`- **Defined in:** \`${e.file}\``);
+    if (e.kind === "action" && e.exportName)
+        lines.push(`- **Exported as:** \`${e.exportName}\``);
+    if (e.argHint)
+        lines.push(`- **Args:** \`${e.argHint}\``);
+    if (e.calls?.length)
+        lines.push(`- **Calls:** ${e.calls.map(renderCall).join(" → ")}`);
+    if (e.publishesCapability) {
+        lines.push("- **Publishes a capability.** It hands a live handle to whatever runs after it. Run on", "  its own there is no downstream, so the handle goes nowhere — useful for a smoke test,", "  not for the thing the capability was for.");
+    }
+    if (e.unavailable)
+        lines.push(`- **Not callable:** ${e.unavailable}`);
+    if (e.argSchema) {
+        lines.push("- **Args** (no short form — the schema is the contract):", "", "```json");
+        lines.push(JSON.stringify(e.argSchema, null, 2));
+        lines.push("```");
+    }
+    lines.push("");
+    return lines;
+}
+const renderCall = (c) => c.tag ? `\`${c.name}\` [${c.tag}]` : `\`${c.name}\``;
+function whereOutputLands() {
+    return [
+        "## Where output lands",
+        "",
+        "`logs/<name>-<hash8>/<date>/<time>/` — `main.log`, `result.json`, `artifacts.log`,",
+        "`events.log`, `asserts.log`, `raw.jsonl`. A run's identity is its name plus its defining",
+        'file, so "the latest run of X" is always resolvable without parsing scrollback.',
+        "",
+        "## What the outlines above do and do not tell you",
+        "",
+        "**Calls** is a static reading of the body, not a trace. A conditional call is listed",
+        "unconditionally, a loop is listed once, an action chosen at runtime is not listed at all,",
+        'and a call made inside a helper function is invisible to it. Read it as "roughly what',
+        'happens in here" and read `result.json` for what actually did.',
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.4.8",
+  "version": "0.8.0",
   "description": "A tiny runtime for developer workflows: typed actions that pass runtime capabilities and emit typed events, under one run and one shared log. The operational/runtime layer to tskb's knowledge layer.",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,7 +10,8 @@
   },
   "files": [
     "dist",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "exports": {
     ".": {
@@ -52,11 +53,13 @@
     "developer-tools"
   ],
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "ink": "^7.1.1",
     "patch-console": "^2.0.0",
     "playwright-core": "^1.49.0",
     "react": "^19.2.8",
     "tsx": "4.23.1",
+    "zod": "^4.4.3",
     "zx": "^8.8.5"
   },
   "devDependencies": {