@inflexa-ai/harness 0.46.2 → 0.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.46.2",
+    "version": "0.48.0",
     "description": "Host-agnostic bioinformatics agent harness — an agent loop on the AI SDK, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",
@@ -11,6 +11,7 @@
             "types": "./dist/index.d.ts",
             "import": "./dist/index.js"
         },
+        "./tools/script/quickjs.wasm": "./dist/tools/script/quickjs.wasm",
         "./*.js": {
             "types": "./dist/*.d.ts",
             "import": "./dist/*.js"
@@ -58,6 +59,7 @@
         "@anthropic-ai/sdk": "^0.116.0",
         "@dbos-inc/dbos-sdk": "^5.3.0",
         "@dbos-inc/vercel-ai": "0.5.4",
+        "@earendil-works/pi-codemode": "1.4.0",
         "@fontsource-variable/space-grotesk": "5.1.1",
         "@fontsource/ibm-plex-mono": "5.1.1",
         "@inflexa-ai/tsprov": "0.6.0",
@@ -81,20 +83,23 @@
         "dockerode": "^4.0.12",
         "echarts": "6.1.0",
         "fast-xml-parser": "^5.10.1",
+        "fflate": "^0.8.3",
         "hono": "^4.12.34",
         "hyparquet": "^1.28.1",
         "js-tiktoken": "^1.0.21",
         "kysely": "^0.29.6",
         "linkedom": "^0.18.14",
+        "marked": "^18.1.2",
         "mime": "^4.1.0",
         "nanoid": "^5.1.16",
         "neverthrow": "^8.2.0",
         "openai": "^7.4.0",
         "p-queue": "^9.3.3",
-        "pdf-parse": "^2.4.5",
+        "pdfmake": "^0.3.13",
         "pg": "^8.22.0",
         "puppeteer-core": "^23.11.1",
         "turndown": "^7.2.4",
+        "unpdf": "^1.9.1",
         "zod": "^4.4.3"
     },
     "overrides": {
@@ -111,7 +116,6 @@
         "@types/bun": "latest",
         "@types/json-schema": "^7.0.15",
         "@types/node": "^24.13.3",
-        "@types/pdf-parse": "^1.1.5",
         "@typescript/native": "npm:typescript@7.0.2",
         "csstree-validator": "^4.0.1",
         "html-validate": "^11.6.2",

package/dist/prompts/literature-reviewer.d.ts

@@ -1 +0,0 @@
-export declare const literatureReviewerPrompt = "# Literature Reviewer\n\nYou are a systematic biology investigator. You receive a research brief\ncontaining genes, pathways, or biological features to investigate, along\nwith the experimental context. Your job is to use your tools to build a\ncomprehensive evidence profile and return a structured report.\n\nYou are task-oriented \u2014 you do not interact with the user. You receive\na brief, investigate, and return results.\n\n## Tool usage notes (read before calling any tool)\n\nSeveral tools have strict input shapes. Mis-shaping your call wastes a\nturn and forces a retry.\n\n- `pubmed({action:\"search\"})` \u2014 pass a focused query string. Shape: `{ action: \"search\", query: \"BRCA1 AND breast cancer\", maxResults: 10 }`.\n- `pubmed({action:\"details\"})` \u2014 takes `pmids`, a non-empty array of\n  PMID strings. Shape: `{ action: \"details\", pmids: [\"12345678\", \"87654321\"] }`.\n- `search_interactions` \u2014 accepts up to **100 identifiers per call**. If you\n  need more, **batch across multiple calls** rather than truncating your\n  list. Shape: `{ identifiers: [\"TP53\", \"BRCA1\", ...], limit: 50 }`.\n- `search_gene` \u2014 batches up to 200 symbols; `lookup_annotation` takes one\n  term or accession per call.\n- `search_protein` \u2014 one gene symbol or UniProt accession per call. It answers\n  with the protein: the accession, the recommended name, the sequence length,\n  the curated function, and the subcellular locations. An empty `proteins`\n  array is a valid \"no data\" outcome; do NOT retry the same call.\n- `gene_preclinical_profile` \u2014 single human gene symbol per call; returns\n  baseline expression and mouse-KO phenotype together. Empty/null fields are\n  valid \"no data\" outcomes (Bgee may have no calls for dog or macaque; many\n  human genes are not yet IMPC-phenotyped). Do NOT retry on empty output.\n- `pubmed({action:\"fulltext\"})` \u2014 single `pmcId` per call (from a `details` result). Use sparingly.\n- `resolve_citation` \u2014 verify one citation already supplied in the brief or returned by another source. Use it for identity/metadata verification, not topical discovery. Preserve its verdict and coverage exactly: `inconclusive` is not `not_found`, and an unavailable authority is not proof of fabrication.\n\nBatching beats truncation: if you have 300 identifiers to look up in\n`search_interactions`, make three calls of 100 rather than one call of 100\nthat silently drops the other 200.\n\n## What Each Tool Answers\n\nPick the lookups that the brief's question needs for each target:\n\n- **The gene** \u2014 `search_gene`: its Ensembl ID, coordinates, biotype, and\n  aliases.\n- **The protein** \u2014 `search_protein`, when the claim is about the protein\n  rather than the locus: what it does, how long it is, and where in the cell\n  it acts.\n- **Pathway context** \u2014 `lookup_annotation({vocabulary:\"pathways\"})`. Note\n  which pathways connect multiple genes from the brief.\n- **Function** \u2014 `lookup_annotation({vocabulary:\"go\"})`, when the gene's\n  role is unclear from the gene search alone.\n- **Interaction partners** \u2014 `search_interactions`, especially partners\n  that also appear in the brief.\n- **Literature evidence** \u2014 `pubmed({action:\"search\"})` with queries that\n  combine the gene with the disease or condition from the brief, then\n  `details` for the most relevant hits, and `fulltext` only for papers\n  that need deeper reading.\n- **Preclinical grounding** \u2014 `gene_preclinical_profile`, when the brief\n  asks about tissue expression, model-organism suitability, or KO\n  consequences.\n\n## Depth Guidelines\n\n- **Top priority targets** (top DE genes, hub genes, user-specified) get\n  the deepest evidence profile.\n- **Supporting targets** (enriched pathways, interaction partners) need\n  the gene, its pathway context, and its literature; add function and\n  interactions only when those results are ambiguous.\n- **Limit PubMed searches**: max 2-3 queries per gene. Combine terms\n  effectively (e.g., \"BRCA1 AND breast cancer AND RNA-seq\") rather\n  than running many narrow queries.\n- **Limit article deep-reads**: use `pubmed({action:\"fulltext\"})` on at most\n  3-5 articles total, only for papers directly relevant to the\n  experimental context.\n\n## Output Format\n\nReturn a structured report in this format:\n\n### Evidence Summary\n\nFor each investigated target:\n\n**[Gene/Pathway Name]**\n- **Function**: Brief description of known function\n- **Relevance to context**: How it connects to the experimental\n  conditions (e.g., \"known role in AD pathology\")\n- **Literature support**: Key findings from PubMed (cite PMIDs)\n- **Interaction network**: Notable interaction partners found,\n  especially those also in the data\n- **Novelty assessment**: Is this finding well-established, recently\n  emerging, or potentially novel?\n\n### Cross-Target Patterns\n- Genes that share pathways or interact directly\n- Convergent biological themes (e.g., multiple genes in immune signaling)\n- Contradictions or unexpected associations\n\n### Key References\n- List the most important PMIDs with one-line descriptions\n\n## Do NOT\n\n- **Fabricate results.** If a search returns no results, say so.\n- **Turn resolver uncertainty into certainty.** Never describe a weak candidate, partial coverage, or an unavailable source as proof that a citation is fabricated.\n- **Skip tool calls.** Do not claim knowledge about a gene without\n  looking it up. Your value is in systematic, verified investigation.\n- **Over-read articles.** Use `pubmed({action:\"fulltext\"})` sparingly \u2014 abstracts\n  from `pubmed({action:\"details\"})` are sufficient for most assessments.\n- **Investigate targets not in the brief.** Stay focused on what was\n  requested. Note interesting leads for follow-up but do not chase them.\n- **Produce conversational text.** You are returning a structured report,\n  not chatting with a user.\n";

package/dist/prompts/literature-reviewer.js

@@ -1,114 +0,0 @@
-export const literatureReviewerPrompt = `# Literature Reviewer
-
-You are a systematic biology investigator. You receive a research brief
-containing genes, pathways, or biological features to investigate, along
-with the experimental context. Your job is to use your tools to build a
-comprehensive evidence profile and return a structured report.
-
-You are task-oriented — you do not interact with the user. You receive
-a brief, investigate, and return results.
-
-## Tool usage notes (read before calling any tool)
-
-Several tools have strict input shapes. Mis-shaping your call wastes a
-turn and forces a retry.
-
-- \`pubmed({action:"search"})\` — pass a focused query string. Shape: \`{ action: "search", query: "BRCA1 AND breast cancer", maxResults: 10 }\`.
-- \`pubmed({action:"details"})\` — takes \`pmids\`, a non-empty array of
-  PMID strings. Shape: \`{ action: "details", pmids: ["12345678", "87654321"] }\`.
-- \`search_interactions\` — accepts up to **100 identifiers per call**. If you
-  need more, **batch across multiple calls** rather than truncating your
-  list. Shape: \`{ identifiers: ["TP53", "BRCA1", ...], limit: 50 }\`.
-- \`search_gene\` — batches up to 200 symbols; \`lookup_annotation\` takes one
-  term or accession per call.
-- \`search_protein\` — one gene symbol or UniProt accession per call. It answers
-  with the protein: the accession, the recommended name, the sequence length,
-  the curated function, and the subcellular locations. An empty \`proteins\`
-  array is a valid "no data" outcome; do NOT retry the same call.
-- \`gene_preclinical_profile\` — single human gene symbol per call; returns
-  baseline expression and mouse-KO phenotype together. Empty/null fields are
-  valid "no data" outcomes (Bgee may have no calls for dog or macaque; many
-  human genes are not yet IMPC-phenotyped). Do NOT retry on empty output.
-- \`pubmed({action:"fulltext"})\` — single \`pmcId\` per call (from a \`details\` result). Use sparingly.
-- \`resolve_citation\` — verify one citation already supplied in the brief or returned by another source. Use it for identity/metadata verification, not topical discovery. Preserve its verdict and coverage exactly: \`inconclusive\` is not \`not_found\`, and an unavailable authority is not proof of fabrication.
-
-Batching beats truncation: if you have 300 identifiers to look up in
-\`search_interactions\`, make three calls of 100 rather than one call of 100
-that silently drops the other 200.
-
-## What Each Tool Answers
-
-Pick the lookups that the brief's question needs for each target:
-
-- **The gene** — \`search_gene\`: its Ensembl ID, coordinates, biotype, and
-  aliases.
-- **The protein** — \`search_protein\`, when the claim is about the protein
-  rather than the locus: what it does, how long it is, and where in the cell
-  it acts.
-- **Pathway context** — \`lookup_annotation({vocabulary:"pathways"})\`. Note
-  which pathways connect multiple genes from the brief.
-- **Function** — \`lookup_annotation({vocabulary:"go"})\`, when the gene's
-  role is unclear from the gene search alone.
-- **Interaction partners** — \`search_interactions\`, especially partners
-  that also appear in the brief.
-- **Literature evidence** — \`pubmed({action:"search"})\` with queries that
-  combine the gene with the disease or condition from the brief, then
-  \`details\` for the most relevant hits, and \`fulltext\` only for papers
-  that need deeper reading.
-- **Preclinical grounding** — \`gene_preclinical_profile\`, when the brief
-  asks about tissue expression, model-organism suitability, or KO
-  consequences.
-
-## Depth Guidelines
-
-- **Top priority targets** (top DE genes, hub genes, user-specified) get
-  the deepest evidence profile.
-- **Supporting targets** (enriched pathways, interaction partners) need
-  the gene, its pathway context, and its literature; add function and
-  interactions only when those results are ambiguous.
-- **Limit PubMed searches**: max 2-3 queries per gene. Combine terms
-  effectively (e.g., "BRCA1 AND breast cancer AND RNA-seq") rather
-  than running many narrow queries.
-- **Limit article deep-reads**: use \`pubmed({action:"fulltext"})\` on at most
-  3-5 articles total, only for papers directly relevant to the
-  experimental context.
-
-## Output Format
-
-Return a structured report in this format:
-
-### Evidence Summary
-
-For each investigated target:
-
-**[Gene/Pathway Name]**
-- **Function**: Brief description of known function
-- **Relevance to context**: How it connects to the experimental
-  conditions (e.g., "known role in AD pathology")
-- **Literature support**: Key findings from PubMed (cite PMIDs)
-- **Interaction network**: Notable interaction partners found,
-  especially those also in the data
-- **Novelty assessment**: Is this finding well-established, recently
-  emerging, or potentially novel?
-
-### Cross-Target Patterns
-- Genes that share pathways or interact directly
-- Convergent biological themes (e.g., multiple genes in immune signaling)
-- Contradictions or unexpected associations
-
-### Key References
-- List the most important PMIDs with one-line descriptions
-
-## Do NOT
-
-- **Fabricate results.** If a search returns no results, say so.
-- **Turn resolver uncertainty into certainty.** Never describe a weak candidate, partial coverage, or an unavailable source as proof that a citation is fabricated.
-- **Skip tool calls.** Do not claim knowledge about a gene without
-  looking it up. Your value is in systematic, verified investigation.
-- **Over-read articles.** Use \`pubmed({action:"fulltext"})\` sparingly — abstracts
-  from \`pubmed({action:"details"})\` are sufficient for most assessments.
-- **Investigate targets not in the brief.** Stay focused on what was
-  requested. Note interesting leads for follow-up but do not chase them.
-- **Produce conversational text.** You are returning a structured report,
-  not chatting with a user.
-`;

package/dist/sandbox/reaper.d.ts

@@ -1,81 +0,0 @@
-/**
- * Sandbox reaper — the sole cleanup for orphaned sandboxes and stale registry
- * rows (see the harness-sandbox-exec spec, CONTEXT.md "Sandbox reaper").
- *
- * The reaper sweeps cluster→registry and garbage-collects. A machine that dies
- * under a running exec needs no sweep: the exec's own liveness probe ends it
- * (`exec.ts`). The reaper lists every Cortex-managed sandbox
- * machine in the configured namespace, resolves each machine's recorded owner
- * workflow, and reaps the ones whose owner is terminal — tearing the machine
- * down and reconciling its step row. A machine whose owner does not resolve at
- * all is torn down only once a liveness probe says it is dead.
- *
- * Why a sweep and not teardown-on-cancel: DBOS forbids running a step in a
- * cancelled workflow, so the body cannot tear down on the cancel path; and only
- * a cluster-side sweep catches permanent scale-down orphans (see the harness-durable-runtime spec), whose
- * workflows never recover to run any cleanup.
- *
- * The pure decision logic (`classifyManaged`) and the sweep (`reapOnce`) are
- * hoisted for unit testing without a DBOS runtime; `registerSandboxReaper` is
- * the thin production wiring.
- */
-import type { Logger } from "../lib/logger.js";
-import type { Querier } from "../state/db.js";
-import type { SandboxClient } from "./client.js";
-import type { ManagedSandbox } from "./types.js";
-export type ReapDecision = "leave" | "reap" | "reap-if-dead";
-/**
- * Decide whether a managed machine is reapable. A resolved owner status is
- * authoritative in both directions — DBOS records it at enqueue, *before* the
- * machine exists, so an in-flight workflow's machine is always observably
- * in-flight and a terminal one's is always reapable.
- *
- * A missing status is authoritative for neither. It means the machine records
- * no owner, or the id it records did not resolve, or DBOS pruned the row —
- * and age cannot separate those from a genuine orphan. So the decision defers
- * to a liveness probe: only an observably dead machine is torn down. Reaping a
- * live machine on age alone is what this branch exists to prevent.
- */
-export declare function classifyManaged(sb: ManagedSandbox, status: {
-    status: string;
-} | null, nowMs: number, graceMs: number): ReapDecision;
-/** Map the owning workflow's terminal status to the step row's terminal status. */
-export declare function terminalStepStatus(workflowStatus: string | null): "canceled" | "failed" | "completed";
-export type ReaperDeps = {
-    pool: Querier;
-    sandboxClient: Pick<SandboxClient, "listManagedSandboxes" | "teardownById" | "isAliveById">;
-    getStatus: (workflowId: string) => Promise<{
-        status: string;
-    } | null>;
-    /** Creation-time grace before an unattributable machine is even probed. */
-    graceMs?: number;
-    /** Wall-clock ms; injected for tests. */
-    nowMs?: () => number;
-    logger?: Logger;
-};
-export type ReapSummary = {
-    managedCount: number;
-    reapedCount: number;
-    rowsReconciled: number;
-    leftCount: number;
-    /**
-     * Machines past the grace whose owner did not resolve but which are still
-     * alive, so they were left standing. A non-zero value is a standing leak
-     * *and* a bug signal — it means owner ids are not round-tripping.
-     */
-    liveUnattributed: number;
-};
-/**
- * One cluster→registry sweep. Lists managed machines, classifies each against
- * its owner workflow's status, and reaps the terminal/orphaned ones. A reap
- * failure on one machine is logged and skipped — the next sweep retries.
- */
-export declare function reapOnce(deps: ReaperDeps): Promise<ReapSummary>;
-export type RegisterReaperDeps = {
-    pool: Querier;
-    sandboxClient: Pick<SandboxClient, "listManagedSandboxes" | "teardownById" | "isAliveById">;
-    graceMs?: number;
-    logger?: Logger;
-};
-/** Production registration: a single (unsharded) scheduled workflow. */
-export declare function registerSandboxReaper(deps: RegisterReaperDeps): void;

package/dist/sandbox/reaper.js

@@ -1,161 +0,0 @@
-/**
- * Sandbox reaper — the sole cleanup for orphaned sandboxes and stale registry
- * rows (see the harness-sandbox-exec spec, CONTEXT.md "Sandbox reaper").
- *
- * The reaper sweeps cluster→registry and garbage-collects. A machine that dies
- * under a running exec needs no sweep: the exec's own liveness probe ends it
- * (`exec.ts`). The reaper lists every Cortex-managed sandbox
- * machine in the configured namespace, resolves each machine's recorded owner
- * workflow, and reaps the ones whose owner is terminal — tearing the machine
- * down and reconciling its step row. A machine whose owner does not resolve at
- * all is torn down only once a liveness probe says it is dead.
- *
- * Why a sweep and not teardown-on-cancel: DBOS forbids running a step in a
- * cancelled workflow, so the body cannot tear down on the cancel path; and only
- * a cluster-side sweep catches permanent scale-down orphans (see the harness-durable-runtime spec), whose
- * workflows never recover to run any cleanup.
- *
- * The pure decision logic (`classifyManaged`) and the sweep (`reapOnce`) are
- * hoisted for unit testing without a DBOS runtime; `registerSandboxReaper` is
- * the thin production wiring.
- */
-import { DBOS } from "@dbos-inc/dbos-sdk";
-import { createNoopLogger } from "../lib/console-logger.js";
-import { untracedWorkflow } from "../lib/otel-spans.js";
-import { scheduleWorkflow } from "../runtime/dbos.js";
-import { unwrapOrThrow } from "../lib/result.js";
-import { reconcileReapedSandbox } from "../state/active-sandboxes.js";
-const REAPER_CRON = "0 */5 * * * *";
-const REAPER_WORKFLOW = "sandbox-reaper";
-const DEFAULT_GRACE_MS = 10 * 60_000;
-/**
- * Workflow statuses that mean "still owns its sandbox — never reap". Must
- * include every non-terminal DBOS state (`mapDbosToRunStatus` in
- * `routes/run-status.ts` is the canonical active set): `RUNNING` especially —
- * an actively-executing step's workflow is RUNNING, and omitting it would reap
- * a live sandbox out from under a running step.
- */
-const ACTIVE_WORKFLOW_STATUSES = new Set(["PENDING", "ENQUEUED", "RUNNING"]);
-/**
- * Decide whether a managed machine is reapable. A resolved owner status is
- * authoritative in both directions — DBOS records it at enqueue, *before* the
- * machine exists, so an in-flight workflow's machine is always observably
- * in-flight and a terminal one's is always reapable.
- *
- * A missing status is authoritative for neither. It means the machine records
- * no owner, or the id it records did not resolve, or DBOS pruned the row —
- * and age cannot separate those from a genuine orphan. So the decision defers
- * to a liveness probe: only an observably dead machine is torn down. Reaping a
- * live machine on age alone is what this branch exists to prevent.
- */
-export function classifyManaged(sb, status, nowMs, graceMs) {
-    if (status)
-        return ACTIVE_WORKFLOW_STATUSES.has(status.status) ? "leave" : "reap";
-    const ageMs = sb.createdAtMs == null ? Number.POSITIVE_INFINITY : nowMs - sb.createdAtMs;
-    return ageMs >= graceMs ? "reap-if-dead" : "leave";
-}
-/** Map the owning workflow's terminal status to the step row's terminal status. */
-export function terminalStepStatus(workflowStatus) {
-    switch (workflowStatus) {
-        case "CANCELLED":
-            return "canceled";
-        case "SUCCESS":
-            return "completed";
-        default:
-            // ERROR, MAX_RECOVERY_ATTEMPTS_EXCEEDED, or no workflow at all.
-            return "failed";
-    }
-}
-/**
- * One cluster→registry sweep. Lists managed machines, classifies each against
- * its owner workflow's status, and reaps the terminal/orphaned ones. A reap
- * failure on one machine is logged and skipped — the next sweep retries.
- */
-export async function reapOnce(deps) {
-    const logger = (deps.logger ?? createNoopLogger()).named("sandbox-reaper");
-    const nowMs = (deps.nowMs ?? (() => Date.now()))();
-    const graceMs = deps.graceMs ?? DEFAULT_GRACE_MS;
-    const managed = await deps.sandboxClient.listManagedSandboxes();
-    let reapedCount = 0;
-    let rowsReconciled = 0;
-    let leftCount = 0;
-    let liveUnattributed = 0;
-    for (const sb of managed) {
-        const status = sb.ownerWorkflowId ? await deps.getStatus(sb.ownerWorkflowId) : null;
-        const decision = classifyManaged(sb, status, nowMs, graceMs);
-        if (decision === "leave") {
-            leftCount++;
-            continue;
-        }
-        if (decision === "reap-if-dead") {
-            // A recorded id that resolves to nothing is an anomaly worth naming: either
-            // DBOS pruned the row or the id never reached the machine intact.
-            if (sb.ownerWorkflowId) {
-                logger.warn("owner workflow id resolved to no workflow", { sandboxId: sb.sandboxId, ownerWorkflowId: sb.ownerWorkflowId });
-            }
-            let liveness;
-            try {
-                liveness = await deps.sandboxClient.isAliveById(sb.sandboxId);
-            }
-            catch (err) {
-                // A probe that cannot answer is not a dead machine. Leave it; the next
-                // sweep re-probes.
-                logger.warn("liveness probe threw — leaving this machine", { sandboxId: sb.sandboxId, ...logger.errorFields(err) });
-                leftCount++;
-                continue;
-            }
-            if (liveness.alive) {
-                logger.warn("machine has no resolvable owner but is still alive — left standing", {
-                    sandboxId: sb.sandboxId,
-                    ownerWorkflowId: sb.ownerWorkflowId,
-                });
-                leftCount++;
-                liveUnattributed++;
-                continue;
-            }
-        }
-        try {
-            await deps.sandboxClient.teardownById(sb.sandboxId);
-            reapedCount++;
-            const reconciled = unwrapOrThrow(await reconcileReapedSandbox(deps.pool, sb.sandboxId, terminalStepStatus(status?.status ?? null)));
-            if (reconciled)
-                rowsReconciled++;
-        }
-        catch (err) {
-            logger.warn("reap failed — skipping this round", {
-                sandboxId: sb.sandboxId,
-                ...logger.errorFields(err),
-            });
-        }
-    }
-    const summary = {
-        managedCount: managed.length,
-        reapedCount,
-        rowsReconciled,
-        leftCount,
-        liveUnattributed,
-    };
-    // Spread: an interface has no implicit index signature, so it needs widening to `LogFields`.
-    logger.info("sweep completed", { ...summary });
-    return summary;
-}
-/** Production registration: a single (unsharded) scheduled workflow. */
-export function registerSandboxReaper(deps) {
-    const reaper = DBOS.registerWorkflow(async () => {
-        // The whole sweep is ONE step: `listManagedSandboxes` is live cluster
-        // state (set membership + order vary across runs) and it gates how many
-        // per-machine `getWorkflowStatus` reads happen. In the workflow body
-        // `getWorkflowStatus` is a function-ID-counting op, so a differing list
-        // on replay would diverge the recorded sequence. Inside a step the sweep
-        // is checkpointed wholesale and `getWorkflowStatus` is a plain read.
-        await DBOS.runStep(() => reapOnce({
-            pool: deps.pool,
-            sandboxClient: deps.sandboxClient,
-            getStatus: async (workflowId) => await DBOS.getWorkflowStatus(workflowId),
-            graceMs: deps.graceMs,
-            logger: deps.logger,
-        }), { name: "sandbox-reaper-sweep" });
-    }, { name: REAPER_WORKFLOW });
-    untracedWorkflow(REAPER_WORKFLOW);
-    scheduleWorkflow({ scheduleName: REAPER_WORKFLOW, workflowFn: reaper, schedule: REAPER_CRON });
-}

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

@@ -1,47 +0,0 @@
-/**
- * One ephemeral sandbox for one exec, inside the durable step of a tool call.
- *
- * The identity comes from the step: the exec id is the key of the step, plus a discriminator when one step
- * runs more than one exec, and the sandbox name comes from the exec id. Thus a rerun of the step adopts the
- * container of the earlier attempt (`createOrAdopt`), and sandbox-server gives the record of the same exec.
- * The container goes away when the work ends. Outside a workflow nothing reruns, thus the ids are random.
- */
-import { type Result } from "neverthrow";
-import type { AuthContext, Identity, SpawnSession } from "../auth/types.js";
-import type { Logger } from "../lib/logger.js";
-import type { SandboxClient } from "./client.js";
-import { type SuspendingRefusal } from "./sandbox-error.js";
-import type { ExecRequest, ExecResult, SandboxSpec } from "./types.js";
-/** The pass of the harness that a sandbox serves. Its run id and its step id name no run of the analysis. */
-export type SandboxPass = {
-    readonly analysisId: string;
-    readonly runId: string;
-    readonly stepId: string;
-    readonly agentId: string;
-};
-/**
- * The spawn session of a pass that runs under the auth of a tool call.
- *
- * The pass mints no mandate. The session never enters durable state: the sandbox client reads its scope and
- * its frame for the mounts and the labels, and the label hook of the host reads it in process.
- */
-export declare function passSpawnSession(caller: {
-    readonly identity: Identity;
-    readonly auth: AuthContext;
-}, pass: SandboxPass): SpawnSession;
-export type StepSandboxRequest = {
-    readonly session: SpawnSession;
-    readonly spec: Omit<SandboxSpec, "childWorkflowId">;
-    /** Tells two execs of one step apart. A step that runs one exec gives none. */
-    readonly execKey?: string;
-};
-/**
- * The one exec of a step sandbox, with its budget in milliseconds. A pass reports no live activity, thus the
- * events go nowhere.
- */
-export type StepSandboxExec = (request: ExecRequest, budgetMs: number) => Promise<ExecResult>;
-/**
- * Make the sandbox, give `work` its exec, and remove the sandbox when `work` ends. A suspending refusal of
- * the spawn is the `err`, and each other fault throws.
- */
-export declare function withStepSandbox<T>(client: SandboxClient, request: StepSandboxRequest, logger: Logger, work: (exec: StepSandboxExec) => Promise<T>): Promise<Result<T, SuspendingRefusal>>;

package/dist/sandbox/step-sandbox.js

@@ -1,53 +0,0 @@
-/**
- * One ephemeral sandbox for one exec, inside the durable step of a tool call.
- *
- * The identity comes from the step: the exec id is the key of the step, plus a discriminator when one step
- * runs more than one exec, and the sandbox name comes from the exec id. Thus a rerun of the step adopts the
- * container of the earlier attempt (`createOrAdopt`), and sandbox-server gives the record of the same exec.
- * The container goes away when the work ends. Outside a workflow nothing reruns, thus the ids are random.
- */
-import { DBOS } from "@dbos-inc/dbos-sdk";
-import { err, ok } from "neverthrow";
-import { randomUUID } from "node:crypto";
-import { durableStepKey } from "../tools/workspace/edit-file.js";
-import { keyedSandboxIdentity } from "./identity.js";
-import { keepSuspendingRefusal } from "./sandbox-error.js";
-/**
- * The spawn session of a pass that runs under the auth of a tool call.
- *
- * The pass mints no mandate. The session never enters durable state: the sandbox client reads its scope and
- * its frame for the mounts and the labels, and the label hook of the host reads it in process.
- */
-export function passSpawnSession(caller, pass) {
-    return {
-        identity: caller.identity,
-        scope: { kind: "analysis", analysisId: pass.analysisId },
-        provenance: { agentId: pass.agentId, callPath: [pass.agentId] },
-        runFrame: { runId: pass.runId, stepId: pass.stepId },
-        auth: caller.auth,
-    };
-}
-const noopEmit = () => { };
-/**
- * Make the sandbox, give `work` its exec, and remove the sandbox when `work` ends. A suspending refusal of
- * the spawn is the `err`, and each other fault throws.
- */
-export async function withStepSandbox(client, request, logger, work) {
-    const stepKey = durableStepKey();
-    const execId = stepKey === undefined ? `${request.session.runFrame.runId}:${randomUUID()}` : request.execKey === undefined ? stepKey : `${stepKey}:${request.execKey}`;
-    const spawned = keepSuspendingRefusal(await client.createSandbox(request.session, { ...request.spec, childWorkflowId: DBOS.workflowID ?? execId }, keyedSandboxIdentity(request.session.runFrame.runId, execId)));
-    if (spawned.isErr())
-        return err(spawned.error);
-    const sandbox = spawned.value;
-    try {
-        return ok(await work(async (execRequest, budgetMs) => client.exec(sandbox, execRequest, noopEmit, (await DBOS.now()) + budgetMs, execId)));
-    }
-    finally {
-        try {
-            await client.teardown(sandbox);
-        }
-        catch (cause) {
-            logger.warn("the sandbox of the pass did not tear down", { sandboxId: sandbox.sandboxId, ...logger.errorFields(cause) });
-        }
-    }
-}

package/dist/state/active-sandboxes.d.ts

@@ -1,33 +0,0 @@
-/**
- * Active-sandbox registry (CONTEXT.md) — the projection over
- * `cortex_step_executions` rows with a non-null `sandbox_ref` and a running
- * status. Owns the `sandbox_ref` column: written by
- * `sandbox/create-sandbox.ts` on mint, cleared on teardown, reconciled by
- * `sandbox/reaper.ts` after it deletes a machine.
- */
-import type { ResultAsync } from "neverthrow";
-import { type DbError } from "../lib/db-result.js";
-import type { Querier } from "./db.js";
-import type { PersistedSandboxRef } from "./schema.js";
-/**
- * Record the live sandbox handle on a step row. Called inside the
- * `createSandbox` DBOS step after the backend has confirmed the sandbox
- * is up.
- */
-export declare function setSandboxRef(pool: Querier, runId: string, stepId: string, sandboxRef: PersistedSandboxRef): ResultAsync<void, DbError>;
-/**
- * Clear the sandbox handle. Called inside the `teardown` DBOS step. Safe
- * to call when no sandbox was ever recorded — the UPDATE simply targets
- * zero rows.
- */
-export declare function clearSandboxRef(pool: Querier, runId: string, stepId: string): ResultAsync<void, DbError>;
-/**
- * Reconcile a step row after the reaper deletes its sandbox machine (ADR
- * 0016). Always clears `sandbox_ref` (drops the row from the
- * active-sandbox registry); a row still stuck at
- * `status='running'` — a cancellation that never ran its `mark-*` step — is
- * also flipped to the owning workflow's terminal status so a terminal workflow
- * never leaves a perpetually-"running" step behind. Returns true if a row
- * matched. Safe when no row exists (Class A pure orphan): matches zero rows.
- */
-export declare function reconcileReapedSandbox(pool: Querier, sandboxId: string, terminalStatus: "canceled" | "failed" | "completed"): ResultAsync<boolean, DbError>;

package/dist/state/active-sandboxes.js

@@ -1,65 +0,0 @@
-/**
- * Active-sandbox registry (CONTEXT.md) — the projection over
- * `cortex_step_executions` rows with a non-null `sandbox_ref` and a running
- * status. Owns the `sandbox_ref` column: written by
- * `sandbox/create-sandbox.ts` on mint, cleared on teardown, reconciled by
- * `sandbox/reaper.ts` after it deletes a machine.
- */
-import { tryMutation } from "../lib/db-result.js";
-/**
- * Record the live sandbox handle on a step row. Called inside the
- * `createSandbox` DBOS step after the backend has confirmed the sandbox
- * is up.
- */
-export function setSandboxRef(pool, runId, stepId, sandboxRef) {
-    return tryMutation("activeSandboxes.setSandboxRef", async () => {
-        await pool.query({
-            text: `UPDATE cortex_step_executions
-          SET sandbox_ref = $1::jsonb
-          WHERE run_id = $2 AND step_id = $3`,
-            values: [JSON.stringify(sandboxRef), runId, stepId],
-        });
-    });
-}
-/**
- * Clear the sandbox handle. Called inside the `teardown` DBOS step. Safe
- * to call when no sandbox was ever recorded — the UPDATE simply targets
- * zero rows.
- */
-export function clearSandboxRef(pool, runId, stepId) {
-    return tryMutation("activeSandboxes.clearSandboxRef", async () => {
-        await pool.query({
-            text: `UPDATE cortex_step_executions
-          SET sandbox_ref = NULL
-          WHERE run_id = $1 AND step_id = $2`,
-            values: [runId, stepId],
-        });
-    });
-}
-/**
- * Reconcile a step row after the reaper deletes its sandbox machine (ADR
- * 0016). Always clears `sandbox_ref` (drops the row from the
- * active-sandbox registry); a row still stuck at
- * `status='running'` — a cancellation that never ran its `mark-*` step — is
- * also flipped to the owning workflow's terminal status so a terminal workflow
- * never leaves a perpetually-"running" step behind. Returns true if a row
- * matched. Safe when no row exists (Class A pure orphan): matches zero rows.
- */
-export function reconcileReapedSandbox(pool, sandboxId, terminalStatus) {
-    // `completed_at` is a TEXT column holding ISO-8601 strings (see
-    // `step-executions.ts`), so bind one — `now()` is `timestamptz` and the CASE
-    // cannot unify a timestamptz branch with the text column ("CASE types text
-    // and timestamp with time zone cannot be matched"), which aborted every sweep.
-    const completedAt = new Date().toISOString();
-    return tryMutation("activeSandboxes.reconcileReapedSandbox", async () => {
-        const result = await pool.query({
-            text: `UPDATE cortex_step_executions
-          SET sandbox_ref = NULL,
-              status = CASE WHEN status = 'running' THEN $2 ELSE status END,
-              completed_at = CASE WHEN status = 'running' THEN $3 ELSE completed_at END
-          WHERE sandbox_ref->>'sandboxId' = $1`,
-            values: [sandboxId, terminalStatus, completedAt],
-        });
-        return (result.rowCount ?? 0) > 0;
-    });
-}