@zenera/neo 1.1.0

package/dist/inspect/css.d.ts

@@ -0,0 +1,2 @@
+export declare const CSS = "\n:root {\n  --bg: #0f1115; --panel: #161922; --line: #262b36; --fg: #d7dbe3; --dim: #8a92a6;\n  --accent: #6ea8fe; --ok: #4ec9a0; --err: #f0776c; --warn: #e2b341; --mono: ui-monospace, SFMono-Regular, Menlo, monospace;\n}\n* { box-sizing: border-box; }\nbody { margin: 0; background: var(--bg); color: var(--fg);\n  font: 14px/1.5 system-ui, -apple-system, Segoe UI, sans-serif; }\nheader { padding: 12px 16px; border-bottom: 1px solid var(--line); background: var(--panel);\n  display: flex; flex-wrap: wrap; gap: 8px 20px; align-items: baseline; }\nheader h1 { font-size: 15px; margin: 0 12px 0 0; font-weight: 600; }\nheader .kv { color: var(--dim); font-size: 12px; }\nheader .kv b { color: var(--fg); font-weight: 600; }\nmain { display: grid; grid-template-columns: 340px 1fr; height: calc(100vh - 49px); }\naside { border-right: 1px solid var(--line); overflow: auto; background: var(--panel); }\n.pad { padding: 10px; position: sticky; top: 0; background: var(--panel); border-bottom: 1px solid var(--line); }\n#filter { width: 100%; padding: 6px 8px; background: var(--bg); color: var(--fg);\n  border: 1px solid var(--line); border-radius: 6px; }\n#timeline { list-style: none; margin: 0; padding: 4px 0; }\n#timeline li { padding: 6px 10px; border-left: 3px solid transparent; cursor: pointer; }\n#timeline li:hover { background: #1c2130; }\n#timeline li.sel { background: #1f2637; border-left-color: var(--accent); }\n#timeline li.covered { opacity: .45; }\n#timeline .row { display: flex; gap: 6px; align-items: baseline; }\n#timeline .t { color: var(--fg); font: 11px var(--mono); min-width: 38px; text-align: right; }\n#timeline .t.same { color: #3d4453; }\n#timeline .dur { margin-left: auto; color: var(--dim); font: 11px var(--mono); }\n#timeline .idx { color: var(--dim); font: 11px var(--mono); min-width: 22px; }\n#timeline .prev { color: var(--dim); font-size: 11px; white-space: nowrap;\n  overflow: hidden; text-overflow: ellipsis; padding-left: 44px; }\n/* Branch histories are contiguous in this list, so a coloured edge plus a\n   header is enough to stop ten parallel branches reading as one long run. */\n#timeline li.sep { cursor: default; padding: 10px 10px 4px; display: flex; gap: 7px;\n  align-items: center; font-size: 11px; letter-spacing: .06em; text-transform: uppercase;\n  color: var(--dim); border-left-color: transparent; }\n#timeline li.sep:hover { background: none; }\n#timeline li.sep .dot { width: 8px; height: 8px; border-radius: 2px;\n  background: var(--bc, var(--dim)); }\n/* The group header shouts in uppercase; its elapsed time should not. */\n#timeline li.sep .dur { text-transform: none; letter-spacing: 0; }\n/* The branch the join actually waited for. */\n#timeline li.sep.slow { background: #232a38; color: var(--fg); }\n#timeline li.sep.slow .dur { color: var(--fg); }\n#timeline li.branch { padding-left: 20px; border-left-color: var(--bc, var(--line)); }\n#timeline li.branch.sel { border-left-color: var(--bc, var(--accent)); }\n#middle { display: flex; flex-direction: column; overflow: hidden; }\n.tabs { display: flex; gap: 4px; padding: 8px 12px; border-bottom: 1px solid var(--line); }\n.tabs button { background: none; border: 1px solid transparent; color: var(--dim);\n  padding: 4px 12px; border-radius: 6px; cursor: pointer; font-size: 13px; }\n.tabs button.on { color: var(--fg); background: var(--panel); border-color: var(--line); }\n#detail { overflow: auto; padding: 16px; flex: 1; }\n#stats { overflow: auto; padding: 16px; flex: 1; }\ntable.st { width: 100%; border-collapse: collapse; font: 12px var(--mono); }\ntable.st th { text-align: right; color: var(--dim); font-weight: 600; padding: 6px 12px;\n  border-bottom: 1px solid var(--line); white-space: nowrap; }\ntable.st td { text-align: right; padding: 5px 12px; border-bottom: 1px solid #1d2230;\n  white-space: nowrap; }\ntable.st th:first-child, table.st td:first-child { text-align: left; }\ntable.st tbody tr:hover { background: #1c2130; }\ntable.st tbody tr:last-child td { border-bottom: none; }\n/* The total is a different kind of row, not one more of the same: it gets its\n   own band so nobody reads it as another model or another agent. */\ntable.st tfoot td { color: var(--fg); font-weight: 600; background: #191e2a;\n  border-top: 1px solid #2b3346; border-bottom: none; padding: 7px 12px; }\ntable.st tfoot td:first-child { color: var(--dim); text-transform: uppercase;\n  letter-spacing: .07em; font-size: 11px; }\n/* Two panes hold a zoomable diagram (the run graph and the architecture), so\n   everything about one is written for both. */\n.pane { display: flex; flex-direction: column; overflow: hidden; flex: 1; }\n/* An explicit display on the pane would otherwise beat the hidden attribute\n   and both views would show at once. */\n.pane[hidden], #detail[hidden], #stats[hidden] { display: none; }\n.pane svg { max-width: none; display: block; }\n.pane .node { cursor: pointer; }\n/* A node with nothing behind it in this run is not clickable, and says so. */\n.pane .node.idle { cursor: default; }\n.gtools { display: flex; align-items: center; gap: 6px; padding: 6px 10px;\n  border-bottom: 1px solid var(--line); background: var(--panel); }\n.gtools button { background: var(--bg); border: 1px solid var(--line); color: var(--fg);\n  border-radius: 6px; padding: 2px 10px; cursor: pointer; font: 12px var(--mono); }\n.gtools button:hover { border-color: var(--accent); }\n.gtools .hint:first-of-type { margin-left: 8px; }\n.gtools .lvl { margin-left: auto; font-family: var(--mono); }\n/* The canvas is transformed, not scrolled: panning has to work past the edges\n   of the diagram, which overflow:auto would forbid. */\n.viewport { flex: 1; overflow: hidden; position: relative; cursor: grab; touch-action: none;\n  user-select: none; -webkit-user-select: none; }\n.viewport.drag { cursor: grabbing; }\n.canvas { position: absolute; top: 0; left: 0; transform-origin: 0 0; }\n.hint { color: var(--dim); font-size: 12px; }\n.hint.pad { padding: 16px; }\n.type { font-size: 11px; letter-spacing: .04em; text-transform: uppercase;\n  padding: 1px 6px; border-radius: 4px; background: #232a38; color: var(--dim); }\n.type.llm_call { background: #1e3357; color: #9dc1ff; }\n.type.tool_call, .type.tool_result { background: #1e3d33; color: #8ee0c2; }\n.type.compaction { background: #40331a; color: var(--warn); }\n.type.fork, .type.join { background: #3a2450; color: #d1a6ff; }\n.type.final_output { background: #14392c; color: var(--ok); }\n.type.err { background: #4a1f1c; color: var(--err); }\nh2.dt { font-size: 16px; margin: 0 0 4px; display: flex; gap: 10px; align-items: center; }\n.meta { color: var(--dim); font-size: 12px; font-family: var(--mono); margin-bottom: 14px;\n  display: flex; flex-wrap: wrap; gap: 4px 14px; }\nsection.blk { border: 1px solid var(--line); border-radius: 8px; margin-bottom: 12px;\n  background: var(--panel); overflow: hidden; }\nsection.blk > h3 { margin: 0; padding: 7px 12px; font-size: 12px; font-weight: 600;\n  color: var(--dim); border-bottom: 1px solid var(--line); letter-spacing: .03em; }\nsection.blk > h3 .tag { float: right; font-weight: 400; }\nsection.blk.sys { border-left: 3px solid var(--warn); }\n/* An LLM call has three things a reader wants to tell apart at a glance: what\n   went in, what came back, and what it cost. Groups carry the first two. */\n.group { border: 1px solid var(--line); border-radius: 10px; margin-bottom: 14px;\n  background: #12151d; overflow: hidden; }\n.group > .ghdr { display: flex; align-items: center; gap: 10px; padding: 8px 12px;\n  font-size: 11px; font-weight: 700; letter-spacing: .09em; text-transform: uppercase;\n  background: #1b2130; border-bottom: 1px solid var(--line); }\n.group > .ghdr .tag { margin-left: auto; font: 11px var(--mono); font-weight: 400;\n  letter-spacing: 0; text-transform: none; color: var(--dim); }\n.group > .body { padding: 10px; }\n.group > .body > .blk:last-child { margin-bottom: 0; }\n.group.req { border-left: 3px solid var(--accent); }\n.group.req > .ghdr { color: #9dc1ff; }\n.group.res { border-left: 3px solid var(--ok); }\n.group.res > .ghdr { color: #8ee0c2; }\n.stats { display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 14px; }\n.stat { background: var(--panel); border: 1px solid var(--line); border-radius: 999px;\n  padding: 3px 12px; font: 12px var(--mono); color: var(--dim); }\n.stat b { color: var(--fg); font-weight: 600; }\npre { margin: 0; padding: 10px 12px; font: 12px/1.55 var(--mono); white-space: pre-wrap;\n  word-break: break-word; overflow-wrap: anywhere; }\npre.text { white-space: pre-wrap; }\nimg.media { display: block; max-width: 100%; max-height: 420px; margin: 10px 12px;\n  border: 1px solid var(--line); border-radius: 6px; background: #0d1017; }\nimg.media.thumb { max-height: 88px; margin: 8px 12px; cursor: zoom-in; }\n.msg { border-top: 1px solid var(--line); border-left: 3px solid transparent; }\n.msg:first-of-type { border-top: none; }\n.msg > .role { padding: 5px 12px; font-size: 11px; text-transform: uppercase;\n  letter-spacing: .05em; color: var(--dim); background: #1b202c;\n  display: flex; justify-content: space-between; }\n.msg.user > .role { color: #9dc1ff; }\n.msg.user { border-left-color: #35507f; }\n.msg.assistant > .role { color: #c3a6ff; }\n.msg.assistant { border-left-color: #5a4380; }\n.msg.tool > .role { color: #8ee0c2; }\n.msg.tool { border-left-color: #2f6b58; }\n.msg.system > .role { color: var(--warn); }\n.msg.system { border-left-color: #7a6535; }\n.msg.err > .role { color: var(--err); }\n.msg.err { border-left-color: #8a3a33; }\n.call { border-top: 1px dashed var(--line); }\n.call .name { padding: 5px 12px; font: 12px var(--mono); color: #8ee0c2; }\ndetails > summary { cursor: pointer; padding: 6px 12px; color: var(--dim); font-size: 12px; }\n.badge { font: 11px var(--mono); color: var(--dim); }\n.badge.ok { color: var(--ok); } .badge.bad { color: var(--err); }\n.empty { padding: 10px 12px; color: var(--dim); font-size: 12px; font-style: italic; }\nbutton.link { background: none; border: none; color: var(--accent); cursor: pointer;\n  font: 12px var(--mono); padding: 0 6px 0 0; }\n";
+//# sourceMappingURL=css.d.ts.map

