@danielblomma/cortex-mcp 2.0.6 → 2.0.8

package/scaffold/mcp/src/daemon/workflow-sync-checker.ts

@@ -0,0 +1,301 @@
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { loadEnterpriseConfig } from "../core/config.js";
+import { workflowDefinitionSchema, type WorkflowDefinition } from "../core/workflow/schemas.js";
+import { writeHostAuditEvent } from "./ungoverned-scanner.js";
+import { daemonDir } from "./paths.js";
+
+/**
+ * Org-workflow sync flow — daemon side.
+ *
+ * The daemon polls cortex-web /api/v1/govern/workflows/manifest each tick
+ * to learn what workflows the org has authored. It diffs against a local
+ * state file, fetches changed full definitions, and caches them locally.
+ * cortex.workflow.start (and the cortex stage CLI) read the cache via
+ * loadSyncedWorkflows() and merge with bundled DEFAULT_WORKFLOWS, with
+ * org definitions taking precedence on workflow_id collisions.
+ *
+ * Three audit outcomes per tick:
+ *  - workflows_unchanged   — manifest matches local state
+ *  - workflows_synced      — at least one workflow was added / changed /
+ *                            removed (metadata: counts)
+ *  - workflows_sync_failed — network / auth / parse error
+ *
+ * Unlike skills, there is no on-disk artifact to write per workflow —
+ * the cached JSON is the only product. No "restart Claude Code"
+ * notification is needed because workflow lookup happens at run-start.
+ */
+
+const STATE_FILENAME = "workflows.local.json";
+
+type ManifestEntry = {
+  workflow_id: string;
+  version: number;
+  updated_at: string;
+};
+
+type FetchedWorkflow = {
+  workflow_id: string;
+  description: string;
+  version: number;
+  definition: WorkflowDefinition;
+  updated_at: string;
+};
+
+type LocalWorkflowRecord = {
+  workflow_id: string;
+  version: number;
+  updated_at: string;
+  definition: WorkflowDefinition;
+};
+
+type LocalWorkflowsState = {
+  workflows: Record<string, LocalWorkflowRecord>;
+  last_synced_at?: string;
+};
+
+export type WorkflowSyncOutcome =
+  | { kind: "unchanged"; count: number }
+  | {
+      kind: "synced";
+      added: string[];
+      changed: string[];
+      removed: string[];
+    }
+  | { kind: "failed"; error: string };
+
+function stateFilePath(): string {
+  return join(daemonDir(), STATE_FILENAME);
+}
+
+export function readSyncedWorkflowsState(): LocalWorkflowsState {
+  const path = stateFilePath();
+  if (!existsSync(path)) return { workflows: {} };
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as LocalWorkflowsState;
+    return {
+      workflows: parsed.workflows ?? {},
+      last_synced_at: parsed.last_synced_at,
+    };
+  } catch {
+    return { workflows: {} };
+  }
+}
+
+function writeSyncedWorkflowsState(state: LocalWorkflowsState): void {
+  writeFileSync(
+    stateFilePath(),
+    JSON.stringify(state, null, 2) + "\n",
+    "utf8",
+  );
+}
+
+async function fetchManifest(
+  baseUrl: string,
+  apiKey: string,
+): Promise<ManifestEntry[]> {
+  const url = new URL(
+    baseUrl.replace(/\/$/, "") + "/api/v1/govern/workflows/manifest",
+  );
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} ${res.statusText}`);
+  }
+  const body = (await res.json()) as { workflows?: ManifestEntry[] };
+  return body.workflows ?? [];
+}
+
+async function fetchWorkflow(
+  baseUrl: string,
+  apiKey: string,
+  workflowId: string,
+): Promise<FetchedWorkflow> {
+  const url = new URL(
+    baseUrl.replace(/\/$/, "") +
+      "/api/v1/govern/workflows/" +
+      encodeURIComponent(workflowId),
+  );
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} ${res.statusText}`);
+  }
+  const body = (await res.json()) as { workflow?: FetchedWorkflow };
+  if (!body.workflow) {
+    throw new Error(`Response for ${workflowId} missing 'workflow' field`);
+  }
+  return body.workflow;
+}
+
+export async function runWorkflowSyncOnce(
+  cwd: string,
+): Promise<WorkflowSyncOutcome> {
+  const config = loadEnterpriseConfig(join(cwd, ".context"));
+  const apiKey = config.enterprise.api_key.trim();
+  const baseUrl = (config.enterprise.base_url || config.enterprise.endpoint).trim();
+  if (!apiKey || !baseUrl) {
+    const outcome: WorkflowSyncOutcome = {
+      kind: "failed",
+      error: "enterprise not configured",
+    };
+    await writeAudit(cwd, outcome);
+    return outcome;
+  }
+
+  let manifest: ManifestEntry[];
+  try {
+    manifest = await fetchManifest(baseUrl, apiKey);
+  } catch (err) {
+    const outcome: WorkflowSyncOutcome = {
+      kind: "failed",
+      error: err instanceof Error ? err.message : String(err),
+    };
+    await writeAudit(cwd, outcome);
+    return outcome;
+  }
+
+  const state = readSyncedWorkflowsState();
+  const remoteByName = new Map(manifest.map((e) => [e.workflow_id, e]));
+
+  const added: string[] = [];
+  const changed: string[] = [];
+  const removed: string[] = [];
+
+  for (const entry of manifest) {
+    const local = state.workflows[entry.workflow_id];
+    const isNew = !local;
+    const isChanged =
+      Boolean(local) &&
+      (local.updated_at !== entry.updated_at || local.version !== entry.version);
+    if (!isNew && !isChanged) continue;
+
+    let fetched: FetchedWorkflow;
+    try {
+      fetched = await fetchWorkflow(baseUrl, apiKey, entry.workflow_id);
+    } catch (err) {
+      const outcome: WorkflowSyncOutcome = {
+        kind: "failed",
+        error:
+          err instanceof Error
+            ? `fetch ${entry.workflow_id}: ${err.message}`
+            : `fetch ${entry.workflow_id}: ${String(err)}`,
+      };
+      await writeAudit(cwd, outcome);
+      return outcome;
+    }
+
+    let validated: WorkflowDefinition;
+    try {
+      validated = workflowDefinitionSchema.parse(fetched.definition);
+    } catch (err) {
+      const outcome: WorkflowSyncOutcome = {
+        kind: "failed",
+        error:
+          err instanceof Error
+            ? `validate ${entry.workflow_id}: ${err.message}`
+            : `validate ${entry.workflow_id}: ${String(err)}`,
+      };
+      await writeAudit(cwd, outcome);
+      return outcome;
+    }
+
+    state.workflows[entry.workflow_id] = {
+      workflow_id: entry.workflow_id,
+      version: fetched.version,
+      updated_at: fetched.updated_at,
+      definition: validated,
+    };
+    (isNew ? added : changed).push(entry.workflow_id);
+  }
+
+  for (const name of Object.keys(state.workflows)) {
+    if (remoteByName.has(name)) continue;
+    delete state.workflows[name];
+    removed.push(name);
+  }
+
+  const totalChanged = added.length + changed.length + removed.length;
+  if (totalChanged === 0) {
+    const outcome: WorkflowSyncOutcome = {
+      kind: "unchanged",
+      count: manifest.length,
+    };
+    await writeAudit(cwd, outcome);
+    return outcome;
+  }
+
+  state.last_synced_at = new Date().toISOString();
+  writeSyncedWorkflowsState(state);
+  const outcome: WorkflowSyncOutcome = {
+    kind: "synced",
+    added,
+    changed,
+    removed,
+  };
+  await writeAudit(cwd, outcome);
+  return outcome;
+}
+
+async function writeAudit(cwd: string, outcome: WorkflowSyncOutcome): Promise<void> {
+  const eventBase = {
+    timestamp: new Date().toISOString(),
+    host_id: hostname(),
+  };
+  if (outcome.kind === "unchanged") {
+    await writeHostAuditEvent(cwd, {
+      ...eventBase,
+      event_type: "workflows_unchanged",
+      count: outcome.count,
+    }).catch(() => undefined);
+  } else if (outcome.kind === "synced") {
+    await writeHostAuditEvent(cwd, {
+      ...eventBase,
+      event_type: "workflows_synced",
+      added: outcome.added,
+      changed: outcome.changed,
+      removed: outcome.removed,
+    }).catch(() => undefined);
+  } else {
+    await writeHostAuditEvent(cwd, {
+      ...eventBase,
+      event_type: "workflows_sync_failed",
+      error: outcome.error,
+    }).catch(() => undefined);
+  }
+}
+
+export type WorkflowSyncTimerHandle = {
+  stop(): void;
+};
+
+export function startWorkflowSyncTimer(
+  cwd: string,
+  intervalMs: number,
+): WorkflowSyncTimerHandle {
+  const tick = () => {
+    void runWorkflowSyncOnce(cwd).catch((err) => {
+      process.stderr.write(
+        `[cortex-daemon] workflow sync failed: ${
+          err instanceof Error ? err.message : String(err)
+        }\n`,
+      );
+    });
+  };
+
+  void Promise.resolve().then(tick);
+  const handle = setInterval(tick, intervalMs);
+  if (typeof handle.unref === "function") handle.unref();
+  return {
+    stop() {
+      clearInterval(handle);
+    },
+  };
+}

