@inflexa-ai/harness 0.11.0 → 0.13.0

package/dist/agents/sandbox/ephemeral-executor.js

@@ -1,20 +0,0 @@
-/**
- * Ephemeral Executor — read-only sandbox agent for quick computations.
- * Cannot create files; step conventions don't apply.
- */
-import { ephemeralExecutorPrompt } from "../../prompts/sandbox/ephemeral-executor.js";
-import { BASE_SANDBOX_TOOLS, createSandboxAgent } from "./shared.js";
-export const meta = {
-    id: "ephemeral-executor",
-    capabilities: ["data inspection", "quick statistics", "data transformation", "table preview"],
-    suitableFor: ["bulk-rna-seq", "single-cell", "proteomics", "metabolomics", "genomics", "transcriptomics", "general-omics"],
-    skills: ["shared/omics-general"],
-    tools: [...BASE_SANDBOX_TOOLS, "pubmed", "searchGene", "searchPathway", "lookupGoTerm", "searchInteractions"],
-    plannable: false,
-};
-export function createEphemeralExecutorAgent(deps) {
-    return createSandboxAgent(deps, meta, ephemeralExecutorPrompt, {
-        appendAnalysisStepStandards: false,
-        readOnly: true,
-    });
-}

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

@@ -1,98 +0,0 @@
-/**
- * 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 { EnvironmentStorePaths } from "../config/environment-stores.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";
-import type { Logger } from "../lib/logger.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 extends EnvironmentStorePaths {
-    /** Operational logging seam; omitted falls back to no-op. */
-    readonly logger?: Logger;
-    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>;
-/**
- * The executor's seed: its workspace frame, then the caller's ask.
- *
- * An ephemeral run is not scheduled by `executeAnalysis`, so no step briefing is
- * composed for it — and the sandbox system prompt names no paths (it is static
- * per agent type, so the provider's prompt cache can reuse it). The analysis
- * root would otherwise reach the agent nowhere: `run_ephemeral`'s `prompt` is
- * free text authored by the conversation agent.
- *
- * The frame differs from a step's, so this does not reuse `renderWorkspace`:
- * there is no writable directory to name. The read-only tree IS the cwd.
- */
-export declare function ephemeralSeed(analysisId: string, prompt: string): string;
-/**
- * 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>;

package/dist/execution/ephemeral-runner.js

@@ -1,189 +0,0 @@
-/**
- * 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";
-import { createNoopLogger } from "../lib/console-logger.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" });
-}
-/**
- * The executor's seed: its workspace frame, then the caller's ask.
- *
- * An ephemeral run is not scheduled by `executeAnalysis`, so no step briefing is
- * composed for it — and the sandbox system prompt names no paths (it is static
- * per agent type, so the provider's prompt cache can reuse it). The analysis
- * root would otherwise reach the agent nowhere: `run_ephemeral`'s `prompt` is
- * free text authored by the conversation agent.
- *
- * The frame differs from a step's, so this does not reuse `renderWorkspace`:
- * there is no writable directory to name. The read-only tree IS the cwd.
- */
-export function ephemeralSeed(analysisId, prompt) {
-    const root = `/${analysisId}`;
-    return [
-        "## Workspace",
-        `- Analysis root (read-only): \`${root}\` — inputs at \`${root}/data/inputs/\`, prior runs at \`${root}/runs/\`.`,
-        `- The analysis root is also your cwd, and what relative paths resolve against. The sandbox is read-only: there is nowhere to write, so return every result inline.`,
-        "",
-        prompt,
-    ].join("\n");
-}
-/**
- * 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;
-    // Bound after the scope guard: `analysisId` comes off the session's scope,
-    // not the workflow input.
-    const logger = (deps.logger ?? createNoopLogger()).named("ephemeral").with({ 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);
-    logger.info("starting sandbox", { executionId });
-    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,
-            ...(deps.packagesFile ? { packagesFile: deps.packagesFile } : {}),
-            ...(deps.refStorePath ? { refStorePath: deps.refStorePath } : {}),
-            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: ephemeralSeed(analysisId, 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);
-        logger.info("completed", { executionId, stepsUsed, durationMs });
-        return { text, stepsUsed, durationMs };
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        logger.error("failed", { executionId, err: 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.
-            logger.warn("teardown failed (non-fatal)", { executionId, ...logger.errorFields(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/prompts/sandbox/ephemeral-executor.d.ts

@@ -1 +0,0 @@
-export declare const ephemeralExecutorPrompt = "# Ephemeral Executor\n\nYou are a read-only compute agent. You execute scripts on the user's data\nand return the results. You **cannot create or save files** \u2014 your sandbox\nis fully read-only.\n\n## What You Do\n\n1. Read data files to understand their structure\n2. Write and execute R or Python scripts via `execute_command`\n3. Return the script output (tables, statistics, plot data) in your response\n\n## Constraints\n\n- **Read-only**: You physically cannot write files. Do not attempt to save\n  output to disk. All results must be returned in your text response.\n- **Inline output**: Print results to stdout. For plots, use base64 encoding\n  and print the encoded string so the caller can display it.\n- **Structured responses**: When returning tabular data, format as markdown\n  tables or JSON arrays. When returning statistics, use clear labeled output.\n\n## Script Execution Pattern\n\nFor Python:\n```\nexecute_command python3 -c \"\nimport pandas as pd\ndf = pd.read_csv('/{resourceId}/data/inputs/{fileId}/data.csv')\nprint(df.describe().to_markdown())\n\"\n```\n\nFor R:\n```\nexecute_command Rscript -e \"\ndf <- read.csv('/{resourceId}/data/inputs/{fileId}/data.csv')\nsummary(df)\n\"\n```\n\nFor plots (base64):\n```\nexecute_command python3 -c \"\nimport matplotlib\nmatplotlib.use('Agg')\nimport matplotlib.pyplot as plt\nimport pandas as pd\nimport base64, io\n\ndf = pd.read_csv('...')\nfig, ax = plt.subplots()\ndf.plot(ax=ax)\nbuf = io.BytesIO()\nfig.savefig(buf, format='png')\nprint(base64.b64encode(buf.getvalue()).decode())\n\"\n```\n\n## Do NOT\n\n- Attempt to write files \u2014 it will fail silently or error\n- Install packages at runtime\n- Return raw binary data without base64 encoding\n- Guess data structure without inspecting the file first\n- Run long-running computations (you have a short timeout)\n";

package/dist/prompts/sandbox/ephemeral-executor.js

@@ -1,66 +0,0 @@
-export const ephemeralExecutorPrompt = `# Ephemeral Executor
-
-You are a read-only compute agent. You execute scripts on the user's data
-and return the results. You **cannot create or save files** — your sandbox
-is fully read-only.
-
-## What You Do
-
-1. Read data files to understand their structure
-2. Write and execute R or Python scripts via \`execute_command\`
-3. Return the script output (tables, statistics, plot data) in your response
-
-## Constraints
-
-- **Read-only**: You physically cannot write files. Do not attempt to save
-  output to disk. All results must be returned in your text response.
-- **Inline output**: Print results to stdout. For plots, use base64 encoding
-  and print the encoded string so the caller can display it.
-- **Structured responses**: When returning tabular data, format as markdown
-  tables or JSON arrays. When returning statistics, use clear labeled output.
-
-## Script Execution Pattern
-
-For Python:
-\`\`\`
-execute_command python3 -c "
-import pandas as pd
-df = pd.read_csv('/{resourceId}/data/inputs/{fileId}/data.csv')
-print(df.describe().to_markdown())
-"
-\`\`\`
-
-For R:
-\`\`\`
-execute_command Rscript -e "
-df <- read.csv('/{resourceId}/data/inputs/{fileId}/data.csv')
-summary(df)
-"
-\`\`\`
-
-For plots (base64):
-\`\`\`
-execute_command python3 -c "
-import matplotlib
-matplotlib.use('Agg')
-import matplotlib.pyplot as plt
-import pandas as pd
-import base64, io
-
-df = pd.read_csv('...')
-fig, ax = plt.subplots()
-df.plot(ax=ax)
-buf = io.BytesIO()
-fig.savefig(buf, format='png')
-print(base64.b64encode(buf.getvalue()).decode())
-"
-\`\`\`
-
-## Do NOT
-
-- Attempt to write files — it will fail silently or error
-- Install packages at runtime
-- Return raw binary data without base64 encoding
-- Guess data structure without inspecting the file first
-- Run long-running computations (you have a short timeout)
-`;

package/dist/tools/execute-plan.d.ts

@@ -1,64 +0,0 @@
-/**
- * executePlan — launch the DBOS `executeAnalysis` parent workflow for an
- * approved plan.
- *
- * Results are pull-only: the tool does NOT register a `.then(saveRunResult)`
- * or any completion callback that writes to the conversation thread. The
- * conversation agent retrieves run results via `inspectRun` on a later turn.
- *
- * Authorization contract: the tool runs in the chat HTTP route, so its session
- * carries the live auth. It authorizes through the injected `RunAuthorizer`
- * seam and never reads a credential. The flow is dedup → reserve → authorize
- * → startWorkflow:
- *
- *   1. Dedup pre-check via `queryActiveRun`. On hit, return the existing
- *      `runId` with no authorization and no `startWorkflow`.
- *   2. Reserve the slot: `insertRun` the `cortex_runs` row (`runId =
- *      randomUUID()`, the bare UUID that IS the DBOS workflowID) BEFORE
- *      authorizing. The partial-unique index is the race backstop; the loser
- *      returns the winner's `runId` without authorizing — nothing to revoke.
- *   3. `runAuthorizer.authorize({ ..., frame: { runId } })` — authorizes the
- *      run; the authorizer's persisted handle now lands because the row
- *      exists. On failure, mark the reserved row `failed` (releasing the dedup
- *      slot for a retry) and rethrow.
- *   4. `runLauncher.launch(executeAnalysis, { workflowId: runId }, ...)`,
- *      passing the `RunSession` in the workflow input. On failure, revoke + mark
- *      failed.
- */
-import type { Pool } from "pg";
-import type { ResourcePolicy } from "../config/resource-limits.js";
-import type { RunAuthorizer } from "../execution/run-authorizer.js";
-import type { RunLauncher } from "../execution/run-launcher.js";
-import type { ExecuteAnalysisInput, ExecuteAnalysisResult } from "../workflows/execute-analysis.js";
-type ExecuteAnalysisWorkflow = (input: ExecuteAnalysisInput) => Promise<ExecuteAnalysisResult>;
-export interface ExecutePlanToolDeps {
-    readonly pool: Pool;
-    /** Registered `executeAnalysis` workflow callable — produced by `registerExecuteAnalysis` (wired by `assembleCoreRuntime`). */
-    readonly executeAnalysisWorkflow: ExecuteAnalysisWorkflow;
-    /** Authorizes the run at the async edge and revokes on the abort paths. */
-    readonly runAuthorizer: RunAuthorizer;
-    /** Starts the durable run — the durability engine stays behind this seam. */
-    readonly runLauncher: RunLauncher;
-    /**
-     * Host resource policy. The machine budget is snapshotted into the workflow
-     * input here at the async edge — the workflow body never reads live config,
-     * so a mid-run config edit cannot change a running run's admission decisions.
-     */
-    readonly resourcePolicy?: ResourcePolicy;
-}
-export declare class PlanNotFoundError extends Error {
-    constructor(planId: string);
-}
-export declare class PlanMalformedError extends Error {
-    constructor(planId: string);
-}
-export declare class PlanValidationError extends Error {
-    readonly errors: string[];
-    constructor(planId: string, errors: string[]);
-}
-export declare function createExecutePlanTool(deps: ExecutePlanToolDeps): import("./define-tool.js").Tool<{
-    planId: string;
-}, {
-    runId: string;
-}>;
-export {};

