@kontextmind/kxm 0.7.24 → 0.7.26

package/plugins/kxm/src/cli/vnext.ts

@@ -484,6 +484,10 @@ interface VnextStatusDrive {
   divergence?: string;
 }
 
+function formatCancelledStatus(reason: string): string {
+  return reason.length > 0 ? `cancelled (${reason})` : "cancelled";
+}
+
 function formatDriveStatusLine(runStatus: string, drive: VnextStatusDrive | undefined): string | undefined {
   if (!drive || typeof drive.driveId !== "string" || drive.driveId.length === 0) return undefined;
   const receipt = drive.receipt ?? null;
@@ -503,12 +507,27 @@ function formatDriveStatusLine(runStatus: string, drive: VnextStatusDrive | unde
       ? `drive ${drive.driveId}: handoff (receipt verified)`
       : `drive ${drive.driveId}: handoff`;
   }
+  if (receipt.settlement?.status === "cancelled") {
+    const label = formatCancelledStatus(reason);
+    return drive.verified === true
+      ? `drive ${drive.driveId}: ${label} (receipt verified)`
+      : `drive ${drive.driveId}: ${label}`;
+  }
   if (drive.verified === true) {
     return `drive ${drive.driveId}: completed (receipt verified)`;
   }
   return `drive ${drive.driveId}: completed`;
 }
 
+function formatRunStatusLine(
+  run: { runId: string; status: string; workflowId: string; updatedAt: string },
+  drive: VnextStatusDrive | undefined,
+): string {
+  const reason = typeof drive?.receipt?.settlement?.reason === "string" ? drive.receipt.settlement.reason : "";
+  const statusLabel = run.status === "cancelled" ? formatCancelledStatus(reason) : run.status;
+  return `run ${run.runId}: ${statusLabel} (workflow ${run.workflowId}, updated ${run.updatedAt})`;
+}
+
 export async function cmdVnextRunStatus(runtime: Runtime, runId: string): Promise<number> {
   try {
     const projectRoot = discoverVnextProjectRoot(runtime.cwd);
@@ -525,7 +544,7 @@ export async function cmdVnextRunStatus(runtime: Runtime, runId: string): Promis
       runtime.io,
       runtime.json,
       { ok: true, command: "runs status", run, ...(drive !== undefined ? { drive } : {}) },
-      `run ${run.runId}: ${run.status} (workflow ${run.workflowId}, updated ${run.updatedAt})${driveLine ? `\n${driveLine}` : ""}`,
+      `${formatRunStatusLine(run, drive)}${driveLine ? `\n${driveLine}` : ""}`,
     );
     return 0;
   } catch (error) {
@@ -538,7 +557,32 @@ export async function cmdVnextRunStatus(runtime: Runtime, runId: string): Promis
   }
 }
 
