@inflexa-ai/harness 0.45.0 → 0.45.1

package/dist/state/runs.js

@@ -9,6 +9,7 @@
  * `DbError`. Every other write maps SQLSTATE 23505/23503/23502/23514 to
  * `err(constraint_violation)` via `tryMutation`.
  */
+import { stripNulCharacters } from "../input-sanitization.js";
 import { tryMutation, tryQuery } from "../lib/db-result.js";
 export class RunIdentityCollisionError extends Error {
     runId;
@@ -44,7 +45,7 @@ export class RunDedupCollisionError extends Error {
  * the err channel as a `DbError`.
  */
 export function insertRun(pool, input) {
-    const now = new Date().toISOString();
+    const now = input.startedAt ?? new Date().toISOString();
     return tryMutation("runs.insertRun", async () => {
         await pool.query({
             text: `INSERT INTO cortex_runs
@@ -75,7 +76,7 @@ export function insertRun(pool, input) {
 }
 /** Reserve a deterministic run id, treating same-analysis PK conflict as redelivery. */
 export function reserveRunById(pool, input) {
-    const now = new Date().toISOString();
+    const now = input.startedAt ?? new Date().toISOString();
     return tryMutation("runs.reserveRunById", async () => {
         const result = await pool.query({
             text: `INSERT INTO cortex_runs
@@ -139,6 +140,20 @@ export function queryActiveRun(pool, analysisId, planId) {
         return row ? mapRunRow(row) : null;
     });
 }
+/**
+ * The SQL condition of the text filter `q` for the bound placeholder `placeholder`. A run matches when its id holds the
+ * text, or when the `title` of the plan of the same analysis holds it. `strpos` is the test, because `LIKE` would turn
+ * `%` and `_` of the input into wildcards. The `analysis_id` condition keeps the plan of a different analysis out, the
+ * same scope as `loadPlan`.
+ */
+function runTextCondition(placeholder) {
+    return `(strpos(lower(run_id), lower(${placeholder}::text)) > 0
+              OR EXISTS (SELECT 1 FROM cortex_plans p
+                         WHERE p.plan_id = cortex_runs.plan_id
+                           AND p.analysis_id = cortex_runs.analysis_id
+                           AND jsonb_typeof(p.plan -> 'title') = 'string'
+                           AND strpos(lower(p.plan ->> 'title'), lower(${placeholder}::text)) > 0))`;
+}
 /**
  * Every NON-TERMINAL run of an analysis, newest-first and deliberately unbounded.
  *
@@ -155,9 +170,13 @@ export function queryActiveRun(pool, analysisId, planId) {
  * 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.
+ *
+ * With `q`, only the runs that the text filter selects are members.
  */
-export function queryActiveRunsByAnalysis(pool, analysisId) {
+export function queryActiveRunsByAnalysis(pool, analysisId, { q } = {}) {
     return tryQuery("runs.queryActiveRunsByAnalysis", async () => {
+        const values = [analysisId];
+        const text = q === undefined ? "" : `AND ${runTextCondition(`$${values.push(q)}`)}`;
         const result = await pool.query({
             text: `SELECT run_id, analysis_id, thread_id, workflow_name,
                    status, started_at, completed_at, error, synthesis_status, synthesis_reason, parts,
@@ -165,8 +184,9 @@ export function queryActiveRunsByAnalysis(pool, analysisId) {
             FROM cortex_runs
             WHERE analysis_id = $1
               AND status = 'running'
+              ${text}
             ORDER BY started_at DESC`,
-            values: [analysisId],
+            values,
         });
         return result.rows.map(mapRunRow);
     });
@@ -207,16 +227,22 @@ export function reconcileOrphanedRuns(pool, opts = {}) {
         return result.rows.map((row) => row.run_id);
     });
 }
+/**
+ * Write a status to a run row that is still `running`, and report whether the row changed. The first terminal write
+ * of a run wins: a row that already holds a terminal status keeps its status, its `completed_at`, and its error.
+ * The error text loses each NUL character, because Postgres rejects a NUL in text and the write must not fail for its own value.
+ */
 export function updateRunStatus(pool, runId, status, error) {
     const now = new Date().toISOString();
     const isTerminal = status === "completed" || status === "partial" || status === "failed" || status === "canceled" || status === "suspended_insufficient_funds";
     return tryMutation("runs.updateRunStatus", async () => {
-        await pool.query({
+        const result = await pool.query({
             text: `UPDATE cortex_runs
             SET status = $1, completed_at = $2, error = $3
-            WHERE run_id = $4`,
-            values: [status, isTerminal ? now : null, error ?? null, runId],
+            WHERE run_id = $4 AND status = 'running'`,
+            values: [status, isTerminal ? now : null, error === undefined || error === null ? null : stripNulCharacters(error), runId],
         });
+        return (result.rowCount ?? 0) > 0;
     });
 }
 /**
@@ -224,9 +250,8 @@ export function updateRunStatus(pool, runId, status, error) {
  * and recording `reason` in `error` (the same column `collectAndComplete`
  * stamps `external_cancel` into). Reports whether a row transitioned — false
  * means the run was already terminal (e.g. it completed concurrently with an
- * external cancel), and the caller MUST NOT fall back to `updateRunStatus`,
- * which would clobber that terminal status. The guarded set is the active set
- * `queryActiveRun` deduplicates on.
+ * external cancel). The guarded set is the active set `queryActiveRun`
+ * deduplicates on.
  */
 export function markRunCanceledIfActive(pool, runId, reason) {
     const now = new Date().toISOString();
@@ -264,20 +289,45 @@ export function queryRun(pool, runId) {
         return row ? mapRunRow(row) : null;
     });
 }
-export function queryRunsByAnalysis(pool, analysisId, { limit = 50, offset = 0 } = {}) {
+/**
+ * One window of the runs of an analysis, newest start first. With `q`, the window holds only the runs that the text
+ * filter selects: the filter applies before `limit` and `offset`, and it does not change the order.
+ */
+export function queryRunsByAnalysis(pool, analysisId, { limit = 50, offset = 0, q } = {}) {
     return tryQuery("runs.queryRunsByAnalysis", async () => {
+        const values = [analysisId, limit, offset];
+        const text = q === undefined ? "" : `AND ${runTextCondition(`$${values.push(q)}`)}`;
         const result = await pool.query({
             text: `SELECT run_id, analysis_id, thread_id, workflow_name,
                    status, started_at, completed_at, error, synthesis_status, synthesis_reason, parts,
                    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
+              ${text}
             ORDER BY started_at DESC LIMIT $2 OFFSET $3`,
-            values: [analysisId, limit, offset],
+            values,
         });
         return result.rows.map(mapRunRow);
     });
 }
+/**
+ * The count of the runs of an analysis, in one statement. With `q`, the count holds only the runs that the text filter
+ * selects, thus it agrees with the windows of {@link queryRunsByAnalysis} for the same `q`.
+ */
+export function countRunsByAnalysis(pool, analysisId, { q } = {}) {
+    return tryQuery("runs.countRunsByAnalysis", async () => {
+        const values = [analysisId];
+        const text = q === undefined ? "" : `AND ${runTextCondition(`$${values.push(q)}`)}`;
+        const result = await pool.query({
+            text: `SELECT COUNT(*)::int AS total
+            FROM cortex_runs
+            WHERE analysis_id = $1
+              ${text}`,
+            values,
+        });
+        return Number(result.rows[0]?.total ?? 0);
+    });
+}
 /**
  * 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
@@ -295,6 +345,23 @@ export function queryRunIdsByPlan(pool, opts) {
         return result.rows.map((row) => row.run_id);
     });
 }
+/**
+ * The newest run of one plan of one analysis, or `null` for a plan with no run. The order is the one of
+ * {@link queryRunIdsByPlan}: the latest start first, and the highest run id on a tie of start times.
+ */
+export function queryNewestPlanRun(pool, opts) {
+    return tryQuery("runs.queryNewestPlanRun", async () => {
+        const result = await pool.query({
+            text: `SELECT run_id, started_at FROM cortex_runs
+            WHERE analysis_id = $1 AND plan_id = $2
+            ORDER BY started_at DESC, run_id DESC
+            LIMIT 1`,
+            values: [opts.analysisId, opts.planId],
+        });
+        const row = result.rows[0];
+        return row ? { runId: row.run_id, startedAt: row.started_at } : null;
+    });
+}
 /**
  * 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
@@ -359,16 +426,20 @@ export function queryRunsForInspection(pool, analysisId, { limit = 50, offset =
         };
     });
 }
-export function queryRunsByThread(pool, analysisId, threadId, { limit = 50, offset = 0 } = {}) {
+/** The runs of one thread of an analysis, newest start first. With `q`, the text filter applies before the window. */
+export function queryRunsByThread(pool, analysisId, threadId, { limit = 50, offset = 0, q } = {}) {
     return tryQuery("runs.queryRunsByThread", async () => {
+        const values = [analysisId, threadId, limit, offset];
+        const text = q === undefined ? "" : `AND ${runTextCondition(`$${values.push(q)}`)}`;
         const result = await pool.query({
             text: `SELECT run_id, analysis_id, thread_id, workflow_name,
                    status, started_at, completed_at, error, synthesis_status, synthesis_reason, parts,
                    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 thread_id = $2
+              ${text}
             ORDER BY started_at DESC LIMIT $3 OFFSET $4`,
-            values: [analysisId, threadId, limit, offset],
+            values,
         });
         return result.rows.map(mapRunRow);
     });

package/dist/state/step-executions.d.ts

@@ -74,4 +74,13 @@ export declare function updateStepExecution(pool: Querier, runId: string, stepId
  * these steps never started.
  */
 export declare function sweepPendingStepExecutions(pool: Querier, runId: string): ResultAsync<void, DbError>;
+/**
+ * Settle a run's still-`running` rows to `canceled` after an engine cancel.
+ * A canceled child re-raises before it writes a terminal row, so this is the
+ * only writer for a step that the cancel cut. `canceled`, not `skipped`: these
+ * steps started. The `status = 'running'` guard keeps a terminal row that a
+ * child wrote first. `started_at` and `completed_at` are ISO 8601 `TEXT`, so
+ * the duration casts both; it is NULL when `started_at` is NULL.
+ */
+export declare function cancelRunningStepExecutions(pool: Querier, runId: string, reason: string): ResultAsync<void, DbError>;
 export declare function queryStepsByRun(pool: Querier, runId: string): ResultAsync<StepExecutionRow[], DbError>;

package/dist/state/step-executions.js

@@ -136,6 +136,28 @@ export function sweepPendingStepExecutions(pool, runId) {
         });
     });
 }
+/**
+ * Settle a run's still-`running` rows to `canceled` after an engine cancel.
+ * A canceled child re-raises before it writes a terminal row, so this is the
+ * only writer for a step that the cancel cut. `canceled`, not `skipped`: these
+ * steps started. The `status = 'running'` guard keeps a terminal row that a
+ * child wrote first. `started_at` and `completed_at` are ISO 8601 `TEXT`, so
+ * the duration casts both; it is NULL when `started_at` is NULL.
+ */
+export function cancelRunningStepExecutions(pool, runId, reason) {
+    const now = new Date().toISOString();
+    return tryMutation("stepExecutions.cancelRunningStepExecutions", async () => {
+        await pool.query({
+            text: `UPDATE cortex_step_executions
+          SET status = 'canceled',
+              completed_at = $2::text,
+              duration_ms = (EXTRACT(EPOCH FROM ($2::text::timestamptz - started_at::timestamptz)) * 1000)::bigint,
+              error = $3
+          WHERE run_id = $1 AND status = 'running'`,
+            values: [runId, now, reason],
+        });
+    });
+}
 export function queryStepsByRun(pool, runId) {
     return tryQuery("stepExecutions.queryStepsByRun", async () => {
         const result = await pool.query({

package/dist/tools/ad-hoc-router.d.ts

@@ -24,6 +24,8 @@ export interface AdHocRoute {
     readonly agentId: string;
     readonly resources: ResourceSpec;
     readonly rationale: string;
+    /** The capability phrase of the chosen agent, when the router copied one that the agent advertises. */
+    readonly capability?: string;
     /** The validated package entries of the step. Empty is a normal answer. */
     readonly packages: readonly string[];
     /** Every entry that the validation removed, with the reason for the caveat. */

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

@@ -1,6 +1,7 @@
 import { jsonSchema, tool as aiTool } from "ai";
 import { z } from "zod";
 import { PLANNABLE_AGENT_CATALOG } from "../agents/sandbox-catalog.js";
+import { SANDBOX_AGENT_META } from "../agents/sandbox/index.js";
 import { forSubAgent } from "../auth/types.js";
 import { DATA_PROFILE_ORIENTATION_MAX_CHARS, buildDataProfileOrientation } from "../app/data-profile-orientation.js";
 import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
@@ -24,6 +25,7 @@ const resourcesSchema = z.object({
 });
 const routeSchema = z.object({
     agentId: z.string().optional().describe("The id of one specialist from the eligible catalog, copied exactly."),
+    capability: z.string().optional().describe("The one capability phrase of that specialist which this request uses, copied exactly from its capabilities."),
     resources: resourcesSchema
         .optional()
         .describe("The sandbox resources of the step, inside the stated ranges. Omit to take the defaults; a value outside the ranges is replaced by the defaults."),
@@ -241,6 +243,20 @@ export async function routeAdHocRequest(deps, input) {
     // never becomes a `fallbackClass`, because that class describes the route
     // as a whole and a step agent reads it as "the routing itself fell back".
     const { packages, droppedPackages } = await routePackages(candidate.packages, deps.resolvePackages, logger);
-    logger.info("ad hoc route selected", { agentId, resources, rationale, failure, packages, droppedPackages });
-    return { agentId, resources, rationale, packages, droppedPackages, ...(failure ? { fallbackClass: failure } : {}) };
+    // Kept only when the chosen agent really advertises it. A phrase that no agent advertises
+    // resolves no data requirement anyway, and carrying it would put a fabricated capability into
+    // the step and into the run record. An absent phrase is a normal answer, not a fallback class:
+    // most requests use a capability that declares nothing.
+    const requestedCapability = typeof candidate.capability === "string" ? candidate.capability.trim() : "";
+    const capability = (SANDBOX_AGENT_META[agentId]?.capabilities ?? []).includes(requestedCapability) ? requestedCapability : undefined;
+    logger.info("ad hoc route selected", { agentId, resources, rationale, failure, packages, droppedPackages, ...(capability ? { capability } : {}) });
+    return {
+        agentId,
+        resources,
+        rationale,
+        packages,
+        droppedPackages,
+        ...(capability ? { capability } : {}),
+        ...(failure ? { fallbackClass: failure } : {}),
+    };
 }

package/dist/tools/capability-data.d.ts

@@ -0,0 +1,36 @@
+/**
+ * inspectCapabilityData — the reference data a specialist capability cannot run without, and
+ * whether this store holds it.
+ *
+ * The method of a capability lives in a skill pack, and only a sandbox step agent reads a skill.
+ * Thus a conversation or planning surface knows a capability by its phrase alone, and it cannot
+ * name the datasets the method needs. It then does one of two wrong things: it calls the work
+ * impossible, or it designs a method around what it can see and substitutes for what it cannot.
+ *
+ * The declaration on the agent metadata is the one place a surface above the step can read, and
+ * this tool is how it reads it. The answer names an absent dataset by its CATALOG ID, because the
+ * id is what an install takes — a surface that can provision needs the identifier, not a
+ * description. Where the ids reach an agent matters: a prompt names no dataset, so the knowledge
+ * arrives through a tool, which carries its own description into the context at attach time.
+ */
+import type { EnvironmentStorePaths } from "../config/environment-stores.js";
+export type InspectCapabilityDataDeps = Pick<EnvironmentStorePaths, "refStorePath">;
+/** One capability, its declared datasets, and what the store holds of them. */
+export interface CapabilityDataRow {
+    readonly agentId: string;
+    readonly capability: string;
+    readonly installed: readonly string[];
+    readonly absent: readonly string[];
+}
+export interface CapabilityDataResult {
+    /** False when the store could not be answered for: every `absent` list is then unknown, not empty. */
+    readonly storeReadable: boolean;
+    readonly rows: readonly CapabilityDataRow[];
+    readonly content: string;
+}
+/**
+ * Build the tool. The store read happens per call, not at construction: a dataset installed during
+ * the conversation must show as installed on the next call, and a cached answer would have the
+ * agent offer a download the user already approved.
+ */
+export declare function createInspectCapabilityDataTool(deps?: InspectCapabilityDataDeps): import("./define-tool.js").Tool<Record<string, never>, CapabilityDataResult>;

package/dist/tools/capability-data.js

@@ -0,0 +1,73 @@
+/**
+ * inspectCapabilityData — the reference data a specialist capability cannot run without, and
+ * whether this store holds it.
+ *
+ * The method of a capability lives in a skill pack, and only a sandbox step agent reads a skill.
+ * Thus a conversation or planning surface knows a capability by its phrase alone, and it cannot
+ * name the datasets the method needs. It then does one of two wrong things: it calls the work
+ * impossible, or it designs a method around what it can see and substitutes for what it cannot.
+ *
+ * The declaration on the agent metadata is the one place a surface above the step can read, and
+ * this tool is how it reads it. The answer names an absent dataset by its CATALOG ID, because the
+ * id is what an install takes — a surface that can provision needs the identifier, not a
+ * description. Where the ids reach an agent matters: a prompt names no dataset, so the knowledge
+ * arrives through a tool, which carries its own description into the context at attach time.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { declaredDataRequirements } from "../agents/sandbox-catalog.js";
+import { defineTool } from "./define-tool.js";
+import { readInstalledDatasetIds } from "./sandbox/list-available-refs.js";
+const NO_DECLARATIONS = "No capability of this install declares reference data that it cannot run without.";
+const STORE_UNREADABLE = "The reference store could not be read, so whether these datasets are installed is UNKNOWN — not absent. " +
+    "Say that, and do not offer to install a dataset on this answer alone.";
+function renderRows(rows, storeReadable) {
+    if (rows.length === 0)
+        return NO_DECLARATIONS;
+    const lines = rows.map((row) => {
+        const state = storeReadable
+            ? [row.absent.length > 0 ? `absent: ${row.absent.join(", ")}` : null, row.installed.length > 0 ? `installed: ${row.installed.join(", ")}` : null]
+                .filter((part) => part !== null)
+                .join(" | ")
+            : `declared: ${[...row.installed, ...row.absent].sort().join(", ")}`;
+        return `- ${row.agentId} — "${row.capability}"\n  ${state}`;
+    });
+    const header = storeReadable
+        ? "Reference data a capability cannot run without, and what this store holds. An absent id is what an install takes."
+        : `Reference data a capability cannot run without. ${STORE_UNREADABLE}`;
+    return [header, "", ...lines].join("\n");
+}
+/**
+ * Build the tool. The store read happens per call, not at construction: a dataset installed during
+ * the conversation must show as installed on the next call, and a cached answer would have the
+ * agent offer a download the user already approved.
+ */
+export function createInspectCapabilityDataTool(deps = {}) {
+    return defineTool({
+        id: "inspect_capability_data",
+        description: "The reference data a specialist capability cannot run without, and whether this install holds it. " +
+            "Call it BEFORE you design a method yourself, and before you tell the user that something cannot be done — a capability whose data is absent is one install away, not impossible, and this is the only place that names WHICH datasets. " +
+            "Each entry names a catalog dataset id, which is exactly what an install takes; a surface with a way to provision can act on it directly. " +
+            "It takes no arguments and the whole set is small, so one call is the complete answer. " +
+            "An unreadable store answers UNKNOWN rather than absent, so a store that cannot be read never reads as a store that holds nothing.",
+        inputSchema: z.object({}),
+        describeCall: () => "declared capability data",
+        execute: async () => {
+            const declared = declaredDataRequirements();
+            if (declared.length === 0)
+                return ok({ storeReadable: true, rows: [], content: NO_DECLARATIONS });
+            const installedIds = await readInstalledDatasetIds(deps);
+            const storeReadable = installedIds !== undefined;
+            const rows = declared.map((requirement) => {
+                const datasets = [...requirement.datasets].sort();
+                return {
+                    agentId: requirement.agentId,
+                    capability: requirement.capability,
+                    installed: installedIds === undefined ? [] : datasets.filter((dataset) => installedIds.has(dataset)),
+                    absent: installedIds === undefined ? datasets : datasets.filter((dataset) => !installedIds.has(dataset)),
+                };
+            });
+            return ok({ storeReadable, rows, content: renderRows(rows, storeReadable) });
+        },
+    });
+}

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

@@ -17,7 +17,7 @@ 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 extends Pick<EnvironmentStorePaths, "farmLockFile" | "imagePackagesFile" | "readPoolInventory"> {
+export interface ExecuteAnalysisToolDeps extends Pick<EnvironmentStorePaths, "farmLockFile" | "imagePackagesFile" | "readPoolInventory" | "refStorePath"> {
     readonly pool: Pool;
     readonly executeAnalysisWorkflow: ExecuteAnalysisWorkflow;
     readonly runAuthorizer: RunAuthorizer;
@@ -56,9 +56,22 @@ export declare class PlanPackagesMissingError extends Error {
     readonly unavailable?: string | undefined;
     constructor(missing: string[], collisions: string[], unavailable?: string | undefined);
 }
+/**
+ * A declared dataset that the reference store does not hold, found at the pre-launch pass. The
+ * message names the datasets and no remedy command — the remedy belongs to the embedder, and its
+ * wrapper appends it.
+ */
+export declare class PlanReferencesMissingError extends Error {
+    readonly missing: string[];
+    readonly unavailable?: string | undefined;
+    constructor(missing: 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 LaunchPlanRunDeps = Pick<ExecuteAnalysisToolDeps, "pool" | "executeAnalysisWorkflow" | "runAuthorizer" | "runLauncher" | "resourcePolicy" | "extendAnalysisFarm" | "refStorePath" | "logger">;
+/**
+ * The run of a stored plan. `started` is false when this call started nothing: `runId` then names the
+ * active run of the plan, or the newest run of the plan when the view of the caller was stale.
+ */
 export type PlanLaunch = {
     runId: string;
     started: boolean;
@@ -80,6 +93,13 @@ export type LaunchPlanRunRefusal = {
     missing: string[];
     collisions: string[];
     unavailable?: string;
+} | {
+    type: "references_missing";
+    missing: string[];
+    unavailable?: string;
+} | {
+    type: "run_not_found";
+    runId: string;
 } | {
     type: "not_authorized";
     reason: string;
@@ -94,18 +114,26 @@ export type LaunchPlanRunRefusal = {
     cause: unknown;
 };
 export declare function buildAdHocPlan(request: string, route: AdHocRoute, createdAt?: string): AnalysisPlan;
+/**
+ * `newestRunId` is the newest run of the plan that the caller saw, or `null` when the caller saw no run.
+ * Without it, the launch compares no run.
+ */
+export type LaunchPlanRunInput = {
+    session: AgentSession;
+    planId: string;
+    newestRunId?: string | null;
+};
 /**
  * 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.
+ * compares the newest run of the plan with `newestRunId`, 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 this call started nothing: a run of the plan was already active, or the
+ * newest run of the plan is not the run that the caller saw. `runId` then names that run.
  *
  * 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 launchPlanRun(deps: LaunchPlanRunDeps, input: LaunchPlanRunInput): ResultAsync<PlanLaunch, LaunchPlanRunRefusal>;
 export declare function createExecuteAnalysisTool(deps: ExecuteAnalysisToolDeps): import("./define-tool.js").Tool<{
     mode: "plan" | "adhoc";
     planId?: string | undefined;