@danielblomma/cortex-mcp 2.0.5 → 2.0.7

package/scaffold/mcp/src/core/workflow/capabilities.ts

@@ -0,0 +1,100 @@
+import { z } from "zod";
+
+/**
+ * Capability registry for the harness. A capability is a least-privilege
+ * profile referenced by a workflow stage's `capability` field. The
+ * pre-tool-use hook reads the active stage's capability and uses it to
+ * gate the agent's tool calls.
+ *
+ * The capability defines:
+ *   - read_globs    paths the agent may read (empty = no restriction)
+ *   - write_globs   paths the agent may modify (empty = read-only)
+ *   - tools_allowed which tool names the agent may call (empty = all)
+ *
+ * Glob patterns use minimatch syntax. The harness ships a default set
+ * keyed by the names referenced in default-workflows.ts; orgs can ship
+ * additional capabilities later via cortex-web sync.
+ */
+
+const slugSchema = z
+  .string()
+  .min(1)
+  .max(80)
+  .regex(/^[a-z0-9][a-z0-9-]*[a-z0-9]$/);
+
+export const capabilityDefinitionSchema = z.object({
+  name: slugSchema,
+  description: z.string().min(1).max(500),
+  read_globs: z.array(z.string().min(1)).default([]),
+  write_globs: z.array(z.string().min(1)).default([]),
+  tools_allowed: z.array(z.string().min(1)).default([]),
+});
+
+export type CapabilityDefinition = z.infer<typeof capabilityDefinitionSchema>;
+
+/**
+ * Default capability profiles that ship with Cortex. Names match the
+ * `capability` fields referenced by SECURE_BUILD_WORKFLOW.
+ *
+ * tools_allowed is intentionally empty for most profiles to mean
+ * "no per-tool restriction beyond what the file globs already imply".
+ * The hook layer checks file paths first, tool name second.
+ */
+export const DEFAULT_CAPABILITIES: Record<string, CapabilityDefinition> = {
+  planner: {
+    name: "planner",
+    description:
+      "Read-only profile for stages that produce planning artifacts. " +
+      "Can read the whole repo and call context tools, cannot modify any files.",
+    read_globs: ["**"],
+    write_globs: [],
+    tools_allowed: [],
+  },
+  reviewer: {
+    name: "reviewer",
+    description:
+      "Read-only profile for review stages. Same access as planner; the " +
+      "review artifact itself is written by the harness, not by an Edit tool.",
+    read_globs: ["**"],
+    write_globs: [],
+    tools_allowed: [],
+  },
+  builder: {
+    name: "builder",
+    description:
+      "Build profile. May edit source and test files but not config, " +
+      "lockfiles, CI workflows, or anything outside the obvious app surface.",
+    read_globs: ["**"],
+    write_globs: ["src/**", "tests/**", "test/**", "lib/**", "app/**", "components/**"],
+    tools_allowed: [],
+  },
+  tester: {
+    name: "tester",
+    description:
+      "Mutation/test profile. Read-only on production code, may edit only " +
+      "test files. Used by mutation-testing or coverage-improvement stages.",
+    read_globs: ["**"],
+    write_globs: ["tests/**", "test/**", "**/*.test.ts", "**/*.test.tsx", "**/*.test.mjs", "**/*.spec.ts"],
+    tools_allowed: [],
+  },
+  "security-reviewer": {
+    name: "security-reviewer",
+    description:
+      "Security review profile. Read-only across the repo. Produces a " +
+      "report artifact; no source modifications allowed.",
+    read_globs: ["**"],
+    write_globs: [],
+    tools_allowed: [],
+  },
+  human: {
+    name: "human",
+    description:
+      "Sentinel capability for human approval stages. The harness does not " +
+      "invoke an agent for this stage; the human writes the artifact directly. " +
+      "If a tool call somehow reaches the hook under this capability, it is " +
+      "blocked because no automation should be running.",
+    read_globs: [],
+    write_globs: [],
+    tools_allowed: [],
+  },
+};

package/scaffold/mcp/src/core/workflow/default-workflows.ts

