@inflexa-ai/harness 0.1.1

package/dist/workflows/metrics.js

@@ -0,0 +1,55 @@
+/**
+ * Workflow-side OTel metrics → Middleware.io.
+ *
+ * Two signals so 3-hour runs and pause-resume cascades are observable:
+ *   - cortex.workflow.parent.cancelled_children — counter, incremented once
+ *     per child the fail-fast or pause cascade reaps. A baseline near 0
+ *     means runs land cleanly; a spike means siblings keep colliding with
+ *     a single failing step.
+ *   - cortex.workflow.stream.bytes               — counter, incremented by
+ *     the byte count of every UI part written onto the DBOS stream. The
+ *     leading indicator for 3-hour stream growth is monotonic — a runaway
+ *     emitter shows up as an unbounded slope.
+ *
+ * Instruments are lazy so the workflow body binds to whichever
+ * `MeterProvider` is globally registered at startup.
+ */
+import { metrics } from "@opentelemetry/api";
+let instruments;
+function getInstruments() {
+    if (instruments === undefined) {
+        const meter = metrics.getMeter("cortex.workflow");
+        instruments = {
+            cancelledChildren: meter.createCounter("cortex.workflow.parent.cancelled_children", {
+                description: "Children cancelled by the parent's fail-fast or pause cascade",
+            }),
+            streamBytes: meter.createCounter("cortex.workflow.stream.bytes", {
+                description: "Bytes written to the parent's DBOS UI-parts stream — proxy for " + "3-hour stream growth",
+                unit: "By",
+            }),
+        };
+    }
+    return instruments;
+}
+/**
+ * Record one child cancellation. The parent calls this once per
+ * `DBOS.cancelWorkflow(childWorkflowId)` in the cascade (fail-fast OR
+ * pause). `cause` distinguishes the two so dashboards can split the
+ * counter.
+ */
+export function recordCancelledChild(args) {
+    getInstruments().cancelledChildren.add(1, { cause: args.cause });
+}
+/**
+ * Record one UI-part write. `bytes` is the serialised JSON size of the
+ * part as it lands on the stream; `kind` is the part `type` for
+ * dashboarding. The workflow body wraps its `DBOS.writeStream` call site
+ * so a single emitter records once per part.
+ */
+export function recordStreamWrite(args) {
+    getInstruments().streamBytes.add(args.bytes, { kind: args.kind });
+}
+/** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
+export function __resetWorkflowMetricsForTest() {
+    instruments = undefined;
+}

package/dist/workflows/plan/level.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Per-step topological level for UI layout.
+ *
+ * Re-export of `computeTopologicalLevels` from the scheduler module under the
+ * name `computeStepLevels` — the react-client `DagStepState.level` contract.
+ * Level 0 = no deps; level N = max(level(deps)) + 1. Layout-only — does NOT
+ * gate execution. Two steps at the same level may run / complete in any order.
+ *
+ * Pre-condition: `validatePlanDag` has been called. Behaviour is undefined on
+ * an invalid DAG; the cycle / missing-dep cases are surfaced by validation.
+ */
+export { computeTopologicalLevels as computeStepLevels, type PlanStep } from "../execute-analysis-scheduler.js";

package/dist/workflows/plan/level.js

@@ -0,0 +1,12 @@
+/**
+ * Per-step topological level for UI layout.
+ *
+ * Re-export of `computeTopologicalLevels` from the scheduler module under the
+ * name `computeStepLevels` — the react-client `DagStepState.level` contract.
+ * Level 0 = no deps; level N = max(level(deps)) + 1. Layout-only — does NOT
+ * gate execution. Two steps at the same level may run / complete in any order.
+ *
+ * Pre-condition: `validatePlanDag` has been called. Behaviour is undefined on
+ * an invalid DAG; the cycle / missing-dep cases are surfaced by validation.
+ */
+export { computeTopologicalLevels as computeStepLevels } from "../execute-analysis-scheduler.js";

