@inflexa-ai/harness 0.12.0 → 0.13.0

package/dist/tools/ad-hoc-router.js

@@ -0,0 +1,132 @@
+import { jsonSchema, tool as aiTool } from "ai";
+import { z } from "zod";
+import { PLANNABLE_AGENT_CATALOG } from "../agents/sandbox-catalog.js";
+import { forSubAgent } from "../auth/types.js";
+import { DATA_PROFILE_ORIENTATION_MAX_CHARS, buildDataProfileOrientation } from "../app/data-profile-orientation.js";
+import { createNoopLogger } from "../lib/console-logger.js";
+import { unwrapOrThrow } from "../lib/result.js";
+import { resourceEstimationSection } from "../prompts/planner.js";
+import { loadDataProfileStatus } from "../state/index.js";
+export const AD_HOC_ROUTER_AGENT_ID = "adhoc-router";
+export const AD_HOC_ROUTER_TIMEOUT_MS = 10_000;
+export const AD_HOC_FALLBACK_AGENT_ID = "scientific-executor";
+const resourcesSchema = z.object({
+    cpu: z.number().positive(),
+    memoryGb: z.number().positive(),
+    gpu: z.object({ count: z.number().int().positive() }).optional(),
+});
+const routeSchema = z.object({
+    agentId: z.string().optional(),
+    resources: resourcesSchema.optional(),
+    rationale: z.string().optional(),
+});
+export function defaultAdHocResources(policy) {
+    return policy ? { cpu: Math.min(4, policy.perStep.maxCpu), memoryGb: Math.min(8, policy.perStep.maxMemoryGb) } : { cpu: 4, memoryGb: 8 };
+}
+export function validAdHocResources(value, policy) {
+    const parsed = resourcesSchema.safeParse(value);
+    if (!parsed.success)
+        return null;
+    const r = parsed.data;
+    const maxCpu = policy?.perStep.maxCpu ?? 4;
+    const maxMemoryGb = policy?.perStep.maxMemoryGb ?? 8;
+    const maxGpuCount = policy?.perStep.maxGpuCount ?? 0;
+    if (r.cpu > maxCpu || r.memoryGb > maxMemoryGb || (r.gpu?.count ?? 0) > maxGpuCount)
+        return null;
+    return r;
+}
+function resourceBounds(policy) {
+    const defaults = defaultAdHocResources(policy);
+    if (!policy) {
+        return `CPU range 1..${defaults.cpu}; default ${defaults.cpu}. Memory range 1..${defaults.memoryGb} GB; default ${defaults.memoryGb}. GPU range 0..0.`;
+    }
+    const { perStep } = policy;
+    return [
+        `CPU range ${Math.min(1, perStep.maxCpu)}..${perStep.maxCpu}; default ${defaults.cpu}.`,
+        `Memory range ${Math.min(1, perStep.maxMemoryGb)}..${perStep.maxMemoryGb} GB; default ${defaults.memoryGb}.`,
+        `GPU range 0..${perStep.maxGpuCount}; omit gpu unless required.`,
+    ].join(" ");
+}
+async function profileOrientation(pool, analysisId, logger) {
+    try {
+        const status = unwrapOrThrow(await loadDataProfileStatus(pool, analysisId));
+        if (!status?.result)
+            return "No persisted data-profile facts are available.";
+        return buildDataProfileOrientation(status.result, DATA_PROFILE_ORIENTATION_MAX_CHARS);
+    }
+    catch (error) {
+        logger.warn("could not load data profile for ad hoc routing", { error: error instanceof Error ? error.message : String(error) });
+        return "The persisted data profile could not be loaded; route from the request alone.";
+    }
+}
+function routeTool() {
+    return {
+        submit_route: aiTool({
+            description: "Submit the single specialist and resource recommendation. This is the only valid response.",
+            inputSchema: jsonSchema(z.toJSONSchema(routeSchema)),
+        }),
+    };
+}
+export async function routeAdHocRequest(deps, input) {
+    const logger = (deps.logger ?? createNoopLogger()).named("adhoc-router").with({ analysisId: input.analysisId, model: deps.model });
+    const catalog = PLANNABLE_AGENT_CATALOG.map((agent) => `- ${agent.id}: capabilities [${agent.capabilities.join(", ")}]; suitable for [${agent.suitableFor.join(", ")}]`).join("\n");
+    const orientation = await profileOrientation(deps.pool, input.analysisId, logger);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error("ad hoc routing timed out")), deps.timeoutMs ?? AD_HOC_ROUTER_TIMEOUT_MS);
+    const signal = AbortSignal.any([input.signal, controller.signal]);
+    let raw;
+    let failure;
+    try {
+        const response = unwrapOrThrow(await deps.provider.chat({
+            system: [
+                "Select exactly one specialist for a targeted one-step analysis and estimate its sandbox resources.",
+                "Choose only from the supplied catalog. Do not create a plan, reject the request, or select scientific-executor.",
+                resourceEstimationSection(deps.resourcePolicy),
+                resourceBounds(deps.resourcePolicy),
+                "Respond only by calling submit_route.",
+            ].join("\n\n"),
+            messages: [
+                {
+                    role: "user",
+                    content: `Request:\n${input.request}\n\nPersisted data-profile orientation:\n${orientation}\n\nEligible specialists:\n${catalog}`,
+                },
+            ],
+            tools: routeTool(),
+            toolChoice: { type: "tool", toolName: "submit_route" },
+        }, forSubAgent(input.session, AD_HOC_ROUTER_AGENT_ID), signal));
+        const call = Array.isArray(response.message.content)
+            ? response.message.content.find((part) => part.type === "tool-call" && part.toolName === "submit_route")
+            : undefined;
+        raw = call?.input;
+        if (!call)
+            failure = "malformed";
+    }
+    catch (error) {
+        if (input.signal.aborted)
+            throw error;
+        failure = controller.signal.aborted && !input.signal.aborted ? "timeout" : "provider_error";
+        logger.warn("ad hoc route fell back", { failure, error: error instanceof Error ? error.message : String(error) });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const candidate = raw !== null && typeof raw === "object" ? raw : {};
+    const requestedAgent = typeof candidate.agentId === "string" ? candidate.agentId : undefined;
+    const validAgent = requestedAgent !== undefined && PLANNABLE_AGENT_CATALOG.some((agent) => agent.id === requestedAgent);
+    const agentId = validAgent ? requestedAgent : AD_HOC_FALLBACK_AGENT_ID;
+    if (!failure && !requestedAgent)
+        failure = "no_match";
+    if (!failure && !validAgent)
+        failure = "invalid_agent";
+    const validResources = validAdHocResources(candidate.resources, deps.resourcePolicy);
+    const resources = validResources ?? defaultAdHocResources(deps.resourcePolicy);
+    if (!validResources && candidate.resources !== undefined && !failure)
+        failure = "invalid_resources";
+    const rationale = typeof candidate.rationale === "string" && candidate.rationale.trim()
+        ? candidate.rationale.trim()
+        : failure
+            ? `Deterministic fallback: ${failure}`
+            : `Selected ${agentId}`;
+    logger.info("ad hoc route selected", { agentId, resources, rationale, failure });
+    return { agentId, resources, rationale, ...(failure ? { fallbackClass: failure } : {}) };
+}