-export async function cmdVnextRunDrive(runtime: Runtime, runId: string, simulated: boolean): Promise<number> {
+const DEFAULT_DRIVE_WAIT_MS = 60_000;
+const MAX_DRIVE_WAIT_MS = 600_000;
+
+function parseDriveWaitTimeoutMs(raw: number | string | undefined): number | undefined {
+  if (raw === undefined) return DEFAULT_DRIVE_WAIT_MS;
+  const value = typeof raw === "number" ? raw : Number(typeof raw === "string" ? raw.trim() : raw);
+  if (!Number.isInteger(value) || value < 1 || value > MAX_DRIVE_WAIT_MS) return undefined;
+  return value;
+}
+
+function sleepMs(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function driveWaitCompleted(drive: VnextStatusDrive | undefined): boolean {
+  return drive?.verified === true
+    && drive.receipt?.settlement?.kind === "terminal"
+    && drive.receipt.settlement.status === "completed";
+}
+
+export async function cmdVnextRunDrive(
+  runtime: Runtime,
+  runId: string,
+  simulated: boolean,
+  options: { wait?: boolean; timeoutMs?: number | string } = {},
+): Promise<number> {
   try {
     const projectRoot = discoverVnextProjectRoot(runtime.cwd);
     if (!projectRoot) {
@@ -550,8 +594,19 @@ export async function cmdVnextRunDrive(runtime: Runtime, runId: string, simulate
       print(runtime.io, runtime.json, { ok: true, command: "runs drive", dryRun: true, runId, mode }, `drive plan: run ${runId} in ${mode} mode (no events written)`);
       return 0;
     }
+    const timeoutMs = options.wait === true ? parseDriveWaitTimeoutMs(options.timeoutMs) : DEFAULT_DRIVE_WAIT_MS;
+    if (options.wait === true && timeoutMs === undefined) {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, command: "runs drive", error: "run_drive_timeout_invalid" },
+        `run drive --wait --timeout-ms must be an integer between 1 and ${MAX_DRIVE_WAIT_MS}`,
+      );
+      return 1;
+    }
     const supervisor = await (vnextDriveCliSeams.ensureSupervisor ?? ensureVnextSupervisor)({ env: runtime.env });
-    const result = await (vnextDriveCliSeams.runtimeRequest ?? vnextRuntimeRequest)(supervisor, "POST", `/v1/runs/${encodeURIComponent(runId)}/drive?projectRoot=${encodeURIComponent(projectRoot)}`, { mode });
+    const request = vnextDriveCliSeams.runtimeRequest ?? vnextRuntimeRequest;
+    const result = await request(supervisor, "POST", `/v1/runs/${encodeURIComponent(runId)}/drive?projectRoot=${encodeURIComponent(projectRoot)}`, { mode });
     const driveId = result.driveId;
     const poll = result.poll;
     const status = result.status;
@@ -559,13 +614,39 @@ export async function cmdVnextRunDrive(runtime: Runtime, runId: string, simulate
       print(runtime.io, runtime.json, { ok: false, command: "runs drive", error: "run_drive_io_failed" }, "run drive failed because a local operation did not complete");
       return 1;
     }
-    print(
-      runtime.io,
-      runtime.json,
-      { ok: true, command: "runs drive", runId, driveId, poll, mode, status },
-      `drive ${driveId}: accepted (poll ${poll})`,
-    );
-    return 0;
+
+    if (options.wait !== true) {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: true, command: "runs drive", runId, driveId, poll, mode, status },
+        `drive ${driveId}: accepted (poll ${poll})`,
+      );
+      return 0;
+    }
+
+    const deadline = Date.now() + timeoutMs!;
+    let interval = 25;
+    while (true) {
+      const stateResult = await request(supervisor, "GET", `/v1/runs/${encodeURIComponent(runId)}?projectRoot=${encodeURIComponent(projectRoot)}`);
+      const drive = stateResult.drive as VnextStatusDrive | undefined;
+      if (drive?.receipt) {
+        print(
+          runtime.io,
+          runtime.json,
+          { ok: driveWaitCompleted(drive), command: "runs drive", receipt: drive.receipt, verified: drive.verified === true },
+          JSON.stringify(drive.receipt, null, 2),
+        );
+        return driveWaitCompleted(drive) ? 0 : 1;
+      }
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await sleepMs(Math.min(interval, remaining));
+      interval = Math.min(Math.floor(interval * 1.5), 250);
+    }
+
+    print(runtime.io, runtime.json, { ok: false, command: "runs drive", error: "timeout" }, "drive wait timed out");
+    return 1;
   } catch (error) {
     if (error instanceof VnextConfigError) {
       print(runtime.io, runtime.json, { ok: false, command: "runs drive", error: "run_drive_failed", issues: error.issues }, `run drive failed: ${error.message}`);
@@ -753,3 +834,45 @@ export async function cmdVnextRuntime(runtime: Runtime, action: string): Promise
     return 1;
   }
 }
+
+export async function cmdVnextRunReceipt(runtime: Runtime, runId: string, options: { all?: boolean } = {}): Promise<number> {
+  try {
+    const projectRoot = discoverVnextProjectRoot(runtime.cwd);
+    if (!projectRoot) {
+      print(runtime.io, runtime.json, { ok: false, command: "runs receipt", error: "project_required" }, "kxm runs receipt requires a vNext project (run kxm init first)");
+      return 1;
+    }
+    const supervisor = await (vnextDriveCliSeams.ensureSupervisor ?? ensureVnextSupervisor)({ env: runtime.env });
+    const result = await (vnextDriveCliSeams.runtimeRequest ?? vnextRuntimeRequest)(
+      supervisor,
+      "GET",
+      `/v1/runs/${encodeURIComponent(runId)}/drive?projectRoot=${encodeURIComponent(projectRoot)}`,
+    );
+    if (!Array.isArray(result.receipts)) {
+      print(runtime.io, runtime.json, { ok: false, command: "runs receipt", error: "run_receipt_io_failed" }, "run receipt failed because a local operation did not complete");
+      return 1;
+    }
+    const receipts = result.receipts as unknown[];
+    if (receipts.length === 0) {
+      print(runtime.io, runtime.json, { ok: false, command: "runs receipt", error: "no_receipts" }, `run ${runId} has no drive receipts`);
+      return 1;
+    }
+    if (options.all === true) {
+      print(runtime.io, runtime.json, { ok: true, command: "runs receipt", receipts }, JSON.stringify(receipts, null, 2));
+      return 0;
+    }
+    const latest = receipts[0];
+    const settlement = latest && typeof latest === "object" && "settlement" in latest
+      ? (latest as { settlement: unknown }).settlement
+      : latest;
+    print(runtime.io, runtime.json, { ok: true, command: "runs receipt", receipt: latest }, JSON.stringify(settlement, null, 2));
+    return 0;
+  } catch (error) {
+    if (error instanceof VnextConfigError) {
+      print(runtime.io, runtime.json, { ok: false, command: "runs receipt", error: "run_receipt_failed", issues: error.issues }, `run receipt failed: ${error.message}`);
+      return 1;
+    }
+    print(runtime.io, runtime.json, { ok: false, command: "runs receipt", error: "run_receipt_io_failed" }, "run receipt failed because a local operation did not complete");
+    return 1;
+  }
+}