package/dist/inspect/css.js

@@ -0,0 +1,164 @@
+// ---------------------------------------------------------------------------
+// Page styles
+//
+// Split out of the report code for no reason other than size: this is one
+// string, embedded verbatim into the <style> element by `page()`.
+// ---------------------------------------------------------------------------
+export const CSS = `
+:root {
+  --bg: #0f1115; --panel: #161922; --line: #262b36; --fg: #d7dbe3; --dim: #8a92a6;
+  --accent: #6ea8fe; --ok: #4ec9a0; --err: #f0776c; --warn: #e2b341; --mono: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--fg);
+  font: 14px/1.5 system-ui, -apple-system, Segoe UI, sans-serif; }
+header { padding: 12px 16px; border-bottom: 1px solid var(--line); background: var(--panel);
+  display: flex; flex-wrap: wrap; gap: 8px 20px; align-items: baseline; }
+header h1 { font-size: 15px; margin: 0 12px 0 0; font-weight: 600; }
+header .kv { color: var(--dim); font-size: 12px; }
+header .kv b { color: var(--fg); font-weight: 600; }
+main { display: grid; grid-template-columns: 340px 1fr; height: calc(100vh - 49px); }
+aside { border-right: 1px solid var(--line); overflow: auto; background: var(--panel); }
+.pad { padding: 10px; position: sticky; top: 0; background: var(--panel); border-bottom: 1px solid var(--line); }
+#filter { width: 100%; padding: 6px 8px; background: var(--bg); color: var(--fg);
+  border: 1px solid var(--line); border-radius: 6px; }
+#timeline { list-style: none; margin: 0; padding: 4px 0; }
+#timeline li { padding: 6px 10px; border-left: 3px solid transparent; cursor: pointer; }
+#timeline li:hover { background: #1c2130; }
+#timeline li.sel { background: #1f2637; border-left-color: var(--accent); }
+#timeline li.covered { opacity: .45; }
+#timeline .row { display: flex; gap: 6px; align-items: baseline; }
+#timeline .t { color: var(--fg); font: 11px var(--mono); min-width: 38px; text-align: right; }
+#timeline .t.same { color: #3d4453; }
+#timeline .dur { margin-left: auto; color: var(--dim); font: 11px var(--mono); }
+#timeline .idx { color: var(--dim); font: 11px var(--mono); min-width: 22px; }
+#timeline .prev { color: var(--dim); font-size: 11px; white-space: nowrap;
+  overflow: hidden; text-overflow: ellipsis; padding-left: 44px; }
+/* Branch histories are contiguous in this list, so a coloured edge plus a
+   header is enough to stop ten parallel branches reading as one long run. */
+#timeline li.sep { cursor: default; padding: 10px 10px 4px; display: flex; gap: 7px;
+  align-items: center; font-size: 11px; letter-spacing: .06em; text-transform: uppercase;
+  color: var(--dim); border-left-color: transparent; }
+#timeline li.sep:hover { background: none; }
+#timeline li.sep .dot { width: 8px; height: 8px; border-radius: 2px;
+  background: var(--bc, var(--dim)); }
+/* The group header shouts in uppercase; its elapsed time should not. */
+#timeline li.sep .dur { text-transform: none; letter-spacing: 0; }
+/* The branch the join actually waited for. */
+#timeline li.sep.slow { background: #232a38; color: var(--fg); }
+#timeline li.sep.slow .dur { color: var(--fg); }
+#timeline li.branch { padding-left: 20px; border-left-color: var(--bc, var(--line)); }
+#timeline li.branch.sel { border-left-color: var(--bc, var(--accent)); }
+#middle { display: flex; flex-direction: column; overflow: hidden; }
+.tabs { display: flex; gap: 4px; padding: 8px 12px; border-bottom: 1px solid var(--line); }
+.tabs button { background: none; border: 1px solid transparent; color: var(--dim);
+  padding: 4px 12px; border-radius: 6px; cursor: pointer; font-size: 13px; }
+.tabs button.on { color: var(--fg); background: var(--panel); border-color: var(--line); }
+#detail { overflow: auto; padding: 16px; flex: 1; }
+#stats { overflow: auto; padding: 16px; flex: 1; }
+table.st { width: 100%; border-collapse: collapse; font: 12px var(--mono); }
+table.st th { text-align: right; color: var(--dim); font-weight: 600; padding: 6px 12px;
+  border-bottom: 1px solid var(--line); white-space: nowrap; }
+table.st td { text-align: right; padding: 5px 12px; border-bottom: 1px solid #1d2230;
+  white-space: nowrap; }
+table.st th:first-child, table.st td:first-child { text-align: left; }
+table.st tbody tr:hover { background: #1c2130; }
+table.st tbody tr:last-child td { border-bottom: none; }
+/* The total is a different kind of row, not one more of the same: it gets its
+   own band so nobody reads it as another model or another agent. */
+table.st tfoot td { color: var(--fg); font-weight: 600; background: #191e2a;
+  border-top: 1px solid #2b3346; border-bottom: none; padding: 7px 12px; }
+table.st tfoot td:first-child { color: var(--dim); text-transform: uppercase;
+  letter-spacing: .07em; font-size: 11px; }
+/* Two panes hold a zoomable diagram (the run graph and the architecture), so
+   everything about one is written for both. */
+.pane { display: flex; flex-direction: column; overflow: hidden; flex: 1; }
+/* An explicit display on the pane would otherwise beat the hidden attribute
+   and both views would show at once. */
+.pane[hidden], #detail[hidden], #stats[hidden] { display: none; }
+.pane svg { max-width: none; display: block; }
+.pane .node { cursor: pointer; }
+/* A node with nothing behind it in this run is not clickable, and says so. */
+.pane .node.idle { cursor: default; }
+.gtools { display: flex; align-items: center; gap: 6px; padding: 6px 10px;
+  border-bottom: 1px solid var(--line); background: var(--panel); }
+.gtools button { background: var(--bg); border: 1px solid var(--line); color: var(--fg);
+  border-radius: 6px; padding: 2px 10px; cursor: pointer; font: 12px var(--mono); }
+.gtools button:hover { border-color: var(--accent); }
+.gtools .hint:first-of-type { margin-left: 8px; }
+.gtools .lvl { margin-left: auto; font-family: var(--mono); }
+/* The canvas is transformed, not scrolled: panning has to work past the edges
+   of the diagram, which overflow:auto would forbid. */
+.viewport { flex: 1; overflow: hidden; position: relative; cursor: grab; touch-action: none;
+  user-select: none; -webkit-user-select: none; }
+.viewport.drag { cursor: grabbing; }
+.canvas { position: absolute; top: 0; left: 0; transform-origin: 0 0; }
+.hint { color: var(--dim); font-size: 12px; }
+.hint.pad { padding: 16px; }
+.type { font-size: 11px; letter-spacing: .04em; text-transform: uppercase;
+  padding: 1px 6px; border-radius: 4px; background: #232a38; color: var(--dim); }
+.type.llm_call { background: #1e3357; color: #9dc1ff; }
+.type.tool_call, .type.tool_result { background: #1e3d33; color: #8ee0c2; }
+.type.compaction { background: #40331a; color: var(--warn); }
+.type.fork, .type.join { background: #3a2450; color: #d1a6ff; }
+.type.final_output { background: #14392c; color: var(--ok); }
+.type.err { background: #4a1f1c; color: var(--err); }
+h2.dt { font-size: 16px; margin: 0 0 4px; display: flex; gap: 10px; align-items: center; }
+.meta { color: var(--dim); font-size: 12px; font-family: var(--mono); margin-bottom: 14px;
+  display: flex; flex-wrap: wrap; gap: 4px 14px; }
+section.blk { border: 1px solid var(--line); border-radius: 8px; margin-bottom: 12px;
+  background: var(--panel); overflow: hidden; }
+section.blk > h3 { margin: 0; padding: 7px 12px; font-size: 12px; font-weight: 600;
+  color: var(--dim); border-bottom: 1px solid var(--line); letter-spacing: .03em; }
+section.blk > h3 .tag { float: right; font-weight: 400; }
+section.blk.sys { border-left: 3px solid var(--warn); }
+/* An LLM call has three things a reader wants to tell apart at a glance: what
+   went in, what came back, and what it cost. Groups carry the first two. */
+.group { border: 1px solid var(--line); border-radius: 10px; margin-bottom: 14px;
+  background: #12151d; overflow: hidden; }
+.group > .ghdr { display: flex; align-items: center; gap: 10px; padding: 8px 12px;
+  font-size: 11px; font-weight: 700; letter-spacing: .09em; text-transform: uppercase;
+  background: #1b2130; border-bottom: 1px solid var(--line); }
+.group > .ghdr .tag { margin-left: auto; font: 11px var(--mono); font-weight: 400;
+  letter-spacing: 0; text-transform: none; color: var(--dim); }
+.group > .body { padding: 10px; }
+.group > .body > .blk:last-child { margin-bottom: 0; }
+.group.req { border-left: 3px solid var(--accent); }
+.group.req > .ghdr { color: #9dc1ff; }
+.group.res { border-left: 3px solid var(--ok); }
+.group.res > .ghdr { color: #8ee0c2; }
+.stats { display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 14px; }
+.stat { background: var(--panel); border: 1px solid var(--line); border-radius: 999px;
+  padding: 3px 12px; font: 12px var(--mono); color: var(--dim); }
+.stat b { color: var(--fg); font-weight: 600; }
+pre { margin: 0; padding: 10px 12px; font: 12px/1.55 var(--mono); white-space: pre-wrap;
+  word-break: break-word; overflow-wrap: anywhere; }
+pre.text { white-space: pre-wrap; }
+img.media { display: block; max-width: 100%; max-height: 420px; margin: 10px 12px;
+  border: 1px solid var(--line); border-radius: 6px; background: #0d1017; }
+img.media.thumb { max-height: 88px; margin: 8px 12px; cursor: zoom-in; }
+.msg { border-top: 1px solid var(--line); border-left: 3px solid transparent; }
+.msg:first-of-type { border-top: none; }
+.msg > .role { padding: 5px 12px; font-size: 11px; text-transform: uppercase;
+  letter-spacing: .05em; color: var(--dim); background: #1b202c;
+  display: flex; justify-content: space-between; }
+.msg.user > .role { color: #9dc1ff; }
+.msg.user { border-left-color: #35507f; }
+.msg.assistant > .role { color: #c3a6ff; }
+.msg.assistant { border-left-color: #5a4380; }
+.msg.tool > .role { color: #8ee0c2; }
+.msg.tool { border-left-color: #2f6b58; }
+.msg.system > .role { color: var(--warn); }
+.msg.system { border-left-color: #7a6535; }
+.msg.err > .role { color: var(--err); }
+.msg.err { border-left-color: #8a3a33; }
+.call { border-top: 1px dashed var(--line); }
+.call .name { padding: 5px 12px; font: 12px var(--mono); color: #8ee0c2; }
+details > summary { cursor: pointer; padding: 6px 12px; color: var(--dim); font-size: 12px; }
+.badge { font: 11px var(--mono); color: var(--dim); }
+.badge.ok { color: var(--ok); } .badge.bad { color: var(--err); }
+.empty { padding: 10px 12px; color: var(--dim); font-size: 12px; font-style: italic; }
+button.link { background: none; border: none; color: var(--accent); cursor: pointer;
+  font: 12px var(--mono); padding: 0 6px 0 0; }
+`;
+//# sourceMappingURL=css.js.map

