@danielblomma/cortex-mcp 2.0.5 → 2.0.6

package/scaffold/mcp/src/core/workflow/mcp-tools.ts

@@ -0,0 +1,208 @@
+import { z } from "zod";
+import { advanceStage, createRun, getRunState } from "./run-lifecycle.js";
+import { composeStageEnvelope } from "./envelope.js";
+import { DEFAULT_WORKFLOWS } from "./default-workflows.js";
+import {
+  stageStatusSchema,
+  type StageStatus,
+  type WorkflowDefinition,
+} from "./schemas.js";
+
+/**
+ * Pure runner functions that back the cortex.workflow.* MCP tools.
+ * Kept separate from server.ts so they can be unit-tested without spinning
+ * up an MCP server. server.ts is a thin shim that registers each runner
+ * under its tool name and serializes the result through buildToolResult.
+ */
+
+const slugSchema = z
+  .string()
+  .min(1)
+  .max(80)
+  .regex(/^[a-z0-9][a-z0-9-]*[a-z0-9]$/);
+
+export const WorkflowStartInput = z.object({
+  task_id: slugSchema,
+  task_description: z.string().min(1).max(2000),
+  workflow_id: slugSchema.default("secure-build"),
+});
+export type WorkflowStartInputT = z.infer<typeof WorkflowStartInput>;
+
+export const WorkflowAdvanceInput = z.object({
+  task_id: slugSchema,
+  /** Required for safety: must equal the run's current_stage. */
+  stage: slugSchema,
+  /**
+   * Stage frontmatter as a free-form object. Stage / status / references /
+   * written_at are managed by the harness and may be omitted (or, if set,
+   * are overridden). Stage-specific fields like `approved` or `score` are
+   * passed through.
+   */
+  frontmatter: z.record(z.string(), z.unknown()).default({}),
+  body: z.string().min(1),
+  /** Final stage status. Defaults to "complete". Use "blocked" or "failed" to halt the run. */
+  status: stageStatusSchema.optional(),
+  /** Optional structured outcome surfaced into state.json for fast lookup by later stages. */
+  outcome: z.record(z.string(), z.unknown()).optional(),
+});
+export type WorkflowAdvanceInputT = z.infer<typeof WorkflowAdvanceInput>;
+
+export const WorkflowStatusInput = z.object({
+  task_id: slugSchema,
+});
+export type WorkflowStatusInputT = z.infer<typeof WorkflowStatusInput>;
+
+export const WorkflowEnvelopeInput = z.object({
+  task_id: slugSchema,
+  /** Defaults to the run's current stage. */
+  stage: slugSchema.optional(),
+});
+export type WorkflowEnvelopeInputT = z.infer<typeof WorkflowEnvelopeInput>;
+
+/**
+ * Resolves the project root. The MCP server is started with cwd =
+ * project root and CORTEX_PROJECT_ROOT set to the same value (see
+ * bin/cortex.mjs `mcp` command). Tests pass cwd explicitly.
+ */
+export function resolveProjectRoot(): string {
+  const fromEnv = process.env.CORTEX_PROJECT_ROOT?.trim();
+  if (fromEnv) return fromEnv;
+  return process.cwd();
+}
+
+export type WorkflowToolContext = {
+  cwd: string;
+  workflows?: Record<string, WorkflowDefinition>;
+};
+
+function resolveWorkflow(
+  workflowId: string,
+  registry: Record<string, WorkflowDefinition> | undefined,
+): WorkflowDefinition {
+  const workflows = registry ?? DEFAULT_WORKFLOWS;
+  const workflow = workflows[workflowId];
+  if (!workflow) {
+    throw new Error(
+      `Unknown workflow_id: ${workflowId}. Available: ${Object.keys(workflows).join(", ") || "<none>"}`,
+    );
+  }
+  return workflow;
+}
+
+export function runWorkflowStart(
+  input: WorkflowStartInputT,
+  ctx: WorkflowToolContext,
+) {
+  const workflow = resolveWorkflow(input.workflow_id, ctx.workflows);
+  const state = createRun({
+    cwd: ctx.cwd,
+    taskId: input.task_id,
+    workflow,
+    taskDescription: input.task_description,
+  });
+  const envelope = composeStageEnvelope({
+    cwd: ctx.cwd,
+    taskId: input.task_id,
+    workflow,
+  });
+  return {
+    state,
+    envelope,
+  };
+}
+
+export function runWorkflowAdvance(
+  input: WorkflowAdvanceInputT,
+  ctx: WorkflowToolContext,
+) {
+  const state = getRunState(ctx.cwd, input.task_id);
+  if (!state) {
+    throw new Error(
+      `No run state found for task ${input.task_id}. Call cortex.workflow.start first.`,
+    );
+  }
+  const workflow = resolveWorkflow(state.workflow_id, ctx.workflows);
+  const stage = workflow.stages.find((s) => s.name === input.stage);
+  if (!stage) {
+    throw new Error(`Stage ${input.stage} is not defined in workflow ${workflow.id}`);
+  }
+
+  const finalStatus: StageStatus = input.status ?? "complete";
+
+  const nextState = advanceStage({
+    cwd: ctx.cwd,
+    taskId: input.task_id,
+    workflow,
+    stageName: input.stage,
+    artifactName: stage.artifact,
+    frontmatter: {
+      ...input.frontmatter,
+      stage: input.stage,
+      status: finalStatus,
+      references:
+        (Array.isArray((input.frontmatter as Record<string, unknown>).references)
+          ? ((input.frontmatter as Record<string, unknown>).references as unknown[])
+              .filter((v): v is string => typeof v === "string")
+          : null) ?? deriveReferencesFromReads(stage.reads, workflow),
+    },
+    body: input.body,
+    outcome: input.outcome,
+    status: finalStatus,
+  });
+
+  // If the run is still going, also return the next envelope so the caller
+  // can immediately know what comes next without a follow-up status round-trip.
+  let nextEnvelope: ReturnType<typeof composeStageEnvelope> | null = null;
+  if (nextState.outcome === "in_progress" && nextState.current_stage) {
+    nextEnvelope = composeStageEnvelope({
+      cwd: ctx.cwd,
+      taskId: input.task_id,
+      workflow,
+    });
+  }
+
+  return {
+    state: nextState,
+    next_envelope: nextEnvelope,
+  };
+}
+
+function deriveReferencesFromReads(
+  reads: string[],
+  workflow: WorkflowDefinition,
+): string[] {
+  const refs: string[] = [];
+  for (const readName of reads) {
+    const stage = workflow.stages.find((s) => s.name === readName);
+    if (stage) refs.push(stage.artifact);
+  }
+  return refs;
+}
+
+export function runWorkflowStatus(
+  input: WorkflowStatusInputT,
+  ctx: WorkflowToolContext,
+) {
+  const state = getRunState(ctx.cwd, input.task_id);
+  return { state };
+}
+
+export function runWorkflowEnvelope(
+  input: WorkflowEnvelopeInputT,
+  ctx: WorkflowToolContext,
+) {
+  const state = getRunState(ctx.cwd, input.task_id);
+  if (!state) {
+    throw new Error(
+      `No run state found for task ${input.task_id}. Call cortex.workflow.start first.`,
+    );
+  }
+  const workflow = resolveWorkflow(state.workflow_id, ctx.workflows);
+  const envelope = composeStageEnvelope({
+    cwd: ctx.cwd,
+    taskId: input.task_id,
+    workflow,
+    stageName: input.stage,
+  });
+  return { envelope };
+}

