@inflexa-ai/harness 0.1.1

package/dist/execution/artifact-metadata.js

@@ -0,0 +1,203 @@
+/**
+ * Per-step artifact metadata generation — describes a step's output files
+ * via a focused `runAgent` tool-call loop on the harness `ChatProvider`.
+ *
+ * Design (mirrors `generate-plan.ts`): the describer agent communicates
+ * exclusively through one tool, `submit_file_metadata`, whose `execute`
+ * validates every entry's `path` against the known artifact set. Unknown
+ * paths (hallucinated files) are rejected with feedback; uncovered files are
+ * reported as `remaining` so the model resubmits. Descriptions are matched
+ * to files BY PATH — there is no positional array-index alignment, so a
+ * dropped, reordered, or extra entry can never attach a description to the
+ * wrong file.
+ *
+ * Lossless contract: every input artifact appears in the result exactly
+ * once. A file the model never describes (loop budget exhausted, persistent
+ * tool errors, model refusal) gets a deterministic fallback description
+ * synthesised from its path + inferred type + size. Fallbacks are logged —
+ * never silently dropped, never silently chunked out.
+ *
+ * `Session` is taken explicitly (see the harness-durable-runtime spec) — billing is a compile-time
+ * obligation on every provider call.
+ */
+import { ok } from "neverthrow";
+import { forSubAgent } from "../auth/types.js";
+import { runAgent } from "../loop/run-agent.js";
+import { passthroughStep } from "../loop/run-step.js";
+import { defineTool } from "../tools/define-tool.js";
+import { createReadFileTool } from "../tools/workspace/read-file.js";
+import { inferArtifactType } from "../schemas/artifact-manifest.js";
+import { SubmitFileMetadataInputSchema } from "../schemas/file-metadata.js";
+/** Sub-agent identity for the describer loop — provenance only. */
+const DESCRIBER_AGENT_ID = "file-metadata-describer";
+/**
+ * Iteration budget: one full submission + a few correction rounds. The
+ * fallback backstop means an exhausted budget degrades gracefully rather
+ * than dropping files, so the cap stays small.
+ */
+const DEFAULT_MAX_ITERATIONS = 8;
+const SYSTEM_PROMPT = `You are a deterministic metadata describer for bioinformatics output files.
+
+You describe files by calling the submit_file_metadata tool. For each file provide:
+  - path        — copy the file's path EXACTLY from the list you are given.
+  - description — one sentence describing what the file contains.
+  - dataType    — semantic type (e.g. "count matrix", "QC report").
+  - format      — file format (e.g. "csv", "tsv", "h5ad", "png").
+  - rows, cols  — optional integers when known.
+  - tags, warnings — optional string arrays.
+
+Rules:
+  - Only describe files from the provided list. Never invent a path.
+  - Cover every file. You may submit in one call or several.
+  - The tool returns {accepted, unknownPaths, remaining}. If accepted is true,
+    every file is covered — STOP, do not call the tool again. Otherwise remove
+    any unknownPaths (they are not real files) and describe the remaining files.
+  - Prefer grounding descriptions in fact. Use the read_file tool to inspect a
+    file's actual contents (e.g. a CSV header or a report's body) when the path
+    alone is not enough to describe it accurately.
+  - Do not guess file contents you cannot infer; a terse, honest description is
+    better than a confident wrong one.`;
+function buildPrompt(artifacts) {
+    const list = artifacts.map((a) => `- ${a.displayPath}`).join("\n");
+    return `Describe the following output files by calling submit_file_metadata. Copy each \`path\` EXACTLY from this list. Read a file with read_file when its path alone is not enough to describe it accurately:\n\n${list}`;
+}
+/**
+ * Drop a trailing partial assistant `tool_use` round from a loop transcript:
+ * it has no matching `tool_result`, so prefixing it onto a fresh loop turn
+ * would be an invalid message sequence.
+ */
+function sanitizeTranscript(messages) {
+    const out = [...messages];
+    while (out.length > 0) {
+        const last = out[out.length - 1];
+        const blocks = Array.isArray(last.content) ? last.content : [];
+        const hasOpenToolUse = last.role === "assistant" && blocks.some((b) => b.type === "tool-call");
+        if (hasOpenToolUse) {
+            out.pop();
+            continue;
+        }
+        break;
+    }
+    return out;
+}
+/**
+ * The single describer tool. Accumulates accepted descriptions into
+ * `holder` keyed by path; rejects paths outside `knownPaths`. Returns the
+ * coverage state the model uses to decide whether to continue.
+ */
+function buildSubmitTool(holder, knownPaths) {
+    return defineTool({
+        id: "submit_file_metadata",
+        description: "Submit metadata for output files. Each entry's `path` MUST exactly " +
+            "match one of the listed files. Returns {accepted, unknownPaths, " +
+            "remaining}: accepted=true means every file now has metadata — STOP. " +
+            "Otherwise drop the unknownPaths and describe the remaining files.",
+        inputSchema: SubmitFileMetadataInputSchema,
+        execute: async (input) => {
+            const unknownPaths = [];
+            for (const entry of input.files) {
+                if (!knownPaths.has(entry.path)) {
+                    unknownPaths.push(entry.path);
+                    continue;
+                }
+                holder.set(entry.path, entry);
+            }
+            const remaining = [...knownPaths].filter((p) => !holder.has(p));
+            return ok({
+                accepted: unknownPaths.length === 0 && remaining.length === 0,
+                unknownPaths,
+                remaining,
+            });
+        },
+    });
+}
+function buildEntry(artifact, desc, extra) {
+    const metadata = {
+        ...extra,
+        dataType: desc.dataType,
+        format: desc.format,
+    };
+    if (desc.rows != null)
+        metadata.rows = desc.rows;
+    if (desc.cols != null)
+        metadata.cols = desc.cols;
+    if (desc.tags)
+        metadata.tags = desc.tags;
+    if (desc.warnings)
+        metadata.warnings = desc.warnings;
+    return { dbPath: artifact.dbPath, description: desc.description, metadata };
+}
+function fileExtension(displayPath) {
+    const base = displayPath.slice(displayPath.lastIndexOf("/") + 1);
+    const dot = base.lastIndexOf(".");
+    return dot > 0 ? base.slice(dot + 1).toLowerCase() : "unknown";
+}
+/**
+ * Deterministic fallback for a file the model never described. No LLM call —
+ * composed from facts already on disk so search still finds the file.
+ */
+function fallbackEntry(artifact, extra) {
+    // Leading slash so `inferArtifactType` matches the `/figures/` etc. segment
+    // on a working-directory-relative display path.
+    const fileType = inferArtifactType(`/${artifact.displayPath}`);
+    const format = fileExtension(artifact.displayPath);
+    const sizePart = artifact.sizeBytes != null ? `, ${artifact.sizeBytes} bytes` : "";
+    const description = `${artifact.displayPath} — ${fileType} file (${format}${sizePart}); automated description unavailable.`;
+    return {
+        dbPath: artifact.dbPath,
+        description,
+        metadata: { ...extra, dataType: fileType, format },
+    };
+}
+/**
+ * Describe a step's known artifacts via a tool-call loop. Non-fatal: a loop
+ * failure or partial coverage degrades to deterministic fallbacks, so the
+ * result always carries exactly one entry per input artifact.
+ */
+export async function generateFileMetadata(opts) {
+    if (opts.artifacts.length === 0) {
+        return { indexed: 0, entries: [] };
+    }
+    const knownPaths = new Set(opts.artifacts.map((a) => a.displayPath));
+    const holder = new Map();
+    const tools = [buildSubmitTool(holder, knownPaths)];
+    if (opts.workspaceFs) {
+        tools.push(createReadFileTool(opts.workspaceFs, opts.workingDir));
+    }
+    const describer = {
+        id: DESCRIBER_AGENT_ID,
+        systemPrompt: SYSTEM_PROMPT,
+        model: opts.modelId,
+        tools,
+        maxIterations: opts.maxIterations ?? DEFAULT_MAX_ITERATIONS,
+    };
+    const signal = opts.signal ?? new AbortController().signal;
+    const transcript = opts.messages ? sanitizeTranscript(opts.messages) : [];
+    try {
+        await runAgent(describer, [...transcript, { role: "user", content: buildPrompt(opts.artifacts) }], forSubAgent(opts.session, DESCRIBER_AGENT_ID), {
+            provider: opts.provider,
+            signal,
+            emit: () => { },
+            runStep: passthroughStep,
+        });
+    }
+    catch (err) {
+        console.warn(`[artifact-metadata] describer loop failed (resource=${opts.resourceId}); using fallbacks: ${err instanceof Error ? err.message : err}`);
+    }
+    const entries = [];
+    const fallbackPaths = [];
+    for (const artifact of opts.artifacts) {
+        const desc = holder.get(artifact.displayPath);
+        if (desc) {
+            entries.push(buildEntry(artifact, desc, opts.extraMetadata));
+        }
+        else {
+            entries.push(fallbackEntry(artifact, opts.extraMetadata));
+            fallbackPaths.push(artifact.displayPath);
+        }
+    }
+    if (fallbackPaths.length > 0) {
+        console.warn(`[artifact-metadata] ${fallbackPaths.length}/${opts.artifacts.length} file(s) used a deterministic fallback description (resource=${opts.resourceId}): ${fallbackPaths.join(", ")}`);
+    }
+    return { indexed: holder.size, entries };
+}

