@wopr-network/defcon 0.2.0 → 0.2.2

package/dist/execution/mcp-server.js

@@ -1,1020 +0,0 @@
-// MCP server — passive mode (flow.claim, flow.report, query.*)
-import { createHash, timingSafeEqual } from "node:crypto";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { DEFAULT_TIMEOUT_PROMPT } from "../engine/constants.js";
-import { isTerminal } from "../engine/state-machine.js";
-import { consoleLogger } from "../logger.js";
-import { AdminFlowCreateSchema, AdminFlowRestoreSchema, AdminFlowSnapshotSchema, AdminFlowUpdateSchema, AdminGateAttachSchema, AdminGateCreateSchema, AdminStateCreateSchema, AdminStateUpdateSchema, AdminTransitionCreateSchema, AdminTransitionUpdateSchema, } from "./admin-schemas.js";
-import { FlowClaimSchema, FlowFailSchema, FlowGetPromptSchema, FlowReportSchema, FlowSeedSchema, QueryEntitiesSchema, QueryEntitySchema, QueryFlowSchema, QueryInvocationsSchema, } from "./tool-schemas.js";
-function getSystemDefaultGateTimeoutMs() {
-    const parsed = parseInt(process.env.DEFCON_DEFAULT_GATE_TIMEOUT_MS ?? "", 10);
-    return !Number.isNaN(parsed) && parsed > 0 ? parsed : 300000;
-}
-const SYSTEM_DEFAULT_GATE_TIMEOUT_MS = getSystemDefaultGateTimeoutMs();
-const TOOL_DEFINITIONS = [
-    {
-        name: "flow.claim",
-        description: "Claim the next available work item for a given discipline role. DEFCON selects the highest-priority entity across all matching flows. Returns entity_id, invocation_id, flow, stage, prompt — or a check_back response with retry_after_ms if no work is available.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                worker_id: { type: "string", description: "Unique worker identifier for affinity tracking" },
-                role: { type: "string", description: "Discipline role (e.g. engineering, devops, qa, security)" },
-                flow: { type: "string", description: "Optional flow name to restrict claim to a single flow" },
-            },
-            required: ["role"],
-        },
-    },
-    {
-        name: "flow.get_prompt",
-        description: "Get the current prompt and context for an entity. Useful if agent needs to re-read its assignment.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                entity_id: { type: "string", description: "Entity ID" },
-            },
-            required: ["entity_id"],
-        },
-    },
-    {
-        name: "flow.report",
-        description: "Report completion of work on an entity. **This call blocks until gate evaluation completes** — " +
-            "which may take milliseconds (trivial gate) or many minutes (CI pipeline). Do not set a short client-side " +
-            "timeout on this call. For HTTP/SSE transports, configure a long timeout (24h is safe). " +
-            "The stdio transport has no timeout by default. " +
-            'Returns next_action: "continue" (next prompt ready), "waiting" (gate failed — stop, do not retry), ' +
-            '"check_back" (gate timed out — not an error, call flow.report again with the same arguments after retry_after_ms), ' +
-            'or "completed" (terminal state). ' +
-            "Set gate timeout_ms to the maximum time you are willing to wait, not an expected duration — " +
-            "the call returns as soon as the gate resolves. " +
-            "gates_passed contains gate names (not IDs).",
-        inputSchema: {
-            type: "object",
-            properties: {
-                entity_id: { type: "string", description: "Entity ID" },
-                signal: {
-                    type: "string",
-                    description: "Completion signal (matches transition trigger)",
-                },
-                artifacts: { type: "object", description: "Optional artifacts to attach" },
-                worker_id: { type: "string", description: "Optional stable worker identifier for affinity routing" },
-            },
-            required: ["entity_id", "signal"],
-        },
-    },
-    {
-        name: "flow.fail",
-        description: "Report failure on an entity. Marks the current invocation as failed.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                entity_id: { type: "string", description: "Entity ID" },
-                error: { type: "string", description: "Error message" },
-            },
-            required: ["entity_id", "error"],
-        },
-    },
-    {
-        name: "query.entity",
-        description: "Get full entity details including history.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                id: { type: "string", description: "Entity ID" },
-            },
-            required: ["id"],
-        },
-    },
-    {
-        name: "query.entities",
-        description: "Search entities by flow and state.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                flow: { type: "string", description: "Flow name to filter by" },
-                state: { type: "string", description: "State to filter by" },
-                limit: { type: "number", description: "Max results (default 50)" },
-            },
-            required: ["flow", "state"],
-        },
-    },
-    {
-        name: "query.invocations",
-        description: "Get all invocations for an entity.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                entity_id: { type: "string", description: "Entity ID" },
-            },
-            required: ["entity_id"],
-        },
-    },
-    {
-        name: "query.flow",
-        description: "Get a flow definition with its states and transitions.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                name: { type: "string", description: "Flow name" },
-            },
-            required: ["name"],
-        },
-    },
-    {
-        name: "query.flows",
-        description: "List all available flow definitions.",
-        inputSchema: {
-            type: "object",
-            properties: {},
-            required: [],
-        },
-    },
-    // ─── Admin Tools ───
-    {
-        name: "admin.flow.create",
-        description: "Create a new flow definition with its initial states.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                name: { type: "string", description: "Unique flow name" },
-                initialState: { type: "string", description: "Name of the initial state (must be in states array)" },
-                discipline: {
-                    type: "string",
-                    description: "Discipline role required to claim work in this flow (e.g. engineering, devops). Null means any role can claim.",
-                },
-                defaultModelTier: {
-                    type: "string",
-                    description: "Default model tier for states that don't specify one (opus, sonnet, haiku)",
-                },
-                description: { type: "string", description: "Flow description" },
-                entitySchema: { type: "object", description: "JSON schema for entity data" },
-                maxConcurrent: { type: "number", description: "Max concurrent entities (0=unlimited)" },
-                maxConcurrentPerRepo: { type: "number", description: "Max concurrent per repo (0=unlimited)" },
-                affinityWindowMs: { type: "number", description: "Worker affinity window duration in ms (default 300000)" },
-                gateTimeoutMs: {
-                    type: "number",
-                    description: `Default gate timeout in ms for all gates in this flow (default ${SYSTEM_DEFAULT_GATE_TIMEOUT_MS})`,
-                },
-                createdBy: { type: "string", description: "Creator identifier" },
-                states: {
-                    type: "array",
-                    description: "State definitions (at least one required; must include initialState)",
-                    items: { type: "object" },
-                },
-            },
-            required: ["name", "initialState", "states"],
-        },
-    },
-    {
-        name: "admin.flow.update",
-        description: "Update a flow's metadata (description, concurrency limits, etc.).",
-        inputSchema: {
-            type: "object",
-            properties: {
-                flow_name: { type: "string", description: "Flow name to update" },
-                description: { type: "string" },
-                discipline: { type: "string", description: "Discipline role required to claim work in this flow" },
-                defaultModelTier: { type: "string", description: "Default model tier for states that don't specify one" },
-                maxConcurrent: { type: "number" },
-                maxConcurrentPerRepo: { type: "number" },
-                affinityWindowMs: { type: "number", description: "Worker affinity window duration in ms (default 300000)" },
-                gateTimeoutMs: { type: "number", description: "Default gate timeout in ms for all gates in this flow" },
-                initialState: { type: "string" },
-            },
-            required: ["flow_name"],
-        },
-    },
-    {
-        name: "admin.state.create",
-        description: "Add a state to an existing flow.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                flow_name: { type: "string", description: "Flow name" },
-                name: { type: "string", description: "State name" },
-                modelTier: { type: "string" },
-                mode: { type: "string", description: "passive or active" },
-                promptTemplate: { type: "string" },
-                constraints: { type: "object" },
-            },
-            required: ["flow_name", "name"],
-        },
-    },
-    {
-        name: "admin.state.update",
-        description: "Update fields on an existing state.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                flow_name: { type: "string", description: "Flow name" },
-                state_name: { type: "string", description: "State name to update" },
-                modelTier: { type: "string" },
-                mode: { type: "string" },
-                promptTemplate: { type: "string" },
-                constraints: { type: "object" },
-            },
-            required: ["flow_name", "state_name"],
-        },
-    },
-    {
-        name: "admin.transition.create",
-        description: "Add a transition rule between two states.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                flow_name: { type: "string" },
-                fromState: { type: "string" },
-                toState: { type: "string" },
-                trigger: { type: "string" },
-                gateName: { type: "string" },
-                condition: { type: "string" },
-                priority: { type: "number" },
-                spawnFlow: { type: "string" },
-                spawnTemplate: { type: "string" },
-            },
-            required: ["flow_name", "fromState", "toState", "trigger"],
-        },
-    },
-    {
-        name: "admin.transition.update",
-        description: "Update an existing transition rule.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                flow_name: { type: "string" },
-                transition_id: { type: "string" },
-                fromState: { type: "string" },
-                toState: { type: "string" },
-                trigger: { type: "string" },
-                gateName: { type: "string" },
-                condition: { type: "string" },
-                priority: { type: "number" },
-                spawnFlow: { type: "string" },
-                spawnTemplate: { type: "string" },
-            },
-            required: ["flow_name", "transition_id"],
-        },
-    },
-    {
-        name: "admin.gate.create",
-        description: "Create a gate definition (command, function, or api).",
-        inputSchema: {
-            type: "object",
-            properties: {
-                name: { type: "string" },
-                type: { type: "string", description: "command | function | api" },
-                command: { type: "string" },
-                functionRef: { type: "string" },
-                apiConfig: { type: "object" },
-                timeoutMs: { type: "number" },
-                failurePrompt: { type: "string" },
-                timeoutPrompt: { type: "string" },
-            },
-            required: ["name", "type"],
-        },
-    },
-    {
-        name: "admin.gate.attach",
-        description: "Attach a gate to a transition.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                flow_name: { type: "string" },
-                transition_id: { type: "string" },
-                gate_name: { type: "string" },
-            },
-            required: ["flow_name", "transition_id", "gate_name"],
-        },
-    },
-    {
-        name: "admin.flow.snapshot",
-        description: "Create a versioned snapshot of the current flow state.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                flow_name: { type: "string" },
-            },
-            required: ["flow_name"],
-        },
-    },
-    {
-        name: "admin.flow.restore",
-        description: "Restore a flow to a previously snapshotted version.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                flow_name: { type: "string" },
-                version: { type: "number" },
-            },
-            required: ["flow_name", "version"],
-        },
-    },
-    {
-        name: "admin.entity.create",
-        description: "Create a new entity in a flow (seed). Equivalent to POST /api/entities. " +
-            "Creates the entity at the flow's initial state and generates the first invocation if the initial state has an agent role. " +
-            "Returns the full Entity object plus an optional invocation_id if the initial state created an invocation.",
-        // inputSchema mirrors FlowSeedSchema in src/execution/tool-schemas.ts — keep in sync
-        inputSchema: {
-            type: "object",
-            properties: {
-                flow: { type: "string", description: "Flow name to create the entity in" },
-                refs: {
-                    type: "object",
-                    description: "Optional external references. Keys are ref names, values are objects with at least { adapter: string, id: string }",
-                    additionalProperties: {
-                        type: "object",
-                        properties: {
-                            adapter: { type: "string" },
-                            id: { type: "string" },
-                        },
-                        required: ["adapter", "id"],
-                    },
-                },
-            },
-            required: ["flow"],
-        },
-    },
-];
-export function createMcpServer(deps, opts) {
-    const server = new Server({ name: "agentic-flow", version: "0.1.0" }, { capabilities: { tools: {} } });
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: TOOL_DEFINITIONS,
-    }));
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        const { name, arguments: args } = request.params;
-        const safeArgs = (args ?? {});
-        return callToolHandler(deps, name, safeArgs, opts);
-    });
-    return server;
-}
-export async function callToolHandler(deps, name, safeArgs, opts) {
-    try {
-        // Auth gate: admin.* tools require a valid token when one is configured
-        if (name.startsWith("admin.")) {
-            const configuredToken = opts?.adminToken || undefined; // treat "" as unset
-            if (configuredToken && !opts?.stdioTrusted) {
-                const callerToken = opts?.callerToken;
-                if (!callerToken || !constantTimeEqual(configuredToken, callerToken)) {
-                    return errorResult("Unauthorized: admin tools require authentication. Check server configuration.");
-                }
-            }
-        }
-        // Auth gate: flow.* tools and query.flows require a valid worker token when one is configured
-        if (name.startsWith("flow.") || name === "query.flows") {
-            const configuredToken = opts?.workerToken?.trim() || undefined; // treat "" or whitespace-only as unset
-            if (configuredToken && !opts?.stdioTrusted) {
-                const callerToken = opts?.callerToken;
-                if (!callerToken || !constantTimeEqual(configuredToken, callerToken)) {
-                    return errorResult("Unauthorized: worker tools require authentication. Check server configuration.");
-                }
-            }
-        }
-        switch (name) {
-            case "flow.claim":
-                return await handleFlowClaim(deps, safeArgs);
-            case "flow.get_prompt":
-                return await handleFlowGetPrompt(deps, safeArgs);
-            case "flow.report":
-                return await handleFlowReport(deps, safeArgs);
-            case "flow.fail":
-                return await handleFlowFail(deps, safeArgs);
-            case "query.entity":
-                return await handleQueryEntity(deps, safeArgs);
-            case "query.entities":
-                return await handleQueryEntities(deps, safeArgs);
-            case "query.invocations":
-                return await handleQueryInvocations(deps, safeArgs);
-            case "query.flow":
-                return await handleQueryFlow(deps, safeArgs);
-            case "query.flows":
-                return await handleQueryFlows(deps);
-            case "admin.flow.create":
-                return await handleAdminFlowCreate(deps, safeArgs);
-            case "admin.flow.update":
-                return await handleAdminFlowUpdate(deps, safeArgs);
-            case "admin.state.create":
-                return await handleAdminStateCreate(deps, safeArgs);
-            case "admin.state.update":
-                return await handleAdminStateUpdate(deps, safeArgs);
-            case "admin.transition.create":
-                return await handleAdminTransitionCreate(deps, safeArgs);
-            case "admin.transition.update":
-                return await handleAdminTransitionUpdate(deps, safeArgs);
-            case "admin.gate.create":
-                return await handleAdminGateCreate(deps, safeArgs);
-            case "admin.gate.attach":
-                return await handleAdminGateAttach(deps, safeArgs);
-            case "admin.flow.snapshot":
-                return await handleAdminFlowSnapshot(deps, safeArgs);
-            case "admin.flow.restore":
-                return await handleAdminFlowRestore(deps, safeArgs);
-            case "admin.entity.create":
-                return await handleAdminEntityCreate(deps, safeArgs);
-            default:
-                return errorResult(`Unknown tool: ${name}`);
-        }
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return errorResult(message);
-    }
-}
-function jsonResult(data) {
-    return {
-        content: [{ type: "text", text: JSON.stringify(data) }],
-    };
-}
-function errorResult(message) {
-    return {
-        content: [{ type: "text", text: message }],
-        isError: true,
-    };
-}
-const RETRY_SHORT_MS = 30_000; // entities exist but all claimed
-const RETRY_LONG_MS = 300_000; // backlog empty
-function noWorkResult(retryAfterMs, role) {
-    return jsonResult({
-        next_action: "check_back",
-        retry_after_ms: retryAfterMs,
-        message: `No work available for role '${role}' right now. Call flow.claim again after the retry delay.`,
-    });
-}
-function constantTimeEqual(a, b) {
-    const hashA = createHash("sha256").update(a.trim()).digest();
-    const hashB = createHash("sha256").update(b.trim()).digest();
-    return timingSafeEqual(hashA, hashB);
-}
-// ─── Tool Handlers ───
-const AFFINITY_WINDOW_MS = 5 * 60 * 1000; // 5 minutes
-async function handleFlowClaim(deps, args) {
-    const v = validateInput(FlowClaimSchema, args);
-    if (!v.ok)
-        return v.result;
-    const log = deps.logger ?? consoleLogger;
-    const { worker_id, role, flow: flowName } = v.data;
-    // 1. Find candidate flows filtered by discipline
-    let candidateFlows = [];
-    if (flowName) {
-        const flow = await deps.flows.getByName(flowName);
-        if (!flow)
-            return errorResult(`Flow not found: ${flowName}`);
-        // Discipline must match — null discipline flows are claimable by any role
-        if (flow.discipline !== null && flow.discipline !== role)
-            return noWorkResult(RETRY_LONG_MS, role);
-        candidateFlows = [flow];
-    }
-    else {
-        const allFlows = await deps.flows.list();
-        candidateFlows = allFlows.filter((f) => f.discipline === null || f.discipline === role);
-    }
-    if (candidateFlows.length === 0)
-        return noWorkResult(RETRY_LONG_MS, role);
-    const allCandidates = [];
-    for (const flow of candidateFlows) {
-        const unclaimed = await deps.invocations.findUnclaimedByFlow(flow.id);
-        allCandidates.push(...unclaimed);
-    }
-    if (allCandidates.length === 0) {
-        // Determine if entities exist but are all claimed (short retry) vs empty backlog (long retry).
-        // Use hasAnyInFlowAndState (SELECT 1 LIMIT 1) to avoid loading full entity rows across all states.
-        let hasEntities = false;
-        for (const flow of candidateFlows) {
-            const stateNames = flow.states.filter((s) => s.promptTemplate !== null).map((s) => s.name);
-            if (await deps.entities.hasAnyInFlowAndState(flow.id, stateNames)) {
-                hasEntities = true;
-                break;
-            }
-        }
-        return noWorkResult(hasEntities ? RETRY_SHORT_MS : RETRY_LONG_MS, role);
-    }
-    // 3. Load entities for priority sorting
-    const entityMap = new Map();
-    const uniqueEntityIds = [...new Set(allCandidates.map((inv) => inv.entityId))];
-    await Promise.all(uniqueEntityIds.map(async (eid) => {
-        const entity = await deps.entities.get(eid);
-        if (entity)
-            entityMap.set(eid, entity);
-    }));
-    // 4. Check affinity for each entity
-    const flowByIdEarly = new Map(candidateFlows.map((f) => [f.id, f]));
-    const affinitySet = new Set();
-    const now = Date.now();
-    if (worker_id) {
-        await Promise.all(uniqueEntityIds.map(async (eid) => {
-            const entity = entityMap.get(eid);
-            const flow = entity ? flowByIdEarly.get(entity.flowId) : undefined;
-            const windowMs = flow?.affinityWindowMs ?? AFFINITY_WINDOW_MS;
-            const invocations = await deps.invocations.findByEntity(eid);
-            const lastCompleted = invocations
-                .filter((inv) => inv.completedAt !== null && inv.claimedBy === worker_id)
-                .sort((a, b) => (b.completedAt?.getTime() ?? 0) - (a.completedAt?.getTime() ?? 0));
-            if (lastCompleted.length > 0) {
-                const elapsed = now - (lastCompleted[0].completedAt?.getTime() ?? 0);
-                if (elapsed < windowMs) {
-                    affinitySet.add(eid);
-                }
-            }
-        }));
-    }
-    // 5. Sort candidates by priority algorithm
-    allCandidates.sort((a, b) => {
-        const entityA = entityMap.get(a.entityId);
-        const entityB = entityMap.get(b.entityId);
-        // Tier 1: Affinity (has affinity sorts first)
-        const affinityA = affinitySet.has(a.entityId) ? 1 : 0;
-        const affinityB = affinitySet.has(b.entityId) ? 1 : 0;
-        if (affinityA !== affinityB)
-            return affinityB - affinityA;
-        // Tier 2: Entity priority (higher priority sorts first)
-        const priA = entityA?.priority ?? 0;
-        const priB = entityB?.priority ?? 0;
-        if (priA !== priB)
-            return priB - priA;
-        // Tier 3: Time in state (longest waiting sorts first — earlier createdAt as stable proxy)
-        const timeA = entityA?.createdAt?.getTime() ?? now;
-        const timeB = entityB?.createdAt?.getTime() ?? now;
-        return timeA - timeB;
-    });
-    // 6. Build a flow lookup map
-    const flowById = new Map(candidateFlows.map((f) => [f.id, f]));
-    // 7. Try claiming in priority order (handle race conditions)
-    for (const invocation of allCandidates) {
-        let claimed;
-        try {
-            claimed = await deps.invocations.claim(invocation.id, worker_id ?? `agent:${role}`);
-        }
-        catch (err) {
-            log.error(`Failed to claim invocation ${invocation.id}:`, err);
-            continue;
-        }
-        if (claimed) {
-            const entity = entityMap.get(claimed.entityId);
-            if (entity) {
-                let claimedEntity;
-                try {
-                    claimedEntity = await deps.entities.claimById(entity.id, worker_id ?? `agent:${role}`);
-                }
-                catch (err) {
-                    log.error(`Failed to claimById for entity ${entity.id}:`, err);
-                    // Release the invocation claim so it can be reclaimed rather than orphaned.
-                    await deps.invocations.releaseClaim(claimed.id);
-                    continue;
-                }
-                if (!claimedEntity) {
-                    // Race condition: another worker claimed this entity first.
-                    // Release the invocation claim so it can be picked up by another worker.
-                    await deps.invocations.releaseClaim(claimed.id);
-                    continue;
-                }
-            }
-            const flow = entity ? flowById.get(entity.flowId) : undefined;
-            // Record affinity for the claiming worker
-            if (worker_id && entity && flow) {
-                const windowMs = flow.affinityWindowMs ?? 300000;
-                try {
-                    await deps.entities.setAffinity(claimed.entityId, worker_id, role, new Date(Date.now() + windowMs));
-                }
-                catch (err) {
-                    // Affinity is non-critical — log and continue with the successful claim.
-                    log.error(`Failed to set affinity for entity ${claimed.entityId} worker ${worker_id}:`, err);
-                }
-            }
-            return jsonResult({
-                worker_id: worker_id,
-                entity_id: claimed.entityId,
-                invocation_id: claimed.id,
-                flow: flow?.name ?? null,
-                stage: claimed.stage,
-                prompt: claimed.prompt,
-                context: claimed.context,
-            });
-        }
-    }
-    return noWorkResult(RETRY_SHORT_MS, role);
-}
-async function handleFlowGetPrompt(deps, args) {
-    const v = validateInput(FlowGetPromptSchema, args);
-    if (!v.ok)
-        return v.result;
-    const { entity_id: entityId } = v.data;
-    const entity = await deps.entities.get(entityId);
-    if (!entity)
-        return errorResult(`Entity not found: ${entityId}`);
-    const invocationList = await deps.invocations.findByEntity(entityId);
-    if (invocationList.length === 0) {
-        return errorResult(`No invocations found for entity: ${entityId}`);
-    }
-    // Return the active (claimed, not completed) invocation rather than the last by insertion order
-    const active = invocationList.find((inv) => inv.claimedAt !== null && inv.completedAt === null && inv.failedAt === null) ??
-        invocationList[invocationList.length - 1];
-    return jsonResult({
-        prompt: active.prompt,
-        context: active.context,
-    });
-}
-async function handleFlowReport(deps, args) {
-    const v = validateInput(FlowReportSchema, args);
-    if (!v.ok)
-        return v.result;
-    const log = deps.logger ?? consoleLogger;
-    const { entity_id: entityId, signal, artifacts, worker_id } = v.data;
-    const invocationList = await deps.invocations.findByEntity(entityId);
-    const activeInvocation = invocationList.find((inv) => inv.claimedAt !== null && inv.completedAt === null && inv.failedAt === null);
-    if (!activeInvocation) {
-        return errorResult(`No active invocation found for entity: ${entityId}`);
-    }
-    if (!deps.engine) {
-        return errorResult("Engine not available — MCP server started without engine dependency");
-    }
-    // Complete the current invocation BEFORE calling processSignal so the
-    // concurrency check inside the engine doesn't count it as still-active.
-    await deps.invocations.complete(activeInvocation.id, signal, artifacts);
-    // Delegate to the engine — it handles gate evaluation, transition, event
-    // emission, invocation creation, concurrency checks, and spawn logic.
-    let result;
-    try {
-        result = await deps.engine.processSignal(entityId, signal, artifacts, activeInvocation.id);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        // processSignal failed after we already completed the invocation — create a
-        // replacement so the entity can be reclaimed rather than being permanently orphaned.
-        // First re-fetch to check whether the engine already created a new invocation
-        // (partial success before the throw) to avoid a duplicate.
-        const currentInvocations = await deps.invocations.findByEntity(entityId);
-        const hasActiveOrUnclaimed = currentInvocations.some((inv) => inv.completedAt === null && inv.failedAt === null && inv.id !== activeInvocation.id);
-        if (!hasActiveOrUnclaimed) {
-            // Re-fetch the entity to check if processSignal partially advanced state
-            // to a terminal state before throwing. If so, do not create a replacement —
-            // the entity is done and no further invocations should be created.
-            const currentEntity = await deps.entities.get(entityId);
-            const flow = currentEntity ? await deps.flows.get(currentEntity.flowId) : null;
-            const entityIsTerminal = currentEntity && flow ? isTerminal(flow, currentEntity.state) : false;
-            if (!entityIsTerminal) {
-                const replacement = await deps.invocations.create(entityId, activeInvocation.stage, activeInvocation.prompt, activeInvocation.mode, undefined, activeInvocation.context ?? undefined);
-                // Claim the replacement for the same worker so it can retry immediately.
-                if (worker_id && replacement) {
-                    try {
-                        await deps.invocations.claim(replacement.id, worker_id);
-                    }
-                    catch (claimErr) {
-                        log.error(`Failed to claim replacement invocation ${replacement.id} for worker ${worker_id}:`, claimErr);
-                    }
-                }
-            }
-        }
-        return errorResult(message);
-    }
-    // Set affinity on completion for passive-mode invocations, after processSignal succeeds
-    if (worker_id && activeInvocation.mode === "passive") {
-        try {
-            const entity = await deps.entities.get(entityId);
-            if (entity) {
-                const flow = await deps.flows.get(entity.flowId);
-                const windowMs = flow?.affinityWindowMs ?? 300000;
-                const affinityRole = flow?.discipline;
-                if (affinityRole) {
-                    await deps.entities.setAffinity(entityId, worker_id, affinityRole, new Date(Date.now() + windowMs));
-                }
-            }
-        }
-        catch (err) {
-            log.error(`Failed to set affinity for entity ${entityId} worker ${worker_id}:`, err);
-        }
-    }
-    // Gate blocked — create a replacement unclaimed invocation so the entity
-    // can be reclaimed; without it the entity would be permanently orphaned.
-    if (result.gated) {
-        await deps.invocations.create(entityId, activeInvocation.stage, activeInvocation.prompt, activeInvocation.mode, undefined, activeInvocation.context ?? undefined);
-        if (result.gateTimedOut) {
-            const renderedPrompt = result.timeoutPrompt ?? DEFAULT_TIMEOUT_PROMPT;
-            return jsonResult({
-                next_action: "check_back",
-                message: renderedPrompt,
-                retry_after_ms: 30000,
-                timeout_prompt: renderedPrompt,
-            });
-        }
-        return jsonResult({
-            new_state: null,
-            gated: true,
-            gate_output: result.gateOutput,
-            gateName: result.gateName,
-            next_action: "waiting",
-            failure_prompt: result.failurePrompt ?? null,
-        });
-    }
-    // If the engine created a next invocation, fetch its prompt
-    let nextPrompt = null;
-    let nextContext = null;
-    if (result.invocationId) {
-        const nextInvocation = await deps.invocations.get(result.invocationId);
-        if (nextInvocation) {
-            nextPrompt = nextInvocation.prompt;
-            nextContext = nextInvocation.context;
-        }
-    }
-    const nextAction = result.terminal ? "completed" : result.invocationId ? "continue" : "waiting";
-    return jsonResult({
-        new_state: result.newState,
-        gates_passed: result.gatesPassed,
-        next_action: nextAction,
-        prompt: nextPrompt,
-        context: nextContext,
-    });
-}
-async function handleFlowFail(deps, args) {
-    const v = validateInput(FlowFailSchema, args);
-    if (!v.ok)
-        return v.result;
-    const { entity_id: entityId, error } = v.data;
-    const invocationList = await deps.invocations.findByEntity(entityId);
-    const activeInvocation = invocationList.find((inv) => inv.claimedAt !== null && inv.completedAt === null && inv.failedAt === null);
-    if (!activeInvocation) {
-        return errorResult(`No active invocation found for entity: ${entityId}`);
-    }
-    await deps.invocations.fail(activeInvocation.id, error);
-    return jsonResult({ acknowledged: true });
-}
-async function handleQueryEntity(deps, args) {
-    const v = validateInput(QueryEntitySchema, args);
-    if (!v.ok)
-        return v.result;
-    const { id } = v.data;
-    const entity = await deps.entities.get(id);
-    if (!entity)
-        return errorResult(`Entity not found: ${id}`);
-    const history = await deps.transitions.historyFor(id);
-    return jsonResult({ ...entity, history });
-}
-async function handleQueryEntities(deps, args) {
-    const v = validateInput(QueryEntitiesSchema, args);
-    if (!v.ok)
-        return v.result;
-    const { flow: flowName, state, limit } = v.data;
-    const effectiveLimit = limit ?? 50;
-    const flow = await deps.flows.getByName(flowName);
-    if (!flow)
-        return errorResult(`Flow not found: ${flowName}`);
-    const results = await deps.entities.findByFlowAndState(flow.id, state);
-    return jsonResult(results.slice(0, effectiveLimit));
-}
-async function handleQueryInvocations(deps, args) {
-    const v = validateInput(QueryInvocationsSchema, args);
-    if (!v.ok)
-        return v.result;
-    const { entity_id: entityId } = v.data;
-    const results = await deps.invocations.findByEntity(entityId);
-    return jsonResult(results);
-}
-async function handleQueryFlow(deps, args) {
-    const v = validateInput(QueryFlowSchema, args);
-    if (!v.ok)
-        return v.result;
-    const { name } = v.data;
-    const flow = await deps.flows.getByName(name);
-    if (!flow)
-        return errorResult(`Flow not found: ${name}`);
-    return jsonResult(flow);
-}
-async function handleQueryFlows(deps) {
-    const flows = await deps.flows.list();
-    return jsonResult(flows.map((f) => ({
-        id: f.id,
-        name: f.name,
-        description: f.description,
-        initialState: f.initialState,
-        discipline: f.discipline,
-        version: f.version,
-        states: f.states.map(({ id, flowId, name, modelTier, mode, constraints, onEnter }) => ({
-            id,
-            flowId,
-            name,
-            modelTier,
-            mode,
-            constraints,
-            onEnter,
-        })),
-        transitions: f.transitions,
-    })));
-}
-async function handleAdminEntityCreate(deps, args) {
-    const v = validateInput(FlowSeedSchema, args);
-    if (!v.ok)
-        return v.result;
-    const { flow: flowName, refs } = v.data;
-    if (!deps.engine) {
-        return errorResult("Engine not available — MCP server started without engine dependency");
-    }
-    const entity = await deps.engine.createEntity(flowName, refs);
-    const invocations = await deps.invocations.findByEntity(entity.id);
-    const activeInvocation = invocations.find((inv) => !inv.completedAt && !inv.failedAt);
-    const result = { ...entity };
-    if (activeInvocation) {
-        result.invocation_id = activeInvocation.id;
-    }
-    return jsonResult(result);
-}
-/** Start the MCP server on stdio transport. */
-export async function startStdioServer(deps, opts) {
-    const server = createMcpServer(deps, opts);
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-}
-// ─── Admin Helpers ───
-function validateInput(schema, args) {
-    const parsed = schema.safeParse(args);
-    if (!parsed.success) {
-        return { ok: false, result: errorResult(`Validation error: ${JSON.stringify(parsed.error?.issues)}`) };
-    }
-    return { ok: true, data: parsed.data };
-}
-function emitDefinitionChanged(eventRepo, flowId, tool, payload) {
-    void eventRepo.emitDefinitionChanged(flowId, tool, payload);
-}
-// ─── Admin Tool Handlers ───
-async function handleAdminFlowCreate(deps, args) {
-    const v = validateInput(AdminFlowCreateSchema, args);
-    if (!v.ok)
-        return v.result;
-    const { states, ...flowInput } = v.data;
-    if (states !== undefined) {
-        const stateNames = states.map((s) => s.name);
-        if (!stateNames.includes(flowInput.initialState)) {
-            return errorResult(`initialState '${flowInput.initialState}' must be included in the states array`);
-        }
-    }
-    const flow = await deps.flows.create(flowInput);
-    for (const stateDef of states ?? []) {
-        await deps.flows.addState(flow.id, stateDef);
-    }
-    const fullFlow = await deps.flows.get(flow.id);
-    emitDefinitionChanged(deps.eventRepo, flow.id, "admin.flow.create", { name: flow.name });
-    return jsonResult(fullFlow);
-}
-async function handleAdminFlowUpdate(deps, args) {
-    const v = validateInput(AdminFlowUpdateSchema, args);
-    if (!v.ok)
-        return v.result;
-    const { flow_name, ...changes } = v.data;
-    const flow = await deps.flows.getByName(flow_name);
-    if (!flow)
-        return errorResult(`Flow not found: ${flow_name}`);
-    await deps.flows.snapshot(flow.id);
-    const updated = await deps.flows.update(flow.id, changes);
-    emitDefinitionChanged(deps.eventRepo, flow.id, "admin.flow.update", { name: flow_name, changes });
-    return jsonResult(updated);
-}
-async function handleAdminStateCreate(deps, args) {
-    const v = validateInput(AdminStateCreateSchema, args);
-    if (!v.ok)
-        return v.result;
-    const { flow_name, ...stateInput } = v.data;
-    const flow = await deps.flows.getByName(flow_name);
-    if (!flow)
-        return errorResult(`Flow not found: ${flow_name}`);
-    await deps.flows.snapshot(flow.id);
-    const state = await deps.flows.addState(flow.id, stateInput);
-    emitDefinitionChanged(deps.eventRepo, flow.id, "admin.state.create", { name: state.name });
-    return jsonResult(state);
-}
-async function handleAdminStateUpdate(deps, args) {
-    const v = validateInput(AdminStateUpdateSchema, args);
-    if (!v.ok)
-        return v.result;
-    const { flow_name, state_name, ...changes } = v.data;
-    const flow = await deps.flows.getByName(flow_name);
-    if (!flow)
-        return errorResult(`Flow not found: ${flow_name}`);
-    const stateDef = flow.states.find((s) => s.name === state_name);
-    if (!stateDef)
-        return errorResult(`State not found: ${state_name} in flow ${flow_name}`);
-    await deps.flows.snapshot(flow.id);
-    const updated = await deps.flows.updateState(stateDef.id, changes);
-    emitDefinitionChanged(deps.eventRepo, flow.id, "admin.state.update", { name: state_name, changes });
-    return jsonResult(updated);
-}
-async function handleAdminTransitionCreate(deps, args) {
-    const v = validateInput(AdminTransitionCreateSchema, args);
-    if (!v.ok)
-        return v.result;
-    const { flow_name, gateName, ...transitionInput } = v.data;
-    const flow = await deps.flows.getByName(flow_name);
-    if (!flow)
-        return errorResult(`Flow not found: ${flow_name}`);
-    const stateNames = flow.states.map((s) => s.name);
-    if (!stateNames.includes(transitionInput.fromState)) {
-        return errorResult(`State not found: '${transitionInput.fromState}' in flow '${flow_name}'`);
-    }
-    if (!stateNames.includes(transitionInput.toState)) {
-        return errorResult(`State not found: '${transitionInput.toState}' in flow '${flow_name}'`);
-    }
-    await deps.flows.snapshot(flow.id);
-    let gateId;
-    if (gateName) {
-        const gate = await deps.gates.getByName(gateName);
-        if (!gate)
-            return errorResult(`Gate not found: ${gateName}`);
-        gateId = gate.id;
-    }
-    const transition = await deps.flows.addTransition(flow.id, { ...transitionInput, gateId });
-    emitDefinitionChanged(deps.eventRepo, flow.id, "admin.transition.create", {
-        fromState: transitionInput.fromState,
-        toState: transitionInput.toState,
-        trigger: transitionInput.trigger,
-    });
-    return jsonResult(transition);
-}
-async function handleAdminTransitionUpdate(deps, args) {
-    const v = validateInput(AdminTransitionUpdateSchema, args);
-    if (!v.ok)
-        return v.result;
-    const { flow_name, transition_id, gateName, ...changes } = v.data;
-    const flow = await deps.flows.getByName(flow_name);
-    if (!flow)
-        return errorResult(`Flow not found: ${flow_name}`);
-    const existing = flow.transitions.find((t) => t.id === transition_id);
-    if (!existing)
-        return errorResult(`Transition not found: ${transition_id} in flow ${flow_name}`);
-    const stateNames = flow.states.map((s) => s.name);
-    if (changes.fromState !== undefined && !stateNames.includes(changes.fromState)) {
-        return errorResult(`State not found: '${changes.fromState}' in flow '${flow_name}'`);
-    }
-    if (changes.toState !== undefined && !stateNames.includes(changes.toState)) {
-        return errorResult(`State not found: '${changes.toState}' in flow '${flow_name}'`);
-    }
-    await deps.flows.snapshot(flow.id);
-    const updateChanges = { ...changes };
-    if (gateName !== undefined) {
-        if (gateName) {
-            const gate = await deps.gates.getByName(gateName);
-            if (!gate)
-                return errorResult(`Gate not found: ${gateName}`);
-            updateChanges.gateId = gate.id;
-        }
-        else {
-            updateChanges.gateId = null;
-        }
-    }
-    const updated = await deps.flows.updateTransition(transition_id, updateChanges);
-    emitDefinitionChanged(deps.eventRepo, flow.id, "admin.transition.update", { transition_id });
-    return jsonResult(updated);
-}
-async function handleAdminGateCreate(deps, args) {
-    const v = validateInput(AdminGateCreateSchema, args);
-    if (!v.ok)
-        return v.result;
-    const gate = await deps.gates.create(v.data);
-    emitDefinitionChanged(deps.eventRepo, null, "admin.gate.create", { name: gate.name });
-    return jsonResult(gate);
-}
-async function handleAdminGateAttach(deps, args) {
-    const v = validateInput(AdminGateAttachSchema, args);
-    if (!v.ok)
-        return v.result;
-    const { flow_name, transition_id, gate_name } = v.data;
-    const flow = await deps.flows.getByName(flow_name);
-    if (!flow)
-        return errorResult(`Flow not found: ${flow_name}`);
-    const existing = flow.transitions.find((t) => t.id === transition_id);
-    if (!existing)
-        return errorResult(`Transition not found: ${transition_id} in flow ${flow_name}`);
-    const gate = await deps.gates.getByName(gate_name);
-    if (!gate)
-        return errorResult(`Gate not found: ${gate_name}`);
-    await deps.flows.snapshot(flow.id);
-    const updated = await deps.flows.updateTransition(transition_id, { gateId: gate.id });
-    emitDefinitionChanged(deps.eventRepo, flow.id, "admin.gate.attach", { transition_id, gate_name });
-    return jsonResult(updated);
-}
-async function handleAdminFlowSnapshot(deps, args) {
-    const v = validateInput(AdminFlowSnapshotSchema, args);
-    if (!v.ok)
-        return v.result;
-    const flow = await deps.flows.getByName(v.data.flow_name);
-    if (!flow)
-        return errorResult(`Flow not found: ${v.data.flow_name}`);
-    const version = await deps.flows.snapshot(flow.id);
-    return jsonResult(version);
-}
-async function handleAdminFlowRestore(deps, args) {
-    const v = validateInput(AdminFlowRestoreSchema, args);
-    if (!v.ok)
-        return v.result;
-    const flow = await deps.flows.getByName(v.data.flow_name);
-    if (!flow)
-        return errorResult(`Flow not found: ${v.data.flow_name}`);
-    // Refuse to restore over a live flow — active invocations mean entities are
-    // currently being processed and restoring the definition would corrupt them.
-    const activeCount = await deps.invocations.countActiveByFlow(flow.id);
-    if (activeCount > 0) {
-        return errorResult(`Cannot restore flow "${v.data.flow_name}": ${activeCount} active invocation(s) in progress. Wait for them to complete before restoring.`);
-    }
-    await deps.flows.snapshot(flow.id);
-    await deps.flows.restore(flow.id, v.data.version);
-    emitDefinitionChanged(deps.eventRepo, flow.id, "admin.flow.restore", { version: v.data.version });
-    return jsonResult({ restored: true, version: v.data.version });
-}