@@ -0,0 +1,83 @@
+import type { WorkflowDefinition } from "./schemas.js";
+
+/**
+ * The default secure-build workflow that ships with Cortex. Organizations
+ * can override this from cortex-web later (Phase 2 of the harness rollout);
+ * until then this is the workflow every project gets out of the box.
+ */
+export const SECURE_BUILD_WORKFLOW: WorkflowDefinition = {
+  id: "secure-build",
+  description:
+    "Plan → Review → Build → Review → Mutation Tests → Security Review → Human Approval. " +
+    "The default Cortex Harness workflow for AI-driven development on production code.",
+  version: 1,
+  stages: [
+    {
+      name: "plan",
+      artifact: "plan.md",
+      reads: [],
+      required_fields: ["files_targeted", "constraints"],
+      capability: "planner",
+      description:
+        "Produce a step-by-step implementation plan grounded in the repo's rules and memory.",
+    },
+    {
+      name: "plan-review",
+      artifact: "plan-review.md",
+      reads: ["plan"],
+      required_fields: ["approved", "blocking_comments"],
+      capability: "reviewer",
+      description:
+        "Review the plan for architectural fit and rule compliance before any code is written.",
+    },
+    {
+      name: "build",
+      artifact: "changes.md",
+      reads: ["plan", "plan-review"],
+      required_fields: ["files_changed"],
+      capability: "builder",
+      description:
+        "Implement the approved plan. Produces the diff manifest used by the downstream reviewers.",
+    },
+    {
+      name: "build-review",
+      artifact: "build-review.md",
+      reads: ["plan", "changes"],
+      required_fields: ["approved", "blocking_comments"],
+      capability: "reviewer",
+      description:
+        "Review the implementation against the plan and the project's rules.",
+    },
+    {
+      name: "mutation",
+      artifact: "mutation-report.md",
+      reads: ["changes"],
+      required_fields: ["score", "survived"],
+      capability: "tester",
+      description:
+        "Run mutation tests on the changed files. Report score + surviving mutants.",
+    },
+    {
+      name: "security",
+      artifact: "security-report.md",
+      reads: ["changes"],
+      required_fields: ["findings", "severity_summary"],
+      capability: "security-reviewer",
+      description:
+        "Security review focused on the diff: injection, authn/authz, secrets, dependency risk.",
+    },
+    {
+      name: "approval",
+      artifact: "approval.md",
+      reads: ["plan", "changes", "build-review", "mutation", "security"],
+      required_fields: ["approved", "approver"],
+      capability: "human",
+      description:
+        "Human sign-off. Pulls every prior artifact for the approver to read; the approver writes the artifact.",
+    },
+  ],
+};
+
+export const DEFAULT_WORKFLOWS: Record<string, WorkflowDefinition> = {
+  [SECURE_BUILD_WORKFLOW.id]: SECURE_BUILD_WORKFLOW,
+};

package/scaffold/mcp/src/core/workflow/enforcement.ts

