@kontextmind/kxm 0.7.24 → 0.7.25

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) {

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

@@ -13,10 +13,12 @@ import {
 } from "./context-packet.ts";
 import { compileVnextWorkflow, type VnextCompiledPlan, type VnextCompiledStep } from "./vnext-engine-compile.ts";
 import {
+  effectiveRunDurationBudget,
   isTerminalRunStatus,
   vnextFoldPanelAttempt,
   vnextFoldPanelAttemptIds,
   vnextJoinAll,
+  type VnextRunDurationBudget,
   type VnextRunState,
 } from "./vnext-engine-fold.ts";
 import {
@@ -76,6 +78,7 @@ import {
   VNEXT_DRIVE_RECEIPT_SCHEMA,
   type VnextAttemptCapabilityRow,
   type VnextDriveReceipt,
+  type VnextDriveReceiptBudget,
   type VnextDriveReceiptHandoff,
   type VnextGateAttemptRow,
   type VnextGateEvidenceRow,
@@ -388,6 +391,8 @@ async function driveAdmitted(
   }
   let latest: VnextRunDriveResult = { state: foldStoredVnextRun(context, requireRun(context, runId)) };
   while (latest.state.status === "running") {
+    const overBudget = cancelRunDurationIfExceeded(context, runId);
+    if (overBudget) return overBudget;
     const before = context.eventStore.runState(runId)?.lastSequence;
     latest = await stepLocked(context, runId, producer, token);
     if (latest.handoff) return latest;
@@ -513,6 +518,7 @@ export function recordDriveReceipt(
     const last = events[events.length - 1]!;
     const openedSequence = opened?.openedSequence ?? openedEvent?.sequence;
     if (openedSequence === undefined) return;
+    const closedAt = new Date().toISOString();
     const receipt: VnextDriveReceipt = {
       schema: VNEXT_DRIVE_RECEIPT_SCHEMA,
       driveId: session.driveId,
@@ -522,7 +528,7 @@ export function recordDriveReceipt(
       mode: session.mode,
       openedAt: openedEvent?.occurredAt ?? session.openedAt,
       openedSequence,
-      closedAt: new Date().toISOString(),
+      closedAt,
       lastSequence: last.sequence,
       logHash: hashVnextDriveLog(events.filter((event) => event.sequence >= 1 && event.sequence <= last.sequence)),
       settlement: {
@@ -532,7 +538,7 @@ export function recordDriveReceipt(
         ...(closeInfo.kind === "handoff" && closeInfo.handoff ? { handoff: receiptHandoff(closeInfo.handoff) } : {}),
         ...(closeInfo.error !== undefined ? { error: closeInfo.error } : {}),
       },
-      budget: null,
+      budget: driveReceiptBudget(context, run.runId, state, events, closedAt),
       producer: { id: closeInfo.producerId, closed: closeInfo.producerClosed },
     };
     context.eventStore.insertDriveReceipt(receipt);
@@ -744,6 +750,8 @@ export class VnextRunScheduler {
             }
             const driveId = newDriveId(runId, token, this.context.homeRuntimeId, vnextMonotonicNs());
             const openedMeta = appendDriveOpened(this.context, runId, driveId, options.mode);
+            const startedState = foldStoredVnextRun(this.context, requireRun(this.context, runId));
+            const deadlineAt = driveDeadlineAt(this.context, runId, startedState);
             const session: VnextDriveSession = {
               driveId,
               runId,
@@ -754,6 +762,7 @@ export class VnextRunScheduler {
               producerId: producer.id,
               controller: new AbortController(),
               settled,
+              ...(deadlineAt !== undefined ? { deadlineAt } : {}),
             };
             attachVnextDriveSession(this.context.eventStore.path, runId, token, session);
             opened = true;
@@ -900,11 +909,13 @@ async function stepLocked(context: VnextRuntimeContext, runId: string, producer:
       throw runtimeError("run_events_illegal", prepared.run.runId, "prepared gate is not artifacts-exist");
     }
     registerVnextAttemptController(context.eventStore.path, runId, { attemptId: prepared.attemptId, controller: prepared.controller });
+    const clearBudget = armRunDurationBudgetTimer(context, runId);
     try {
       const observation = evaluateArtifactsGate(context, definition);
       vnextGateDispatchSeams.afterEvaluate?.(prepared);
       return context.eventStore.transaction(() => settlePreparedGate(context, prepared, observation));
     } finally {
+      clearBudget();
       unregisterVnextAttemptController(context.eventStore.path, runId, prepared.attemptId);
     }
   }
@@ -945,6 +956,7 @@ async function runPreparedCommandGate(
   });
   armVnextGateHold(storePath, prepared.run.runId, token, prepared.attemptId, () => observer.requestStop("cancel"));
   registerVnextAttemptController(storePath, prepared.run.runId, { attemptId: prepared.attemptId, controller: prepared.controller });
+  const clearBudget = armRunDurationBudgetTimer(context, prepared.run.runId);
   const unhookClose = registerVnextRuntimeCloseHook(context, () => {
     try {
       markVnextGateHoldUnsettled(storePath, prepared.run.runId, token, prepared.attemptId);
@@ -992,6 +1004,7 @@ async function runPreparedCommandGate(
     return commitCommandUncertainty(context, prepared, token, outcome.reason, outcome.observation);
   } finally {
     unhookClose();
+    clearBudget();
     unregisterVnextAttemptController(storePath, prepared.run.runId, prepared.attemptId);
   }
 }
@@ -1798,8 +1811,10 @@ async function drivePanel(
   let stopBirths = false;
   let settlementFailed = false;
 
+  const budgetClears = new Map<string, () => void>();
   const register = (member: PreparedDispatch): void => {
     registerVnextAttemptController(context.eventStore.path, runId, { attemptId: member.attemptId, controller: member.controller });
+    budgetClears.set(member.attemptId, armRunDurationBudgetTimer(context, runId));
     owned.set(member.attemptId, member);
   };
 
@@ -2006,6 +2021,7 @@ async function drivePanel(
     throw error;
   } finally {
     for (const attemptId of owned.keys()) {
+      budgetClears.get(attemptId)?.();
       unregisterVnextAttemptController(context.eventStore.path, runId, attemptId);
     }
   }
@@ -2194,7 +2210,7 @@ function joinPanel(context: VnextRuntimeContext, panel: PreparedPanel): VnextRun
 
   const cancelRun = (): VnextRunDriveResult => {
     push("step.status_changed", { stepId: panel.stepId, status: "cancelled", previousStatus: "running" });
-    push("run.status_changed", { status: "cancelled", reason: "operator_cancel" });
+    push("run.status_changed", { status: "cancelled", reason: cancelReasonFromLog(context, run.runId) });
     for (const event of events) context.eventStore.appendEvent(event);
     const next = foldStoredVnextRun(context, run);
     persistVnextRunState(context, run.runId, next, events[events.length - 1]!.sequence);
@@ -2316,16 +2332,146 @@ function transitionBudgetFailure(plan: VnextCompiledPlan, state: VnextRunState,
   return undefined;
 }
 
-function unsupportedLimit(envelope: VnextRunPlanEnvelope): VnextRunHandoff | undefined {
-  if (envelope.plan.limits.maxRunDurationMs !== undefined) {
-    return { reason: "limit_unsupported", field: "limits.maxRunDurationMs", detail: "duration budget enforcement is not available in this slice" };
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+function elapsedMsBetween(fromIso: string, toIso: string): number {
+  const from = Date.parse(fromIso);
+  const to = Date.parse(toIso);
+  if (!Number.isFinite(from) || !Number.isFinite(to)) return 0;
+  return Math.max(0, Math.trunc(to - from));
+}
+
+function declaredRunDurationBudget(context: VnextRuntimeContext, runId: string): VnextRunDurationBudget | undefined {
+  const run = context.eventStore.run(runId);
+  if (!run) return undefined;
+  try {
+    const envelope = loadVnextRunPlanEnvelope(context.eventStore, run);
+    return effectiveRunDurationBudget(envelope.plan.limits, envelope.projectLimits);
+  } catch {
+    return undefined;
   }
+}
+
+function runDurationOverrunPayload(
+  context: VnextRuntimeContext,
+  runId: string,
+  nowIso = new Date().toISOString(),
+): { budgetMs: number; elapsedMs: number; source: VnextRunDurationBudget["source"] } | undefined {
+  const declared = declaredRunDurationBudget(context, runId);
+  if (!declared) return undefined;
+  const run = context.eventStore.run(runId);
+  if (!run) return undefined;
+  const state = foldStoredVnextRun(context, run);
+  if (!state.runningSince) return undefined;
+  if (isTerminalRunStatus(state.status) || state.status === "cancelling") return undefined;
+  const elapsedMs = elapsedMsBetween(state.runningSince, nowIso);
+  if (elapsedMs < declared.budgetMs) return undefined;
+  return { budgetMs: declared.budgetMs, elapsedMs, source: declared.source };
+}
+
+function cancelRunDurationIfExceeded(context: VnextRuntimeContext, runId: string): VnextRunDriveResult | undefined {
+  if (isVnextRuntimeContextClosed(context)) return undefined;
+  const payload = runDurationOverrunPayload(context, runId);
+  if (!payload) return undefined;
+  cancelVnextRun(context, runId, { reason: "budget_run_duration", budget: payload });
+  return { state: foldStoredVnextRun(context, requireRun(context, runId)) };
+}
+
+function driveDeadlineAt(context: VnextRuntimeContext, runId: string, state: VnextRunState): string | undefined {
+  const declared = declaredRunDurationBudget(context, runId);
+  if (!declared || !state.runningSince) return undefined;
+  const start = Date.parse(state.runningSince);
+  if (!Number.isFinite(start)) return undefined;
+  return new Date(start + declared.budgetMs).toISOString();
+}
+
+function driveReceiptBudget(
+  context: VnextRuntimeContext,
+  runId: string,
+  state: VnextRunState,
+  events: readonly VnextRunEvent[],
+  closedAt: string,
+): VnextDriveReceiptBudget | null {
+  const declared = declaredRunDurationBudget(context, runId);
+  if (!declared) return null;
+  const elapsedMs = state.runningSince ? elapsedMsBetween(state.runningSince, closedAt) : 0;
+  const overrun = events.some((event) => (
+    event.eventType === "run.cancel_requested" && event.payload.reason === "budget_run_duration"
+  ));
+  return {
+    budgetMs: declared.budgetMs,
+    source: declared.source,
+    elapsedMs,
+    overrun,
+  };
+}
+
+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 armRunDurationBudgetTimer(context: VnextRuntimeContext, runId: string): () => void {
+  const declared = declaredRunDurationBudget(context, runId);
+  if (!declared) return () => undefined;
+  const run = context.eventStore.run(runId);
+  if (!run) return () => undefined;
+  const state = foldStoredVnextRun(context, run);
+  if (!state.runningSince) return () => undefined;
+  const startMs = Date.parse(state.runningSince);
+  if (!Number.isFinite(startMs)) return () => undefined;
+  const deadlineMs = startMs + declared.budgetMs;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let cleared = false;
+  const fire = (): void => {
+    timer = undefined;
+    if (cleared || isVnextRuntimeContextClosed(context)) return;
+    const nowIso = new Date().toISOString();
+    const elapsedMs = elapsedMsBetween(state.runningSince!, nowIso);
+    if (elapsedMs < declared.budgetMs) {
+      arm(declared.budgetMs - elapsedMs);
+      return;
+    }
+    try {
+      cancelVnextRun(context, runId, {
+        reason: "budget_run_duration",
+        budget: { budgetMs: declared.budgetMs, elapsedMs, source: declared.source },
+      });
+    } catch {
+      // Already cancelling, terminal, or the store closed under us.
+    }
+  };
+  const arm = (remaining: number): void => {
+    if (cleared) return;
+    const delay = Math.min(Math.max(0, remaining), MAX_TIMER_DELAY_MS);
+    timer = setTimeout(fire, delay);
+    timer.unref();
+  };
+  const unhook = registerVnextRuntimeCloseHook(context, () => {
+    cleared = true;
+    if (timer !== undefined) clearTimeout(timer);
+    timer = undefined;
+  });
+  arm(deadlineMs - Date.now());
+  return () => {
+    if (cleared) return;
+    cleared = true;
+    if (timer !== undefined) clearTimeout(timer);
+    timer = undefined;
+    unhook();
+  };
+}
+
+function unsupportedLimit(envelope: VnextRunPlanEnvelope): VnextRunHandoff | undefined {
   if (envelope.plan.limits.maxAgentTimeMs !== undefined) {
     return { reason: "limit_unsupported", field: "limits.maxAgentTimeMs", detail: "agent-time budget enforcement is not available in this slice" };
   }
-  if (envelope.projectLimits.maxRunDurationMs !== undefined) {
-    return { reason: "limit_unsupported", field: "project.limits.maxRunDurationMs", detail: "duration budget enforcement is not available in this slice" };
-  }
   if (envelope.projectLimits.maxAgentTimeMs !== undefined) {
     return { reason: "limit_unsupported", field: "project.limits.maxAgentTimeMs", detail: "agent-time budget enforcement is not available in this slice" };
   }

package/plugins/kxm/src/vnext-runtime-owner.ts

@@ -29,6 +29,7 @@ export interface VnextDriveSession {
   producerId: string;
   controller: AbortController;
   settled: Promise<unknown>;
+  deadlineAt?: string;
 }
 
 interface AdmissionRecord {

package/plugins/kxm/src/vnext-runtime-store.ts

@@ -392,10 +392,17 @@ export interface VnextDriveReceipt {
   lastSequence: number;
   logHash: string;
   settlement: VnextDriveReceiptSettlement;
-  budget: null;
+  budget: VnextDriveReceiptBudget | null;
   producer: { id: string; closed: boolean };
 }
 
+export interface VnextDriveReceiptBudget {
+  budgetMs: number;
+  source: "workflow" | "project" | "both";
+  elapsedMs: number;
+  overrun: boolean;
+}
+
 /** sha256 over `eventId:sequence` for events 1..lastSequence, in sequence order. */
 export function hashVnextDriveLog(events: readonly { eventId: string; sequence: number }[]): string {
   const body = events.map((event) => `${event.eventId}:${event.sequence}`).join("\n");

package/plugins/kxm/src/vnext-runtime-supervisor.ts

@@ -505,7 +505,7 @@ async function startVnextRuntimeSupervisorInner(
               const scheduler = VnextRunScheduler.for(context, bundle);
               const opening = scheduler.openDriveSession(runId, {
                 mode: body.mode,
-                allowLimits: true,
+                allowLimits: false,
                 liveMode: body.mode === "live",
                 createProducer,
               });

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

@@ -464,6 +464,7 @@ export function foldStoredVnextRun(context: VnextRuntimeContext, run: VnextRunRe
         if (!step || step.kind !== "gate") return undefined;
         return envelope.gates.definitions[step.gate]?.kind;
       },
+      projectLimits: envelope.projectLimits,
     }
     : {});
   if (envelope) verifyVnextGateEvidence(context.eventStore, run, envelope, events, state);
@@ -551,7 +552,13 @@ export interface VnextRunCancelResult {
 export function cancelVnextRun(
   context: VnextRuntimeContext,
   runId: string,
-  options: { commandId?: string; now?: string; monotonicNs?: string; reason?: string } = {},
+  options: {
+    commandId?: string;
+    now?: string;
+    monotonicNs?: string;
+    reason?: string;
+    budget?: { budgetMs: number; elapsedMs: number; source: "workflow" | "project" | "both" };
+  } = {},
 ): VnextRunCancelResult {
   const commandId = options.commandId ?? newVnextCommandId();
   const now = options.now ?? new Date().toISOString();
@@ -600,10 +607,17 @@ export function cancelVnextRun(
 
     const cancelReason = options.reason ?? "operator_cancel";
     const activeAttempt = Boolean(folded.currentStep?.attemptId) || vnextFoldPanelAttemptIds(folded.currentStep).length > 0;
-    push("run.cancel_requested", {
+    const cancelPayload: Record<string, unknown> = {
       actor: { kind: "runtime", id: context.homeRuntimeId },
       reason: cancelReason,
-    });
+    };
+    if (cancelReason === "budget_run_duration") {
+      if (!options.budget) {
+        throw runtimeError("run_events_illegal", runId, "budget_run_duration requires a budget payload");
+      }
+      cancelPayload.budget = options.budget;
+    }
+    push("run.cancel_requested", cancelPayload);
 
     let status: VnextRunStatus = "cancelled";
     if (folded.status === "running" && activeAttempt) {

package/schemas/vnext/drive-receipt.schema.json

@@ -32,7 +32,7 @@
     "lastSequence": { "type": "integer", "minimum": 1 },
     "logHash": { "$ref": "common.schema.json#/$defs/sha256" },
     "settlement": { "$ref": "#/$defs/settlement" },
-    "budget": { "type": "null" },
+    "budget": { "$ref": "#/$defs/budget" },
     "producer": {
       "type": "object",
       "required": ["id", "closed"],
@@ -64,6 +64,22 @@
         }
       ]
     },
+    "budget": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "required": ["budgetMs", "source", "elapsedMs", "overrun"],
+          "properties": {
+            "budgetMs": { "$ref": "common.schema.json#/$defs/durationMs" },
+            "source": { "enum": ["workflow", "project", "both"] },
+            "elapsedMs": { "type": "integer", "minimum": 0 },
+            "overrun": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
     "handoff": {
       "type": "object",
       "required": ["reason", "detail"],

package/schemas/vnext/run-event.schema.json

@@ -90,6 +90,24 @@
         }
       }
     },
+    {
+      "if": {
+        "properties": {
+          "eventType": { "const": "run.cancel_requested" },
+          "payload": {
+            "type": "object",
+            "properties": { "reason": { "const": "budget_run_duration" } },
+            "required": ["reason"]
+          }
+        },
+        "required": ["eventType", "payload"]
+      },
+      "then": {
+        "properties": {
+          "payload": { "type": "object", "required": ["actor", "reason", "budget"] }
+        }
+      }
+    },
     {
       "if": { "properties": { "eventType": { "const": "step.entered" } }, "required": ["eventType"] },
       "then": {
@@ -290,6 +308,16 @@
   ],
   "additionalProperties": false,
   "$defs": {
+    "runDurationBudget": {
+      "type": "object",
+      "required": ["budgetMs", "elapsedMs", "source"],
+      "properties": {
+        "budgetMs": { "$ref": "common.schema.json#/$defs/durationMs" },
+        "elapsedMs": { "type": "integer", "minimum": 0 },
+        "source": { "enum": ["workflow", "project", "both"] }
+      },
+      "additionalProperties": false
+    },
     "repositorySnapshot": {
       "type": "object",
       "required": ["repositoryId", "baseCommit", "contentSnapshotHash"],
@@ -391,6 +419,7 @@
         "timing": { "$ref": "common.schema.json#/$defs/timing" },
         "usage": { "$ref": "common.schema.json#/$defs/usage" },
         "error": { "$ref": "common.schema.json#/$defs/errorSummary" },
+        "budget": { "$ref": "#/$defs/runDurationBudget" },
         "actor": { "$ref": "common.schema.json#/$defs/actor" },
         "resolvedBy": { "$ref": "common.schema.json#/$defs/actor" },
         "resolutionAction": {