@kontextmind/kxm 0.6.0 → 0.7.0

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

@@ -1,7 +1,13 @@
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { isProducerAdmitted, listRoleBindings } from "./producers.ts";
 import {
   buildFormalContextPacket,
+  buildHandoffManifest,
   formatContextPacketForPrompt,
+  pruneContextPacket,
   type FormalContextPacketV2,
   type HandoffManifestV1,
 } from "./context-packet.ts";
@@ -116,6 +122,8 @@ export interface VnextProducerRequest {
 
 export interface VnextProducerResult {
   readonly outcome: string;
+  /** Host cannot attest termination; retain the issued attempt, never replay or settle it. */
+  readonly effectUncertain?: true;
   readonly costBasis?: "metered" | "unmetered" | "unknown";
   readonly costUsd?: number | null;
   readonly tokensIn?: number | null;
@@ -136,7 +144,7 @@ export interface VnextProducerResult {
 }
 
 export interface VnextProducer {
-  readonly id: "driver-simulated" | "pi" | "oneshot" | string;
+  readonly id: "driver-simulated" | "pi" | "oneshot";
   produce(request: VnextProducerRequest): Promise<VnextProducerResult>;
 }
 
@@ -332,7 +340,7 @@ export async function driveVnextRun(
   context: VnextRuntimeContext,
   runId: string,
   producer: VnextProducer,
-  options: { allowLimits?: boolean } = {},
+  options: { allowLimits?: boolean; liveMode?: boolean } = {},
 ): Promise<VnextRunDriveResult> {
   requireTrustedProducer(producer);
   const run = requireRun(context, runId);
@@ -347,7 +355,7 @@ async function driveAdmitted(
   runId: string,
   producer: VnextProducer,
   token: string,
-  options: { allowLimits?: boolean } = {},
+  options: { allowLimits?: boolean; liveMode?: boolean } = {},
 ): Promise<VnextRunDriveResult> {
   const run = requireRun(context, runId);
   if (run.status === "preparing") {
@@ -407,7 +415,11 @@ export class VnextRunScheduler {
     return new VnextRunScheduler(context, bundle.configRevision);
   }
 
-  enqueue(runId: string, producer: VnextProducer): Promise<VnextRunDriveResult> {
+  enqueue(
+    runId: string,
+    producer: VnextProducer,
+    options: { allowLimits?: boolean; liveMode?: boolean } = {},
+  ): Promise<VnextRunDriveResult> {
     requireTrustedProducer(producer);
     const policy = vnextSchedulerPolicy(this.context.eventStore.path);
     if (!policy || policy.configRevision !== this.configRevision) {
@@ -421,7 +433,7 @@ export class VnextRunScheduler {
         runId,
         envelope.revisions.config,
         envelope.projectLimits.maxConcurrentRuns,
-        (token) => driveAdmitted(this.context, runId, producer, token),
+        (token) => driveAdmitted(this.context, runId, producer, token, options),
       ) as Promise<VnextRunDriveResult>;
     } catch (error) {
       return Promise.reject(error);
@@ -471,7 +483,7 @@ export function verifyVnextAttemptCapability(
 function invokeProducer(
   producer: VnextProducer,
   request: VnextProducerRequest,
-): Promise<{ result?: VnextProducerResult; error: boolean }> {
+): Promise<{ result?: VnextProducerResult; error: boolean; errorCode?: string }> {
   let pending: Promise<VnextProducerResult>;
   try {
     pending = Promise.resolve(producer.produce(request));
@@ -884,6 +896,79 @@ function unreconciledPanelAttemptId(state: VnextRunState): string | undefined {
   return undefined;
 }
 
+function resolveProducerRoute(
+  projectRoot: string,
+  step: VnextCompiledStep,
+  agentId: string,
+): { provider: string; model: string; selector: string } | { error: Omit<VnextRunHandoff, "stepId"> } {
+  let agentModel: string | undefined;
+  const agentFile = join(projectRoot, ".kxm", "agents", `${agentId}.yaml`);
+  if (existsSync(agentFile)) {
+    try {
+      const parsed = parse(readFileSync(agentFile, "utf8")) as Record<string, unknown>;
+      if (typeof parsed?.model === "string") {
+        agentModel = parsed.model;
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  let selector = typeof step.model === "string" ? step.model : agentModel;
+  if (!selector) {
+    if (agentId === "implementer") {
+      selector = "xai/grok-4.6";
+    }
+  }
+  if (!selector) {
+    return {
+      error: {
+        reason: "step_unsupported",
+        field: "model",
+        detail: "producer_route_unsupported: agent or step has no model declared",
+      },
+    };
+  }
+
+  const slash = selector.indexOf("/");
+  if (slash <= 0 || slash === selector.length - 1) {
+    return {
+      error: {
+        reason: "step_unsupported",
+        field: "model",
+        detail: `producer_route_unsupported: invalid selector '${selector}'`,
+      },
+    };
+  }
+
+  if (!isProducerAdmitted(projectRoot, selector)) {
+    return {
+      error: {
+        reason: "step_unsupported",
+        field: "model",
+        detail: `producer_route_unsupported: model '${selector}' is not admitted`,
+      },
+    };
+  }
+
+  const role = agentId === "implementer" ? "writer" : agentId;
+  const roleBindings = listRoleBindings(projectRoot);
+  const roster = roleBindings[role];
+  if (roster && !roster.includes(selector)) {
+    return {
+      error: {
+        reason: "step_unsupported",
+        field: "model",
+        detail: `producer_route_unsupported: model '${selector}' not in role '${role}' roster`,
+      },
+    };
+  }
+
+  const provider = selector.slice(0, slash);
+  const model = selector.slice(slash + 1);
+  return { provider, model, selector };
+}
+
 function prepareDispatch(
   context: VnextRuntimeContext,
   runId: string,
@@ -1022,8 +1107,22 @@ function prepareDispatch(
     };
   }
 
-  const unsupported = unsupportedStep(plan, step);
+  const unsupported = unsupportedStep(plan, step, producerId);
   if (unsupported) return { kind: "return", state, handoff: { ...unsupported, stepId } };
+
+  let resolvedRoute: { provider: string; model: string; selector: string } | undefined;
+  if (producerId !== "driver-simulated") {
+    const allowed = step.assignments.allowedAgents;
+    const agentId = (allowed && allowed.length > 0 && allowed[0])
+      ? allowed[0]!
+      : (step.kind === "agent" || step.kind === "moa" ? step.agent : "coordinator");
+    const routeResult = resolveProducerRoute(context.projectRoot, step, agentId);
+    if ("error" in routeResult) {
+      return { kind: "return", state, handoff: { ...routeResult.error, stepId } };
+    }
+    resolvedRoute = routeResult;
+  }
+
   const used = state.stepAttempts[stepId] ?? 0;
   if (used >= step.maxAttempts) {
     return { kind: "return", ...failBudget(context, run, plan, state, "budget_step_attempts", stepId) };
@@ -1056,6 +1155,7 @@ function prepareDispatch(
     stepAttempt,
     enterRunning: true,
     producerId,
+    resolvedRoute,
   });
   return {
     kind: "panel",
@@ -1114,6 +1214,7 @@ function birthMember(
     stepAttempt: number;
     enterRunning?: boolean | undefined;
     producerId?: ("driver-simulated" | "pi" | string) | undefined;
+    resolvedRoute?: { provider: string; model: string; selector: string } | undefined;
   },
 ): PreparedDispatch {
   const run = requireRun(context, input.run.runId);
@@ -1121,11 +1222,27 @@ function birthMember(
   if (!birthAllowed(folded, input.step)) {
     throw runtimeError("run_events_illegal", run.runId, "member birth is not legal");
   }
+  const promptText = context.eventStore.getRunPrompt(run.runId);
+  if (promptText === undefined) {
+    throw runtimeError("run_prompt_mismatch", run.runId, "prompt text missing from accepted run prompt store");
+  }
+  const promptHash = createHash("sha256").update(promptText, "utf8").digest("hex");
+  const expectedHash = run.promptSha256.replace(/^sha256:/, "");
+  if (promptHash !== expectedHash) {
+    throw runtimeError("run_prompt_mismatch", run.runId, "prompt text does not match accepted promptSha256");
+  }
   const born = folded.currentStep?.panel.order.length ?? 0;
   const allowed = input.step.assignments.allowedAgents;
   const agentId = (allowed && allowed.length > born && allowed[born])
     ? allowed[born]!
     : (input.step.kind === "agent" || input.step.kind === "moa" ? input.step.agent : "coordinator");
+  let resolvedRoute = input.resolvedRoute;
+  if (!resolvedRoute && input.producerId && input.producerId !== "driver-simulated") {
+    const routeResult = resolveProducerRoute(context.projectRoot, input.step, agentId);
+    if (!("error" in routeResult)) {
+      resolvedRoute = routeResult;
+    }
+  }
   const assignmentId = newVnextAssignmentId();
   const attemptId = newVnextAttemptId();
   const minted = mintCapabilitySecret();
@@ -1147,7 +1264,12 @@ function birthMember(
   push("assignment.created", { assignmentId, stepId: input.stepId, stepAttempt: input.stepAttempt, agentId, status: "created" });
   push("assignment.accepted", { assignmentId, status: "accepted" });
   push("attempt.created", { attemptId, assignmentId, status: "created" });
-  push("assignment.dispatched", { assignmentId, capabilityHash: minted.hash, status: "dispatched" });
+  push("assignment.dispatched", {
+    assignmentId,
+    capabilityHash: minted.hash,
+    status: "dispatched",
+    ...(resolvedRoute ? { model: { provider: resolvedRoute.provider, model: resolvedRoute.model } } : {}),
+  });
   push("attempt.status_changed", { attemptId, status: "starting" });
   if (input.enterRunning) {
     push("step.status_changed", { stepId: input.stepId, status: "running", previousStatus: "preparing" });
@@ -1165,16 +1287,16 @@ function birthMember(
   });
   const next = foldStoredVnextRun(context, run);
   persistVnextRunState(context, run.runId, next, events[events.length - 1]!.sequence);
-  const contextPacket = buildFormalContextPacket({
+  const rawContextPacket = buildFormalContextPacket({
     project: run.projectId,
     targetRole: agentId,
     task: {
       taskId: run.runId,
       stepId: input.stepId,
       stepAttempt: input.stepAttempt,
-      objective: input.step.description ?? input.step.instructions ?? input.stepId,
+      objective: promptText,
       allowedOutcomes: [...input.step.outcomes],
-      permissionCeiling: "edit",
+      permissionCeiling: Object.values(input.step.repositories).some((access) => access === "write") ? "edit" : "read-only",
     },
     acceptanceCriteria: input.step.requiredEvidence.map((ev) => ({
       id: ev.key,
@@ -1189,6 +1311,7 @@ function birthMember(
       settledDecisions: [],
     },
   });
+  const { packet: contextPacket } = pruneContextPacket(rawContextPacket);
   const generatedPrompt = formatContextPacketForPrompt(contextPacket);
 
   const member: PreparedDispatch = {
@@ -1215,7 +1338,9 @@ function birthMember(
       allowedOutcomes: input.step.outcomes,
       signal: controller.signal,
       prompt: input.step.instructions ? `${input.step.instructions}\n\n${generatedPrompt}` : generatedPrompt,
+      thinking: input.stepAttempt <= 1 ? "low" : "medium",
       contextPacket,
+      ...(resolvedRoute ? { provider: resolvedRoute.provider, model: resolvedRoute.model } : {}),
     },
     controller,
     state: next,
@@ -1391,6 +1516,11 @@ async function drivePanel(
   };
 
   const settleInvoked = (member: PreparedDispatch, produced: { result?: VnextProducerResult; error: boolean }): boolean => {
+    if (produced.result?.effectUncertain) {
+      settlementFailed = true;
+      stopBirths = true;
+      return false;
+    }
     try {
       context.eventStore.transaction(() => {
         if (vnextPanelDispatchSeams.failSettleMember?.(member)) {
@@ -1515,6 +1645,43 @@ async function drivePanel(
   }
 }
 
+function producerRoutingRecord(context: VnextRuntimeContext, dispatch: PreparedDispatch, result: VnextProducerResult, now: string): RoutingRecordV2 {
+  const run = requireRun(context, dispatch.run.runId);
+  if (result.costBasis === undefined || result.costBasis === null) {
+    throw runtimeError("settle_missing_cost_basis", run.runId, `attempt settlement rejected: missing required costBasis for attempt ${dispatch.attemptId}`);
+  }
+  if (result.costBasis !== "metered" && result.costBasis !== "unmetered" && result.costBasis !== "unknown") {
+    throw runtimeError("settle_invalid_cost_basis", run.runId, `attempt settlement rejected: invalid costBasis ${String(result.costBasis)}`);
+  }
+  if (result.costBasis === "metered" && (typeof result.costUsd !== "number" || !Number.isFinite(result.costUsd) || result.costUsd < 0)) {
+    throw runtimeError("settle_invalid_cost", run.runId, "attempt settlement rejected: metered costBasis requires non-negative finite costUsd");
+  }
+  const envelope = loadVnextRunPlanEnvelope(context.eventStore, run);
+  const rawHash = result.behavioralSha256 ?? behavioralConfigHash({
+    requestedModel: result.requestedModel ?? "simulated",
+    effectiveModel: result.effectiveModel ?? result.requestedModel ?? "simulated",
+    agentRole: dispatch.step.kind === "agent" || dispatch.step.kind === "moa" ? dispatch.step.agent : undefined,
+    toolPolicyVersion: envelope.revisions.toolPolicy,
+  });
+  const record: Record<string, unknown> = {
+    schema: ROUTING_RECORD_V2_SCHEMA, recordedAt: now,
+    project: run.projectId, runId: run.runId, stepId: dispatch.stepId,
+    assignmentId: dispatch.assignmentId, attemptId: dispatch.attemptId,
+    harness: result.harness ?? (dispatch.producerId === "pi" ? "pi" : "driver-simulated"),
+    provider: result.provider ?? "simulated", requestedModel: result.requestedModel ?? "simulated",
+    effectiveModel: result.effectiveModel ?? result.requestedModel ?? "simulated",
+    behavioralSha256: rawHash.startsWith("sha256:") ? rawHash : `sha256:${rawHash}`,
+    latencyMs: typeof result.latencyMs === "number" ? result.latencyMs : 0,
+    costBasis: result.costBasis, costUsd: result.costUsd ?? null,
+    retries: Math.max(0, dispatch.stepAttempt - 1),
+    thinking: result.thinking ?? dispatch.request.thinking,
+  };
+  for (const field of ["agentRole", "contextTokens", "tokensIn", "tokensOut", "cacheReadTokens", "cacheWriteTokens", "priceRef", "providerMetadata"] as const) {
+    if (result[field] !== undefined) record[field] = result[field];
+  }
+  return parseRoutingRecordV2(record);
+}
+
 function settleMember(
   context: VnextRuntimeContext,
   dispatch: PreparedDispatch,
@@ -1551,6 +1718,8 @@ function settleMember(
   };
   push("attempt.status_changed", { attemptId: dispatch.attemptId, status: "settling" });
   if (cancelling) {
+    push("routing.attempt.recorded", { routing: producerRoutingRecord(context, dispatch,
+      result ?? { outcome: "cancelled", costBasis: "unknown", costUsd: null }, now) });
     push("assignment.result_recorded", { assignmentId: dispatch.assignmentId, resultClass: "cancelled", status: "result_recorded" });
     push("attempt.status_changed", { attemptId: dispatch.attemptId, status: "terminal" });
     push("assignment.terminal", { assignmentId: dispatch.assignmentId, outcome: "cancelled", status: "terminal" });
@@ -1592,57 +1761,10 @@ function settleMember(
     push("attempt.status_changed", { attemptId: dispatch.attemptId, status: "terminal" });
     push("assignment.terminal", { assignmentId: dispatch.assignmentId, outcome: "failed", status: "terminal" });
   } else {
-    if (!result || result.costBasis === undefined || result.costBasis === null) {
+    if (!result) {
       throw runtimeError("settle_missing_cost_basis", run.runId, `attempt settlement rejected: missing required costBasis for attempt ${dispatch.attemptId}`);
     }
-    if (result.costBasis !== "metered" && result.costBasis !== "unmetered" && result.costBasis !== "unknown") {
-      throw runtimeError("settle_invalid_cost_basis", run.runId, `attempt settlement rejected: invalid costBasis ${String(result.costBasis)}`);
-    }
-    if (result.costBasis === "metered") {
-      if (typeof result.costUsd !== "number" || !Number.isFinite(result.costUsd) || result.costUsd < 0) {
-        throw runtimeError("settle_invalid_cost", run.runId, "attempt settlement rejected: metered costBasis requires non-negative finite costUsd");
-      }
-    }
-
-    const envelope = loadVnextRunPlanEnvelope(context.eventStore, run);
-    const rawHash = result.behavioralSha256 ?? behavioralConfigHash({
-      requestedModel: result.requestedModel ?? "simulated",
-      effectiveModel: result.effectiveModel ?? result.requestedModel ?? "simulated",
-      agentRole: dispatch.step.kind === "agent" || dispatch.step.kind === "moa" ? dispatch.step.agent : undefined,
-      toolPolicyVersion: envelope.revisions.toolPolicy,
-    });
-    const behavioralSha256 = rawHash.startsWith("sha256:") ? rawHash : `sha256:${rawHash}`;
-
-    const routingRecord: RoutingRecordV2 = {
-      schema: ROUTING_RECORD_V2_SCHEMA,
-      recordedAt: now,
-      project: run.projectId,
-      runId: run.runId,
-      stepId: dispatch.stepId,
-      assignmentId: dispatch.assignmentId,
-      attemptId: dispatch.attemptId,
-      harness: result.harness ?? (dispatch.producerId === "pi" ? "pi" : "driver-simulated"),
-      provider: result.provider ?? "simulated",
-      requestedModel: result.requestedModel ?? "simulated",
-      effectiveModel: result.effectiveModel ?? result.requestedModel ?? "simulated",
-      behavioralSha256,
-      latencyMs: typeof result.latencyMs === "number" ? result.latencyMs : 0,
-      costBasis: result.costBasis,
-      costUsd: result.costBasis === "metered" ? (result.costUsd ?? 0) : (result.costUsd ?? null),
-      retries: Math.max(0, dispatch.stepAttempt - 1),
-    };
-
-    if (result.thinking !== undefined) routingRecord.thinking = result.thinking;
-    if (result.agentRole !== undefined) routingRecord.agentRole = result.agentRole;
-    if (result.contextTokens !== undefined) routingRecord.contextTokens = result.contextTokens;
-    if (result.tokensIn !== undefined) routingRecord.tokensIn = result.tokensIn;
-    if (result.tokensOut !== undefined) routingRecord.tokensOut = result.tokensOut;
-    if (result.cacheReadTokens !== undefined) routingRecord.cacheReadTokens = result.cacheReadTokens;
-    if (result.cacheWriteTokens !== undefined) routingRecord.cacheWriteTokens = result.cacheWriteTokens;
-    if (result.priceRef !== undefined) routingRecord.priceRef = result.priceRef;
-    if (result.providerMetadata !== undefined) routingRecord.providerMetadata = result.providerMetadata;
-
-    push("routing.attempt.recorded", { routing: parseRoutingRecordV2(routingRecord) });
+    push("routing.attempt.recorded", { routing: producerRoutingRecord(context, dispatch, result, now) });
 
     const outcome = typeof result.outcome === "string" ? result.outcome : undefined;
     const known = outcome !== undefined && dispatch.step.outcomes.includes(outcome);
@@ -1844,7 +1966,11 @@ function unsupportedLimit(envelope: VnextRunPlanEnvelope): VnextRunHandoff | und
   return undefined;
 }
 
-function unsupportedStep(plan: VnextCompiledPlan, step: VnextCompiledStep): Omit<VnextRunHandoff, "stepId"> | undefined {
+function unsupportedStep(
+  plan: VnextCompiledPlan,
+  step: VnextCompiledStep,
+  producerId?: "driver-simulated" | "pi" | string,
+): Omit<VnextRunHandoff, "stepId"> | undefined {
   if (step.kind === "gate") throw runtimeError("run_plan_corrupt", plan.workflowId, `unsupportedStep called on gate without envelope; use unsupportedGateStep instead`);
   if (step.kind !== "agent" && step.kind !== "moa" && step.kind !== "approval" && step.kind !== "wait") {
     return { reason: "step_unsupported", field: "kind", detail: `step kind ${step.kind} is not executed in this slice` };
@@ -1883,6 +2009,13 @@ function unsupportedStep(plan: VnextCompiledPlan, step: VnextCompiledStep): Omit
       return { reason: "step_unsupported", field: "repositories", detail: `invalid repository access '${access}' on ${repoId}` };
     }
   }
+  if (producerId !== "driver-simulated" && Object.values(step.repositories).some((access) => access === "write")) {
+    return {
+      reason: "step_unsupported",
+      field: "repositories",
+      detail: "live write steps are unsupported until writer sandboxing witness passes",
+    };
+  }
   return undefined;
 }
 
@@ -2364,9 +2497,12 @@ export function recoverVnextRun(
     const run = requireRun(context, runId);
     let state = foldStoredVnextRun(context, run);
 
-    if (state.status !== "blocked_uncertain" && state.currentStep?.effectState !== "blocked_uncertain") {
+    if (state.status !== "blocked_uncertain" && state.status !== "cancelling" && state.currentStep?.effectState !== "blocked_uncertain") {
       throw runtimeError("run_events_illegal", runId, `run ${runId} is not in blocked_uncertain status`);
     }
+    if (state.status === "cancelling" && state.currentStep?.effectState === "blocked_uncertain") {
+      state = { ...state, status: "blocked_uncertain" };
+    }
 
     const now = new Date().toISOString();
     let sequence = context.eventStore.nextSequence(runId);