@kontextmind/kxm 0.7.23 → 0.7.25

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxm-claude-plugin",
-  "version": "0.7.23",
+  "version": "0.7.25",
   "private": true,
   "type": "module",
   "engines": {

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

@@ -473,6 +473,61 @@ export async function cmdVnextRun(runtime: Runtime, workflow: string | undefined
   }
 }
 
+interface VnextStatusDrive {
+  driveId?: string;
+  mode?: string;
+  openedAt?: string;
+  receipt?: {
+    settlement?: { kind?: string; status?: string; reason?: string };
+  } | null;
+  verified?: boolean;
+  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;
+  if (receipt === null) {
+    if (runStatus === "running" || runStatus === "blocked_uncertain") {
+      return `drive ${drive.driveId}: open`;
+    }
+    return `drive ${drive.driveId}: no receipt (orphaned)`;
+  }
+  const kind = receipt.settlement?.kind;
+  const reason = typeof receipt.settlement?.reason === "string" ? receipt.settlement.reason : "";
+  if (kind === "unsettled") {
+    return `drive ${drive.driveId}: unsettled ${reason}`.trimEnd();
+  }
+  if (kind === "handoff") {
+    return drive.verified === true
+      ? `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);
@@ -480,10 +535,17 @@ export async function cmdVnextRunStatus(runtime: Runtime, runId: string): Promis
       print(runtime.io, runtime.json, { ok: false, command: "runs status", error: "project_required" }, "kxm runs status requires a vNext project (run kxm init first)");
       return 1;
     }
-    const supervisor = await ensureVnextSupervisor({ env: runtime.env });
-    const result = await vnextRuntimeRequest(supervisor, "GET", `/v1/runs/${encodeURIComponent(runId)}?projectRoot=${encodeURIComponent(projectRoot)}`);
+    const supervisor = await (vnextDriveCliSeams.ensureSupervisor ?? ensureVnextSupervisor)({ env: runtime.env });
+    const result = await (vnextDriveCliSeams.runtimeRequest ?? vnextRuntimeRequest)(supervisor, "GET", `/v1/runs/${encodeURIComponent(runId)}?projectRoot=${encodeURIComponent(projectRoot)}`);
     const run = result.run as { runId: string; status: string; workflowId: string; configRevision: string; updatedAt: string };
-    print(runtime.io, runtime.json, { ok: true, command: "runs status", run }, `run ${run.runId}: ${run.status} (workflow ${run.workflowId}, updated ${run.updatedAt})`);
+    const drive = result.drive as VnextStatusDrive | undefined;
+    const driveLine = formatDriveStatusLine(run.status, drive);
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: true, command: "runs status", run, ...(drive !== undefined ? { drive } : {}) },
+      `${formatRunStatusLine(run, drive)}${driveLine ? `\n${driveLine}` : ""}`,
+    );
     return 0;
   } catch (error) {
     if (error instanceof VnextConfigError) {

package/plugins/kxm/src/cli.ts

@@ -382,7 +382,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     }));
   const runCmd = addGlobalOptions(program.command("runs").description("Inspect vNext runs"));
   runCmd.helpCommand("help", "Show runs help");
-  addGlobalOptions(runCmd.command("status").description("Show the projected status of a run"))
+  addGlobalOptions(runCmd.command("status").description("Show the projected status of a run, including durable drive receipt state (open / receipt verified / unsettled / orphaned)"))
     .argument("<runId>", "Run id")
     .action(async function runStatusAction(this: Command, runId: string) {
       result.code = await cmdVnextRunStatus(runtimeFrom(ctx, this), runId);

package/plugins/kxm/src/database.ts

@@ -420,7 +420,7 @@ export function discoverProjectStores(projectRoot: string, options: { hubDataPat
         stores.push({
           storeId: `events:${key}`,
           sourcePath: join(eventsDir, entry.name),
-          maxSupportedVersion: 3,
+          maxSupportedVersion: 4,
         });
       }
     }
@@ -537,6 +537,8 @@ export function restoreBackup(
     let maxSupported = 3;
     if (store.storeId === "registry" || store.storeId === "binding-store") {
       maxSupported = 1;
+    } else if (store.storeId.startsWith("events:")) {
+      maxSupported = 4;
     }
 
     let targetPath = store.sourcePath;

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.23";
+const VERSION = "0.7.25";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;

package/plugins/kxm/src/vnext-config.ts

@@ -166,6 +166,7 @@ export class VnextSchemaRegistry {
   readonly migrationReceiptValidator: ValidateFunction;
   readonly permissionDiffValidator: ValidateFunction;
   readonly runEventValidator: ValidateFunction;
+  readonly driveReceiptValidator: ValidateFunction;
 
   constructor(schemasDir = DEFAULT_SCHEMA_DIR) {
     this.schemasDir = resolve(schemasDir);
@@ -183,6 +184,7 @@ export class VnextSchemaRegistry {
     const migrationReceiptFile = "migration-receipt.schema.json";
     const permissionDiffFile = "permission-diff.schema.json";
     const runEventFile = "run-event.schema.json";
+    const driveReceiptFile = "drive-receipt.schema.json";
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, localBindingsFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, templateProvenanceFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, initOperationFile)));
@@ -191,6 +193,7 @@ export class VnextSchemaRegistry {
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, migrationReceiptFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, permissionDiffFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, runEventFile)));
+    this.ajv.addSchema(readJsonObject(join(this.schemasDir, driveReceiptFile)));
     for (const [kind, definition] of Object.entries(RESOURCE_SCHEMA) as [VnextResourceKind, { identity: string; file: string }][]) {
       const validator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${definition.file}`);
       if (!validator) throw new Error(`schema did not compile: ${definition.file}`);
@@ -204,6 +207,7 @@ export class VnextSchemaRegistry {
     const migrationReceiptValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${migrationReceiptFile}`);
     const permissionDiffValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${permissionDiffFile}`);
     const runEventValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${runEventFile}`);
+    const driveReceiptValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${driveReceiptFile}`);
     if (!localBindingsValidator) throw new Error(`schema did not compile: ${localBindingsFile}`);
     if (!templateProvenanceValidator) throw new Error(`schema did not compile: ${templateProvenanceFile}`);
     if (!initOperationValidator) throw new Error(`schema did not compile: ${initOperationFile}`);
