@inflexa-ai/harness 0.43.1 → 0.45.0

package/dist/tools/execute-analysis.js

@@ -3,7 +3,7 @@
  * hoc analyses. Both modes launch the ordinary executeAnalysis workflow.
  */
 import { randomUUID } from "node:crypto";
-import { err, ok } from "neverthrow";
+import { err, ok, ResultAsync } 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";
@@ -103,9 +103,9 @@ export class PlanPackagesMissingError extends Error {
  * is what the launch record must carry to tell a checked launch from an
  * unchecked one.
  */
-async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
+async function linkPlanPackages(extendAnalysisFarm, analysisId, planId, plan) {
     if (!extendAnalysisFarm)
-        return 0;
+        return ok(0);
     // The union dedupes EQUAL queries only: two entries are one ask when their
     // spelling, their track, and their version are equal. A bare entry beside a
     // qualified entry of one spelling stays two asks, because the bare one
@@ -118,7 +118,12 @@ async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
             if (parsed.isErr()) {
                 // `validatePlan` parsed every entry of this plan already, thus a
                 // refusal here means that the two readers disagree.
-                throw new Error(`Step "${step.id}" carries the package entry "${entry}", which the plan validation should have refused`);
+                return err({
+                    type: "plan_invalid",
+                    planId,
+                    malformed: false,
+                    errors: [`Step "${step.id}" carries the package entry "${entry}", which the plan validation should have refused`],
+                });
             }
             const query = parsed.value;
             const key = formatQuery(query);
@@ -128,12 +133,12 @@ async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
     }
     const queries = [...union.values()];
     if (queries.length === 0)
-        return 0;
+        return ok(0);
     const linked = await callExtendAnalysisFarm(extendAnalysisFarm, analysisId, queries);
     if (linked.isErr()) {
         // A call that gave no answer is an `unavailable` answer, not a driver
         // error: the planner can act on "the store cannot answer".
-        throw new PlanPackagesMissingError([], [], linked.error);
+        return err({ type: "packages_missing", missing: [], collisions: [], unavailable: linked.error });
     }
     const outcomes = linked.value;
     // An `unavailable` outcome preempts everything: the link pass could not
@@ -141,7 +146,7 @@ async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
     // absence list would be a fabrication. One reason covers the batch.
     const unavailable = outcomes.find((o) => o.kind === "unavailable");
     if (unavailable !== undefined) {
-        throw new PlanPackagesMissingError([], [], unavailable.reason);
+        return err({ type: "packages_missing", missing: [], collisions: [], unavailable: unavailable.reason });
     }
     // A seam-supplied detail classifies the miss in host terms (in flight,
     // failed with its reason, never requested), and it rides beside the name
@@ -165,13 +170,32 @@ async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
         `; when the two directories are one spelling in two tracks, name the track in the plan, as ` +
         `${formatQuery({ spelling: o.spelling, track: "python" })} or ${formatQuery({ spelling: o.spelling, track: "r" })}`);
     if (missing.length > 0 || collisions.length > 0) {
-        throw new PlanPackagesMissingError(missing, collisions);
+        return err({ type: "packages_missing", missing, collisions });
     }
-    return queries.length;
+    return ok(queries.length);
 }
 function planSummary(plan) {
     return plan.title?.trim() || plan.analytical_narrative.trim().slice(0, 280);
 }
+/**
+ * The resources of each step. `validatePlan` refuses a step without them, thus
+ * a missing entry here means that the two readers disagree.
+ */
+function stepResources(planId, plan) {
+    const byStepId = {};
+    for (const step of plan.steps) {
+        if (!step.resources) {
+            return err({
+                type: "plan_invalid",
+                planId,
+                malformed: false,
+                errors: [`Step "${step.id}" has no resources — validation should have rejected it`],
+            });
+        }
+        byStepId[step.id] = step.resources;
+    }
+    return ok(byStepId);
+}
 function workflowInput(planId, plan, args) {
     return {
         analysisId: args.analysisId,
@@ -181,11 +205,7 @@ function workflowInput(planId, plan, args) {
         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];
-        })),
+        resourcesByStepId: args.resourcesByStepId,
         timeoutByStepId: Object.fromEntries(plan.steps.filter((step) => step.timeout !== undefined).map((step) => [step.id, step.timeout])),
         budget: args.budget,
         runSession: args.runSession,
