omkit 0.8.13 → 0.8.14

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. Each node also carries what its definition declared about itself: the `.describe()` summary, the `.mcp()` exposure, and the `.args()` schema as JSON Schema. Each node also records `calledAt`, the line that launched it, so a built-in step (a `prompt`, a `command`) points back at your code rather than omkit's, and a `step(...)` is defined at the line where you wrote it.
+- `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. Each node also records what it returned (`value`, or a `valueNote` when it was too large or not JSON) and `calledAt`, the line that launched it, so a built-in step (a `prompt`, a `command`) points back at your code rather than omkit's, and a `step(...)` is defined at the line where you wrote it.
 - `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/ExecutionTree.js

@@ -391,6 +391,7 @@ export class ExecutionTree {
             duration: node.duration,
             logFile: this.logFile(node.path),
             ...this.metaView(node),
+            ...valueView(node.value),
             children: node.children.map((child) => this.nodeView(child)),
         };
     }
@@ -506,6 +507,36 @@ const messageOf = (error) => error instanceof Error ? (error.stack ?? error.mess
  * body may hand back anything — a capability handle, a cyclic object — and the run must
  * still write its record; a value that does not survive JSON is dropped, not fatal.
  */
+/** A node's return value is recorded up to this many characters of JSON. */
+const VALUE_CAP = 512 * 1024;
+/**
+ * What a node returned, for the record: the value itself when JSON can carry it and it fits,
+ * otherwise a one-line note saying what it was — so "returned a Page" is still on the record.
+ */
+function valueView(value) {
+    if (value === undefined)
+        return {};
+    const kind = value === null
+        ? "null"
+        : typeof value === "object"
+            ? (value.constructor?.name ?? "object")
+            : typeof value;
+    let text;
+    try {
+        text = JSON.stringify(value);
+    }
+    catch {
+        text = undefined;
+    }
+    if (text === undefined)
+        return { valueNote: `${kind} (not JSON)` };
+    if (text.length > VALUE_CAP) {
+        return {
+            valueNote: `${kind}, ${Math.round(text.length / 1024)} KB of JSON — too large to record`,
+        };
+    }
+    return { value: JSON.parse(text) };
+}
 function serialisable(value) {
     if (value === undefined)
         return undefined;

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

@@ -337,6 +337,7 @@ a.icon-btn { text-decoration: none; }
 .tk-k { color: var(--tk-k); }
 .tk-f { color: var(--tk-f); }
 .tk-t { color: var(--tk-t); }
+.tk-p { color: var(--tk-f); }
 
 /* ── popover tabs, prompt panel, flow snapshot strip ───── */
 .code-pop .cp-tabs { display: flex; gap: 2px; padding: 0 8px; border-bottom: 1px solid var(--line); background: var(--panel-2); }
@@ -355,6 +356,18 @@ a.icon-btn { text-decoration: none; }
 .flow-shots .shot:hover rect { stroke: var(--accent); }
 .flow-shots .shot text { fill: var(--text-3); font: 600 9px var(--mono); pointer-events: none; }
 
+/* ── returned values ───────────────────────────────────── */
+.code-btn path { fill: none; stroke: var(--text-2); stroke-width: 2.6; stroke-linecap: round; stroke-linejoin: round; pointer-events: none; }
+.code-btn:hover path { stroke: var(--accent); }
+.cp-tools { display: flex; align-items: center; justify-content: space-between; gap: 10px; padding: 6px 10px 6px 14px; border-bottom: 1px solid var(--line-soft); font-size: 12px; }
+.btn.small { padding: 3px 9px; font-size: 12px; }
+.btn.small svg { width: 13px; height: 13px; }
+.code-box { border: 1px solid var(--line-soft); border-radius: 8px; background: var(--panel-2); overflow: auto; max-height: 60vh; }
+.code-box .cp-code, .code-pop .cp-code { font: 11.5px/1.65 var(--mono); padding: 8px 0; min-width: max-content; }
+.code-box .cl { display: grid; grid-template-columns: 40px auto; white-space: pre; }
+.code-box .ln { color: var(--text-3); text-align: right; padding-right: 12px; user-select: none; }
+.code-box .lc { padding-right: 14px; }
+
 @media (max-width: 1100px) {
   .bottom { grid-template-columns: minmax(0, 1fr); }
   .legend, .overview { display: none; }

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

@@ -43,6 +43,7 @@
     info: "M12 3a9 9 0 1 0 0 18 9 9 0 0 0 0-18zM12 11v5M12 8h.01",
     locate: "M12 5a7 7 0 1 0 0 14 7 7 0 0 0 0-14zM12 2v3M12 19v3M2 12h3M19 12h3M12 10.5a1.5 1.5 0 1 0 0 3 1.5 1.5 0 0 0 0-3z",
     code: "M8 7l-5 5 5 5M16 7l5 5-5 5",
+    ret: "M9 10l-4 4 4 4M5 14h11a4 4 0 0 0 4-4V5",
     external: "M14 4h6v6M20 4l-9 9M18 14v6H4V6h6",
   };
   const svgIcon = (name, extra) =>
@@ -505,9 +506,12 @@
           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");
-          const cb = r.append("g").attr("class", "code-btn");
+          const cb = r.append("g").attr("class", "code-btn src");
           cb.append("circle").attr("r", 9);
           cb.append("text").attr("text-anchor", "middle").attr("y", 3.5).text("<>");
+          const rb = r.append("g").attr("class", "code-btn ret");
+          rb.append("circle").attr("r", 9);
+          rb.append("path").attr("d", ICON.ret).attr("transform", "translate(-6,-6) scale(0.5)");
           return r;
         })
         .attr("transform", (_n, i) => `translate(0,${i * ROW_H})`)
