@inflexa-ai/harness 0.43.1 → 0.45.0

package/dist/state/runs.d.ts

@@ -77,11 +77,33 @@ export declare function queryActiveRun(pool: Querier, analysisId: string, planId
  * analysis's live concurrency, not by its history, and a run leaves the set permanently when it
  * finishes.
  *
- * The status set is the one {@link queryActiveRun} uses — non-terminal means still running, or
- * suspended awaiting funds. Keep the two in step: a new non-terminal status added to one and not the
- * other makes a live run invisible to exactly one of its readers.
+ * The status set is the one {@link queryActiveRun} uses — non-terminal means `running`. Keep the two
+ * in step: a new non-terminal status added to one and not the other makes a live run invisible to
+ * exactly one of its readers.
  */
 export declare function queryActiveRunsByAnalysis(pool: Querier, analysisId: string): ResultAsync<CortexRunRow[], DbError>;
+/**
+ * How long a reserved run may wait for its workflow before {@link reconcileOrphanedRuns} fails it. A launch writes
+ * the workflow row seconds after the reservation, and the margin covers a slow authorization gate of a managed host.
+ */
+export declare const ORPHANED_RUN_GRACE_MS: number;
+/**
+ * Fail each `running` run that started before the grace and that has no DBOS workflow row, and give the ids of
+ * the runs that it failed.
+ *
+ * A launch reserves the run row, then starts the workflow. A host that dies between the two, or a start that throws
+ * while the following status write also fails, leaves a `running` row that no workflow will ever settle. That row
+ * holds the active-plan slot, thus each later launch of the plan answers `started: false` for a run that never
+ * started. Recovery cannot help, because no workflow row exists to recover.
+ *
+ * Only a run with no workflow row at all is failed. A run whose workflow exists, also a terminal one, is the
+ * workflow's to settle: a failed mark could misname a run that completed. Call it after `DBOS.launch()`, thus a
+ * recovered workflow is visible to the predicate.
+ */
+export declare function reconcileOrphanedRuns(pool: Querier, opts?: {
+    now?: number;
+    graceMs?: number;
+}): ResultAsync<string[], DbError>;
 export declare function updateRunStatus(pool: Querier, runId: string, status: "running" | "completed" | "partial" | "failed" | "canceled" | "suspended_insufficient_funds", error?: string | null): ResultAsync<void, DbError>;
 /**
  * Conditionally transition an ACTIVE run to `canceled`, stamping `completed_at`
@@ -99,6 +121,16 @@ export declare function queryRunsByAnalysis(pool: Querier, analysisId: string, {
     limit?: number;
     offset?: number;
 }): ResultAsync<CortexRunRow[], DbError>;
+/**
+ * The run ids of one plan of one analysis, newest start first, at most `limit`.
+ * The run id breaks a tie of start times, highest first. A plan with no run gives
+ * an empty list.
+ */
+export declare function queryRunIdsByPlan(pool: Querier, opts: {
+    analysisId: string;
+    planId: string;
+    limit: number;
+}): ResultAsync<string[], DbError>;
 /**
  * Read the analysis's non-terminal run activity without coupling it to a
  * conversation thread. The total is counted before the detail limit so a
@@ -106,8 +138,7 @@ export declare function queryRunsByAnalysis(pool: Querier, analysisId: string, {
  */
 export declare function queryNonTerminalRunsByAnalysis(pool: Querier, analysisId: string, limit?: number): ResultAsync<RunPage, DbError>;
 /**
- * Read one stable inspection page: running first, then suspended, then
- * terminal history. This is deliberately separate from
+ * Read one stable inspection page: running first, then each other run. This is deliberately separate from
  * {@link queryRunsByAnalysis}, whose chronological order is an embedder/UI
  * contract.
  */

package/dist/state/runs.js

@@ -132,7 +132,7 @@ export function queryActiveRun(pool, analysisId, planId) {
             FROM cortex_runs
             WHERE analysis_id = $1
               AND plan_id IS NOT DISTINCT FROM $2
-              AND status IN ('running','suspended_insufficient_funds')`,
+              AND status = 'running'`,
             values: [analysisId, planId],
         });
         const row = result.rows[0];