@@ -193,14 +213,21 @@ function workflowInput(planId, plan, args) {
         synthesisEnabled: args.synthesisEnabled,
     };
 }
-function validateStoredPlan(raw, planId) {
+function parseStoredPlan(raw, planId) {
     const parsed = AnalysisPlanSchema.safeParse(raw);
     if (!parsed.success)
-        throw new PlanMalformedError(planId);
+        return err({ type: "plan_invalid", planId, malformed: true, errors: [] });
     const result = validatePlan(parsed.data);
     if (!result.valid)
-        throw new PlanValidationError(planId, result.errors);
-    return parsed.data;
+        return err({ type: "plan_invalid", planId, malformed: false, errors: result.errors });
+    return ok(parsed.data);
+}
+/** The error that a tool body throws for a stored plan that the parse refused. */
+function validateStoredPlan(raw, planId) {
+    const parsed = parseStoredPlan(raw, planId);
+    if (parsed.isErr())
+        return throwLaunchRefusal(parsed.error);
+    return parsed.value;
 }
 function adHocTitle(request) {
     const compact = request.trim().replace(/\s+/g, " ");
@@ -320,8 +347,181 @@ async function persistedAdHocPlan(deps, args) {
         throw new Error(`Internal ad hoc plan ${args.planId} could not be reloaded`);
     return validateStoredPlan(stored, args.planId);
 }
-export function createExecuteAnalysisTool(deps) {
+/**
+ * The half of a launch that the plan mode and the ad hoc mode share: the link pass, the reservation,
+ * the authorization, and the workflow start. It gives each outcome as a `Result`.
+ */
+async function launchReservedRun(deps, args) {
     const logger = (deps.logger ?? createNoopLogger()).named("execute-analysis-tool");
+    const { session, planId, plan } = args;
+    const analysisId = session.scope.analysisId;
+    const threadId = session.scope.threadId ?? null;
+    const resources = stepResources(planId, plan);
+    if (resources.isErr())
+        return err(resources.error);
+    // The link pass comes before the run reserves anything, thus a pool
+    // miss leaves no run row and no revoked authorization behind.
+    const linked = await linkPlanPackages(deps.extendAnalysisFarm, analysisId, planId, plan);
+    if (linked.isErr())
+        return err(linked.error);
+    const packageQueries = linked.value;
+    const reservation = await args.reserve({ analysisId, threadId });
+    if (reservation.isErr())
+        return err(reservation.error);
+    if (!reservation.value.started)
+        return reservation;
+    const runId = reservation.value.runId;
+    const authorized = await passGate("RunAuthorizer.authorize", deps.runAuthorizer.authorize({
+        auth: session.auth,
+        scope: session.scope,
+        provenance: session.provenance,
+        frame: { runId },
+    }));
+    if (authorized.isErr()) {
+        // The refusal ends the run before a workflow exists, thus the
+        // reserved row must not stay `running`.
+        const { kind, reason } = authorized.error;
+        if (kind === "suspended") {
+            await updateRunStatus(deps.pool, runId, "suspended_insufficient_funds", reason).match(() => { }, () => { });
+            const suspension = await suspendAnalysis(deps.pool, analysisId);
+            if (suspension.isErr())
+                return err({ type: "store_failed", cause: suspension.error });
+            return err({ type: "suspended", reason });
+        }
+        await updateRunStatus(deps.pool, runId, "failed", reason).match(() => { }, () => { });
+        return err({ type: "not_authorized", reason });
+    }
+    const authorization = authorized.value;
+    const wfInput = workflowInput(planId, plan, {
+        analysisId,
+        threadId,
+        runSession: authorization.runSession,
+        ownsMandate: authorization.ownsMandate,
+        budget: deps.resourcePolicy?.budget,
+        synthesisEnabled: args.mode === "plan",
+        resourcesByStepId: resources.value,
+    });
+    try {
+        await deps.runLauncher.launch(deps.executeAnalysisWorkflow, { workflowId: runId }, wfInput);
+    }
+    catch (cause) {
+        await deliverNotice(logger, "RunAuthorizer.revoke", deps.runAuthorizer.revoke(authorization, "workflow-start-failed"));
+        // A failed write leaves the row `running` with no workflow. The boot repair (`reconcileOrphanedRuns`) fails it.
+        await updateRunStatus(deps.pool, runId, "failed", "workflow start failed").match(() => { }, (error) => logger.warn("the failed status of a run whose start failed was not written", { runId, ...logger.errorFields(error) }));
+        return err({ type: "launch_failed", cause });
+    }
+    logger.info("analysis launched", { analysisId, runId, planId, mode: args.mode, packageQueries });
+    return ok({ runId, started: true });
+}
+/**
+ * Reserve a fresh run for a plan. A concurrent launch of the same plan holds the active-plan slot,
+ * and its run is the answer.
+ */
+async function reservePlanRun(deps, args) {
+    const runId = randomUUID();
+    try {
+        const inserted = await insertRun(deps.pool, {
+            runId,
+            analysisId: args.analysisId,
+            threadId: args.threadId,
+            workflowName: "executeAnalysis",
+            planId: args.planId,
+        });
+        if (inserted.isErr())
+            return err({ type: "store_failed", cause: inserted.error });
+        return ok({ runId, started: true });
+    }
+    catch (cause) {
+        // `insertRun` rejects its promise on a collision of the active-plan index, and on nothing else.
+        if (!isDedupCollision(cause))
+            return err({ type: "store_failed", cause });
+        const active = await queryActiveRun(deps.pool, args.analysisId, args.planId);
+        if (active.isErr())
+            return err({ type: "store_failed", cause: active.error });
+        // The slot was free again when the read ran, so no run holds it and the collision stays the cause.
+        if (!active.value)
+            return err({ type: "store_failed", cause });
+        return ok({ runId: active.value.runId, started: false });
+    }
+}
+/**
+ * Reserve the run of an ad hoc call under its deterministic id, and treat a reservation that exists
+ * as a redelivery of the same call.
+ */
+async function reserveAdHocRun(deps, args) {
+    try {
+        const reservation = await reserveRunById(deps.pool, {
+            runId: args.runId,
+            analysisId: args.analysisId,
+            threadId: args.threadId,
+            workflowName: "executeAnalysis",
+            planId: args.planId,
+        });
+        if (reservation.isErr())
+            return err({ type: "store_failed", cause: reservation.error });
+        return ok({ runId: reservation.value.row.runId, started: reservation.value.inserted });
+    }
+    catch (cause) {
+        // `reserveRunById` rejects its promise when the run id belongs to another analysis.
+        return err({ type: "store_failed", cause });
+    }
+}
+async function launchStoredPlan(deps, input) {
+    const { session, planId } = input;
+    const analysisId = session.scope.analysisId;
+    const raw = await loadPlan(deps.pool, planId, { analysisId });
+    if (raw.isErr())
+        return err({ type: "store_failed", cause: raw.error });
+    if (!raw.value)
+        return err({ type: "plan_not_found", planId });
+    const plan = parseStoredPlan(raw.value, planId);
+    if (plan.isErr())
+        return err(plan.error);
+    const active = await queryActiveRun(deps.pool, analysisId, planId);
+    if (active.isErr())
+        return err({ type: "store_failed", cause: active.error });
+    if (active.value)
+        return ok({ runId: active.value.runId, started: false });
+    return launchReservedRun(deps, {
+        session,
+        planId,
+        plan: plan.value,
+        mode: "plan",
+        reserve: (frame) => reservePlanRun(deps, { ...frame, planId }),
+    });
+}
+/**
+ * Start the run of a stored plan. It reads the plan under the analysis of the session, validates it,
+ * links its packages, reserves a run, authorizes it, and starts the workflow. It gives the run id, or
+ * the refusal, and it emits no chat part. `started` is false when a run of the plan was already active.
+ *
+ * This is an API boundary: a host calls it outside a tool body, thus no outcome above rejects the
+ * promise.
+ */
+export function launchPlanRun(deps, input) {
+    return new ResultAsync(launchStoredPlan(deps, input));
+}
+/** Throw the error that the tool body threw before the launch gave a `Result`. */
+function throwLaunchRefusal(refusal) {
+    switch (refusal.type) {
+        case "plan_not_found":
+            throw new PlanNotFoundError(refusal.planId);
+        case "plan_invalid":
+            throw refusal.malformed ? new PlanMalformedError(refusal.planId) : new PlanValidationError(refusal.planId, refusal.errors);
+        case "packages_missing":
+            throw new PlanPackagesMissingError(refusal.missing, refusal.collisions, refusal.unavailable);
+        case "store_failed":
+            return unwrapOrThrow(err(refusal.cause));
+        case "launch_failed":
+            // The cause is the value that the launcher threw, and the tool rethrows it unchanged.
+            throw refusal.cause;
+        default: {
+            const unreachable = refusal;
+            return unreachable;
+        }
+    }
+}
+export function createExecuteAnalysisTool(deps) {
     return defineTool({
         id: "execute_analysis",
         description: "Launch analysis computation asynchronously. Use mode=plan with the planId only after the user approved that stored plan. " +
@@ -340,104 +540,36 @@ export function createExecuteAnalysisTool(deps) {
             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, status: "in_progress" });
-                }
-            }
-            else {
-                plan = await persistedAdHocPlan(deps, { analysisId, request: input.request, ctx, planId });
-            }
-            // The link pass comes before the run reserves anything, thus a pool
-            // miss leaves no run row and no revoked authorization behind.
-            const packageQueries = await linkPlanPackages(deps.extendAnalysisFarm, analysisId, plan);
-            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, status: "in_progress" });
-                        }
-                    }
-                    throw error;
-                }
-            }
-            else {
-                const reservation = unwrapOrThrow(await reserveRunById(deps.pool, {
-                    runId,
-                    analysisId,
-                    threadId,
-                    workflowName: "executeAnalysis",
+            const launch = async () => {
+                if (input.mode === "plan")
+                    return launchPlanRun(deps, { session: ctx.session, planId });
+                const plan = await persistedAdHocPlan(deps, { analysisId, request: input.request, ctx, planId });
+                const runId = adHocRunId(analysisId, ctx.invocationId);
+                return launchReservedRun(deps, {
+                    session: ctx.session,
                     planId,
-                }));
-                if (!reservation.inserted) {
-                    await emitRunCard(reservation.row.runId);
-                    return ok({ runId: reservation.row.runId, status: "in_progress" });
-                }
-            }
-            const authorized = await passGate("RunAuthorizer.authorize", deps.runAuthorizer.authorize({
-                auth: ctx.session.auth,
-                scope: ctx.session.scope,
-                provenance: ctx.session.provenance,
-                frame: { runId },
-            }));
-            if (authorized.isErr()) {
-                // The refusal ends the run before a workflow exists, thus the
-                // reserved row must not stay `running`.
-                const { kind, reason } = authorized.error;
-                if (kind === "suspended") {
-                    await updateRunStatus(deps.pool, runId, "canceled", reason).match(() => { }, () => { });
-                    unwrapOrThrow(await suspendAnalysis(deps.pool, analysisId));
-                    return err({ error: `The analysis is suspended: ${reason}`, retryable: false });
-                }
-                await updateRunStatus(deps.pool, runId, "failed", reason).match(() => { }, () => { });
-                return err({ error: `The run was not authorized: ${reason}`, retryable: false });
-            }
-            const authorization = authorized.value;
-            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 deliverNotice(logger, "RunAuthorizer.revoke", deps.runAuthorizer.revoke(authorization, "workflow-start-failed"));
-                await updateRunStatus(deps.pool, runId, "failed", "workflow start failed").match(() => { }, () => { });
-                throw error;
+                    plan,
+                    mode: "adhoc",
+                    reserve: (frame) => reserveAdHocRun(deps, { ...frame, planId, runId }),
+                });
+            };
+            const launched = await launch();
+            if (launched.isErr()) {
+                const refusal = launched.error;
+                if (refusal.type === "suspended")
+                    return err({ error: `The analysis is suspended: ${refusal.reason}`, retryable: false });
+                if (refusal.type === "not_authorized")
+                    return err({ error: `The run was not authorized: ${refusal.reason}`, retryable: false });
+                return throwLaunchRefusal(refusal);
             }
