@inflexa-ai/harness 0.1.1

package/dist/execution/ephemeral-runner.js

@@ -0,0 +1,161 @@
+/**
+ * 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 { DBOS, Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
+import { forSubAgent } from "../auth/types.js";
+import { finalText, runAgent } from "../loop/run-agent.js";
+import { durableStep } from "../loop/run-step.js";
+import { generateExecutionId } from "../sandbox/execution-id.js";
+import { mintSandboxIdentity } from "../sandbox/identity.js";
+import { createEphemeralExecutorAgent } from "../agents/sandbox/ephemeral-executor.js";
+/** Sub-agent identity — appended to `callPath`, set as `agentId`. */
+export const EPHEMERAL_AGENT_ID = "ephemeral-executor";
+/**
+ * Synthetic run/step literal stamped into the agent's step coords.
+ * Host-managed billing rules key on this literal to recognize chat-turn
+ * ephemeral runs (no `cortex_runs` row, no DBOS stream).
+ */
+const EPHEMERAL_RUN_LITERAL = "ephemeral";
+/** Workflow-id prefix — the boot-time never-recover sweep matches on it. */
+export const EPHEMERAL_WORKFLOW_PREFIX = "ephemeral:";
+/** Default budget — chat-turn-scoped, no recovery, no checkpointing. */
+const DEFAULT_DEADLINE_MS = 120_000;
+/** Ephemeral runs have no planner estimate, so the sandbox box is chosen here
+ *  explicitly — the policy's `ephemeral` spec when supplied, otherwise this
+ *  mid-range default; either way clamped to cluster limits at create time. */
+const EPHEMERAL_SANDBOX_RESOURCES = { cpu: 4, memoryGb: 8 };
+/**
+ * Register the ephemeral workflow with DBOS. Returns the registered callable
+ * so the `run_ephemeral` tool can dispatch via `DBOS.startWorkflow`.
+ */
+export function registerEphemeralWorkflow(deps) {
+    return DBOS.registerWorkflow((input) => runEphemeralBody(input, deps), { name: "ephemeral" });
+}
+/**
+ * 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 async function runEphemeralBody(input, deps) {
+    const { runSession } = input;
+    if (runSession.scope.kind !== "analysis") {
+        throw new Error(`runEphemeralBody requires an analysis-scoped session — got ${runSession.scope.kind}`);
+    }
+    const analysisId = runSession.scope.analysisId;
+    const startedAt = performance.now();
+    const executionId = generateExecutionId(EPHEMERAL_AGENT_ID);
+    const workflowId = DBOS.workflowID ?? `${EPHEMERAL_WORKFLOW_PREFIX}${executionId}`;
+    const childSession = forSubAgent(runSession, EPHEMERAL_AGENT_ID);
+    // Resolver throw = loud workflow failure, per the workspace-root-resolution contract.
+    const workspaceRoot = deps.resolveWorkspaceRoot(analysisId);
+    console.log(`[ephemeral] execution=${executionId} analysis=${analysisId} starting sandbox`);
+    const sandbox = await deps.sandboxClient.createSandbox({
+        runId: EPHEMERAL_RUN_LITERAL,
+        stepId: EPHEMERAL_RUN_LITERAL,
+        analysisId,
+        execId: null,
+        childWorkflowId: workflowId,
+        resources: deps.resourcePolicy?.ephemeral ?? EPHEMERAL_SANDBOX_RESOURCES,
+        // No read-write step mount — only the read-only analysis tree.
+        readOnly: true,
+    }, mintSandboxIdentity(EPHEMERAL_RUN_LITERAL));
+    try {
+        // The fallback reads the CHECKPOINTED clock, not `Date.now()`: `awaitExec`
+        // gates on this absolute deadline, and its recovery-pull is a durable step,
+        // so a wall-clock deadline that grew on replay would shift which loop
+        // iteration crosses the deadline and desynchronise the recorded function-ID
+        // sequence (see the harness-durable-runtime spec; sandbox-step.ts does the
+        // same). `input.deadlineMs`, when present, is already replay-stable.
+        const deadlineAbs = input.deadlineMs ?? (await DBOS.now()) + DEFAULT_DEADLINE_MS;
+        const nextFunctionId = makeNextFunctionId();
+        const sandboxAgentDeps = {
+            provider: deps.provider,
+            pool: deps.pool,
+            sandboxClient: deps.sandboxClient,
+            workspaceFs: deps.workspaceFs,
+            embedding: deps.embedding,
+            model: deps.model,
+            bioKeys: deps.bioKeys,
+            step: {
+                sandbox,
+                workspaceRoot,
+                analysisId,
+                runId: EPHEMERAL_RUN_LITERAL,
+                stepId: EPHEMERAL_RUN_LITERAL,
+                workflowId,
+                // Enforced read-only: the executor agent gets no write_file/edit_file
+                // tools and the sandbox has no read-write mount. This prefix is not a
+                // writable location — it only resolves `execute_command`'s default cwd
+                // to the read-only analysis-tree root (`/{analysisId}`), where reads land.
+                allowedWritePrefix: workspaceRoot,
+                nextFunctionId,
+                deadlineMs: () => deadlineAbs,
+            },
+        };
+        const agentDef = createEphemeralExecutorAgent(sandboxAgentDeps);
+        const agent = input.maxIterations !== undefined ? { ...agentDef, maxIterations: input.maxIterations } : agentDef;
+        const signal = new AbortController().signal;
+        const { messages: finalMessages } = await runAgent(agent, [{ role: "user", content: input.prompt }], childSession, {
+            provider: deps.provider,
+            signal,
+            emit: () => { },
+            runStep: durableStep,
+            isFatalLoopError: (err) => err instanceof DBOSErrors.DBOSWorkflowCancelledError,
+        });
+        const text = finalText(finalMessages);
+        const stepsUsed = countAssistantTurns(finalMessages);
+        const durationMs = Math.round(performance.now() - startedAt);
+        console.log(`[ephemeral] execution=${executionId} completed stepsUsed=${stepsUsed} durationMs=${durationMs}`);
+        return { text, stepsUsed, durationMs };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[ephemeral] execution=${executionId} failed: ${message}`);
+        throw err;
+    }
+    finally {
+        try {
+            await deps.sandboxClient.teardown(sandbox);
+        }
+        catch (teardownErr) {
+            // Teardown is idempotent — "already gone" is success. A failure here
+            // is best-effort logged so the chat turn doesn't fail on cleanup.
+            console.warn(`[ephemeral] execution=${executionId} teardown failed (non-fatal): ${teardownErr instanceof Error ? teardownErr.message : teardownErr}`);
+        }
+    }
+}
+/** Per-call function-id minter — replay-deterministic. */
+function makeNextFunctionId() {
+    let n = 0;
+    return () => `fn-${(n++).toString(36)}`;
+}
+/** The agent's final assistant turn is the `stepsUsed` proxy — every loop
+ *  iteration produces one assistant message. */
+function countAssistantTurns(messages) {
+    let n = 0;
+    for (const m of messages)
+        if (m.role === "assistant")
+            n++;
+    return n;
+}

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