package/scaffold/mcp/src/enterprise/index.ts

@@ -14,6 +14,7 @@ import { pushAuditEvents, queueAuditEvent, setAuditPushContext } from "./audit/p
 import { PolicyStore } from "../core/policy/store.js";
 import { syncFromCloud, syncFromLocal } from "./policy/sync.js";
 import { registerEnterpriseTools } from "./tools/enterprise.js";
+import { registerHarnessTools } from "./tools/harness.js";
 import { pushViolations, setViolationPushContext } from "./violations/push.js";
 import { pushReviewResults, setReviewPushContext } from "./reviews/push.js";
 import { setWorkflowPushContext } from "./workflow/push.js";
@@ -319,6 +320,10 @@ export async function register(server: McpServer): Promise<void> {
   }
 
   registerEnterpriseTools(server, collector, auditWriter, config, contextDir, policyStore, version);
+  // Cortex Harness MCP tools (cortex.workflow.*) — only registered for
+  // enterprise projects, since they depend on org-authored workflows
+  // synced from cortex-web (also enterprise-only).
+  registerHarnessTools(server);
 
   // v2.0.0: globalThis.__cortexContextToolHook bridge removed.
   // Enterprise is now in-process with cortex-mcp; tool events flow via

package/scaffold/mcp/src/enterprise/tools/harness.ts