package/dist/execution/artifact-record.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Artifact record — the shape post-step deps and the provenance collector
+ * read for each file the step produced (hash + size + tool provenance +
+ * write timestamp). Pure data type; lives in its own file because it is
+ * shared across `execution/` and `provenance/`.
+ */
+export interface ArtifactRecord {
+    path: string;
+    hash: string;
+    size: number;
+    /**
+     * The filesystem operation that created this artifact (`write_file`,
+     * `edit_file`). Undefined for files discovered by disk scan —
+     * their provenance comes from the collector.
+     */
+    toolName?: string;
+    /** ISO 8601 timestamp captured at write time. */
+    timestamp: string;
+}

package/dist/execution/artifact-record.js

@@ -0,0 +1,7 @@
+/**
+ * Artifact record — the shape post-step deps and the provenance collector
+ * read for each file the step produced (hash + size + tool provenance +
+ * write timestamp). Pure data type; lives in its own file because it is
+ * shared across `execution/` and `provenance/`.
+ */
+export {};

package/dist/execution/artifact-registration.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Artifact registration — registers a step's artifacts in the local ledger
+ * (cortex_artifacts) and with an injected provenance-agnostic
+ * `ArtifactRegistry`.
+ *
+ * The harness owns the local ledger: it builds the `cortex_artifacts` rows, upserts
+ * them, then calls `registry.register(...)` for external provenance and writes
+ * the returned external ids back onto the ledger rows. Which registry is wired
+ * (an external provenance ledger, or a filesystem index) is a composition-root
+ * decision — this module never names one.
+ */
+import type { Pool, PoolClient } from "pg";
+import type { AgentSession } from "../auth/types.js";
+import type { ArtifactRegistry, ArtifactRegistrationInput } from "./artifact-registry.js";
+export type { ArtifactRegistrationInput };
+export interface ArtifactRegistrationResult {
+    /** Number of artifacts written to the local ledger. */
+    localCount: number;
+    /** Number of artifacts registered externally and given external IDs. */
+    externalRegistered: number;
+    /** Number of external registration failures. */
+    externalFailed: number;
+    /** Per-artifact failure details from the registry (if any). */
+    failureDetails: Array<{
+        path: string;
+        error: string;
+    }>;
+}
+/**
+ * Register step-level artifacts (paths under `runs/{runId}/{stepId}/`).
+ *
+ * Builds the `cortex_artifacts` rows from the manifest, upserts them, then
+ * delegates external provenance registration to the injected `ArtifactRegistry`
+ * and applies any returned external ids back onto the local rows.
+ */
+export declare function registerStepArtifacts(db: Pool | PoolClient, registry: ArtifactRegistry, input: ArtifactRegistrationInput, session: AgentSession): Promise<ArtifactRegistrationResult>;