@@ -547,18 +551,33 @@
         // …and, for a block spanning the chart, inside it right after its label
         const cx =
           right + 8 <= W - 10 ? right + 8 : left - 8 >= 10 ? left - 8 : Math.min(W - 12, (flip ? x0 : lx + tw) + 14);
-        d3.select(this.parentNode)
-          .select("g.code-btn")
-          .style("display", hasCode(n) ? null : "none")
+        // buttons stack away from the block: rightward when they sit after it, leftward before it
+        const dir = right + 8 <= W - 10 || left - 8 < 10 ? 1 : -1;
+        const src = hasCode(n);
+        const row = d3.select(this.parentNode);
+        row
+          .select("g.code-btn.src")
+          .style("display", src ? null : "none")
           .attr("transform", `translate(${cx},${BAR_Y + BAR_H / 2})`);
+        row
+          .select("g.code-btn.ret")
+          .style("display", hasValue(n) ? null : "none")
+          .attr("transform", `translate(${src ? cx + dir * 21 : cx},${BAR_Y + BAR_H / 2})`);
       });
-      g.select("g.code-btn")
+      g.select("g.code-btn.src")
         .on("click", (ev, n) => {
           ev.stopPropagation();
           toggleCode(n, ev);
         })
         .on("mouseenter", (ev) => showTip(ev, "Show source"))
         .on("mouseleave", hideTip);
+      g.select("g.code-btn.ret")
+        .on("click", (ev, n) => {
+          ev.stopPropagation();
+          toggleCode(n, ev, "value", true);
+        })
+        .on("mouseenter", (ev, n) => showTip(ev, `Returned: <span class="mono">${esc(valuePreview(n, 80))}</span>`))
+        .on("mouseleave", hideTip);
       g.selectAll("rect.hit, text.bar-label").call(bindNode);
 
       g.select("g.marks").each(function (n) {
@@ -802,6 +821,21 @@
         });
       fcb.append("circle").attr("r", 9);
       fcb.append("text").attr("text-anchor", "middle").attr("y", 3.5).text("<>");
+      const frb = card
+        .filter((d) => hasValue(d.data))
+        .append("g")
+        .attr("class", "code-btn ret")
+        .attr("transform", (d) => `translate(${CW / 2 + (hasCode(d.data) ? 22 : 0)},0)`)
+        .on("click", (ev, d) => {
+          ev.stopPropagation();
+          toggleCode(d.data, ev, "value", true);
+        })
+        .on("mouseenter", (ev, d) => {
+          ev.stopPropagation();
+          showTip(ev, `Returned: <span class="mono">${esc(valuePreview(d.data, 80))}</span>`);
+        });
+      frb.append("circle").attr("r", 9);
+      frb.append("path").attr("d", ICON.ret).attr("transform", "translate(-6,-6) scale(0.5)");
       const TW = 46;
       const TH = 28;
       const strip = card
