@wopr-network/defcon 1.4.0 → 1.5.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,6 +87,7 @@ 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,

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

@@ -23,6 +23,7 @@ export declare const OnEnterSchema: z.ZodObject<{
 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";
@@ -42,6 +43,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 +55,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 +67,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 +79,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 +90,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 +101,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 +139,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";
@@ -133,6 +159,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 +170,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 +181,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

@@ -37,6 +37,7 @@ export const OnEnterSchema = z.object({
 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
@@ -51,11 +52,16 @@ export const StateDefinitionSchema = z.object({
     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

@@ -55,83 +55,20 @@ 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(),
-                        },
-                    ],
-                });
-                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(),
-            });
+        // 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;
         // 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 +79,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 +105,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 +130,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 +151,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 +169,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 +186,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 +331,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 +503,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;

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/execution/active-runner.js

@@ -104,7 +104,7 @@ export class ActiveRunner {
                 await this.entityRepo.updateArtifacts(invocation.entityId, { stuck: true, stuckAt: new Date().toISOString() });
                 return;
             }
-            await this.invocationRepo.create(invocation.entityId, invocation.stage, invocation.prompt, invocation.mode, undefined, { ...(invocation.context ?? {}), retryCount: retryCount + 1 });
+            await this.invocationRepo.create(invocation.entityId, invocation.stage, invocation.prompt, invocation.mode, undefined, { ...(invocation.context ?? {}), retryCount: retryCount + 1 }, invocation.agentRole);
             return;
         }
         // Gate timed out — re-queue after backoff instead of failing.
@@ -113,7 +113,7 @@ export class ActiveRunner {
         if (result.gated && result.gateTimedOut) {
             const retryAfterMs = 30000;
             this.logger.info(`[active-runner] gate timed out for entity ${invocation.entityId}, re-queuing after ${retryAfterMs}ms`);
-            await this.invocationRepo.create(invocation.entityId, invocation.stage, invocation.prompt, invocation.mode, undefined, invocation.context ?? undefined);
+            await this.invocationRepo.create(invocation.entityId, invocation.stage, invocation.prompt, invocation.mode, undefined, invocation.context ?? undefined, invocation.agentRole);
             await sleep(retryAfterMs, signal);
             return;
         }

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

@@ -203,6 +203,7 @@ export async function handleFlowClaim(deps, args) {
             invocation_id: claimed.id,
             flow: flow?.name ?? null,
             stage: claimed.stage,
+            agent_role: claimed.agentRole || null,
             prompt: claimed.prompt,
             context: claimed.context,
         });
@@ -260,7 +261,7 @@ export async function handleFlowReport(deps, args) {
         // 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);
+            await deps.invocations.create(entityId, activeInvocation.stage, activeInvocation.prompt, activeInvocation.mode, undefined, activeInvocation.context ?? undefined, activeInvocation.agentRole);
         }
         return errorResult(message);
     }