@@ -0,0 +1,206 @@
+import { isAbsolute, relative } from "node:path";
+import { minimatch } from "minimatch";
+import { readRunState } from "./artifact-io.js";
+import { DEFAULT_CAPABILITIES, type CapabilityDefinition } from "./capabilities.js";
+import { workflowDefinitionSchema, type WorkflowDefinition } from "./schemas.js";
+import { DEFAULT_WORKFLOWS } from "./default-workflows.js";
+
+/**
+ * Pre-tool-use enforcement for the harness. Pure function: takes the tool
+ * call shape Claude Code emits, looks up the active workflow stage's
+ * capability, returns allow/deny + reason. The hook wires this into the
+ * stdin/exit-code dance.
+ *
+ * "Active task" is identified by env var CORTEX_ACTIVE_TASK_ID. The
+ * harness sets this when invoking an agent for a stage; outside the
+ * harness, the env var is unset and this evaluator is a no-op (returns
+ * { allowed: true }).
+ */
+
+export type ToolCall = {
+  toolName: string;
+  toolInput: Record<string, unknown>;
+};
+
+export type EnforcementResult =
+  | { allowed: true; reason?: string }
+  | { allowed: false; reason: string };
+
+export type EvaluateOptions = {
+  cwd: string;
+  taskId: string;
+  call: ToolCall;
+  workflows?: Record<string, WorkflowDefinition>;
+  capabilities?: Record<string, CapabilityDefinition>;
+};
+
+/**
+ * Tool names that are pure mutations of the file system. Edits and writes
+ * gate against `write_globs`. Bash is treated as a mutation by default
+ * because we cannot reliably extract paths from arbitrary shell — agents
+ * running in restricted-write capabilities lose Bash unless the
+ * capability explicitly allow-lists it.
+ */
+const MUTATING_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+
+/**
+ * Tool names that read but do not mutate. Gate against `read_globs`.
+ */
+const READING_TOOLS = new Set(["Read", "Grep", "Glob", "NotebookRead"]);
+
+export function evaluateToolCall(options: EvaluateOptions): EnforcementResult {
+  const state = readRunState(options.cwd, options.taskId);
+  if (!state) {
+    return { allowed: true, reason: "no run state — harness not active" };
+  }
+  if (state.outcome !== "in_progress" || !state.current_stage) {
+    return {
+      allowed: true,
+      reason: `run not in progress (outcome=${state.outcome}) — no capability gate to apply`,
+    };
+  }
+
+  const workflows = options.workflows ?? DEFAULT_WORKFLOWS;
+  const workflow = workflows[state.workflow_id];
+  if (!workflow) {
+    return {
+      allowed: false,
+      reason: `unknown workflow_id ${state.workflow_id}; cannot resolve capability for current stage`,
+    };
+  }
+  // Validate so corrupt input doesn't slip through.
+  workflowDefinitionSchema.parse(workflow);
+
+  const stage = workflow.stages.find((s) => s.name === state.current_stage);
+  if (!stage) {
+    return {
+      allowed: false,
+      reason: `current stage ${state.current_stage} is not defined in workflow ${workflow.id}`,
+    };
+  }
+
+  if (!stage.capability) {
+    return { allowed: true, reason: "stage has no capability declared" };
+  }
+
+  const capabilities = options.capabilities ?? DEFAULT_CAPABILITIES;
+  const capability = capabilities[stage.capability];
+  if (!capability) {
+    return {
+      allowed: false,
+      reason: `capability ${stage.capability} (referenced by stage ${stage.name}) is not in the registry`,
+    };
+  }
+
+  return evaluateAgainstCapability(capability, options.call, options.cwd);
+}
+
+function evaluateAgainstCapability(
+  capability: CapabilityDefinition,
+  call: ToolCall,
+  cwd: string,
+): EnforcementResult {
+  // 1. tools_allowed: empty = no restriction; otherwise tool must be in the list.
+  if (
+    capability.tools_allowed.length > 0 &&
+    !capability.tools_allowed.includes(call.toolName)
+  ) {
+    return {
+      allowed: false,
+      reason: `capability ${capability.name} does not allow tool ${call.toolName}`,
+    };
+  }
+
+  const isMutation = MUTATING_TOOLS.has(call.toolName);
+  const isRead = READING_TOOLS.has(call.toolName);
+
+  // Bash is special: with restricted write_globs we have to assume the
+  // worst (since the shell can write anywhere). Block unless capability
+  // explicitly allow-lists Bash via tools_allowed.
+  if (call.toolName === "Bash") {
+    const isAllowedViaToolList = capability.tools_allowed.includes("Bash");
+    const writesUnrestricted = capability.write_globs.length === 0;
+    if (writesUnrestricted && !isAllowedViaToolList) {
+      return {
+        allowed: false,
+        reason: `capability ${capability.name} is read-only; Bash can mutate the filesystem and is not allow-listed`,
+      };
+    }
+    return { allowed: true };
+  }
+
+  if (isMutation) {
+    if (capability.write_globs.length === 0) {
+      return {
+        allowed: false,
+        reason: `capability ${capability.name} is read-only; ${call.toolName} cannot run`,
+      };
+    }
+    const targetPath = extractFilePath(call.toolInput);
+    if (!targetPath) {
+      return {
+        allowed: false,
+        reason: `${call.toolName} did not include a file_path; cannot verify against capability ${capability.name}`,
+      };
+    }
+    const relPath = toRepoRelative(cwd, targetPath);
+    if (!matchesAnyGlob(relPath, capability.write_globs)) {
+      return {
+        allowed: false,
+        reason: `path ${relPath} is outside capability ${capability.name}'s write_globs (${capability.write_globs.join(", ")})`,
+      };
+    }
+    return { allowed: true };
+  }
+
+  if (isRead) {
+    if (capability.read_globs.length === 0) {
+      // No reads allowed at all — only the human capability lands here.
+      return {
+        allowed: false,
+        reason: `capability ${capability.name} does not permit any read operations`,
+      };
+    }
+    const targetPath = extractFilePath(call.toolInput);
+    if (!targetPath) {
+      // Some read tools (Grep, Glob) operate on the whole repo; allow
+      // through if the capability has any read access at all.
+      return { allowed: true };
+    }
+    const relPath = toRepoRelative(cwd, targetPath);
+    if (!matchesAnyGlob(relPath, capability.read_globs)) {
+      return {
+        allowed: false,
+        reason: `path ${relPath} is outside capability ${capability.name}'s read_globs (${capability.read_globs.join(", ")})`,
+      };
+    }
+    return { allowed: true };
+  }
+
+  // Unknown tool — fall through to allow if not explicitly restricted.
+  return { allowed: true };
+}
+
+function extractFilePath(toolInput: Record<string, unknown>): string | null {
+  const candidates = ["file_path", "path", "notebook_path"];
+  for (const key of candidates) {
+    const value = toolInput[key];
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return null;
+}
+
+function toRepoRelative(cwd: string, targetPath: string): string {
+  if (!isAbsolute(targetPath)) return targetPath;
+  const rel = relative(cwd, targetPath);
+  // If the path is outside the repo, return the absolute form so glob
+  // matches (which expect repo-relative) reliably miss.
+  if (rel.startsWith("..")) return targetPath;
+  return rel;
+}
+
+function matchesAnyGlob(path: string, globs: string[]): boolean {
+  return globs.some((pattern) =>
+    minimatch(path, pattern, { dot: true, nocase: false }),
+  );
+}

package/scaffold/mcp/src/core/workflow/envelope.ts

@@ -0,0 +1,220 @@
+import { readFileSync } from "node:fs";
+import { artifactPath, readRunState } from "./artifact-io.js";
+import { workflowDefinitionSchema, type WorkflowDefinition } from "./schemas.js";
+
+/**
+ * Composes the prompt one stage's agent sees. Pure function over the
+ * persisted run state plus the workflow definition — no agent invocation,
+ * no MCP, no daemon. The harness later wraps this into an MCP call or a
+ * CLI invocation.
+ *
+ * Design: the agent gets four sections in a fixed order so it can anchor
+ * on them reliably:
+ *
+ *   TASK     — what the developer asked for, copied verbatim from RunState
+ *   STAGE    — what *this* stage is supposed to produce
+ *   HANDOFFS — every prior-stage artifact the new stage declared in `reads`,
+ *              inlined raw (frontmatter + body) so the agent sees structured
+ *              outcomes alongside the reasoning
+ *   OUTPUT   — exact frontmatter contract the agent must satisfy plus the
+ *              expected artifact filename
+ *
+ * Capability constraints (which files the agent may edit, which tools it
+ * may call) are NOT enforced by the prompt — they're enforced by hooks
+ * downstream. The capability key is surfaced in the prompt as a label so
+ * the agent knows under what role it's running, but the real gate is
+ * pre-tool-use.
+ */
+
+export type ComposedEnvelope = {
+  /** The full prompt the agent will receive. */
+  prompt: string;
+  /** Expected artifact filename the agent must produce. */
+  expectedArtifact: string;
+  /** Frontmatter keys the agent must populate (beyond stage/status/references). */
+  requiredFields: string[];
+  /** Capability key the stage runs under (informational). */
+  capability: string | null;
+};
+
+export type ComposeStageEnvelopeOptions = {
+  cwd: string;
+  taskId: string;
+  workflow: WorkflowDefinition;
+  /**
+   * Defaults to the run's current_stage. Pass an explicit stageName when
+   * dry-running an envelope without driving state forward.
+   */
+  stageName?: string;
+};
+
+export function composeStageEnvelope(
+  options: ComposeStageEnvelopeOptions,
+): ComposedEnvelope {
+  const workflow = workflowDefinitionSchema.parse(options.workflow);
+  const state = readRunState(options.cwd, options.taskId);
+  if (!state) {
+    throw new Error(
+      `No run state found for task ${options.taskId}. Call createRun() first.`,
+    );
+  }
+  if (state.workflow_id !== workflow.id) {
+    throw new Error(
+      `Workflow mismatch: run was started with ${state.workflow_id}, envelope was composed with ${workflow.id}`,
+    );
+  }
+
+  const stageName = options.stageName ?? state.current_stage;
+  if (!stageName) {
+    throw new Error(
+      `Run ${options.taskId} is not at any stage (outcome=${state.outcome}). Cannot compose envelope.`,
+    );
+  }
+  const stage = workflow.stages.find((s) => s.name === stageName);
+  if (!stage) {
+    throw new Error(
+      `Stage ${stageName} is not defined in workflow ${workflow.id}`,
+    );
+  }
+
+  const handoffs: string[] = [];
+  for (const readName of stage.reads) {
+    const priorStage = workflow.stages.find((s) => s.name === readName);
+    if (!priorStage) {
+      throw new Error(
+        `Stage ${stageName} declares reads from unknown stage ${readName}`,
+      );
+    }
+    const priorRecord = state.stages.find((r) => r.name === readName);
+    if (!priorRecord || priorRecord.status === "pending" || !priorRecord.artifact) {
+      throw new Error(
+        `Stage ${stageName} requires artifact from ${readName}, but it has not been produced yet`,
+      );
+    }
+    const path = artifactPath(options.cwd, options.taskId, priorRecord.artifact);
+    let raw: string;
+    try {
+      raw = readFileSync(path, "utf8");
+    } catch (err) {
+      throw new Error(
+        `Failed to read handoff artifact for ${readName} at ${path}: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
+    handoffs.push(renderHandoff(readName, priorRecord.artifact, raw));
+  }
+
+  const requiredFields = stage.required_fields;
+  const capability = stage.capability ?? null;
+
+  const prompt = renderPrompt({
+    taskDescription: state.task_description,
+    workflowId: workflow.id,
+    workflowDescription: workflow.description,
+    stageName: stage.name,
+    stageDescription: stage.description,
+    expectedArtifact: stage.artifact,
+    requiredFields,
+    capability,
+    handoffs,
+  });
+
+  return {
+    prompt,
+    expectedArtifact: stage.artifact,
+    requiredFields,
+    capability,
+  };
+}
+
+function renderHandoff(
+  stageName: string,
+  artifactName: string,
+  rawArtifact: string,
+): string {
+  return [
+    `--- handoff:${stageName} (${artifactName}) ---`,
+    rawArtifact.trim(),
+    `--- end handoff:${stageName} ---`,
+  ].join("\n");
+}
+
+type RenderPromptOptions = {
+  taskDescription: string;
+  workflowId: string;
+  workflowDescription: string;
+  stageName: string;
+  stageDescription: string;
+  expectedArtifact: string;
+  requiredFields: string[];
+  capability: string | null;
+  handoffs: string[];
+};
+
+function renderPrompt(o: RenderPromptOptions): string {
+  const sections: string[] = [];
+
+  sections.push(
+    [
+      `# TASK`,
+      ``,
+      o.taskDescription.trim(),
+      ``,
+      `Workflow: ${o.workflowId} — ${o.workflowDescription}`,
+    ].join("\n"),
+  );
+
+  sections.push(
+    [
+      `# STAGE: ${o.stageName}`,
+      ``,
+      o.stageDescription.trim(),
+      ``,
+      o.capability
+        ? `Running under capability: \`${o.capability}\` (file and tool restrictions are enforced by Cortex hooks at tool-use time, not by you).`
+        : `No capability constraint declared for this stage.`,
+    ].join("\n"),
+  );
+
+  if (o.handoffs.length === 0) {
+    sections.push(
+      [`# HANDOFFS`, ``, `_No prior-stage artifacts; this is the first stage._`].join(
+        "\n",
+      ),
+    );
+  } else {
+    sections.push(
+      [
+        `# HANDOFFS`,
+        ``,
+        `The following stages have already run. Each artifact below is the complete file as it lives on disk; use the frontmatter for structured outcomes and the body for reasoning.`,
+        ``,
+        ...o.handoffs,
+      ].join("\n"),
+    );
+  }
+
+  const requiredLines =
+    o.requiredFields.length === 0
+      ? `_No additional required fields beyond the harness defaults._`
+      : o.requiredFields.map((f) => `- \`${f}\``).join("\n");
+
+  sections.push(
+    [
+      `# OUTPUT`,
+      ``,
+      `Produce a single markdown file named \`${o.expectedArtifact}\` with YAML frontmatter on top.`,
+      ``,
+      `Required frontmatter fields (in addition to \`stage\`, \`status\`, \`references\`, \`written_at\` which the harness manages):`,
+      ``,
+      requiredLines,
+      ``,
+      `Body: clear, well-structured markdown explaining your reasoning. Cite handoff artifacts by stage name when relevant.`,
+      ``,
+      `If you cannot complete this stage (missing context, blocking concern, conflicting prior decisions), set \`status: blocked\` in frontmatter and explain why in the body — do not fabricate work.`,
+    ].join("\n"),
+  );
+
+  return sections.join("\n\n");
+}

package/scaffold/mcp/src/core/workflow/index.ts

@@ -0,0 +1,9 @@
+export * from "./schemas.js";
+export * from "./artifact-io.js";
+export * from "./run-lifecycle.js";
+export * from "./envelope.js";
+export * from "./default-workflows.js";
+export * from "./mcp-tools.js";
+export * from "./capabilities.js";
+export * from "./enforcement.js";
+export * from "./synced-registry.js";