@inflexa-ai/harness 0.42.1 → 0.43.0

package/dist/report-render/value-bridge.js

@@ -13,6 +13,7 @@
  * one call reports each fault at one time.
  */
 import { err, ok } from "neverthrow";
+import { statisticSlot, treeSlot } from "../report-model/block-walk.js";
 /**
  * Map the resolved values of the blocks onto a `RenderValues` map.
  *
@@ -40,16 +41,24 @@ export function bridgeValues(resolutions, figureSrc) {
                 values[resolution.blockId] = { type: "scalar", value: value.value };
                 break;
             }
-            case "table":
-            case "chart": {
+            case "table": {
                 const value = resolution.resolved;
                 if (value.type !== "table") {
-                    mismatches.push(mismatch(resolution.blockId, resolution.kind, "table", value.type));
+                    mismatches.push(mismatch(resolution.blockId, "table", "table", value.type));
                     break;
                 }
                 values[resolution.blockId] = tableValue(value);
                 break;
             }
+            case "chart": {
+                const chart = chartValue(resolution);
+                if (chart.isErr()) {
+                    mismatches.push(...chart.error);
+                    break;
+                }
+                values[resolution.blockId] = chart.value;
+                break;
+            }
             case "figure": {
                 const value = resolution.resolved;
                 if (value.type !== "file") {
@@ -66,6 +75,125 @@ export function bridgeValues(resolutions, figureSrc) {
     }
     return ok(values);
 }
+/**
+ * Pair each block with the resolved value of its binding, in document order.
+ *
+ * A value-bearing kind carries the resolved value of its binding, looked up by the block id from the map
+ * that the resolution pass filled. A chart also carries the value of its track, of each tree, and of each statistic, looked
+ * up by the block id and the slot. The label of a statistic comes from the block, because the render value
+ * prints it. A no-value kind carries none. Where a reference sits in a block is the knowledge of
+ * `block-walk.ts`, thus this walk reads the slots that the walk names and never a binding field.
+ *
+ * The switch is exhaustive over the eight block kinds. A ninth kind reaches the end with no return, and
+ * the declared return type fails the build. Thus the walk cannot drop a kind in silence. A value-bearing
+ * block reaches here only when its reference resolved, because an unresolved reference short-circuits
+ * before this walk.
+ */
+export function collectResolutions(blocks, resolvedByBlock, resolvedBySlot) {
+    const resolutions = [];
+    const visit = (block) => {
+        switch (block.kind) {
+            case "section":
+                resolutions.push({ blockId: block.id, kind: "section" });
+                for (const child of block.blocks) {
+                    visit(child);
+                }
+                return;
+            case "text":
+            case "claim":
+            case "citation":
+                resolutions.push({ blockId: block.id, kind: block.kind });
+                return;
+            case "metric":
+            case "table":
+            case "figure": {
+                const resolved = resolvedByBlock.get(block.id);
+                if (resolved !== undefined) {
+                    resolutions.push({ blockId: block.id, kind: block.kind, resolved });
+                }
+                return;
+            }
+            case "chart": {
+                const resolved = resolvedByBlock.get(block.id);
+                if (resolved === undefined) {
+                    return;
+                }
+                const slots = resolvedBySlot.get(block.id);
+                const track = slots?.get("track");
+                const treeX = slots?.get(treeSlot("x"));
+                const treeY = slots?.get(treeSlot("y"));
+                const statistics = (block.statistics ?? []).flatMap((statistic, index) => {
+                    const value = slots?.get(statisticSlot(index));
+                    return value === undefined ? [] : [{ label: statistic.label, resolved: value }];
+                });
+                resolutions.push({
+                    blockId: block.id,
+                    kind: "chart",
+                    resolved,
+                    ...(track !== undefined ? { track } : {}),
+                    ...(treeX !== undefined || treeY !== undefined
+                        ? { trees: { ...(treeX !== undefined ? { x: treeX } : {}), ...(treeY !== undefined ? { y: treeY } : {}) } }
+                        : {}),
+                    ...(statistics.length > 0 ? { statistics } : {}),
+                });
+                return;
+            }
+        }
+    };
+    for (const block of blocks) {
+        visit(block);
+    }
+    return resolutions;
+}
+/**
+ * Map the resolutions of one chart onto its render value: the table of the binding, the rows of the track and
+ * of each tree, and the value of each statistic in block order. The binding, the track, and each tree resolve
+ * to a table, and each statistic resolves to a scalar. Each part of another type is one mismatch that names
+ * its slot.
+ */
+function chartValue(resolution) {
+    const mismatches = [];
+    const binding = resolution.resolved;
+    if (binding.type !== "table") {
+        mismatches.push(mismatch(resolution.blockId, "chart", "table", binding.type));
+    }
+    const track = resolution.track;
+    if (track !== undefined && track.type !== "table") {
+        mismatches.push(mismatch(resolution.blockId, "chart", "table", track.type, "track"));
+    }
+    const trees = {};
+    for (const axis of ["x", "y"]) {
+        const tree = resolution.trees?.[axis];
+        if (tree === undefined)
+            continue;
+        if (tree.type !== "table") {
+            mismatches.push(mismatch(resolution.blockId, "chart", "table", tree.type, treeSlot(axis)));
+            continue;
+        }
+        trees[axis] = secondTable(tree);
+    }
+    const statistics = [];
+    for (const [index, statistic] of (resolution.statistics ?? []).entries()) {
+        if (statistic.resolved.type !== "scalar") {
+            mismatches.push(mismatch(resolution.blockId, "chart", "scalar", statistic.resolved.type, statisticSlot(index)));
+            continue;
+        }
+        statistics.push({ label: statistic.label, value: statistic.resolved.value });
+    }
+    if (mismatches.length > 0 || binding.type !== "table") {
+        return err(mismatches);
+    }
+    return ok({
+        ...tableValue(binding),
+        ...(statistics.length > 0 ? { statistics } : {}),
+        ...(track !== undefined && track.type === "table" ? { track: secondTable(track) } : {}),
+        ...(trees.x !== undefined || trees.y !== undefined ? { trees } : {}),
+    });
+}
+/** The rows of a second table of a chart, a track or a tree, with its column order where the resolution gives one. */
+function secondTable(value) {
+    return value.columns !== undefined ? { rows: value.rows, columns: value.columns } : { rows: value.rows };
+}
 /**
  * Map a resolved table onto a render table. The explicit column order carries through when it is present,
  * and it stays absent otherwise, thus the renderer keeps its first-row order as the default.
@@ -80,7 +208,10 @@ function tableValue(value) {
     }
     return { type: "table", rows: value.rows, ...total };
 }
-/** Make one mismatch that names the block, its kind, the resolved type that it needs, and the type that arrived. */
-function mismatch(blockId, blockKind, expected, actual) {
-    return { blockId, blockKind, expected, actual };
+/**
+ * Make one mismatch that names the block, its kind, the resolved type that it needs, and the type that
+ * arrived. A mismatch of a chart track, tree, or statistic names its slot.
+ */
+function mismatch(blockId, blockKind, expected, actual, slot) {
+    return { blockId, blockKind, ...(slot !== undefined ? { slot } : {}), expected, actual };
 }

package/dist/report-render/views/chart-view.d.ts

@@ -7,19 +7,55 @@
  * The card is the square corner-accent form of the table and the figure, with the mono title line over it. A
  * report is a document, thus the card wears no application-window costume. The chart body carries a fixed
  * height, because the chart runtime measures the container and a container with no height shows no chart.
+ * A faceted chart grows its body one row of height for each row of panels, and a figure of many rows states
+ * its own height. A figure that draws a block of a fixed size, for example a square, narrows the body to the
+ * block and centers it. Each export entry states the height of its export, which grows with a taller body.
+ *
+ * The option of the page carries the toolbox of the chart, and the download control of the toolbox opens the
+ * download menu of the card. The runtime draws that control on the canvas and binds a mouse click alone, thus the
+ * title line also carries a download button that the keyboard reaches and that opens the same menu. The menu
+ * follows the option script, and it holds the two SVG entries and the three PNG entries. An SVG entry links a
+ * staged file, or it names the hybrid file that the page builds for a dense chart. The page draws each PNG on
+ * click.
  */
 import type { ChartBlock } from "../../contracts/report-blocks.js";
 import type { EchartOption } from "../chart.js";
 import type { ReferenceLedger } from "../references.js";
 import { type ViewOptions } from "./lineage.js";
+/**
+ * What the card carries beside the option: the staged names of the two SVG files, and the box of the chart
+ * body. A chart past the export bound carries no SVG name. The page then builds the hybrid SVG of a chart that
+ * holds a point layer, and the menu states that the PNG serves each other such chart.
+ * `bodyPx` is the height of the body, and `widthPx` is the width of a figure that draws a block of a fixed
+ * size.
+ */
+export interface ChartCard {
+    readonly svg?: {
+        readonly single: string;
+        readonly double: string;
+    };
+    readonly bodyPx: number;
+    readonly widthPx?: number;
+}
+/**
+ * The note of a chart past the export bound that holds no point layer. The page draws its PNG, and no SVG
+ * serves it.
+ */
+export declare const PNG_ONLY_NOTE = "The chart holds too many points for an SVG file. Use a PNG.";
+/** The note that the menu of a dense chart shows when the page cannot build its hybrid SVG file. */
+export declare const HYBRID_FAULT_NOTE = "The page could not build the SVG file. Use a PNG.";
+/** The text of the download control in the title line of the card. */
+export declare const DOWNLOAD_CONTROL_LABEL = "Download";
 /**
  * Render the card markup for a chart.
  *
- * The whole-table binding joins the reference ladder, thus the title line carries the marker and the
- * appendix names the artifact that the chart plots. A chart with no title still shows its marker on the
- * same line.
+ * Each reference of the chart joins the reference ladder: the whole-table binding, the track, the tree of `x`,
+ * the tree of `y`, and each statistic, in that order. Thus the title line carries one marker for each, and the
+ * appendix names the artifact that the chart plots, each second table that it draws, and each cell that it
+ * prints. A chart with
+ * no title still shows its markers on the same line.
  *
- * `view.lineage` states that the page carries a provenance document. The card then stamps its keys, and the
- * marker carries the control that opens the chain.
+ * `view.lineage` states that the page carries a provenance document. The card then stamps the keys of its
+ * references, and each marker carries the control that opens the chain of its own key.
  */
-export declare function renderChart(block: ChartBlock, ledger: ReferenceLedger, option: EchartOption, view?: ViewOptions): string;
+export declare function renderChart(block: ChartBlock, ledger: ReferenceLedger, option: EchartOption, view?: ViewOptions, card?: ChartCard): string;

package/dist/report-render/views/chart-view.js

@@ -8,30 +8,91 @@ import { jsx as _jsx, jsxs as _jsxs } from "hono/jsx/jsx-runtime";
  * The card is the square corner-accent form of the table and the figure, with the mono title line over it. A
  * report is a document, thus the card wears no application-window costume. The chart body carries a fixed
  * height, because the chart runtime measures the container and a container with no height shows no chart.
+ * A faceted chart grows its body one row of height for each row of panels, and a figure of many rows states
+ * its own height. A figure that draws a block of a fixed size, for example a square, narrows the body to the
+ * block and centers it. Each export entry states the height of its export, which grows with a taller body.
+ *
+ * The option of the page carries the toolbox of the chart, and the download control of the toolbox opens the
+ * download menu of the card. The runtime draws that control on the canvas and binds a mouse click alone, thus the
+ * title line also carries a download button that the keyboard reaches and that opens the same menu. The menu
+ * follows the option script, and it holds the two SVG entries and the three PNG entries. An SVG entry links a
+ * staged file, or it names the hybrid file that the page builds for a dense chart. The page draws each PNG on
+ * click.
  */
 import { raw } from "hono/html";
+import { kebabFilename } from "../../tools/display/normalize-echart-spec.js";
+import { stagedSource } from "../assets.js";
+import { chartMenuControlId, chartMenuId, MENU_CONTROL_ATTRIBUTE, MENU_FAULT_CLASS, pageChartOption } from "../chart-toolbox.js";
+import { CHART_BODY_PX, CHART_EXPORT_SIZES, exportSizeFor } from "../design.js";
+import { holdsPointLayer } from "../hybrid-svg.js";
 import { blockMark } from "./block-mark.js";
 import { DEFAULT_VIEW_OPTIONS, lineagePlace, lineageStamp } from "./lineage.js";
 import { Marker } from "./references-view.js";
 import { scriptJson } from "../script-json.js";
+/** The card of a chart with the default body and no SVG file. */
+const PLAIN_CARD = { bodyPx: CHART_BODY_PX };
+/**
+ * The note of a chart past the export bound that holds no point layer. The page draws its PNG, and no SVG
+ * serves it.
+ */
+export const PNG_ONLY_NOTE = "The chart holds too many points for an SVG file. Use a PNG.";
+/** The note that the menu of a dense chart shows when the page cannot build its hybrid SVG file. */
+export const HYBRID_FAULT_NOTE = "The page could not build the SVG file. Use a PNG.";
+/** The name of the download menu for a reader who hears the page instead of seeing it. */
+const MENU_LABEL = "Download the chart";
+/** The text of the download control in the title line of the card. */
+export const DOWNLOAD_CONTROL_LABEL = "Download";
+/** The two SVG entries of the menu, in the order that the menu shows them. */
+const SVG_EXPORTS = ["single", "double"];
+/** The three PNG entries, in the order that the menu shows them, with the suffix of each file name. */
+const PNG_EXPORTS = [
+    { kind: "single", suffix: `${CHART_EXPORT_SIZES.single.widthMm}mm` },
+    { kind: "double", suffix: `${CHART_EXPORT_SIZES.double.widthMm}mm` },
+    { kind: "slide", suffix: "slide" },
+];
 /**
  * Render the card markup for a chart.
  *
- * The whole-table binding joins the reference ladder, thus the title line carries the marker and the
- * appendix names the artifact that the chart plots. A chart with no title still shows its marker on the
- * same line.
+ * Each reference of the chart joins the reference ladder: the whole-table binding, the track, the tree of `x`,
+ * the tree of `y`, and each statistic, in that order. Thus the title line carries one marker for each, and the
+ * appendix names the artifact that the chart plots, each second table that it draws, and each cell that it
+ * prints. A chart with
+ * no title still shows its markers on the same line.
  *
- * `view.lineage` states that the page carries a provenance document. The card then stamps its keys, and the
- * marker carries the control that opens the chain.
+ * `view.lineage` states that the page carries a provenance document. The card then stamps the keys of its
+ * references, and each marker carries the control that opens the chain of its own key.
  */
-export function renderChart(block, ledger, option, view = DEFAULT_VIEW_OPTIONS) {
-    const n = ledger.mark(block.binding);
+export function renderChart(block, ledger, option, view = DEFAULT_VIEW_OPTIONS, card = PLAIN_CARD) {
+    const references = [
+        block.binding,
+        ...(block.track !== undefined ? [block.track.binding] : []),
+        ...(block.trees?.x !== undefined ? [block.trees.x.binding] : []),
+        ...(block.trees?.y !== undefined ? [block.trees.y.binding] : []),
+        ...(block.statistics ?? []).map((statistic) => statistic.value),
+    ];
+    const markers = references.map((reference, index) => _jsx(Marker, { n: ledger.mark(reference), lineage: lineagePlace(view.lineage, reference, index) }));
     const containerId = chartContainerId(block.id);
     // The JSON goes to the page through `raw()`, thus `scriptJson` is the sole guard of this sink. It
     // replaces every `<` with `\u003c`, thus a `</script` sequence in a string cell cannot close the
     // element early. The JSON parser reads `\u003c` as `<`, thus the option value stays exact.
-    const json = scriptJson(option);
-    return String(_jsxs("div", { class: "report-chart", ...blockMark(block.id), ...lineageStamp(view.lineage, block.id, [block.binding]), children: [_jsxs("div", { class: "report-chart-title", children: [block.title, _jsx(Marker, { n: n, lineage: lineagePlace(view.lineage, block.binding) })] }), _jsxs("div", { class: "report-chart-card corner-accents", children: [_jsx("div", { id: containerId, "data-echarts-id": block.id, class: "chart-container" }), _jsx("script", { type: "application/json", children: raw(json) })] }), block.caption !== undefined ? _jsx("p", { class: "report-caption", children: block.caption }) : null] }));
+    const json = scriptJson(pageChartOption(option, block.chartType));
+    const bodyStyle = [
+        ...(card.bodyPx !== CHART_BODY_PX ? [`height: ${card.bodyPx}px`] : []),
+        ...(card.widthPx !== undefined ? [`max-width: ${card.widthPx}px; margin-inline: auto`] : []),
+    ].join("; ");
+    const stem = kebabFilename(block.title ?? block.id);
+    const hybrid = card.svg === undefined && holdsPointLayer(option);
+    return String(_jsxs("div", { class: "report-chart", ...blockMark(block.id), ...lineageStamp(view.lineage, block.id, references), children: [_jsxs("div", { class: "report-chart-title", children: [block.title, markers, _jsx("button", { type: "button", id: chartMenuControlId(containerId), class: "report-chart-download", "aria-haspopup": "menu", "aria-expanded": "false", "aria-controls": chartMenuId(containerId), [MENU_CONTROL_ATTRIBUTE]: containerId, children: DOWNLOAD_CONTROL_LABEL })] }), _jsxs("div", { class: "report-chart-card corner-accents", children: [_jsx("div", { id: containerId, "data-echarts-id": block.id, class: "chart-container", ...(bodyStyle !== "" ? { style: bodyStyle } : {}) }), _jsx("script", { type: "application/json", children: raw(json) }), _jsxs("div", { id: chartMenuId(containerId), class: "report-chart-menu", role: "menu", "aria-label": MENU_LABEL, children: [SVG_EXPORTS.map((kind) => {
+                                const size = exportSizeFor(CHART_EXPORT_SIZES[kind], card.bodyPx);
+                                const file = `${stem}-${size.widthMm}mm.svg`;
+                                const label = `SVG · ${size.label}`;
+                                if (card.svg !== undefined) {
+                                    return (_jsx("a", { class: "report-chart-menu-item", role: "menuitem", tabindex: -1, href: stagedSource(card.svg[kind]), download: file, children: label }));
+                                }
+                                if (!hybrid)
+                                    return null;
+                                return (_jsx("button", { type: "button", class: "report-chart-menu-item", role: "menuitem", tabindex: -1, "data-hybrid": kind, "data-chart": containerId, "data-height": String(size.heightPx), "data-height-mm": String(size.heightMm), "data-file": file, children: label }));
+                            }), card.svg === undefined && !hybrid ? (_jsx("span", { class: "report-chart-menu-note", role: "menuitem", "aria-disabled": "true", children: PNG_ONLY_NOTE })) : null, hybrid ? (_jsx("span", { class: `report-chart-menu-note ${MENU_FAULT_CLASS}`, role: "menuitem", "aria-disabled": "true", tabindex: -1, children: HYBRID_FAULT_NOTE })) : null, _jsx("div", { class: "report-chart-menu-rule", role: "separator" }), PNG_EXPORTS.map((png) => (_jsxs("button", { type: "button", class: "report-chart-menu-item", role: "menuitem", tabindex: -1, "data-export": png.kind, "data-chart": containerId, "data-height": String(exportSizeFor(CHART_EXPORT_SIZES[png.kind], card.bodyPx).heightPx), "data-file": `${stem}-${png.suffix}.png`, children: ["PNG \u00B7 ", CHART_EXPORT_SIZES[png.kind].label] })))] })] }), block.caption !== undefined ? _jsx("p", { class: "report-caption", children: block.caption }) : null] }));
 }
 /** The container id derives from the block id, thus the id stays stable across renders. */
 function chartContainerId(blockId) {

package/dist/report-render/views/page-view.js

@@ -20,7 +20,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "hono/jsx/jsx-runtime";
 import { raw } from "hono/html";
 import { ASSET_HEAD, CHART_BOOTSTRAP, FADE_IN_OBSERVER, GRID_ASSET_HEAD, GRID_BOOTSTRAP, LINEAGE_ASSET_HEAD, LINEAGE_POPOVER, SECTION_SPY, TABLE_DATA_DECODER, } from "../page.js";
 import { stagedSource } from "../assets.js";
-import { DESIGN_CSS, ECHARTS_THEME, ECHARTS_THEME_NAME } from "../design.js";
+import { CHART_THEMES, chartTheme, DESIGN_CSS } from "../design.js";
 import { renderReferences } from "./references-view.js";
 import { scriptJson } from "../script-json.js";
 /** The constant eyebrow of the hero. The render reads no clock, thus the hero carries no date. */
@@ -30,20 +30,19 @@ const FOOTER_NOTE = "Powered by Inflexa";
 /** The title of the one appendix. It holds each artifact and each paper that the report names. */
 const REFERENCES_TITLE = "References";
 /**
- * The theme object as script-safe JSON. `scriptJson` replaces every `<` with `\u003c`, thus a later edit
- * that adds a `<` to the theme stays safe inside the script sink. The JSON parser reads `\u003c` as `<`, thus
- * the theme value stays exact.
- */
-const THEME_JSON = scriptJson(ECHARTS_THEME);
-/**
- * The registration script for the ECharts theme. It runs before the chart bootstrap, thus each chart
- * reads the registered theme by its name. The guard skips the call when the ECharts runtime did not load.
+ * The registration script for the ECharts themes: the page theme, and the two export themes that the PNG
+ * download reads. It runs before the chart bootstrap, thus each chart reads the registered theme by its
+ * name. The guard skips the calls when the ECharts runtime did not load.
+ *
+ * Each theme rides as script-safe JSON. `scriptJson` replaces every `<` with `\u003c`, thus a later edit that
+ * adds a `<` to the theme stays safe inside the script sink. The JSON parser reads `\u003c` as `<`, thus the
+ * theme value stays exact.
  */
 const THEME_REGISTRATION = `(function () {
   if (typeof echarts === "undefined") {
     return;
   }
-  echarts.registerTheme(${JSON.stringify(ECHARTS_THEME_NAME)}, ${THEME_JSON});
+${CHART_THEMES.map((theme) => `  echarts.registerTheme(${JSON.stringify(theme.name)}, ${scriptJson(chartTheme(theme.textPx))});`).join("\n")}
 })();`;
 /**
  * Wrap already-escaped markup in one full-bleed band. An even index gives the white background and the dot

package/dist/runtime/assemble.js

@@ -103,8 +103,8 @@ export function assembleCoreRuntime(deps) {
         runAuthorizer: wf.dataProfile.runAuthorizer,
         ...(wf.dataProfile.logger ? { logger: wf.dataProfile.logger } : {}),
     });
-    // A session derivation runs its container here and not in the turn. The await of an exec is a
-    // workflow-body call under the callback transport, thus the tool starts this workflow and awaits it.
+    // A session derivation runs its container here and not in the turn. An exec is a durable step of a
+    // workflow, thus the tool starts this workflow and awaits it.
     const deriveTableExec = registerDeriveTableExecWorkflow({
         sandboxClient: wf.dataProfile.sandboxClient,
         ...(wf.dataProfile.logger ? { logger: wf.dataProfile.logger } : {}),

package/dist/sandbox/client.d.ts

@@ -9,26 +9,18 @@
  * - `client.ts` (here) — the interface and the per-method types.
  * - `create-sandbox.ts` — the factory + per-backend `createSandbox` /
  *   `teardown` / `isAlive` implementations.
- * - `submit-exec.ts` + `await-exec.ts` — `submitExec` and the workflow-
- *   body recv loop, which are backend-agnostic (HTTP + DBOS messages).
+ * - `exec.ts` — the submit and the poll loop of one exec, which are
+ *   backend-agnostic (HTTP only).
  *
  * Lifetime separation (CONTEXT.md "Sandbox exec"):
  * - The **sandbox machine** lifetime is `createSandbox → ... → teardown`.
  *   Many execs may fire against the same machine.
- * - The **exec** lifetime is one `submitExec → awaitExec`.
- *
- * **Every caller of `awaitExec` runs inside a DBOS workflow body.** `DBOS.recv`
- * and `DBOS.writeStream` are body-only, thus the callback transport cannot
- * settle anywhere else, and the poll transport reaches for `DBOS.runStep` and
- * `DBOS.sleepms` defaults. A caller that starts from a live chat turn registers
- * its own workflow and starts it: `tasks/extract-values.ts` and
- * `tasks/derive-table-exec.ts` are the two worked examples. No type carries this
- * rule yet, thus a new caller must read this paragraph.
+ * - The **exec** lifetime is one `exec` call: one durable step.
  */
 import type { ResultAsync } from "neverthrow";
 import type { SpawnSession } from "../auth/types.js";
 import type { SandboxError } from "./sandbox-error.js";
-import type { ExecEmit, ExecResult, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SandboxSpec, SubmitExecBody, ToolchainSource } from "./types.js";
+import type { ExecEmit, ExecRequest, ExecResult, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SandboxSpec, ToolchainSource } from "./types.js";
 export interface SandboxClient {
     /**
      * The declared owner of the sandbox toolchain, as the client was composed
@@ -42,7 +34,7 @@ export interface SandboxClient {
     /**
      * DBOS step (`sandbox.create`) — the spawn half of the two-step create
      * (see the harness-sandbox-exec spec). Launches the sandbox-base container/Job under the
-     * pre-minted `identity` (name + HMAC secret checkpointed by `sandbox.mint`),
+     * pre-minted `identity` (the name checkpointed by `sandbox.mint`),
      * stamps the labels, waits for `/health`, records the live handle in
      * the active-sandbox registry, and returns the in-memory `SandboxRef`. A
      * recovery re-run whose machine already exists (the crash window between
@@ -55,30 +47,29 @@ export interface SandboxClient {
      */
     createSandbox(session: SpawnSession, spec: SandboxSpec, identity: SandboxIdentity): ResultAsync<SandboxRef, SandboxError>;
     /**
-     * DBOS step (`sandbox.submit-exec.${execId}`). POSTs the command to
-     * sandbox-server's `/exec` and returns after the HTTP 202 ack. Does NOT
-     * wait for command completion. Replay-safe: the cached step output is
-     * returned on subsequent invocations; any duplicate POST that reaches
-     * sandbox-server during the in-flight window is deduped server-side
-     * (PR #3 change 4) on `execId`.
-     */
-    submitExec(ref: SandboxRef, body: SubmitExecBody): Promise<void>;
-    /**
-     * Awaits a submitted exec's terminal result under the client's transport.
-     * Poll (default) loops durable, signed `GET /exec/{execId}?since={cursor}`
-     * steps against the sandbox in `ref`; callback loops
-     * `DBOS.recv("exec-event:${execId}", T)` with a signed pull as its
-     * recovery backstop. Both HMAC-verify every body against
-     * `ref.callbackSecret`, forward progress events via `emit`, and are
-     * bounded by `deadline` (absolute unix-ms timestamp).
+     * DBOS step (`sandbox.exec`). Submits the command to the sandbox in `ref`,
+     * polls `GET /exec/{execId}?since={cursor}` until the exec is
+     * terminal, forwards each progress event through `emit`, and returns the
+     * result. `deadline` is an absolute unix-ms timestamp.
+     *
+     * The exec id is the id of the workflow and the function id of the step
+     * that the exec runs in. Called from a workflow body, the exec is its own
+     * step. Called inside a step (a tool call of the agent loop), it runs
+     * inline in that step, thus ONE exec for each step: a second exec in the
+     * same step gets the same id, and the sandbox gives it the result of the
+     * first. Outside a workflow it throws.
+     *
+     * A recovered step submits again under the same id. The sandbox dedups the
+     * submit on the id, thus the poll attaches to the exec that already ran or
+     * runs, and `emit` sees its events again from the start.
      */
-    awaitExec(ref: SandboxRef, execId: string, emit: ExecEmit, deadline: number): Promise<ExecResult>;
+    exec(ref: SandboxRef, request: ExecRequest, emit: ExecEmit, deadline: number): Promise<ExecResult>;
     /**
      * Per-sandbox-machine liveness. `alive: false` only when observably dead
      * (terminal pod phase, missing container); `oomKilled` marks a death the
      * backend attributes to the machine's memory limit. Transient API errors
-     * throw, so callers can decide whether to retry — silently lying about
-     * dead sandboxes would race the synthetic-complete path.
+     * throw, so callers can decide whether to retry — a false `dead` verdict
+     * would fail an exec that still runs.
      */
     isAlive(ref: SandboxRef): Promise<SandboxLiveness>;
     /**

package/dist/sandbox/client.js

@@ -9,20 +9,12 @@
  * - `client.ts` (here) — the interface and the per-method types.
  * - `create-sandbox.ts` — the factory + per-backend `createSandbox` /
  *   `teardown` / `isAlive` implementations.
- * - `submit-exec.ts` + `await-exec.ts` — `submitExec` and the workflow-
- *   body recv loop, which are backend-agnostic (HTTP + DBOS messages).
+ * - `exec.ts` — the submit and the poll loop of one exec, which are
+ *   backend-agnostic (HTTP only).
  *
  * Lifetime separation (CONTEXT.md "Sandbox exec"):
  * - The **sandbox machine** lifetime is `createSandbox → ... → teardown`.
  *   Many execs may fire against the same machine.
- * - The **exec** lifetime is one `submitExec → awaitExec`.
- *
- * **Every caller of `awaitExec` runs inside a DBOS workflow body.** `DBOS.recv`
- * and `DBOS.writeStream` are body-only, thus the callback transport cannot
- * settle anywhere else, and the poll transport reaches for `DBOS.runStep` and
- * `DBOS.sleepms` defaults. A caller that starts from a live chat turn registers
- * its own workflow and starts it: `tasks/extract-values.ts` and
- * `tasks/derive-table-exec.ts` are the two worked examples. No type carries this
- * rule yet, thus a new caller must read this paragraph.
+ * - The **exec** lifetime is one `exec` call: one durable step.
  */
 export {};

package/dist/sandbox/create-sandbox.d.ts

@@ -8,8 +8,8 @@
  *
  * Registry write/clear callbacks are wired here so the per-backend
  * `createSandbox` / `teardown` implementations stay free of state-layer
- * coupling (they just call the closures we hand them). `submitExec` and
- * `awaitExec` are backend-agnostic — they only need the SandboxRef.
+ * coupling (they just call the closures we hand them). `exec` is
+ * backend-agnostic — it only needs the SandboxRef.
  */
 import type { V1Toleration } from "@kubernetes/client-node";
 import type { Pool } from "pg";
@@ -17,11 +17,10 @@ import type { Logger } from "../lib/logger.js";
 import { type ResourceLimits } from "../config/resource-limits.js";
 import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { clearSandboxRef } from "../state/index.js";
-import { type AwaitExecOptions } from "./await-exec.js";
 import type { SandboxClient } from "./client.js";
+import { type ExecDeps } from "./exec.js";
 import { type MountPlanCoords } from "./mount-plan.js";
-import { type SubmitExecDeps } from "./submit-exec.js";
-import { type FarmSource, type ResolveSandboxLabels, type SandboxTransport, type ToolchainSource } from "./types.js";
+import type { FarmSource, ResolveSandboxLabels, ToolchainSource } from "./types.js";
 /**
  * Narrow config slice the sandbox factory reads off `Env` — the backend
  * default and the K8s namespace fallback. Composition roots map their
@@ -36,14 +35,6 @@ export interface CreateSandboxClientConfig {
     pool: Pool;
     /** Backend default + namespace fallback source. */
     env: SandboxBackendConfig;
-    /** Cortex base URL injected into sandbox-server's env for callbacks. */
-    cortexBaseUrl: string;
-    /**
-     * Result transport for every sandbox this client creates. Threaded to the
-     * container as `SANDBOX_TRANSPORT` and to `awaitExec`'s loop selection.
-     * Defaults to `poll`.
-     */
-    transport?: SandboxTransport;
     /** Default sandbox-base image when the workflow doesn't override per-step. */
     image: string;
     /**
@@ -154,18 +145,12 @@ export interface CreateSandboxClientConfig {
      * unset.
      */
     logger?: Logger;
-    /** Dependency seams (fetch, durable step/sleep, clock, recv, warn sink) forwarded to submit/await. */
-    submitDeps?: SubmitExecDeps;
-    awaitOptions?: AwaitExecOptions;
+    /**
+     * The effects of each exec (fetch, clock, sleep, cancel read, warn sink).
+     * An `isAlive` here wins over the backend inspect that the client wires.
+     */
+    execDeps?: ExecDeps;
 }
-/**
- * Assemble `awaitExec`'s options: the liveness probe self-wires from the
- * backend ops (the poll loop's escalation always has its arbiter under the
- * client), explicit seam injections in `base` win over the self-wired probe,
- * and the transport is client-owned — never overridable through the seam bag.
- * Exported for tests.
- */
-export declare function composeAwaitOptions(base: AwaitExecOptions | undefined, transport: SandboxTransport, isAlive: NonNullable<AwaitExecOptions["isAlive"]>): AwaitExecOptions;
 /**
  * Backend-agnostic pre-creation of the writable tree under the analysis's
  * resolved workspace root. On Docker that root is the host dir the container