package/dist/workflows/register-workflows.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Single registration call site for the analysis-side DBOS workflows.
+ *
+ * This module is the **one place** that calls `registerExecuteAnalysis` and
+ * `registerSandboxStep`, binding the parent + child workflow bodies to the
+ * running DBOS engine. Keeping both registrations in one file holds a single
+ * invariant: both workflows land under the same `applicationVersion` stamp
+ * that `launchDbos` writes onto the engine (`harness/runtime/dbos.ts`).
+ * Blue/green drains gate on `dbos.application_versions`, so registering the
+ * parent and child together under one stamp guarantees a drain treats them
+ * as one cohort.
+ *
+ * Deps are supplied by the composition root: `registerAnalysisWorkflows`
+ * takes a fully-formed deps bundle and passes each half straight through to
+ * the per-workflow register functions. This module constructs nothing —
+ * it only wires.
+ */
+import { type ExecuteAnalysisDeps, type ExecuteAnalysisInput, type ExecuteAnalysisResult } from "./execute-analysis.js";
+import { type SandboxStepDeps, type SandboxStepInput, type SandboxStepResult } from "./sandbox-step.js";
+export interface AnalysisWorkflowDeps {
+    readonly executeAnalysis: ExecuteAnalysisDeps;
+    readonly sandboxStep: SandboxStepDeps;
+}
+export interface RegisteredAnalysisWorkflows {
+    readonly executeAnalysis: (input: ExecuteAnalysisInput) => Promise<ExecuteAnalysisResult>;
+    readonly sandboxStep: (input: SandboxStepInput) => Promise<SandboxStepResult>;
+}
+/**
+ * Register the parent + child workflows with the running DBOS engine.
+ *
+ * Call this BEFORE `launchDbos`: `DBOS.launch()` runs recovery synchronously and
+ * resolves in-flight workflows by their registered name, so a workflow that is
+ * not registered at launch cannot be reclaimed. `runtime/assemble.ts` — the
+ * declared source of truth for wiring order — registers every workflow before
+ * launch for exactly this reason, and the embedded runtime does the same.
+ * Idempotency is owned by the SDK — calling twice with the same name is a
+ * `DBOS.registerWorkflow` invariant violation, not something this module
+ * guards against.
+ *
+ * Scope: this helper takes a fully-formed `AnalysisWorkflowDeps`, so it fits
+ * only a caller that already holds a registered sandbox-step callable —
+ * `ExecuteAnalysisDeps.sandboxStepCallable` (inside `deps.executeAnalysis`)
+ * exists only after `registerSandboxStep` has run. A caller that still needs
+ * that child callable must instead register the two workflows directly in
+ * assemble-order — register the child first, then feed its callable into the
+ * parent's deps — the way `runtime/assemble.ts` does; registering the child
+ * here as well would make its `registerSandboxStep` a second registration under
+ * the same name, which the SDK rejects. No in-tree caller holds a
+ * pre-registered child callable, so this helper is currently uncalled.
+ */
+export declare function registerAnalysisWorkflows(deps: AnalysisWorkflowDeps): RegisteredAnalysisWorkflows;

package/dist/workflows/register-workflows.js