package/dist/execution/artifact-registration.js

@@ -0,0 +1,61 @@
+/**
+ * Artifact registration — registers a step's artifacts in the local ledger
+ * (cortex_artifacts) and with an injected provenance-agnostic
+ * `ArtifactRegistry`.
+ *
+ * The harness owns the local ledger: it builds the `cortex_artifacts` rows, upserts
+ * them, then calls `registry.register(...)` for external provenance and writes
+ * the returned external ids back onto the ledger rows. Which registry is wired
+ * (an external provenance ledger, or a filesystem index) is a composition-root
+ * decision — this module never names one.
+ */
+import { upsertArtifacts, updateArtifactId } from "../state/index.js";
+// ── Registration ─────────────────────────────────────────────────────
+/**
+ * Register step-level artifacts (paths under `runs/{runId}/{stepId}/`).
+ *
+ * Builds the `cortex_artifacts` rows from the manifest, upserts them, then
+ * delegates external provenance registration to the injected `ArtifactRegistry`
+ * and applies any returned external ids back onto the local rows.
+ */
+export async function registerStepArtifacts(db, registry, input, session) {
+    const { resourceId, runId, stepId, artifacts } = input;
+    if (artifacts.length === 0) {
+        return { localCount: 0, externalRegistered: 0, externalFailed: 0, failureDetails: [] };
+    }
+    const dbPathPrefix = `runs/${runId}/${stepId}/`;
+    const emptyHash = "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+    const localEntries = artifacts.map((a) => {
+        if (a.size === 0 || a.hash === emptyHash) {
+            console.warn(`[artifact-registration] empty artifact: path=${dbPathPrefix}${a.path} hash=${a.hash?.slice(0, 16)} size=${a.size} runId=${runId} stepId=${stepId}`);
+        }
+        return {
+            resourceId,
+            path: `${dbPathPrefix}${a.path}`,
+            hash: a.hash ?? "",
+            size: a.size,
+            role: "step_output",
+            sourceStep: stepId,
+            sourceRun: runId,
+            fileType: a.type,
+        };
+    });
+    await upsertArtifacts(db, localEntries);
+    const localPaths = new Set(localEntries.map((e) => e.path));
+    const result = await registry.register(input, session);
+    let externalRegistered = 0;
+    for (const reg of result.registered) {
+        // Skip files the registry also returned that we didn't upsert locally
+        // (e.g., data inputs that were already born-synced).
+        if (!localPaths.has(reg.path))
+            continue;
+        await updateArtifactId(db, resourceId, reg.path, reg.externalId);
+        externalRegistered++;
+    }
+    return {
+        localCount: localEntries.length,
+        externalRegistered,
+        externalFailed: result.failedCount,
+        failureDetails: result.failed,
+    };
+}