@@ -1004,6 +1038,7 @@
       const tabs = [
         ["overview", "Overview"],
         ["args", "Args"],
+        ...(hasValue(n) ? [["value", "Return"]] : []),
         ["events", `Events`],
         ["logs", "Logs"],
         ["snapshots", "Snapshots"],
@@ -1026,6 +1061,7 @@
             ${userSite(n) ? `<div class="k">${siteLabel(n)}</div><div class="v defined">
               <button class="icon-btn" data-copy-source aria-label="Copy relative path">${svgIcon("copy")}</button>
               ${hasCode(n) ? `<button class="icon-btn" data-show-code aria-label="Show source">${svgIcon("code")}</button>` : ""}
+              ${hasValue(n) ? `<button class="icon-btn" data-show-value aria-label="Show returned value">${svgIcon("ret")}</button>` : ""}
               <a class="icon-btn" href="${esc(editorUrl(userSite(n)))}" aria-label="Open in VS Code" data-tip-text="Open in VS Code">${svgIcon("external")}</a>
               <span class="defined-name" >${esc(basename(sourceOf(n)))}</span>
             </div>` : ""}
@@ -1044,6 +1080,13 @@
         copySrc.addEventListener("mousemove", (ev) => moveTip(ev));
         copySrc.addEventListener("mouseleave", hideTip);
       }
