@wopr-network/defcon 1.5.0 → 1.6.1

package/dist/src/config/seed-loader.js

@@ -93,6 +93,7 @@ async function parseSeedAndLoad(json, flowRepo, gateRepo, db) {
                     promptTemplate: s.promptTemplate,
                     constraints: s.constraints,
                     onEnter: s.onEnter,
+                    onExit: s.onExit,
                     retryAfterMs: s.retryAfterMs,
                 });
             }

package/dist/src/config/zod-schemas.d.ts

@@ -20,6 +20,10 @@ export declare const OnEnterSchema: z.ZodObject<{
     artifacts: z.ZodArray<z.ZodString>;
     timeout_ms: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
 }, z.core.$strip>;
+export declare const OnExitSchema: z.ZodObject<{
+    command: z.ZodString;
+    timeout_ms: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
 export declare const StateDefinitionSchema: z.ZodObject<{
     name: z.ZodString;
     flowName: z.ZodString;
@@ -36,6 +40,10 @@ export declare const StateDefinitionSchema: z.ZodObject<{
         artifacts: z.ZodArray<z.ZodString>;
         timeout_ms: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     }, z.core.$strip>>;
+    onExit: z.ZodOptional<z.ZodObject<{
+        command: z.ZodString;
+        timeout_ms: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, z.core.$strip>>;
     retryAfterMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export declare const CommandGateSchema: z.ZodObject<{
@@ -152,6 +160,10 @@ export declare const SeedFileSchema: z.ZodObject<{
             artifacts: z.ZodArray<z.ZodString>;
             timeout_ms: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
         }, z.core.$strip>>;
+        onExit: z.ZodOptional<z.ZodObject<{
+            command: z.ZodString;
+            timeout_ms: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        }, z.core.$strip>>;
         retryAfterMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     gates: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{

package/dist/src/config/zod-schemas.js

@@ -34,6 +34,15 @@ export const OnEnterSchema = z.object({
     artifacts: z.array(z.string().min(1)).min(1),
     timeout_ms: z.number().int().min(0).optional().default(30000),
 });
+export const OnExitSchema = z.object({
+    command: z
+        .string()
+        .min(1)
+        .refine((val) => validateTemplate(val), {
+        message: "onExit command contains disallowed Handlebars expressions",
+    }),
+    timeout_ms: z.number().int().min(1).optional().default(30000),
+});
 export const StateDefinitionSchema = z.object({
     name: z.string().min(1),
     flowName: z.string().min(1),
@@ -49,6 +58,7 @@ export const StateDefinitionSchema = z.object({
         .optional(),
     constraints: z.record(z.string(), z.unknown()).optional(),
     onEnter: OnEnterSchema.optional(),
+    onExit: OnExitSchema.optional(),
     retryAfterMs: z.number().int().min(0).optional(),
 });
 // Gate: discriminated union on `type`

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

@@ -38,6 +38,8 @@ export interface EngineDeps {
     adapters: Map<string, unknown>;
     eventEmitter: IEventBusAdapter;
     logger?: Logger;
+    /** Optional transaction wrapper from the database layer. When provided, processSignal runs inside a single transaction and events are flushed only after successful commit. */
+    withTransaction?: <T>(fn: () => T | Promise<T>) => Promise<T>;
 }
 export declare class Engine {
     private entityRepo;
@@ -48,6 +50,7 @@ export declare class Engine {
     readonly adapters: Map<string, unknown>;
     private eventEmitter;
     private readonly logger;
+    private readonly withTransactionFn;
     private drainingWorkers;
     constructor(deps: EngineDeps);
     drainWorker(workerId: string): void;
@@ -56,6 +59,7 @@ export declare class Engine {
     listDrainingWorkers(): string[];
     emit(event: import("./event-types.js").EngineEvent): Promise<void>;
     processSignal(entityId: string, signal: string, artifacts?: Artifacts, triggeringInvocationId?: string): Promise<ProcessSignalResult>;
+    private _processSignalInner;
     /**
      * Evaluate a gate and return a routing decision:
      * - `proceed`  — gate passed, continue to transition.toState

package/dist/src/engine/engine.js

@@ -6,6 +6,7 @@ import { evaluateGate } from "./gate-evaluator.js";
 import { getHandlebars } from "./handlebars.js";
 import { buildInvocation } from "./invocation-builder.js";
 import { executeOnEnter } from "./on-enter.js";
+import { executeOnExit } from "./on-exit.js";
 import { findTransition, isTerminal } from "./state-machine.js";
 export class Engine {
     entityRepo;
@@ -16,6 +17,7 @@ export class Engine {
     adapters;
     eventEmitter;
     logger;
+    withTransactionFn;
     drainingWorkers = new Set();
     constructor(deps) {
         this.entityRepo = deps.entityRepo;
@@ -26,6 +28,7 @@ export class Engine {
         this.adapters = deps.adapters;
         this.eventEmitter = deps.eventEmitter;
         this.logger = deps.logger ?? consoleLogger;
+        this.withTransactionFn = deps.withTransaction ?? null;
     }
     drainWorker(workerId) {
         this.drainingWorkers.add(workerId);
@@ -43,6 +46,28 @@ export class Engine {
         await this.eventEmitter.emit(event);
     }
     async processSignal(entityId, signal, artifacts, triggeringInvocationId) {
+        const pendingEvents = [];
+        const bufferingEmitter = {
+            emit: async (event) => {
+                pendingEvents.push(event);
+            },
+        };
+        if (this.withTransactionFn) {
+            // Run DB writes inside a transaction; events are buffered and only
+            // flushed to real subscribers after successful COMMIT.
+            const result = await this.withTransactionFn(() => this._processSignalInner(entityId, signal, artifacts, triggeringInvocationId, bufferingEmitter));
+            for (const event of pendingEvents) {
+                await this.eventEmitter.emit(event);
+            }
+            return result;
+        }
+        const result = await this._processSignalInner(entityId, signal, artifacts, triggeringInvocationId, bufferingEmitter);
+        for (const event of pendingEvents) {
+            await this.eventEmitter.emit(event);
+        }
+        return result;
+    }
+    async _processSignalInner(entityId, signal, artifacts, triggeringInvocationId, emitter = this.eventEmitter) {
         // 1. Load entity
         const entity = await this.entityRepo.get(entityId);
         if (!entity)
@@ -67,6 +92,29 @@ export class Engine {
         const trigger = routing.kind === "redirect" ? routing.trigger : signal;
         const spawnFlow = routing.kind === "redirect" ? null : transition.spawnFlow;
         const { gatesPassed } = routing;
+        // 4b. Execute onExit hook on the DEPARTING state (before transition)
+        const departingStateDef = flow.states.find((s) => s.name === entity.state);
+        if (departingStateDef?.onExit) {
+            const onExitResult = await executeOnExit(departingStateDef.onExit, entity);
+            if (onExitResult.error) {
+                this.logger.warn(`[engine] onExit failed for entity ${entityId} state ${entity.state}: ${onExitResult.error}`);
+                await this.eventEmitter.emit({
+                    type: "onExit.failed",
+                    entityId,
+                    state: entity.state,
+                    error: onExitResult.error,
+                    emittedAt: new Date(),
+                });
+            }
+            else {
+                await this.eventEmitter.emit({
+                    type: "onExit.completed",
+                    entityId,
+                    state: entity.state,
+                    emittedAt: new Date(),
+                });
+            }
+        }
         // 5. Transition entity
         let updated = await this.entityRepo.transition(entityId, toState, trigger, artifacts);
         // Clear gate_failures on successful transition so stale failures don't bleed into future agent prompts
@@ -74,7 +122,7 @@ export class Engine {
         // Keep the in-memory entity in sync so buildInvocation sees the cleared failures
         updated = { ...updated, artifacts: { ...updated.artifacts, gate_failures: [] } };
         // 6. Emit transition event
-        await this.eventEmitter.emit({
+        await emitter.emit({
             type: "entity.transitioned",
             entityId,
             flowId: flow.id,
@@ -94,7 +142,7 @@ export class Engine {
         if (newStateDef?.onEnter) {
             const onEnterResult = await executeOnEnter(newStateDef.onEnter, updated, this.entityRepo);
             if (onEnterResult.skipped) {
-                await this.eventEmitter.emit({
+                await emitter.emit({
                     type: "onEnter.skipped",
                     entityId,
                     state: toState,
@@ -102,7 +150,7 @@ export class Engine {
                 });
             }
             else if (onEnterResult.error) {
-                await this.eventEmitter.emit({
+                await emitter.emit({
                     type: "onEnter.failed",
                     entityId,
                     state: toState,
@@ -127,7 +175,7 @@ export class Engine {
                 };
             }
             else {
-                await this.eventEmitter.emit({
+                await emitter.emit({
                     type: "onEnter.completed",
                     entityId,
                     state: toState,
@@ -155,7 +203,7 @@ export class Engine {
                     ? { systemPrompt: build.systemPrompt, userContent: build.userContent }
                     : undefined, newStateDef.agentRole ?? null);
                 result.invocationId = invocation.id;
-                await this.eventEmitter.emit({
+                await emitter.emit({
                     type: "invocation.created",
                     entityId,
                     invocationId: invocation.id,
@@ -178,7 +226,7 @@ export class Engine {
         const spawned = await executeSpawn({ spawnFlow }, updated, this.flowRepo, this.entityRepo, this.logger);
         if (spawned) {
             result.spawned = [spawned.id];
-            await this.eventEmitter.emit({
+            await emitter.emit({
                 type: "flow.spawned",
                 entityId,
                 flowId: flow.id,

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

@@ -104,6 +104,17 @@ export type EngineEvent = {
     entityId: string;
     state: string;
     emittedAt: Date;
+} | {
+    type: "onExit.completed";
+    entityId: string;
+    state: string;
+    emittedAt: Date;
+} | {
+    type: "onExit.failed";
+    entityId: string;
+    state: string;
+    error: string;
+    emittedAt: Date;
 };
 /** Adapter for broadcasting engine events to external systems. */
 export interface IEventBusAdapter {

package/dist/src/engine/on-exit.d.ts

@@ -0,0 +1,6 @@
+import type { Entity, OnExitConfig } from "../repositories/interfaces.js";
+export interface OnExitResult {
+    error: string | null;
+    timedOut: boolean;
+}
+export declare function executeOnExit(onExit: OnExitConfig, entity: Entity): Promise<OnExitResult>;

package/dist/src/engine/on-exit.js

@@ -0,0 +1,45 @@
+import { execFile } from "node:child_process";
+import { getHandlebars } from "./handlebars.js";
+export async function executeOnExit(onExit, entity) {
+    const hbs = getHandlebars();
+    let renderedCommand;
+    // Merge artifact refs into entity.refs (same pattern as on-enter.ts)
+    const artifactRefs = entity.artifacts !== null &&
+        typeof entity.artifacts === "object" &&
+        "refs" in entity.artifacts &&
+        entity.artifacts.refs !== null &&
+        typeof entity.artifacts.refs === "object"
+        ? entity.artifacts.refs
+        : {};
+    const entityForContext = { ...entity, refs: { ...artifactRefs, ...(entity.refs ?? {}) } };
+    try {
+        renderedCommand = hbs.compile(onExit.command)({ entity: entityForContext });
+    }
+    catch (err) {
+        const error = `onExit template error: ${err instanceof Error ? err.message : String(err)}`;
+        return { error, timedOut: false };
+    }
+    const timeoutMs = onExit.timeout_ms ?? 30000;
+    const { exitCode, stdout, stderr, timedOut } = await runCommand(renderedCommand, timeoutMs);
+    if (timedOut) {
+        return { error: `onExit command timed out after ${timeoutMs}ms`, timedOut: true };
+    }
+    if (exitCode !== 0) {
+        return { error: `onExit command exited with code ${exitCode}: ${stderr || stdout}`, timedOut: false };
+    }
+    return { error: null, timedOut: false };
+}
+function runCommand(command, timeoutMs) {
+    return new Promise((resolve) => {
+        execFile("/bin/sh", ["-c", command], { timeout: timeoutMs }, (error, stdout, stderr) => {
+            const execErr = error;
+            const timedOut = execErr !== null && execErr.killed === true;
+            resolve({
+                exitCode: execErr ? (typeof execErr.code === "number" ? execErr.code : 1) : 0,
+                stdout: stdout.trim(),
+                stderr: stderr.trim(),
+                timedOut,
+            });
+        });
+    });
+}

package/dist/src/execution/cli.js

@@ -14,6 +14,7 @@ import { loadSeed } from "../config/seed-loader.js";
 import { resolveCorsOrigin } from "../cors.js";
 import { Engine } from "../engine/engine.js";
 import { EventEmitter } from "../engine/event-emitter.js";
+import { withTransaction } from "../main.js";
 import { DrizzleEntityRepository } from "../repositories/drizzle/entity.repo.js";
 import { DrizzleEventRepository } from "../repositories/drizzle/event.repo.js";
 import { DrizzleFlowRepository } from "../repositories/drizzle/flow.repo.js";
@@ -173,6 +174,7 @@ program
         transitionLogRepo,
         adapters: new Map(),
         eventEmitter,
+        withTransaction: (fn) => withTransaction(sqlite, fn),
     });
     const deps = {
         entities: entityRepo,

package/dist/src/main.d.ts

@@ -5,6 +5,12 @@ export declare function createDatabase(dbPath?: string): {
     db: ReturnType<typeof drizzle<typeof schema>>;
     sqlite: Database.Database;
 };
+/**
+ * Wraps `fn` in a BEGIN/COMMIT/ROLLBACK transaction on `sqlite`.
+ * If already inside a transaction, runs `fn` directly (allows nested calls).
+ * Supports both synchronous and Promise-returning `fn`.
+ */
+export declare function withTransaction<T>(sqlite: Database.Database, fn: () => T | Promise<T>): Promise<T>;
 export declare function runMigrations(db: ReturnType<typeof drizzle>, migrationsFolder?: string): void;
 export declare function bootstrap(dbPath?: string): {
     db: ReturnType<typeof drizzle>;

package/dist/src/main.js

@@ -10,6 +10,26 @@ export function createDatabase(dbPath = DB_PATH) {
     const db = drizzle(sqlite, { schema });
     return { db, sqlite };
 }
+/**
+ * Wraps `fn` in a BEGIN/COMMIT/ROLLBACK transaction on `sqlite`.
+ * If already inside a transaction, runs `fn` directly (allows nested calls).
+ * Supports both synchronous and Promise-returning `fn`.
+ */
+export async function withTransaction(sqlite, fn) {
+    if (sqlite.inTransaction) {
+        return fn();
+    }
+    sqlite.exec("BEGIN");
+    try {
+        const result = await fn();
+        sqlite.exec("COMMIT");
+        return result;
+    }
+    catch (err) {
+        sqlite.exec("ROLLBACK");
+        throw err;
+    }
+}
 export function runMigrations(db, migrationsFolder = "./drizzle") {
     migrate(db, { migrationsFolder });
 }

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

@@ -15,6 +15,7 @@ function rowToState(r) {
         promptTemplate: r.promptTemplate ?? null,
         constraints: r.constraints,
         onEnter: r.onEnter ?? null,
+        onExit: r.onExit ?? null,
         retryAfterMs: r.retryAfterMs ?? null,
     };
 }
@@ -174,6 +175,7 @@ export class DrizzleFlowRepository {
             promptTemplate: state.promptTemplate ?? null,
             constraints: (state.constraints ?? null),
             onEnter: (state.onEnter ?? null),
+            onExit: (state.onExit ?? null),
             retryAfterMs: state.retryAfterMs ?? null,
         };
         this.db.transaction((tx) => {
@@ -201,6 +203,8 @@ export class DrizzleFlowRepository {
             updateValues.constraints = changes.constraints;
         if (changes.onEnter !== undefined)
             updateValues.onEnter = changes.onEnter;
+        if (changes.onExit !== undefined)
+            updateValues.onExit = changes.onExit;
         if (changes.retryAfterMs !== undefined)
             updateValues.retryAfterMs = changes.retryAfterMs;
         if (Object.keys(updateValues).length > 0) {
@@ -338,6 +342,7 @@ export class DrizzleFlowRepository {
                     promptTemplate: s.promptTemplate,
                     constraints: s.constraints,
                     onEnter: (s.onEnter ?? null),
+                    onExit: (s.onExit ?? null),
                     retryAfterMs: s.retryAfterMs ?? null,
                 })
                     .run();

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

@@ -498,6 +498,23 @@ export declare const stateDefinitions: import("drizzle-orm/sqlite-core").SQLiteT
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        onExit: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "on_exit";
+            tableName: "state_definitions";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: unknown;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         retryAfterMs: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "retry_after_ms";
             tableName: "state_definitions";

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

@@ -32,6 +32,7 @@ export const stateDefinitions = sqliteTable("state_definitions", {
     promptTemplate: text("prompt_template"),
     constraints: text("constraints", { mode: "json" }),
     onEnter: text("on_enter", { mode: "json" }),
+    onExit: text("on_exit", { mode: "json" }),
     retryAfterMs: integer("retry_after_ms"),
 }, (table) => ({
     flowNameUnique: uniqueIndex("state_definitions_flow_name_unique").on(table.flowId, table.name),

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

@@ -12,6 +12,11 @@ export interface OnEnterConfig {
     artifacts: string[];
     timeout_ms?: number;
 }
+/** Configuration for running a cleanup command when an entity exits a state */
+export interface OnExitConfig {
+    command: string;
+    timeout_ms?: number;
+}
 /** Invocation execution mode */
 export type Mode = "active" | "passive";
 /** Runtime entity tracked through a flow */
@@ -90,6 +95,7 @@ export interface State {
     promptTemplate: string | null;
     constraints: Record<string, unknown> | null;
     onEnter: OnEnterConfig | null;
+    onExit: OnExitConfig | null;
     /** Override check_back delay for workers claiming this state. Falls back to Flow.claimRetryAfterMs. */
     retryAfterMs: number | null;
 }
@@ -186,6 +192,7 @@ export interface CreateStateInput {
     promptTemplate?: string;
     constraints?: Record<string, unknown>;
     onEnter?: OnEnterConfig;
+    onExit?: OnExitConfig;
     retryAfterMs?: number;
 }
 /** Input for adding a transition rule */

package/drizzle/0014_smiling_crusher_hogan.sql

@@ -0,0 +1 @@
+ALTER TABLE `state_definitions` ADD `on_exit` text;