@danielblomma/cortex-mcp 2.4.0 → 2.4.1

package/scaffold/mcp/dist/core/workflow/run-lifecycle.js

@@ -0,0 +1,123 @@
+import { readRunState, writeRunState, writeStageArtifact, } from "./artifact-io.js";
+import { runStateSchema, stageArtifactFrontmatterSchema, stageOverrideSchema, workflowDefinitionSchema, } from "./schemas.js";
+export function createRun(options) {
+    const workflow = workflowDefinitionSchema.parse(options.workflow);
+    const now = (options.now ?? (() => new Date()))();
+    const startedAt = now.toISOString();
+    const stages = workflow.stages.map((stage) => ({
+        name: stage.name,
+        status: "pending",
+        validators_passed: [],
+    }));
+    const state = {
+        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, taskId) {
+    return readRunState(cwd, taskId);
+}
+/**
+ * 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) {
+    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 stageIndex = workflow.stages.findIndex((s) => s.name === options.stageName);
+    const stageDef = workflow.stages[stageIndex];
+    // Validator coverage check: every validator the stage declares must
+    // appear in validators_passed unless the override explicitly skips it.
+    // Process is enforced here even though the validators themselves run
+    // in the agent's environment.
+    const validatorsPassed = options.validatorsPassed ?? [];
+    const override = options.override
+        ? stageOverrideSchema.parse(options.override)
+        : undefined;
+    const requiredValidators = stageDef.validators.map((v) => v.id);
+    const declaredSkipped = new Set(override?.skipped_validators ?? []);
+    const missingValidators = requiredValidators.filter((id) => !validatorsPassed.includes(id) && !declaredSkipped.has(id));
+    // blocked / failed stages are exempt from validator coverage — the
+    // stage is explicitly halting before completion, so the validators
+    // logically cannot have run.
+    const finalStatus = options.status ?? "complete";
+    const exemptStatus = finalStatus === "blocked" || finalStatus === "failed";
+    if (missingValidators.length > 0 && !exemptStatus) {
+        throw new Error(`Stage ${options.stageName} requires validators ${requiredValidators.join(", ")} ` +
+            `but artifact reported only ${validatorsPassed.join(", ") || "<none>"}. ` +
+            `Missing: ${missingValidators.join(", ")}. ` +
+            `Pass override.skipped_validators with a reason to advance anyway.`);
+    }
+    const now = (options.now ?? (() => new Date()))();
+    const completedAt = now.toISOString();
+    const frontmatter = stageArtifactFrontmatterSchema.parse({
+        ...options.frontmatter,
+        stage: options.stageName,
+        validators_passed: validatorsPassed,
+        ...(override
+            ? {
+                override: {
+                    reason: override.reason,
+                    skipped_validators: override.skipped_validators,
+                    skipped_requirements: override.skipped_requirements,
+                },
+            }
+            : {}),
+        written_at: options.frontmatter.written_at ?? completedAt,
+    });
+    writeStageArtifact(options.cwd, options.taskId, options.artifactName, frontmatter, options.body);
+    const nextStage = workflow.stages[stageIndex + 1] ?? null;
+    const updatedStages = 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,
+            validators_passed: validatorsPassed,
+            override,
+        };
+    });
+    const runOutcome = finalStatus === "blocked" || finalStatus === "failed"
+        ? finalStatus
+        : nextStage
+            ? "in_progress"
+            : "complete";
+    const next = {
+        ...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/dist/core/workflow/schemas.js

@@ -0,0 +1,141 @@
+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)");
+/**
+ * Validator requirement declared by a workflow stage. Cortex enforces
+ * that the agent reports having run each declared validator (via the
+ * artifact's `validators_passed` frontmatter), but never executes the
+ * validator itself — the agent picks the concrete tooling.
+ *
+ * id is a stable identifier (e.g. "mutation-score") that the agent
+ * echoes back; description is human-readable context for the agent
+ * rendered into the stage envelope.
+ */
+export const validatorRequirementSchema = z.object({
+    id: slugSchema,
+    description: z.string().min(1).max(500),
+});
+/**
+ * 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([]),
+    /**
+     * Validators the stage requires the agent to have run. The agent
+     * picks the actual tooling (e.g. stryker for mutation testing) and
+     * reports the result by listing each validator's id under
+     * `validators_passed` in the artifact frontmatter. Cortex enforces
+     * the list-coverage contract on advance unless the call carries an
+     * explicit override.
+     */
+    validators: z.array(validatorRequirementSchema).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),
+});
+/**
+ * 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),
+});
+/**
+ * Status of a single stage inside a run.
+ */
+export const stageStatusSchema = z.enum([
+    "pending",
+    "in_progress",
+    "complete",
+    "blocked",
+    "failed",
+]);
+/**
+ * Process-override record. When a stage advances despite missing or
+ * failed validators, the caller must pass an override with a free-text
+ * reason. The override is recorded on the StageRecord, stamped into
+ * the artifact's frontmatter, and emitted as a high-evidence audit
+ * event so reviewers can see the deviation in the evidence trail.
+ */
+export const stageOverrideSchema = z.object({
+    reason: z.string().min(1).max(2000),
+    skipped_validators: z.array(z.string().min(1)).default([]),
+    skipped_requirements: z.array(z.string().min(1)).default([]),
+});
+/**
+ * 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(),
+    /** Validators the agent reported having run for this stage. */
+    validators_passed: z.array(z.string().min(1)).default([]),
+    /** Override record if the stage advanced despite missing/failed requirements. */
+    override: stageOverrideSchema.optional(),
+});
+/**
+ * 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),
+});
+/**
+ * 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();

package/scaffold/mcp/dist/core/workflow/synced-capability-registry.js

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { configuredEnterpriseCredentialId } from "../enterprise-identity.js";
+import { capabilityDefinitionSchema, } from "./capabilities.js";
+/**
+ * Read side of the org-capability sync cache. The daemon's
+ * capability-sync-checker writes ~/.cortex/capabilities.local.json;
+ * this module reads it. Kept in core/workflow/ rather than daemon/ so
+ * enforcement.ts can consult the cache without depending on daemon code.
+ *
+ * Each entry is validated against capabilityDefinitionSchema 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_CAPABILITIES_FILENAME = "capabilities.local.json";
+export function syncedCapabilitiesCachePath(dir) {
+    return join(dir ?? join(homedir(), ".cortex"), SYNCED_CAPABILITIES_FILENAME);
+}
+/**
+ * Returns the synced org-authored capabilities keyed by capability name.
+ * 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 loadSyncedCapabilities(dir, expectedCredentialId) {
+    const path = syncedCapabilitiesCachePath(dir);
+    if (!existsSync(path))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return {};
+    }
+    const requiredCredentialId = expectedCredentialId ??
+        (dir ? undefined : configuredEnterpriseCredentialId(process.cwd()));
+    if (!dir && !requiredCredentialId) {
+        return {};
+    }
+    if (requiredCredentialId &&
+        parsed.credential_id !== requiredCredentialId) {
+        return {};
+    }
+    const records = parsed.capabilities;
+    if (!records || typeof records !== "object")
+        return {};
+    const out = {};
+    for (const [name, record] of Object.entries(records)) {
+        if (!record || typeof record !== "object")
+            continue;
+        const result = capabilityDefinitionSchema.safeParse(record.definition);
+        if (!result.success)
+            continue;
+        out[name] = result.data;
+    }
+    return out;
+}

package/scaffold/mcp/dist/core/workflow/synced-registry.js

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { configuredEnterpriseCredentialId } from "../enterprise-identity.js";
+import { workflowDefinitionSchema } 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";
+export function syncedWorkflowsCachePath(dir) {
+    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, expectedCredentialId) {
+    const path = syncedWorkflowsCachePath(dir);
+    if (!existsSync(path))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return {};
+    }
+    const requiredCredentialId = expectedCredentialId ??
+        (dir ? undefined : configuredEnterpriseCredentialId(process.cwd()));
+    if (!dir && !requiredCredentialId) {
+        return {};
+    }
+    if (requiredCredentialId &&
+        parsed.credential_id !== requiredCredentialId) {
+        return {};
+    }
+    const records = parsed.workflows;
+    if (!records || typeof records !== "object")
+        return {};
+    const out = {};
+    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/dist/daemon/capability-sync-checker.js

@@ -0,0 +1,242 @@
+import { existsSync, readFileSync, writeFileSync, } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { loadEnterpriseConfig } from "../core/config.js";
+import { matchesEnterpriseHostIdentity } from "../core/enterprise-host-identity.js";
+import { enterpriseCredentialId, isAllowedLicenseEndpoint, } from "../core/license.js";
+import { capabilityDefinitionSchema, } 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";
+function stateFilePath() {
+    return join(daemonDir(), STATE_FILENAME);
+}
+function readSyncedCapabilitiesState() {
+    const path = stateFilePath();
+    if (!existsSync(path))
+        return { capabilities: {} };
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return {
+            credential_id: typeof parsed.credential_id === "string"
+                ? parsed.credential_id
+                : undefined,
+            capabilities: parsed.capabilities ?? {},
+            last_synced_at: parsed.last_synced_at,
+        };
+    }
+    catch {
+        return { capabilities: {} };
+    }
+}
+function writeSyncedCapabilitiesState(state) {
+    writeFileSync(stateFilePath(), JSON.stringify(state, null, 2) + "\n", "utf8");
+}
+async function fetchManifest(baseUrl, apiKey) {
+    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());
+    return body.capabilities ?? [];
+}
+async function fetchCapability(baseUrl, apiKey, capabilityName) {
+    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());
+    if (!body.capability) {
+        throw new Error(`Response for ${capabilityName} missing 'capability' field`);
+    }
+    return body.capability;
+}
+export async function runCapabilitySyncOnce(cwd) {
+    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 = {
+            kind: "failed",
+            error: "enterprise not configured",
+        };
+        await writeAudit(cwd, outcome);
+        return outcome;
+    }
+    if (!isAllowedLicenseEndpoint(baseUrl)) {
+        const outcome = {
+            kind: "failed",
+            error: "insecure or invalid enterprise endpoint",
+        };
+        await writeAudit(cwd, outcome);
+        return outcome;
+    }
+    const credentialId = enterpriseCredentialId(baseUrl, apiKey);
+    if (!matchesEnterpriseHostIdentity(credentialId)) {
+        const outcome = {
+            kind: "failed",
+            error: "enterprise identity conflict: this user profile is already enrolled to another endpoint or API key",
+        };
+        await writeAudit(cwd, outcome);
+        return outcome;
+    }
+    const state = readSyncedCapabilitiesState();
+    const identityChanged = state.credential_id !== credentialId;
+    state.credential_id = credentialId;
+    let manifest;
+    try {
+        manifest = await fetchManifest(baseUrl, apiKey);
+    }
+    catch (err) {
+        const outcome = {
+            kind: "failed",
+            error: err instanceof Error ? err.message : String(err),
+        };
+        await writeAudit(cwd, outcome);
+        return outcome;
+    }
+    const remoteByName = new Map(manifest.map((e) => [e.capability_name, e]));
+    const added = [];
+    const changed = [];
+    const removed = [];
+    for (const entry of manifest) {
+        const local = state.capabilities[entry.capability_name];
+        const isNew = !local;
+        const isChanged = Boolean(local) &&
+            (identityChanged || local.updated_at !== entry.updated_at);
+        if (!isNew && !isChanged)
+            continue;
+        let fetched;
+        try {
+            fetched = await fetchCapability(baseUrl, apiKey, entry.capability_name);
+        }
+        catch (err) {
+            const outcome = {
+                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;
+        try {
+            validated = capabilityDefinitionSchema.parse(fetched.definition);
+        }
+        catch (err) {
+            const outcome = {
+                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) {
+        if (identityChanged) {
+            state.last_synced_at = new Date().toISOString();
+            writeSyncedCapabilitiesState(state);
+        }
+        const outcome = {
+            kind: "unchanged",
+            count: manifest.length,
+        };
+        await writeAudit(cwd, outcome);
+        return outcome;
+    }
+    state.last_synced_at = new Date().toISOString();
+    writeSyncedCapabilitiesState(state);
+    const outcome = {
+        kind: "synced",
+        added,
+        changed,
+        removed,
+    };
+    await writeAudit(cwd, outcome);
+    return outcome;
+}
+async function writeAudit(cwd, outcome) {
+    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 function startCapabilitySyncTimer(cwd, intervalMs) {
+    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);
+        },
+    };
+}