omkit 0.8.10 → 0.8.11

package/README.md

@@ -185,7 +185,7 @@ flakyBackgroundJob().result.catch((e) => console.warn("job failed, carrying on",
 
 Every action's output, events, asserts, snapshots, and lifecycle land on **one timeline** — streamed live to the terminal (curated milestones) and written to a per-run folder:
 
-- `result.json` — the run's tree, per-node status, verdict, and curated artifacts.
+- `result.json` — the run's tree, per-node status, verdict, and curated artifacts. Each node also carries what its definition declared about itself: the `.describe()` summary, the `.mcp()` exposure, and the `.args()` schema as JSON Schema.
 - `raw.jsonl` — every entry, machine-readable.
 - `main.log` + one `.log` per action — the human-readable timelines.
 - `events.log` / `asserts.log` / `snapshots.log` / `artifacts.log` — cross-cutting rollups.

package/dist/core/ActionRun.d.ts

@@ -3,7 +3,7 @@ import type { ActionRef } from "../foundation/ActionRef.ts";
 import type { LogStore } from "../output/log/LogStore.ts";
 import type { SnapshotStore } from "../output/snapshot/SnapshotStore.ts";
 import type { ArtifactStore } from "../output/artifact/ArtifactStore.ts";
-import type { Activity, Exec, InstanceEvents, NodeStatus } from "./types.ts";
+import type { ActionMeta, Activity, Exec, InstanceEvents, NodeStatus } from "./types.ts";
 /** Everything a node needs to exist, minus its behavior. */
 export interface NodeInit {
     readonly store: LogStore;
@@ -45,6 +45,8 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
     readonly path: string;
     readonly parentId: string | null;
     readonly tags: string[];
+    /** What the definition said about itself (`.describe()`, `.mcp()`, `.args()`); for the record. */
+    meta: ActionMeta | undefined;
     /** The captured args this node ran with (for the log header); set at run start. */
     args: readonly unknown[];
     readonly children: ActionRun[];

package/dist/core/ActionRun.js

@@ -18,6 +18,8 @@ export class ActionRun {
     path;
     parentId;
     tags = [];
+    /** What the definition said about itself (`.describe()`, `.mcp()`, `.args()`); for the record. */
+    meta;
     /** The captured args this node ran with (for the log header); set at run start. */
     args = [];
     children = [];

package/dist/core/ExecutionTree.d.ts

@@ -41,6 +41,7 @@ export declare class ExecutionTree {
     private readonly snapshotStore;
     private readonly artifactStore;
     private readonly registry;
+    private readonly schemaCache;
     private readonly unsettled;
     private readonly originalLog;
     private streaming;
@@ -101,6 +102,12 @@ export declare class ExecutionTree {
     private printSummary;
     private verdictOk;
     private nodeView;
+    /**
+     * The node's self-description, projected for the record. The root's comes from the om
+     * builder; a child's from its action definition. The args schema is converted here, once per
+     * definition, so a step launched a thousand times converts its schema once.
+     */
+    private metaView;
     /** Test seam: the projected run view (same object written to result.json). */
     runViewForTest(): RunView;
     /** Test seam: the run's curated artifacts. */

package/dist/core/ExecutionTree.js

@@ -61,6 +61,7 @@ export class ExecutionTree {
     snapshotStore;
     artifactStore = new ArtifactStore();
     registry = [];
+    schemaCache = new Map();
     unsettled = new Set();
     originalLog = console.log.bind(console);
     streaming;
@@ -137,6 +138,7 @@ export class ExecutionTree {
             // into the parent's log, attributed to this child's id.
             bubble: (message) => this.append(parent, "child", id, message),
         });
+        node.meta = spec.meta;
         parent.children.push(node);
         this.registry.push(node);
         // Launch reference — the parent's pointer to the child's own (absolute) log, plus where
@@ -386,9 +388,34 @@ export class ExecutionTree {
             endedAt: node.endedAt,
             duration: node.duration,
             logFile: this.logFile(node.path),
+            ...this.metaView(node),
             children: node.children.map((child) => this.nodeView(child)),
         };
     }
+    /**
+     * The node's self-description, projected for the record. The root's comes from the om
+     * builder; a child's from its action definition. The args schema is converted here, once per
+     * definition, so a step launched a thousand times converts its schema once.
+     */
+    metaView(node) {
+        const meta = node.parentId === null
+            ? { description: this.description, mcp: this.mcp, describeArgs: node.meta?.describeArgs }
+            : node.meta;
+        if (!meta)
+            return {};
+        let inputSchema;
+        if (meta.describeArgs) {
+            if (!this.schemaCache.has(meta.describeArgs)) {
+                this.schemaCache.set(meta.describeArgs, meta.describeArgs().inputSchema);
+            }
+            inputSchema = this.schemaCache.get(meta.describeArgs);
+        }
+        return {
+            ...(meta.description === undefined ? {} : { description: { ...meta.description } }),
+            ...(meta.mcp === undefined ? {} : { mcp: { ...meta.mcp } }),
+            ...(inputSchema === undefined ? {} : { inputSchema }),
+        };
+    }
     /** Test seam: the projected run view (same object written to result.json). */
     runViewForTest() {
         return this.runView();

package/dist/core/action.js

@@ -49,9 +49,13 @@ class Builder {
         // No `.args()` on this path, so there is nothing to describe — or to resolve against.
         const describeArgs = () => describeSchema(undefined);
         const parseArgs = (supplied) => supplied;
+        const meta = {
+            ...(description === undefined ? {} : { description }),
+            ...(mcp === undefined ? {} : { mcp }),
+        };
         const exec = body;
         const create = (...args) => {
-            const spec = { name, args, tags: [], body: exec, definedAt };
+            const spec = { name, args, tags: [], body: exec, definedAt, meta };
             return ExecutionTree.require().launch(spec);
         };
         return Object.assign(create, {
@@ -102,6 +106,11 @@ class ArgsBuilder {
         // that built it — rather than in whichever copy the discovery child is running.
         const schema = this.schema;
         const describeArgs = () => describeSchema(schema);
+        const meta = {
+            ...(description === undefined ? {} : { description }),
+            ...(mcp === undefined ? {} : { mcp }),
+            describeArgs,
+        };
         // `safeParse` is what applies `.default()`s, so this is where an advertised default
         // becomes the effective one. A refusal names the action and every failing field.
         const parseArgs = (supplied) => {
@@ -112,7 +121,7 @@ class ArgsBuilder {
         };
         const exec = body;
         const create = (...args) => {
-            const spec = { name, args, tags: [], body: exec, definedAt };
+            const spec = { name, args, tags: [], body: exec, definedAt, meta };
             return ExecutionTree.require().launch(spec);
         };
         return Object.assign(create, {

package/dist/core/om.js

@@ -37,6 +37,9 @@ function launch(name, site, description, exposure, body, schema) {
     }
     const tree = new ExecutionTree(name, site, description, exposure);
     ExecutionTree.current = tree;
+    // The root's description and exposure live on the tree; its schema rides on the node.
+    if (schema !== undefined)
+        tree.root.meta = { describeArgs: () => describeSchema(schema) };
     const rootBody = (ctx) => body({
         signal: ctx.signal,
         logs: ctx.logs,

package/dist/core/types.d.ts

@@ -239,4 +239,17 @@ export interface LaunchSpec {
     readonly body: Exec<object, unknown, unknown>;
     /** `file:line` where the action was defined; carried onto the node for its log header. */
     readonly definedAt: string | undefined;
+    /** What the definition declared about itself — carried onto the node for the run record. */
+    readonly meta?: ActionMeta;
+}
+/**
+ * A definition's self-description, as it travels onto each node it launches: what
+ * `.describe()` and `.mcp()` said, and the `.args()` schema as JSON Schema. Read only by the
+ * run record (`result.json`, `report.html`) — the runtime never branches on it.
+ */
+export interface ActionMeta {
+    readonly description?: OmDescription;
+    readonly mcp?: ResolvedMcpExposure;
+    /** Converts the declared args schema; called once, at finalize. */
+    readonly describeArgs?: () => DescribedArgs;
 }

package/dist/output/writers/ReportWriter.js

@@ -33,10 +33,13 @@ export async function writeReport(file, input) {
     const assets = [];
     const files = await collectFiles(input, assets);
     const snapshots = await collectSnapshots(input);
+    const root = await projectRoot(input.folder);
     const payload = {
         version: 1,
         name: input.name,
         folder: input.folder,
+        projectRoot: root,
+        sources: definitionSources(input.run.root, root),
         generatedAt: Date.now(),
         run: input.run,
         entries: input.entries,
@@ -183,6 +186,40 @@ function artifactTimes(entries) {
     }
     return out;
 }
+/**
+ * The project the run belongs to, for project-relative paths: the nearest ancestor of the run
+ * folder holding `.git`, else the folder `logs/` sits in (the root omkit was given), else cwd.
+ */
+async function projectRoot(folder) {
+    let dir = path.resolve(folder);
+    for (;;) {
+        try {
+            await stat(path.join(dir, ".git"));
+            return dir;
+        }
+        catch {
+            /* keep climbing */
+        }
+        const up = path.dirname(dir);
+        if (up === dir)
+            break;
+        dir = up;
+    }
+    return process.env.OMKIT_ROOT ? path.resolve(process.env.OMKIT_ROOT) : process.cwd();
+}
+/** Each distinct `definedAt` site → its file, relative to the project root, forward-slashed, no line. */
+function definitionSources(root, projectDir) {
+    const out = {};
+    const visit = (n) => {
+        if (n.definedAt && !(n.definedAt in out)) {
+            const file = n.definedAt.replace(/:\d+(:\d+)?$/, "");
+            out[n.definedAt] = path.relative(projectDir, file).split(path.sep).join("/") || file;
+        }
+        n.children.forEach(visit);
+    };
+    visit(root);
+    return out;
+}
 async function walk(dir, depth = 0) {
     if (depth > 4)
         return [];

package/dist/output/writers/report/report.css

@@ -153,10 +153,13 @@ button { font: inherit; color: inherit; }
 .guide::before { content: ""; position: absolute; left: 7px; top: 0; bottom: 0; border-left: 1px solid var(--line); }
 
 .chart { position: relative; min-width: 0; }
-.chart svg { display: block; }
-.chart .bar-label { font-size: 12px; fill: var(--bar-text); font-weight: 500; pointer-events: none; }
+.chart svg { display: block; overflow: hidden; }
+.chart .bar-label { font-size: 12px; fill: var(--bar-text); font-weight: 500; cursor: pointer; }
+.chart .hit { fill: transparent; cursor: pointer; }
+.chart .hit:hover + .bar { filter: brightness(1.15); }
 .chart .bar-label.outside { fill: var(--text); }
-.chart .mark-label { font-size: 11px; fill: var(--text-2); pointer-events: none; }
+.chart .mark-label { font-size: 11px; fill: var(--text-2); cursor: pointer; }
+.chart .mark-label:hover { fill: var(--text); }
 .chart .grid line { stroke: var(--line-soft); }
 .chart .cursor { stroke: var(--text-2); stroke-dasharray: 3 3; pointer-events: none; }
 .chart .link { fill: none; stroke: var(--text-3); stroke-width: 1.2; }
@@ -175,7 +178,7 @@ button { font: inherit; color: inherit; }
 .flow-link { fill: none; stroke: var(--text-3); stroke-width: 1.3; }
 .flame-rect { cursor: pointer; stroke: var(--panel); stroke-width: 1; }
 .flame-rect.selected { stroke: var(--text); stroke-width: 2; }
-.flame-text { font-size: 11px; fill: var(--bar-text); pointer-events: none; }
+.flame-text { font-size: 11px; fill: var(--bar-text); cursor: pointer; }
 
 /* ── details ────────────────────────────────────────────── */
 .details { display: grid; grid-template-rows: auto auto minmax(0, 1fr); overflow: hidden; }
@@ -252,6 +255,31 @@ table.list tr:hover td { background: var(--raise); }
 }
 .tip .tt { font-weight: 600; margin-bottom: 2px; }
 .tip .ts { color: var(--text-2); }
+.tip.wide { max-width: 420px; min-width: 260px; }
+.tip .mono { font-family: var(--mono); font-size: 11px; overflow-wrap: anywhere; }
+.tip .small { color: var(--text-2); }
+.tip .badges { display: flex; flex-wrap: wrap; gap: 5px; margin: 6px 0; }
+.tip .badge { display: inline-flex; align-items: center; gap: 5px; padding: 1px 8px; border-radius: 999px; background: var(--raise); font-size: 11px; color: var(--text-2); }
+.tip .badge.mcp { background: var(--accent-soft); color: var(--accent); font-weight: 600; }
+.tip .summary { margin: 4px 0 8px; line-height: 1.45; }
+.tip .tkv { display: grid; grid-template-columns: auto minmax(0, 1fr); gap: 2px 10px; font-variant-numeric: tabular-nums; }
+.tip .tkv .k, .tip .sec { color: var(--text-3); }
+.tip .sec { margin: 8px 0 3px; font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em; }
+.tip .sec.fail { color: var(--fail); }
+.params { display: grid; gap: 3px; }
+.param { font: 11px/1.4 var(--mono); }
+.param .pn { color: var(--text); }
+.param .pt { color: var(--accent); margin-left: 6px; }
+.param .pd { color: var(--text-3); margin-left: 6px; }
+.param .pdesc { font-family: var(--sans); color: var(--text-2); margin-left: 10px; }
+.kv .v.defined { display: flex; align-items: center; gap: 6px; }
+.kv .v.defined a { min-width: 0; overflow-wrap: anywhere; font-family: var(--mono); font-size: 12px; }
+.icon-btn { flex: none; border: 1px solid var(--line); background: var(--panel-2); color: var(--text-2); border-radius: 6px; width: 24px; height: 22px; display: grid; place-items: center; cursor: pointer; padding: 0; }
+.icon-btn:hover { color: var(--text); border-color: var(--accent); }
+.icon-btn svg { width: 13px; height: 13px; }
+.tip .hint { margin-top: 8px; color: var(--text-3); font-size: 11px; }
+.tip kbd { font: 600 10px var(--mono); border: 1px solid var(--line); border-bottom-width: 2px; border-radius: 4px; padding: 0 4px; color: var(--text-2); }
+.badge-inline { display: inline-block; padding: 0 7px; border-radius: 999px; background: var(--accent-soft); color: var(--accent); font-size: 11px; font-weight: 600; }
 .tip img { display: block; max-width: 240px; max-height: 150px; border-radius: 4px; margin: 6px 0; border: 1px solid var(--line); }
 .modal { position: fixed; inset: 0; background: rgba(5, 8, 18, 0.72); z-index: 60; display: grid; place-items: center; padding: 28px; }
 .modal .box { background: var(--panel); border: 1px solid var(--line); border-radius: 12px; box-shadow: var(--shadow); max-width: min(1200px, 100%); max-height: 100%; display: grid; grid-template-rows: auto minmax(0, 1fr); overflow: hidden; }

package/dist/output/writers/report/report.js

@@ -393,6 +393,9 @@
           select(n.id);
         });
         r.addEventListener("dblclick", () => focusNode(n));
+        r.addEventListener("mouseenter", (ev) => showTip(ev, nodeTip(n), true, 280));
+        r.addEventListener("mousemove", (ev) => moveTip(ev));
+        r.addEventListener("mouseleave", hideTip);
       });
     }
     function treeRowHtml(n) {
@@ -488,6 +491,8 @@
         .data(rowsNow, (n) => n.id)
         .join((enter) => {
           const r = enter.append("g").attr("class", "r");
+          // A transparent target spanning the bar *and* its label, so a 2px bar is still hoverable.
+          r.append("rect").attr("class", "hit").attr("y", BAR_Y - 4).attr("height", BAR_H + 8);
           r.append("rect").attr("class", "bar").attr("rx", 5).attr("y", BAR_Y).attr("height", BAR_H);
           r.append("text").attr("class", "bar-label").attr("y", BAR_Y + BAR_H / 2 + 4);
           r.append("g").attr("class", "marks");
@@ -504,17 +509,7 @@
         .attr("stroke-width", (n) => (n.status === "failed" ? 2 : null))
         .attr("stroke-dasharray", (n) => (n.status === "cancelled" ? "4 3" : null))
         .classed("selected", (n) => n.id === state.selected)
-        .on("click", (ev, n) => {
-          ev.stopPropagation();
-          select(n.id);
-        })
-        .on("dblclick", (ev, n) => {
-          ev.stopPropagation();
-          focusNode(n);
-        })
-        .on("mouseenter", (ev, n) => showTip(ev, nodeTip(n)))
-        .on("mousemove", (ev) => moveTip(ev))
-        .on("mouseleave", hideTip);
+        .call(bindNode);
 
       g.select("text.bar-label").each(function (n) {
         const t = d3.select(this);
@@ -524,10 +519,19 @@
         const need = text.length * 6.6 + 14;
         const inside = w >= need;
         const clipX = Math.max(x0, 0);
-        t.text(inside ? text : w > 60 ? truncate(text, (w - 14) / 6.6) : text)
-          .classed("outside", !inside && w <= 60)
-          .attr("x", !inside && w <= 60 ? x0 + Math.max(w, 3) + 6 : Math.min(clipX + 8, x0 + w - 20));
+        const outside = !inside && w <= 60;
+        const shown = inside || outside ? text : truncate(text, (w - 14) / 6.6);
+        const tw = shown.length * 6.6;
+        // an outside label that would run off the chart hangs left of its bar instead
+        const flip = outside && x0 + Math.max(w, 3) + 6 + tw > W;
+        const lx = flip ? x0 - 6 : outside ? x0 + Math.max(w, 3) + 6 : Math.min(clipX + 8, x0 + w - 20);
+        t.text(shown).classed("outside", outside).attr("x", lx).attr("text-anchor", flip ? "end" : "start");
+        // the hit target covers bar + label, padded so a sliver of a bar is still easy to reach
+        const left = Math.min(x0, flip ? lx - tw : lx) - 6;
+        const right = Math.max(x0 + Math.max(w, 3), flip ? x0 : lx + tw) + 6;
+        d3.select(this.parentNode).select("rect.hit").attr("x", left).attr("width", Math.max(16, right - left));
       });
+      g.selectAll("rect.hit, text.bar-label").call(bindNode);
 
       g.select("g.marks").each(function (n) {
         drawMarks(d3.select(this), n, x);
@@ -584,7 +588,14 @@
         .attr("x", (l) => (flip(l) ? l.d.px + 4 : l.d.px - 4))
         .attr("text-anchor", (l) => (flip(l) ? "end" : "start"))
         .attr("y", BAR_Y + BAR_H + 13)
-        .text((l) => l.text);
+        .text((l) => l.text)
+        .on("click", (ev, l) => {
+          ev.stopPropagation();
+          openItem(l.d.m);
+        })
+        .on("mouseenter", (ev, l) => showTip(ev, markTip(l.d)))
+        .on("mousemove", (ev) => moveTip(ev))
+        .on("mouseleave", hideTip);
     }
     function worst(d) {
       const all = [d.m, ...d.more].map((m) => m.kind);
@@ -669,21 +680,15 @@
         .attr("fill", (n) => colorOf(n))
         .attr("fill-opacity", (n) => (n.status === "cancelled" ? 0.55 : 0.92))
         .classed("selected", (n) => n.id === state.selected)
-        .on("click", (ev, n) => select(n.id))
-        .on("dblclick", (ev, n) => {
-          ev.stopPropagation();
-          focusNode(n);
-        })
-        .on("mouseenter", (ev, n) => showTip(ev, nodeTip(n)))
-        .on("mousemove", (ev) => moveTip(ev))
-        .on("mouseleave", hideTip);
+        .call(bindNode);
       cells
         .select("text")
         .attr("x", (n) => Math.max(x(n.start), 0) + 5)
         .text((n) => {
           const w = x(n.end) - Math.max(x(n.start), 0);
           return w < 34 ? "" : truncate(`${displayName(n)} ${fmtDur(n.duration)}`, (w - 10) / 6.2);
-        });
+        })
+        .call(bindNode);
     }
 
     // ── flow view ──
@@ -858,14 +863,18 @@
             <div class="k">Duration</div><div class="v">${fmtDur(n.duration)}</div>
             <div class="k">Start</div><div class="v">${fmtRel(n.start)} (${fmtClock(n.startAbs)})</div>
             <div class="k">End</div><div class="v">${fmtRel(n.end)} (${fmtClock(n.endAbs)})</div>
+            ${n.v.description ? `<div class="k">Summary</div><div class="v">${esc(n.v.description.summary)}</div>` : ""}
+            ${n.v.mcp ? `<div class="k">MCP</div><div class="v"><span class="badge-inline">${esc(n.v.mcp.mode)}</span></div>` : ""}
             <div class="k">Path</div><div class="v">${esc(n.v.path)}</div>
-            ${n.v.definedAt ? `<div class="k">Defined at</div><div class="v"><a href="${esc(editorUrl(n.v.definedAt))}" title="${esc(n.v.definedAt)}">${esc(basename(n.v.definedAt))}</a></div>` : ""}
+            ${n.v.definedAt ? `<div class="k">Defined at</div><div class="v defined"><a href="${esc(editorUrl(n.v.definedAt))}" title="Open ${esc(n.v.definedAt)} in VS Code">${esc(sourceOf(n))}</a><button class="icon-btn" data-copy-source title="Copy relative path (C)">${svgIcon("copy")}</button></div>` : ""}
           </div>
           <div class="tabs">${tabs
             .map(([k, l]) => `<button class="tab ${state.detailTab === k ? "active" : ""}" data-tab="${k}">${l}</button>`)
             .join("")}</div>
           <div class="tabbody">${detailTabHtml(n)}</div>
         </div>`;
+      const copySrc = el.details.querySelector("[data-copy-source]");
+      if (copySrc) copySrc.addEventListener("click", () => copySource(n));
       el.details.querySelector(".x").addEventListener("click", () => {
         state.details = false;
         el.main.classList.add("no-details");
@@ -883,7 +892,9 @@
     function detailTabHtml(n) {
       const tab = state.detailTab;
       if (tab === "args") {
-        return n.v.args && n.v.args.length ? `<pre class="code">${esc(json(n.v.args.length === 1 ? n.v.args[0] : n.v.args))}</pre>` : '<div class="muted">No arguments.</div>';
+        const params = schemaFields(n.v.inputSchema);
+        const schema = params.length ? `<div class="section-title">Schema</div><div class="params">${params.map(paramHtml).join("")}</div><div class="section-title">Values</div>` : "";
+        return schema + (n.v.args && n.v.args.length ? `<pre class="code">${esc(json(n.v.args.length === 1 ? n.v.args[0] : n.v.args))}</pre>` : '<div class="muted">No arguments.</div>');
       }
       if (tab === "events") {
         const evs = n.entries.filter((i) => i.kind !== "info");
@@ -1115,11 +1126,50 @@
     }
 
     // ── tooltips ──
+    /** Click selects, double-click focuses, hover explains — the same on every node mark. */
+    function bindNode(sel) {
+      sel
+        .on("click", (ev, n) => {
+          ev.stopPropagation();
+          select(n.id);
+        })
+        .on("dblclick", (ev, n) => {
+          ev.stopPropagation();
+          focusNode(n);
+        })
+        .on("mouseenter", (ev, n) => showTip(ev, nodeTip(n), true))
+        .on("mousemove", (ev) => moveTip(ev))
+        .on("mouseleave", hideTip);
+    }
     function nodeTip(n) {
-      return `<div class="tt">${esc(n.name)}</div>
-        <div class="ts"><span class="dot ${n.status}"></span> ${esc(n.status)} · ${fmtDur(n.duration)}</div>
-        <div class="ts">${fmtRel(n.start)} → ${fmtRel(n.end)}</div>
-        ${n.v.tags.length ? `<div class="ts">${esc(n.v.tags.join(" · "))}</div>` : ""}`;
+      hovered = n; // the node `C` copies while its tooltip is up
+      const v = n.v;
+      const shown = displayName(n);
+      const badges = [
+        `<span class="badge"><span class="dot ${n.status}"></span>${esc(n.status)}</span>`,
+        v.mcp ? `<span class="badge mcp" title="Exposed over MCP">MCP · ${esc(v.mcp.mode)}</span>` : "",
+        n.depth === 0 ? '<span class="badge">om</span>' : "",
+      ].join("");
+      const rows = [
+        ["Duration", fmtDur(n.duration)],
+        ["When", `${fmtRel(n.start)} → ${fmtRel(n.end)}`],
+        v.tags.length ? ["Tags", esc(v.tags.join(" · "))] : null,
+        v.definedAt ? ["Defined", `<span class="mono">${esc(sourceOf(n))}</span>`] : null,
+        n.children.length ? ["Children", String(n.children.length)] : null,
+        n.marks.length ? ["Events", String(n.marks.length)] : null,
+      ].filter(Boolean);
+      const args = v.args && v.args.length ? truncate(oneLine(v.args.length === 1 ? v.args[0] : v.args), 220) : "";
+      const params = schemaFields(v.inputSchema);
+      const fails = model.run.failures.filter((f) => f.action === n.id || f.action === n.name || f.action === v.path);
+      return `<div class="tt">${esc(shown)}</div>
+        ${shown !== n.name ? `<div class="ts mono">${esc(truncate(n.name, 140))}</div>` : ""}
+        <div class="badges">${badges}</div>
+        ${v.description ? `<div class="summary">${esc(v.description.summary)}</div>` : '<div class="summary muted">No description.</div>'}
+        <div class="tkv">${rows.map(([k, val]) => `<span class="k">${k}</span><span>${val}</span>`).join("")}</div>
+        ${params.length ? `<div class="sec">Args schema</div><div class="params">${params.map(paramHtml).join("")}</div>` : ""}
+        ${args ? `<div class="sec">Args</div><div class="mono small">${esc(args)}</div>` : ""}
+        ${v.definedAt ? '<div class="hint">Press <kbd>C</kbd> to copy the path</div>' : ""}
+        ${fails.length ? `<div class="sec fail">Failed</div><div class="mono small">${esc(truncate(String(fails[0].error).split(String.fromCharCode(10))[0], 200))}</div>` : ""}`;
     }
     function markTip(d) {
       const m = d.m;
@@ -1129,12 +1179,34 @@
       const extra = m.gallery && m.gallery.image ? `<div class="ts">${esc(m.gallery.f.rel)} · ${fmtSize(m.gallery.f.size)}</div>` : "";
       return `<div class="tt">${esc(mk.label)} · ${fmtRel(m.t)}</div>${img}<div>${esc(truncate(m.kind === "snapshot" || m.kind === "artifact" ? m.label : m.e.message, 260))}</div>${extra}${more}`;
     }
-    function showTip(ev, html) {
-      tip.innerHTML = html;
-      tip.hidden = false;
-      moveTip(ev);
+    let tipTimer = 0;
+    let hovered = null;
+    /** The file where `n` is defined, relative to the project root — no line. */
+    function sourceOf(n) {
+      const site = n.v.definedAt;
+      if (!site) return "";
+      return (model.data.sources && model.data.sources[site]) || site.replace(/:\d+(:\d+)?$/, "");
+    }
+    function copySource(n) {
+      const src = n && sourceOf(n);
+      if (src) copy(src, `Copied ${src}`);
+    }
+    let lastEv = null;
+    function showTip(ev, html, wide, delay) {
+      clearTimeout(tipTimer);
+      lastEv = ev;
+      const open = () => {
+        tip.innerHTML = html;
+        tip.classList.toggle("wide", !!wide);
+        tip.hidden = false;
+        moveTip(lastEv);
+      };
+      if (delay && tip.hidden) tipTimer = setTimeout(open, delay);
+      else open();
     }
     function moveTip(ev) {
+      lastEv = ev;
+      if (tip.hidden) return;
       const pad = 14;
       const r = tip.getBoundingClientRect();
       let x = ev.clientX + pad;
@@ -1145,6 +1217,8 @@
       tip.style.top = `${y}px`;
     }
     function hideTip() {
+      hovered = null;
+      clearTimeout(tipTimer);
       tip.hidden = true;
     }
 
@@ -1172,6 +1246,9 @@
       if (e.key === "+" || e.key === "=") zoomBy(1.6);
       else if (e.key === "-") zoomBy(1 / 1.6);
       else if (e.key === "0") fit();
+      else if ((e.key === "c" || e.key === "C") && !e.ctrlKey && !e.metaKey && !e.altKey) {
+        copySource(hovered || model.byId.get(state.selected));
+      }
       else if (e.key === "ArrowDown" || e.key === "ArrowUp") {
         const rows = visible();
         const i = rows.findIndex((n) => n.id === state.selected);
@@ -1281,6 +1358,40 @@
     c.opacity = a;
     return c.formatRgb();
   }
+  function oneLine(v) {
+    try {
+      return typeof v === "string" ? v : JSON.stringify(v);
+    } catch {
+      return String(v);
+    }
+  }
+  /** Top-level fields of a JSON Schema object: name, type, required, default, description. */
+  function schemaFields(schema) {
+    if (!schema || typeof schema !== "object" || !schema.properties) return [];
+    const req = new Set(schema.required || []);
+    return Object.entries(schema.properties).map(([name, p]) => ({
+      name,
+      type: typeOf(p),
+      required: req.has(name) && !(p && "default" in p),
+      def: p && "default" in p ? oneLine(p.default) : undefined,
+      desc: p && p.description,
+    }));
+  }
+  function typeOf(p) {
+    if (!p || typeof p !== "object") return "any";
+    if (p.enum) return p.enum.map((e) => JSON.stringify(e)).join(" | ");
+    if (p.const !== undefined) return JSON.stringify(p.const);
+    if (Array.isArray(p.type)) return p.type.join(" | ");
+    if (p.type === "array") return `${typeOf(p.items)}[]`;
+    if (p.type) return p.type;
+    if (p.anyOf || p.oneOf) return (p.anyOf || p.oneOf).map(typeOf).join(" | ");
+    return "any";
+  }
+  function paramHtml(f) {
+    return `<div class="param"><span class="pn">${esc(f.name)}${f.required ? "" : "?"}</span><span class="pt">${esc(truncate(f.type, 40))}</span>${
+      f.def !== undefined ? `<span class="pd">= ${esc(truncate(f.def, 24))}</span>` : ""
+    }${f.desc ? `<div class="pdesc">${esc(f.desc)}</div>` : ""}</div>`;
+  }
   function truncate(s, n) {
     n = Math.max(1, Math.floor(n));
     return s.length > n ? `${s.slice(0, Math.max(1, n - 1))}…` : s;
@@ -1306,19 +1417,19 @@
     if (/build|compile|bundle/.test(s)) return "box";
     return "play";
   }
-  function copy(text) {
-    const done = () => toast("Copied");
-    if (navigator.clipboard && window.isSecureContext) navigator.clipboard.writeText(text).then(done, () => fallbackCopy(text));
-    else fallbackCopy(text);
+  function copy(text, message) {
+    const done = () => toast(message || "Copied");
+    if (navigator.clipboard && window.isSecureContext) navigator.clipboard.writeText(text).then(done, () => fallbackCopy(text, message));
+    else fallbackCopy(text, message);
   }
-  function fallbackCopy(text) {
+  function fallbackCopy(text, message) {
     const t = document.createElement("textarea");
     t.value = text;
     document.body.appendChild(t);
     t.select();
     try {
       document.execCommand("copy");
-      toast("Copied");
+      toast(message || "Copied");
     } catch {
       toast(text);
     }

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

@@ -19,6 +19,16 @@ export interface NodeView {
     readonly duration: number;
     /** Absolute path to this node's own `.log`. */
     readonly logFile: string;
+    /** What the definition's `.describe()` said; absent when it said nothing. */
+    readonly description?: {
+        readonly summary: string;
+    };
+    /** The definition's `.mcp()` exposure; absent when it is not exposed. */
+    readonly mcp?: {
+        readonly mode: string;
+    };
+    /** The definition's `.args()` schema as JSON Schema; absent without one. */
+    readonly inputSchema?: unknown;
     readonly children: readonly NodeView[];
 }
 /** A curated artifact, as projected into `result.json`. Data-only — no core import. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.8.10",
+  "version": "0.8.11",
   "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",