+      const showValue = el.details.querySelector("[data-show-value]");
+      if (showValue) {
+        showValue.addEventListener("click", (ev) => toggleCode(n, ev, "value", true));
+        showValue.addEventListener("mouseenter", (ev) => showTip(ev, `Returned: <span class="mono">${esc(valuePreview(n, 80))}</span>`));
+        showValue.addEventListener("mouseleave", hideTip);
+      }
+      wireValue(el.details, n);
       const showCode = el.details.querySelector("[data-show-code]");
       if (showCode) {
         showCode.addEventListener("click", (ev) => toggleCode(n, ev));
@@ -1070,6 +1113,9 @@
 
     function detailTabHtml(n) {
       const tab = state.detailTab;
+      if (tab === "value") {
+        return hasValue(n) ? `<div class="code-box">${valueHtml(n)}</div>` : '<div class="muted">Returned nothing.</div>';
+      }
       if (tab === "args") {
         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>` : "";
@@ -1343,6 +1389,7 @@
         ["When", `${fmtRel(n.start)} → ${fmtRel(n.end)}`],
         v.tags.length ? ["Tags", esc(v.tags.join(" · "))] : null,
         userSite(n) ? [siteLabel(n) === "Called at" ? "Called" : "Defined", `<span class="mono">${esc(sourceOf(n))}</span>`] : null,
+        hasValue(n) ? ["Returns", `<span class="mono">${esc(valuePreview(n, 90))}</span>`] : null,
         n.children.length ? ["Children", String(n.children.length)] : null,
         n.marks.length ? ["Events", String(n.marks.length)] : null,
       ].filter(Boolean);
@@ -1391,6 +1438,7 @@
     codeEl.hidden = true;
     document.body.appendChild(codeEl);
     let codeFor = null;
+    let codeTab = null;
     let codeAway = null;
     /** A site inside omkit or an installed package — library source, not the user's. */
     function isLib(site) {
@@ -1416,6 +1464,7 @@
     function codeTabs(n) {
       const tabs = [];
       if (promptOf(n)) tabs.push({ key: "prompt", label: "Prompt" });
+      if (hasValue(n)) tabs.push({ key: "value", label: "Returned" });
       const mine = userSite(n);
       if (codeOf(mine)) tabs.push({ key: "user", label: siteLabel(n) === "Called at" ? "Call site" : "Source", site: mine });
       const def = n.v.definedAt;
@@ -1423,11 +1472,36 @@
       return tabs;
     }
     function hasCode(n) {
-      return codeTabs(n).length > 0;
+      return codeTabs(n).some((t) => t.key !== "value");
     }
     function relOf(site) {
       return (model.data.sources && model.data.sources[site]) || String(site).replace(/:\d+(:\d+)?$/, "");
     }
+    function hasValue(n) {
+      return n.v.value !== undefined || !!n.v.valueNote;
+    }
+    function valuePreview(n, max) {
+      if (n.v.value === undefined) return n.v.valueNote || "";
+      return truncate(oneLine(n.v.value), max);
+    }
+    /** The returned value in the code view: pretty JSON, highlighted, numbered, copyable. */
+    function valueHtml(n) {
+      if (n.v.value === undefined) {
+        return `<div class="pp"><div class="muted">${esc(n.v.valueNote || "Returned nothing.")}</div></div>`;
+      }
+      const text = json(n.v.value);
+      const lines = highlight(text);
+      const kind = Array.isArray(n.v.value) ? `array · ${n.v.value.length} items` : n.v.value === null ? "null" : typeof n.v.value === "object" ? `object · ${Object.keys(n.v.value).length} keys` : typeof n.v.value;
+      return `<div class="cp-tools"><span class="muted">${esc(kind)} · ${lines.length} line${lines.length > 1 ? "s" : ""} · ${fmtSize(text.length)}</span>
+          <button class="btn solo small" data-a="copy-json">${svgIcon("copy")}Copy JSON</button></div>
+        <div class="cp-code">${lines
+          .map((html, i) => `<div class="cl"><span class="ln">${i + 1}</span><span class="lc">${html || " "}</span></div>`)
+          .join("")}</div>`;
+    }
+    function wireValue(root, n) {
+      const b = root.querySelector('[data-a="copy-json"]');
+      if (b) b.addEventListener("click", () => copy(json(n.v.value), "Copied the returned value"));
+    }
     function codeHtml(site) {
       const c = codeOf(site);
       const line = Number((/:(\d+)(?::\d+)?$/.exec(site) || [])[1]);
@@ -1464,11 +1538,13 @@
         ${answer}
       </div>`;
     }
-    function toggleCode(n, ev, want) {
-      if (codeFor === n.id && !want) return closeCode();
+    function toggleCode(n, ev, want, toggle) {
+      // the <> closes whatever is open on its node; the return button closes only its own tab
+      if (codeFor === n.id && (!want || (toggle && codeTab === want))) return closeCode();
       const tabs = codeTabs(n);
       if (!tabs.length) return;
-      const tab = tabs.find((t) => t.key === want) || tabs[0];
+      const tab = tabs.find((t) => t.key === want) || tabs.find((t) => t.key !== "value") || tabs[0];
+      codeTab = tab.key;
       hideTip();
       const reopen = codeFor !== n.id;
       codeFor = n.id;
@@ -1483,7 +1559,8 @@
           <button class="icon-btn" data-a="close" aria-label="Close">${svgIcon("close")}</button>
         </div>
         ${tabs.length > 1 ? `<div class="cp-tabs">${tabs.map((t) => `<button class="tab ${t === tab ? "active" : ""}" data-tab="${t.key}">${esc(t.label)}</button>`).join("")}</div>` : ""}
-        <div class="cp-body">${tab.key === "prompt" ? promptHtml(promptOf(n)) : codeHtml(site)}</div>`;
+        <div class="cp-body">${tab.key === "prompt" ? promptHtml(promptOf(n)) : tab.key === "value" ? valueHtml(n) : codeHtml(site)}</div>`;
+      wireValue(codeEl, n);
       const cp = codeEl.querySelector('[data-a="copy"]');
       if (cp) cp.addEventListener("click", () => copy(rel, `Copied ${rel}`));
       codeEl.querySelector('[data-a="close"]').addEventListener("click", closeCode);
@@ -1503,7 +1580,7 @@
       if (at) at.scrollIntoView({ block: "center" });
       if (codeAway) document.removeEventListener("mousedown", codeAway, true);
       codeAway = (e) => {
-        if (!codeEl.contains(e.target) && !e.target.closest(".code-btn, [data-show-code]")) closeCode();
+        if (!codeEl.contains(e.target) && !e.target.closest(".code-btn, [data-show-code], [data-show-value]")) closeCode();
       };
       setTimeout(() => codeAway && document.addEventListener("mousedown", codeAway, true), 0);
     }
@@ -1710,7 +1787,7 @@
       if (m.index > last) parts.push([null, text.slice(last, m.index)]);
       let cls = null;
       if (m[1]) cls = "tk-c";
-      else if (m[2]) cls = "tk-s";
+      else if (m[2]) cls = /^\s*:/.test(text.slice(TOKEN.lastIndex, TOKEN.lastIndex + 8)) ? "tk-p" : "tk-s";
       else if (m[3]) cls = "tk-n";
       else if (m[4]) {
         if (KEYWORDS.has(m[4])) cls = "tk-k";

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

@@ -31,6 +31,10 @@ export interface NodeView {
     };
     /** The definition's `.args()` schema as JSON Schema; absent without one. */
     readonly inputSchema?: unknown;
+    /** What the node returned, when JSON can carry it; absent for `undefined` and for failures. */
+    readonly value?: unknown;
+    /** Why a returned value is not in {@link value}: what it was, and that it was too big or not JSON. */
+    readonly valueNote?: string;
     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.13",
+  "version": "0.8.14",
   "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",