package/dist/inspect/index.d.ts

@@ -0,0 +1,9 @@
+import { type ReportOptions, type RunReport } from './report.ts';
+import type { AgentState } from '../state.ts';
+import type { PayloadResolver } from '../payload.ts';
+export { buildRunReport, MAX_BLOB_BYTES, MERMAID_URL, type ReportOptions, type RunReport, } from './report.ts';
+/** Report → one standalone HTML document. */
+export declare function renderReportHtml(report: RunReport, opts?: ReportOptions): string;
+/** The usual entry point: state in, HTML out. */
+export declare function renderRunReport(state: AgentState, payloads: PayloadResolver, opts?: ReportOptions): Promise<string>;
+//# sourceMappingURL=index.d.ts.map

package/dist/inspect/index.js

@@ -0,0 +1,12 @@
+import { page } from "./page.js";
+import { buildRunReport, MERMAID_URL } from "./report.js";
+export { buildRunReport, MAX_BLOB_BYTES, MERMAID_URL, } from "./report.js";
+/** Report → one standalone HTML document. */
+export function renderReportHtml(report, opts = {}) {
+    return page(report, opts.mermaidUrl ?? MERMAID_URL);
+}
+/** The usual entry point: state in, HTML out. */
+export async function renderRunReport(state, payloads, opts = {}) {
+    return renderReportHtml(await buildRunReport(state, payloads, opts), opts);
+}
+//# sourceMappingURL=index.js.map