package/dist/execution/artifact-registry.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `ArtifactRegistry` — provenance-agnostic seam for external artifact
+ * registration.
+ *
+ * The harness's `registerStepArtifacts` owns the local ledger (cortex_artifacts) and
+ * delegates external provenance registration to an injected `ArtifactRegistry`.
+ * The seam input is the high-level step input; the result is a flat per-path
+ * outcome. The seam deliberately mentions no host-managed vocabulary — a
+ * trivial no-op adapter satisfies it just as well as a managed adapter.
+ *
+ * Adapters:
+ *   - a managed provenance adapter (harness/compose/) — builds the structured
+ *     payload and calls the host provenance ledger.
+ *   - `createNoopArtifactRegistry` (the harness, this dir) — registers nothing
+ *     externally; the local `cortex_artifacts` ledger is the only record.
+ */
+import type { ArtifactManifestEntry } from "../schemas/artifact-manifest.js";
+import type { ProvenanceCollector } from "../provenance/collector.js";
+import type { AgentSession } from "../auth/types.js";
+/** High-level input for registering one step's artifacts. */
+export interface ArtifactRegistrationInput {
+    /** Analysis resource ID. */
+    resourceId: string;
+    /** Workflow run ID. */
+    runId: string;
+    /** Step ID that produced the artifacts. */
+    stepId: string;
+    /** Artifact manifest from the sandbox runner. */
+    artifacts: ArtifactManifestEntry[];
+    /** Provenance collector with tracked inputs/outputs. */
+    collector: ProvenanceCollector;
+}
+/** Step coordinates for a per-step artifact sync. */
+export interface ArtifactSyncInput {
+    /** Analysis resource ID. */
+    resourceId: string;
+    /** Workflow run ID. */
+    runId: string;
+    /** Step ID whose registered artifacts are synced. */
+    stepId: string;
+}
+/**
+ * Outcome of external registration. Flat per-path results — no provenance-model
+ * vocabulary leaks across the seam.
+ */
+export interface ExternalRegistrationResult {
+    /**
+     * Artifacts the external registry accepted, with the external identity to
+     * write back onto the local ledger row. `path` is the analysis-scoped path
+     * (`runs/{runId}/{stepId}/...`) matching the local ledger row.
+     */
+    registered: Array<{
+        path: string;
+        externalId: string;
+    }>;
+    /** Per-path rejections (persistent — transient errors are retried inside the adapter). */
+    failed: Array<{
+        path: string;
+        error: string;
+    }>;
+    /**
+     * Number of rows the external registry rejected. Usually `failed.length`, but
+     * an adapter may report a higher count when a single transport error rolls
+     * back a whole batch (`failed` then carries one summary entry).
+     */
+    failedCount: number;
+}
+export interface ArtifactRegistry {
+    /**
+     * Register one step's artifacts with the external provenance system.
+     * Implementations MUST NOT touch the local `cortex_artifacts` ledger — that
+     * is the harness's responsibility, applied around this call. The `session` carries
+     * the run credential an adapter needs to address the external system.
+     */
+    register(input: ArtifactRegistrationInput, session: AgentSession): Promise<ExternalRegistrationResult>;
+    /**
+     * Push a step's registered artifacts to permanent storage. A no-op when the
+     * adapter's bytes already live locally; the managed adapter uploads them.
+     * Throws on a persistent failure so the caller's fail-fast boundary fires.
+     */
+    sync(input: ArtifactSyncInput, session: AgentSession): Promise<void>;
+}

