@wopr-network/defcon 0.2.0

package/dist/src/execution/handlers/admin.d.ts

@@ -0,0 +1,67 @@
+import type { McpServerDeps } from "../mcp-helpers.js";
+export declare function handleAdminEntityCreate(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleAdminFlowCreate(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleAdminFlowUpdate(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleAdminStateCreate(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleAdminStateUpdate(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleAdminTransitionCreate(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleAdminTransitionUpdate(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleAdminGateCreate(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleAdminGateAttach(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleAdminFlowSnapshot(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleAdminFlowRestore(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/src/execution/handlers/admin.js

@@ -0,0 +1,200 @@
+import { isTerminal } from "../../engine/state-machine.js";
+import { AdminFlowCreateSchema, AdminFlowRestoreSchema, AdminFlowSnapshotSchema, AdminFlowUpdateSchema, AdminGateAttachSchema, AdminGateCreateSchema, AdminStateCreateSchema, AdminStateUpdateSchema, AdminTransitionCreateSchema, AdminTransitionUpdateSchema, } from "../admin-schemas.js";
+import { emitDefinitionChanged, errorResult, jsonResult, validateInput } from "../mcp-helpers.js";
+import { FlowSeedSchema } from "../tool-schemas.js";
+export 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);
+}
+export 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);
+}
+export 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);
+}
+export 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);
+}
+export 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);
+}
+export 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);
+}
+export 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 === null) {
+        updateChanges.gateId = null;
+    }
+    else if (gateName !== undefined) {
+        const gate = await deps.gates.getByName(gateName);
+        if (!gate)
+            return errorResult(`Gate not found: ${gateName}`);
+        updateChanges.gateId = gate.id;
+    }
+    const updated = await deps.flows.updateTransition(transition_id, updateChanges);
+    emitDefinitionChanged(deps.eventRepo, flow.id, "admin.transition.update", { transition_id });
+    return jsonResult(updated);
+}
+export 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);
+}
+export 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);
+}
+export 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);
+}
+export 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}`);
+    const nonTerminalStateNames = flow.states.map((s) => s.name).filter((name) => !isTerminal(flow, name));
+    const hasActive = await deps.entities.hasAnyInFlowAndState(flow.id, nonTerminalStateNames);
+    if (hasActive) {
+        return errorResult(`Cannot restore flow '${v.data.flow_name}': active entities exist. Complete or fail them first.`);
+    }
+    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 });
+}

package/dist/src/execution/handlers/flow.d.ts

@@ -0,0 +1,25 @@
+import type { McpServerDeps } from "../mcp-helpers.js";
+export declare function handleFlowClaim(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleFlowGetPrompt(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleFlowReport(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleFlowFail(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/src/execution/handlers/flow.js

@@ -0,0 +1,289 @@
+import { DEFAULT_TIMEOUT_PROMPT } from "../../engine/constants.js";
+import { errorResult, jsonResult, validateInput } from "../mcp-helpers.js";
+import { FlowClaimSchema, FlowFailSchema, FlowGetPromptSchema, FlowReportSchema } from "../tool-schemas.js";
+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.`,
+    });
+}
+export async function handleFlowClaim(deps, args) {
+    const v = validateInput(FlowClaimSchema, args);
+    if (!v.ok)
+        return v.result;
+    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. Build a flow lookup map (needed for affinity window below)
+    const flowById = new Map(candidateFlows.map((f) => [f.id, f]));
+    // 5. Check affinity for each entity using the flow's configured window
+    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 ? flowById.get(entity.flowId) : undefined;
+            const affinityWindowMs = flow?.affinityWindowMs ?? 300000;
+            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 < affinityWindowMs) {
+                    affinitySet.add(eid);
+                }
+            }
+        }));
+    }
+    // 6. 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;
+    });
+    // 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) {
+            console.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) {
+                    console.error(`Failed to claim entity ${entity.id}:`, err);
+                    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 (best-effort; failure must not block the claim)
+            if (worker_id && entity && flow) {
+                try {
+                    const windowMs = flow.affinityWindowMs ?? 300000;
+                    await deps.entities.setAffinity(claimed.entityId, worker_id, role, new Date(Date.now() + windowMs));
+                }
+                catch (err) {
+                    console.error(`Failed to set affinity for entity ${claimed.entityId}:`, 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);
+}
+export 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,
+    });
+}
+export async function handleFlowReport(deps, args) {
+    const v = validateInput(FlowReportSchema, args);
+    if (!v.ok)
+        return v.result;
+    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.
+        // Only recreate the replacement if the engine did NOT already advance the entity
+        // (i.e. the entity is still in the same state as when we started). If the engine
+        // mutated the entity mid-execution and then threw, recreating the old invocation
+        // would regress the entity back to a stale state.
+        const entityAfter = await deps.entities.get(entityId).catch(() => null);
+        if (!entityAfter || entityAfter.state === activeInvocation.stage) {
+            await deps.invocations.create(entityId, activeInvocation.stage, activeInvocation.prompt, activeInvocation.mode, undefined, activeInvocation.context ?? undefined);
+        }
+        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) {
+            console.error(`Failed to set affinity for entity ${entityId} worker ${worker_id}:`, err);
+        }
+    }
+    // Gate blocked — create a replacement invocation so the entity can be reclaimed.
+    // Claim it immediately for the same worker so that a retry flow.report call (for
+    // check_back) finds an active invocation without requiring a round-trip through
+    // flow.claim. Workers on the "waiting" path will re-claim via flow.claim as usual.
+    if (result.gated) {
+        const replacement = await deps.invocations.create(entityId, activeInvocation.stage, activeInvocation.prompt, activeInvocation.mode, undefined, activeInvocation.context ?? undefined);
+        const claimedBy = activeInvocation.claimedBy;
+        if (claimedBy) {
+            await deps.invocations.claim(replacement.id, claimedBy).catch(() => {
+                // Best-effort: if claim fails the invocation remains unclaimed and the worker
+                // can re-claim it via flow.claim on the next attempt.
+            });
+        }
+        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,
+    });
+}
+export 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 });
+}

package/dist/src/execution/handlers/query.d.ts

@@ -0,0 +1,31 @@
+import type { McpServerDeps } from "../mcp-helpers.js";
+export declare function handleQueryEntity(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleQueryEntities(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleQueryInvocations(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleQueryFlow(deps: McpServerDeps, args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleQueryFlows(deps: McpServerDeps): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/src/execution/handlers/query.js

@@ -0,0 +1,64 @@
+import { errorResult, jsonResult, validateInput } from "../mcp-helpers.js";
+import { QueryEntitiesSchema, QueryEntitySchema, QueryFlowSchema, QueryInvocationsSchema } from "../tool-schemas.js";
+export 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 });
+}
+export 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, effectiveLimit);
+    return jsonResult(results);
+}
+export 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);
+}
+export 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);
+}
+export 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,
+    })));
+}

package/dist/src/execution/index.d.ts

@@ -0,0 +1,4 @@
+export type { ActiveRunnerDeps, ActiveRunnerRunOptions, IAIProviderAdapter } from "./active-runner.js";
+export { ActiveRunner } from "./active-runner.js";
+export type { McpServerDeps, McpServerOpts } from "./mcp-server.js";
+export { createMcpServer, startStdioServer } from "./mcp-server.js";