package/dist/inspect/page.d.ts

@@ -0,0 +1,3 @@
+import type { RunReport } from './report.ts';
+export declare function page(report: RunReport, mermaidUrl: string): string;
+//# sourceMappingURL=page.d.ts.map

package/dist/inspect/page.js

@@ -0,0 +1,93 @@
+import { CLIENT } from "./client.js";
+import { CSS } from "./css.js";
+// ---------------------------------------------------------------------------
+// The document
+//
+// One function, one string. The page is data-driven: all of the report travels
+// as JSON and the rendering happens in the browser, so the only thing this
+// module has to get right is the shell and the escaping.
+// ---------------------------------------------------------------------------
+export function page(report, mermaidUrl) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(report.title)}</title>
+<style>${CSS}</style>
+</head>
+<body>
+<header id="head"></header>
+<main>
+  <aside id="side">
+    <div class="pad"><input id="filter" type="search" placeholder="filter nodes…" autocomplete="off"></div>
+    <ol id="timeline"></ol>
+  </aside>
+  <section id="middle">
+    <div class="tabs" id="viewtabs">
+      <button data-view="graph" class="on">Graph</button>
+      <button data-view="detail">Detail</button>
+      <button data-view="stats">Stats</button>
+      <button data-view="agents">Agents</button>
+    </div>
+    <div id="graph" class="pane">
+      <div class="gtools">
+        <button data-zoom="out" title="zoom out">−</button>
+        <button data-zoom="in" title="zoom in">+</button>
+        <button data-zoom="fit" title="fit to window (double-click the canvas)">fit</button>
+        <button data-zoom="reset" title="actual size">1:1</button>
+        <span class="hint">scroll to zoom · drag to pan</span>
+        <span class="hint lvl">100%</span>
+      </div>
+      <div class="viewport"><div class="canvas"><div class="hint pad">rendering…</div></div></div>
+    </div>
+    <div id="detail" hidden></div>
+    <div id="stats" hidden></div>
+    <div id="agents" class="pane" hidden>
+      <div class="gtools">
+        <button data-zoom="out" title="zoom out">−</button>
+        <button data-zoom="in" title="zoom in">+</button>
+        <button data-zoom="fit" title="fit to window (double-click the canvas)">fit</button>
+        <button data-zoom="reset" title="actual size">1:1</button>
+        <span class="hint" id="alegend"></span>
+        <span class="hint lvl">100%</span>
+      </div>
+      <div class="viewport"><div class="canvas"><div class="hint pad">rendering…</div></div></div>
+    </div>
+  </section>
+</main>
+<script id="run-data" type="application/json">${embedJson(report)}</script>
+<script type="module">
+const MERMAID_URL = ${embedJson(mermaidUrl)};
+${CLIENT}
+</script>
+</body>
+</html>
+`;
+}
+// ---------------------------------------------------------------------------
+// Escaping
+// ---------------------------------------------------------------------------
+/**
+ * Blob content is model output and tool output — untrusted by definition. Two
+ * rules keep it inert: it reaches the document only as JSON inside a non-executable
+ * `application/json` block, and the page only ever writes it through
+ * `textContent`. Escaping every `<`, `>` and `&` makes the first rule
+ * unbreakable: no byte sequence in a payload can close the script element.
+ */
+function embedJson(value) {
+    return JSON.stringify(value)
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/&/g, '\\u0026')
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029');
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+//# sourceMappingURL=page.js.map

package/dist/inspect/report.d.ts

@@ -0,0 +1,54 @@
+import type { Architecture } from '../architecture.ts';
+import { type PayloadResolver } from '../payload.ts';
+import type { AgentState } from '../state.ts';
+/** Default per-payload inline cap. Keeps one runaway tool result from turning
+ *  a report into a file no editor will open. */
+export declare const MAX_BLOB_BYTES: number;
+export declare const MERMAID_URL = "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+export interface ReportOptions {
+    title?: string;
+    /** per-payload inline cap; larger values are cut, with a visible marker */
+    maxBlobBytes?: number;
+    /**
+     * Where the page loads Mermaid from. The diagram is the one thing the page
+     * cannot carry itself without bloating past a megabyte; everything else is
+     * inlined, and the timeline works with no network at all.
+     */
+    mermaidUrl?: string;
+    /**
+     * The declared wiring, from `AgentRunner.describe()`. Optional because a
+     * report is often rendered from a stored state with no live runner around;
+     * the page then reconstructs what the run itself touched, which is a
+     * strictly smaller picture but never a wrong one.
+     */
+    architecture?: Architecture;
+}
+/** Everything the page needs, and nothing that needs a store to interpret. */
+export interface RunReport {
+    title: string;
+    generatedAt: string;
+    state: AgentState;
+    /** sha256 → content, deduped by address exactly as in a `RunBundle` */
+    blobs: Record<string, string>;
+    /** addresses whose content was cut to `maxBlobBytes` */
+    truncated: string[];
+    /**
+     * Base64 `data:` uris lifted out of the state and the payloads above,
+     * both of which now refer to them as `media:<index>`. A conversation
+     * re-sends its images with every turn, so a run with five model calls
+     * would otherwise inline the same megabyte six times — and each recorded
+     * request would blow past `maxBlobBytes`, arriving cut mid-string and
+     * unparseable. Blob content therefore no longer hashes to the address it
+     * is filed under: a report is a thing to read, not a bundle to restore.
+     */
+    media: string[];
+    /** the declared wiring, when the caller had a runner to ask */
+    architecture?: Architecture;
+}
+/**
+ * Resolves a state into a self-describing report. Separate from rendering so a
+ * caller can ship the JSON somewhere else (a service, a test fixture) instead
+ * of the page.
+ */
+export declare function buildRunReport(state: AgentState, payloads: PayloadResolver, opts?: ReportOptions): Promise<RunReport>;
+//# sourceMappingURL=report.d.ts.map

package/dist/inspect/report.js

@@ -0,0 +1,62 @@
+import { collectPayloads } from "../payload.js";
+// ---------------------------------------------------------------------------
+// Run inspector — a single HTML file that explains a run
+//
+// A state is a graph of references, which makes it cheap to store and useless
+// to read. This module does the inverse of the storage design: it resolves
+// every payload a run points at and inlines the whole thing into one page, so
+// debugging needs no server, no store credentials and no live process — just a
+// file you can open, attach to a bug report or diff against yesterday's run.
+// ---------------------------------------------------------------------------
+/** Default per-payload inline cap. Keeps one runaway tool result from turning
+ *  a report into a file no editor will open. */
+export const MAX_BLOB_BYTES = 512 * 1024;
+export const MERMAID_URL = 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+/** Base64 data uris only: the charset ends at the closing JSON quote. */
+const DATA_URL = /data:[\w.+-]+\/[\w.+-]+;base64,[A-Za-z0-9+/=]+/g;
+/** Below this a uri is cheaper to leave in place than to indirect through. */
+const MIN_HOIST = 2048;
+function hoistMedia(text, media) {
+    return text.replace(DATA_URL, (url) => {
+        if (url.length < MIN_HOIST)
+            return url;
+        const at = media.indexOf(url);
+        return `media:${at < 0 ? media.push(url) - 1 : at}`;
+    });
+}
+/**
+ * Resolves a state into a self-describing report. Separate from rendering so a
+ * caller can ship the JSON somewhere else (a service, a test fixture) instead
+ * of the page.
+ */
+export async function buildRunReport(state, payloads, opts = {}) {
+    const limit = opts.maxBlobBytes ?? MAX_BLOB_BYTES;
+    const refs = collectPayloads(state);
+    const values = await payloads.getMany(refs);
+    const blobs = {};
+    const truncated = [];
+    const media = [];
+    for (const ref of refs) {
+        const value = hoistMedia(values.get(ref.sha256) ?? '', media);
+        if (value.length > limit) {
+            blobs[ref.sha256] = value.slice(0, limit);
+            truncated.push(ref.sha256);
+        }
+        else {
+            blobs[ref.sha256] = value;
+        }
+    }
+    return {
+        title: opts.title ?? `Run ${state.runId}`,
+        generatedAt: new Date().toISOString(),
+        // The user input carries the same image the requests do. Putting the
+        // whole state through the same table is the difference between one
+        // copy of a photo in the file and one copy per turn.
+        state: JSON.parse(hoistMedia(JSON.stringify(state), media)),
+        blobs,
+        truncated,
+        media,
+        architecture: opts.architecture,
+    };
+}
+//# sourceMappingURL=report.js.map

package/dist/kernel.d.ts

@@ -0,0 +1,178 @@
+import { z } from 'zod';
+import { Agent, AgentRegistry } from './agent.ts';
+import type { PendingToolCall } from './events.ts';
+import { type IdClock } from './ids.ts';
+import { type MemoryOpSpec, type MemoryRecallSpec } from './memory.ts';
+import type { ModelRequest, ModelResponse } from './model.ts';
+import type { Services } from './services.ts';
+import { type Skill } from './skills.ts';
+import type { AgentState } from './state.ts';
+import { type CompactionNode, type FinalOutputNode, type UserInputNode } from './trajectory.ts';
+import { type AnyTool, type Input, type TokenUsage, type ToolOutcome } from './types.ts';
+/**
+ * The kernel is a module of plain functions: it holds no state and no
+ * configuration, so there is nothing to instantiate and nothing hidden. All
+ * nondeterminism (ids, clock) and all I/O (payloads, memory, skills) enter
+ * through the explicit `KernelEnv` argument, which is what makes the same code
+ * usable inside a replay-based workflow engine.
+ *
+ * Deviation from the spec worth knowing: several `apply*` and `createState` are
+ * async, because offloading a value to the `PayloadStore` is I/O. Nothing else
+ * in the kernel touches the outside world.
+ */
+export interface KernelEnv {
+    services: Services;
+    /** Zod schema of a typed run; must match `state.spec.outputSchemaHash`. */
+    output?: z.ZodType;
+    clock?: IdClock;
+}
+export interface CreateStateOptions<T = string, TCtx = unknown> {
+    /** default: a fresh ulid */
+    runId?: string;
+    /** starting agent name */
+    agent: string;
+    input?: Input;
+    /** app context — must be JSON-serializable */
+    context?: TCtx;
+    /** typed-result request: the source of both `T` and validation */
+    output?: z.ZodType<T>;
+    /** pre-rendered; otherwise rendered on the first step */
+    systemPrompt?: string;
+    maxForkDepth?: number;
+}
+/**
+ * The only way to obtain a state. Starting a run is explicit; the loop then
+ * only ever *advances* an existing state.
+ */
+export declare function createState<T = string, TCtx = unknown>(opts: CreateStateOptions<T, TCtx>, env: KernelEnv): Promise<AgentState>;
+/** A persisted run must not silently change its contract on resume. */
+export declare function checkOutputSchema(state: AgentState, env: KernelEnv): void;
+export interface BranchPlan {
+    name: string;
+    agent: string;
+    childRunId: string;
+}
+export type NextAction = {
+    kind: 'llm';
+} | {
+    kind: 'tools';
+    calls: PendingToolCall[];
+} | {
+    kind: 'fork';
+    forkId: string;
+    branches: BranchPlan[];
+} | {
+    kind: 'done';
+    output: FinalOutputNode;
+};
+/** Pure inspection: what must happen next. No I/O, no payload resolution. */
+export declare function nextAction(state: AgentState): NextAction;
+/**
+ * tools(state) = agent tools + handoffs + memory + skills + fork +
+ * final_output. Computed from the state so a rehydrated run offers exactly the
+ * tools it had before the crash.
+ *
+ * Skill-owned tools are declared here whether or not their skill is active: the
+ * gate `lockedSkillTools` installs reads the trajectory when the tool is called,
+ * not when it is declared, so the array the model is sent never mutates
+ * mid-conversation and the provider's prompt cache survives a `skill_load`.
+ */
+export declare function resolveTools<TCtx>(state: AgentState, reg: AgentRegistry<TCtx>, env: KernelEnv): Promise<AnyTool<TCtx>[]>;
+/**
+ * Projection + tool schemas + system prompt for the active agent. The only
+ * place in the kernel that dereferences payloads — everything else works on
+ * refs alone.
+ *
+ * Nothing is appended to the system prompt here: what the model reads is
+ * exactly the `system_prompt` node `applySystemPrompt` recorded, which is what
+ * makes `requestDigest` a meaningful replay check for the prompt.
+ */
+export declare function buildRequest<TCtx>(state: AgentState, reg: AgentRegistry<TCtx>, env: KernelEnv): Promise<ModelRequest>;
+/** Stable fingerprint of a request, for replay divergence detection. */
+export declare function requestDigest(req: ModelRequest): string;
+/**
+ * A request as it goes onto an `llm_call` node: everything that shaped the
+ * call, minus the `signal`, which is machinery rather than content and is not
+ * JSON anyway. Pretty-printed, since the whole point of keeping it is that a
+ * human reads it later.
+ */
+export declare function serializeRequest(req: ModelRequest): string;
+export declare function applyUserInput(state: AgentState, input: Input, env: KernelEnv, synthetic?: boolean): Promise<AgentState>;
+/**
+ * Renders the active agent's instructions into the trajectory. Idempotent: a
+ * matching prompt already in force produces no node, so re-entering the loop
+ * (or resuming) does not litter the history.
+ *
+ * The rendered bytes are the identity. Two compositions that render the same
+ * string *are* the same prompt to the model, the provider cache and replay, so
+ * there is nothing else to hash and no renderer version to pin: a change that
+ * matters changes the bytes, and one that does not, does not.
+ */
+export declare function applySystemPrompt<TCtx>(state: AgentState, reg: AgentRegistry<TCtx>, env: KernelEnv): Promise<AgentState>;
+/** What the driver knows about a model call that the response itself omits. */
+export interface LlmCallOptions<TCtx = unknown> {
+    /** stable fingerprint of the request, for replay divergence detection */
+    digest?: string;
+    /** the request as sent; stored as a payload on the node when given */
+    request?: ModelRequest;
+    /** needed to validate a `fork` call against the agent's declaration */
+    registry?: AgentRegistry<TCtx>;
+}
+/**
+ * Appends the `llm_call` node (plus the nodes its tool calls imply) and moves
+ * the phase on. Typed runs are resolved here too: `final_output` never reaches
+ * tool execution, it is validated against the run's schema on the spot.
+ */
+export declare function applyLlmResponse<TCtx>(state: AgentState, res: ModelResponse, model: string, env: KernelEnv, opts?: LlmCallOptions<TCtx>): Promise<AgentState>;
+/**
+ * Appends the tool result, folds in whatever the tool did to memory or skills,
+ * and performs a hand-off when the call was a `transfer_to_*`.
+ */
+export declare function applyToolResult(state: AgentState, callId: string, outcome: ToolOutcome, env: KernelEnv): Promise<AgentState>;
+/** Records a memory recall or mutation performed by the driver. */
+export declare function applyMemoryEffect(state: AgentState, effect: MemoryRecallSpec | MemoryOpSpec, env: KernelEnv): Promise<AgentState>;
+/** Records a skill activation and the tools it unlocked. */
+export declare function applySkillLoad(state: AgentState, provider: string, skills: Skill[], env: KernelEnv): Promise<AgentState>;
+export interface CompactionSpec {
+    /** ids of the nodes this summary replaces; need not be contiguous */
+    covers: string[];
+    summary: string;
+    reason: CompactionNode['reason'];
+    /** the model's call id when it compacted itself; synthesized otherwise */
+    callId?: string;
+    /** tokens the summarizer burned */
+    usage?: TokenUsage;
+}
+/**
+ * Containment, not deletion: the covered nodes stay in the trajectory for audit
+ * and replay, and only the projection skips them. The log stays append-only.
+ */
+export declare function applyCompaction(state: AgentState, spec: CompactionSpec, env: KernelEnv): Promise<AgentState>;
+export declare function applyFailure(state: AgentState, error: string): AgentState;
+/**
+ * Derives a child state seeded with *real nodes* copied from the parent, not a
+ * frozen `Message[]` blob: the branch can compact its own inherited context,
+ * and at join those nodes splice back into one trajectory. The copy is a
+ * snapshot, so the branch can execute in another process.
+ */
+export declare function createChildState(state: AgentState, forkId: string, branch: string, env: KernelEnv): Promise<AgentState>;
+export interface BranchResult {
+    name: string;
+    status: 'ok' | 'error' | 'aborted';
+    /** what the parent sees for this branch — already summarized by the policy */
+    output: string;
+    error?: string;
+    usage: TokenUsage;
+    childRunId: string;
+    childState: AgentState;
+}
+/**
+ * Folds branches back into the parent. Each branch's history is nested inside
+ * its row of the join, in *declared* branch order — so the result is identical
+ * regardless of completion order, and a walk of the parent array never trips
+ * over someone else's nodes.
+ */
+export declare function applyJoin(state: AgentState, forkId: string, results: BranchResult[], env: KernelEnv): Promise<AgentState>;
+export declare function lastUserInput(state: AgentState): UserInputNode | undefined;
+export { Agent, AgentRegistry };
+//# sourceMappingURL=kernel.d.ts.map