package/scaffold/mcp/src/core/workflow/run-lifecycle.ts

@@ -0,0 +1,165 @@
+import {
+  readRunState,
+  writeRunState,
+  writeStageArtifact,
+} from "./artifact-io.js";
+import {
+  runStateSchema,
+  stageArtifactFrontmatterSchema,
+  workflowDefinitionSchema,
+  type RunState,
+  type StageRecord,
+  type StageStatus,
+  type WorkflowDefinition,
+} from "./schemas.js";
+
+/**
+ * Lifecycle helpers for one workflow run. The harness composes envelopes
+ * and invokes agents elsewhere; these primitives only manipulate the
+ * persisted state under .agents/<task-id>/. Pure functions on top of
+ * artifact-io.ts so unit tests can hit them without spawning agents.
+ */
+
+export type CreateRunOptions = {
+  cwd: string;
+  taskId: string;
+  workflow: WorkflowDefinition;
+  taskDescription: string;
+  now?: () => Date;
+};
+
+export function createRun(options: CreateRunOptions): RunState {
+  const workflow = workflowDefinitionSchema.parse(options.workflow);
+  const now = (options.now ?? (() => new Date()))();
+  const startedAt = now.toISOString();
+
+  const stages: StageRecord[] = workflow.stages.map((stage) => ({
+    name: stage.name,
+    status: "pending" as StageStatus,
+  }));
+
+  const state: RunState = {
+    schema_version: 1,
+    task_id: options.taskId,
+    workflow_id: workflow.id,
+    workflow_version: workflow.version,
+    task_description: options.taskDescription,
+    current_stage: workflow.stages[0].name,
+    outcome: "in_progress",
+    started_at: startedAt,
+    completed_at: null,
+    stages,
+  };
+
+  // Validate before write so a malformed input never reaches disk.
+  const validated = runStateSchema.parse(state);
+  writeRunState(options.cwd, validated);
+  return validated;
+}
+
+export function getRunState(cwd: string, taskId: string): RunState | null {
+  return readRunState(cwd, taskId);
+}
+
+export type AdvanceStageOptions = {
+  cwd: string;
+  taskId: string;
+  workflow: WorkflowDefinition;
+  /** The stage we just finished. Must equal state.current_stage. */
+  stageName: string;
+  /** Filename of the artifact to write (e.g. "plan.md"). */
+  artifactName: string;
+  /** Frontmatter for the artifact, minus the auto-injected `written_at`. */
+  frontmatter: Omit<
+    import("./schemas.js").StageArtifactFrontmatter,
+    "written_at"
+  > & { written_at?: string };
+  /** Markdown body of the artifact. */
+  body: string;
+  /** Per-stage outcome surfaced into state.json for fast lookup. */
+  outcome?: Record<string, unknown>;
+  /** Final status to record for this stage. Defaults to "complete". */
+  status?: StageStatus;
+  now?: () => Date;
+};
+
+/**
+ * Marks `stageName` as finished, writes its artifact under .agents/<task-id>/,
+ * and advances `current_stage` to the next stage (or marks the run complete
+ * if this was the final stage). Idempotent only at the artifact layer —
+ * calling twice for the same stage will overwrite the artifact and the
+ * state.json record.
+ */
+export function advanceStage(options: AdvanceStageOptions): RunState {
+  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}, advance was called with ${workflow.id}`,
+    );
+  }
+  if (state.current_stage !== options.stageName) {
+    throw new Error(
+      `Cannot advance stage ${options.stageName}: run is currently at ${
+        state.current_stage ?? "<finished>"
+      }`,
+    );
+  }
+
+  const now = (options.now ?? (() => new Date()))();
+  const completedAt = now.toISOString();
+
+  const frontmatter = stageArtifactFrontmatterSchema.parse({
+    ...options.frontmatter,
+    stage: options.stageName,
+    written_at: options.frontmatter.written_at ?? completedAt,
+  });
+  writeStageArtifact(
+    options.cwd,
+    options.taskId,
+    options.artifactName,
+    frontmatter,
+    options.body,
+  );
+
+  const stageIndex = workflow.stages.findIndex((s) => s.name === options.stageName);
+  const nextStage = workflow.stages[stageIndex + 1] ?? null;
+  const finalStatus = options.status ?? "complete";
+
+  const updatedStages: StageRecord[] = state.stages.map((record) => {
+    if (record.name !== options.stageName) return record;
+    return {
+      ...record,
+      status: finalStatus,
+      artifact: options.artifactName,
+      started_at: record.started_at ?? state.started_at,
+      completed_at: completedAt,
+      outcome: options.outcome,
+    };
+  });
+
+  const runOutcome: RunState["outcome"] =
+    finalStatus === "blocked" || finalStatus === "failed"
+      ? finalStatus
+      : nextStage
+        ? "in_progress"
+        : "complete";
+
+  const next: RunState = {
+    ...state,
+    current_stage:
+      runOutcome === "in_progress" && nextStage ? nextStage.name : null,
+    outcome: runOutcome,
+    completed_at: runOutcome === "in_progress" ? null : completedAt,
+    stages: updatedStages,
+  };
+
+  const validated = runStateSchema.parse(next);
+  writeRunState(options.cwd, validated);
+  return validated;
+}

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

@@ -0,0 +1,125 @@
+import { z } from "zod";
+
+/**
+ * Schemas for the Cortex Harness workflow engine.
+ *
+ * See docs/harness-vision.md for the design. In short:
+ *
+ *   .agents/<task-id>/
+ *     plan.md            # frontmatter + body
+ *     review.md
+ *     changes.md
+ *     mutation-report.md
+ *     security-report.md
+ *     state.json         # current run state
+ *
+ * All artifacts are markdown with YAML frontmatter; state.json is the only
+ * JSON file. Both are tracked in git so a PR carries the evidence trail.
+ */
+
+const slugSchema = z
+  .string()
+  .min(1)
+  .max(80)
+  .regex(
+    /^[a-z0-9][a-z0-9-]*[a-z0-9]$/,
+    "Must be lowercase alphanumeric with hyphens (no leading/trailing hyphen)",
+  );
+
+/**
+ * Static definition of a single stage in a workflow. Authored at the
+ * organization level (in cortex-web later) and synced down to projects.
+ */
+export const stageDefinitionSchema = z.object({
+  name: slugSchema,
+  artifact: z.string().min(1).regex(/^[a-z0-9][a-z0-9-]*\.md$/),
+  /** Stage names this stage may read artifacts from. Empty = no inputs. */
+  reads: z.array(slugSchema).default([]),
+  /** Required frontmatter fields the produced artifact must populate. */
+  required_fields: z.array(z.string().min(1)).default([]),
+  /** Capability key the stage runs under. References a separate capability registry. */
+  capability: z.string().min(1).optional(),
+  /** Human-readable summary surfaced in dashboards and audit. */
+  description: z.string().min(1).max(500),
+});
+
+export type StageDefinition = z.infer<typeof stageDefinitionSchema>;
+
+/**
+ * A complete workflow: ordered stages plus a stable identifier.
+ */
+export const workflowDefinitionSchema = z.object({
+  id: slugSchema,
+  description: z.string().min(1).max(500),
+  version: z.number().int().min(1),
+  stages: z.array(stageDefinitionSchema).min(1),
+});
+
+export type WorkflowDefinition = z.infer<typeof workflowDefinitionSchema>;
+
+/**
+ * Status of a single stage inside a run.
+ */
+export const stageStatusSchema = z.enum([
+  "pending",
+  "in_progress",
+  "complete",
+  "blocked",
+  "failed",
+]);
+
+export type StageStatus = z.infer<typeof stageStatusSchema>;
+
+/**
+ * Per-stage record inside state.json. Holds outcome metadata that the next
+ * stage's envelope composer needs without re-parsing every artifact.
+ */
+export const stageRecordSchema = z.object({
+  name: slugSchema,
+  status: stageStatusSchema,
+  artifact: z.string().min(1).optional(),
+  started_at: z.string().datetime().optional(),
+  completed_at: z.string().datetime().optional(),
+  /** Frontmatter outcome surfaced for fast lookup (e.g. approved=true on review). */
+  outcome: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type StageRecord = z.infer<typeof stageRecordSchema>;
+
+/**
+ * The full state of one workflow run, persisted as
+ * .agents/<task-id>/state.json. Written only on stage boundaries so it
+ * never churns mid-tick.
+ */
+export const runStateSchema = z.object({
+  schema_version: z.literal(1),
+  task_id: slugSchema,
+  workflow_id: slugSchema,
+  workflow_version: z.number().int().min(1),
+  task_description: z.string().min(1).max(2000),
+  current_stage: slugSchema.nullable(),
+  outcome: z.enum(["in_progress", "complete", "failed", "blocked"]),
+  started_at: z.string().datetime(),
+  completed_at: z.string().datetime().nullable(),
+  stages: z.array(stageRecordSchema).min(1),
+});
+
+export type RunState = z.infer<typeof runStateSchema>;
+
+/**
+ * The required-by-convention frontmatter shape every stage artifact carries.
+ * Stages may add additional structured fields; these four are the ones the
+ * harness itself relies on.
+ */
+export const stageArtifactFrontmatterSchema = z
+  .object({
+    stage: slugSchema,
+    status: stageStatusSchema,
+    /** Sister-artifacts this artifact references (relative filenames). */
+    references: z.array(z.string().min(1)).default([]),
+    /** ISO 8601; injected by the harness, not the agent. */
+    written_at: z.string().datetime(),
+  })
+  .passthrough();
+
+export type StageArtifactFrontmatter = z.infer<typeof stageArtifactFrontmatterSchema>;

package/scaffold/mcp/src/hooks/pre-tool-use.ts

@@ -8,6 +8,7 @@ import {
   resolveDaemonEntry,
   sendHeartbeat,
 } from "./shared.js";
+import { evaluateToolCall } from "../core/workflow/enforcement.js";
 
 /**
  * PreToolUse hook for Claude Code.
@@ -46,6 +47,35 @@ async function main(): Promise<void> {
     });
   }
 
+  // Workflow capability gate. Runs before policy.check so harness-level
+  // restrictions block before the daemon's general policy machinery sees
+  // the call. No-op when CORTEX_ACTIVE_TASK_ID is unset.
+  const activeTaskId = process.env.CORTEX_ACTIVE_TASK_ID?.trim();
+  if (activeTaskId) {
+    try {
+      const verdict = evaluateToolCall({
+        cwd,
+        taskId: activeTaskId,
+        call: { toolName: tool, toolInput: input.tool_input ?? {} },
+      });
+      if (!verdict.allowed) {
+        process.stderr.write(
+          `[cortex] Blocked by harness capability: ${verdict.reason}\n`,
+        );
+        process.exit(2);
+      }
+    } catch (err) {
+      // Capability evaluation should never crash the hook — if it does,
+      // log and fall through to the existing policy.check rather than
+      // accidentally blocking a legitimate tool.
+      process.stderr.write(
+        `[cortex] capability evaluation failed (${
+          err instanceof Error ? err.message : String(err)
+        }); deferring to policy.check\n`,
+      );
+    }
+  }
+
   const payload: PolicyCheckPayload = {
     tool,
     cwd,

package/scaffold/mcp/src/server.ts

@@ -11,6 +11,17 @@ import {
   getSessionEventHook,
   loadPlugins,
 } from "./plugin.js";
+import {
+  WorkflowStartInput,
+  WorkflowAdvanceInput,
+  WorkflowStatusInput,
+  WorkflowEnvelopeInput,
+  resolveProjectRoot,
+  runWorkflowAdvance,
+  runWorkflowEnvelope,
+  runWorkflowStart,
+  runWorkflowStatus,
+} from "./core/workflow/mcp-tools.js";
 
 type ToolPayload = Record<string, unknown>;
 
@@ -322,6 +333,70 @@ function registerTools(server: McpServer): void {
       return reloadContextGraph(parsed.force);
     })
   );
+
+  server.registerTool(
+    "cortex.workflow.start",
+    {
+      description:
+        "Start a Cortex Harness workflow run for a task. Creates .agents/<task_id>/state.json and returns the first stage's envelope (the prompt the agent should answer).",
+      inputSchema: WorkflowStartInput,
+    },
+    async (input) => executeInstrumentedTool(
+      "cortex.workflow.start",
+      input,
+      async () => runWorkflowStart(WorkflowStartInput.parse(input ?? {}), {
+        cwd: resolveProjectRoot(),
+      }) as ToolPayload,
+    ),
+  );
+
+  server.registerTool(
+    "cortex.workflow.advance",
+    {
+      description:
+        "Complete the current stage of a workflow run by writing its artifact and advancing the run pointer. Returns the new run state plus the next stage's envelope (or null when the run is finished, blocked, or failed).",
+      inputSchema: WorkflowAdvanceInput,
+    },
+    async (input) => executeInstrumentedTool(
+      "cortex.workflow.advance",
+      input,
+      async () => runWorkflowAdvance(WorkflowAdvanceInput.parse(input ?? {}), {
+        cwd: resolveProjectRoot(),
+      }) as ToolPayload,
+    ),
+  );
+
+  server.registerTool(
+    "cortex.workflow.status",
+    {
+      description:
+        "Read the current run state for a task (current stage, completed stages, outcome). Returns null state when no run exists for the given task_id.",
+      inputSchema: WorkflowStatusInput,
+    },
+    async (input) => executeInstrumentedTool(
+      "cortex.workflow.status",
+      input,
+      async () => runWorkflowStatus(WorkflowStatusInput.parse(input ?? {}), {
+        cwd: resolveProjectRoot(),
+      }) as ToolPayload,
+    ),
+  );
+
+  server.registerTool(
+    "cortex.workflow.envelope",
+    {
+      description:
+        "Compose the prompt envelope for a workflow stage without advancing the run. Defaults to the run's current_stage; pass `stage` to dry-run a different stage.",
+      inputSchema: WorkflowEnvelopeInput,
+    },
+    async (input) => executeInstrumentedTool(
+      "cortex.workflow.envelope",
+      input,
+      async () => runWorkflowEnvelope(WorkflowEnvelopeInput.parse(input ?? {}), {
+        cwd: resolveProjectRoot(),
+      }) as ToolPayload,
+    ),
+  );
 }
 
 let shutdownCalled = false;