-            logger.info("analysis launched", { analysisId, runId, planId, mode: input.mode, packageQueries });
-            await emitRunCard(runId);
-            return ok({ runId, status: "in_progress" });
+            await emitRunCard(launched.value.runId);
+            return ok({ runId: launched.value.runId, status: "in_progress" });
         },
     });
 }

package/dist/tools/report-session/derive-table.js

@@ -221,7 +221,7 @@ export function createDeriveTableTool(deps) {
             }
             let root;
             try {
-                root = deps.resolveWorkspaceRoot(analysisId);
+                root = await deps.resolveWorkspaceRoot(analysisId);
             }
             catch (cause) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });

package/dist/tools/report-session/examine-page.js

@@ -276,7 +276,7 @@ export function createExaminePageTool(deps) {
             const { threadId, analysisId } = opened.value;
             let root;
             try {
-                root = deps.resolveWorkspaceRoot(analysisId);
+                root = await deps.resolveWorkspaceRoot(analysisId);
             }
             catch (cause) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });

package/dist/tools/report-session/list-artifacts.js

@@ -170,11 +170,11 @@ export function createListPinnedArtifactsTool(deps) {
                 return ok({ outcome: "refused", refusal: opened.error });
             }
             const { threadId, analysisId, state } = opened.value;