@@ -212,6 +216,7 @@ export class VnextSchemaRegistry {
     if (!migrationReceiptValidator) throw new Error(`schema did not compile: ${migrationReceiptFile}`);
     if (!permissionDiffValidator) throw new Error(`schema did not compile: ${permissionDiffFile}`);
     if (!runEventValidator) throw new Error(`schema did not compile: ${runEventFile}`);
+    if (!driveReceiptValidator) throw new Error(`schema did not compile: ${driveReceiptFile}`);
     this.localBindingsValidator = localBindingsValidator;
     this.templateProvenanceValidator = templateProvenanceValidator;
     this.initOperationValidator = initOperationValidator;
@@ -220,6 +225,7 @@ export class VnextSchemaRegistry {
     this.migrationReceiptValidator = migrationReceiptValidator;
     this.permissionDiffValidator = permissionDiffValidator;
     this.runEventValidator = runEventValidator;
+    this.driveReceiptValidator = driveReceiptValidator;
   }
 
   validate(kind: VnextResourceKind, value: JsonObject, file: string): VnextConfigIssue[] {
@@ -261,6 +267,10 @@ export class VnextSchemaRegistry {
     return this.validateAuxiliary(value, file, "kxm.permission-diff.v1", this.permissionDiffValidator);
   }
 
+  validateDriveReceipt(value: JsonObject, file: string): VnextConfigIssue[] {
+    return this.validateAuxiliary(value, file, "kxm.drive-receipt.v1", this.driveReceiptValidator);
+  }
+
   private validateAuxiliary(value: JsonObject, file: string, identity: string, validator: ValidateFunction): VnextConfigIssue[] {
     if (value.schema !== identity) {
       return [issue("schema", "schema_identity_mismatch", file, `expected ${identity}, received ${String(value.schema)}`)];
@@ -285,6 +295,27 @@ export function validateRunEvent(value: unknown, file: string): void {
   }
 }
 
+/** Validate a drive receipt against `kxm.drive-receipt.v1`. Throws `drive_receipt_invalid`. */
+export function validateDriveReceipt(value: unknown, file: string): void {
+  const registry = (cachedRunEventRegistry ??= new VnextSchemaRegistry());
+  if (!value || typeof value !== "object" || Array.isArray(value) || (value as JsonObject).schema !== "kxm.drive-receipt.v1") {
+    throw new VnextConfigError([issue(
+      "schema",
+      "drive_receipt_invalid",
+      file,
+      "expected kxm.drive-receipt.v1",
+    )]);
+  }
+  if (!registry.driveReceiptValidator(value)) {
+    throw new VnextConfigError([issue(
+      "schema",
+      "drive_receipt_invalid",
+      file,
+      registry.ajv.errorsText(registry.driveReceiptValidator.errors, { separator: "; " }),
+    )]);
+  }
+}
+
 function schemaIssue(file: string, error: ErrorObject): VnextConfigIssue {
   const location = error.instancePath || "/";
   const suffix = error.params && "additionalProperty" in error.params

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 {
@@ -107,6 +131,12 @@ export interface VnextRunCurrentStep {
   readonly evidenceRefs?: readonly { id: string; kind: string; hash: string; status: string }[] | undefined;
 }
 
+export interface VnextRunDriveBinding {
+  readonly driveId: string;
+  readonly mode: "simulated" | "live";
+  readonly openedSequence: number;
+}
+
 export interface VnextRunState {
   readonly schema: typeof VNEXT_RUN_STATE_SCHEMA;
   readonly runId: string;
@@ -120,6 +150,8 @@ export interface VnextRunState {
   readonly cancelRequested: boolean;
   readonly terminalReason?: string | undefined;
   readonly failureReason?: string | undefined;
+  readonly drive?: VnextRunDriveBinding | undefined;
+  readonly runningSince?: string | undefined;
 }
 
 interface MutableAttempt {
@@ -171,6 +203,8 @@ interface MutableState {
   awaitingTransition: boolean;
   cancelCommandId?: string | undefined;
   lastTerminalTransition?: VnextTerminalStatus | undefined;
+  drive?: VnextRunDriveBinding | undefined;
+  runningSince?: string | undefined;
 }
 
 function emptyPanel(): MutablePanel {
@@ -460,7 +494,10 @@ 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);
         break;
       case "step.entered":
         foldStepEntered(state, plan!, event);
@@ -595,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;
@@ -694,10 +734,53 @@ function isProvenFailure(state: MutableState, plan: VnextCompiledPlan | undefine
   return Boolean(step && used >= step.maxAttempts);
 }
 
-function foldCancelRequested(state: MutableState, event: VnextRunEvent): void {
+function foldDriveOpened(state: MutableState, event: VnextRunEvent): void {
+  if (state.status !== "running" && state.status !== "blocked_uncertain") {
+    throw runtimeError("run_events_illegal", state.runId, "run.drive_opened is only legal while running or blocked_uncertain");
+  }
+  const driveId = stringPayload(event, "driveId");
+  const mode = stringPayload(event, "mode");
+  if (mode !== "simulated" && mode !== "live") {
+    throw runtimeError("run_events_illegal", state.runId, "run.drive_opened mode must be simulated or live");
+  }
+  state.drive = { driveId, mode, openedSequence: event.sequence };
+}
+
+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;
 }
@@ -1379,6 +1462,8 @@ function freezeState(state: MutableState): VnextRunState {
     cancelRequested: state.cancelRequested,
     ...(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) {