@kontextmind/kxm 0.6.0

package/plugins/kxm/src/diagnostics.ts

@@ -0,0 +1,184 @@
+export const DIAGNOSTIC_CLASSES = [
+  "command_not_found",
+  "typecheck_error",
+  "test_failure",
+  "timeout",
+  "cancelled",
+  "workflow_scope",
+  "invalid_identity",
+  "invalid_auth",
+  "signal_mismatch",
+  "not_waiting",
+  "network",
+  "parse_error",
+  "unresumable_session",
+  "quota",
+  "provider_error",
+  "unknown",
+] as const;
+
+export type DiagnosticClass = (typeof DIAGNOSTIC_CLASSES)[number];
+
+export const DIAGNOSTIC_OPERATIONS = [
+  "get",
+  "wait",
+  "checkpoint",
+  "journal",
+  "signal",
+  "await",
+  "other",
+] as const;
+
+export type DiagnosticOperation = (typeof DIAGNOSTIC_OPERATIONS)[number];
+
+export const NEXT_ACTIONS = [
+  "use_assigned_coordinator",
+  "wait_then_checkpoint",
+  "record_journal_as_coordinator",
+  "reconnect_with_current_agent_key",
+  "check_project_token",
+  "export_retrospective",
+  "post_signal",
+  "restart_fresh_session",
+  "switch_model_or_retry",
+] as const;
+
+export type NextAction = (typeof NEXT_ACTIONS)[number];
+
+export interface Diagnostic {
+  class: DiagnosticClass;
+  tool: string;
+  operation: DiagnosticOperation;
+  httpStatus?: number;
+  code?: string;
+  assignedCoordinatorName?: string;
+  nextAction?: NextAction;
+  exitCode?: number;
+  durationMs?: number;
+}
+
+export interface ClassifyFailureInput {
+  toolName?: string;
+  message?: string;
+  code?: string;
+  statusCode?: number;
+  exitCode?: number;
+  durationMs?: number;
+  assignedCoordinatorName?: string;
+  nextAction?: NextAction;
+}
+
+const CODE_TO_CLASS: Record<string, DiagnosticClass> = {
+  workflow_forbidden: "workflow_scope",
+  invalid_agent_identity: "invalid_identity",
+  invalid_auth: "invalid_auth",
+  workflow_signal_mismatch: "signal_mismatch",
+  workflow_not_waiting: "not_waiting",
+  workflow_terminal: "not_waiting",
+  workflow_not_running: "not_waiting",
+  unresumable_session: "unresumable_session",
+  provider_quota: "quota",
+  provider_error: "provider_error",
+};
+
+export function operationForTool(toolName: string | undefined): DiagnosticOperation {
+  switch (toolName) {
+    case "kxm_workflow_get":
+    case "kxm_workflow_list":
+      return "get";
+    case "kxm_workflow_wait":
+      return "wait";
+    case "kxm_workflow_checkpoint":
+      return "checkpoint";
+    case "kxm_workflow_record":
+      return "journal";
+    case "kxm_await":
+      return "await";
+    default:
+      return "other";
+  }
+}
+
+export function areaForTool(toolName: string | undefined): "workflow" | "harness" | "implementation" {
+  if (toolName?.startsWith("kxm_workflow_")) return "workflow";
+  if (toolName?.startsWith("kxm_")) return "harness";
+  return "implementation";
+}
+
+export function nextActionForCode(code: string | undefined, operation: DiagnosticOperation): NextAction | undefined {
+  if (code === "workflow_forbidden") return "use_assigned_coordinator";
+  if (code === "invalid_agent_identity") return "reconnect_with_current_agent_key";
+  if (code === "invalid_auth") return "check_project_token";
+  if (code === "workflow_not_waiting" || code === "workflow_terminal" || code === "workflow_not_running") {
+    return operation === "checkpoint" ? "wait_then_checkpoint" : "export_retrospective";
+  }
+  if (code === "workflow_signal_mismatch") return "post_signal";
+  if (code === "unresumable_session") return "restart_fresh_session";
+  if (code === "provider_quota" || code === "provider_error") return "switch_model_or_retry";
+  return undefined;
+}
+
+function classFromTokens(text: string): DiagnosticClass | undefined {
+  const value = text.toLowerCase();
+  if (/\b(enoent|not recognized|command not found|is not recognized)\b/.test(value)) return "command_not_found";
+  if (/\b(ts\d{3,4}|typecheck|type error)\b/.test(value)) return "typecheck_error";
+  if (/\b(test failed|assertionerror|not equal)\b/.test(value)) return "test_failure";
+  if (/\b(timed out|timeout|deadline)\b/.test(value)) return "timeout";
+  if (/\b(aborted|cancelled|canceled|sigint|sigterm)\b/.test(value)) return "cancelled";
+  if (/\b(econnrefused|enotfound|fetch failed|network)\b/.test(value)) return "network";
+  if (/\b(invalid json|unexpected token|parse error)\b/.test(value)) return "parse_error";
+  if (/\b(invalid_request_error|missing_tool_result|unresumable)\b/.test(value)) return "unresumable_session";
+  if (/\b(quota reached|quota exceeded|rate limit(?:ed)?|too many requests|resource exhausted|http 429)\b/.test(value)) return "quota";
+  if (/\b(not visible|only the assigned coordinator)\b/.test(value)) return "workflow_scope";
+  return undefined;
+}
+
+export function classifyFailure(input: ClassifyFailureInput): Diagnostic {
+  const tool = input.toolName?.trim() || "unknown";
+  const operation = operationForTool(input.toolName);
+  const fromCode = input.code ? CODE_TO_CLASS[input.code] : undefined;
+  const fromTokens = input.message ? classFromTokens(input.message) : undefined;
+  const diagnosticClass = fromCode ?? fromTokens ?? "unknown";
+  const messageCoordinator = input.message?.match(/assignedCoordinator=([A-Za-z0-9_.-]{1,64})/)?.[1];
+  const messageAction = input.message?.match(/nextAction=([a-z_]{1,64})/)?.[1];
+  const parsedAction = NEXT_ACTIONS.includes(messageAction as NextAction) ? messageAction as NextAction : undefined;
+  const nextAction = input.nextAction ?? parsedAction ?? nextActionForCode(input.code, operation);
+  const assignedCoordinatorName = input.assignedCoordinatorName ?? messageCoordinator;
+  return {
+    class: diagnosticClass,
+    tool,
+    operation,
+    ...(input.statusCode !== undefined ? { httpStatus: input.statusCode } : {}),
+    ...(input.code ? { code: input.code } : {}),
+    ...(assignedCoordinatorName ? { assignedCoordinatorName } : {}),
+    ...(nextAction ? { nextAction } : {}),
+    ...(input.exitCode !== undefined ? { exitCode: input.exitCode } : {}),
+    ...(input.durationMs !== undefined ? { durationMs: input.durationMs } : {}),
+  };
+}
+
+export function diagnosticEvidence(diagnostic: Diagnostic, toolCallId?: string): string[] {
+  return [
+    `tool:${diagnostic.tool}`,
+    ...(toolCallId ? [`tool-call:${toolCallId}`] : []),
+    `class:${diagnostic.class}`,
+    `operation:${diagnostic.operation}`,
+    ...(diagnostic.code ? [`code:${diagnostic.code}`] : []),
+    ...(diagnostic.nextAction ? [`nextAction:${diagnostic.nextAction}`] : []),
+    ...(diagnostic.assignedCoordinatorName ? [`assignedCoordinator:${diagnostic.assignedCoordinatorName}`] : []),
+  ];
+}
+
+export function diagnosticSummary(diagnostic: Diagnostic): string {
+  const coordinator = diagnostic.assignedCoordinatorName ? `; assigned coordinator: ${diagnostic.assignedCoordinatorName}` : "";
+  const next = diagnostic.nextAction ? `; next action: ${diagnostic.nextAction}` : "";
+  return `Tool ${diagnostic.tool} failed: ${diagnostic.class}${coordinator}${next}`;
+}
+
+export function workflowScopeExtras(operation: DiagnosticOperation, assignedCoordinatorName: string) {
+  return {
+    operation,
+    assignedCoordinatorName,
+    nextAction: "use_assigned_coordinator" as const,
+  };
+}