@@ -0,0 +1,57 @@
+/**
+ * `FilesystemArtifactRegistry` — the harness's (cloud-free) `ArtifactRegistry`
+ * adapter.
+ *
+ * Instead of registering provenance with an external ledger, it writes a local
+ * provenance index file under the step directory:
+ *
+ *   {sessionPath}/{resourceId}/runs/{runId}/{stepId}/provenance-index.json
+ *
+ * The index records the step's registered artifacts (analysis-scoped paths +
+ * hashes) and the tracked inputs/outputs captured by the `ProvenanceCollector`,
+ * so a local embedder (the CLI) retains a queryable lineage record with no
+ * cloud dependency. Re-registration merges by output path (latest wins).
+ *
+ * It returns no external ids — the local `cortex_artifacts` ledger is the only
+ * identity store in the cloud-free configuration.
+ */
+import type { ArtifactRegistry } from "./artifact-registry.js";
+export interface FilesystemArtifactRegistryDeps {
+    /** Base path holding per-analysis session directories. */
+    sessionPath: string;
+}
+/** One registered artifact in the local index. */
+export interface FilesystemArtifactEntry {
+    /** Analysis-scoped path (`runs/{runId}/{stepId}/...`). */
+    path: string;
+    hash: string;
+    size: number;
+    type: string;
+}
+/** One tracked output's lineage in the local index. */
+export interface FilesystemLineageRecord {
+    outputPath: string;
+    outputHash: string;
+    producer: string;
+    scriptPath: string | null;
+    inputs: Array<{
+        path: string;
+        hash: string;
+        source: string;
+    }>;
+}
+/** Shape of the persisted provenance index file. */
+export interface FilesystemProvenanceIndex {
+    resourceId: string;
+    runId: string;
+    stepId: string;
+    updatedAt: string;
+    artifacts: FilesystemArtifactEntry[];
+    inputs: Array<{
+        path: string;
+        hash: string;
+        source: string;
+    }>;
+    lineage: FilesystemLineageRecord[];
+}
+export declare function createFilesystemArtifactRegistry(deps: FilesystemArtifactRegistryDeps): ArtifactRegistry;

