@inflexa-ai/harness 0.46.2 → 0.47.0

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;
-    });
-}

package/dist/tasks/extract-values-script.d.ts

@@ -1,64 +0,0 @@
-/**
- * The fixed extraction script and its wire protocol.
- *
- * The extraction arm runs this one Python script in the sandbox. The script reads one JSON input: a list
- * of path, format, and hash triples. For each triple the script hashes the file bytes with a streamed
- * sha256 before any read. If the on-disk hash does not match the pinned hash, the script refuses the file
- * as a typed error. If the hash matches, the script reads the file from the read-only analysis mount, and
- * it parses the file by the carried format. A parquet file uses pyarrow. The script emits one JSON map:
- * each path to its rows, or to a typed error. The script decides nothing else. It applies no filter and no
- * projection.
- *
- * The host decides the format one time, and the request carries it. Thus the script derives no reader from
- * an extension, and it refuses a request that names no format. The JSON arm obeys the strict host shape, an
- * array of flat objects, thus a shape that the host refuses is a refusal here too and it never comes back
- * as a table that pandas inferred.
- *
- * The harness holds the script as a string constant, thus the package ships no separate asset file. The
- * script reaches the container as the argument of `python3 -c`. The input reaches the container as one
- * environment variable.
- */
-import { z } from "zod";
-/**
- * The environment variable that carries the script input. The workflow body sets it to the JSON list of
- * path, format, and hash triples. The script reads it back one time.
- */
-export declare const EXTRACTION_INPUT_ENV = "CORTEX_EXTRACTION_REQUESTS";
-/**
- * One artifact row, as plain cells. A text-backed format holds a numeric column as a string, thus a cell
- * is a string or a number.
- */
-declare const ExtractionRowSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
-export type ExtractionRow = z.infer<typeof ExtractionRowSchema>;
-/**
- * The outcome for one path. A clean read gives the rows. A per-file read fault gives a typed error, and
- * the script still emits the map. The arm keeps the rows and drops the error, thus a failed path reads as
- * an unread artifact downstream.
- */
-declare const ExtractOutcomeSchema: z.ZodUnion<readonly [z.ZodObject<{
-    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
-}, z.core.$strip>, z.ZodObject<{
-    error: z.ZodObject<{
-        type: z.ZodString;
-        message: z.ZodString;
-    }, z.core.$strip>;
-}, z.core.$strip>]>;
-export type ExtractOutcome = z.infer<typeof ExtractOutcomeSchema>;
-/** The script output: each requested path to its outcome. */
-export declare const ExtractValuesResultSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
-    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
-}, z.core.$strip>, z.ZodObject<{
-    error: z.ZodObject<{
-        type: z.ZodString;
-        message: z.ZodString;
-    }, z.core.$strip>;
-}, z.core.$strip>]>>;
-export type ExtractValuesResult = z.infer<typeof ExtractValuesResultSchema>;
-/**
- * The one extraction script. The workflow body runs it as the argument of `python3 -c`. The script reads
- * the request list from `CORTEX_EXTRACTION_REQUESTS`, and it emits the value map to stdout.
- *
- * The Python comments obey the same Simplified Technical English rule as the harness comments.
- */
-export declare const EXTRACTION_SCRIPT = "import hashlib\nimport json\nimport math\nimport os\nimport sys\n\nimport pandas as pd\n\n\ndef sha256_of(path):\n    # The host pins the exact bytes with a streamed sha256, in the \"sha256:<hex>\" form. Mirror that form\n    # here, and stream the file in blocks, thus a large file never loads fully into memory.\n    digest = hashlib.sha256()\n    with open(path, \"rb\") as handle:\n        for block in iter(lambda: handle.read(1024 * 1024), b\"\"):\n            digest.update(block)\n    return \"sha256:\" + digest.hexdigest()\n\n\ndef coerce_cell(value):\n    # A null cell becomes None, thus the record drops the key.\n    if value is None:\n        return None\n    # A numpy scalar becomes a plain Python scalar.\n    if hasattr(value, \"item\"):\n        try:\n            value = value.item()\n        except (ValueError, TypeError):\n            return str(value)\n    if isinstance(value, bool):\n        return \"true\" if value else \"false\"\n    if isinstance(value, float):\n        if math.isnan(value) or math.isinf(value):\n            return None\n        return value\n    if isinstance(value, int):\n        return value\n    if isinstance(value, str):\n        return value\n    return str(value)\n\n\ndef read_frame(path, fmt):\n    # pyarrow reads the parquet columnar format.\n    if fmt == \"parquet\":\n        return pd.read_parquet(path, engine=\"pyarrow\")\n    if fmt == \"tsv\":\n        # keep_default_na=False keeps a literal cell such as \"NA\" or an empty string as its text, and the\n        # host parser keeps it too. A default read turns each into NaN, and the row builder drops the key.\n        return pd.read_csv(path, sep=\"\\t\", dtype=str, keep_default_na=False)\n    if fmt == \"csv\":\n        # keep_default_na=False keeps a literal cell such as \"NA\" or an empty string as its text, thus a\n        # text cell survives and the row keeps the key.\n        return pd.read_csv(path, dtype=str, keep_default_na=False)\n    # The host decides the format for both arms. A request with no decided format is a protocol fault, thus\n    # the file refuses here and no reader guesses at it.\n    raise ValueError(\"the request names no supported format: \" + str(fmt))\n\n\ndef json_rows(path):\n    # The host reads a JSON table as an array of flat objects, and it refuses any other shape. Obey the\n    # same shape here. An inference pass would turn a shape that the host refuses into a different table.\n    with open(path, \"rb\") as handle:\n        value = json.load(handle)\n    if not isinstance(value, list):\n        raise ValueError(\"the JSON top-level value is not an array\")\n    rows = []\n    for item in value:\n        if not isinstance(item, dict):\n            raise ValueError(\"a JSON array item is not an object\")\n        row = {}\n        for key, cell in item.items():\n            if isinstance(cell, (dict, list)):\n                raise ValueError(\"a JSON cell holds a nested value\")\n            coerced = coerce_cell(cell)\n            if coerced is not None:\n                row[str(key)] = coerced\n        rows.append(row)\n    return rows\n\n\ndef rows_of(frame):\n    # A null cell becomes None before the record build, thus a missing cell drops.\n    clean = frame.astype(object).where(pd.notnull(frame), None)\n    records = clean.to_dict(orient=\"records\")\n    rows = []\n    for record in records:\n        row = {}\n        for key, value in record.items():\n            cell = coerce_cell(value)\n            if cell is not None:\n                row[str(key)] = cell\n        rows.append(row)\n    return rows\n\n\ndef rows_for(path, fmt):\n    # The JSON arm reads the strict host shape itself. Each other format reads through pandas.\n    if fmt == \"json\":\n        return json_rows(path)\n    return rows_of(read_frame(path, fmt))\n\n\ndef main():\n    raw = os.environ.get(\"CORTEX_EXTRACTION_REQUESTS\", \"[]\")\n    requests = json.loads(raw)\n    out = {}\n    for request in requests:\n        path = request[\"path\"]\n        fmt = request.get(\"format\")\n        expected = request[\"hash\"]\n        try:\n            # Hash the file before any read. A file that drifted from the pin never reaches the reader, thus\n            # the extraction never gives back drifted bytes for the gate to match against.\n            actual = sha256_of(path)\n            if actual != expected:\n                out[path] = {\n                    \"error\": {\n                        \"type\": \"hash-mismatch\",\n                        \"message\": f\"the pinned hash {expected} does not match the on-disk hash {actual}\",\n                    }\n                }\n                continue\n            out[path] = {\"rows\": rows_for(path, fmt)}\n        except Exception as exc:\n            # A per-file read fault lands as a typed error, and the map still holds each other path.\n            out[path] = {\"error\": {\"type\": \"read-fault\", \"message\": str(exc)}}\n    json.dump(out, sys.stdout)\n\n\nmain()\n";
-export {};