-            // The seam signals an unresolvable resource by a throw. The listing still serves the path and
+            // The seam signals an unresolvable resource by a rejection. The listing still serves the path and
             // the file type of each entry, thus the fault costs the columns alone and never the whole call.
             let root;
             try {
-                root = deps.resolveWorkspaceRoot(analysisId);
+                root = await deps.resolveWorkspaceRoot(analysisId);
             }
             catch (cause) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });

package/dist/tools/report-session/preview-report.d.ts

@@ -139,7 +139,7 @@ export interface PreviewReportToolDeps {
     readonly makeResolver?: (scope: {
         analysisId: string;
         auth: AuthContext;
-    }) => ReferenceResolver;
+    }) => Promise<ReferenceResolver>;
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     readonly resolvePageAsset?: ResolvePageAsset;
     readonly makeSessionPages?: MakeSessionPagePublisher;

package/dist/tools/report-session/preview-report.js

@@ -165,8 +165,8 @@ async function resolveDocument(document, resolver, snapshot) {
 /**
  * Resolve the page root, stage each bound image and each manifest entry, and write the page.
  *
- * The workspace-root seam signals an unresolvable resource by a throw, thus the resolution sits inside
- * the protection and its throw becomes a value. Each `fs` call runs through `tryFsWrite`, the one
+ * The workspace-root seam signals an unresolvable resource by a rejection, thus the resolution sits inside
+ * the protection and its rejection becomes a value. Each `fs` call runs through `tryFsWrite`, the one
  * sanctioned `fs` guard, thus a genuine I/O fault becomes a value and a control-flow exception such as a
  * cancellation propagates.
  *
@@ -186,7 +186,7 @@ async function resolveDocument(document, resolver, snapshot) {
 async function renderToWorkspace(args) {
     let root;
     try {
-        root = args.resolveWorkspaceRoot(args.analysisId);
+        root = await args.resolveWorkspaceRoot(args.analysisId);
     }
     catch (cause) {
         return err({ kind: "fs", error: { type: "read_failed", op: "preview.resolveWorkspaceRoot", path: args.analysisId, cause } });
@@ -382,12 +382,12 @@ export function createPreviewReportTool(deps) {
             if (deps.makeResolver === undefined) {
                 return ok({ outcome: "resolver-unavailable" });
             }
-            // The resolver construction resolves the workspace root inside, and that seam throws on an
-            // unresolvable root. The guard turns the throw into a typed outcome that names the fault, thus a
+            // The resolver construction resolves the workspace root inside, and that seam rejects on an
+            // unresolvable root. The guard turns the rejection into a typed outcome that names the fault, thus a
             // control-flow exception propagates and the unresolvable root does not.
             let resolver;
             try {
-                resolver = deps.makeResolver({ analysisId, auth: ctx.session.auth });
+                resolver = await deps.makeResolver({ analysisId, auth: ctx.session.auth });
             }
             catch (cause) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });

package/dist/tools/report-session/record-version.d.ts

@@ -105,7 +105,7 @@ export interface RecordVersionToolDeps {
     readonly makeResolver?: (scope: {
         analysisId: string;
         auth: AuthContext;
-    }) => ReferenceResolver;
+    }) => Promise<ReferenceResolver>;
     /** The provenance seam; an unbound session emit emits nothing and the record runs the same. */
     readonly provenance?: ProvenanceSeam;
     readonly logger?: Logger;

package/dist/tools/report-session/record-version.js

@@ -86,7 +86,7 @@ async function pruneUnusedDerivations(args) {
     let root;
     let derivedDir;
     try {
-        root = args.resolveWorkspaceRoot(args.analysisId);
+        root = await args.resolveWorkspaceRoot(args.analysisId);
         derivedDir = resolvePath(root, reportSessionDerivedDir(args.threadId));
     }
     catch (cause) {
@@ -169,12 +169,12 @@ export function createRecordVersionTool(deps) {
             if (deps.makeResolver === undefined) {
                 return ok({ outcome: "resolver-unavailable" });
             }
-            // The resolver construction resolves the workspace root inside, and that seam throws on an
-            // unresolvable root. The guard turns the throw into a typed outcome that names the fault, thus a
+            // The resolver construction resolves the workspace root inside, and that seam rejects on an
+            // unresolvable root. The guard turns the rejection into a typed outcome that names the fault, thus a
             // control-flow exception propagates and the unresolvable root does not.
             let resolver;
             try {
-                resolver = deps.makeResolver({ analysisId, auth: ctx.session.auth });
+                resolver = await deps.makeResolver({ analysisId, auth: ctx.session.auth });
             }
             catch (cause) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...logger.errorFields(cause) });

package/dist/tools/research/inspect-data-profile.d.ts

@@ -161,7 +161,7 @@ interface FailedOutput {
 }
 export type InspectDataProfileOutput = OverviewOutput | GroupsOutput | FilesOutput | AbsentOutput | PendingOutput | FailedOutput;
 export declare function createInspectDataProfileTool(pool: Pool): import("../define-tool.js").Tool<{
-    scope?: "overview" | "groups" | "files" | undefined;
+    scope?: "groups" | "files" | "overview" | undefined;
     page?: number | undefined;
     pageSize?: number | undefined;
 }, InspectDataProfileOutput>;

package/dist/tools/research/inspect-run.d.ts

@@ -2,7 +2,7 @@
  * inspectRun — inspect workflow runs for the current analysis.
  *
  * Results are pull-only: workflows never append completion messages to a
- * conversation. List mode is active-first and paged. Targeted mode makes
+ * conversation. List mode puts the running runs first and is paged. Targeted mode makes
  * readiness explicit and can perform one bounded, abort-aware wait.
  */
 import type { Pool } from "pg";

package/dist/tools/research/inspect-run.js

@@ -2,7 +2,7 @@
  * inspectRun — inspect workflow runs for the current analysis.
  *
  * Results are pull-only: workflows never append completion messages to a
- * conversation. List mode is active-first and paged. Targeted mode makes
+ * conversation. List mode puts the running runs first and is paged. Targeted mode makes
  * readiness explicit and can perform one bounded, abort-aware wait.
  */
 import { setTimeout as sleep } from "node:timers/promises";
@@ -20,7 +20,7 @@ const systemClock = {
     wait: (ms, signal) => sleep(ms, undefined, { signal }),
 };
 function isTerminal(status) {
-    return status === "completed" || status === "partial" || status === "failed" || status === "canceled";
+    return status === "completed" || status === "partial" || status === "failed" || status === "canceled" || status === "suspended_insufficient_funds";
 }
 function formatRun(r, verbose, exposePaths = isTerminal(r.status)) {
     return {
@@ -98,10 +98,10 @@ export function createInspectRunTool(pool, clock = systemClock) {
     return defineTool({
         id: "inspect_run",
         description: "Inspect workflow runs for this analysis. A run never posts its completion into the conversation; this tool is how you read it. " +
-            "Without a runId, returns an active-first paged list (running, suspended, then terminal history) with total and hasMore. " +
-            "With a runId, returns the run, its steps, and an inspectionState: not_found; in_progress; suspended (the run does not progress until it is resumed); " +
+            "Without a runId, returns a paged list (running runs first, then each other run) with total and hasMore. " +
+            "With a runId, returns the run, its steps, and an inspectionState: not_found; in_progress; suspended (the host suspended the run, it does not progress, and a new run of the plan can start); " +
             "or terminal (run.status completed, partial, failed, or canceled). " +
-            "Output paths appear only on a terminal run: run.synthesisPath when synthesisStatus is produced, and the summaryPath of each step that ran. " +
+            "Output paths appear only on a suspended or terminal run: run.synthesisPath when synthesisStatus is produced, and the summaryPath of each step that ran. " +
             "For a user-directed check, waitForTerminalSeconds can wait once for 1-30 seconds; if the cutoff returns in_progress, stop polling for that turn. " +
             "A wait on the run that the caller itself runs inside returns at once with selfWaitPrevented. " +
             "Default response is lightweight — pass includeDiagnostics:true to add error/duration/retry telemetry.",
@@ -179,8 +179,8 @@ export function createInspectRunTool(pool, clock = systemClock) {
             if (run.status === "suspended_insufficient_funds") {
                 return ok({
                     inspectionState: "suspended",
-                    message: "This run is suspended and will not progress until it is resumed.",
-                    run: formatRun(run, verbose, false),
+                    message: "The host suspended this run. The run does not progress. A new run of the plan can start.",
+                    run: formatRun(run, verbose, true),
                     steps,
                     ...wait,
                 });

package/dist/tools/workspace/mutator.js

@@ -201,9 +201,9 @@ export function createSessionWorkspaceMutator(deps) {
             const scope = session.scope;
             if (scope.kind !== "analysis")
                 return { status: "out_of_scope", path };
-            // Throws on an unknown analysis — the loop's dispatch catch maps
+            // Rejects on an unknown analysis — the loop's dispatch catch maps
             // it to an error tool result, like any unexpected host failure.
-            const workspaceRoot = deps.resolveWorkspaceRoot(scope.analysisId);
+            const workspaceRoot = await deps.resolveWorkspaceRoot(scope.analysisId);
             const landed = await confinedWrite({
                 workspaceRoot,
                 analysisId: scope.analysisId,