@wopr-network/defcon 1.4.0 → 1.6.0

package/dist/src/api/wire-types.d.ts

@@ -12,6 +12,7 @@ export type ClaimResponse = {
     invocation_id: string;
     flow: string | null;
     stage: string;
+    agent_role: string | null;
     prompt: string;
     context: Record<string, unknown> | null;
     worker_notice?: string;

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

@@ -63,6 +63,7 @@ async function parseSeedAndLoad(json, flowRepo, gateRepo, db) {
                 timeoutMs: g.timeoutMs,
                 failurePrompt: g.failurePrompt,
                 timeoutPrompt: g.timeoutPrompt,
+                outcomes: g.outcomes,
             });
             gateNameToId.set(g.name, gate.id);
         }
@@ -86,11 +87,13 @@ async function parseSeedAndLoad(json, flowRepo, gateRepo, db) {
             for (const s of flowStates) {
                 await flowRepo.addState(flow.id, {
                     name: s.name,
+                    agentRole: s.agentRole,
                     modelTier: s.modelTier,
                     mode: s.mode,
                     promptTemplate: s.promptTemplate,
                     constraints: s.constraints,
                     onEnter: s.onEnter,
+                    onExit: s.onExit,
                     retryAfterMs: s.retryAfterMs,
                 });
             }

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

@@ -20,9 +20,14 @@ 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;
+    agentRole: z.ZodOptional<z.ZodString>;
     modelTier: z.ZodOptional<z.ZodString>;
     mode: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
         passive: "passive";
@@ -35,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<{
@@ -42,6 +51,10 @@ export declare const CommandGateSchema: z.ZodObject<{
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     failurePrompt: z.ZodOptional<z.ZodString>;
     timeoutPrompt: z.ZodOptional<z.ZodString>;
+    outcomes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        proceed: z.ZodOptional<z.ZodBoolean>;
+        toState: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     type: z.ZodLiteral<"command">;
     command: z.ZodString;
 }, z.core.$strip>;
@@ -50,6 +63,10 @@ export declare const FunctionGateSchema: z.ZodObject<{
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     failurePrompt: z.ZodOptional<z.ZodString>;
     timeoutPrompt: z.ZodOptional<z.ZodString>;
+    outcomes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        proceed: z.ZodOptional<z.ZodBoolean>;
+        toState: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     type: z.ZodLiteral<"function">;
     functionRef: z.ZodString;
 }, z.core.$strip>;
@@ -58,6 +75,10 @@ export declare const ApiGateSchema: z.ZodObject<{
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     failurePrompt: z.ZodOptional<z.ZodString>;
     timeoutPrompt: z.ZodOptional<z.ZodString>;
+    outcomes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        proceed: z.ZodOptional<z.ZodBoolean>;
+        toState: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     type: z.ZodLiteral<"api">;
     apiConfig: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strip>;
@@ -66,6 +87,10 @@ export declare const GateDefinitionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     failurePrompt: z.ZodOptional<z.ZodString>;
     timeoutPrompt: z.ZodOptional<z.ZodString>;
+    outcomes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        proceed: z.ZodOptional<z.ZodBoolean>;
+        toState: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     type: z.ZodLiteral<"command">;
     command: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
@@ -73,6 +98,10 @@ export declare const GateDefinitionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     failurePrompt: z.ZodOptional<z.ZodString>;
     timeoutPrompt: z.ZodOptional<z.ZodString>;
+    outcomes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        proceed: z.ZodOptional<z.ZodBoolean>;
+        toState: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     type: z.ZodLiteral<"function">;
     functionRef: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
@@ -80,6 +109,10 @@ export declare const GateDefinitionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     failurePrompt: z.ZodOptional<z.ZodString>;
     timeoutPrompt: z.ZodOptional<z.ZodString>;
+    outcomes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        proceed: z.ZodOptional<z.ZodBoolean>;
+        toState: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     type: z.ZodLiteral<"api">;
     apiConfig: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strip>], "type">;
@@ -114,6 +147,7 @@ export declare const SeedFileSchema: z.ZodObject<{
     states: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         flowName: z.ZodString;
+        agentRole: z.ZodOptional<z.ZodString>;
         modelTier: z.ZodOptional<z.ZodString>;
         mode: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
             passive: "passive";
@@ -126,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<{
@@ -133,6 +171,10 @@ export declare const SeedFileSchema: z.ZodObject<{
         timeoutMs: z.ZodOptional<z.ZodNumber>;
         failurePrompt: z.ZodOptional<z.ZodString>;
         timeoutPrompt: z.ZodOptional<z.ZodString>;
+        outcomes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            proceed: z.ZodOptional<z.ZodBoolean>;
+            toState: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
         type: z.ZodLiteral<"command">;
         command: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
@@ -140,6 +182,10 @@ export declare const SeedFileSchema: z.ZodObject<{
         timeoutMs: z.ZodOptional<z.ZodNumber>;
         failurePrompt: z.ZodOptional<z.ZodString>;
         timeoutPrompt: z.ZodOptional<z.ZodString>;
+        outcomes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            proceed: z.ZodOptional<z.ZodBoolean>;
+            toState: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
         type: z.ZodLiteral<"function">;
         functionRef: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
@@ -147,6 +193,10 @@ export declare const SeedFileSchema: z.ZodObject<{
         timeoutMs: z.ZodOptional<z.ZodNumber>;
         failurePrompt: z.ZodOptional<z.ZodString>;
         timeoutPrompt: z.ZodOptional<z.ZodString>;
+        outcomes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            proceed: z.ZodOptional<z.ZodBoolean>;
+            toState: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
         type: z.ZodLiteral<"api">;
         apiConfig: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, z.core.$strip>], "type">>>>;

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

@@ -34,9 +34,19 @@ 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),
+    agentRole: z.string().optional(),
     modelTier: z.string().optional(),
     mode: z.enum(["passive", "active"]).optional().default("passive"),
     promptTemplate: z
@@ -48,14 +58,20 @@ 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`
+const GateOutcomeSchema = z.object({
+    proceed: z.boolean().optional(),
+    toState: z.string().min(1).optional(),
+});
 const BaseGateSchema = z.object({
     name: z.string().min(1),
     timeoutMs: z.number().int().min(1).optional(),
     failurePrompt: z.string().optional(),
     timeoutPrompt: z.string().min(1).optional(),
+    outcomes: z.record(z.string(), GateOutcomeSchema).optional(),
 });
 export const CommandGateSchema = BaseGateSchema.extend({
     type: z.literal("command"),

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

@@ -56,6 +56,13 @@ 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>;
+    /**
+     * Evaluate a gate and return a routing decision:
+     * - `proceed`  — gate passed, continue to transition.toState
+     * - `redirect` — gate outcome maps to a different toState
+     * - `block`    — gate failed or timed out; caller should return this as the signal result
+     */
+    private resolveGate;
     createEntity(flowName: string, refs?: Record<string, {
         adapter: string;
         id: string;

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;
@@ -55,83 +56,43 @@ export class Engine {
         const transition = findTransition(flow, entity.state, signal, { entity }, true, this.logger);
         if (!transition)
             throw new ValidationError(`No transition from "${entity.state}" on signal "${signal}" in flow "${flow.name}"`);
-        // 4. Evaluate gate if present
-        const gatesPassed = [];
-        if (transition.gateId) {
-            const gate = await this.gateRepo.get(transition.gateId);
-            if (!gate)
-                throw new NotFoundError(`Gate "${transition.gateId}" not found`);
-            const gateResult = await evaluateGate(gate, entity, this.gateRepo, flow.gateTimeoutMs);
-            if (!gateResult.passed) {
-                // Persist gate failure into entity artifacts for retry context
-                const priorFailures = Array.isArray(entity.artifacts?.gate_failures)
-                    ? entity.artifacts.gate_failures
-                    : [];
-                await this.entityRepo.updateArtifacts(entityId, {
-                    gate_failures: [
-                        ...priorFailures,
-                        {
-                            gateId: gate.id,
-                            gateName: gate.name,
-                            output: gateResult.output,
-                            failedAt: new Date().toISOString(),
-                        },
-                    ],
+        // 4. Evaluate gate — returns a routing decision or a block result to return immediately.
+        const routing = transition.gateId
+            ? await this.resolveGate(transition.gateId, entity, flow)
+            : { kind: "proceed", gatesPassed: [] };
+        if (routing.kind === "block") {
+            return { gated: true, ...routing, terminal: false };
+        }
+        // Gate passed or redirected — determine the actual destination.
+        const toState = routing.kind === "redirect" ? routing.toState : transition.toState;
+        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(),
                 });
-                if (gateResult.timedOut) {
-                    await this.eventEmitter.emit({
-                        type: "gate.timedOut",
-                        entityId,
-                        gateId: gate.id,
-                        emittedAt: new Date(),
-                    });
-                }
-                else {
-                    await this.eventEmitter.emit({
-                        type: "gate.failed",
-                        entityId,
-                        gateId: gate.id,
-                        emittedAt: new Date(),
-                    });
-                }
-                let resolvedTimeoutPrompt;
-                if (gateResult.timedOut) {
-                    const rawTemplate = gate.timeoutPrompt ?? flow.timeoutPrompt ?? DEFAULT_TIMEOUT_PROMPT;
-                    try {
-                        const hbs = getHandlebars();
-                        const template = hbs.compile(rawTemplate);
-                        resolvedTimeoutPrompt = template({
-                            entity,
-                            flow,
-                            gate: { name: gate.name, output: gateResult.output },
-                        });
-                    }
-                    catch (err) {
-                        this.logger.error("[engine] Failed to render timeoutPrompt template:", err);
-                        resolvedTimeoutPrompt = DEFAULT_TIMEOUT_PROMPT;
-                    }
-                }
-                return {
-                    gated: true,
-                    gateTimedOut: gateResult.timedOut,
-                    gateOutput: gateResult.output,
-                    gateName: gate.name,
-                    failurePrompt: gate.failurePrompt ?? undefined,
-                    timeoutPrompt: resolvedTimeoutPrompt,
-                    gatesPassed,
-                    terminal: false,
-                };
             }
-            gatesPassed.push(gate.name);
-            await this.eventEmitter.emit({
-                type: "gate.passed",
-                entityId,
-                gateId: gate.id,
-                emittedAt: new Date(),
-            });
         }
         // 5. Transition entity
-        let updated = await this.entityRepo.transition(entityId, transition.toState, signal, artifacts);
+        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
         await this.entityRepo.updateArtifacts(entityId, { gate_failures: [] });
         // Keep the in-memory entity in sync so buildInvocation sees the cleared failures
@@ -142,25 +103,25 @@ export class Engine {
             entityId,
             flowId: flow.id,
             fromState: entity.state,
-            toState: transition.toState,
-            trigger: signal,
+            toState,
+            trigger,
             emittedAt: new Date(),
         });
         const result = {
-            newState: transition.toState,
+            newState: toState,
             gatesPassed,
             gated: false,
             terminal: false,
         };
         // 6b. Execute onEnter hook if defined on the new state
-        const newStateDef = flow.states.find((s) => s.name === transition.toState);
+        const newStateDef = flow.states.find((s) => s.name === toState);
         if (newStateDef?.onEnter) {
             const onEnterResult = await executeOnEnter(newStateDef.onEnter, updated, this.entityRepo);
             if (onEnterResult.skipped) {
                 await this.eventEmitter.emit({
                     type: "onEnter.skipped",
                     entityId,
-                    state: transition.toState,
+                    state: toState,
                     emittedAt: new Date(),
                 });
             }
@@ -168,20 +129,20 @@ export class Engine {
                 await this.eventEmitter.emit({
                     type: "onEnter.failed",
                     entityId,
-                    state: transition.toState,
+                    state: toState,
                     error: onEnterResult.error,
                     emittedAt: new Date(),
                 });
                 await this.transitionLogRepo.record({
                     entityId,
                     fromState: entity.state,
-                    toState: transition.toState,
-                    trigger: signal,
+                    toState,
+                    trigger,
                     invocationId: triggeringInvocationId ?? null,
                     timestamp: new Date(),
                 });
                 return {
-                    newState: transition.toState,
+                    newState: toState,
                     gatesPassed,
                     gated: false,
                     onEnterFailed: true,
@@ -193,7 +154,7 @@ export class Engine {
                 await this.eventEmitter.emit({
                     type: "onEnter.completed",
                     entityId,
-                    state: transition.toState,
+                    state: toState,
                     artifacts: onEnterResult.artifacts ?? {},
                     emittedAt: new Date(),
                 });
@@ -214,15 +175,15 @@ export class Engine {
                 ]);
                 const enriched = { ...updated, invocations, gateResults };
                 const build = await buildInvocation(newStateDef, enriched, this.adapters, flow, this.logger);
-                const invocation = await this.invocationRepo.create(entityId, transition.toState, build.prompt, build.mode, undefined, build.systemPrompt || build.userContent
+                const invocation = await this.invocationRepo.create(entityId, toState, build.prompt, build.mode, undefined, build.systemPrompt || build.userContent
                     ? { systemPrompt: build.systemPrompt, userContent: build.userContent }
-                    : undefined);
+                    : undefined, newStateDef.agentRole ?? null);
                 result.invocationId = invocation.id;
                 await this.eventEmitter.emit({
                     type: "invocation.created",
                     entityId,
                     invocationId: invocation.id,
-                    stage: transition.toState,
+                    stage: toState,
                     emittedAt: new Date(),
                 });
             }
@@ -232,13 +193,13 @@ export class Engine {
         await this.transitionLogRepo.record({
             entityId,
             fromState: entity.state,
-            toState: transition.toState,
-            trigger: signal,
+            toState,
+            trigger,
             invocationId: triggeringInvocationId ?? null,
             timestamp: new Date(),
         });
         // 9. Spawn child flows
-        const spawned = await executeSpawn(transition, updated, this.flowRepo, this.entityRepo, this.logger);
+        const spawned = await executeSpawn({ spawnFlow }, updated, this.flowRepo, this.entityRepo, this.logger);
         if (spawned) {
             result.spawned = [spawned.id];
             await this.eventEmitter.emit({
@@ -249,14 +210,93 @@ export class Engine {
                 emittedAt: new Date(),
             });
         }
-        // 10. Mark terminal — no invocation is created for terminal states (handled above),
-        //     but we surface terminality in the result for callers.
-        if (isTerminal(flow, transition.toState)) {
+        // 10. Mark terminal
+        if (isTerminal(flow, toState)) {
             result.terminal = true;
             result.spawned = result.spawned ?? [];
         }
         return result;
     }
+    /**
+     * Evaluate a gate and return a routing decision:
+     * - `proceed`  — gate passed, continue to transition.toState
+     * - `redirect` — gate outcome maps to a different toState
+     * - `block`    — gate failed or timed out; caller should return this as the signal result
+     */
+    async resolveGate(gateId, entity, flow) {
+        const gate = await this.gateRepo.get(gateId);
+        if (!gate)
+            throw new NotFoundError(`Gate "${gateId}" not found`);
+        const gateResult = await evaluateGate(gate, entity, this.gateRepo, flow.gateTimeoutMs);
+        const namedOutcome = gateResult.outcome && gate.outcomes ? gate.outcomes[gateResult.outcome] : undefined;
+        if (namedOutcome?.toState) {
+            const outcomeLabel = gateResult.outcome ?? gate.name;
+            await this.eventEmitter.emit({
+                type: "gate.redirected",
+                entityId: entity.id,
+                gateId: gate.id,
+                outcome: outcomeLabel,
+                toState: namedOutcome.toState,
+                emittedAt: new Date(),
+            });
+            return {
+                kind: "redirect",
+                toState: namedOutcome.toState,
+                trigger: `gate:${gate.name}:${outcomeLabel}`,
+                gatesPassed: [gate.name],
+            };
+        }
+        if (namedOutcome?.proceed || (!namedOutcome && gateResult.passed)) {
+            await this.eventEmitter.emit({
+                type: "gate.passed",
+                entityId: entity.id,
+                gateId: gate.id,
+                emittedAt: new Date(),
+            });
+            return { kind: "proceed", gatesPassed: [gate.name] };
+        }
+        // Gate failed — persist failure context and emit event
+        const priorFailures = Array.isArray(entity.artifacts?.gate_failures)
+            ? entity.artifacts.gate_failures
+            : [];
+        await this.entityRepo.updateArtifacts(entity.id, {
+            gate_failures: [
+                ...priorFailures,
+                { gateId: gate.id, gateName: gate.name, output: gateResult.output, failedAt: new Date().toISOString() },
+            ],
+        });
+        await this.eventEmitter.emit({
+            type: gateResult.timedOut ? "gate.timedOut" : "gate.failed",
+            entityId: entity.id,
+            gateId: gate.id,
+            emittedAt: new Date(),
+        });
+        let timeoutPrompt;
+        if (gateResult.timedOut) {
+            const rawTemplate = gate.timeoutPrompt ?? flow.timeoutPrompt ?? DEFAULT_TIMEOUT_PROMPT;
+            try {
+                const hbs = getHandlebars();
+                timeoutPrompt = hbs.compile(rawTemplate)({
+                    entity,
+                    flow,
+                    gate: { name: gate.name, output: gateResult.output },
+                });
+            }
+            catch (err) {
+                this.logger.error("[engine] Failed to render timeoutPrompt template:", err);
+                timeoutPrompt = DEFAULT_TIMEOUT_PROMPT;
+            }
+        }
+        return {
+            kind: "block",
+            gateTimedOut: gateResult.timedOut,
+            gateOutput: gateResult.output,
+            gateName: gate.name,
+            failurePrompt: gate.failurePrompt ?? undefined,
+            timeoutPrompt,
+            gatesPassed: [],
+        };
+    }
     async createEntity(flowName, refs, payload) {
         const flow = await this.flowRepo.getByName(flowName);
         if (!flow)
@@ -315,7 +355,7 @@ export class Engine {
             const build = await buildInvocation(initialState, enriched, this.adapters, flow, this.logger);
             await this.invocationRepo.create(entity.id, flow.initialState, build.prompt, build.mode, undefined, build.systemPrompt || build.userContent
                 ? { systemPrompt: build.systemPrompt, userContent: build.userContent }
-                : undefined);
+                : undefined, initialState.agentRole ?? null);
         }
         return entity;
     }
@@ -487,7 +527,7 @@ export class Engine {
                 const build = await this.buildPromptForEntity(state, claimed, flow);
                 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);
+                    : undefined, state.agentRole ?? null);
                 const entityClaimToken = worker_id ?? `agent:${role}`;
                 let claimedInvocation;
                 try {

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

@@ -68,6 +68,13 @@ export type EngineEvent = {
     entityId: string;
     gateId: string;
     emittedAt: Date;
+} | {
+    type: "gate.redirected";
+    entityId: string;
+    gateId: string;
+    outcome: string;
+    toState: string;
+    emittedAt: Date;
 } | {
     type: "flow.spawned";
     entityId: string;
@@ -97,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/flow-spawner.d.ts

@@ -1,8 +1,10 @@
 import type { Logger } from "../logger.js";
-import type { Entity, IEntityRepository, IFlowRepository, Transition } from "../repositories/interfaces.js";
+import type { Entity, IEntityRepository, IFlowRepository } from "../repositories/interfaces.js";
 /**
  * If the transition has a spawnFlow, look up that flow and create a new entity in it.
  * The spawned entity inherits the parent entity's refs.
  * Returns the spawned entity, or null if no spawn is configured.
  */
-export declare function executeSpawn(transition: Transition, parentEntity: Entity, flowRepo: IFlowRepository, entityRepo: IEntityRepository, logger?: Logger): Promise<Entity | null>;
+export declare function executeSpawn(transition: {
+    spawnFlow: string | null | undefined;
+}, parentEntity: Entity, flowRepo: IFlowRepository, entityRepo: IEntityRepository, logger?: Logger): Promise<Entity | null>;

package/dist/src/engine/gate-evaluator.d.ts

@@ -3,6 +3,10 @@ export interface GateEvalResult {
     passed: boolean;
     timedOut: boolean;
     output: string;
+    /** Named outcome from structured JSON output, if the gate emitted one. */
+    outcome?: string;
+    /** Human-readable message from structured JSON output. */
+    message?: string;
 }
 export declare function resolveGateTimeout(gateTimeoutMs: number | null | undefined, flowGateTimeoutMs: number | null | undefined): number;
 /**

package/dist/src/engine/gate-evaluator.js

@@ -59,6 +59,33 @@ export async function evaluateGate(gate, entity, gateRepo, flowGateTimeoutMs) {
         passed = result.exitCode === 0;
         output = result.output;
         timedOut = result.timedOut;
+        // Parse structured JSON outcome from the last non-empty output line.
+        // Gate scripts can emit { outcome: string, message?: string } as their final line
+        // to enable named outcome routing (e.g. "blocked" → toState: "fixing").
+        const lastLine = result.output
+            .split("\n")
+            .map((l) => l.trim())
+            .filter(Boolean)
+            .at(-1);
+        if (lastLine?.startsWith("{")) {
+            try {
+                const parsed = JSON.parse(lastLine);
+                if (typeof parsed.outcome === "string") {
+                    const outcomeResult = {
+                        passed,
+                        timedOut,
+                        output: result.output,
+                        outcome: parsed.outcome,
+                        message: typeof parsed.message === "string" ? parsed.message : undefined,
+                    };
+                    await gateRepo.record(entity.id, gate.id, passed, result.output);
+                    return outcomeResult;
+                }
+            }
+            catch {
+                // Not JSON — treat output as plain text, fall through to normal path
+            }
+        }
     }
     else if (gate.type === "function") {
         try {

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>;