@@ -286,7 +287,7 @@ export async function handleFlowReport(deps, args) {
     // 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 replacement = await deps.invocations.create(entityId, activeInvocation.stage, activeInvocation.prompt, activeInvocation.mode, undefined, activeInvocation.context ?? undefined, activeInvocation.agentRole);
         const claimedBy = activeInvocation.claimedBy;
         if (claimedBy) {
             await deps.invocations.claim(replacement.id, claimedBy).catch(() => {

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

@@ -556,7 +556,7 @@ async function handleFlowReport(deps, args) {
             const flow = currentEntity ? await deps.flows.get(currentEntity.flowId) : null;
             const entityIsTerminal = currentEntity && flow ? isTerminal(flow, currentEntity.state) : false;
             if (!entityIsTerminal) {
-                const replacement = await deps.invocations.create(entityId, activeInvocation.stage, activeInvocation.prompt, activeInvocation.mode, undefined, activeInvocation.context ?? undefined);
+                const replacement = await deps.invocations.create(entityId, activeInvocation.stage, activeInvocation.prompt, activeInvocation.mode, undefined, activeInvocation.context ?? undefined, activeInvocation.agentRole);
                 // Claim the replacement for the same worker so it can retry immediately.
                 if (worker_id && replacement) {
                     try {
@@ -590,7 +590,7 @@ async function handleFlowReport(deps, args) {
     // Gate blocked — create a replacement unclaimed invocation so the entity
     // can be reclaimed; without it the entity would be permanently orphaned.
     if (result.gated) {
-        await deps.invocations.create(entityId, activeInvocation.stage, activeInvocation.prompt, activeInvocation.mode, undefined, activeInvocation.context ?? undefined);
+        await deps.invocations.create(entityId, activeInvocation.stage, activeInvocation.prompt, activeInvocation.mode, undefined, activeInvocation.context ?? undefined, activeInvocation.agentRole);
         if (result.gateTimedOut) {
             const renderedPrompt = result.timeoutPrompt ?? DEFAULT_TIMEOUT_PROMPT;
             return jsonResult({

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

@@ -9,6 +9,7 @@ function rowToState(r) {
         id: r.id,
         flowId: r.flowId,
         name: r.name,
+        agentRole: r.agentRole ?? null,
         modelTier: r.modelTier ?? null,
         mode: (r.mode ?? "passive"),
         promptTemplate: r.promptTemplate ?? null,
@@ -167,7 +168,7 @@ export class DrizzleFlowRepository {
             id,
             flowId,
             name: state.name,
-            agentRole: null,
+            agentRole: state.agentRole || null,
             modelTier: state.modelTier ?? null,
             mode: state.mode ?? "passive",
             promptTemplate: state.promptTemplate ?? null,
@@ -188,6 +189,8 @@ export class DrizzleFlowRepository {
         const updateValues = {};
         if (changes.name !== undefined)
             updateValues.name = changes.name;
+        if (changes.agentRole !== undefined)
+            updateValues.agentRole = changes.agentRole;
         if (changes.modelTier !== undefined)
             updateValues.modelTier = changes.modelTier;
         if (changes.mode !== undefined)
@@ -329,6 +332,7 @@ export class DrizzleFlowRepository {
                     id: s.id,
                     flowId,
                     name: s.name,
+                    agentRole: s.agentRole || null,
                     modelTier: s.modelTier,
                     mode: s.mode ?? "passive",
                     promptTemplate: s.promptTemplate,

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

@@ -13,6 +13,7 @@ function toGate(row) {
         timeoutMs: row.timeoutMs ?? null,
         failurePrompt: row.failurePrompt ?? null,
         timeoutPrompt: row.timeoutPrompt ?? null,
+        outcomes: row.outcomes ?? null,
     };
 }
 function toGateResult(row) {
@@ -42,6 +43,7 @@ export class DrizzleGateRepository {
             ...(gate.timeoutMs != null ? { timeoutMs: gate.timeoutMs } : {}),
             failurePrompt: gate.failurePrompt ?? null,
             timeoutPrompt: gate.timeoutPrompt ?? null,
+            outcomes: gate.outcomes ?? null,
         };
         this.db.insert(gateDefinitions).values(values).run();
         const row = this.db.select().from(gateDefinitions).where(eq(gateDefinitions.id, id)).get();

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

@@ -5,7 +5,7 @@ type Db = BetterSQLite3Database<typeof schema>;
 export declare class DrizzleInvocationRepository implements IInvocationRepository {
     private db;
     constructor(db: Db);
-    create(entityId: string, stage: string, prompt: string, mode: Mode, ttlMs?: number, context?: Record<string, unknown>): Promise<Invocation>;
+    create(entityId: string, stage: string, prompt: string, mode: Mode, ttlMs: number | undefined, context: Record<string, unknown> | undefined, agentRole: string | null): Promise<Invocation>;
     get(id: string): Promise<Invocation | null>;
     claim(invocationId: string, agentId: string): Promise<Invocation | null>;
     complete(id: string, signal: string, artifacts?: Artifacts): Promise<Invocation>;

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

@@ -6,6 +6,7 @@ function toInvocation(row) {
         id: row.id,
         entityId: row.entityId,
         stage: row.stage,
+        agentRole: row.agentRole ?? null,
         mode: row.mode,
         prompt: row.prompt,
         context: row.context,
@@ -25,7 +26,7 @@ export class DrizzleInvocationRepository {
     constructor(db) {
         this.db = db;
     }
-    async create(entityId, stage, prompt, mode, ttlMs, context) {
+    async create(entityId, stage, prompt, mode, ttlMs, context, agentRole) {
         const id = crypto.randomUUID();
         this.db
             .insert(invocations)
@@ -33,6 +34,7 @@ export class DrizzleInvocationRepository {
             id,
             entityId,
             stage,
+            agentRole: agentRole || null,
             prompt,
             mode,
             ttlMs: ttlMs ?? 1800000,

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

@@ -689,6 +689,23 @@ export declare const gateDefinitions: import("drizzle-orm/sqlite-core").SQLiteTa
         }, {}, {
             length: number | undefined;
         }>;
+        outcomes: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "outcomes";
+            tableName: "gate_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;
+        }, {}, {}>;
     };
     dialect: "sqlite";
 }>;

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

@@ -46,6 +46,7 @@ export const gateDefinitions = sqliteTable("gate_definitions", {
     timeoutMs: integer("timeout_ms"),
     failurePrompt: text("failure_prompt"),
     timeoutPrompt: text("timeout_prompt"),
+    outcomes: text("outcomes", { mode: "json" }),
 });
 export const transitionRules = sqliteTable("transition_rules", {
     id: text("id").primaryKey(),

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

@@ -36,6 +36,7 @@ export interface Invocation {
     id: string;
     entityId: string;
     stage: string;
+    agentRole: string | null;
     mode: Mode;
     prompt: string;
     context: Record<string, unknown> | null;
@@ -82,6 +83,8 @@ export interface State {
     id: string;
     flowId: string;
     name: string;
+    /** Agent type identifier — maps to an agent MD file (e.g. "wopr-architect" → ~/.claude/agents/wopr-architect.md). */
+    agentRole: string | null;
     modelTier: string | null;
     mode: Mode;
     promptTemplate: string | null;
@@ -115,6 +118,13 @@ export interface Gate {
     timeoutMs: number | null;
     failurePrompt: string | null;
     timeoutPrompt: string | null;
+    /** Named outcome map from structured gate output. Keys are outcome names; values declare
+     *  where the entity goes. `proceed: true` means the original transition continues.
+     *  `toState` redirects to a different state. */
+    outcomes: Record<string, {
+        proceed?: boolean;
+        toState?: string;
+    }> | null;
 }
 /** A complete flow definition with its states and transitions */
 export interface Flow {
@@ -170,6 +180,7 @@ export interface CreateFlowInput {
 /** Input for adding a state to a flow */
 export interface CreateStateInput {
     name: string;
+    agentRole?: string;
     modelTier?: string;
     mode?: Mode;
     promptTemplate?: string;
@@ -198,6 +209,10 @@ export interface CreateGateInput {
     timeoutMs?: number;
     failurePrompt?: string;
     timeoutPrompt?: string;
+    outcomes?: Record<string, {
+        proceed?: boolean;
+        toState?: string;
+    }>;
 }
 /** Data-access contract for entity lifecycle operations. */
 export interface IEntityRepository {
@@ -274,7 +289,7 @@ export interface IFlowRepository {
 /** Data-access contract for invocation lifecycle and claiming. */
 export interface IInvocationRepository {
     /** Create a new invocation for an entity at a given stage. */
-    create(entityId: string, stage: string, prompt: string, mode: Mode, ttlMs?: number, context?: Record<string, unknown>): Promise<Invocation>;
+    create(entityId: string, stage: string, prompt: string, mode: Mode, ttlMs: number | undefined, context: Record<string, unknown> | undefined, agentRole: string | null): Promise<Invocation>;
     /** Get an invocation by ID, or null if not found. */
     get(id: string): Promise<Invocation | null>;
     /** Atomically claim an unclaimed invocation for the specified agent. Uses compare-and-swap (UPDATE WHERE claimedBy IS NULL). Returns null if already claimed. */
@@ -329,7 +344,7 @@ export interface IGateRepository {
     /** Get all gate results for a given entity. */
     resultsFor(entityId: string): Promise<GateResult[]>;
     /** Update mutable fields on a gate definition. */
-    update(id: string, changes: Partial<Pick<Gate, "command" | "functionRef" | "apiConfig" | "timeoutMs" | "failurePrompt" | "timeoutPrompt">>): Promise<Gate>;
+    update(id: string, changes: Partial<Pick<Gate, "command" | "functionRef" | "apiConfig" | "timeoutMs" | "failurePrompt" | "timeoutPrompt" | "outcomes">>): Promise<Gate>;
     /** Delete the gate result for a specific entity+gate combination. */
     clearResult(entityId: string, gateId: string): Promise<void>;
 }

package/drizzle/0013_gate_outcomes.sql

@@ -0,0 +1 @@
+ALTER TABLE `gate_definitions` ADD `outcomes` text;

package/drizzle/meta/_journal.json

@@ -92,6 +92,13 @@
       "when": 1773002575474,
       "tag": "0012_certain_human_fly",
       "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "6",
+      "when": 1773100000000,
+      "tag": "0013_gate_outcomes",
+      "breakpoints": true
     }
   ]
 }

package/package.json

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