@@ -0,0 +1,48 @@
+/**
+ * Single registration call site for the analysis-side DBOS workflows.
+ *
+ * This module is the **one place** that calls `registerExecuteAnalysis` and
+ * `registerSandboxStep`, binding the parent + child workflow bodies to the
+ * running DBOS engine. Keeping both registrations in one file holds a single
+ * invariant: both workflows land under the same `applicationVersion` stamp
+ * that `launchDbos` writes onto the engine (`harness/runtime/dbos.ts`).
+ * Blue/green drains gate on `dbos.application_versions`, so registering the
+ * parent and child together under one stamp guarantees a drain treats them
+ * as one cohort.
+ *
+ * Deps are supplied by the composition root: `registerAnalysisWorkflows`
+ * takes a fully-formed deps bundle and passes each half straight through to
+ * the per-workflow register functions. This module constructs nothing —
+ * it only wires.
+ */
+import { registerExecuteAnalysis } from "./execute-analysis.js";
+import { registerSandboxStep } from "./sandbox-step.js";
+/**
+ * Register the parent + child workflows with the running DBOS engine.
+ *
+ * Call this BEFORE `launchDbos`: `DBOS.launch()` runs recovery synchronously and
+ * resolves in-flight workflows by their registered name, so a workflow that is
+ * not registered at launch cannot be reclaimed. `runtime/assemble.ts` — the
+ * declared source of truth for wiring order — registers every workflow before
+ * launch for exactly this reason, and the embedded runtime does the same.
+ * Idempotency is owned by the SDK — calling twice with the same name is a
+ * `DBOS.registerWorkflow` invariant violation, not something this module
+ * guards against.
+ *
+ * Scope: this helper takes a fully-formed `AnalysisWorkflowDeps`, so it fits
+ * only a caller that already holds a registered sandbox-step callable —
+ * `ExecuteAnalysisDeps.sandboxStepCallable` (inside `deps.executeAnalysis`)
+ * exists only after `registerSandboxStep` has run. A caller that still needs
+ * that child callable must instead register the two workflows directly in
+ * assemble-order — register the child first, then feed its callable into the
+ * parent's deps — the way `runtime/assemble.ts` does; registering the child
+ * here as well would make its `registerSandboxStep` a second registration under
+ * the same name, which the SDK rejects. No in-tree caller holds a
+ * pre-registered child callable, so this helper is currently uncalled.
+ */
+export function registerAnalysisWorkflows(deps) {
+    return {
+        executeAnalysis: registerExecuteAnalysis(deps.executeAnalysis),
+        sandboxStep: registerSandboxStep(deps.sandboxStep),
+    };
+}

package/dist/workflows/resume-execute-analysis.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Resume helper for the `executeAnalysis` parent workflow.
+ *
+ * The actual resume *entry-point* (the HTTP route, the operator CLI hook,
+ * the analytics-tier replay) is owned by change 9 — that change exposes
+ * resume to the world. This module owns the **internal contract** every
+ * resume call site MUST satisfy so the parent body re-opens the running
+ * charge correctly after a 402 pause.
+ *
+ * Contract:
+ *
+ *   1. Call `prepareExecuteAnalysisResume(pool, parentWorkflowId)` BEFORE
+ *      `DBOS.resumeWorkflow(parentWorkflowId)`.
+ *   2. The helper finds the cortex_runs row by `workflow_id`, atomically
+ *      bumps `attempt_count`, and returns the new attempt + the runId.
+ *      Children that are still CANCELLED need an explicit
+ *      `DBOS.resumeWorkflow(childWorkflowId)` from the caller; completed
+ *      children's `getResult` returns from the DBOS cache.
+ *   3. On resume the parent body reads the bumped attempt_count and uses
+ *      it in `open-running-charge:${attempt}` / `close-running-charge:${attempt}`
+ *      / `revoke-run-auth:${attempt}` so each step name has never been
+ *      cached. A fresh managed-root charge is opened to replace the one that
+ *      closed with `budget_exceeded` on the pause.
+ *   4. The same attempt is passed through to children via
+ *      `SandboxStepInput.attempt`, where it drives
+ *      `attemptStepNameFormatter` and so the resumed LLM calls miss the
+ *      prior cached 402 and fire fresh (NOTES #3).
+ *   5. The workflow id and run id MUST NOT change across resume:
+ *      `cortex_runs.workflow_id` is rewritten by nothing in this code
+ *      path. The whole point of the bumped attempt counter is that the
+ *      same workflow id can survive multiple resumes without cache
+ *      collisions.
+ *
+ * Failure modes:
+ *
+ *   - The row does not exist → `MissingRunError`. Caller MUST surface a 404
+ *     to the originating operator; do NOT call `DBOS.resumeWorkflow` on a
+ *     missing run.
+ *   - The row's status is terminal (`completed`/`partial`/`failed`/`canceled`
+ *     without `suspended_insufficient_funds` on the analysis): the helper
+ *     still bumps the counter so a defensive retry is harmless, but the
+ *     caller SHOULD skip the resume — the workflow already ran to
+ *     completion. Change 9's entry point owns this guard.
+ */
+import type { Pool } from "pg";
+import type { CortexRunRow } from "../state/schema.js";
+export declare class MissingRunError extends Error {
+    readonly workflowId: string;
+    constructor(workflowId: string);
+}
+export interface PrepareResumeResult {
+    readonly runId: string;
+    readonly workflowId: string;
+    readonly attempt: number;
+    readonly previousStatus: CortexRunRow["status"];
+}
+/**
+ * Bump the parent-workflow resume attempt counter and return the new
+ * value. The caller invokes `DBOS.resumeWorkflow(workflowId)` immediately
+ * after; the resumed parent body reads the bumped counter and re-opens
+ * the running charge with a step name that has never been cached.
+ *
+ * `workflowId` and `runId` are the same bare UUID — `cortex_runs.run_id`
+ * IS the DBOS workflowID.
+ *
+ * Idempotency: each call bumps once. A double-call before
+ * `DBOS.resumeWorkflow` is harmless — both step names are misses and the
+ * close on the just-opened charge will still cleanly land.
+ */
+export declare function prepareExecuteAnalysisResume(pool: Pool, workflowId: string): Promise<PrepareResumeResult>;