package/plugins/kxm/src/envelope.ts

@@ -0,0 +1,118 @@
+import { nowIso } from "./protocol.ts";
+
+export const WORKER_SCHEMA = "kxm.worker.v1" as const;
+export const WORKER_RESULT_SCHEMA = "kxm.worker-result.v1" as const;
+import { parseRoutingRecord } from "./routing.ts";
+
+export type WorkerKind = "agent" | "gate";
+export type WorkerDriver = "ai" | "code";
+export type WorkerOutcome = "passed" | "warning" | "failed" | "running";
+
+/** Shared worker base. Agents and gates are both workers; they differ only by driver. */
+export interface WorkerBase {
+  schema: typeof WORKER_SCHEMA;
+  kind: WorkerKind;
+  driver: WorkerDriver;
+  name: string;
+  project?: string;
+  purpose?: string;
+}
+
+export interface AgentWorker extends WorkerBase {
+  kind: "agent";
+  driver: "ai";
+  model?: string;
+  thinking?: string;
+}
+
+export interface GateWorker extends WorkerBase {
+  kind: "gate";
+  driver: "code";
+}
+
+export type Worker = AgentWorker | GateWorker;
+
+/** Standard result envelope emitted by every worker, AI or code. */
+export interface WorkerResultEnvelope<T extends Worker = Worker> {
+  schema: typeof WORKER_RESULT_SCHEMA;
+  worker: T;
+  command: string;
+  ok: boolean;
+  outcome: WorkerOutcome;
+  createdAt: string;
+  summary: string;
+}
+
+export function agentWorker(input: {
+  name: string;
+  project?: string;
+  purpose?: string;
+  model?: string;
+  thinking?: string;
+}): AgentWorker {
+  return {
+    schema: WORKER_SCHEMA,
+    kind: "agent",
+    driver: "ai",
+    name: input.name,
+    ...(input.project ? { project: input.project } : {}),
+    ...(input.purpose ? { purpose: input.purpose } : {}),
+    ...(input.model ? { model: input.model } : {}),
+    ...(input.thinking ? { thinking: input.thinking } : {}),
+  };
+}
+
+export function gateWorker(input: {
+  name: string;
+  project?: string;
+  purpose?: string;
+}): GateWorker {
+  return {
+    schema: WORKER_SCHEMA,
+    kind: "gate",
+    driver: "code",
+    name: input.name,
+    ...(input.project ? { project: input.project } : {}),
+    ...(input.purpose ? { purpose: input.purpose } : {}),
+  };
+}
+
+/**
+ * Build the standard result envelope. Additive payload keys extend the
+ * envelope, but hub-owned identity keys (`schema` and `worker`) are written
+ * after the payload spread and cannot be clobbered. Caller-owned `summary`,
+ * optional `createdAt`, and optional `outcome` are canonical inputs. An explicit `outcome`
+ * must not contradict `ok` ("passed" requires ok: true; "failed" requires
+ * ok: false); contradictions throw instead of emitting a lying envelope.
+ */
+export function workerResult<T extends Worker, P extends Record<string, unknown>>(
+  worker: T,
+  payload: P & {
+    command: string;
+    ok: boolean;
+    summary: string;
+    outcome?: WorkerOutcome;
+    createdAt?: string;
+  },
+): WorkerResultEnvelope<T> & P {
+  const { summary, outcome, createdAt, ...rest } = payload;
+  if (outcome === "passed" && payload.ok === false) {
+    throw new Error("workerResult outcome contradicts ok: \"passed\" requires ok: true");
+  }
+  if (outcome === "failed" && payload.ok === true) {
+    throw new Error("workerResult outcome contradicts ok: \"failed\" requires ok: false");
+  }
+  // Routing records are validated, not trusted: a malformed or body-bearing
+  // routing payload fails closed instead of polluting telemetry.
+  if (rest.routing !== undefined) {
+    parseRoutingRecord(rest.routing);
+  }
+  return {
+    ...rest,
+    schema: WORKER_RESULT_SCHEMA,
+    worker,
+    createdAt: createdAt ?? nowIso(),
+    outcome: outcome ?? (payload.ok ? "passed" : "failed"),
+    summary,
+  } as WorkerResultEnvelope<T> & P;
+}