package/dist/execution/filesystem-artifact-registry.js

@@ -0,0 +1,92 @@
+/**
+ * `FilesystemArtifactRegistry` — the harness's (cloud-free) `ArtifactRegistry`
+ * adapter.
+ *
+ * Instead of registering provenance with an external ledger, it writes a local
+ * provenance index file under the step directory:
+ *
+ *   {sessionPath}/{resourceId}/runs/{runId}/{stepId}/provenance-index.json
+ *
+ * The index records the step's registered artifacts (analysis-scoped paths +
+ * hashes) and the tracked inputs/outputs captured by the `ProvenanceCollector`,
+ * so a local embedder (the CLI) retains a queryable lineage record with no
+ * cloud dependency. Re-registration merges by output path (latest wins).
+ *
+ * It returns no external ids — the local `cortex_artifacts` ledger is the only
+ * identity store in the cloud-free configuration.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { runStepDir } from "../workspace/paths.js";
+function indexPath(sessionPath, input) {
+    return join(sessionPath, runStepDir(input.resourceId, input.runId, input.stepId), "provenance-index.json");
+}
+async function readIndex(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        // Corrupt/partial index (e.g. crash mid-write) → treat as absent and rebuild.
+        if (err instanceof SyntaxError)
+            return null;
+        throw err;
+    }
+}
+/** Merge two keyed lists, latest (incoming) winning per key. */
+function mergeBy(prior, incoming, key) {
+    const byKey = new Map();
+    for (const item of prior)
+        byKey.set(key(item), item);
+    for (const item of incoming)
+        byKey.set(key(item), item);
+    return [...byKey.values()];
+}
+export function createFilesystemArtifactRegistry(deps) {
+    const { sessionPath } = deps;
+    return {
+        async register(input, _session) {
+            const { runId, stepId, artifacts, collector } = input;
+            if (artifacts.length === 0) {
+                return { registered: [], failed: [], failedCount: 0 };
+            }
+            const dbPathPrefix = `runs/${runId}/${stepId}/`;
+            const entries = artifacts.map((a) => ({
+                path: `${dbPathPrefix}${a.path}`,
+                hash: a.hash ?? "",
+                size: a.size,
+                type: a.type,
+            }));
+            const inputs = collector.getTrackedInputs().map((i) => ({
+                path: i.path,
+                hash: i.hash,
+                source: i.source,
+            }));
+            const lineage = collector.getRecords().map((r) => ({
+                outputPath: r.outputPath,
+                outputHash: r.outputHash,
+                producer: r.producer.type,
+                scriptPath: r.scriptPath,
+                inputs: r.inputs.map((i) => ({ path: i.path, hash: i.hash, source: i.source })),
+            }));
+            const path = indexPath(sessionPath, input);
+            const prior = await readIndex(path);
+            const merged = {
+                resourceId: input.resourceId,
+                runId,
+                stepId,
+                updatedAt: new Date().toISOString(),
+                artifacts: mergeBy(prior?.artifacts ?? [], entries, (e) => e.path),
+                inputs: mergeBy(prior?.inputs ?? [], inputs, (i) => i.path),
+                lineage: mergeBy(prior?.lineage ?? [], lineage, (l) => l.outputPath),
+            };
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, JSON.stringify(merged, null, 2));
+            // No external identity store in the cloud-free configuration.
+            return { registered: [], failed: [], failedCount: 0 };
+        },
+        // Bytes already live in the local session tree — nothing to upload.
+        async sync() { },
+    };
+}

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