package/dist/tools/execute-plan.js

@@ -1,211 +0,0 @@
-/**
- * executePlan — launch the DBOS `executeAnalysis` parent workflow for an
- * approved plan.
- *
- * Results are pull-only: the tool does NOT register a `.then(saveRunResult)`
- * or any completion callback that writes to the conversation thread. The
- * conversation agent retrieves run results via `inspectRun` on a later turn.
- *
- * Authorization contract: the tool runs in the chat HTTP route, so its session
- * carries the live auth. It authorizes through the injected `RunAuthorizer`
- * seam and never reads a credential. The flow is dedup → reserve → authorize
- * → startWorkflow:
- *
- *   1. Dedup pre-check via `queryActiveRun`. On hit, return the existing
- *      `runId` with no authorization and no `startWorkflow`.
- *   2. Reserve the slot: `insertRun` the `cortex_runs` row (`runId =
- *      randomUUID()`, the bare UUID that IS the DBOS workflowID) BEFORE
- *      authorizing. The partial-unique index is the race backstop; the loser
- *      returns the winner's `runId` without authorizing — nothing to revoke.
- *   3. `runAuthorizer.authorize({ ..., frame: { runId } })` — authorizes the
- *      run; the authorizer's persisted handle now lands because the row
- *      exists. On failure, mark the reserved row `failed` (releasing the dedup
- *      slot for a retry) and rethrow.
- *   4. `runLauncher.launch(executeAnalysis, { workflowId: runId }, ...)`,
- *      passing the `RunSession` in the workflow input. On failure, revoke + mark
- *      failed.
- */
-import { randomUUID } from "node:crypto";
-import { ok } from "neverthrow";
-import { z } from "zod";
-import { buildRunCardData } from "../memory/card-builders.js";
-import { unwrapOrThrow } from "../lib/result.js";
-import { validatePlan } from "../schemas/validate-plan.js";
-import { AnalysisPlanSchema } from "../schemas/workflow-state.js";
-import { RunDedupCollisionError, insertRun, loadPlan, queryActiveRun, updateRunStatus } from "../state/index.js";
-import { defineTool } from "./define-tool.js";
-const planIdSchema = z.string().regex(/^pln-[a-f0-9]{8}$/, "planId must be a pln-<8hex> value");
-const inputSchema = z.object({
-    planId: planIdSchema,
-});
-export class PlanNotFoundError extends Error {
-    constructor(planId) {
-        super(`Plan ${planId} not found for this analysis`);
-        this.name = "PlanNotFoundError";
-    }
-}
-export class PlanMalformedError extends Error {
-    constructor(planId) {
-        super(`Plan ${planId} is malformed`);
-        this.name = "PlanMalformedError";
-    }
-}
-export class PlanValidationError extends Error {
-    errors;
-    constructor(planId, errors) {
-        super(`Plan ${planId} failed validation: ${errors.length} error(s)`);
-        this.errors = errors;
-        this.name = "PlanValidationError";
-    }
-}
-function isDedupCollision(err) {
-    return err instanceof RunDedupCollisionError || (err instanceof Error && err.name === "RunDedupCollisionError");
-}
-export function createExecutePlanTool(deps) {
-    const { pool, executeAnalysisWorkflow, runAuthorizer, runLauncher, resourcePolicy } = deps;
-    return defineTool({
-        id: "execute_plan",
-        description: "Execute an approved analysis plan by its planId. " +
-            "Pass the planId returned from generatePlan — the tool resolves the plan " +
-            "server-side, validates the DAG, and starts the executeAnalysis workflow " +
-            "asynchronously. Returns the runId on success. " +
-            "The user sees a run card in chat (also tracked in the Runs panel); " +
-            "run results become available for inspection on a later turn. " +
-            "Do not instruct the user to invoke any tool.",
-        inputSchema,
-        execute: async (input, ctx) => {
-            const { planId } = input;
-            // Mirror show_plan: emit a live display card so chat renders a run card
-            // rather than a generic "used 1 tool" chip. Null (plan/run unresolvable)
-            // simply skips the card — the run still starts.
-            const emitRunCard = async (analysisId, runId) => {
-                const card = await buildRunCardData(pool, {
-                    planId,
-                    analysisId,
-                    runId,
-                }).unwrapOr(null);
-                if (card) {
-                    await ctx.emit({
-                        type: "data-run-card",
-                        source: ctx.session.provenance,
-                        data: card,
-                    });
-                }
-            };
-            const { session } = ctx;
-            if (session.scope.kind !== "analysis") {
-                throw new Error("executePlan can only be invoked on an analysis-scoped session");
-            }
-            if (!session.auth) {
-                throw new Error("executePlan: session is missing its auth capability");
-            }
-            const analysisId = session.scope.analysisId;
-            const threadId = session.scope.threadId ?? null;
-            const raw = unwrapOrThrow(await loadPlan(pool, planId, { analysisId }));
-            if (!raw)
-                throw new PlanNotFoundError(planId);
-            const parsed = AnalysisPlanSchema.safeParse(raw);
-            if (!parsed.success)
-                throw new PlanMalformedError(planId);
-            const plan = parsed.data;
-            const result = validatePlan(plan);
-            if (!result.valid) {
-                throw new PlanValidationError(planId, result.errors);
-            }
-            // (1) Dedup pre-check — common case is the user re-clicked Execute on
-            // an in-flight plan. A hit avoids both the authorization and the DBOS
-            // startWorkflow.
-            const existingPre = unwrapOrThrow(await queryActiveRun(pool, analysisId, planId));
-            if (existingPre) {
-                await emitRunCard(analysisId, existingPre.runId);
-                return ok({ runId: existingPre.runId });
-            }
-            // (2) Reserve the dedup slot by inserting the run row BEFORE authorizing.
-            // The partial-unique index is the race backstop for two callers that both
-            // passed the pre-check; the loser returns the winner's runId without
-            // having authorized — there is nothing to revoke. The authorization handle is left
-            // null here and populated by the authorizer, whose UPDATE lands
-            // because the row now exists.
-            const runId = randomUUID();
-            try {
-                // On the dedup collision `insertRun` throws `RunDedupCollisionError`
-                // (a control-flow signal that rides out of the ResultAsync as a
-                // rejection) — `unwrapOrThrow` never sees it; the catch below does.
-                unwrapOrThrow(await insertRun(pool, {
-                    runId,
-                    analysisId,
-                    threadId,
-                    workflowName: "executeAnalysis",
-                    planId,
-                }));
-            }
-            catch (err) {
-                if (isDedupCollision(err)) {
-                    const existing = unwrapOrThrow(await queryActiveRun(pool, analysisId, planId));
-                    if (existing) {
-                        await emitRunCard(analysisId, existing.runId);
-                        return ok({ runId: existing.runId });
-                    }
-                }
-                throw err;
-            }
-            // (3) Authorize the run. The row exists, so the authorizer's persisted handle
-            // persists. On failure, mark the reserved row failed — releasing the
-            // partial-unique slot so a retry can re-run — and rethrow.
-            let authorization;
-            try {
-                authorization = await runAuthorizer.authorize({
-                    auth: session.auth,
-                    scope: session.scope,
-                    provenance: session.provenance,
-                    frame: { runId },
-                });
-            }
-            catch (err) {
-                await updateRunStatus(pool, runId, "failed", "run authorization failed").match(() => { }, () => { });
-                throw err;
-            }
-            const { runSession } = authorization;
-            const planSummary = plan.title?.trim() || plan.analytical_narrative.trim().slice(0, 280);
-            const workflowInput = {
-                analysisId,
-                planId,
-                planSummary,
-                threadId,
-                steps: plan.steps.map((s) => ({
-                    id: s.id,
-                    depends_on: s.depends_on ?? [],
-                })),
-                // The step DATA, not a rendered prompt: each step's seed is composed
-                // by the scheduler at dispatch, when its dependencies' results exist.
-                // A prompt frozen here — before the first step has run — could never
-                // mention them.
-                planStepById: Object.fromEntries(plan.steps.map((s) => [s.id, s])),
-                agentByStepId: Object.fromEntries(plan.steps.map((s) => [s.id, s.agent ?? "unknown"])),
-                resourcesByStepId: Object.fromEntries(plan.steps.map((s) => {
-                    if (!s.resources) {
-                        throw new Error(`Step "${s.id}" has no resources — validatePlan should have rejected this plan`);
-                    }
-                    return [s.id, s.resources];
-                })),
-                timeoutByStepId: Object.fromEntries(plan.steps.filter((s) => s.timeout !== undefined).map((s) => [s.id, s.timeout])),
-                budget: resourcePolicy?.budget,
-                runSession,
-                ownsMandate: authorization.ownsMandate, // oss-core-managed-ok
-            };
-            // (4) Dispatch the workflow. `workflowId = runId` — both are the same
-            // bare UUID. On failure after insert + authorize, revoke the authorization and
-            // mark the row failed.
-            try {
-                await runLauncher.launch(executeAnalysisWorkflow, { workflowId: runId }, workflowInput);
-            }
-            catch (err) {
-                await runAuthorizer.revoke(authorization, "workflow-start-failed").catch(() => { });
-                await updateRunStatus(pool, runId, "failed", "workflow start failed").match(() => { }, () => { });
-                throw err;
-            }
-            await emitRunCard(analysisId, runId);
-            return ok({ runId });
-        },
-    });
-}