package/dist/execution/artifact-registry.js

@@ -0,0 +1,17 @@
+/**
+ * `ArtifactRegistry` — provenance-agnostic seam for external artifact
+ * registration.
+ *
+ * The harness's `registerStepArtifacts` owns the local ledger (cortex_artifacts) and
+ * delegates external provenance registration to an injected `ArtifactRegistry`.
+ * The seam input is the high-level step input; the result is a flat per-path
+ * outcome. The seam deliberately mentions no host-managed vocabulary — a
+ * trivial no-op adapter satisfies it just as well as a managed adapter.
+ *
+ * Adapters:
+ *   - a managed provenance adapter (harness/compose/) — builds the structured
+ *     payload and calls the host provenance ledger.
+ *   - `createNoopArtifactRegistry` (the harness, this dir) — registers nothing
+ *     externally; the local `cortex_artifacts` ledger is the only record.
+ */
+export {};

package/dist/execution/dbos-run-launcher.d.ts

@@ -0,0 +1,7 @@
+/**
+ * DBOS realization of the `RunLauncher` seam — the single production adapter,
+ * shared by every embedder. Host-neutral: it references only DBOS, which the harness
+ * already depends on, so it ships in the harness.
+ */
+import type { RunLauncher } from "./run-launcher.js";
+export declare function createDbosRunLauncher(): RunLauncher;

package/dist/execution/dbos-run-launcher.js