@@ -0,0 +1,11 @@
+import type { ArtifactRegistry } from "./artifact-registry.js";
+/**
+ * Local/OSS artifact-registration seam: `register` records nothing externally
+ * and reports zero failures; `sync` is a no-op. The harness writes the local
+ * `cortex_artifacts` ledger itself around this seam (see
+ * `artifact-registration.ts`), so an embedder with no external provenance
+ * system genuinely has nothing to register. `failedCount: 0` is the shape the
+ * post-step fail-fast gate reads as success, so the local default never trips
+ * it.
+ */
+export declare function createNoopArtifactRegistry(): ArtifactRegistry;

package/dist/execution/noop-artifact-registry.js

@@ -0,0 +1,17 @@
+/**
+ * Local/OSS artifact-registration seam: `register` records nothing externally
+ * and reports zero failures; `sync` is a no-op. The harness writes the local
+ * `cortex_artifacts` ledger itself around this seam (see
+ * `artifact-registration.ts`), so an embedder with no external provenance
+ * system genuinely has nothing to register. `failedCount: 0` is the shape the
+ * post-step fail-fast gate reads as success, so the local default never trips
+ * it.
+ */
+export function createNoopArtifactRegistry() {
+    return {
+        async register() {
+            return { registered: [], failed: [], failedCount: 0 };
+        },
+        async sync() { },
+    };
+}

package/dist/execution/post-step-pipeline.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The harness's post-step pipeline — the per-step bookkeeping that runs after a sandbox
+ * agent loop finishes: describe the output files, write an interpretive
+ * summary, reconcile + register the artifact manifest, and index the
+ * descriptions into the per-analysis vector store.
+ *
+ * These leaf bodies are host-neutral: the only place an embedder differs is the
+ * injected `ArtifactRegistry` (filesystem vs. external provenance) and the
+ * write-side `EmbeddingProvider` (billing). The sandbox-step workflow body owns
+ * the orchestration — which stage is `DBOS.runStep`-wrapped, which stage is
+ * fail-fast vs. best-effort. This module owns only the stage bodies.
+ */
+import type { Pool } from "pg";
+import type { AgentChat, EmbeddingProvider } from "../providers/types.js";
+import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
+import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
+import type { ArtifactManifestEntry } from "../schemas/artifact-manifest.js";
+import type { StepSummary } from "../schemas/step-summary.js";
+import type { ArtifactRegistry } from "./artifact-registry.js";
+import { type FileMetadataEntry } from "./artifact-metadata.js";
+import type { PostStepArtifacts, PostStepContext, StepOutputs } from "../workflows/sandbox-step.js";
+/**
+ * The subset of `SandboxStepDeps` the post-step stages consume. The sandbox-step
+ * body passes its own `deps` straight through (it is a structural superset).
+ */
+export interface PostStepPipelineDeps {
+    readonly pool: Pool;
+    /** Non-streaming chat — the metadata + summary sub-agent loops. */
+    readonly provider: AgentChat;
+    /** Write-side embedder for the vector index. */
+    readonly embedding: EmbeddingProvider;
+    readonly workspaceFs: WorkspaceFilesystem;
+    readonly artifactRegistry: ArtifactRegistry;
+    /** Workspace-root resolution seam (see workspace/paths.ts). */
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    /** Sandbox model id — provenance label for metadata + summary. */
+    readonly model: string;
+}
+/**
+ * Describe each manifest file. Returns one entry per file — a file the model
+ * fails to describe gets a deterministic fallback, never a dropped entry.
+ */
+export declare function generateStepFileMetadata(deps: PostStepPipelineDeps, postCtx: PostStepContext, manifest: readonly ArtifactManifestEntry[]): Promise<readonly FileMetadataEntry[]>;
+/**
+ * Generate the interpretive step summary and persist it to
+ * `output/summary.md`. A write failure is non-fatal (logged) — the summary is
+ * still returned for vector indexing.
+ */
+export declare function generateStepSummaryAndWrite(deps: PostStepPipelineDeps, postCtx: PostStepContext, manifest: readonly ArtifactManifestEntry[]): Promise<StepSummary | undefined>;
+/**
+ * Reconcile the manifest against disk (drop phantoms, rehash) and register the
+ * survivors with the local ledger + the injected `ArtifactRegistry`. Fail-fast
+ * (see the artifact-manifest spec): a non-zero `externalFailed` is a persistent rejection that
+ * orphans real outputs, so it throws with the per-file detail (the OSS
+ * filesystem registry returns `externalFailed: 0`, so it never trips). Returns
+ * the reconciled manifest.
+ */
+export declare function reconcileAndRegisterStepArtifacts(deps: PostStepPipelineDeps, postCtx: PostStepContext, manifest: readonly ArtifactManifestEntry[]): Promise<readonly ArtifactManifestEntry[]>;
+/**
+ * Vector-index the threaded file descriptions + summary into the per-analysis
+ * pgvector store. Best-effort (see the artifact-manifest spec): indexing degrades on any failure
+ * without failing the step — the internal try/catch logs + swallows.
+ */
+export declare function vectorIndexStepOutputs(deps: PostStepPipelineDeps, postCtx: PostStepContext, artifacts: PostStepArtifacts): Promise<void>;
+/**
+ * Assemble the step-detail payload (file tree, summary markdown, output file
+ * descriptions) from the threaded post-step products. Pure — returns
+ * `undefined` when nothing was produced.
+ */
+export declare function collectStepOutputs(postCtx: PostStepContext, artifacts: PostStepArtifacts): StepOutputs | undefined;

