@danielblomma/cortex-mcp 2.0.7 → 2.0.9

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

@@ -0,0 +1,295 @@
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { loadEnterpriseConfig } from "../core/config.js";
+import {
+  capabilityDefinitionSchema,
+  type CapabilityDefinition,
+} from "../core/workflow/capabilities.js";
+import { writeHostAuditEvent } from "./ungoverned-scanner.js";
+import { daemonDir } from "./paths.js";
+
+/**
+ * Org-capability sync flow — daemon side.
+ *
+ * The daemon polls cortex-web /api/v1/govern/capabilities/manifest each
+ * tick to learn what capabilities the org has authored. It diffs against
+ * a local state file, fetches changed full definitions, and caches them
+ * locally. The pre-tool-use hook's evaluateToolCall consults the merged
+ * registry via loadSyncedCapabilities() with synced taking precedence
+ * over bundled DEFAULT_CAPABILITIES on name collisions.
+ *
+ * Three audit outcomes per tick:
+ *  - capabilities_unchanged   — manifest matches local state
+ *  - capabilities_synced      — at least one capability was added /
+ *                               changed / removed (metadata: counts)
+ *  - capabilities_sync_failed — network / auth / parse error
+ */
+
+const STATE_FILENAME = "capabilities.local.json";
+
+type ManifestEntry = {
+  capability_name: string;
+  updated_at: string;
+};
+
+type FetchedCapability = {
+  capability_name: string;
+  description: string;
+  definition: CapabilityDefinition;
+  updated_at: string;
+};
+
+type LocalCapabilityRecord = {
+  capability_name: string;
+  updated_at: string;
+  definition: CapabilityDefinition;
+};
+
+type LocalCapabilitiesState = {
+  capabilities: Record<string, LocalCapabilityRecord>;
+  last_synced_at?: string;
+};
+
+export type CapabilitySyncOutcome =
+  | { kind: "unchanged"; count: number }
+  | {
+      kind: "synced";
+      added: string[];
+      changed: string[];
+      removed: string[];
+    }
+  | { kind: "failed"; error: string };
+
+function stateFilePath(): string {
+  return join(daemonDir(), STATE_FILENAME);
+}
+
+function readSyncedCapabilitiesState(): LocalCapabilitiesState {
+  const path = stateFilePath();
+  if (!existsSync(path)) return { capabilities: {} };
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as LocalCapabilitiesState;
+    return {
+      capabilities: parsed.capabilities ?? {},
+      last_synced_at: parsed.last_synced_at,
+    };
+  } catch {
+    return { capabilities: {} };
+  }
+}
+
+function writeSyncedCapabilitiesState(state: LocalCapabilitiesState): 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/capabilities/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 { capabilities?: ManifestEntry[] };
+  return body.capabilities ?? [];
+}
+
+async function fetchCapability(
+  baseUrl: string,
+  apiKey: string,
+  capabilityName: string,
+): Promise<FetchedCapability> {
+  const url = new URL(
+    baseUrl.replace(/\/$/, "") +
+      "/api/v1/govern/capabilities/" +
+      encodeURIComponent(capabilityName),
+  );
+  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 { capability?: FetchedCapability };
+  if (!body.capability) {
+    throw new Error(`Response for ${capabilityName} missing 'capability' field`);
+  }
+  return body.capability;
+}
+
+export async function runCapabilitySyncOnce(
+  cwd: string,
+): Promise<CapabilitySyncOutcome> {
+  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: CapabilitySyncOutcome = {
+      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: CapabilitySyncOutcome = {
+      kind: "failed",
+      error: err instanceof Error ? err.message : String(err),
+    };
+    await writeAudit(cwd, outcome);
+    return outcome;
+  }
+
+  const state = readSyncedCapabilitiesState();
+  const remoteByName = new Map(manifest.map((e) => [e.capability_name, e]));
+
+  const added: string[] = [];
+  const changed: string[] = [];
+  const removed: string[] = [];
+
+  for (const entry of manifest) {
+    const local = state.capabilities[entry.capability_name];
+    const isNew = !local;
+    const isChanged =
+      Boolean(local) && local.updated_at !== entry.updated_at;
+    if (!isNew && !isChanged) continue;
+
+    let fetched: FetchedCapability;
+    try {
+      fetched = await fetchCapability(baseUrl, apiKey, entry.capability_name);
+    } catch (err) {
+      const outcome: CapabilitySyncOutcome = {
+        kind: "failed",
+        error:
+          err instanceof Error
+            ? `fetch ${entry.capability_name}: ${err.message}`
+            : `fetch ${entry.capability_name}: ${String(err)}`,
+      };
+      await writeAudit(cwd, outcome);
+      return outcome;
+    }
+
+    let validated: CapabilityDefinition;
+    try {
+      validated = capabilityDefinitionSchema.parse(fetched.definition);
+    } catch (err) {
+      const outcome: CapabilitySyncOutcome = {
+        kind: "failed",
+        error:
+          err instanceof Error
+            ? `validate ${entry.capability_name}: ${err.message}`
+            : `validate ${entry.capability_name}: ${String(err)}`,
+      };
+      await writeAudit(cwd, outcome);
+      return outcome;
+    }
+
+    state.capabilities[entry.capability_name] = {
+      capability_name: entry.capability_name,
+      updated_at: fetched.updated_at,
+      definition: validated,
+    };
+    (isNew ? added : changed).push(entry.capability_name);
+  }
+
+  for (const name of Object.keys(state.capabilities)) {
+    if (remoteByName.has(name)) continue;
+    delete state.capabilities[name];
+    removed.push(name);
+  }
+
+  const totalChanged = added.length + changed.length + removed.length;
+  if (totalChanged === 0) {
+    const outcome: CapabilitySyncOutcome = {
+      kind: "unchanged",
+      count: manifest.length,
+    };
+    await writeAudit(cwd, outcome);
+    return outcome;
+  }
+
+  state.last_synced_at = new Date().toISOString();
+  writeSyncedCapabilitiesState(state);
+  const outcome: CapabilitySyncOutcome = {
+    kind: "synced",
+    added,
+    changed,
+    removed,
+  };
+  await writeAudit(cwd, outcome);
+  return outcome;
+}
+
+async function writeAudit(cwd: string, outcome: CapabilitySyncOutcome): Promise<void> {
+  const eventBase = {
+    timestamp: new Date().toISOString(),
+    host_id: hostname(),
+  };
+  if (outcome.kind === "unchanged") {
+    await writeHostAuditEvent(cwd, {
+      ...eventBase,
+      event_type: "capabilities_unchanged",
+      count: outcome.count,
+    }).catch(() => undefined);
+  } else if (outcome.kind === "synced") {
+    await writeHostAuditEvent(cwd, {
+      ...eventBase,
+      event_type: "capabilities_synced",
+      added: outcome.added,
+      changed: outcome.changed,
+      removed: outcome.removed,
+    }).catch(() => undefined);
+  } else {
+    await writeHostAuditEvent(cwd, {
+      ...eventBase,
+      event_type: "capabilities_sync_failed",
+      error: outcome.error,
+    }).catch(() => undefined);
+  }
+}
+
+export type CapabilitySyncTimerHandle = {
+  stop(): void;
+};
+
+export function startCapabilitySyncTimer(
+  cwd: string,
+  intervalMs: number,
+): CapabilitySyncTimerHandle {
+  const tick = () => {
+    void runCapabilitySyncOnce(cwd).catch((err) => {
+      process.stderr.write(
+        `[cortex-daemon] capability 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/daemon/main.ts

@@ -29,6 +29,7 @@ import {
 import { startSyncTimer } from "./sync-checker.js";
 import { startSkillSyncTimer } from "./skill-sync-checker.js";
 import { startWorkflowSyncTimer } from "./workflow-sync-checker.js";
+import { startCapabilitySyncTimer } from "./capability-sync-checker.js";
 import { startHostEventsPusher } from "./host-events-pusher.js";
 import { startEgressProxy } from "./egress-proxy.js";
 import { startHeartbeatPusher } from "./heartbeat-pusher.js";
@@ -372,6 +373,20 @@ async function main(): Promise<void> {
     startWorkflowSyncTimer(process.cwd(), workflowSyncMs);
   }
 
+  // Harness Phase 2: poll cortex-web for org-authored capabilities and
+  // cache definitions locally so evaluateToolCall can merge them over
+  // bundled DEFAULT_CAPABILITIES on the pre-tool-use path. Same cadence
+  // as the workflow sync by default; independently configurable via
+  // CORTEX_CAPABILITY_SYNC_MS / CORTEX_DISABLE_CAPABILITY_SYNC.
+  const capabilitySyncRaw = parseInt(process.env.CORTEX_CAPABILITY_SYNC_MS ?? "", 10);
+  const capabilitySyncMs =
+    Number.isFinite(capabilitySyncRaw) && capabilitySyncRaw > 0
+      ? capabilitySyncRaw
+      : workflowSyncMs;
+  if (process.env.CORTEX_DISABLE_CAPABILITY_SYNC !== "1") {
+    startCapabilitySyncTimer(process.cwd(), capabilitySyncMs);
+  }
+
   // 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);

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;
+  }
+});