@kontextmind/kxm 0.6.0

package/plugins/kxm/src/commands.ts

@@ -0,0 +1,1063 @@
+import { randomUUID } from "node:crypto";
+import { HubClient, HubHttpError } from "./client.ts";
+import type {
+  DeliveryMode,
+  ImprovementArea,
+  JournalCategory,
+  MessageRecord,
+  WorkflowCheckpointStatus,
+  WorkflowEvidenceInput,
+  WorkflowEvidenceReferenceInput,
+} from "./protocol.ts";
+
+export interface CommandSchemaProperty {
+  type: "string" | "number" | "integer" | "boolean" | "object" | "array";
+  description?: string;
+  enum?: readonly string[];
+  default?: unknown;
+  minimum?: number;
+  maximum?: number;
+  minItems?: number;
+  maxItems?: number;
+  maxProperties?: number;
+  items?: Record<string, unknown>;
+  patternProperties?: Record<string, unknown>;
+  properties?: Record<string, unknown>;
+  required?: readonly string[];
+  additionalProperties?: boolean | Record<string, unknown>;
+}
+
+export interface CommandJsonSchema {
+  type: "object";
+  properties: Record<string, CommandSchemaProperty>;
+  required?: readonly string[];
+  additionalProperties?: boolean;
+}
+
+export interface ToolPolicy {
+  preset?: string;
+  allow?: string[];
+  deny?: string[];
+  allowedTools?: string[];
+  deniedTools?: string[];
+}
+
+export interface AttemptTokenPayload {
+  schema: "kxm.attempt-token.v1";
+  runId: string;
+  stepId: string;
+  stepAttempt: number;
+  assignmentId: string;
+  attemptId: string;
+  agentId: string;
+  stageId?: string;
+  attempt?: number;
+  toolPolicy?: ToolPolicy;
+  issuedAt?: string;
+}
+
+export interface SessionTokenPayload {
+  schema: "kxm.session-token.v1";
+  sessionId: string;
+  agentName?: string;
+  toolPolicy?: ToolPolicy;
+  issuedAt: string;
+}
+
+export interface CommandExecutionContext {
+  signal?: AbortSignal | undefined;
+  inbox?: Map<string, MessageRecord> | undefined;
+  notifiedInbox?: Set<string> | undefined;
+}
+
+export interface AgentCommand {
+  /** Tool name exposed in MCP and Pi, e.g. "kxm_send" */
+  name: string;
+  /** Primary CLI group, e.g. "peer" or "workflow" or "context" */
+  group: "peer" | "workflow" | "context";
+  /** Subcommand verb in CLI, e.g. "send" or "checkpoint" */
+  verb: string;
+  /** Label for UI displays */
+  label: string;
+  /** Human-readable and LLM description */
+  description: string;
+  /** JSON Schema parameters */
+  parameters: CommandJsonSchema;
+  /** Shared implementation over HubClient */
+  execute: (
+    client: HubClient,
+    args: Record<string, unknown>,
+    context?: CommandExecutionContext,
+  ) => Promise<unknown>;
+}
+
+function requiredString(value: unknown, name: string): string {
+  if (typeof value !== "string" || value.trim() === "") throw new Error(`${name} is required`);
+  return value.trim();
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function optionalWorkflowContext(
+  value: unknown,
+): { runId: string; stageId: string; requirementKey: string; attempt: number } | undefined {
+  if (value === undefined) return undefined;
+  const context = asRecord(value);
+  if (
+    !Number.isInteger(context.attempt)
+    || (context.attempt as number) < 1
+    || (context.attempt as number) > 20
+  ) {
+    throw new Error("workflowContext.attempt must be an integer between 1 and 20");
+  }
+  return {
+    runId: requiredString(context.runId, "workflowContext.runId"),
+    stageId: requiredString(context.stageId, "workflowContext.stageId"),
+    requirementKey: requiredString(context.requirementKey, "workflowContext.requirementKey"),
+    attempt: context.attempt as number,
+  };
+}
+
+function optionalEvidenceRefs(value: unknown): WorkflowEvidenceReferenceInput | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as WorkflowEvidenceReferenceInput)
+    : undefined;
+}
+
+function isTerminalMessageError(error: unknown): boolean {
+  return (
+    error instanceof HubHttpError
+    && (error.statusCode === 409
+      || (error.statusCode === 404 && error.code === "message_not_found"))
+  );
+}
+
+function isTerminalMessage(message: MessageRecord): boolean {
+  return (
+    message.status === "replied"
+    || message.status === "cancelled"
+    || message.status === "expired"
+    || message.status === "error"
+  );
+}
+
+export async function reconcileInbox(
+  client: HubClient,
+  inbox: Map<string, MessageRecord>,
+  notifiedInbox?: Set<string>,
+): Promise<void> {
+  await Promise.all(
+    [...inbox.keys()].map(async (messageId) => {
+      try {
+        const current = await client.getMessage(messageId);
+        if (isTerminalMessage(current)) {
+          inbox.delete(messageId);
+          notifiedInbox?.delete(messageId);
+        } else {
+          inbox.set(messageId, current);
+        }
+      } catch (error) {
+        if (isTerminalMessageError(error)) {
+          inbox.delete(messageId);
+          notifiedInbox?.delete(messageId);
+          return;
+        }
+        throw error;
+      }
+    }),
+  );
+}
+
+function resolveProject(client: HubClient, projectArg: unknown): string {
+  const proj = optionalString(projectArg) ?? client.agent?.project;
+  if (!proj) {
+    throw new Error('missing required parameter "project"');
+  }
+  return proj;
+}
+
+export const AGENT_COMMANDS: readonly AgentCommand[] = [
+  {
+    name: "kxm_list",
+    group: "peer",
+    verb: "list",
+    label: "List hub peers",
+    description: "List online peer agents in this project's hub pool, including their names and purposes.",
+    parameters: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+    async execute(client) {
+      return { agents: await client.listAgents() };
+    },
+  },
+  {
+    name: "kxm_send",
+    group: "peer",
+    verb: "send",
+    label: "Send peer request",
+    description:
+      "Send a focused request to a peer agent. Returns a message ID for kxm_get or kxm_await. For durable peer evidence, workflowContext is the hub-authorized provenance scope; correlation and idempotency are transport concerns and do not establish evidence provenance.",
+    parameters: {
+      type: "object",
+      properties: {
+        target: { type: "string", description: "Peer name or agent ID" },
+        content: { type: "string", description: "Focused request with the expected response or artifact" },
+        delivery: {
+          type: "string",
+          enum: ["steer", "followUp", "nextTurn"],
+          default: "followUp",
+          description: "followUp is the safe default; use steer only for active blockers",
+        },
+        correlationId: {
+          type: "string",
+          description: "Optional task grouping; the hub binds it to runId when workflowContext is supplied",
+        },
+        idempotencyKey: {
+          type: "string",
+          description: "Retry/deduplication key only; not a workflow security or evidence binding",
+        },
+        workflowContext: {
+          type: "object",
+          description: "Requested provenance scope; the hub authorizes and persists the canonical binding",
+          properties: {
+            runId: { type: "string", description: "Active durable workflow run ID" },
+            stageId: { type: "string", description: "Active workflow stage ID" },
+            requirementKey: { type: "string", description: "Required evidence identity this peer reply may satisfy" },
+            attempt: { type: "integer", minimum: 1, maximum: 20, description: "Current one-based stage attempt" },
+          },
+          required: ["runId", "stageId", "requirementKey", "attempt"],
+          additionalProperties: false,
+        },
+        ttlMs: { type: "number", minimum: 1_000, maximum: 604_800_000, description: "Message TTL in milliseconds" },
+      },
+      required: ["target", "content"],
+      additionalProperties: false,
+    },
+    async execute(client, args) {
+      const delivery = optionalString(args.delivery) as DeliveryMode | undefined;
+      const correlationId = optionalString(args.correlationId);
+      const idempotencyKey = optionalString(args.idempotencyKey);
+      const workflowContext = optionalWorkflowContext(args.workflowContext);
+      const message = await client.send({
+        target: requiredString(args.target, "target"),
+        content: requiredString(args.content, "content"),
+        ...(delivery ? { delivery } : {}),
+        ...(correlationId ? { correlationId } : {}),
+        ...(idempotencyKey ? { idempotencyKey } : {}),
+        ...(workflowContext ? { workflowContext } : {}),
+        ...(typeof args.ttlMs === "number" ? { ttlMs: args.ttlMs } : {}),
+      });
+      return { messageId: message.id, status: message.status, target: message.toName };
+    },
+  },
+  {
+    name: "kxm_get",
+    group: "peer",
+    verb: "get",
+    label: "Get peer request",
+    description: "Check the status and optional reply for a previously sent request.",
+    parameters: {
+      type: "object",
+      properties: {
+        messageId: { type: "string", description: "Message ID of the sent request" },
+      },
+      required: ["messageId"],
+      additionalProperties: false,
+    },
+    async execute(client, args) {
+      return await client.getMessage(requiredString(args.messageId, "messageId"));
+    },
+  },
+  {
+    name: "kxm_fanout",
+    group: "peer",
+    verb: "fanout",
+    label: "Fanout peer requests",
+    description:
+      "Ask one through three peers independently and return replies for comparison and synthesis. A local timeout or request cancellation returns a pending response with a durable messageId for kxm_get or an exact retry.",
+    parameters: {
+      type: "object",
+      properties: {
+        targets: {
+          type: "array",
+          items: { type: "string" },
+          minItems: 1,
+          maxItems: 3,
+          description: "One through three target peer names or agent IDs",
+        },
+        content: { type: "string", description: "Task description sent to all targets" },
+        correlationId: {
+          type: "string",
+          description: "Optional task grouping; the hub binds it to runId when workflowContext is supplied",
+        },
+        idempotencyKeyPrefix: {
+          type: "string",
+          description: "Stable retry/deduplication prefix only; not a workflow security or evidence binding",
+        },
+        workflowContext: {
+          type: "object",
+          description: "Requested provenance scope shared by each request",
+          properties: {
+            runId: { type: "string", description: "Active durable workflow run ID" },
+            stageId: { type: "string", description: "Active workflow stage ID" },
+            requirementKey: { type: "string", description: "Required evidence identity these peer replies may satisfy" },
+            attempt: { type: "integer", minimum: 1, maximum: 20, description: "Current one-based stage attempt" },
+          },
+          required: ["runId", "stageId", "requirementKey", "attempt"],
+          additionalProperties: false,
+        },
+        ttlMs: { type: "number", minimum: 1_000, maximum: 604_800_000, description: "Message TTL in milliseconds" },
+        timeoutMs: { type: "number", minimum: 100, maximum: 1_800_000, description: "Client wait timeout in milliseconds" },
+      },
+      required: ["targets", "content"],
+      additionalProperties: false,
+    },
+    async execute(client, args, context) {
+      const targets = Array.isArray(args.targets)
+        ? args.targets.map((t) => requiredString(t, "target"))
+        : [];
+      return {
+        responses: await client.fanout({
+          targets,
+          content: requiredString(args.content, "content"),
+          ...(optionalString(args.correlationId) ? { correlationId: optionalString(args.correlationId)! } : {}),
+          ...(optionalString(args.idempotencyKeyPrefix)
+            ? { idempotencyKeyPrefix: optionalString(args.idempotencyKeyPrefix)! }
+            : {}),
+          ...(optionalWorkflowContext(args.workflowContext)
+            ? { workflowContext: optionalWorkflowContext(args.workflowContext)! }
+            : {}),
+          ...(typeof args.ttlMs === "number" ? { ttlMs: args.ttlMs } : {}),
+          ...(typeof args.timeoutMs === "number" ? { timeoutMs: args.timeoutMs } : {}),
+          ...(context?.signal ? { signal: context.signal } : {}),
+        }),
+      };
+    },
+  },
+  {
+    name: "kxm_await",
+    group: "peer",
+    verb: "await",
+    label: "Await peer response",
+    description:
+      "Wait until a sent request receives a reply or reaches a terminal error. Capped at 60 seconds (60000ms); longer waits are workflow wait steps.",
+    parameters: {
+      type: "object",
+      properties: {
+        messageId: { type: "string", description: "Message ID of the sent request" },
+        timeoutMs: {
+          type: "number",
+          minimum: 100,
+          maximum: 60_000,
+          default: 60_000,
+          description: "Timeout in milliseconds (capped at 60 seconds)",
+        },
+      },
+      required: ["messageId"],
+      additionalProperties: false,
+    },
+    async execute(client, args, context) {
+      const timeoutMs = Math.min(
+        typeof args.timeoutMs === "number" ? args.timeoutMs : 60_000,
+        60_000,
+      );
+      return await client.awaitResponse(
+        requiredString(args.messageId, "messageId"),
+        timeoutMs,
+        context?.signal,
+      );
+    },
+  },
+  {
+    name: "kxm_cancel",
+    group: "peer",
+    verb: "cancel",
+    label: "Cancel peer request",
+    description: "Cancel a queued or delivered request sent by this agent.",
+    parameters: {
+      type: "object",
+      properties: {
+        messageId: { type: "string", description: "Message ID of the request to cancel" },
+      },
+      required: ["messageId"],
+      additionalProperties: false,
+    },
+    async execute(client, args) {
+      return await client.cancel(requiredString(args.messageId, "messageId"));
+    },
+  },
+  {
+    name: "kxm_inbox",
+    group: "peer",
+    verb: "inbox",
+    label: "List inbound requests",
+    description: "List inbound peer requests awaiting a reply.",
+    parameters: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+    async execute(client, _args, context) {
+      if (context?.inbox) {
+        await reconcileInbox(client, context.inbox, context.notifiedInbox);
+        return { messages: [...context.inbox.values()] };
+      }
+      return { messages: [] };
+    },
+  },
+  {
+    name: "kxm_reply",
+    group: "peer",
+    verb: "reply",
+    label: "Reply to peer request",
+    description: "Reply to an inbound peer request using its message ID.",
+    parameters: {
+      type: "object",
+      properties: {
+        messageId: { type: "string", description: "Message ID of the inbound request" },
+        content: { type: "string", description: "Final response with evidence and remaining risks" },
+      },
+      required: ["messageId", "content"],
+      additionalProperties: false,
+    },
+    async execute(client, args, context) {
+      const messageId = requiredString(args.messageId, "messageId");
+      try {
+        const message = await client.reply(messageId, requiredString(args.content, "content"));
+        if (context?.inbox) {
+          context.inbox.delete(messageId);
+          context.notifiedInbox?.delete(messageId);
+        }
+        return { messageId, status: message.status, recipient: message.fromName };
+      } catch (error) {
+        if (context?.inbox && isTerminalMessageError(error)) {
+          context.inbox.delete(messageId);
+          context.notifiedInbox?.delete(messageId);
+        }
+        throw error;
+      }
+    },
+  },
+  {
+    name: "kxm_workflow_list",
+    group: "workflow",
+    verb: "runs",
+    label: "List workflow runs",
+    description: "List durable webhook workflows assigned to this agent.",
+    parameters: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+    async execute(client) {
+      return { runs: await client.listWorkflows() };
+    },
+  },
+  {
+    name: "kxm_workflow_get",
+    group: "workflow",
+    verb: "run",
+    label: "Get workflow run",
+    description: "Get a workflow's stages and journal of plans, decisions, contradictions, errors, and lessons.",
+    parameters: {
+      type: "object",
+      properties: {
+        runId: { type: "string", description: "Workflow run ID" },
+      },
+      required: ["runId"],
+      additionalProperties: false,
+    },
+    async execute(client, args) {
+      return await client.getWorkflow(requiredString(args.runId, "runId"));
+    },
+  },
+  {
+    name: "kxm_workflow_checkpoint",
+    group: "workflow",
+    verb: "checkpoint",
+    label: "Checkpoint workflow stage",
+    description:
+      "Record a stage result with evidence keyed by the stage's required evidence identities. Cite peer-reply requirements through evidenceRefs so the hub can verify provenance and quorum; caller-authored evidence strings cannot satisfy those policies. Warnings and failures require another attempt until passed or exhausted.",
+    parameters: {
+      type: "object",
+      properties: {
+        runId: { type: "string", description: "Active durable workflow run ID" },
+        stageId: { type: "string", description: "Active stage ID" },
+        status: { type: "string", enum: ["passed", "warning", "failed"], description: "Stage outcome" },
+        summary: { type: "string", description: "Summary of changes, verification, and remaining risks" },
+        evidence: {
+          type: "object",
+          additionalProperties: { type: "string" },
+          maxProperties: 64,
+          description: "Key-value evidence mapping required keys to proof strings",
+        },
+        evidenceRefs: {
+          type: "object",
+          description: "Peer evidence references keyed by required evidence identity",
+          patternProperties: {
+            "^(.*)$": {
+              type: "object",
+              properties: {
+                messageIds: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 16 },
+              },
+              required: ["messageIds"],
+              additionalProperties: false,
+            },
+          },
+          additionalProperties: {
+            type: "object",
+            properties: {
+              messageIds: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 16 },
+            },
+            required: ["messageIds"],
+            additionalProperties: false,
+          },
+          maxProperties: 32,
+        },
+      },
+      required: ["runId", "stageId", "status", "summary"],
+      additionalProperties: false,
+    },
+    async execute(client, args) {
+      return await client.checkpointWorkflow(requiredString(args.runId, "runId"), {
+        stageId: requiredString(args.stageId, "stageId"),
+        status: requiredString(args.status, "status") as WorkflowCheckpointStatus,
+        summary: requiredString(args.summary, "summary"),
+        ...(args.evidence && typeof args.evidence === "object" && !Array.isArray(args.evidence)
+          ? { evidence: args.evidence as WorkflowEvidenceInput }
+          : {}),
+        ...(optionalEvidenceRefs(args.evidenceRefs)
+          ? { evidenceRefs: optionalEvidenceRefs(args.evidenceRefs)! }
+          : {}),
+      });
+    },
+  },
+  {
+    name: "kxm_workflow_record",
+    group: "workflow",
+    verb: "record",
+    label: "Record workflow journal entry",
+    description: "Record a plan, decision, contradiction, error, or lesson for continuous improvement.",
+    parameters: {
+      type: "object",
+      properties: {
+        runId: { type: "string", description: "Active durable workflow run ID" },
+        category: {
+          type: "string",
+          enum: ["plan", "decision", "contradiction", "error", "lesson"],
+          description: "Category of journal entry",
+        },
+        area: {
+          type: "string",
+          enum: ["harness", "gates", "implementation", "workflow", "documentation", "security", "other"],
+          description: "System area",
+        },
+        severity: {
+          type: "string",
+          enum: ["info", "warning", "error"],
+          default: "info",
+          description: "Severity level",
+        },
+        summary: { type: "string", description: "Concise description of the observation or decision" },
+        details: { type: "string", description: "Extended details, context, and reasoning" },
+        evidence: {
+          type: "array",
+          items: { type: "string" },
+          maxItems: 32,
+          description: "Durable evidence strings or URIs",
+        },
+        relatedEntryIds: {
+          type: "array",
+          items: { type: "string" },
+          maxItems: 16,
+          description: "Related previous journal entry IDs",
+        },
+      },
+      required: ["runId", "category", "area", "summary"],
+      additionalProperties: false,
+    },
+    async execute(client, args) {
+      return await client.recordWorkflowEntry(requiredString(args.runId, "runId"), {
+        category: requiredString(args.category, "category") as JournalCategory,
+        area: requiredString(args.area, "area") as ImprovementArea,
+        ...(optionalString(args.severity)
+          ? { severity: optionalString(args.severity) as "info" | "warning" | "error" }
+          : {}),
+        summary: requiredString(args.summary, "summary"),
+        ...(optionalString(args.details) ? { details: optionalString(args.details)! } : {}),
+        ...(Array.isArray(args.evidence) ? { evidence: args.evidence as string[] } : {}),
+        ...(Array.isArray(args.relatedEntryIds) ? { relatedEntryIds: args.relatedEntryIds as string[] } : {}),
+      });
+    },
+  },
+  {
+    name: "kxm_workflow_wait",
+    group: "workflow",
+    verb: "wait",
+    label: "Wait for workflow signal",
+    description:
+      "Pause the active stage until a signed external callback checkpoints it and resumes the coordinator. Cite peer-reply requirements through evidenceRefs so the hub can verify provenance and quorum; verified evidence is accumulated with callback evidence.",
+    parameters: {
+      type: "object",
+      properties: {
+        runId: { type: "string", description: "Active durable workflow run ID" },
+        stageId: { type: "string", description: "Active stage ID" },
+        signalKey: { type: "string", description: "Stable callback key, such as github-pr-42-checks" },
+        summary: { type: "string", description: "What is running externally and what result is expected" },
+        evidence: {
+          type: "object",
+          additionalProperties: { type: "string" },
+          maxProperties: 64,
+          description: "Evidence gathered before the wait",
+        },
+        evidenceRefs: {
+          type: "object",
+          description: "Peer evidence references verified before waiting",
+          patternProperties: {
+            "^(.*)$": {
+              type: "object",
+              properties: {
+                messageIds: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 16 },
+              },
+              required: ["messageIds"],
+              additionalProperties: false,
+            },
+          },
+          additionalProperties: {
+            type: "object",
+            properties: {
+              messageIds: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 16 },
+            },
+            required: ["messageIds"],
+            additionalProperties: false,
+          },
+          maxProperties: 32,
+        },
+        timeoutMs: {
+          type: "number",
+          minimum: 1_000,
+          maximum: 2_592_000_000,
+          description: "Maximum wait duration in milliseconds",
+        },
+      },
+      required: ["runId", "stageId", "signalKey", "summary"],
+      additionalProperties: false,
+    },
+    async execute(client, args) {
+      return await client.waitForWorkflowSignal(requiredString(args.runId, "runId"), {
+        stageId: requiredString(args.stageId, "stageId"),
+        signalKey: requiredString(args.signalKey, "signalKey"),
+        summary: requiredString(args.summary, "summary"),
+        ...(args.evidence && typeof args.evidence === "object" && !Array.isArray(args.evidence)
+          ? { evidence: args.evidence as WorkflowEvidenceInput }
+          : {}),
+        ...(optionalEvidenceRefs(args.evidenceRefs)
+          ? { evidenceRefs: optionalEvidenceRefs(args.evidenceRefs)! }
+          : {}),
+        ...(typeof args.timeoutMs === "number" ? { timeoutMs: args.timeoutMs } : {}),
+      });
+    },
+  },
+  {
+    name: "kxm_improvement_report",
+    group: "workflow",
+    verb: "improve-report",
+    label: "Summarize improvement report",
+    description: "Summarize workflow errors, contradictions, and lessons by improvement area.",
+    parameters: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+    async execute(client) {
+      return await client.improvementReport();
+    },
+  },
+  {
+    name: "kxm_context",
+    group: "context",
+    verb: "get",
+    label: "Get KXM context packet",
+    description:
+      "Normal entry point for KXM context. Assembles a token-budgeted role-aware context packet from durable journal evidence, temporal state, knowledge, episodes, and skills. Superseded and rejected records are excluded. Use KXM context tools instead of provider-specific memory APIs.",
+    parameters: {
+      type: "object",
+      properties: {
+        project: { type: "string", description: "Project scope (must be the client's project)" },
+        role: {
+          type: "string",
+          description: "Requesting role: repro, planner, critic, implementer, verifier, or custom",
+        },
+        task: { type: "string", description: "What the role is trying to accomplish" },
+        workflowRunId: { type: "string", description: "Workflow run scope" },
+        stageId: { type: "string", description: "Workflow stage scope" },
+        budgetTokens: { type: "integer", description: "Token budget; defaults to the role policy" },
+        includeKinds: {
+          type: "array",
+          items: { type: "string", enum: ["evidence", "state", "episode", "knowledge", "skill"] },
+          description: "Restrict packet to these item kinds",
+        },
+      },
+      required: ["role", "task"],
+      additionalProperties: false,
+    },
+    async execute(client, args) {
+      return await client.contextGet({
+        project: resolveProject(client, args.project),
+        role: requiredString(args.role, "role"),
+        task: requiredString(args.task, "task"),
+        ...(optionalString(args.workflowRunId) ? { workflowRunId: optionalString(args.workflowRunId)! } : {}),
+        ...(optionalString(args.stageId) ? { stageId: optionalString(args.stageId)! } : {}),
+        ...(typeof args.budgetTokens === "number" ? { budgetTokens: args.budgetTokens } : {}),
+        ...(Array.isArray(args.includeKinds) ? { includeKinds: args.includeKinds as any } : {}),
+      });
+    },
+  },
+  {
+    name: "kxm_recall",
+    group: "context",
+    verb: "recall",
+    label: "Recall context metadata",
+    description: "Search durable context records for a project by query; returns bounded metadata only.",
+    parameters: {
+      type: "object",
+      properties: {
+        project: { type: "string", description: "Project identifier" },
+        query: { type: "string", description: "Query string" },
+        kinds: { type: "array", items: { type: "string" }, description: "Kinds filter" },
+        limit: { type: "integer", minimum: 1, maximum: 100, description: "Maximum results" },
+      },
+      additionalProperties: false,
+    },
+    async execute(client, args) {
+      return await client.contextRecall({
+        project: resolveProject(client, args.project),
+        ...(optionalString(args.query) ? { query: optionalString(args.query)! } : {}),
+        ...(Array.isArray(args.kinds) ? { kinds: args.kinds as any } : {}),
+        ...(typeof args.limit === "number" ? { limit: args.limit } : {}),
+      });
+    },
+  },
+  {
+    name: "kxm_state",
+    group: "context",
+    verb: "state",
+    label: "Get temporal state",
+    description: "Current value for one temporal state key, optionally as of a historical timestamp.",
+    parameters: {
+      type: "object",
+      properties: {
+        project: { type: "string", description: "Project identifier" },
+        key: { type: "string", description: "State key" },
+        asOf: { type: "string", description: "ISO-8601 timestamp for historical queries" },
+      },
+      required: ["key"],
+      additionalProperties: false,
+    },
+    async execute(client, args) {
+      return await client.contextState({
+        project: resolveProject(client, args.project),
+        key: requiredString(args.key, "key"),
+        ...(optionalString(args.asOf) ? { asOf: optionalString(args.asOf)! } : {}),
+      });
+    },
+  },
+  {
+    name: "kxm_episode",
+    group: "context",
+    verb: "episode",
+    label: "Get workflow episodes",
+    description: "Episodic learning from workflow journals: errors, lessons, observations, experiments for a project.",
+    parameters: {
+      type: "object",
+      properties: {
+        project: { type: "string", description: "Project identifier" },
+        workflowRunId: { type: "string", description: "Optional workflow run scope" },
+      },
+      additionalProperties: false,
+    },
+    async execute(client, args) {
+      return await client.contextEpisode({
+        project: resolveProject(client, args.project),
+        ...(optionalString(args.workflowRunId) ? { workflowRunId: optionalString(args.workflowRunId)! } : {}),
+      });
+    },
+  },
+  {
+    name: "kxm_promote",
+    group: "context",
+    verb: "promote",
+    label: "Propose state promotion",
+    description: "Propose a change to one authoritative state key. Promotion requires durable evidence.",
+    parameters: {
+      type: "object",
+      properties: {
+        project: { type: "string", description: "Project identifier" },
+        key: { type: "string", description: "State key to promote" },
+        summary: { type: "string", description: "Promotion summary" },
+        authority: {
+          type: "string",
+          enum: ["policy", "instruction", "evidence", "hypothesis"],
+          description: "Authority class",
+        },
+        confidence: {
+          type: "string",
+          enum: ["verified", "probable", "uncertain"],
+          description: "Confidence level",
+        },
+        evidenceRefs: {
+          type: "array",
+          items: { type: "string" },
+          minItems: 1,
+          maxItems: 32,
+          description: "Evidence item references backing the promotion",
+        },
+      },
+      required: ["key", "summary", "authority", "confidence", "evidenceRefs"],
+      additionalProperties: false,
+    },
+    async execute(client, args) {
+      return await client.contextStatePropose({
+        project: resolveProject(client, args.project),
+        key: requiredString(args.key, "key"),
+        summary: requiredString(args.summary, "summary"),
+        authority: requiredString(args.authority, "authority") as any,
+        confidence: requiredString(args.confidence, "confidence") as any,
+        evidenceRefs: Array.isArray(args.evidenceRefs) ? (args.evidenceRefs as string[]) : [],
+      });
+    },
+  },
+];
+
+export const AGENT_COMMANDS_MAP: ReadonlyMap<string, AgentCommand> = new Map(
+  AGENT_COMMANDS.map((cmd) => [cmd.name, cmd]),
+);
+
+export function getMcpTools(): Array<{
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}> {
+  return AGENT_COMMANDS.map((cmd) => ({
+    name: cmd.name,
+    description: cmd.description,
+    inputSchema: cmd.parameters as unknown as Record<string, unknown>,
+  }));
+}
+
+export function getPiToolDefinitions(): Array<{
+  name: string;
+  label: string;
+  description: string;
+  parameters: Record<string, unknown>;
+}> {
+  return AGENT_COMMANDS.map((cmd) => ({
+    name: cmd.name,
+    label: cmd.label,
+    description: cmd.description,
+    parameters: cmd.parameters as unknown as Record<string, unknown>,
+  }));
+}
+
+export function getCliAgentCommands(): readonly AgentCommand[] {
+  return AGENT_COMMANDS;
+}
+
+export function mintAttemptToken(input: {
+  runId: string;
+  stepId?: string;
+  stepAttempt?: number;
+  assignmentId?: string;
+  attemptId?: string;
+  agentId?: string;
+  toolPolicy?: ToolPolicy;
+  stageId?: string;
+  attempt?: number;
+  allowedTools?: string[];
+  deniedTools?: string[];
+  preset?: string;
+}): string {
+  const toolPolicy: ToolPolicy | undefined = input.toolPolicy ?? (
+    input.allowedTools || input.deniedTools || input.preset
+      ? {
+          ...(input.preset ? { preset: input.preset } : {}),
+          ...(input.allowedTools ? { allow: input.allowedTools, allowedTools: input.allowedTools } : {}),
+          ...(input.deniedTools ? { deny: input.deniedTools, deniedTools: input.deniedTools } : {}),
+        }
+      : undefined
+  );
+  const payload: AttemptTokenPayload = {
+    schema: "kxm.attempt-token.v1",
+    runId: input.runId,
+    stepId: input.stepId ?? input.stageId ?? "step-1",
+    stepAttempt: input.stepAttempt ?? input.attempt ?? 1,
+    stageId: input.stageId ?? input.stepId ?? "step-1",
+    attempt: input.attempt ?? input.stepAttempt ?? 1,
+    assignmentId: input.assignmentId ?? `assign-${randomUUID()}`,
+    attemptId: input.attemptId ?? `attempt-${randomUUID()}`,
+    agentId: input.agentId ?? "agent-worker",
+    issuedAt: new Date().toISOString(),
+    ...(toolPolicy ? { toolPolicy } : {}),
+  };
+  return Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+
+export function parseAttemptToken(token: string): AttemptTokenPayload | undefined {
+  try {
+    const raw = Buffer.from(token.trim(), "base64url").toString("utf8");
+    const parsed = JSON.parse(raw);
+    if (
+      parsed
+      && typeof parsed === "object"
+      && parsed.schema === "kxm.attempt-token.v1"
+      && typeof parsed.runId === "string"
+    ) {
+      return parsed as AttemptTokenPayload;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+export function mintSessionToken(input?: {
+  sessionId?: string;
+  agentName?: string;
+  toolPolicy?: ToolPolicy;
+  preset?: string;
+  allowedTools?: string[];
+  deniedTools?: string[];
+}): string {
+  const toolPolicy: ToolPolicy | undefined = input?.toolPolicy ?? (
+    input?.allowedTools || input?.deniedTools || input?.preset
+      ? {
+          ...(input?.preset ? { preset: input.preset } : {}),
+          ...(input?.allowedTools ? { allow: input.allowedTools } : {}),
+          ...(input?.deniedTools ? { deny: input.deniedTools } : {}),
+        }
+      : undefined
+  );
+  const payload: SessionTokenPayload = {
+    schema: "kxm.session-token.v1",
+    sessionId: input?.sessionId ?? `session-${randomUUID()}`,
+    issuedAt: new Date().toISOString(),
+    ...(input?.agentName ? { agentName: input.agentName } : {}),
+    ...(toolPolicy ? { toolPolicy } : {}),
+  };
+  return Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+
+export function parseSessionToken(token: string): SessionTokenPayload | undefined {
+  try {
+    const raw = Buffer.from(token.trim(), "base64url").toString("utf8");
+    const parsed = JSON.parse(raw);
+    if (
+      parsed
+      && typeof parsed === "object"
+      && parsed.schema === "kxm.session-token.v1"
+      && typeof parsed.sessionId === "string"
+    ) {
+      return parsed as SessionTokenPayload;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+function matchToolPattern(pattern: string, toolName: string): boolean {
+  if (pattern === "*" || pattern === toolName) return true;
+  if (pattern.endsWith("*")) {
+    const prefix = pattern.slice(0, -1);
+    return toolName.startsWith(prefix);
+  }
+  return false;
+}
+
+export function isToolAllowed(commandName: string, policy?: ToolPolicy): boolean {
+  if (!policy) return true;
+  const canonical = commandName.startsWith("kxm_") ? commandName : `kxm_${commandName}`;
+  const bare = commandName.replace(/^kxm_/, "");
+
+  const denyList = policy.deny ?? policy.deniedTools;
+  if (Array.isArray(denyList)) {
+    for (const d of denyList) {
+      if (d === canonical || d === commandName || d === bare || matchToolPattern(d, canonical)) {
+        return false;
+      }
+    }
+  }
+
+  const allowList = policy.allow ?? policy.allowedTools;
+  if (Array.isArray(allowList) && allowList.length > 0) {
+    const matched = allowList.some(
+      (a) => a === canonical || a === commandName || a === bare || a === "*" || matchToolPattern(a, canonical),
+    );
+    if (!matched) return false;
+  }
+
+  if (policy.preset === "read-only") {
+    const mutating = [
+      "kxm_send",
+      "kxm_reply",
+      "kxm_cancel",
+      "kxm_fanout",
+      "kxm_workflow_checkpoint",
+      "kxm_workflow_record",
+      "kxm_workflow_wait",
+      "kxm_promote",
+    ];
+    if (mutating.includes(canonical)) return false;
+  }
+
+  return true;
+}
+
+export function enforceToolPolicy(
+  commandName: string,
+  env: NodeJS.ProcessEnv = process.env,
+): { allowed: boolean; error?: string; detail?: string } {
+  const attemptTokenRaw = env.KXM_ATTEMPT_TOKEN?.trim();
+  if (attemptTokenRaw) {
+    const attempt = parseAttemptToken(attemptTokenRaw);
+    if (!attempt) {
+      return { allowed: false, error: "attempt_token_invalid", detail: "KXM_ATTEMPT_TOKEN is malformed" };
+    }
+    if (!isToolAllowed(commandName, attempt.toolPolicy)) {
+      return {
+        allowed: false,
+        error: "tool_policy_denied",
+        detail: `command ${commandName} is denied by attempt tool policy`,
+      };
+    }
+    return { allowed: true };
+  }
+
+  const sessionTokenRaw = env.KXM_SESSION_TOKEN?.trim();
+  if (sessionTokenRaw) {
+    const session = parseSessionToken(sessionTokenRaw);
+    if (!session) {
+      return { allowed: false, error: "session_token_invalid", detail: "KXM_SESSION_TOKEN is malformed" };
+    }
+    if (!isToolAllowed(commandName, session.toolPolicy)) {
+      return {
+        allowed: false,
+        error: "tool_policy_denied",
+        detail: `command ${commandName} is denied by session tool policy`,
+      };
+    }
+    return { allowed: true };
+  }
+
+  return { allowed: true };
+}