@danielblomma/cortex-mcp 2.2.5 → 2.4.1

package/scaffold/mcp/dist/core/workflow/default-workflows.js

@@ -0,0 +1,102 @@
+/**
+ * The default secure-build workflow that ships with Cortex. Organizations
+ * can override this from cortex-web later (Phase 2 of the harness rollout);
+ * until then this is the workflow every project gets out of the box.
+ */
+export const SECURE_BUILD_WORKFLOW = {
+    id: "secure-build",
+    description: "Plan → Review → Build → Review → Mutation Tests → Security Review → Human Approval. " +
+        "The default Cortex Harness workflow for AI-driven development on production code.",
+    version: 1,
+    stages: [
+        {
+            name: "plan",
+            artifact: "plan.md",
+            reads: [],
+            required_fields: ["files_targeted", "constraints"],
+            validators: [],
+            capability: "planner",
+            description: "Produce a step-by-step implementation plan grounded in the repo's rules and memory.",
+        },
+        {
+            name: "plan-review",
+            artifact: "plan-review.md",
+            reads: ["plan"],
+            required_fields: ["approved", "blocking_comments"],
+            validators: [],
+            capability: "reviewer",
+            description: "Review the plan for architectural fit and rule compliance before any code is written.",
+        },
+        {
+            name: "build",
+            artifact: "changes.md",
+            reads: ["plan", "plan-review"],
+            required_fields: ["files_changed"],
+            validators: [
+                {
+                    id: "build-passes",
+                    description: "The project's build / typecheck command must succeed on the produced diff.",
+                },
+                {
+                    id: "tests-pass",
+                    description: "The project's existing test suite must pass on the produced diff.",
+                },
+            ],
+            capability: "builder",
+            description: "Implement the approved plan. Produces the diff manifest used by the downstream reviewers.",
+        },
+        {
+            name: "build-review",
+            artifact: "build-review.md",
+            reads: ["plan", "changes"],
+            required_fields: ["approved", "blocking_comments"],
+            validators: [],
+            capability: "reviewer",
+            description: "Review the implementation against the plan and the project's rules.",
+        },
+        {
+            name: "mutation",
+            artifact: "mutation-report.md",
+            reads: ["changes"],
+            required_fields: ["score", "survived"],
+            validators: [
+                {
+                    id: "mutation-score",
+                    description: "Mutation testing tool of the agent's choice (e.g. stryker, mutmut) must run and report a score against the changed files.",
+                },
+            ],
+            capability: "tester",
+            description: "Run mutation tests on the changed files. Report score + surviving mutants.",
+        },
+        {
+            name: "security",
+            artifact: "security-report.md",
+            reads: ["changes"],
+            required_fields: ["findings", "severity_summary"],
+            validators: [
+                {
+                    id: "secret-scan",
+                    description: "Scan the diff for newly committed secrets (API keys, tokens, credentials).",
+                },
+                {
+                    id: "dependency-audit",
+                    description: "Audit any added or upgraded dependencies for known vulnerabilities.",
+                },
+            ],
+            capability: "security-reviewer",
+            description: "Security review focused on the diff: injection, authn/authz, secrets, dependency risk.",
+        },
+        {
+            name: "approval",
+            artifact: "approval.md",
+            reads: ["plan", "changes", "build-review", "mutation", "security"],
+            required_fields: ["approved", "approver"],
+            validators: [],
+            capability: "human",
+            description: "Human sign-off. Pulls every prior artifact for the approver to read; the approver writes the artifact.",
+        },
+    ],
+};
+export const DEFAULT_WORKFLOWS = {
+    [SECURE_BUILD_WORKFLOW.id]: SECURE_BUILD_WORKFLOW,
+};

package/scaffold/mcp/dist/core/workflow/enforcement.js