@@ -0,0 +1,38 @@
+/**
+ * DBOS realization of the `RunLauncher` seam — the single production adapter,
+ * shared by every embedder. Host-neutral: it references only DBOS, which the harness
+ * already depends on, so it ships in the harness.
+ */
+import { DBOS, Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
+export function createDbosRunLauncher() {
+    return {
+        async launch(workflow, opts, input) {
+            await DBOS.startWorkflow(workflow, { workflowID: opts.workflowId })(input);
+        },
+        async launchAndAwait(workflow, opts, input, runOpts) {
+            const handle = await DBOS.startWorkflow(workflow, {
+                workflowID: opts.workflowId,
+            })(input);
+            // Registered only after the workflow row is persisted — an abort racing a
+            // not-yet-started workflow would `cancelWorkflow` a missing row (no-op)
+            // and, being `{ once: true }`, never fire again, blocking `getResult`.
+            const cancel = () => {
+                void DBOS.cancelWorkflow(opts.workflowId);
+            };
+            if (runOpts.signal.aborted)
+                cancel();
+            else
+                runOpts.signal.addEventListener("abort", cancel, { once: true });
+            try {
+                const result = await handle.getResult();
+                return { status: "completed", result };
+            }
+            catch (e) {
+                if (e instanceof DBOSErrors.DBOSWorkflowCancelledError) {
+                    return { status: "cancelled" };
+                }
+                throw e;
+            }
+        },
+    };
+}

package/dist/execution/ephemeral-runner.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Ephemeral runner — read-only sandbox execution for ad-hoc data
+ * exploration, run as a turn-scoped DBOS workflow.
+ *
+ * The `run_ephemeral` conversation tool authorizes the run at the async
+ * edge, starts this workflow, and awaits its result inline within the chat
+ * turn. The workflow is "bare": it has no run-event stream, so `emit` is a
+ * no-op and live sandbox progress events are dropped. It is never recovered
+ * — chat disconnect cancels it (`DBOS.cancelWorkflow`), and a boot-time sweep
+ * cancels any `ephemeral:`-prefixed PENDING workflow a dead pod left behind.
+ *
+ * Lifecycle: create sandbox → build the ephemeral-executor with synthetic
+ * step coords (`runId = stepId = "ephemeral"`, the literal the host-managed
+ * billing rules key on) → drive `runAgent` over the executor with `durableStep` →
+ * final text + step count → teardown the sandbox in `finally` on every
+ * terminal path.
+ *
+ * Read-only is enforced, not aspirational: the executor agent is built with
+ * `readOnly: true` (no `write_file`/`edit_file` tools) and its sandbox is
+ * provisioned with no read-write mount — only the read-only analysis tree.
+ * Container-local `/tmp` stays writable (torn down with the sandbox); nothing
+ * persists. The prompt's "you physically cannot write files" is now true.
+ */
+import type { Pool } from "pg";
+import type { RunSession } from "../auth/types.js";
+import type { ResourcePolicy } from "../config/resource-limits.js";
+import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
+import type { SandboxClient } from "../sandbox/client.js";
+import type { BioToolKeys } from "../tools/bio/keys.js";
+import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
+import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
+/** Sub-agent identity — appended to `callPath`, set as `agentId`. */
+export declare const EPHEMERAL_AGENT_ID = "ephemeral-executor";
+/** Workflow-id prefix — the boot-time never-recover sweep matches on it. */
+export declare const EPHEMERAL_WORKFLOW_PREFIX: "ephemeral:";
+/** The body's construction-time deps — closed over at registration. */
+export interface EphemeralDeps {
+    readonly provider: ChatProvider;
+    readonly pool: Pool;
+    readonly sandboxClient: SandboxClient;
+    readonly workspaceFs: WorkspaceFilesystem;
+    /** Embedding provider for the executor's in-sandbox `workspace_search`. */
+    readonly embedding: EmbeddingProvider;
+    /** Workspace-root resolution seam (see workspace/paths.ts). */
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    /** Model id — provenance / metric label; the provider owns the wire model. */
+    readonly model: string;
+    /** API keys for the bio/chem tools the ephemeral executor may use. */
+    readonly bioKeys: BioToolKeys;
+    /** Host resource policy — its `ephemeral` spec overrides the default sandbox size. */
+    readonly resourcePolicy?: ResourcePolicy;
+}
+/**
+ * Workflow input. JSON-serialisable — the authorized `RunSession` carries the
+ * run credential; the body reads it and never re-authorizes.
+ */
+export interface EphemeralWorkflowInput {
+    readonly runSession: RunSession;
+    readonly prompt: string;
+    /** Optional cap on the inner agent's tool-call budget. */
+    readonly maxIterations?: number;
+    /** Optional deadline override for sandbox-server execs (unix ms). */
+    readonly deadlineMs?: number;
+}
+export interface EphemeralResult {
+    readonly text: string;
+    readonly durationMs: number;
+    readonly stepsUsed: number;
+}
+/**
+ * Register the ephemeral workflow with DBOS. Returns the registered callable
+ * so the `run_ephemeral` tool can dispatch via `DBOS.startWorkflow`.
+ */
+export declare function registerEphemeralWorkflow(deps: EphemeralDeps): (input: EphemeralWorkflowInput) => Promise<EphemeralResult>;
+/**
+ * Run the ephemeral-executor agent against a fresh read-only sandbox.
+ * Throws on sandbox start failure; otherwise returns the agent's final
+ * text plus timing. Sandbox teardown fires on every terminal path —
+ * success, error, cancel.
+ */
+export declare function runEphemeralBody(input: EphemeralWorkflowInput, deps: EphemeralDeps): Promise<EphemeralResult>;