@danielblomma/cortex-mcp 2.0.5 → 2.0.7

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

@@ -0,0 +1,215 @@
+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 { loadSyncedWorkflows } from "./synced-registry.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 {
+  // When the caller passes an explicit registry, it wins outright (used
+  // by tests). Otherwise we merge bundled defaults with the org-authored
+  // workflows the daemon has synced into ~/.cortex/workflows.local.json,
+  // with the synced ones taking precedence on workflow_id collisions so
+  // org overrides actually override.
+  const workflows =
+    registry ?? { ...DEFAULT_WORKFLOWS, ...loadSyncedWorkflows() };
+  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/core/workflow/synced-registry.ts

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { workflowDefinitionSchema, type WorkflowDefinition } from "./schemas.js";
+
+/**
+ * Read side of the org-workflow sync cache. The daemon's
+ * workflow-sync-checker writes ~/.cortex/workflows.local.json; this
+ * module reads it. Kept in core/workflow/ rather than daemon/ so
+ * mcp-tools.ts can consult the cache without depending on daemon code.
+ *
+ * Each entry is validated against workflowDefinitionSchema before being
+ * surfaced — if the cache file is corrupt or contains stale shapes from
+ * an older daemon, those entries are silently dropped rather than
+ * crashing the read.
+ */
+
+export const SYNCED_WORKFLOWS_FILENAME = "workflows.local.json";
+
+type LocalWorkflowRecord = {
+  workflow_id: string;
+  version: number;
+  updated_at: string;
+  definition: unknown;
+};
+
+type LocalWorkflowsState = {
+  workflows?: Record<string, LocalWorkflowRecord>;
+};
+
+export function syncedWorkflowsCachePath(dir?: string): string {
+  return join(dir ?? join(homedir(), ".cortex"), SYNCED_WORKFLOWS_FILENAME);
+}
+
+/**
+ * Returns the synced org-authored workflows keyed by `workflow_id`.
+ * Empty object when the cache is missing, unreadable, malformed, or
+ * contains no valid entries. The optional `dir` argument is for tests;
+ * production callers leave it unset.
+ */
+export function loadSyncedWorkflows(
+  dir?: string,
+): Record<string, WorkflowDefinition> {
+  const path = syncedWorkflowsCachePath(dir);
+  if (!existsSync(path)) return {};
+
+  let parsed: LocalWorkflowsState;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8")) as LocalWorkflowsState;
+  } catch {
+    return {};
+  }
+  const records = parsed.workflows;
+  if (!records || typeof records !== "object") return {};
+
+  const out: Record<string, WorkflowDefinition> = {};
+  for (const [id, record] of Object.entries(records)) {
+    if (!record || typeof record !== "object") continue;
+    const result = workflowDefinitionSchema.safeParse(record.definition);
+    if (!result.success) continue;
+    out[id] = result.data;
+  }
+  return out;
+}

package/scaffold/mcp/src/daemon/main.ts

@@ -28,6 +28,7 @@ import {
 } from "./heartbeat-tracker.js";
 import { startSyncTimer } from "./sync-checker.js";
 import { startSkillSyncTimer } from "./skill-sync-checker.js";
+import { startWorkflowSyncTimer } from "./workflow-sync-checker.js";
 import { startHostEventsPusher } from "./host-events-pusher.js";
 import { startEgressProxy } from "./egress-proxy.js";
 import { startHeartbeatPusher } from "./heartbeat-pusher.js";
@@ -357,6 +358,20 @@ async function main(): Promise<void> {
     startSkillSyncTimer(process.cwd(), skillSyncMs);
   }
 
+  // Harness Phase 2: poll cortex-web for org-authored workflows, cache
+  // their definitions locally so cortex.workflow.start can resolve
+  // org-specific workflow_ids ahead of bundled defaults. Same cadence
+  // as the skill sync by default; independently configurable via
+  // CORTEX_WORKFLOW_SYNC_MS / CORTEX_DISABLE_WORKFLOW_SYNC.
+  const workflowSyncRaw = parseInt(process.env.CORTEX_WORKFLOW_SYNC_MS ?? "", 10);
+  const workflowSyncMs =
+    Number.isFinite(workflowSyncRaw) && workflowSyncRaw > 0
+      ? workflowSyncRaw
+      : skillSyncMs;
+  if (process.env.CORTEX_DISABLE_WORKFLOW_SYNC !== "1") {
+    startWorkflowSyncTimer(process.cwd(), workflowSyncMs);
+  }
+
   // Govern host heartbeat — fills host_enrollment on cortex-web so the
   // dashboard at /dashboard/govern actually shows this host.
   const heartbeatRaw = parseInt(process.env.CORTEX_HEARTBEAT_PUSH_MS ?? "", 10);