@@ -0,0 +1,164 @@
+import { isAbsolute, relative } from "node:path";
+import { minimatch } from "minimatch";
+import { readRunState } from "./artifact-io.js";
+import { DEFAULT_CAPABILITIES } from "./capabilities.js";
+import { workflowDefinitionSchema } from "./schemas.js";
+import { DEFAULT_WORKFLOWS } from "./default-workflows.js";
+import { loadSyncedCapabilities } from "./synced-capability-registry.js";
+import { configuredEnterpriseCredentialId } from "../enterprise-identity.js";
+/**
+ * Tool names that are pure mutations of the file system. Edits and writes
+ * gate against `write_globs`. Bash is treated as a mutation by default
+ * because we cannot reliably extract paths from arbitrary shell — agents
+ * running in restricted-write capabilities lose Bash unless the
+ * capability explicitly allow-lists it.
+ */
+const MUTATING_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+/**
+ * Tool names that read but do not mutate. Gate against `read_globs`.
+ */
+const READING_TOOLS = new Set(["Read", "Grep", "Glob", "NotebookRead"]);
+export function evaluateToolCall(options) {
+    const state = readRunState(options.cwd, options.taskId);
+    if (!state) {
+        return { allowed: true, reason: "no run state — harness not active" };
+    }
+    if (state.outcome !== "in_progress" || !state.current_stage) {
+        return {
+            allowed: true,
+            reason: `run not in progress (outcome=${state.outcome}) — no capability gate to apply`,
+        };
+    }
+    const workflows = options.workflows ?? DEFAULT_WORKFLOWS;
+    const workflow = workflows[state.workflow_id];
+    if (!workflow) {
+        return {
+            allowed: false,
+            reason: `unknown workflow_id ${state.workflow_id}; cannot resolve capability for current stage`,
+        };
+    }
+    // Validate so corrupt input doesn't slip through.
+    workflowDefinitionSchema.parse(workflow);
+    const stage = workflow.stages.find((s) => s.name === state.current_stage);
+    if (!stage) {
+        return {
+            allowed: false,
+            reason: `current stage ${state.current_stage} is not defined in workflow ${workflow.id}`,
+        };
+    }
+    if (!stage.capability) {
+        return { allowed: true, reason: "stage has no capability declared" };
+    }
+    // When the caller passes an explicit registry, use it as-is (tests).
+    // Otherwise merge bundled defaults with the daemon-synced org-authored
+    // capabilities, with synced ones taking precedence on name collisions
+    // so org overrides actually override.
+    const capabilities = options.capabilities ?? {
+        ...DEFAULT_CAPABILITIES,
+        ...loadSyncedCapabilities(undefined, configuredEnterpriseCredentialId(options.cwd) ?? undefined),
+    };
+    const capability = capabilities[stage.capability];
+    if (!capability) {
+        return {
+            allowed: false,
+            reason: `capability ${stage.capability} (referenced by stage ${stage.name}) is not in the registry`,
+        };
+    }
+    return evaluateAgainstCapability(capability, options.call, options.cwd);
+}
+function evaluateAgainstCapability(capability, call, cwd) {
+    // 1. tools_allowed: empty = no restriction; otherwise tool must be in the list.
+    if (capability.tools_allowed.length > 0 &&
+        !capability.tools_allowed.includes(call.toolName)) {
+        return {
+            allowed: false,
+            reason: `capability ${capability.name} does not allow tool ${call.toolName}`,
+        };
+    }
+    const isMutation = MUTATING_TOOLS.has(call.toolName);
+    const isRead = READING_TOOLS.has(call.toolName);
+    // Bash is special: with restricted write_globs we have to assume the
+    // worst (since the shell can write anywhere). Block unless capability
+    // explicitly allow-lists Bash via tools_allowed.
+    if (call.toolName === "Bash") {
+        const isAllowedViaToolList = capability.tools_allowed.includes("Bash");
+        const writesUnrestricted = capability.write_globs.length === 0;
+        if (writesUnrestricted && !isAllowedViaToolList) {
+            return {
+                allowed: false,
+                reason: `capability ${capability.name} is read-only; Bash can mutate the filesystem and is not allow-listed`,
+            };
+        }
+        return { allowed: true };
+    }
+    if (isMutation) {
+        if (capability.write_globs.length === 0) {
+            return {
+                allowed: false,
+                reason: `capability ${capability.name} is read-only; ${call.toolName} cannot run`,
+            };
+        }
+        const targetPath = extractFilePath(call.toolInput);
+        if (!targetPath) {
+            return {
+                allowed: false,
+                reason: `${call.toolName} did not include a file_path; cannot verify against capability ${capability.name}`,
+            };
+        }
+        const relPath = toRepoRelative(cwd, targetPath);
+        if (!matchesAnyGlob(relPath, capability.write_globs)) {
+            return {
+                allowed: false,
+                reason: `path ${relPath} is outside capability ${capability.name}'s write_globs (${capability.write_globs.join(", ")})`,
+            };
+        }
+        return { allowed: true };
+    }
+    if (isRead) {
+        if (capability.read_globs.length === 0) {
+            // No reads allowed at all — only the human capability lands here.
+            return {
+                allowed: false,
+                reason: `capability ${capability.name} does not permit any read operations`,
+            };
+        }
+        const targetPath = extractFilePath(call.toolInput);
+        if (!targetPath) {
+            // Some read tools (Grep, Glob) operate on the whole repo; allow
+            // through if the capability has any read access at all.
+            return { allowed: true };
+        }
+        const relPath = toRepoRelative(cwd, targetPath);
+        if (!matchesAnyGlob(relPath, capability.read_globs)) {
+            return {
+                allowed: false,
+                reason: `path ${relPath} is outside capability ${capability.name}'s read_globs (${capability.read_globs.join(", ")})`,
+            };
+        }
+        return { allowed: true };
+    }
+    // Unknown tool — fall through to allow if not explicitly restricted.
+    return { allowed: true };
+}
+function extractFilePath(toolInput) {
+    const candidates = ["file_path", "path", "notebook_path"];
+    for (const key of candidates) {
+        const value = toolInput[key];
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    }
+    return null;
+}
+function toRepoRelative(cwd, targetPath) {
+    if (!isAbsolute(targetPath))
+        return targetPath;
+    const rel = relative(cwd, targetPath);
+    // If the path is outside the repo, return the absolute form so glob
+    // matches (which expect repo-relative) reliably miss.
+    if (rel.startsWith(".."))
+        return targetPath;
+    return rel;
+}
+function matchesAnyGlob(path, globs) {
+    return globs.some((pattern) => minimatch(path, pattern, { dot: true, nocase: false }));
+}