package/dist/workflows/resume-execute-analysis.js

@@ -0,0 +1,80 @@
+/**
+ * Resume helper for the `executeAnalysis` parent workflow.
+ *
+ * The actual resume *entry-point* (the HTTP route, the operator CLI hook,
+ * the analytics-tier replay) is owned by change 9 — that change exposes
+ * resume to the world. This module owns the **internal contract** every
+ * resume call site MUST satisfy so the parent body re-opens the running
+ * charge correctly after a 402 pause.
+ *
+ * Contract:
+ *
+ *   1. Call `prepareExecuteAnalysisResume(pool, parentWorkflowId)` BEFORE
+ *      `DBOS.resumeWorkflow(parentWorkflowId)`.
+ *   2. The helper finds the cortex_runs row by `workflow_id`, atomically
+ *      bumps `attempt_count`, and returns the new attempt + the runId.
+ *      Children that are still CANCELLED need an explicit
+ *      `DBOS.resumeWorkflow(childWorkflowId)` from the caller; completed
+ *      children's `getResult` returns from the DBOS cache.
+ *   3. On resume the parent body reads the bumped attempt_count and uses
+ *      it in `open-running-charge:${attempt}` / `close-running-charge:${attempt}`
+ *      / `revoke-run-auth:${attempt}` so each step name has never been
+ *      cached. A fresh managed-root charge is opened to replace the one that
+ *      closed with `budget_exceeded` on the pause.
+ *   4. The same attempt is passed through to children via
+ *      `SandboxStepInput.attempt`, where it drives
+ *      `attemptStepNameFormatter` and so the resumed LLM calls miss the
+ *      prior cached 402 and fire fresh (NOTES #3).
+ *   5. The workflow id and run id MUST NOT change across resume:
+ *      `cortex_runs.workflow_id` is rewritten by nothing in this code
+ *      path. The whole point of the bumped attempt counter is that the
+ *      same workflow id can survive multiple resumes without cache
+ *      collisions.
+ *
+ * Failure modes:
+ *
+ *   - The row does not exist → `MissingRunError`. Caller MUST surface a 404
+ *     to the originating operator; do NOT call `DBOS.resumeWorkflow` on a
+ *     missing run.
+ *   - The row's status is terminal (`completed`/`partial`/`failed`/`canceled`
+ *     without `suspended_insufficient_funds` on the analysis): the helper
+ *     still bumps the counter so a defensive retry is harmless, but the
+ *     caller SHOULD skip the resume — the workflow already ran to
+ *     completion. Change 9's entry point owns this guard.
+ */
+import { unwrapOrThrow } from "../lib/result.js";
+import { bumpRunAttemptCount, queryRun } from "../state/index.js";
+export class MissingRunError extends Error {
+    workflowId;
+    constructor(workflowId) {
+        super(`No cortex_runs row found for run_id=${workflowId}`);
+        this.workflowId = workflowId;
+        this.name = "MissingRunError";
+    }
+}
+/**
+ * Bump the parent-workflow resume attempt counter and return the new
+ * value. The caller invokes `DBOS.resumeWorkflow(workflowId)` immediately
+ * after; the resumed parent body reads the bumped counter and re-opens
+ * the running charge with a step name that has never been cached.
+ *
+ * `workflowId` and `runId` are the same bare UUID — `cortex_runs.run_id`
+ * IS the DBOS workflowID.
+ *
+ * Idempotency: each call bumps once. A double-call before
+ * `DBOS.resumeWorkflow` is harmless — both step names are misses and the
+ * close on the just-opened charge will still cleanly land.
+ */
+export async function prepareExecuteAnalysisResume(pool, workflowId) {
+    const row = unwrapOrThrow(await queryRun(pool, workflowId));
+    if (!row) {
+        throw new MissingRunError(workflowId);
+    }
+    const attempt = unwrapOrThrow(await bumpRunAttemptCount(pool, row.runId));
+    return {
+        runId: row.runId,
+        workflowId,
+        attempt,
+        previousStatus: row.status,
+    };
+}

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