@@ -152,9 +152,9 @@ export function queryActiveRun(pool, analysisId, planId) {
  * analysis's live concurrency, not by its history, and a run leaves the set permanently when it
  * finishes.
  *
- * The status set is the one {@link queryActiveRun} uses — non-terminal means still running, or
- * suspended awaiting funds. Keep the two in step: a new non-terminal status added to one and not the
- * other makes a live run invisible to exactly one of its readers.
+ * The status set is the one {@link queryActiveRun} uses — non-terminal means `running`. Keep the two
+ * in step: a new non-terminal status added to one and not the other makes a live run invisible to
+ * exactly one of its readers.
  */
 export function queryActiveRunsByAnalysis(pool, analysisId) {
     return tryQuery("runs.queryActiveRunsByAnalysis", async () => {
@@ -164,16 +164,52 @@ export function queryActiveRunsByAnalysis(pool, analysisId) {
                    mandate_jti, mandate_expires_at, plan_id -- oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
             FROM cortex_runs
             WHERE analysis_id = $1
-              AND status IN ('running','suspended_insufficient_funds')
+              AND status = 'running'
             ORDER BY started_at DESC`,
             values: [analysisId],
         });
         return result.rows.map(mapRunRow);
     });
 }
+/**
+ * How long a reserved run may wait for its workflow before {@link reconcileOrphanedRuns} fails it. A launch writes
+ * the workflow row seconds after the reservation, and the margin covers a slow authorization gate of a managed host.
+ */
+export const ORPHANED_RUN_GRACE_MS = 5 * 60 * 1000;
+/**
+ * Fail each `running` run that started before the grace and that has no DBOS workflow row, and give the ids of
+ * the runs that it failed.
+ *
+ * A launch reserves the run row, then starts the workflow. A host that dies between the two, or a start that throws
+ * while the following status write also fails, leaves a `running` row that no workflow will ever settle. That row
+ * holds the active-plan slot, thus each later launch of the plan answers `started: false` for a run that never
+ * started. Recovery cannot help, because no workflow row exists to recover.
+ *
+ * Only a run with no workflow row at all is failed. A run whose workflow exists, also a terminal one, is the
+ * workflow's to settle: a failed mark could misname a run that completed. Call it after `DBOS.launch()`, thus a
+ * recovered workflow is visible to the predicate.
+ */
+export function reconcileOrphanedRuns(pool, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const before = new Date(now - (opts.graceMs ?? ORPHANED_RUN_GRACE_MS)).toISOString();
+    return tryMutation("runs.reconcileOrphanedRuns", async () => {
+        const result = await pool.query({
+            text: `UPDATE cortex_runs r
+            SET status = 'failed',
+                error = 'The workflow of the run never started.',
+                completed_at = $1
+            WHERE r.status = 'running'
+              AND r.started_at < $2
+              AND NOT EXISTS (SELECT 1 FROM dbos.workflow_status ws WHERE ws.workflow_uuid = r.run_id)
+            RETURNING r.run_id`,
+            values: [new Date(now).toISOString(), before],
+        });
+        return result.rows.map((row) => row.run_id);
+    });
+}
 export function updateRunStatus(pool, runId, status, error) {
     const now = new Date().toISOString();
-    const isTerminal = status === "completed" || status === "partial" || status === "failed" || status === "canceled";
+    const isTerminal = status === "completed" || status === "partial" || status === "failed" || status === "canceled" || status === "suspended_insufficient_funds";
     return tryMutation("runs.updateRunStatus", async () => {
         await pool.query({
             text: `UPDATE cortex_runs
@@ -198,7 +234,7 @@ export function markRunCanceledIfActive(pool, runId, reason) {
         const result = await pool.query({
             text: `UPDATE cortex_runs
             SET status = 'canceled', completed_at = $2, error = $3
-            WHERE run_id = $1 AND status IN ('running','suspended_insufficient_funds')`,
+            WHERE run_id = $1 AND status = 'running'`,
             values: [runId, now, reason],
         });
         return (result.rowCount ?? 0) > 0;
@@ -242,6 +278,23 @@ export function queryRunsByAnalysis(pool, analysisId, { limit = 50, offset = 0 }
         return result.rows.map(mapRunRow);
     });
 }
+/**
+ * The run ids of one plan of one analysis, newest start first, at most `limit`.
+ * The run id breaks a tie of start times, highest first. A plan with no run gives
+ * an empty list.
+ */
+export function queryRunIdsByPlan(pool, opts) {
+    return tryQuery("runs.queryRunIdsByPlan", async () => {
+        const result = await pool.query({
+            text: `SELECT run_id FROM cortex_runs
+            WHERE analysis_id = $1 AND plan_id = $2
+            ORDER BY started_at DESC, run_id DESC
+            LIMIT $3`,
+            values: [opts.analysisId, opts.planId, opts.limit],
+        });
+        return result.rows.map((row) => row.run_id);
+    });
+}
 /**
  * Read the analysis's non-terminal run activity without coupling it to a
  * conversation thread. The total is counted before the detail limit so a
@@ -253,7 +306,7 @@ export function queryNonTerminalRunsByAnalysis(pool, analysisId, limit = 20) {
             text: `SELECT COUNT(*)::int AS total
             FROM cortex_runs
             WHERE analysis_id = $1
-              AND status IN ('running','suspended_insufficient_funds')`,
+              AND status = 'running'`,
             values: [analysisId],
         });
         const rowsResult = await pool.query({
@@ -262,13 +315,8 @@ export function queryNonTerminalRunsByAnalysis(pool, analysisId, limit = 20) {
                    mandate_jti, mandate_expires_at, plan_id
             FROM cortex_runs
             WHERE analysis_id = $1
-              AND status IN ('running','suspended_insufficient_funds')
-            ORDER BY CASE status
-                         WHEN 'running' THEN 0
-                         WHEN 'suspended_insufficient_funds' THEN 1
-                         ELSE 2
-                     END,
-                     started_at DESC,
+              AND status = 'running'
+            ORDER BY started_at DESC,
                      run_id DESC
             LIMIT $2`,
             values: [analysisId, limit],
@@ -280,8 +328,7 @@ export function queryNonTerminalRunsByAnalysis(pool, analysisId, limit = 20) {
     });
 }
 /**
- * Read one stable inspection page: running first, then suspended, then
- * terminal history. This is deliberately separate from
+ * Read one stable inspection page: running first, then each other run. This is deliberately separate from
  * {@link queryRunsByAnalysis}, whose chronological order is an embedder/UI
  * contract.
  */
@@ -299,8 +346,7 @@ export function queryRunsForInspection(pool, analysisId, { limit = 50, offset =
             WHERE analysis_id = $1
             ORDER BY CASE status
                          WHEN 'running' THEN 0
-                         WHEN 'suspended_insufficient_funds' THEN 1
-                         ELSE 2
+                         ELSE 1
                      END,
                      started_at DESC,
                      run_id DESC

package/dist/state/schema.d.ts

@@ -54,6 +54,8 @@ export declare const RunStatus: z.ZodEnum<{
     suspended_insufficient_funds: "suspended_insufficient_funds";
 }>;
 export type RunStatus = z.infer<typeof RunStatus>;
+/** A status that a run keeps once it ended: every status but `running`. */
+export type TerminalRunStatus = Exclude<RunStatus, "running">;
 export declare const StepExecutionStatus: z.ZodEnum<{
     failed: "failed";
     pending: "pending";

package/dist/tasks/data-profile-activity.d.ts

@@ -103,5 +103,11 @@ export interface ProfileActivityFrame {
  * A failing write is swallowed and logged, never propagated: observation is a
  * diagnostic channel, and a dropped frame must not fail a profile that is otherwise
  * succeeding. This mirrors the sandbox-step producer's stance on the same write.
+ *
+ * Each emission writes the reconciling activity part, so a late subscriber folds to the
+ * current activity, and then one `data-activity-entry`, so it also gets each earlier line.
+ * The two parts carry one time from `now`, which the body binds to the checkpointed clock of
+ * its workflow. The two writes fail alone. The sequence number of the entry advances before
+ * the clock read and the writes, thus a failure cannot shift a later id.
  */
-export declare function createProfileActivityEmitter(write: ActivityWrite, frame: ProfileActivityFrame, logger: Logger): ProfileActivityEmitter;
+export declare function createProfileActivityEmitter(write: ActivityWrite, frame: ProfileActivityFrame, logger: Logger, now: () => Promise<number>): ProfileActivityEmitter;

package/dist/tasks/data-profile-activity.js

@@ -19,7 +19,7 @@
  * anything that throws on the way there reaches the failure path having emitted
  * no terminal at all.
  */
-import { activityForTool, stepPartId } from "../sandbox/sandbox-step-translate.js";
+import { activityEmission, activityForTool } from "../sandbox/sandbox-step-translate.js";
 /**
  * Build the profile's activity channel over `write`.
  *
@@ -30,21 +30,30 @@ import { activityForTool, stepPartId } from "../sandbox/sandbox-step-translate.j
  * A failing write is swallowed and logged, never propagated: observation is a
  * diagnostic channel, and a dropped frame must not fail a profile that is otherwise
  * succeeding. This mirrors the sandbox-step producer's stance on the same write.
+ *
+ * Each emission writes the reconciling activity part, so a late subscriber folds to the
+ * current activity, and then one `data-activity-entry`, so it also gets each earlier line.
+ * The two parts carry one time from `now`, which the body binds to the checkpointed clock of
+ * its workflow. The two writes fail alone. The sequence number of the entry advances before
+ * the clock read and the writes, thus a failure cannot shift a later id.
  */
-export function createProfileActivityEmitter(write, frame, logger) {
-    // One reconciling id for the profile's single step, so the run-stream fold
-    // collapses every phase transition latest-wins onto one frame rather than
-    // accumulating them. Minted through the shared construction because that
-    // sameness across producers is what makes the fold correct.
-    const id = stepPartId("step-activity", frame.runId, frame.stepId);
-    const emit = async (phase, activity) => {
+export function createProfileActivityEmitter(write, frame, logger, now) {
+    let seq = 0;
+    const writeAlone = async (part, phase) => {
         try {
-            await write({ type: "data-step-activity", id, runId: frame.runId, stepId: frame.stepId, phase, activity });
+            await write(part);
         }
         catch (err) {
             logger.warn("run-event write failed (non-fatal)", { phase, ...logger.errorFields(err) });
         }
     };
+    const emit = async (phase, activity) => {
+        const position = seq++;
+        const at = new Date(await now()).toISOString();
+        const parts = activityEmission(frame, position, phase, activity, at);
+        await writeAlone(parts.activity, phase);
+        await writeAlone(parts.entry, phase);
+    };
     return {
         sandboxInit: () => emit("sandbox-init", "Starting sandbox"),
         scanning: () => emit("executing", "Scanning input files"),

package/dist/tasks/data-profile.d.ts

@@ -28,7 +28,7 @@ import type { SandboxAgentDeps } from "../agents/sandbox/shared.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
 import type { ToolOutputStore } from "../loop/tool-output.js";
 import type { DbError } from "../lib/db-result.js";
-import { type GateRefusal } from "../lib/hooks.js";
+import { type GateRefusal, type NoticeFailure } from "../lib/hooks.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
@@ -38,6 +38,15 @@ import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { type ProfileSubmission } from "../schemas/data-profile-schemas.js";
 import { type ProfileResolution } from "./data-profile-resolve.js";
 import { type DataProfileResult } from "../state/index.js";
+/** The settle of one profile claim: the ledger row left `running`, and the terminal write stamped it. */
+export interface DataProfileSettlement {
+    readonly analysisId: string;
+    readonly status: "completed" | "failed";
+    /** The `data_profile_completed_at` that the terminal write stamped, as an ISO 8601 string. */
+    readonly completedAt: string;
+}
+/** The notice of a profile settle. The workflow body calls it one time for each settled claim. */
+export type NotifyDataProfileSettled = (settlement: DataProfileSettlement) => ResultAsync<void, NoticeFailure>;
 /** The body's construction-time deps — closed over at registration. */
 export interface DataProfileDeps extends EnvironmentStorePaths {
     /** Operational logging seam; omitted falls back to no-op. */
@@ -73,6 +82,11 @@ export interface DataProfileDeps extends EnvironmentStorePaths {
      * Unbound keeps the current shape: no link tool, and no error.
      */
     readonly extendAnalysisFarm?: ExtendAnalysisFarm;
+    /**
+     * Notice of each profile settle, for the records of the embedder. Unbound, the
+     * body calls nothing. It is not a provenance hook.
+     */
+    readonly notifyDataProfileSettled?: NotifyDataProfileSettled;
 }
 /**
  * Workflow input. JSON-serialisable — DBOS persists it as the workflow's

package/dist/tasks/data-profile.js

@@ -296,7 +296,7 @@ export async function runDataProfileBody(input, deps) {
     // ledger has no suspended state and the retry path takes a `failed` row again.
     const suspendProfile = async (suspension) => {
         logger.warn("profile suspended", { reason: suspension.reason });
-        settleTerminalWrite(logger, analysisId, unwrapOrThrow(await failDataProfile(deps.pool, analysisId, suspension.reason)), "failed");
+        await settleTerminalWrite(logger, analysisId, unwrapOrThrow(await failDataProfile(deps.pool, analysisId, suspension.reason)), "failed", deps.notifyDataProfileSettled);
         await revoke("data-profile-suspended");
         unwrapOrThrow(await suspendAnalysis(deps.pool, analysisId));
         await activity.failed(suspension.reason);
@@ -310,7 +310,7 @@ export async function runDataProfileBody(input, deps) {
     // this capability, and a body that composed its own strings is a body they can drift from.
     // The frame is the workflow's synthetic one: both values are constants shared by every analysis,
     // so they identify nothing and consumers are required not to key on them.
-    const activity = createProfileActivityEmitter((part) => DBOS.writeStream("events", part), { runId: DATA_PROFILE_RUN_LITERAL, stepId: DATA_PROFILE_STEP_LITERAL }, logger);
+    const activity = createProfileActivityEmitter((part) => DBOS.writeStream("events", part), { runId: DATA_PROFILE_RUN_LITERAL, stepId: DATA_PROFILE_STEP_LITERAL }, logger, () => DBOS.now());
     try {
         // Record which workflow owns this profile before anything else, so a consumer that resolves
         // the id from the ledger can subscribe from the earliest possible moment. Guarded on a real
@@ -337,7 +337,7 @@ export async function runDataProfileBody(input, deps) {
             // catalogue's fit is measured, and a completion that emitted none would make the
             // empty-manifest path invisible to the same monitoring that watches every other.
             logProfileMonitoring(logger, { dimensions: [], probes: [], repairRounds: 0, absorb: "none" });
-            settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId)), "completed");
+            await settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId)), "completed", deps.notifyDataProfileSettled);
             await revoke("data-profile-completed");
             // This is a terminal completion like any other, so it reports one — a consumer watching
             // an empty-manifest profile sees it settle rather than seeing the stream simply stop.
@@ -356,10 +356,10 @@ export async function runDataProfileBody(input, deps) {
         const executionId = generateExecutionId(DATA_PROFILE_AGENT_ID);
         const workflowId = DBOS.workflowID ?? `${DATA_PROFILE_RUN_LITERAL}:${executionId}`;
         const childSession = forSubAgent(runSession, DATA_PROFILE_AGENT_ID);
-        // A resolver throw fails the workflow loudly (workspace-root-resolution
+        // A resolver rejection fails the workflow loudly (workspace-root-resolution
         // contract) — profiling an analysis whose root cannot be resolved is
         // meaningless, so no softer handling is warranted.
-        const workspaceRoot = deps.resolveWorkspaceRoot(analysisId);
+        const workspaceRoot = await deps.resolveWorkspaceRoot(analysisId);
         const profileWritePrefix = `${workspaceRoot}/runs/${DATA_PROFILE_RUN_LITERAL}/${DATA_PROFILE_STEP_LITERAL}`;
         // 3. The deterministic scan, before any container and before the agent's first turn.
         // It is always needed and its result does not depend on agent judgement, so spending
@@ -390,7 +390,7 @@ export async function runDataProfileBody(input, deps) {
             await activity.indexing();
             await indexProfile({ deps, analysisId, session: runSession, record, scan, logger });
             logProfileMonitoring(logger, { resolution, dimensions: [], probes: [], repairRounds: 0, absorb: "none" });
-            settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, record)), "completed");
+            await settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, record)), "completed", deps.notifyDataProfileSettled);
             await revoke("data-profile-completed");
             await activity.complete();
             return;
@@ -416,7 +416,7 @@ export async function runDataProfileBody(input, deps) {
                 repairRounds: 0,
                 absorb: absorb.kind,
             });
-            settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, absorbed)), "completed");
+            await settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, absorbed)), "completed", deps.notifyDataProfileSettled);
             await revoke("data-profile-completed");
             await activity.complete();
             return;
@@ -571,7 +571,7 @@ export async function runDataProfileBody(input, deps) {
             });
             // 6. Complete — store the FULL profiler finding plus the input signature for
             // staleness detection. The scratch tree is gone; this row is all that survives.
-            settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, profileRecord)), "completed");
+            await settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, profileRecord)), "completed", deps.notifyDataProfileSettled);
             await revoke("data-profile-completed");
             // LAST statement of the success path, and that placement is the guarantee that exactly
             // one terminal activity is ever emitted. Everything that could still throw — the ledger
@@ -598,7 +598,7 @@ export async function runDataProfileBody(input, deps) {
             return await suspendProfile(suspension);
         logger.error("profile failed", logger.errorFields(err));
         const reason = profileFailureReason(err);
-        settleTerminalWrite(logger, analysisId, unwrapOrThrow(await failDataProfile(deps.pool, analysisId, reason)), "failed");
+        await settleTerminalWrite(logger, analysisId, unwrapOrThrow(await failDataProfile(deps.pool, analysisId, reason)), "failed", deps.notifyDataProfileSettled);
         await revoke("data-profile-failed");
         // The same bounded, user-safe line the ledger receives — never the raw error, whose paths and
         // stack frames stay in the log record above. This is the only other terminal emission, so
@@ -617,18 +617,23 @@ function logTerminalNoop(logger, analysisId, write) {
 }
 /**
  * Settle one terminal write of the profile ledger. A refused stamp is logged
- * (see `logTerminalNoop`). An accepted stamp records the profile's run outcome:
- * the CAS admits one write per `running` claim, so this is the exactly-once
+ * (see `logTerminalNoop`) and sends no notice. An accepted stamp records the
+ * profile's run outcome and then delivers the settle notice when the deps bind
+ * one: the CAS admits one write per `running` claim, so this is the exactly-once
  * point of the transition — a recovery replay of the body finds the row no
- * longer `running`, and records nothing again. The duration runs from the
+ * longer `running`, and does neither again. The duration runs from the
  * `data_profile_started_at` the claim stamped, never from a body-local clock.
+ * A crash between the stamp and the notice loses that one notice.
  */
-function settleTerminalWrite(logger, analysisId, write, status) {
+async function settleTerminalWrite(logger, analysisId, write, status, notify) {
     if (!write.stamped) {
         logTerminalNoop(logger, analysisId, status === "completed" ? "completion" : "failure");
         return;
     }
     recordRunCompleted({ workflow: "data_profile", status, durationMs: elapsedSinceIso(write.startedAt) });
+    if (notify === undefined)
+        return;
+    await deliverNotice(logger, "notifyDataProfileSettled", notify({ analysisId, status, completedAt: write.completedAt }));
 }
 /** A one-line, user-facing description of a `DataProfileStartError`. */
 export function describeDataProfileStartError(e) {

package/dist/tools/approval/gateway.js

@@ -40,8 +40,11 @@ export function createAskGateway(deps) {
         // A standing grant this user holds for this ask's grant key — the command
         // unless the tool supplied a broader key — short-circuits the prompt: record
         // the invocation as `resolved` for the audit trail and return without pausing.
+        // The one part it emits is already settled, so no surface prompts, and the
+        // transcript still shows that a standing grant approved the call.
         if (unwrapOrThrow(await selectGrant(pool, ctx.analysisId, ctx.userId, request.grantKey ?? request.command))) {
             unwrapOrThrow(await insertGrantedAsk(pool, row, now));
+            await emitAskPart(ctx.emit, id, request, "resolved", "always");
             return { kind: "always" };
         }
         unwrapOrThrow(await insertPendingAsk(pool, row));
@@ -69,7 +72,7 @@ export function createAskGateway(deps) {
                 throw new AskRejectedError("approval request is no longer available");
             }
             if (resolution.status !== "pending") {
-                await emitAskPart(ctx.emit, id, request, resolution.status);
+                await emitAskPart(ctx.emit, id, request, resolution.status, replyKindOf(resolution.status, resolution.reply));
                 return settle(resolution.status, resolution.reply, ctx.signal);
             }
             await sleepUntil(POLL_INTERVAL_MS, ctx.signal);
@@ -88,7 +91,7 @@ export function createAskGateway(deps) {
     return { ask, answer, pending, sweepExpired };
 }
 /** Emit (or reconcile, under the same id) the ask's `data-ask` chat part. */
-function emitAskPart(emit, id, request, status) {
+function emitAskPart(emit, id, request, status, reply) {
     return emit({
         type: "data-ask",
         data: {
@@ -97,16 +100,36 @@ function emitAskPart(emit, id, request, status) {
             command: request.command,
             ...(request.detail !== undefined ? { detail: request.detail } : {}),
             status,
+            ...(reply !== undefined ? { reply } : {}),
         },
     });
 }
+/**
+ * The kind of reply the terminal part shows: the kind that `settle` acts on for a `resolved` or `rejected` row,
+ * and none for any other status. It never reads the feedback of a rejection, which is for the model.
+ */
+function replyKindOf(status, reply) {
+    switch (status) {
+        case "resolved":
+            return approvalOf(reply).kind;
+        case "rejected":
+            return "reject";
+        case "expired":
+        case "aborted":
+            return undefined;
+    }
+}
+/** The approval that a `resolved` row grants. */
+function approvalOf(reply) {
+    // Only `once` / `always` reach `resolved`; guard the JSONB round-trip and
+    // default to the narrowest approval if a malformed reply ever slipped in.
+    return reply && (reply.kind === "once" || reply.kind === "always") ? reply : { kind: "once" };
+}
 /** Resolve an approval or throw the terminal denial the ledger recorded. */
 function settle(status, reply, signal) {
     switch (status) {
         case "resolved":
-            // Only `once` / `always` reach `resolved`; guard the JSONB round-trip and
-            // default to the narrowest approval if a malformed reply ever slipped in.
-            return reply && (reply.kind === "once" || reply.kind === "always") ? reply : { kind: "once" };
+            return approvalOf(reply);
         case "rejected":
             throw new AskRejectedError(reply && reply.kind === "reject" ? reply.feedback : undefined);
         case "expired":

package/dist/tools/display/show-user.d.ts

@@ -26,7 +26,7 @@ type ShowUserOutput = {
     id: string;
 };
 export declare const showUserTool: import("../define-tool.js").Tool<{
-    kind: "code" | "markdown" | "echart" | "svg" | "table" | "structure";
+    kind: "code" | "echart" | "markdown" | "svg" | "table" | "structure";
     title?: string | undefined;
     spec?: Record<string, unknown> | undefined;
     dataPath?: string | undefined;

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

@@ -2,7 +2,9 @@
  * Unified async edge for approved plans and explicitly requested one-step ad
  * hoc analyses. Both modes launch the ordinary executeAnalysis workflow.
  */
+import { ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
+import type { AgentSession } from "../auth/types.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { EnvironmentStorePaths } from "../config/environment-stores.js";
 import type { ResourcePolicy } from "../config/resource-limits.js";
@@ -54,7 +56,56 @@ export declare class PlanPackagesMissingError extends Error {
     readonly unavailable?: string | undefined;
     constructor(missing: string[], collisions: string[], unavailable?: string | undefined);
 }
+/** The deps that start the run of a stored plan. */
+export type LaunchPlanRunDeps = Pick<ExecuteAnalysisToolDeps, "pool" | "executeAnalysisWorkflow" | "runAuthorizer" | "runLauncher" | "resourcePolicy" | "extendAnalysisFarm" | "logger">;
+/** The run of a stored plan. `started` is false when a run of the plan was already active. */
+export type PlanLaunch = {
+    runId: string;
+    started: boolean;
+};
+/**
+ * Why a stored plan did not start a run. `store_failed.cause` and `launch_failed.cause` are the
+ * values as the failing call gave them, thus a caller that must throw them keeps their class.
+ */
+export type LaunchPlanRunRefusal = {
+    type: "plan_not_found";
+    planId: string;
+} | {
+    type: "plan_invalid";
+    planId: string;
+    malformed: boolean;
+    errors: string[];
+} | {
+    type: "packages_missing";
+    missing: string[];
+    collisions: string[];
+    unavailable?: string;
+} | {
+    type: "not_authorized";
+    reason: string;
+} | {
+    type: "suspended";
+    reason: string;
+} | {
+    type: "store_failed";
+    cause: unknown;
+} | {
+    type: "launch_failed";
+    cause: unknown;
+};
 export declare function buildAdHocPlan(request: string, route: AdHocRoute, createdAt?: string): AnalysisPlan;
+/**
+ * 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 declare function launchPlanRun(deps: LaunchPlanRunDeps, input: {
+    session: AgentSession;
+    planId: string;
+}): ResultAsync<PlanLaunch, LaunchPlanRunRefusal>;
 export declare function createExecuteAnalysisTool(deps: ExecuteAnalysisToolDeps): import("./define-tool.js").Tool<{
     mode: "plan" | "adhoc";
     planId?: string | undefined;