package/scaffold/mcp/dist/core/workflow/envelope.js

@@ -0,0 +1,132 @@
+import { readFileSync } from "node:fs";
+import { artifactPath, readRunState } from "./artifact-io.js";
+import { workflowDefinitionSchema } from "./schemas.js";
+export function composeStageEnvelope(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}, envelope was composed with ${workflow.id}`);
+    }
+    const stageName = options.stageName ?? state.current_stage;
+    if (!stageName) {
+        throw new Error(`Run ${options.taskId} is not at any stage (outcome=${state.outcome}). Cannot compose envelope.`);
+    }
+    const stage = workflow.stages.find((s) => s.name === stageName);
+    if (!stage) {
+        throw new Error(`Stage ${stageName} is not defined in workflow ${workflow.id}`);
+    }
+    const handoffs = [];
+    for (const readName of stage.reads) {
+        const priorStage = workflow.stages.find((s) => s.name === readName);
+        if (!priorStage) {
+            throw new Error(`Stage ${stageName} declares reads from unknown stage ${readName}`);
+        }
+        const priorRecord = state.stages.find((r) => r.name === readName);
+        if (!priorRecord || priorRecord.status === "pending" || !priorRecord.artifact) {
+            throw new Error(`Stage ${stageName} requires artifact from ${readName}, but it has not been produced yet`);
+        }
+        const path = artifactPath(options.cwd, options.taskId, priorRecord.artifact);
+        let raw;
+        try {
+            raw = readFileSync(path, "utf8");
+        }
+        catch (err) {
+            throw new Error(`Failed to read handoff artifact for ${readName} at ${path}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        handoffs.push(renderHandoff(readName, priorRecord.artifact, raw));
+    }
+    const requiredFields = stage.required_fields;
+    const capability = stage.capability ?? null;
+    const validators = stage.validators;
+    const prompt = renderPrompt({
+        taskDescription: state.task_description,
+        workflowId: workflow.id,
+        workflowDescription: workflow.description,
+        stageName: stage.name,
+        stageDescription: stage.description,
+        expectedArtifact: stage.artifact,
+        requiredFields,
+        capability,
+        handoffs,
+        validators,
+    });
+    return {
+        prompt,
+        expectedArtifact: stage.artifact,
+        requiredFields,
+        capability,
+        validators,
+    };
+}
+function renderHandoff(stageName, artifactName, rawArtifact) {
+    return [
+        `--- handoff:${stageName} (${artifactName}) ---`,
+        rawArtifact.trim(),
+        `--- end handoff:${stageName} ---`,
+    ].join("\n");
+}
+function renderPrompt(o) {
+    const sections = [];
+    sections.push([
+        `# TASK`,
+        ``,
+        o.taskDescription.trim(),
+        ``,
+        `Workflow: ${o.workflowId} — ${o.workflowDescription}`,
+    ].join("\n"));
+    sections.push([
+        `# STAGE: ${o.stageName}`,
+        ``,
+        o.stageDescription.trim(),
+        ``,
+        o.capability
+            ? `Running under capability: \`${o.capability}\` (file and tool restrictions are enforced by Cortex hooks at tool-use time, not by you).`
+            : `No capability constraint declared for this stage.`,
+    ].join("\n"));
+    if (o.handoffs.length === 0) {
+        sections.push([`# HANDOFFS`, ``, `_No prior-stage artifacts; this is the first stage._`].join("\n"));
+    }
+    else {
+        sections.push([
+            `# HANDOFFS`,
+            ``,
+            `The following stages have already run. Each artifact below is the complete file as it lives on disk; use the frontmatter for structured outcomes and the body for reasoning.`,
+            ``,
+            ...o.handoffs,
+        ].join("\n"));
+    }
+    const requiredLines = o.requiredFields.length === 0
+        ? `_No additional required fields beyond the harness defaults._`
+        : o.requiredFields.map((f) => `- \`${f}\``).join("\n");
+    const validatorLines = o.validators.length === 0
+        ? `_No validators required for this stage._`
+        : o.validators
+            .map((v) => `- \`${v.id}\` — ${v.description}`)
+            .join("\n");
+    sections.push([
+        `# VALIDATORS`,
+        ``,
+        `Cortex defines what must be validated; you (the agent) pick the concrete tooling and run it in this environment, then report back.`,
+        ``,
+        validatorLines,
+        ``,
+        `When you call \`cortex.workflow.advance\`, set \`validators_passed: [<id1>, <id2>, ...]\` listing every validator you successfully ran. The harness blocks the advance if a required validator is missing — unless you explicitly pass \`override\` with a reason and the list of skipped validator ids.`,
+    ].join("\n"));
+    sections.push([
+        `# OUTPUT`,
+        ``,
+        `Produce a single markdown file named \`${o.expectedArtifact}\` with YAML frontmatter on top.`,
+        ``,
+        `Required frontmatter fields (in addition to \`stage\`, \`status\`, \`references\`, \`validators_passed\`, \`written_at\` which the harness manages):`,
+        ``,
+        requiredLines,
+        ``,
+        `Body: clear, well-structured markdown explaining your reasoning. Cite handoff artifacts by stage name when relevant.`,
+        ``,
+        `If you cannot complete this stage (missing context, blocking concern, conflicting prior decisions), set \`status: blocked\` in frontmatter and explain why in the body — do not fabricate work.`,
+    ].join("\n"));
+    return sections.join("\n\n");
+}