@@ -0,0 +1,243 @@
+/**
+ * `sandbox-step` — the per-step DBOS child workflow that drives one
+ * sandbox-agent execution and its post-step bookkeeping.
+ *
+ * Structure (each block runs as a `DBOS.runStep` so a crashed workflow
+ * replays from the cache instead of re-issuing work):
+ *
+ *  1. `mark-running`        — update `cortex_step_executions` to running.
+ *  2. `createSandbox`       — provision the sandbox; persist its handle.
+ *  3. `runAgent`            — the harness agent loop. Every LLM and tool
+ *                             call inside is its own durableStep.
+ *                             Catches `isBudgetExceeded` and self-cancels
+ *                             via `DBOS.cancelWorkflow(self)` to CANCELLED
+ *                             (resumable, not ERROR).
+ *  4. `generateFileMetadata`— post-step LLM call (chunked, slice-to-length).
+ *  5. `generateStepSummary` — post-step LLM call producing `output/summary.md`.
+ *  6. `reconcile + register`— write artifact manifest entries to cortex_artifacts.
+ *  7. `syncArtifacts`       — register provenance + upload missing file_ids
+ *                             via the managed root (scoped to this run+step).
+ *  8. `vector-index`        — index file descriptions + summary into pgvector.
+ *  9. `teardown`            — destroy the sandbox + clear sandbox_ref.
+ * 10. `mark-terminal`       — write the final status, emit `data-step-activity`
+ *                             onto the parent's DBOS stream.
+ *
+ * The parent owns sibling lifecycle: fail-fast and 402-cascade live on the
+ * parent (`executeAnalysis`). This child only owns its own teardown and
+ * its own self-cancel on 402.
+ */
+import type { Pool } from "pg";
+import type { AgentDefinition, LoopMessage } from "../loop/types.js";
+import type { AgentChat, EmbeddingProvider } from "../providers/types.js";
+import { type RunSession } from "../auth/types.js";
+import type { FileMetadataEntry } from "../execution/artifact-metadata.js";
+import type { ArtifactManifestEntry } from "../schemas/artifact-manifest.js";
+import type { StepSummary } from "../schemas/step-summary.js";
+import type { SandboxClient } from "../sandbox/client.js";
+import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
+import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
+import type { ArtifactRegistry } from "../execution/artifact-registry.js";
+import type { ResourceSpec } from "../config/resource-limits.js";
+import type { SandboxRef } from "../sandbox/types.js";
+import { ProvenanceCollector } from "../provenance/collector.js";
+import { type BlockerHolder } from "../tools/sandbox/report-blocker.js";
+/**
+ * Input the parent hands the child. Must be JSON-serialisable — DBOS
+ * persists this as the workflow's input row.
+ */
+export interface SandboxStepInput {
+    readonly analysisId: string;
+    readonly runId: string;
+    readonly stepId: string;
+    readonly agentId: string;
+    /** Topological level — persisted on `cortex_step_executions.wave`. */
+    readonly level: number;
+    /** User-content prompt the agent receives as its initial message. */
+    readonly prompt: string;
+    /**
+     * DBOS workflow id of the parent (`executeAnalysis`). The child uses
+     * this to address the parent for the budget-exceeded side-channel
+     * (`DBOS.send(parent, …, "child-budget-exceeded")`) — the parent's
+     * scheduler-loop classifier relies on it to disambiguate a budget-induced
+     * self-cancel from an operator-driven sibling cancel (CANCELLED is the
+     * same terminal state for both).
+     */
+    readonly parentWorkflowId: string;
+    /** Sandbox image override; falls back to the child's configured default. */
+    readonly image?: string;
+    /** Per-step env overrides forwarded to sandbox-server. */
+    readonly extraEnv?: Record<string, string>;
+    /** Planner-estimated CPU/memory/GPU request for this step's sandbox. */
+    readonly resources: ResourceSpec;
+    /**
+     * Per-step execution budget in seconds. The body translates this into the
+     * absolute unix-ms deadline that `awaitExec` honours as its durable
+     * backstop. Comes from the plan's `step.timeout` (defaulted on the parent
+     * side); falls back to `DEFAULT_STEP_TIMEOUT_SECONDS` when unset so a
+     * client that omits the field still gets a non-pathological ceiling.
+     */
+    readonly timeoutSeconds?: number;
+    /**
+     * Durable `RunSession` derived by the parent via `forStep`. Carries the
+     * run-authorization credential, identity, scope, and `runFrame = { runId, stepId }`.
+     * DBOS replay reconstructs it on resume — the body never reads the JWT
+     * from `cortex_runs`.
+     */
+    readonly runSession: RunSession;
+}
+/**
+ * Fallback when the plan step omits `timeout`. Plans that need 3-hour runs
+ * declare it explicitly.
+ */
+export declare const DEFAULT_STEP_TIMEOUT_SECONDS = 3600;
+export type SandboxStepStatus = "complete" | "failed" | "canceled" | "blocked";
+/**
+ * DBOS message topic the child uses to notify the parent that it is
+ * about to self-cancel because of a 402 budget-exceeded error. The
+ * notification fires BEFORE `DBOS.cancelWorkflow(self)` so the parent's
+ * concurrent recv accumulator records the child id before the child's
+ * terminal state lands. Without it the parent observes
+ * `DBOSWorkflowCancelledError` from `getResult` — a generic message that
+ * `isBudgetExceeded` does NOT match — and misclassifies the failure as
+ * fail-fast, skipping the 402 pause cascade.
+ */
+export declare const BUDGET_EXCEEDED_TOPIC = "child-budget-exceeded";
+export interface BudgetExceededNotification {
+    readonly childWorkflowId: string;
+    readonly stepId: string;
+    readonly error: string;
+}
+export interface SandboxStepResult {
+    readonly status: SandboxStepStatus;
+    readonly durationMs: number;
+    readonly finishReason: string | null;
+    readonly error: string | null;
+}
+/** One file in the step's terminal file tree / output listing. */
+export interface StepFileEntry {
+    readonly path: string;
+    readonly size: number;
+    /** Schema-conformant `StepOutputFile.fileType`. */
+    readonly fileType: "script" | "output" | "figure" | "log" | "notebook" | "summary";
+    readonly description: string;
+}
+/**
+ * Post-step detail the body emits to the run stream once the bookkeeping
+ * helpers have run. Derived from the metadata entries, the generated step
+ * summary, and the reconciled artifact manifest. `collectStepOutputs`
+ * assembles it from the same stash the vector-index step consumes.
+ */
+export interface StepOutputs {
+    /** Reconciled artifact files with category + description + size. */
+    readonly files: readonly StepFileEntry[];
+    /** Generated step summary markdown (empty when none produced). */
+    readonly summaryMarkdown: string;
+}
+/**
+ * The typed post-step products threaded through the workflow body: file
+ * descriptions, the interpretive summary, and the reconciled (phantom-dropped)
+ * artifact manifest. Each value is produced by one post-step dep and consumed
+ * by `collectStepOutputs` and the vector indexer — the body is the explicit
+ * composition, so the producer→consumer ordering is a type constraint rather
+ * than an implicit contract over shared mutable state.
+ */
+export interface PostStepArtifacts {
+    readonly metadataEntries: readonly FileMetadataEntry[];
+    readonly summary: StepSummary | undefined;
+    readonly reconciledManifest: readonly ArtifactManifestEntry[];
+}
+/**
+ * Per-step coordinates the workflow body computes once and threads to the
+ * deps factory. The parent supplies the durable inputs; the factory
+ * supplies the live sandbox ref, the per-call function-id minter, and the
+ * deadline.
+ */
+export interface SandboxAgentBuildContext {
+    readonly input: SandboxStepInput;
+    readonly session: RunSession;
+    readonly sandbox: SandboxRef;
+    /** Workflow-id used to scope sandbox callbacks + workspace mutate provenance. */
+    readonly workflowId: string;
+    readonly stepWritePrefix: string;
+    readonly nextFunctionId: () => string;
+    readonly deadlineMs: () => number;
+    /**
+     * Step-scoped lineage collector. The body owns one per step and threads
+     * it both here (so `execute_command` feeds each exec's provenance frame)
+     * and into `PostStepContext` (so registration reads the resulting
+     * input/script edges). Same instance on both paths.
+     */
+    readonly lineageCollector: ProvenanceCollector;
+    /**
+     * Per-run blocker cell (see the harness-sandbox-agents spec). The body owns it and reads
+     * `holder.outcome` after `runAgent`; the agent factory adds `report_blocker`
+     * bound to this holder.
+     */
+    readonly blockerHolder: BlockerHolder;
+}
+/**
+ * Inversion of control: the parent supplies the live agent, the parent's
+ * stream emitter, and the post-step helpers. Keeping the workflow body
+ * free of per-agent imports means it can drive every agent in the catalog
+ * without becoming a switch on agentId.
+ */
+export interface SandboxStepDeps {
+    readonly pool: Pool;
+    /** Non-streaming chat — drives the agent loop + the post-step sub-agents. */
+    readonly provider: AgentChat;
+    /** Write-side embedder for the post-step vector index. */
+    readonly embedding: EmbeddingProvider;
+    readonly sandboxClient: SandboxClient;
+    /**
+     * External artifact registration + sync seam. The harness's post-step pipeline
+     * registers each step's outputs through it (filesystem index in the
+     * cloud-free build, external provenance ledger in the managed build).
+     */
+    readonly artifactRegistry: ArtifactRegistry;
+    /** Workspace read seam — backs `read_file` in the metadata + summary loops. */
+    readonly workspaceFs: WorkspaceFilesystem;
+    /** Workspace-root resolution seam (see workspace/paths.ts). */
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    /** Sandbox model id — provenance label for metadata + summary generation. */
+    readonly model: string;
+    /**
+     * Build the agent definition for this step. The parent resolves the
+     * agent from the catalog, wires its workspace tools, and returns the
+     * configured `AgentDefinition` runAgent will drive.
+     */
+    buildAgent(ctx: SandboxAgentBuildContext): AgentDefinition;
+    /**
+     * Resolve the absolute writable artifact prefix for this step. The
+     * workspace mutate tools enforce write confinement against this path.
+     */
+    resolveWritePrefix(input: SandboxStepInput): string;
+}
+/**
+ * Per-step context passed to every post-step dep. Carries the durable input
+ * (analysisId/runId/stepId/agentId), the durable `RunSession`, the in-memory
+ * agent transcript, and the on-disk write prefix. The write prefix is the
+ * absolute path each post-step dep walks to discover artifacts;
+ * `lineageCollector` carries the runtime-observed input/script edges the
+ * step loop accumulated, which registration translates into managed-root parents.
+ */
+export interface PostStepContext {
+    readonly input: SandboxStepInput;
+    readonly session: RunSession;
+    readonly transcript: readonly LoopMessage[];
+    /** Absolute path to the step's writable artifact directory. */
+    readonly writePrefix: string;
+    /** Sandbox handle id — informational only, used in log lines. */
+    readonly sandboxId: string;
+    /** Same step-scoped collector the agent loop fed each exec frame into. */
+    readonly lineageCollector: ProvenanceCollector;
+}
+/**
+ * Register the sandbox-step child workflow with DBOS. Returns the
+ * registered callable so callers can dispatch via `DBOS.startWorkflow`.
+ *
+ * Workflow version stamping is handled globally via `DBOS.setConfig({
+ * applicationVersion })` in `launchDbos` — DBOS records the running
+ * version on every workflow row automatically, so blue/green drains read
+ * `dbos.application_versions` without per-workflow config.
+ */
+export declare function registerSandboxStep(deps: SandboxStepDeps): (input: SandboxStepInput) => Promise<SandboxStepResult>;