@danielblomma/cortex-mcp 2.0.6 → 2.0.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "description": "Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.",
   "type": "module",
   "author": "Daniel Blomma",

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

@@ -6,3 +6,4 @@ export * from "./default-workflows.js";
 export * from "./mcp-tools.js";
 export * from "./capabilities.js";
 export * from "./enforcement.js";
+export * from "./synced-registry.js";

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

@@ -2,6 +2,7 @@ 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,
@@ -79,7 +80,13 @@ function resolveWorkflow(
   workflowId: string,
   registry: Record<string, WorkflowDefinition> | undefined,
 ): WorkflowDefinition {
-  const workflows = registry ?? DEFAULT_WORKFLOWS;
+  // 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(

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

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/tests/workflow-synced-registry.test.mjs

@@ -0,0 +1,179 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  loadSyncedWorkflows,
+  syncedWorkflowsCachePath,
+} from "../dist/core/workflow/synced-registry.js";
+import { runWorkflowStart } from "../dist/core/workflow/mcp-tools.js";
+import { SECURE_BUILD_WORKFLOW } from "../dist/core/workflow/default-workflows.js";
+
+function makeWorkspace() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "cortex-synced-registry-"));
+}
+
+const TINY_WORKFLOW = {
+  id: "tiny",
+  description: "Two-stage tests workflow",
+  version: 1,
+  stages: [
+    {
+      name: "plan",
+      artifact: "plan.md",
+      reads: [],
+      required_fields: [],
+      capability: "planner",
+      description: "Produce a plan.",
+    },
+    {
+      name: "review",
+      artifact: "review.md",
+      reads: ["plan"],
+      required_fields: ["approved"],
+      capability: "reviewer",
+      description: "Review the plan.",
+    },
+  ],
+};
+
+function writeCache(dir, payload) {
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(
+    syncedWorkflowsCachePath(dir),
+    JSON.stringify(payload, null, 2),
+    "utf8",
+  );
+}
+
+test("syncedWorkflowsCachePath: defaults to ~/.cortex/workflows.local.json", () => {
+  const expected = path.join(os.homedir(), ".cortex", "workflows.local.json");
+  assert.equal(syncedWorkflowsCachePath(), expected);
+});
+
+test("loadSyncedWorkflows: returns {} when cache is missing", () => {
+  const dir = makeWorkspace();
+  assert.deepEqual(loadSyncedWorkflows(dir), {});
+});
+
+test("loadSyncedWorkflows: returns {} when cache is unreadable JSON", () => {
+  const dir = makeWorkspace();
+  fs.writeFileSync(syncedWorkflowsCachePath(dir), "not valid json", "utf8");
+  assert.deepEqual(loadSyncedWorkflows(dir), {});
+});
+
+test("loadSyncedWorkflows: returns {} when 'workflows' key is missing", () => {
+  const dir = makeWorkspace();
+  writeCache(dir, { last_synced_at: "x" });
+  assert.deepEqual(loadSyncedWorkflows(dir), {});
+});
+
+test("loadSyncedWorkflows: drops entries whose definition fails schema", () => {
+  const dir = makeWorkspace();
+  writeCache(dir, {
+    workflows: {
+      "valid-one": {
+        workflow_id: "valid-one",
+        version: 1,
+        updated_at: "2026-05-06T12:00:00.000Z",
+        definition: TINY_WORKFLOW,
+      },
+      "broken-one": {
+        workflow_id: "broken-one",
+        version: 1,
+        updated_at: "2026-05-06T12:00:00.000Z",
+        definition: { id: "broken-one" /* missing stages */ },
+      },
+    },
+  });
+  const loaded = loadSyncedWorkflows(dir);
+  assert.deepEqual(Object.keys(loaded).sort(), ["valid-one"]);
+});
+
+test("loadSyncedWorkflows: returns valid workflow definitions keyed by workflow_id", () => {
+  const dir = makeWorkspace();
+  writeCache(dir, {
+    workflows: {
+      tiny: {
+        workflow_id: "tiny",
+        version: 1,
+        updated_at: "2026-05-06T12:00:00.000Z",
+        definition: TINY_WORKFLOW,
+      },
+    },
+  });
+  const loaded = loadSyncedWorkflows(dir);
+  assert.equal(loaded.tiny.id, "tiny");
+  assert.equal(loaded.tiny.stages.length, 2);
+});
+
+test("resolveWorkflow integration: synced workflow takes precedence over bundled default", () => {
+  // We can't easily intercept loadSyncedWorkflows() from inside
+  // mcp-tools.ts (it reads from a fixed home-dir path). Instead, exercise
+  // the explicit-registry path which mirrors what the merge would do
+  // and confirm the contract: passing a registry that includes the same
+  // id as a bundled default uses the registry version.
+  const cwd = makeWorkspace();
+  process.env.HOME = cwd; // sandbox the cache lookup
+  try {
+    const overridden = {
+      ...SECURE_BUILD_WORKFLOW,
+      description: "Org-overridden secure-build",
+    };
+    const registry = { "secure-build": overridden };
+    const result = runWorkflowStart(
+      {
+        task_id: "task-1",
+        task_description: "test",
+        workflow_id: "secure-build",
+      },
+      { cwd, workflows: registry },
+    );
+    assert.equal(result.state.workflow_id, "secure-build");
+    // The envelope renders the workflow description verbatim — confirms
+    // we got the org-overridden version and not the bundled one.
+    assert.match(result.envelope.prompt, /Org-overridden secure-build/);
+  } finally {
+    delete process.env.HOME;
+  }
+});
+
+test("resolveWorkflow integration: synced cache adds new workflow_ids beyond defaults", () => {
+  const cwd = makeWorkspace();
+  // Build a cache under a tmp HOME and point HOME at it, so that the
+  // home-dir-based loader picks it up.
+  const fakeHome = makeWorkspace();
+  process.env.HOME = fakeHome;
+  try {
+    fs.mkdirSync(path.join(fakeHome, ".cortex"), { recursive: true });
+    fs.writeFileSync(
+      path.join(fakeHome, ".cortex", "workflows.local.json"),
+      JSON.stringify({
+        workflows: {
+          tiny: {
+            workflow_id: "tiny",
+            version: 1,
+            updated_at: "2026-05-06T12:00:00.000Z",
+            definition: TINY_WORKFLOW,
+          },
+        },
+      }),
+      "utf8",
+    );
+
+    const result = runWorkflowStart(
+      {
+        task_id: "task-2",
+        task_description: "Use synced workflow",
+        workflow_id: "tiny",
+      },
+      { cwd },
+    );
+    assert.equal(result.state.workflow_id, "tiny");
+    assert.equal(result.state.current_stage, "plan");
+  } finally {
+    delete process.env.HOME;
+  }
+});