package/scaffold/mcp/dist/core/workflow/index.js

@@ -0,0 +1,11 @@
+export * from "./schemas.js";
+export * from "./artifact-io.js";
+export * from "./run-lifecycle.js";
+export * from "./envelope.js";
+export * from "./default-workflows.js";
+export * from "./mcp-tools.js";
+export * from "./capabilities.js";
+export * from "./enforcement.js";
+export * from "./synced-registry.js";
+export * from "./synced-capability-registry.js";
+export * from "./resolution.js";

package/scaffold/mcp/dist/core/workflow/mcp-tools.js

@@ -0,0 +1,175 @@
+import { z } from "zod";
+import { advanceStage, createRun, getRunState } from "./run-lifecycle.js";
+import { composeStageEnvelope } from "./envelope.js";
+import { resolveWorkflowDefinition } from "./resolution.js";
+import { stageOverrideSchema, stageStatusSchema, } 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 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(),
+    /**
+     * Validators the agent reports having run for this stage. Compared
+     * against the stage definition's required validators on advance —
+     * missing entries block the call unless an override is supplied.
+     */
+    validators_passed: z.array(z.string().min(1)).default([]),
+    /**
+     * Process override. Required when validators_passed does not cover
+     * every validator the stage declares. Logged as a high-evidence
+     * audit event and stamped into the artifact's frontmatter so the
+     * deviation is visible in the evidence trail.
+     */
+    override: stageOverrideSchema.optional(),
+});
+export const WorkflowStatusInput = z.object({
+    task_id: slugSchema,
+});
+export const WorkflowEnvelopeInput = z.object({
+    task_id: slugSchema,
+    /** Defaults to the run's current stage. */
+    stage: slugSchema.optional(),
+});
+/**
+ * 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() {
+    const fromEnv = process.env.CORTEX_PROJECT_ROOT?.trim();
+    if (fromEnv)
+        return fromEnv;
+    return process.cwd();
+}
+export function runWorkflowStart(input, ctx) {
+    const resolved = resolveWorkflowDefinition(input.workflow_id, {
+        registry: ctx.workflows,
+        cwd: ctx.cwd,
+        bundledFallbackPolicy: ctx.bundledFallbackPolicy,
+    });
+    const workflow = resolved.workflow;
+    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,
+        workflow_source: resolved.source,
+        warnings: resolved.warnings,
+    };
+}
+export function runWorkflowAdvance(input, ctx) {
+    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 = resolveWorkflowDefinition(state.workflow_id, {
+        registry: ctx.workflows,
+        cwd: ctx.cwd,
+    }).workflow;
+    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 = 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.references)
+                ? input.frontmatter.references
+                    .filter((v) => typeof v === "string")
+                : null) ?? deriveReferencesFromReads(stage.reads, workflow),
+        },
+        body: input.body,
+        outcome: input.outcome,
+        status: finalStatus,
+        validatorsPassed: input.validators_passed,
+        override: input.override,
+    });
+    // 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 = 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, workflow) {
+    const refs = [];
+    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, ctx) {
+    const state = getRunState(ctx.cwd, input.task_id);
+    return { state };
+}
+export function runWorkflowEnvelope(input, ctx) {
+    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 = resolveWorkflowDefinition(state.workflow_id, {
+        registry: ctx.workflows,
+        cwd: ctx.cwd,
+    }).workflow;
+    const envelope = composeStageEnvelope({
+        cwd: ctx.cwd,
+        taskId: input.task_id,
+        workflow,
+        stageName: input.stage,
+    });
+    return { envelope };
+}

package/scaffold/mcp/dist/core/workflow/resolution.js

@@ -0,0 +1,69 @@
+import { DEFAULT_WORKFLOWS } from "./default-workflows.js";
+import { loadSyncedWorkflows } from "./synced-registry.js";
+import { configuredEnterpriseCredentialId } from "../enterprise-identity.js";
+function sortIds(ids) {
+    return [...ids].sort((left, right) => left.localeCompare(right));
+}
+function formatIds(ids) {
+    return ids.length > 0 ? ids.join(", ") : "<none>";
+}
+export function resolveWorkflowDefinition(workflowId, options = {}) {
+    if (options.registry) {
+        const availableIds = sortIds(Object.keys(options.registry));
+        const workflow = options.registry[workflowId];
+        if (!workflow) {
+            throw new Error(`Unknown workflow_id: ${workflowId}. Available injected: ${formatIds(availableIds)}`);
+        }
+        return {
+            workflow,
+            source: "injected",
+            warnings: [],
+            bundled_ids: [],
+            synced_ids: [],
+            available_ids: availableIds,
+        };
+    }
+    const bundled = DEFAULT_WORKFLOWS;
+    const expectedCredentialId = options.syncedDir
+        ? undefined
+        : configuredEnterpriseCredentialId(options.cwd ?? process.cwd()) ?? undefined;
+    const synced = loadSyncedWorkflows(options.syncedDir, expectedCredentialId);
+    const bundledIds = sortIds(Object.keys(bundled));
+    const syncedIds = sortIds(Object.keys(synced));
+    const merged = { ...bundled, ...synced };
+    const availableIds = sortIds(Object.keys(merged));
+    const workflow = merged[workflowId];
+    if (!workflow) {
+        throw new Error(`Unknown workflow_id: ${workflowId}. Available bundled: ${formatIds(bundledIds)}. ` +
+            `Available synced: ${formatIds(syncedIds)}. Available all: ${formatIds(availableIds)}`);
+    }
+    const source = Object.prototype.hasOwnProperty.call(synced, workflowId)
+        ? "synced"
+        : "bundled";
+    const warnings = [];
+    const fallbackPolicy = options.bundledFallbackPolicy ?? "allow";
+    if (source === "bundled" && fallbackPolicy === "block") {
+        throw new Error(`Workflow "${workflowId}" is only available from the bundled registry, ` +
+            "but enforced govern mode requires a synced org workflow. " +
+            `Available synced: ${formatIds(syncedIds)}.`);
+    }
+    if (source === "bundled" &&
+        (options.emitBundledFallbackWarning || fallbackPolicy === "warn")) {
+        warnings.push({
+            code: "bundled-workflow-fallback",
+            workflow_id: workflowId,
+            bundled_available: true,
+            synced_available: syncedIds.length > 0,
+            message: `Workflow "${workflowId}" was resolved from the bundled registry because ` +
+                "no synced org workflow with that id exists in the local cache.",
+        });
+    }
+    return {
+        workflow,
+        source,
+        warnings,
+        bundled_ids: bundledIds,
+        synced_ids: syncedIds,
+        available_ids: availableIds,
+    };
+}