@@ -0,0 +1,98 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  WorkflowAdvanceInput,
+  WorkflowEnvelopeInput,
+  WorkflowStartInput,
+  WorkflowStatusInput,
+  resolveProjectRoot,
+  runWorkflowAdvance,
+  runWorkflowEnvelope,
+  runWorkflowStart,
+  runWorkflowStatus,
+} from "../../core/workflow/mcp-tools.js";
+
+/**
+ * Registers the cortex.workflow.* tools that drive the Cortex Harness.
+ * These are an enterprise-only feature: they're only registered when
+ * the enterprise plugin successfully loads (license + config valid).
+ *
+ * Community-mode MCP servers do not see these tools at all — the
+ * harness depends on org-authored workflows from cortex-web, which
+ * itself requires an enterprise plan.
+ *
+ * Pure runner functions live in core/workflow/mcp-tools.ts so they can
+ * be unit-tested without spinning up an MCP server. This module only
+ * wires them onto the server with the right tool names + input schemas.
+ */
+
+type ToolPayload = Record<string, unknown>;
+
+export function registerHarnessTools(server: McpServer): void {
+  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). Enterprise-only.",
+      inputSchema: WorkflowStartInput,
+    },
+    async (input) => buildResult(
+      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). Enterprise-only.",
+      inputSchema: WorkflowAdvanceInput,
+    },
+    async (input) => buildResult(
+      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. Enterprise-only.",
+      inputSchema: WorkflowStatusInput,
+    },
+    async (input) => buildResult(
+      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. Enterprise-only.",
+      inputSchema: WorkflowEnvelopeInput,
+    },
+    async (input) => buildResult(
+      runWorkflowEnvelope(WorkflowEnvelopeInput.parse(input ?? {}), {
+        cwd: resolveProjectRoot(),
+      }) as ToolPayload,
+    ),
+  );
+}
+
+function buildResult(data: ToolPayload) {
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(data, null, 2),
+      },
+    ],
+    structuredContent: data,
+  };
+}

package/scaffold/mcp/src/server.ts

@@ -11,17 +11,6 @@ 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>;
 
@@ -334,69 +323,10 @@ function registerTools(server: McpServer): void {
     })
   );
 
-  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,
-    ),
-  );
+  // Note: cortex.workflow.* tools (the Cortex Harness) are enterprise-only
+  // and registered by enterprise/index.ts::register() once the license has
+  // verified. They intentionally do not appear here so community-mode MCP
+  // servers do not surface them at all.
 }
 
 let shutdownCalled = false;

package/scaffold/mcp/tests/workflow-cli.test.mjs

@@ -9,6 +9,15 @@ import { runStageCommand } from "../dist/cli/stage.js";
 function makeWorkspace() {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "cortex-stage-cli-"));
   process.env.CORTEX_PROJECT_ROOT = dir;
+  // cortex stage is enterprise-only; satisfy the gate by writing a
+  // minimal enterprise.yml. isEnterpriseProject only requires a
+  // non-empty enterprise.api_key field.
+  fs.mkdirSync(path.join(dir, ".context"), { recursive: true });
+  fs.writeFileSync(
+    path.join(dir, ".context", "enterprise.yml"),
+    "enterprise:\n  api_key: test-key-for-cli-tests\n",
+    "utf8",
+  );
   return dir;
 }
 
@@ -289,5 +298,37 @@ test("stage help: prints help text and returns without throwing", async () => {
 });
 
 test("stage <unknown>: throws with help text", async () => {
+  makeWorkspace();
   await assert.rejects(runStageCommand(["frobnicate"]), /Unknown stage subcommand/);
 });
+
+test("stage start: blocked in community mode (no enterprise.yml)", async () => {
+  // Bypass the helper that auto-writes enterprise.yml.
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "cortex-stage-cli-community-"));
+  process.env.CORTEX_PROJECT_ROOT = dir;
+  try {
+    await assert.rejects(
+      runStageCommand([
+        "start",
+        "--task-id",
+        "task-1",
+        "--description",
+        "x",
+      ]),
+      /Cortex Harness — an enterprise-only feature/,
+    );
+  } finally {
+    delete process.env.CORTEX_PROJECT_ROOT;
+  }
+});
+
+test("stage help: still prints in community mode (so users discover the feature)", async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "cortex-stage-cli-community-help-"));
+  process.env.CORTEX_PROJECT_ROOT = dir;
+  try {
+    const { captured } = await captureStdout(() => runStageCommand(["help"]));
+    assert.match(captured, /Usage:/);
+  } finally {
+    delete process.env.CORTEX_PROJECT_ROOT;
+  }
+});