package/plugins/kxm/src/cli.ts

@@ -107,6 +107,7 @@ import {
   cmdVnextRun,
   cmdVnextRunStatus,
   cmdVnextRunDrive,
+  cmdVnextRunReceipt,
   cmdVnextRunCancel,
   cmdVnextRunList,
   cmdHarnessList,
@@ -390,8 +391,19 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
   addGlobalOptions(runCmd.command("drive").description("Drive a run with an explicit model-free simulation"))
     .argument("<runId>", "Run id")
     .option("--simulated", "Use the model-free simulation producer")
-    .action(async function runDriveAction(this: Command, runId: string, options: { simulated?: boolean }) {
-      result.code = await cmdVnextRunDrive(runtimeFrom(ctx, this), runId, options.simulated === true);
+    .option("--wait", "Wait until a drive receipt is recorded; exits 0 only for a VERIFIED COMPLETED settlement")
+    .option("--timeout-ms <n>", "Wait timeout in milliseconds (default 60000, max 600000)")
+    .action(async function runDriveAction(this: Command, runId: string, options: { simulated?: boolean; wait?: boolean; timeoutMs?: string }) {
+      result.code = await cmdVnextRunDrive(runtimeFrom(ctx, this), runId, options.simulated === true, {
+        wait: options.wait === true,
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+      });
+    });
+  addGlobalOptions(runCmd.command("receipt").description("Print the newest drive receipt for a run"))
+    .argument("<runId>", "Run id")
+    .option("--all", "Print the capped receipt list for the run")
+    .action(async function runReceiptAction(this: Command, runId: string, options: { all?: boolean }) {
+      result.code = await cmdVnextRunReceipt(runtimeFrom(ctx, this), runId, { all: options.all === true });
     });
   addGlobalOptions(runCmd.command("cancel").description("Durably request cancellation of a run"))
     .argument("<runId>", "Run id")

package/plugins/kxm/src/mcp-server.ts

@@ -8,7 +8,7 @@ import { AGENT_COMMANDS_MAP, enforceToolPolicy, getMcpTools, reconcileInbox } fr
 import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 
-const VERSION = "0.7.24";
+const VERSION = "0.7.26";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;

package/plugins/kxm/src/vnext-engine-fold.ts

@@ -62,6 +62,30 @@ export interface VnextFoldOptions {
     observationId: string,
   ) => { completeness: "complete" | "incomplete" | "no-start" } | undefined;
   readonly gateKind?: (stepId: string) => string | undefined;
+  readonly projectLimits?: {
+    readonly maxRunDurationMs?: number;
+  };
+}
+
+export type VnextRunDurationBudgetSource = "workflow" | "project" | "both";
+
+export interface VnextRunDurationBudget {
+  readonly budgetMs: number;
+  readonly source: VnextRunDurationBudgetSource;
+}
+
+export function effectiveRunDurationBudget(
+  planLimits: { readonly maxRunDurationMs?: number } | undefined,
+  projectLimits: { readonly maxRunDurationMs?: number } | undefined,
+): VnextRunDurationBudget | undefined {
+  const workflow = planLimits?.maxRunDurationMs;
+  const project = projectLimits?.maxRunDurationMs;
+  if (workflow === undefined && project === undefined) return undefined;
+  if (workflow !== undefined && project !== undefined) {
+    return { budgetMs: Math.min(workflow, project), source: "both" };
+  }
+  if (workflow !== undefined) return { budgetMs: workflow, source: "workflow" };
+  return { budgetMs: project!, source: "project" };
 }
 
 export interface VnextFoldAttemptState {
@@ -127,6 +151,7 @@ export interface VnextRunState {
   readonly terminalReason?: string | undefined;
   readonly failureReason?: string | undefined;
   readonly drive?: VnextRunDriveBinding | undefined;
+  readonly runningSince?: string | undefined;
 }
 
 interface MutableAttempt {
@@ -179,6 +204,7 @@ interface MutableState {
   cancelCommandId?: string | undefined;
   lastTerminalTransition?: VnextTerminalStatus | undefined;
   drive?: VnextRunDriveBinding | undefined;
+  runningSince?: string | undefined;
 }
 
 function emptyPanel(): MutablePanel {
@@ -468,7 +494,7 @@ export function foldVnextRunState(
         foldRunStatus(state, plan, event);
         break;
       case "run.cancel_requested":
-        foldCancelRequested(state, event);
+        foldCancelRequested(state, event, plan, options);
         break;
       case "run.drive_opened":
         foldDriveOpened(state, event);
@@ -606,6 +632,9 @@ function foldRunStatus(state: MutableState, plan: VnextCompiledPlan | undefined,
   if ((status === "running" || status === "cancelling") && !plan) {
     throw runtimeError("run_plan_missing", state.runId, `status ${status} requires a pinned run plan`);
   }
+  if (status === "running" && state.runningSince === undefined) {
+    state.runningSince = event.occurredAt;
+  }
   if (TERMINAL_RUN.has(status)) {
     assertTerminalRunStatus(state, plan, status, event);
     if (typeof event.payload.reason === "string") state.terminalReason = event.payload.reason;
@@ -717,10 +746,41 @@ function foldDriveOpened(state: MutableState, event: VnextRunEvent): void {
   state.drive = { driveId, mode, openedSequence: event.sequence };
 }
 
-function foldCancelRequested(state: MutableState, event: VnextRunEvent): void {
+function foldCancelRequested(
+  state: MutableState,
+  event: VnextRunEvent,
+  plan: VnextCompiledPlan | undefined,
+  options: VnextFoldOptions,
+): void {
   if (state.cancelRequested || TERMINAL_RUN.has(state.status)) {
     throw runtimeError("run_events_illegal", state.runId, "duplicate run.cancel_requested is not legal");
   }
+  if (event.payload.reason === "budget_run_duration") {
+    const budget = event.payload.budget;
+    if (!budget || typeof budget !== "object" || Array.isArray(budget)) {
+      throw runtimeError("run_events_illegal", state.runId, "budget_run_duration requires a budget payload");
+    }
+    const body = budget as Record<string, unknown>;
+    const budgetMs = body.budgetMs;
+    const elapsedMs = body.elapsedMs;
+    const source = body.source;
+    if (typeof budgetMs !== "number" || !Number.isInteger(budgetMs) || budgetMs < 0) {
+      throw runtimeError("run_events_illegal", state.runId, "budget_run_duration budgetMs is invalid");
+    }
+    if (typeof elapsedMs !== "number" || !Number.isInteger(elapsedMs) || elapsedMs < 0) {
+      throw runtimeError("run_events_illegal", state.runId, "budget_run_duration elapsedMs is invalid");
+    }
+    if (source !== "workflow" && source !== "project" && source !== "both") {
+      throw runtimeError("run_events_illegal", state.runId, "budget_run_duration source is invalid");
+    }
+    const expected = effectiveRunDurationBudget(plan?.limits, options.projectLimits);
+    if (!expected || expected.budgetMs !== budgetMs || expected.source !== source) {
+      throw runtimeError("run_events_illegal", state.runId, "budget_run_duration budgetMs does not match the plan");
+    }
+    if (elapsedMs < budgetMs) {
+      throw runtimeError("run_events_illegal", state.runId, "budget_run_duration elapsedMs is below budgetMs");
+    }
+  }
   state.cancelRequested = true;
   if (event.commandId) state.cancelCommandId = event.commandId;
 }
@@ -1403,6 +1463,7 @@ function freezeState(state: MutableState): VnextRunState {
     ...(state.terminalReason !== undefined ? { terminalReason: state.terminalReason } : {}),
     ...(state.terminalReason !== undefined && state.status === "failed" ? { failureReason: state.terminalReason } : {}),
     ...(state.drive !== undefined ? { drive: Object.freeze({ ...state.drive }) } : {}),
+    ...(state.runningSince !== undefined ? { runningSince: state.runningSince } : {}),
   };
   return Object.freeze(frozen);
 }

package/plugins/kxm/src/vnext-engine-gate-records.ts

@@ -257,7 +257,7 @@ export function recordGateNoStartInTransaction(
   const cancelled = observation.stopCause === "cancel";
   const now = new Date().toISOString();
   const seq = sequencer(context, run, now);
-  if (cancelled) ensureOperatorCancel(seq, ids.state, run);
+  const cancelReason = cancelled ? ensureOperatorCancel(seq, ids.state, run, context) : undefined;
   const observationId = newVnextObservationId();
   const observed = seq.push("effect.observed", {
     effect: { id: ids.effectId, policy: { class: ids.gateKind === "artifacts-exist" ? "read-only" : "unknown", sharedMutable: false } },
@@ -289,7 +289,7 @@ export function recordGateNoStartInTransaction(
     seq.push("attempt.status_changed", { attemptId: ids.attemptId, status: "terminal" });
     seq.push("assignment.terminal", { assignmentId: ids.assignmentId, outcome: "cancelled", status: "terminal" });
     seq.push("step.status_changed", { stepId, status: "cancelled", previousStatus: "running" });
-    seq.push("run.status_changed", { status: "cancelled", reason: "operator_cancel", stepId });
+    seq.push("run.status_changed", { status: "cancelled", reason: cancelReason ?? "operator_cancel", stepId });
   } else {
     seq.push("assignment.result_recorded", { assignmentId: ids.assignmentId, resultClass: "producer_rejected", status: "result_recorded" });
     seq.push("attempt.status_changed", { attemptId: ids.attemptId, status: "terminal" });
@@ -385,7 +385,7 @@ export function recordGateCancelObservedInTransaction(
   }
   const now = new Date().toISOString();
   const seq = sequencer(context, run, now);
-  ensureOperatorCancel(seq, ids.state, run);
+  const cancelReason = ensureOperatorCancel(seq, ids.state, run, context);
   if (ids.gateKind === "artifacts-exist") {
     seq.push("assignment.executing", { assignmentId: ids.assignmentId, stepId, stepAttempt: ids.stepAttempt, attemptId: ids.attemptId, status: "executing" });
     seq.push("attempt.status_changed", { attemptId: ids.attemptId, assignmentId: ids.assignmentId, stepId, stepAttempt: ids.stepAttempt, status: "executing" });
@@ -428,7 +428,7 @@ export function recordGateCancelObservedInTransaction(
   seq.push("attempt.status_changed", { attemptId: ids.attemptId, status: "terminal" });
   seq.push("assignment.terminal", { assignmentId: ids.assignmentId, outcome: "cancelled", status: "terminal" });
   seq.push("step.status_changed", { stepId, status: "cancelled", previousStatus: "running" });
-  seq.push("run.status_changed", { status: "cancelled", reason: "operator_cancel", stepId });
+  seq.push("run.status_changed", { status: "cancelled", reason: cancelReason, stepId });
   for (const event of seq.events) context.eventStore.appendEvent(event);
   context.eventStore.insertGateObservation(observationRow);
   context.eventStore.settleCapability(ids.attemptId, "settled");
@@ -536,8 +536,9 @@ function ensureOperatorCancel(
   seq: ReturnType<typeof sequencer>,
   state: ReturnType<typeof foldStoredVnextRun>,
   run: VnextRunRecord,
-): void {
-  if (state.status === "cancelling") return;
+  context: VnextRuntimeContext,
+): string {
+  if (state.status === "cancelling") return cancelReasonFromLog(context, run.runId);
   if (state.status !== "running") {
     throw runtimeError("run_events_illegal", run.runId, "cancelled gate proof requires a running or cancelling run");
   }
@@ -546,6 +547,18 @@ function ensureOperatorCancel(
     reason: "operator_cancel",
   });
   seq.push("run.status_changed", { status: "cancelling", reason: "operator_cancel" });
+  return "operator_cancel";
+}
+
+function cancelReasonFromLog(context: VnextRuntimeContext, runId: string): string {
+  const events = context.eventStore.events(runId, 0, 1_000_000);
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index]!;
+    if (event.eventType === "run.cancel_requested" && typeof event.payload.reason === "string") {
+      return event.payload.reason;
+    }
+  }
+  return "operator_cancel";
 }
 
 function sequencer(context: VnextRuntimeContext, run: VnextRunRecord, now: string) {