package/dist/tools/analysis-invocation.d.ts

@@ -0,0 +1,4 @@
+/** Deterministic internal plan id in the existing persistence shape. */
+export declare function adHocPlanId(analysisId: string, invocationId: string): string;
+/** Deterministic RFC-4122 UUID used as both cortex run id and DBOS workflow id. */
+export declare function adHocRunId(analysisId: string, invocationId: string): string;

package/dist/tools/analysis-invocation.js

@@ -0,0 +1,17 @@
+import { createHash } from "node:crypto";
+const TOOL_ID = "execute_analysis";
+function digest(analysisId, invocationId) {
+    return createHash("sha256").update(`${TOOL_ID}\0${analysisId}\0${invocationId}`, "utf8").digest();
+}
+/** Deterministic internal plan id in the existing persistence shape. */
+export function adHocPlanId(analysisId, invocationId) {
+    return `pln-${digest(analysisId, invocationId).toString("hex", 0, 4)}`;
+}
+/** Deterministic RFC-4122 UUID used as both cortex run id and DBOS workflow id. */
+export function adHocRunId(analysisId, invocationId) {
+    const bytes = Buffer.from(digest(analysisId, invocationId).subarray(4, 20));
+    bytes[6] = (bytes[6] & 0x0f) | 0x50;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = bytes.toString("hex");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/dist/tools/define-tool.d.ts

@@ -8,7 +8,7 @@
  * captures its deps and calls `defineTool`.
  *
  * `ToolContext` carries only request-scoped values every tool may need
- * (`session`, `signal`, `emit`, `runStep`, `ask`) — no pool, no sandbox, no
+ * (`invocationId`, `session`, `signal`, `emit`, `runStep`, `ask`) — no pool, no sandbox, no
  * logger. The error contract: an expected
  * outcome ("not found", "no results") stays in the ok channel as a data
  * variant (`ok({ found: false })`); an unexpected failure is an `err(ToolError)`
@@ -39,11 +39,15 @@ export type ToolExecutionMode = "step" | "workflow" | "inline";
 export declare function isToolError(value: unknown): value is ToolError;
 /**
  * The request-scoped values passed to every tool's `execute`. No injected
- * dependencies (see the harness-durable-runtime spec) — `session`, `signal`, `emit`, the `runStep`
+ * dependencies (see the harness-durable-runtime spec) — invocation identity,
+ * `session`, `signal`, `emit`, the `runStep`
  * durability seam (`passthroughStep` in chat, `DBOS.runStep` in workflows) a
  * tool uses to wrap its own durable work, and the `ask` user-approval seam.
  */
 export interface ToolContext {
+    /** Stable identity of this AI SDK tool call. Redelivery preserves it; a new
+     * model-issued call receives a new value. */
+    readonly invocationId: string;
     readonly session: AgentSession;
     readonly signal: AbortSignal;
     readonly emit: EmitFn;

package/dist/tools/define-tool.js

@@ -8,7 +8,7 @@
  * captures its deps and calls `defineTool`.
  *
  * `ToolContext` carries only request-scoped values every tool may need
- * (`session`, `signal`, `emit`, `runStep`, `ask`) — no pool, no sandbox, no
+ * (`invocationId`, `session`, `signal`, `emit`, `runStep`, `ask`) — no pool, no sandbox, no
  * logger. The error contract: an expected
  * outcome ("not found", "no results") stays in the ok channel as a data
  * variant (`ok({ found: false })`); an unexpected failure is an `err(ToolError)`

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

@@ -0,0 +1,43 @@
+/**
+ * Unified async edge for approved plans and explicitly requested one-step ad
+ * hoc analyses. Both modes launch the ordinary executeAnalysis workflow.
+ */
+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 { Logger } from "../lib/logger.js";
+import type { ChatProvider } from "../providers/types.js";
+import { type AnalysisPlan } from "../schemas/workflow-state.js";
+import type { ExecuteAnalysisInput, ExecuteAnalysisResult } from "../workflows/execute-analysis.js";
+import { type AdHocRoute } from "./ad-hoc-router.js";
+type ExecuteAnalysisWorkflow = (input: ExecuteAnalysisInput) => Promise<ExecuteAnalysisResult>;
+export interface ExecuteAnalysisToolDeps {
+    readonly pool: Pool;
+    readonly executeAnalysisWorkflow: ExecuteAnalysisWorkflow;
+    readonly runAuthorizer: RunAuthorizer;
+    readonly runLauncher: RunLauncher;
+    readonly resourcePolicy?: ResourcePolicy;
+    readonly utilityProvider: ChatProvider;
+    readonly utilityModel: string;
+    readonly logger?: Logger;
+}
+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 buildAdHocPlan(request: string, route: AdHocRoute, createdAt?: string): AnalysisPlan;
+export declare function createExecuteAnalysisTool(deps: ExecuteAnalysisToolDeps): import("./define-tool.js").Tool<{
+    mode: "plan" | "adhoc";
+    planId?: string | undefined;
+    request?: string | undefined;
+}, {
+    runId: string;
+}>;
+export {};

package/dist/tools/execute-analysis.js

@@ -0,0 +1,252 @@
+/**
+ * Unified async edge for approved plans and explicitly requested one-step ad
+ * hoc analyses. Both modes launch the ordinary executeAnalysis workflow.
+ */
+import { randomUUID } from "node:crypto";
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { SANDBOX_AGENT_META } from "../agents/sandbox/index.js";
+import { DEFAULT_SANDBOX_MAX_STEPS } from "../config/resource-limits.js";
+import { createNoopLogger } from "../lib/console-logger.js";
+import { unwrapOrThrow } from "../lib/result.js";
+import { buildRunCardData } from "../memory/card-builders.js";
+import { AnalysisPlanSchema } from "../schemas/workflow-state.js";
+import { validatePlan } from "../schemas/validate-plan.js";
+import { RunDedupCollisionError, insertRun, loadPlan, queryActiveRun, reserveRunById, updateRunStatus, upsertPlan } from "../state/index.js";
+import { routeAdHocRequest } from "./ad-hoc-router.js";
+import { adHocPlanId, adHocRunId } from "./analysis-invocation.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({
+    mode: z.enum(["plan", "adhoc"]),
+    planId: planIdSchema.optional(),
+    request: z.string().min(1).optional(),
+})
+    .superRefine((value, ctx) => {
+    if (value.mode === "plan" && (value.planId === undefined || value.request !== undefined)) {
+        ctx.addIssue({ code: "custom", message: "plan mode requires planId and forbids request" });
+    }
+    if (value.mode === "adhoc" && (value.request === undefined || value.planId !== undefined)) {
+        ctx.addIssue({ code: "custom", message: "adhoc mode requires request and forbids planId" });
+    }
+});
+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");
+}
+function planSummary(plan) {
+    return plan.title?.trim() || plan.analytical_narrative.trim().slice(0, 280);
+}
+function workflowInput(planId, plan, args) {
+    return {
+        analysisId: args.analysisId,
+        planId,
+        planSummary: planSummary(plan),
+        threadId: args.threadId,
+        steps: plan.steps.map((step) => ({ id: step.id, depends_on: step.depends_on ?? [] })),
+        planStepById: Object.fromEntries(plan.steps.map((step) => [step.id, step])),
+        agentByStepId: Object.fromEntries(plan.steps.map((step) => [step.id, step.agent ?? "unknown"])),
+        resourcesByStepId: Object.fromEntries(plan.steps.map((step) => {
+            if (!step.resources)
+                throw new Error(`Step "${step.id}" has no resources — validation should have rejected it`);
+            return [step.id, step.resources];
+        })),
+        timeoutByStepId: Object.fromEntries(plan.steps.filter((step) => step.timeout !== undefined).map((step) => [step.id, step.timeout])),
+        budget: args.budget,
+        runSession: args.runSession,
+        ownsMandate: args.ownsMandate,
+        synthesisEnabled: args.synthesisEnabled,
+    };
+}
+function validateStoredPlan(raw, planId) {
+    const parsed = AnalysisPlanSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new PlanMalformedError(planId);
+    const result = validatePlan(parsed.data);
+    if (!result.valid)
+        throw new PlanValidationError(planId, result.errors);
+    return parsed.data;
+}
+function adHocTitle(request) {
+    const compact = request.trim().replace(/\s+/g, " ");
+    return compact.length <= 80 ? compact : `${compact.slice(0, 77)}…`;
+}
+export function buildAdHocPlan(request, route, createdAt = new Date().toISOString()) {
+    const meta = SANDBOX_AGENT_META[route.agentId];
+    const plan = {
+        title: adHocTitle(request),
+        analytical_narrative: `Execute one targeted analysis step for the explicit request: ${request}`,
+        created_at: createdAt,
+        steps: [
+            {
+                id: "T1S1",
+                name: "Ad hoc analysis",
+                track: "ad-hoc",
+                step_type: "analysis",
+                question: request,
+                context: `Automatically routed to ${route.agentId}. Routing rationale: ${route.rationale}`,
+                constraints: [
+                    "Use the staged analysis inputs and persisted data profile; do not invent missing data.",
+                    "Complete only this targeted request; do not expand it into a multi-step plan.",
+                ],
+                acceptance_criteria: [
+                    "Persist every script needed to reproduce the computation.",
+                    "Persist machine-readable result file(s), even when the answer is a single scalar.",
+                    "Provide a direct result summary grounded in the persisted outputs.",
+                ],
+                caveats: route.fallbackClass ? [`Automatic routing fallback: ${route.fallbackClass}`] : undefined,
+                depends_on: [],
+                status: "pending",
+                resources: route.resources,
+                agent: route.agentId,
+                maxSteps: meta?.defaultMaxSteps ?? DEFAULT_SANDBOX_MAX_STEPS,
+            },
+        ],
+    };
+    return AnalysisPlanSchema.parse(plan);
+}
+async function persistedAdHocPlan(deps, args) {
+    const existing = unwrapOrThrow(await loadPlan(deps.pool, args.planId, { analysisId: args.analysisId }));
+    if (existing)
+        return validateStoredPlan(existing, args.planId);
+    const route = await routeAdHocRequest({
+        provider: deps.utilityProvider,
+        model: deps.utilityModel,
+        pool: deps.pool,
+        resourcePolicy: deps.resourcePolicy,
+        logger: deps.logger,
+    }, { analysisId: args.analysisId, request: args.request, session: args.ctx.session, signal: args.ctx.signal });
+    const candidate = buildAdHocPlan(args.request, route);
+    unwrapOrThrow(await upsertPlan(deps.pool, { planId: args.planId, analysisId: args.analysisId, plan: candidate }));
+    const stored = unwrapOrThrow(await loadPlan(deps.pool, args.planId, { analysisId: args.analysisId }));
+    if (!stored)
+        throw new Error(`Internal ad hoc plan ${args.planId} could not be reloaded`);
+    return validateStoredPlan(stored, args.planId);
+}
+export function createExecuteAnalysisTool(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("execute-analysis-tool");
+    return defineTool({
+        id: "execute_analysis",
+        description: "Launch analysis computation asynchronously. Use mode=plan with the planId only after the user approved that stored plan. " +
+            "Use mode=adhoc with the user's exact targeted computational request when they explicitly asked to run/compute/test/compare it; " +
+            "that explicit request is consent and needs no synthetic-plan approval. If computation is merely your suggestion, ask first. " +
+            "You never choose the sandbox specialist: ad hoc routing does that automatically. Returns runId; inspect results on a later turn.",
+        inputSchema,
+        execute: async (input, ctx) => {
+            if (ctx.session.scope.kind !== "analysis")
+                throw new Error("execute_analysis requires an analysis-scoped session");
+            if (!ctx.session.auth)
+                throw new Error("execute_analysis: session is missing its auth capability");
+            const analysisId = ctx.session.scope.analysisId;
+            const threadId = ctx.session.scope.threadId ?? null;
+            const planId = input.mode === "plan" ? input.planId : adHocPlanId(analysisId, ctx.invocationId);
+            const emitRunCard = async (runId) => {
+                const card = await buildRunCardData(deps.pool, { planId, analysisId, runId }).unwrapOr(null);
+                if (card)
+                    await ctx.emit({ type: "data-run-card", source: ctx.session.provenance, data: card });
+            };
+            let plan;
+            if (input.mode === "plan") {
+                const raw = unwrapOrThrow(await loadPlan(deps.pool, planId, { analysisId }));
+                if (!raw)
+                    throw new PlanNotFoundError(planId);
+                plan = validateStoredPlan(raw, planId);
+                const active = unwrapOrThrow(await queryActiveRun(deps.pool, analysisId, planId));
+                if (active) {
+                    await emitRunCard(active.runId);
+                    return ok({ runId: active.runId });
+                }
+            }
+            else {
+                plan = await persistedAdHocPlan(deps, { analysisId, request: input.request, ctx, planId });
+            }
+            const runId = input.mode === "plan" ? randomUUID() : adHocRunId(analysisId, ctx.invocationId);
+            if (input.mode === "plan") {
+                try {
+                    unwrapOrThrow(await insertRun(deps.pool, {
+                        runId,
+                        analysisId,
+                        threadId,
+                        workflowName: "executeAnalysis",
+                        planId,
+                    }));
+                }
+                catch (error) {
+                    if (isDedupCollision(error)) {
+                        const active = unwrapOrThrow(await queryActiveRun(deps.pool, analysisId, planId));
+                        if (active) {
+                            await emitRunCard(active.runId);
+                            return ok({ runId: active.runId });
+                        }
+                    }
+                    throw error;
+                }
+            }
+            else {
+                const reservation = unwrapOrThrow(await reserveRunById(deps.pool, {
+                    runId,
+                    analysisId,
+                    threadId,
+                    workflowName: "executeAnalysis",
+                    planId,
+                }));
+                if (!reservation.inserted) {
+                    await emitRunCard(reservation.row.runId);
+                    return ok({ runId: reservation.row.runId });
+                }
+            }
+            let authorization;
+            try {
+                authorization = await deps.runAuthorizer.authorize({
+                    auth: ctx.session.auth,
+                    scope: ctx.session.scope,
+                    provenance: ctx.session.provenance,
+                    frame: { runId },
+                });
+            }
+            catch (error) {
+                await updateRunStatus(deps.pool, runId, "failed", "run authorization failed").match(() => { }, () => { });
+                throw error;
+            }
+            const wfInput = workflowInput(planId, plan, {
+                analysisId,
+                threadId,
+                runSession: authorization.runSession,
+                ownsMandate: authorization.ownsMandate,
+                budget: deps.resourcePolicy?.budget,
+                synthesisEnabled: input.mode === "plan",
+            });
+            try {
+                await deps.runLauncher.launch(deps.executeAnalysisWorkflow, { workflowId: runId }, wfInput);
+            }
+            catch (error) {
+                await deps.runAuthorizer.revoke(authorization, "workflow-start-failed").catch(() => { });
+                await updateRunStatus(deps.pool, runId, "failed", "workflow start failed").match(() => { }, () => { });
+                throw error;
+            }
+            logger.info("analysis launched", { analysisId, runId, planId, mode: input.mode });
+            await emitRunCard(runId);
+            return ok({ runId });
+        },
+    });
+}