package/dist/execution/post-step-pipeline.js

@@ -0,0 +1,207 @@
+/**
+ * The harness's post-step pipeline — the per-step bookkeeping that runs after a sandbox
+ * agent loop finishes: describe the output files, write an interpretive
+ * summary, reconcile + register the artifact manifest, and index the
+ * descriptions into the per-analysis vector store.
+ *
+ * These leaf bodies are host-neutral: the only place an embedder differs is the
+ * injected `ArtifactRegistry` (filesystem vs. external provenance) and the
+ * write-side `EmbeddingProvider` (billing). The sandbox-step workflow body owns
+ * the orchestration — which stage is `DBOS.runStep`-wrapped, which stage is
+ * fail-fast vs. best-effort. This module owns only the stage bodies.
+ */
+import { join } from "node:path";
+import { unwrapOrThrow } from "../lib/result.js";
+import { writeFileWithinRoot } from "../lib/fs-helpers.js";
+import { registerStepArtifacts } from "./artifact-registration.js";
+import { reconcileManifestWithDisk } from "./reconcile-manifest.js";
+import { generateFileMetadata as coreGenerateFileMetadata } from "./artifact-metadata.js";
+import { generateStepSummary as coreGenerateStepSummary } from "./step-summary.js";
+import { createVectorStore } from "../state/vector-store.js";
+import { ensureSearchIndex, searchIndexName } from "../workspace/search-config.js";
+/**
+ * Describe each manifest file. Returns one entry per file — a file the model
+ * fails to describe gets a deterministic fallback, never a dropped entry.
+ */
+export async function generateStepFileMetadata(deps, postCtx, manifest) {
+    const { input, session, transcript, writePrefix } = postCtx;
+    if (manifest.length === 0)
+        return [];
+    const dbPathPrefix = `runs/${input.runId}/${input.stepId}/`;
+    const artifactsForMeta = manifest.map((a) => ({
+        dbPath: `${dbPathPrefix}${a.path}`,
+        displayPath: a.path,
+        sizeBytes: a.size,
+    }));
+    const result = await coreGenerateFileMetadata({
+        provider: deps.provider,
+        session,
+        artifacts: artifactsForMeta,
+        resourceId: input.analysisId,
+        extraMetadata: {
+            role: "step_output",
+            producerStep: input.stepId,
+            producerRun: input.runId,
+            producerAgent: input.agentId,
+        },
+        modelId: deps.model,
+        messages: transcript,
+        workspaceFs: deps.workspaceFs,
+        workingDir: writePrefix,
+    });
+    return result.entries;
+}
+/**
+ * Generate the interpretive step summary and persist it to
+ * `output/summary.md`. A write failure is non-fatal (logged) — the summary is
+ * still returned for vector indexing.
+ */
+export async function generateStepSummaryAndWrite(deps, postCtx, manifest) {
+    const { input, session, transcript, writePrefix } = postCtx;
+    const summary = await coreGenerateStepSummary({
+        provider: deps.provider,
+        session,
+        modelId: deps.model,
+        messages: transcript,
+        artifactPaths: manifest.map((a) => a.path),
+        workspaceFs: deps.workspaceFs,
+        workingDir: writePrefix,
+        stepId: input.stepId,
+        agentId: input.agentId,
+        runId: input.runId,
+    });
+    if (summary && summary.markdown.trim().length > 0) {
+        try {
+            // Host-side write into the step's own RW subtree. Confine to the step
+            // prefix (not the whole workspace) so a symlink a compromised agent
+            // planted cannot redirect it onto a host file — and so this write can
+            // never reach the hard-linked `data/` inputs, which are RO by design.
+            await writeFileWithinRoot(writePrefix, join(writePrefix, "output", "summary.md"), summary.markdown);
+        }
+        catch (err) {
+            console.warn(`[post-step.summary] writeFile output/summary.md failed for ${input.stepId}: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    return summary;
+}
+/**
+ * Reconcile the manifest against disk (drop phantoms, rehash) and register the
+ * survivors with the local ledger + the injected `ArtifactRegistry`. Fail-fast
+ * (see the artifact-manifest spec): a non-zero `externalFailed` is a persistent rejection that
+ * orphans real outputs, so it throws with the per-file detail (the OSS
+ * filesystem registry returns `externalFailed: 0`, so it never trips). Returns
+ * the reconciled manifest.
+ */
+export async function reconcileAndRegisterStepArtifacts(deps, postCtx, manifest) {
+    const { input, session, lineageCollector } = postCtx;
+    const reconciled = await reconcileManifestWithDisk({
+        workspaceRoot: deps.resolveWorkspaceRoot(input.analysisId),
+        resourceId: input.analysisId,
+        runId: input.runId,
+        stepId: input.stepId,
+        agentId: input.agentId,
+        manifest: [...manifest],
+        collector: lineageCollector,
+    });
+    if (reconciled.manifest.length === 0)
+        return reconciled.manifest;
+    const reg = await registerStepArtifacts(deps.pool, deps.artifactRegistry, {
+        resourceId: input.analysisId,
+        runId: input.runId,
+        stepId: input.stepId,
+        artifacts: reconciled.manifest,
+        collector: lineageCollector,
+    }, session);
+    if (reg.externalFailed > 0) {
+        const wholeActivityFailed = reg.externalRegistered === 0;
+        const detail = reg.failureDetails.map((f) => `${f.path}: ${f.error}`).join("\n  ");
+        const msg = `[post-step.reconcile] external registration failed for ${input.stepId}: ` +
+            `${reg.externalFailed} row(s) rejected, ${reg.externalRegistered}/${reg.localCount} local artifact(s) registered` +
+            (wholeActivityFailed ? " (WHOLE ACTIVITY ROLLED BACK — outputs orphaned)" : "") +
+            (detail ? `\n  ${detail}` : "");
+        console.error(msg);
+        throw new Error(msg);
+    }
+    return reconciled.manifest;
+}
+/**
+ * Vector-index the threaded file descriptions + summary into the per-analysis
+ * pgvector store. Best-effort (see the artifact-manifest spec): indexing degrades on any failure
+ * without failing the step — the internal try/catch logs + swallows.
+ */
+export async function vectorIndexStepOutputs(deps, postCtx, artifacts) {
+    const { input } = postCtx;
+    const { metadataEntries, summary, reconciledManifest } = artifacts;
+    try {
+        await ensureSearchIndex(deps.pool, input.analysisId, deps.embedding.dimensions);
+        const vectorStore = createVectorStore(deps.pool);
+        const indexName = searchIndexName(input.analysisId);
+        const embedOne = async (text) => {
+            const [vec] = unwrapOrThrow(await deps.embedding.embed([text], postCtx.session));
+            if (!vec)
+                throw new Error("vectorIndexStepOutputs: empty embedding response");
+            return vec;
+        };
+        const dbPathPrefix = `runs/${input.runId}/${input.stepId}/`;
+        const survivingPaths = new Set(reconciledManifest.map((a) => a.path));
+        const liveMetadata = metadataEntries.filter((e) => survivingPaths.has(e.dbPath.slice(dbPathPrefix.length)));
+        for (const entry of liveMetadata) {
+            const embedding = await embedOne(entry.description);
+            unwrapOrThrow(await vectorStore.upsert({
+                indexName,
+                vectors: [embedding],
+                metadata: [{ text: entry.description, type: "output", ...entry.metadata }],
+                ids: [`/${input.analysisId}/${entry.dbPath}`],
+            }));
+        }
+        if (summary && summary.markdown.trim().length > 0) {
+            const relPath = `runs/${input.runId}/${input.stepId}/output/summary.md`;
+            const summaryDbPath = `/${input.analysisId}/${relPath}`;
+            const summaryEmbedding = await embedOne(summary.markdown);
+            unwrapOrThrow(await vectorStore.upsert({
+                indexName,
+                vectors: [summaryEmbedding],
+                metadata: [
+                    {
+                        text: summary.markdown,
+                        type: "summary",
+                        stepId: input.stepId,
+                        runId: input.runId,
+                        agentId: input.agentId,
+                        path: relPath,
+                    },
+                ],
+                ids: [summaryDbPath],
+            }));
+        }
+    }
+    catch (err) {
+        console.warn(`[post-step.vector-index] indexing failed for ${input.stepId}: ${err instanceof Error ? err.message : err}`);
+    }
+}
+/**
+ * Assemble the step-detail payload (file tree, summary markdown, output file
+ * descriptions) from the threaded post-step products. Pure — returns
+ * `undefined` when nothing was produced.
+ */
+export function collectStepOutputs(postCtx, artifacts) {
+    const { input } = postCtx;
+    const { metadataEntries, summary, reconciledManifest } = artifacts;
+    const dbPathPrefix = `runs/${input.runId}/${input.stepId}/`;
+    const descByPath = new Map();
+    for (const e of metadataEntries) {
+        const rel = e.dbPath.startsWith(dbPathPrefix) ? e.dbPath.slice(dbPathPrefix.length) : e.dbPath;
+        descByPath.set(rel, e.description);
+    }
+    const files = reconciledManifest.map((a) => ({
+        path: a.path,
+        size: a.size,
+        fileType: a.type,
+        description: descByPath.get(a.path) ?? "",
+    }));
+    const summaryMarkdown = summary?.markdown ?? "";
+    if (files.length === 0 && summaryMarkdown.trim().length === 0) {
+        return undefined;
+    }
+    return { files, summaryMarkdown };
+}

package/dist/execution/post-step.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Post-step helper — disk-walk of a step's writable artifact directory.
+ *
+ * The step's runtime input/script lineage rides on the step-scoped
+ * `ProvenanceCollector` the sandbox-step body threads through
+ * `PostStepContext` (fed per-exec during the agent loop). This module only
+ * owns the manifest source: walking the writable step dir and hashing each
+ * file from disk.
+ */
+import { type ArtifactManifestEntry } from "../schemas/artifact-manifest.js";
+/**
+ * Walk a step's writable artifact directory and produce a fully-hashed
+ * `ArtifactManifestEntry[]`. Skips IGNORED_DIRS. Paths are relative to
+ * `writePrefix`.
+ */
+export declare function walkStepArtifacts(args: {
+    readonly writePrefix: string;
+    readonly stepId: string;
+    readonly runId: string;
+}): Promise<ArtifactManifestEntry[]>;