@wopr-network/defcon 1.7.0 → 1.8.0

package/dist/src/engine/engine.js

@@ -72,6 +72,9 @@ export class Engine {
         const entity = await this.entityRepo.get(entityId);
         if (!entity)
             throw new NotFoundError(`Entity "${entityId}" not found`);
+        if (entity.state === "cancelled") {
+            throw new ValidationError(`Entity "${entityId}" is cancelled and cannot be transitioned`);
+        }
         // 2. Load flow at entity's pinned version
         const flow = await this.flowRepo.getAtVersion(entity.flowId, entity.flowVersion);
         if (!flow)
@@ -466,6 +469,8 @@ export class Engine {
             const entity = entityMap.get(pending.entityId);
             if (!entity)
                 continue;
+            if (entity.state === "cancelled")
+                continue;
             // Guard: entity state must still match the invocation's stage — if another worker
             // transitioned the entity between candidate fetch and now, skip this candidate.
             if (entity.state !== pending.stage)
@@ -545,6 +550,10 @@ export class Engine {
                 const claimed = await this.entityRepo.claim(flow.id, state.name, worker_id ?? `agent:${role}`);
                 if (!claimed)
                     continue;
+                if (claimed.state === "cancelled") {
+                    await this.entityRepo.release(claimed.id, worker_id ?? `agent:${role}`);
+                    continue;
+                }
                 const claimedVersionedFlow = await this.flowRepo.getAtVersion(claimed.flowId, claimed.flowVersion);
                 const claimedEffectiveFlow = claimedVersionedFlow ?? flow;
                 const canCreate = await this.checkConcurrency(claimedEffectiveFlow, claimed);

package/dist/src/engine/event-types.d.ts

@@ -24,6 +24,14 @@ export type EngineEvent = {
     entityId: string;
     flowId: string;
     emittedAt: Date;
+} | {
+    type: "entity.cancelled";
+    entityId: string;
+    flowId: string;
+    cancelledBy: string;
+    reason: string | null;
+    cascade: boolean;
+    emittedAt: Date;
 } | {
     type: "invocation.created";
     entityId: string;

package/dist/src/engine/flow-spawner.js

@@ -11,7 +11,7 @@ export async function executeSpawn(transition, parentEntity, flowRepo, entityRep
     const flow = await flowRepo.getByName(transition.spawnFlow);
     if (!flow)
         throw new NotFoundError(`Spawn flow "${transition.spawnFlow}" not found`);
-    const childEntity = await entityRepo.create(flow.id, flow.initialState, parentEntity.refs ?? undefined);
+    const childEntity = await entityRepo.create(flow.id, flow.initialState, parentEntity.refs ?? undefined, undefined, parentEntity.id);
     try {
         await entityRepo.appendSpawnedChild(parentEntity.id, {
             childId: childEntity.id,

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

@@ -119,6 +119,8 @@ export declare const AdminFlowPauseSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const AdminEntityCancelSchema: z.ZodObject<{
     entity_id: z.ZodString;
+    cascade: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const AdminEntityResetSchema: z.ZodObject<{
     entity_id: z.ZodString;

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

@@ -128,6 +128,8 @@ export const AdminFlowPauseSchema = z.object({
 });
 export const AdminEntityCancelSchema = z.object({
     entity_id: z.string().min(1),
+    cascade: z.boolean().optional().default(false),
+    reason: z.string().optional(),
 });
 export const AdminEntityResetSchema = z.object({
     entity_id: z.string().min(1),

package/dist/src/execution/cli.js

@@ -184,6 +184,7 @@ program
         transitions: transitionLogRepo,
         eventRepo: new DrizzleEventRepository(db),
         engine,
+        withTransaction: (fn) => withTransaction(sqlite, fn),
     };
     const reaperInterval = parseInt(opts.reaperInterval, 10);
     if (Number.isNaN(reaperInterval) || reaperInterval < 1000) {

package/dist/src/execution/mcp-server.d.ts

@@ -11,6 +11,7 @@ export interface McpServerDeps {
     eventRepo: IEventRepository;
     engine?: Engine;
     logger?: Logger;
+    withTransaction?: <T>(fn: () => T | Promise<T>) => Promise<T>;
 }
 export interface McpServerOpts {
     /** DEFCON_ADMIN_TOKEN — if set, admin.* tools require this token */

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

@@ -350,8 +350,16 @@ const TOOL_DEFINITIONS = [
     },
     {
         name: "admin.entity.cancel",
-        description: "Cancel an entity — fails active invocation, moves to 'cancelled' terminal state.",
-        inputSchema: { type: "object", properties: { entity_id: { type: "string" } }, required: ["entity_id"] },
+        description: "Cancel an entity — fails active invocation, moves to 'cancelled' terminal state. Use cascade to cancel all descendant entities.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                entity_id: { type: "string" },
+                cascade: { type: "boolean", description: "Recursively cancel all child entities" },
+                reason: { type: "string", description: "Cancellation reason" },
+            },
+            required: ["entity_id"],
+        },
     },
     {
         name: "admin.entity.reset",
@@ -755,31 +763,67 @@ async function handleAdminEntityCancel(deps, args) {
     const v = validateInput(AdminEntityCancelSchema, args);
     if (!v.ok)
         return v.result;
-    const entity = await deps.entities.get(v.data.entity_id);
+    const { entity_id, cascade, reason } = v.data;
+    const entity = await deps.entities.get(entity_id);
     if (!entity)
-        return errorResult(`Entity not found: ${v.data.entity_id}`);
-    const flow = await deps.flows.get(entity.flowId);
-    if (!flow)
-        return errorResult(`Flow not found for entity: ${v.data.entity_id}`);
-    const cancelledState = flow.states.find((s) => s.name === "cancelled");
-    if (!cancelledState)
-        return errorResult(`State 'cancelled' not found in flow '${flow.name}'`);
-    const invocations = await deps.invocations.findByEntity(v.data.entity_id);
-    for (const inv of invocations) {
-        if (inv.completedAt === null && inv.failedAt === null) {
-            await deps.invocations.fail(inv.id, "Cancelled by admin");
+        return errorResult(`Entity not found: ${entity_id}`);
+    if (entity.state === "cancelled" && !cascade)
+        return errorResult(`Entity ${entity_id} is already cancelled`);
+    const cancelled = [];
+    const MAX_CANCEL_DEPTH = 100;
+    async function cancelOne(eid, depth, visited) {
+        if (visited.has(eid))
+            return;
+        visited.add(eid);
+        if (depth > MAX_CANCEL_DEPTH) {
+            throw new Error(`cancelOne exceeded maximum recursion depth of ${MAX_CANCEL_DEPTH} — possible cycle or pathologically deep entity tree`);
+        }
+        const e = await deps.entities.get(eid);
+        const alreadyCancelled = !e || e.state === "cancelled";
+        if (!alreadyCancelled) {
+            const invocations = await deps.invocations.findByEntity(eid);
+            for (const inv of invocations) {
+                if (inv.completedAt === null && inv.failedAt === null) {
+                    await deps.invocations.fail(inv.id, reason ?? "Cancelled by admin");
+                }
+            }
+            await deps.entities.cancelEntity(eid);
+            await deps.transitions.record({
+                entityId: eid,
+                fromState: e.state,
+                toState: "cancelled",
+                trigger: "admin.cancel",
+                invocationId: null,
+                timestamp: new Date(),
+            });
+            if (deps.engine) {
+                await deps.engine.emit({
+                    type: "entity.cancelled",
+                    entityId: eid,
+                    flowId: e.flowId,
+                    cancelledBy: "admin",
+                    reason: reason ?? null,
+                    cascade: cascade ?? false,
+                    emittedAt: new Date(),
+                });
+            }
+            cancelled.push(eid);
+        }
+        if (cascade) {
+            const children = await deps.entities.findByParentId(eid);
+            for (const child of children) {
+                await cancelOne(child.id, depth + 1, visited);
+            }
         }
     }
-    await deps.entities.cancelEntity(v.data.entity_id);
-    await deps.transitions.record({
-        entityId: v.data.entity_id,
-        fromState: entity.state,
-        toState: "cancelled",
-        trigger: "admin.cancel",
-        invocationId: null,
-        timestamp: new Date(),
-    });
-    return jsonResult({ cancelled: true, entity_id: v.data.entity_id });
+    const run = () => cancelOne(entity_id, 0, new Set());
+    if (deps.withTransaction) {
+        await deps.withTransaction(run);
+    }
+    else {
+        await run();
+    }
+    return jsonResult({ cancelled: true, entity_id, cancelled_count: cancelled.length, cancelled_ids: cancelled });
 }
 async function handleAdminEntityReset(deps, args) {
     const v = validateInput(AdminEntityResetSchema, args);

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, flowVersion?: number): Promise<Entity>;
+    create(flowId: string, initialState: string, refs?: Refs, flowVersion?: number, parentEntityId?: string): Promise<Entity>;
     get(id: string): Promise<Entity | null>;
     findByFlowAndState(flowId: string, state: string, limit?: number): Promise<Entity[]>;
     hasAnyInFlowAndState(flowId: string, stateNames: string[]): Promise<boolean>;
@@ -23,6 +23,7 @@ export declare class DrizzleEntityRepository implements IEntityRepository {
     reapExpired(ttlMs: number): Promise<string[]>;
     setAffinity(entityId: string, workerId: string, role: string, expiresAt: Date): Promise<void>;
     clearExpiredAffinity(): Promise<string[]>;
+    findByParentId(parentEntityId: string): Promise<Entity[]>;
     cancelEntity(entityId: string): Promise<void>;
     resetEntity(entityId: string, targetState: string): Promise<Entity>;
     updateFlowVersion(entityId: string, version: number): Promise<void>;

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

@@ -22,9 +22,10 @@ export class DrizzleEntityRepository {
             affinityWorkerId: row.affinityWorkerId ?? null,
             affinityRole: row.affinityRole ?? null,
             affinityExpiresAt: row.affinityExpiresAt ? new Date(row.affinityExpiresAt) : null,
+            parentEntityId: row.parentEntityId ?? null,
         };
     }
-    async create(flowId, initialState, refs, flowVersion) {
+    async create(flowId, initialState, refs, flowVersion, parentEntityId) {
         const now = Date.now();
         const id = crypto.randomUUID();
         const row = {
@@ -41,6 +42,7 @@ export class DrizzleEntityRepository {
             affinityWorkerId: null,
             affinityRole: null,
             affinityExpiresAt: null,
+            parentEntityId: parentEntityId ?? null,
         };
         await this.db.insert(entities).values(row);
         return this.toEntity(row);
@@ -188,6 +190,10 @@ export class DrizzleEntityRepository {
             .all();
         return rows.map((r) => r.id);
     }
+    async findByParentId(parentEntityId) {
+        const rows = await this.db.select().from(entities).where(eq(entities.parentEntityId, parentEntityId));
+        return rows.map((r) => this.toEntity(r));
+    }
     async cancelEntity(entityId) {
         await this.db
             .update(entities)

package/dist/src/repositories/drizzle/schema.d.ts

@@ -1326,6 +1326,25 @@ export declare const entities: import("drizzle-orm/sqlite-core").SQLiteTableWith
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        parentEntityId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "parent_entity_id";
+            tableName: "entities";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
     };
     dialect: "sqlite";
 }>;

package/dist/src/repositories/drizzle/schema.js

@@ -95,10 +95,12 @@ export const entities = sqliteTable("entities", {
     affinityWorkerId: text("affinity_worker_id"),
     affinityRole: text("affinity_role"),
     affinityExpiresAt: integer("affinity_expires_at"),
+    parentEntityId: text("parent_entity_id"),
 }, (table) => ({
     flowStateIdx: index("entities_flow_state_idx").on(table.flowId, table.state),
     claimIdx: index("entities_claim_idx").on(table.flowId, table.state, table.claimedBy),
     affinityIdx: index("entities_affinity_idx").on(table.affinityWorkerId, table.affinityRole, table.affinityExpiresAt),
+    parentIdx: index("entities_parent_idx").on(table.parentEntityId),
 }));
 export const invocations = sqliteTable("invocations", {
     id: text("id").primaryKey(),

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

@@ -35,6 +35,7 @@ export interface Entity {
     affinityWorkerId: string | null;
     affinityRole: string | null;
     affinityExpiresAt: Date | null;
+    parentEntityId: string | null;
 }
 /** A single agent invocation tied to an entity */
 export interface Invocation {
@@ -224,7 +225,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, flowVersion?: number): Promise<Entity>;
+    create(flowId: string, initialState: string, refs?: Refs, flowVersion?: number, parentEntityId?: string): 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. */
@@ -255,6 +256,8 @@ export interface IEntityRepository {
         childFlow: string;
         spawnedAt: string;
     }): Promise<void>;
+    /** Find all direct children of a parent entity. */
+    findByParentId(parentEntityId: string): Promise<Entity[]>;
     /** Move entity to 'cancelled' terminal state and clear claimedBy/claimedAt. */
     cancelEntity(entityId: string): Promise<void>;
     /** Move entity to targetState and clear claimedBy/claimedAt. Returns the updated entity. */

package/drizzle/0015_add_parent_entity_id.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `entities` ADD `parent_entity_id` text;--> statement-breakpoint
+CREATE INDEX `entities_parent_idx` ON `entities` (`parent_entity_id`);

package/drizzle/meta/_journal.json

@@ -106,6 +106,13 @@
       "when": 1773031139526,
       "tag": "0014_smiling_crusher_hogan",
       "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "6",
+      "when": 1773200000001,
+      "tag": "0015_add_parent_entity_id",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

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