package/dist/tools/iterate-report.js

@@ -130,7 +130,7 @@ const intentField = () => z
     .describe("Why this section exists and what to emphasize (e.g. 'hero — headline " +
     "finding', 'downplay if space is tight'). Emphasis, not layout — the " +
     "builder picks the components, sizing and alternation.");
-/** Free-text row transform — the reason to never pre-slice a CSV with `run_ephemeral`. */
+/** Free-text row transform — the reason to avoid launching analysis just to pre-slice a CSV. */
 const transformField = () => z
     .string()
     .optional()
@@ -138,7 +138,7 @@ const transformField = () => z
     "asset — filter, derive, aggregate, sort (e.g. 'filter padj < 0.05 and " +
     "abs(log2FoldChange) > 1', 'compute -log10(padj) as neg_log_padj', 'group " +
     "by sample and sum count', 'sort by mean_count desc, take top 50'). Use " +
-    "this instead of running `run_ephemeral` to pre-slice the file. The text " +
+    "this instead of launching an ad hoc analysis to pre-slice the file. The text " +
     "is rendered verbatim as a provenance footnote, so the data reads as " +
     "processed, not fabricated.");
 const SectionSchema = z.discriminatedUnion("type", [
@@ -359,14 +359,15 @@ treatment. Pass the composed brief as \`submit_report\`'s \`report\` field.
   their content reaches the report as prose you write into \`narrative\` /
   \`methods\` sections.
 
-## Do NOT reach for run_ephemeral first
+## Do NOT launch ad hoc analysis for a section transform
 - Not to peek at a CSV — pre-flight already parsed its columns and head rows.
 - Not to filter, slice, rank, or derive columns from a single CSV about to be
   rendered — \`chart.content.transform\` and \`table.content.transform\` do exactly
   that client-side, and the transform text renders as a provenance footnote.
-- run_ephemeral is only for computation no single section transform covers:
-  cross-file aggregation, statistics needing a real numerical library, or a
-  derived CSV the report then lists as a fresh source.
+- A durable ad hoc analysis is appropriate only when the user explicitly asks
+  for computation no single section transform covers: cross-file aggregation,
+  statistics needing a real numerical library, or a derived CSV the report then
+  lists as a fresh source.
 
 ## Choosing a section type
 - narrative — prose you wrote: context, story, interpretation.

package/dist/tools/research/generate-plan.js

@@ -420,7 +420,7 @@ export function createGeneratePlanTool(deps) {
             "to the planner directly. Do NOT summarize or re-type them into this call; you cannot restate that " +
             "record more faithfully than the record itself. Pass only what the profile cannot hold: the research " +
             "question, facts the user told you (analystNotes), prior run results, and their constraints. " +
-            "Returns a structured plan ready for show_plan and execute_plan, or a clarification question if " +
+            "Returns a structured plan ready for show_plan and execute_analysis plan mode, or a clarification question if " +
             "the planner is missing something it cannot infer.",
         inputSchema: z.object({
             researchQuestion: z.string().describe("What the user wants to analyze — their goal and specific questions."),

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

@@ -115,6 +115,11 @@ export interface ExecuteAnalysisInput {
      * dependency-satisfied step starts immediately — the legacy fan-out.
      */
     readonly budget?: MachineBudget;
+    /**
+     * Replay-stable run-level synthesis decision. Absent preserves the legacy
+     * behavior for workflows persisted before this field existed.
+     */
+    readonly synthesisEnabled?: boolean;
     /**
      * Durable `RunSession` minted at the async edge by `executePlan`.
      * Carries the run-authorization credential, identity, scope, and `runFrame.runId`.
@@ -230,11 +235,6 @@ export interface ExecuteAnalysisDeps {
     readonly bioKeys: BioToolKeys;
     /** Run-level billing-bracket seam (managed: external bracket; OSS: no-op). */
     readonly runCharge: RunCharge;
-    /**
-     * When false, skip run-level synthesis entirely (findings stay empty).
-     * Config, not a seam. Defaults to true.
-     */
-    readonly synthesisEnabled?: boolean;
     /** Run-authorization seam — the terminal path revokes through `revoke`. */
     readonly runAuthorizer: RunAuthorizer;
     /**

package/dist/workflows/execute-analysis.js

@@ -342,7 +342,7 @@ export async function runExecuteAnalysisBody(input, deps) {
     // `pending` and the terminal sweep finalizes it to `skipped` — honest
     // ("never ran, never will"), like any never-dispatched DAG step. Its wave
     // sits after every DAG level so ledger-ordered readers render it last.
-    const synthesisEnabled = deps.synthesisEnabled ?? true;
+    const synthesisEnabled = input.synthesisEnabled ?? true;
     const synthesisWave = Math.max(-1, ...levels.values()) + 1;
     await DBOS.runStep(async () => {
         const dagRows = input.steps.map((step) => ({
@@ -403,10 +403,8 @@ export async function runExecuteAnalysisBody(input, deps) {
         // recovered replay reuses the original instants (same rule as `startedAtMs`).
         const synthStartedAtMs = await DBOS.now();
         // Mark the seeded `synthesis` row running. The same upsert the DAG children
-        // use: it stamps started_at, and it CREATES the row outright when the seed
-        // never carried it (synthesisEnabled flipped true across a recovery
-        // redeploy) — the mark self-heals rather than trusting the seed's snapshot
-        // of the config. Log-don't-fail: a progress row must never fail an
+        // use: it stamps started_at, and it creates the row outright if a legacy
+        // persisted input did not seed it. Log-don't-fail: a progress row must never fail an
         // otherwise-healthy run. Cancellation still re-propagates — it is not a
         // write failure, and swallowing it here would only defer it one operation.
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.12.0",
+    "version": "0.13.0",
     "description": "Host-agnostic bioinformatics agent harness \u2014 hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",

package/dist/agents/sandbox/ephemeral-executor.d.ts

@@ -1,9 +0,0 @@
-/**
- * Ephemeral Executor — read-only sandbox agent for quick computations.
- * Cannot create files; step conventions don't apply.
- */
-import type { AgentDefinition } from "../../loop/types.js";
-import { type SandboxAgentDeps } from "./shared.js";
-import type { AgentMeta } from "./types.js";
-export declare const meta: AgentMeta;
-export declare function createEphemeralExecutorAgent(deps: SandboxAgentDeps): AgentDefinition;

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