@wopr-network/defcon 1.6.1 → 1.7.0

package/dist/src/engine/engine.d.ts

@@ -28,6 +28,7 @@ export interface EngineStatus {
     flows: Record<string, Record<string, number>>;
     activeInvocations: number;
     pendingClaims: number;
+    versionDistribution: Record<string, Record<string, number>>;
 }
 export interface EngineDeps {
     entityRepo: IEntityRepository;

package/dist/src/engine/engine.js

@@ -72,10 +72,10 @@ export class Engine {
         const entity = await this.entityRepo.get(entityId);
         if (!entity)
             throw new NotFoundError(`Entity "${entityId}" not found`);
-        // 2. Load flow
-        const flow = await this.flowRepo.get(entity.flowId);
+        // 2. Load flow at entity's pinned version
+        const flow = await this.flowRepo.getAtVersion(entity.flowId, entity.flowVersion);
         if (!flow)
-            throw new NotFoundError(`Flow "${entity.flowId}" not found`);
+            throw new NotFoundError(`Flow "${entity.flowId}" version ${entity.flowVersion} not found`);
         // 3. Find transition
         const transition = findTransition(flow, entity.state, signal, { entity }, true, this.logger);
         if (!transition)
@@ -325,7 +325,7 @@ export class Engine {
         const flow = await this.flowRepo.getByName(flowName);
         if (!flow)
             throw new NotFoundError(`Flow "${flowName}" not found`);
-        let entity = await this.entityRepo.create(flow.id, flow.initialState, refs);
+        let entity = await this.entityRepo.create(flow.id, flow.initialState, refs, flow.version);
         // Store any caller-supplied payload as initial artifacts so prompt templates
         // can access refs like {{entity.artifacts.refs.linear.id}}.
         if (payload && Object.keys(payload).length > 0) {
@@ -516,9 +516,11 @@ export class Engine {
                     this.logger.warn(`[engine] setAffinity failed for entity ${claimed.id} worker ${worker_id} — continuing:`, err);
                 }
             }
-            const state = flow.states.find((s) => s.name === pending.stage);
+            const versionedFlow = await this.flowRepo.getAtVersion(claimed.flowId, claimed.flowVersion);
+            const effectiveFlow = versionedFlow ?? flow;
+            const state = effectiveFlow.states.find((s) => s.name === pending.stage);
             const build = state
-                ? await this.buildPromptForEntity(state, claimed, flow)
+                ? await this.buildPromptForEntity(state, claimed, effectiveFlow)
                 : { prompt: pending.prompt, context: null };
             await this.eventEmitter.emit({
                 type: "entity.claimed",
@@ -543,12 +545,14 @@ export class Engine {
                 const claimed = await this.entityRepo.claim(flow.id, state.name, worker_id ?? `agent:${role}`);
                 if (!claimed)
                     continue;
-                const canCreate = await this.checkConcurrency(flow, claimed);
+                const claimedVersionedFlow = await this.flowRepo.getAtVersion(claimed.flowId, claimed.flowVersion);
+                const claimedEffectiveFlow = claimedVersionedFlow ?? flow;
+                const canCreate = await this.checkConcurrency(claimedEffectiveFlow, claimed);
                 if (!canCreate) {
                     await this.entityRepo.release(claimed.id, worker_id ?? `agent:${role}`);
                     continue;
                 }
-                const build = await this.buildPromptForEntity(state, claimed, flow);
+                const build = await this.buildPromptForEntity(state, claimed, claimedEffectiveFlow);
                 const invocation = await this.invocationRepo.create(claimed.id, state.name, build.prompt, build.mode, undefined, build.systemPrompt || build.userContent
                     ? { systemPrompt: build.systemPrompt, userContent: build.userContent }
                     : undefined, state.agentRole ?? null);
@@ -647,7 +651,21 @@ export class Engine {
             activeInvocations += active;
             pendingClaims += pending;
         }
-        return { flows: statusData, activeInvocations, pendingClaims };
+        const versionDistribution = {};
+        for (const flow of allFlows) {
+            const versionCounts = {};
+            for (const state of flow.states) {
+                const stateEntities = await this.entityRepo.findByFlowAndState(flow.id, state.name);
+                for (const e of stateEntities) {
+                    const vKey = String(e.flowVersion);
+                    versionCounts[vKey] = (versionCounts[vKey] ?? 0) + 1;
+                }
+            }
+            if (Object.keys(versionCounts).length > 0) {
+                versionDistribution[flow.id] = versionCounts;
+            }
+        }
+        return { flows: statusData, activeInvocations, pendingClaims, versionDistribution };
     }
     startReaper(intervalMs, entityTtlMs = 60_000) {
         let tickInFlight = false;

package/dist/src/execution/admin-schemas.d.ts

@@ -124,6 +124,9 @@ export declare const AdminEntityResetSchema: z.ZodObject<{
     entity_id: z.ZodString;
     target_state: z.ZodString;
 }, z.core.$strip>;
+export declare const AdminEntityMigrateSchema: z.ZodObject<{
+    entity_id: z.ZodString;
+}, z.core.$strip>;
 export declare const AdminWorkerDrainSchema: z.ZodObject<{
     worker_id: z.ZodString;
 }, z.core.$strip>;

package/dist/src/execution/admin-schemas.js

@@ -133,6 +133,9 @@ export const AdminEntityResetSchema = z.object({
     entity_id: z.string().min(1),
     target_state: z.string().min(1),
 });
+export const AdminEntityMigrateSchema = z.object({
+    entity_id: z.string().min(1),
+});
 export const AdminWorkerDrainSchema = z.object({
     worker_id: z.string().min(1),
 });

package/dist/src/execution/mcp-server.js

@@ -6,7 +6,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import { DEFAULT_TIMEOUT_PROMPT } from "../engine/constants.js";
 import { isTerminal } from "../engine/state-machine.js";
 import { consoleLogger } from "../logger.js";
-import { AdminEntityCancelSchema, AdminEntityResetSchema, AdminFlowCreateSchema, AdminFlowPauseSchema, AdminFlowRestoreSchema, AdminFlowSnapshotSchema, AdminFlowUpdateSchema, AdminGateAttachSchema, AdminGateCreateSchema, AdminGateRerunSchema, AdminStateCreateSchema, AdminStateUpdateSchema, AdminTransitionCreateSchema, AdminTransitionUpdateSchema, AdminWorkerDrainSchema, } from "./admin-schemas.js";
+import { AdminEntityCancelSchema, AdminEntityMigrateSchema, AdminEntityResetSchema, AdminFlowCreateSchema, AdminFlowPauseSchema, AdminFlowRestoreSchema, AdminFlowSnapshotSchema, AdminFlowUpdateSchema, AdminGateAttachSchema, AdminGateCreateSchema, AdminGateRerunSchema, AdminStateCreateSchema, AdminStateUpdateSchema, AdminTransitionCreateSchema, AdminTransitionUpdateSchema, AdminWorkerDrainSchema, } from "./admin-schemas.js";
 import { handleFlowClaim } from "./handlers/flow.js";
 import { FlowFailSchema, FlowGetPromptSchema, FlowReportSchema, FlowSeedSchema, QueryEntitiesSchema, QueryEntitySchema, QueryFlowSchema, QueryInvocationsSchema, } from "./tool-schemas.js";
 function getSystemDefaultGateTimeoutMs() {
@@ -362,6 +362,11 @@ const TOOL_DEFINITIONS = [
             required: ["entity_id", "target_state"],
         },
     },
+    {
+        name: "admin.entity.migrate",
+        description: "Migrate an entity to the latest flow version. Validates that the entity's current state exists in the new version.",
+        inputSchema: { type: "object", properties: { entity_id: { type: "string" } }, required: ["entity_id"] },
+    },
     {
         name: "admin.worker.drain",
         description: "Mark a worker as draining — claimWork() will skip it.",
@@ -465,6 +470,8 @@ export async function callToolHandler(deps, name, safeArgs, opts) {
                 return await handleAdminEntityCancel(deps, safeArgs);
             case "admin.entity.reset":
                 return await handleAdminEntityReset(deps, safeArgs);
+            case "admin.entity.migrate":
+                return await handleAdminEntityMigrate(deps, safeArgs);
             case "admin.worker.drain":
                 return await handleAdminWorkerDrain(deps, safeArgs);
             case "admin.worker.undrain":
@@ -804,6 +811,32 @@ async function handleAdminEntityReset(deps, args) {
     });
     return jsonResult({ reset: true, entity_id: v.data.entity_id, state: updated.state });
 }
+async function handleAdminEntityMigrate(deps, args) {
+    const v = validateInput(AdminEntityMigrateSchema, 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 flow = await deps.flows.get(entity.flowId);
+    if (!flow)
+        return errorResult(`Flow not found: ${entity.flowId}`);
+    if (entity.flowVersion === flow.version) {
+        return jsonResult({
+            migrated: false,
+            message: "Entity is already on the latest version",
+            flowVersion: flow.version,
+        });
+    }
+    const stateExists = flow.states.some((s) => s.name === entity.state);
+    if (!stateExists) {
+        return errorResult(`Cannot migrate entity ${entityId}: current state '${entity.state}' does not exist in flow '${flow.name}' version ${flow.version}`);
+    }
+    await deps.entities.updateFlowVersion(entityId, flow.version);
+    const updated = await deps.entities.get(entityId);
+    return jsonResult(updated);
+}
 async function handleAdminWorkerDrain(deps, args) {
     const v = validateInput(AdminWorkerDrainSchema, args);
     if (!v.ok)

package/dist/src/repositories/drizzle/entity.repo.d.ts

@@ -6,7 +6,7 @@ export declare class DrizzleEntityRepository implements IEntityRepository {
     private db;
     constructor(db: Db);
     private toEntity;
-    create(flowId: string, initialState: string, refs?: Refs): Promise<Entity>;
+    create(flowId: string, initialState: string, refs?: Refs, flowVersion?: number): Promise<Entity>;
     get(id: string): Promise<Entity | null>;
     findByFlowAndState(flowId: string, state: string, limit?: number): Promise<Entity[]>;
     hasAnyInFlowAndState(flowId: string, stateNames: string[]): Promise<boolean>;
@@ -25,5 +25,6 @@ export declare class DrizzleEntityRepository implements IEntityRepository {
     clearExpiredAffinity(): Promise<string[]>;
     cancelEntity(entityId: string): Promise<void>;
     resetEntity(entityId: string, targetState: string): Promise<Entity>;
+    updateFlowVersion(entityId: string, version: number): Promise<void>;
 }
 export {};

package/dist/src/repositories/drizzle/entity.repo.js

@@ -24,7 +24,7 @@ export class DrizzleEntityRepository {
             affinityExpiresAt: row.affinityExpiresAt ? new Date(row.affinityExpiresAt) : null,
         };
     }
-    async create(flowId, initialState, refs) {
+    async create(flowId, initialState, refs, flowVersion) {
         const now = Date.now();
         const id = crypto.randomUUID();
         const row = {
@@ -35,7 +35,7 @@ export class DrizzleEntityRepository {
             artifacts: null,
             claimedBy: null,
             claimedAt: null,
-            flowVersion: 1,
+            flowVersion: flowVersion ?? 1,
             createdAt: now,
             updatedAt: now,
             affinityWorkerId: null,
@@ -205,4 +205,10 @@ export class DrizzleEntityRepository {
             throw new NotFoundError(`Entity not found: ${entityId}`);
         return this.toEntity(rows[0]);
     }
+    async updateFlowVersion(entityId, version) {
+        await this.db
+            .update(entities)
+            .set({ flowVersion: version, updatedAt: Date.now() })
+            .where(eq(entities.id, entityId));
+    }
 }

package/dist/src/repositories/drizzle/flow.repo.d.ts

@@ -9,6 +9,7 @@ export declare class DrizzleFlowRepository implements IFlowRepository {
     create(input: CreateFlowInput): Promise<Flow>;
     get(id: string): Promise<Flow | null>;
     getByName(name: string): Promise<Flow | null>;
+    getAtVersion(flowId: string, version: number): Promise<Flow | null>;
     list(): Promise<Flow[]>;
     listAll(): Promise<Flow[]>;
     update(id: string, changes: UpdateFlowInput): Promise<Flow>;

package/dist/src/repositories/drizzle/flow.repo.js

@@ -116,6 +116,67 @@ export class DrizzleFlowRepository {
             return null;
         return this.hydrateFlow(rows[0]);
     }
+    async getAtVersion(flowId, version) {
+        const current = await this.get(flowId);
+        if (!current)
+            return null;
+        if (current.version === version)
+            return current;
+        const rows = this.db
+            .select()
+            .from(flowVersions)
+            .where(and(eq(flowVersions.flowId, flowId), eq(flowVersions.version, version)))
+            .all();
+        if (rows.length === 0)
+            return null;
+        const snap = rows[0].snapshot;
+        return {
+            id: flowId,
+            name: snap.name ?? current.name,
+            description: snap.description ?? null,
+            entitySchema: snap.entitySchema ?? null,
+            initialState: snap.initialState ?? current.initialState,
+            maxConcurrent: snap.maxConcurrent ?? 0,
+            maxConcurrentPerRepo: snap.maxConcurrentPerRepo ?? 0,
+            affinityWindowMs: snap.affinityWindowMs ?? 300000,
+            claimRetryAfterMs: snap.claimRetryAfterMs ?? null,
+            gateTimeoutMs: snap.gateTimeoutMs ?? null,
+            version,
+            createdBy: snap.createdBy ?? null,
+            discipline: snap.discipline ?? null,
+            defaultModelTier: snap.defaultModelTier ?? null,
+            timeoutPrompt: snap.timeoutPrompt ?? null,
+            paused: current.paused,
+            createdAt: snap.createdAt ? new Date(snap.createdAt) : null,
+            updatedAt: snap.updatedAt ? new Date(snap.updatedAt) : null,
+            states: (snap.states ?? []).map((s) => ({
+                id: s.id,
+                flowId,
+                name: s.name,
+                agentRole: s.agentRole ?? null,
+                modelTier: s.modelTier ?? null,
+                mode: s.mode ?? "passive",
+                promptTemplate: s.promptTemplate ?? null,
+                constraints: s.constraints ?? null,
+                onEnter: s.onEnter ?? null,
+                onExit: s.onExit ?? null,
+                retryAfterMs: s.retryAfterMs ?? null,
+            })),
+            transitions: (snap.transitions ?? []).map((t) => ({
+                id: t.id,
+                flowId,
+                fromState: t.fromState,
+                toState: t.toState,
+                trigger: t.trigger,
+                gateId: t.gateId ?? null,
+                condition: t.condition ?? null,
+                priority: t.priority ?? 0,
+                spawnFlow: t.spawnFlow ?? null,
+                spawnTemplate: t.spawnTemplate ?? null,
+                createdAt: t.createdAt ? new Date(t.createdAt) : null,
+            })),
+        };
+    }
     async list() {
         const rows = this.db.select().from(flowDefinitions).all();
         return rows.map((row) => this.hydrateFlow(row));
@@ -306,6 +367,10 @@ export class DrizzleFlowRepository {
                 createdAt: now,
             })
                 .run();
+            tx.update(flowDefinitions)
+                .set({ version: version + 1, updatedAt: now })
+                .where(eq(flowDefinitions.id, flowId))
+                .run();
             return version;
         });
         return {

package/dist/src/repositories/interfaces.d.ts

@@ -224,7 +224,7 @@ export interface CreateGateInput {
 /** Data-access contract for entity lifecycle operations. */
 export interface IEntityRepository {
     /** Create a new entity in the given flow's initial state. */
-    create(flowId: string, initialState: string, refs?: Refs): Promise<Entity>;
+    create(flowId: string, initialState: string, refs?: Refs, flowVersion?: number): Promise<Entity>;
     /** Get an entity by ID, or null if not found. */
     get(id: string): Promise<Entity | null>;
     /** Find entities in a given flow and state, up to an optional limit. */
@@ -259,6 +259,8 @@ export interface IEntityRepository {
     cancelEntity(entityId: string): Promise<void>;
     /** Move entity to targetState and clear claimedBy/claimedAt. Returns the updated entity. */
     resetEntity(entityId: string, targetState: string): Promise<Entity>;
+    /** Update an entity's pinned flow version. */
+    updateFlowVersion(entityId: string, version: number): Promise<void>;
 }
 /** Fields that can be updated on a flow's top-level definition */
 export type UpdateFlowInput = Partial<Omit<Flow, "id" | "states" | "transitions" | "createdAt" | "updatedAt">>;
@@ -276,6 +278,8 @@ export interface IFlowRepository {
     get(id: string): Promise<Flow | null>;
     /** Get a flow by unique name. Returns null if not found. */
     getByName(name: string): Promise<Flow | null>;
+    /** Load a flow definition at a specific version. Returns the snapshot if version < current, or live flow if version === current. */
+    getAtVersion(flowId: string, version: number): Promise<Flow | null>;
     /** Update a flow's top-level fields. */
     update(id: string, changes: UpdateFlowInput): Promise<Flow>;
     /** Add a state definition to a flow. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/defcon",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "type": "module",
   "packageManager": "pnpm@9.15.4",
   "engines": {