squadfoundry 0.1.0

package/dist/orchestrator/core/state-machine.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Squad Foundry — Explicit State Machine
+ *
+ * Manages valid job state transitions. All transitions are declared explicitly —
+ * no implicit or magical state changes. Each transition can carry a guard function
+ * that must return true for the transition to proceed.
+ *
+ * Squads can extend the base transitions with custom ones via registerTransition().
+ */
+import type { JobStatus, JobDefinition, GuardrailResult } from './types.js';
+export type TransitionEvent = 'START_CONTEXT_LOADING' | 'CONTEXT_LOADED' | 'START_SQUAD_DESIGN' | 'SQUAD_DESIGN_COMPLETE' | 'CREATE_JOB' | 'REQUEST_USER_INPUT' | 'USER_INPUT_RECEIVED' | 'MARK_READY' | 'START_STEP' | 'STEP_COMPLETE' | 'STEP_NEEDS_APPROVAL' | 'APPROVAL_GRANTED' | 'APPROVAL_REJECTED' | 'GUARDRAIL_BLOCKED' | 'GUARDRAIL_CLEARED' | 'FAIL' | 'COMPLETE' | string;
+export type GuardFn = (job: JobDefinition) => GuardResult;
+export interface GuardResult {
+    allowed: boolean;
+    reason?: string;
+    guardrailResults?: GuardrailResult[];
+}
+export interface TransitionDef {
+    from: JobStatus | JobStatus[];
+    event: TransitionEvent;
+    to: JobStatus;
+    guard?: GuardFn;
+    description: string;
+}
+export interface TransitionResult {
+    success: boolean;
+    previousStatus: JobStatus;
+    newStatus: JobStatus;
+    event: TransitionEvent;
+    reason?: string;
+    guardrailResults?: GuardrailResult[];
+}
+export declare class StateMachine {
+    private transitions;
+    /**
+     * Register a custom transition (e.g., for squad-specific states).
+     */
+    registerTransition(transition: TransitionDef): void;
+    /**
+     * Attempt a state transition. Returns a result with success/failure and reason.
+     */
+    transition(job: JobDefinition, event: TransitionEvent): TransitionResult;
+    /**
+     * Get all valid events from a given status.
+     */
+    validEventsFrom(status: JobStatus): TransitionEvent[];
+    /**
+     * Check whether a job is in a terminal state.
+     */
+    isTerminal(status: JobStatus): boolean;
+    /**
+     * Check whether a given transition is defined (ignoring guards).
+     */
+    canTransition(fromStatus: JobStatus, event: TransitionEvent): boolean;
+    /**
+     * Get all registered transitions (for diagnostics).
+     */
+    getAllTransitions(): Readonly<TransitionDef[]>;
+}
+/**
+ * Singleton factory — one machine per process.
+ * Squads register custom transitions on startup.
+ */
+export declare function createStateMachine(): StateMachine;
+//# sourceMappingURL=state-machine.d.ts.map

package/dist/orchestrator/core/state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../../../orchestrator/core/state-machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAM3E,MAAM,MAAM,eAAe,GACvB,uBAAuB,GACvB,gBAAgB,GAChB,oBAAoB,GACpB,uBAAuB,GACvB,YAAY,GACZ,oBAAoB,GACpB,qBAAqB,GACrB,YAAY,GACZ,YAAY,GACZ,eAAe,GACf,qBAAqB,GACrB,kBAAkB,GAClB,mBAAmB,GACnB,mBAAmB,GACnB,mBAAmB,GACnB,MAAM,GACN,UAAU,GACV,MAAM,CAAA;AAMV,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,aAAa,KAAK,WAAW,CAAA;AAEzD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAA;CACrC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,GAAG,SAAS,EAAE,CAAA;IAC7B,KAAK,EAAE,eAAe,CAAA;IACtB,EAAE,EAAE,SAAS,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAA;IAChB,cAAc,EAAE,SAAS,CAAA;IACzB,SAAS,EAAE,SAAS,CAAA;IACpB,KAAK,EAAE,eAAe,CAAA;IACtB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAA;CACrC;AAqID,qBAAa,YAAY;IACvB,OAAO,CAAC,WAAW,CAAyC;IAE5D;;OAEG;IACH,kBAAkB,CAAC,UAAU,EAAE,aAAa,GAAG,IAAI;IAInD;;OAEG;IACH,UAAU,CACR,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE,eAAe,GACrB,gBAAgB;IA2CnB;;OAEG;IACH,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,eAAe,EAAE;IASrD;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO;IAItC;;OAEG;IACH,aAAa,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO;IAOrE;;OAEG;IACH,iBAAiB,IAAI,QAAQ,CAAC,aAAa,EAAE,CAAC;CAG/C;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAEjD"}

package/dist/orchestrator/core/state-machine.js

@@ -0,0 +1,227 @@
+/**
+ * Squad Foundry — Explicit State Machine
+ *
+ * Manages valid job state transitions. All transitions are declared explicitly —
+ * no implicit or magical state changes. Each transition can carry a guard function
+ * that must return true for the transition to proceed.
+ *
+ * Squads can extend the base transitions with custom ones via registerTransition().
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Base Transitions
+// ─────────────────────────────────────────────────────────────────────────────
+const BASE_TRANSITIONS = [
+    {
+        from: 'INTAKE_PENDING',
+        event: 'START_CONTEXT_LOADING',
+        to: 'CONTEXT_LOADING',
+        description: 'Begin loading context files from filesystem',
+    },
+    {
+        from: 'CONTEXT_LOADING',
+        event: 'CONTEXT_LOADED',
+        to: 'SQUAD_DESIGNING',
+        description: 'Context loaded — begin squad design interview',
+    },
+    {
+        from: 'CONTEXT_LOADING',
+        event: 'CREATE_JOB',
+        to: 'JOB_CREATED',
+        description: 'Context loaded for existing squad — create job directly',
+    },
+    {
+        from: 'SQUAD_DESIGNING',
+        event: 'SQUAD_DESIGN_COMPLETE',
+        to: 'SQUAD_READY',
+        description: 'Squad definition generated and approved',
+    },
+    {
+        from: 'SQUAD_DESIGNING',
+        event: 'REQUEST_USER_INPUT',
+        to: 'WAITING_USER_INPUT',
+        description: 'Need more information from user during design',
+    },
+    {
+        from: 'SQUAD_READY',
+        event: 'CREATE_JOB',
+        to: 'JOB_CREATED',
+        description: 'Squad ready — create a new job',
+    },
+    {
+        from: 'JOB_CREATED',
+        event: 'MARK_READY',
+        to: 'READY_FOR_EXECUTION',
+        description: 'Job initialized and all preconditions met',
+    },
+    {
+        from: 'JOB_CREATED',
+        event: 'REQUEST_USER_INPUT',
+        to: 'WAITING_USER_INPUT',
+        description: 'Job created but needs user clarification before starting',
+    },
+    {
+        from: 'WAITING_USER_INPUT',
+        event: 'USER_INPUT_RECEIVED',
+        to: 'READY_FOR_EXECUTION',
+        description: 'User provided required input — ready to proceed',
+    },
+    {
+        from: 'READY_FOR_EXECUTION',
+        event: 'START_STEP',
+        to: 'RUNNING_STEP',
+        description: 'Beginning execution of the next workflow step',
+    },
+    {
+        from: 'RUNNING_STEP',
+        event: 'STEP_COMPLETE',
+        to: 'READY_FOR_EXECUTION',
+        description: 'Step completed — ready for next step',
+    },
+    {
+        from: 'RUNNING_STEP',
+        event: 'STEP_NEEDS_APPROVAL',
+        to: 'WAITING_APPROVAL',
+        description: 'Step output requires human approval before proceeding',
+    },
+    {
+        from: 'RUNNING_STEP',
+        event: 'GUARDRAIL_BLOCKED',
+        to: 'BLOCKED',
+        description: 'A guardrail blocked this step from continuing',
+    },
+    {
+        from: 'RUNNING_STEP',
+        event: 'REQUEST_USER_INPUT',
+        to: 'WAITING_USER_INPUT',
+        description: 'Agent needs user clarification during execution',
+    },
+    {
+        from: 'RUNNING_STEP',
+        event: 'FAIL',
+        to: 'FAILED',
+        description: 'Step failed critically',
+    },
+    {
+        from: 'WAITING_APPROVAL',
+        event: 'APPROVAL_GRANTED',
+        to: 'READY_FOR_EXECUTION',
+        description: 'Human approved — continue workflow',
+    },
+    {
+        from: 'WAITING_APPROVAL',
+        event: 'APPROVAL_REJECTED',
+        to: 'BLOCKED',
+        description: 'Human rejected — block workflow',
+    },
+    {
+        from: 'BLOCKED',
+        event: 'GUARDRAIL_CLEARED',
+        to: 'READY_FOR_EXECUTION',
+        description: 'Blocking condition resolved — resume',
+    },
+    {
+        from: 'BLOCKED',
+        event: 'FAIL',
+        to: 'FAILED',
+        description: 'Block was unresolvable — fail job',
+    },
+    {
+        from: ['READY_FOR_EXECUTION', 'RUNNING_STEP'],
+        event: 'COMPLETE',
+        to: 'COMPLETED',
+        description: 'All steps done — job complete',
+    },
+];
+// ─────────────────────────────────────────────────────────────────────────────
+// State Machine
+// ─────────────────────────────────────────────────────────────────────────────
+export class StateMachine {
+    transitions = [...BASE_TRANSITIONS];
+    /**
+     * Register a custom transition (e.g., for squad-specific states).
+     */
+    registerTransition(transition) {
+        this.transitions.push(transition);
+    }
+    /**
+     * Attempt a state transition. Returns a result with success/failure and reason.
+     */
+    transition(job, event) {
+        const currentStatus = job.status;
+        const previousStatus = currentStatus;
+        // Find a matching transition
+        const match = this.transitions.find((t) => {
+            const fromStates = Array.isArray(t.from) ? t.from : [t.from];
+            return fromStates.includes(currentStatus) && t.event === event;
+        });
+        if (!match) {
+            return {
+                success: false,
+                previousStatus,
+                newStatus: currentStatus,
+                event,
+                reason: `No transition found for state '${currentStatus}' + event '${event}'`,
+            };
+        }
+        // Run guard if present
+        if (match.guard) {
+            const guardResult = match.guard(job);
+            if (!guardResult.allowed) {
+                return {
+                    success: false,
+                    previousStatus,
+                    newStatus: currentStatus,
+                    event,
+                    reason: guardResult.reason ?? 'Guard function blocked transition',
+                    guardrailResults: guardResult.guardrailResults,
+                };
+            }
+        }
+        return {
+            success: true,
+            previousStatus,
+            newStatus: match.to,
+            event,
+        };
+    }
+    /**
+     * Get all valid events from a given status.
+     */
+    validEventsFrom(status) {
+        return this.transitions
+            .filter((t) => {
+            const fromStates = Array.isArray(t.from) ? t.from : [t.from];
+            return fromStates.includes(status);
+        })
+            .map((t) => t.event);
+    }
+    /**
+     * Check whether a job is in a terminal state.
+     */
+    isTerminal(status) {
+        return status === 'COMPLETED' || status === 'FAILED';
+    }
+    /**
+     * Check whether a given transition is defined (ignoring guards).
+     */
+    canTransition(fromStatus, event) {
+        return this.transitions.some((t) => {
+            const fromStates = Array.isArray(t.from) ? t.from : [t.from];
+            return fromStates.includes(fromStatus) && t.event === event;
+        });
+    }
+    /**
+     * Get all registered transitions (for diagnostics).
+     */
+    getAllTransitions() {
+        return this.transitions;
+    }
+}
+/**
+ * Singleton factory — one machine per process.
+ * Squads register custom transitions on startup.
+ */
+export function createStateMachine() {
+    return new StateMachine();
+}
+//# sourceMappingURL=state-machine.js.map

package/dist/orchestrator/core/state-machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.js","sourceRoot":"","sources":["../../../orchestrator/core/state-machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAyDH,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF,MAAM,gBAAgB,GAAoB;IACxC;QACE,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,uBAAuB;QAC9B,EAAE,EAAE,iBAAiB;QACrB,WAAW,EAAE,6CAA6C;KAC3D;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,KAAK,EAAE,gBAAgB;QACvB,EAAE,EAAE,iBAAiB;QACrB,WAAW,EAAE,+CAA+C;KAC7D;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,KAAK,EAAE,YAAY;QACnB,EAAE,EAAE,aAAa;QACjB,WAAW,EAAE,yDAAyD;KACvE;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,KAAK,EAAE,uBAAuB;QAC9B,EAAE,EAAE,aAAa;QACjB,WAAW,EAAE,yCAAyC;KACvD;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,KAAK,EAAE,oBAAoB;QAC3B,EAAE,EAAE,oBAAoB;QACxB,WAAW,EAAE,+CAA+C;KAC7D;IACD;QACE,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,YAAY;QACnB,EAAE,EAAE,aAAa;QACjB,WAAW,EAAE,gCAAgC;KAC9C;IACD;QACE,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,YAAY;QACnB,EAAE,EAAE,qBAAqB;QACzB,WAAW,EAAE,2CAA2C;KACzD;IACD;QACE,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,oBAAoB;QAC3B,EAAE,EAAE,oBAAoB;QACxB,WAAW,EAAE,0DAA0D;KACxE;IACD;QACE,IAAI,EAAE,oBAAoB;QAC1B,KAAK,EAAE,qBAAqB;QAC5B,EAAE,EAAE,qBAAqB;QACzB,WAAW,EAAE,iDAAiD;KAC/D;IACD;QACE,IAAI,EAAE,qBAAqB;QAC3B,KAAK,EAAE,YAAY;QACnB,EAAE,EAAE,cAAc;QAClB,WAAW,EAAE,+CAA+C;KAC7D;IACD;QACE,IAAI,EAAE,cAAc;QACpB,KAAK,EAAE,eAAe;QACtB,EAAE,EAAE,qBAAqB;QACzB,WAAW,EAAE,sCAAsC;KACpD;IACD;QACE,IAAI,EAAE,cAAc;QACpB,KAAK,EAAE,qBAAqB;QAC5B,EAAE,EAAE,kBAAkB;QACtB,WAAW,EAAE,uDAAuD;KACrE;IACD;QACE,IAAI,EAAE,cAAc;QACpB,KAAK,EAAE,mBAAmB;QAC1B,EAAE,EAAE,SAAS;QACb,WAAW,EAAE,+CAA+C;KAC7D;IACD;QACE,IAAI,EAAE,cAAc;QACpB,KAAK,EAAE,oBAAoB;QAC3B,EAAE,EAAE,oBAAoB;QACxB,WAAW,EAAE,iDAAiD;KAC/D;IACD;QACE,IAAI,EAAE,cAAc;QACpB,KAAK,EAAE,MAAM;QACb,EAAE,EAAE,QAAQ;QACZ,WAAW,EAAE,wBAAwB;KACtC;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,KAAK,EAAE,kBAAkB;QACzB,EAAE,EAAE,qBAAqB;QACzB,WAAW,EAAE,oCAAoC;KAClD;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,KAAK,EAAE,mBAAmB;QAC1B,EAAE,EAAE,SAAS;QACb,WAAW,EAAE,iCAAiC;KAC/C;IACD;QACE,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,mBAAmB;QAC1B,EAAE,EAAE,qBAAqB;QACzB,WAAW,EAAE,sCAAsC;KACpD;IACD;QACE,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,MAAM;QACb,EAAE,EAAE,QAAQ;QACZ,WAAW,EAAE,mCAAmC;KACjD;IACD;QACE,IAAI,EAAE,CAAC,qBAAqB,EAAE,cAAc,CAAC;QAC7C,KAAK,EAAE,UAAU;QACjB,EAAE,EAAE,WAAW;QACf,WAAW,EAAE,+BAA+B;KAC7C;CACF,CAAA;AAED,gFAAgF;AAChF,gBAAgB;AAChB,gFAAgF;AAEhF,MAAM,OAAO,YAAY;IACf,WAAW,GAAoB,CAAC,GAAG,gBAAgB,CAAC,CAAA;IAE5D;;OAEG;IACH,kBAAkB,CAAC,UAAyB;QAC1C,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IACnC,CAAC;IAED;;OAEG;IACH,UAAU,CACR,GAAkB,EAClB,KAAsB;QAEtB,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,CAAA;QAChC,MAAM,cAAc,GAAG,aAAa,CAAA;QAEpC,6BAA6B;QAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;YACxC,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;YAC5D,OAAO,UAAU,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,KAAK,CAAA;QAChE,CAAC,CAAC,CAAA;QAEF,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,cAAc;gBACd,SAAS,EAAE,aAAa;gBACxB,KAAK;gBACL,MAAM,EAAE,kCAAkC,aAAa,cAAc,KAAK,GAAG;aAC9E,CAAA;QACH,CAAC;QAED,uBAAuB;QACvB,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAChB,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;YACpC,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;gBACzB,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,cAAc;oBACd,SAAS,EAAE,aAAa;oBACxB,KAAK;oBACL,MAAM,EAAE,WAAW,CAAC,MAAM,IAAI,mCAAmC;oBACjE,gBAAgB,EAAE,WAAW,CAAC,gBAAgB;iBAC/C,CAAA;YACH,CAAC;QACH,CAAC;QAED,OAAO;YACL,OAAO,EAAE,IAAI;YACb,cAAc;YACd,SAAS,EAAE,KAAK,CAAC,EAAE;YACnB,KAAK;SACN,CAAA;IACH,CAAC;IAED;;OAEG;IACH,eAAe,CAAC,MAAiB;QAC/B,OAAO,IAAI,CAAC,WAAW;aACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;YACZ,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;YAC5D,OAAO,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;QACpC,CAAC,CAAC;aACD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;IACxB,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,MAAiB;QAC1B,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,QAAQ,CAAA;IACtD,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,UAAqB,EAAE,KAAsB;QACzD,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;YACjC,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;YAC5D,OAAO,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,KAAK,CAAA;QAC7D,CAAC,CAAC,CAAA;IACJ,CAAC;IAED;;OAEG;IACH,iBAAiB;QACf,OAAO,IAAI,CAAC,WAAW,CAAA;IACzB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,IAAI,YAAY,EAAE,CAAA;AAC3B,CAAC"}

package/dist/orchestrator/core/types.d.ts

@@ -0,0 +1,364 @@
+/**
+ * Squad Foundry — Core Type Definitions
+ *
+ * These types form the portable, host-agnostic contract for the entire platform.
+ * No external dependencies. No IDE-specific concepts. No vendor lock-in.
+ *
+ * All adapters, runtime components, and builders operate against these types.
+ */
+export type SquadId = string;
+export type AgentId = string;
+export type JobId = string;
+export type StepId = string;
+export type GuardrailId = string;
+export type ArtifactId = string;
+export type HandoffId = string;
+export type SquadDomain = 'software-development' | 'content-marketing' | 'social-media' | 'documentation' | 'research' | 'operations' | 'hr' | 'sales' | 'custom';
+/**
+ * Base states available to every job regardless of squad domain.
+ * Squads can define additional custom states in their WorkflowDefinition.
+ */
+export type BaseJobStatus = 'INTAKE_PENDING' | 'CONTEXT_LOADING' | 'SQUAD_DESIGNING' | 'SQUAD_READY' | 'JOB_CREATED' | 'WAITING_USER_INPUT' | 'READY_FOR_EXECUTION' | 'RUNNING_STEP' | 'BLOCKED' | 'WAITING_APPROVAL' | 'FAILED' | 'COMPLETED';
+export type JobStatus = BaseJobStatus | (string & Record<never, never>);
+/**
+ * A portable definition of an agent. Not tied to any host, model, or tool.
+ * The same AgentDefinition can run in Claude Code, OpenCode, Cursor, etc.
+ */
+export interface AgentDefinition {
+    /** Unique identifier within the squad */
+    id: AgentId;
+    /** Human-readable name */
+    name: string;
+    /** Functional role in the squad */
+    role: string;
+    /** Domain this agent operates in */
+    domain: SquadDomain;
+    /** What this agent is responsible for */
+    objective: string;
+    /** Base system prompt / instructions for this agent */
+    instructions: string;
+    /** Expected input format/description */
+    inputs: AgentIO[];
+    /** Expected output format/description */
+    outputs: AgentIO[];
+    /** Tool IDs this agent is allowed to invoke */
+    allowedTools: string[];
+    /** Hard constraints / prohibitions */
+    constraints: string[];
+    /** What constitutes success for this agent's turn */
+    successCriteria: string[];
+    /** What constitutes failure for this agent's turn */
+    failureCriteria: string[];
+    /** Which job states this agent can run in */
+    allowedStates: JobStatus[];
+    /** Conditions that block this agent from running */
+    blockingConditions: string[];
+    /** Handoff rules: which agent comes next and under which conditions */
+    handoffRules: HandoffRule[];
+    /** Expected response format */
+    responseFormat: 'markdown' | 'json' | 'plain' | 'structured';
+    /** Model preference for this agent (optional — uses squad default if absent) */
+    modelPreference?: ModelPreference;
+}
+export interface AgentIO {
+    name: string;
+    description: string;
+    required: boolean;
+    format?: string;
+}
+export interface HandoffRule {
+    condition: string;
+    targetAgentId: AgentId;
+    description: string;
+    requiresApproval?: boolean;
+}
+export interface ModelPreference {
+    provider?: string;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+export interface WorkflowDefinition {
+    id: string;
+    name: string;
+    description: string;
+    /** Ordered list of steps */
+    steps: WorkflowStep[];
+    /** Custom states this squad adds beyond the base states */
+    customStates?: string[];
+    /** Default entry point step */
+    entryStepId: StepId;
+}
+export interface WorkflowStep {
+    id: StepId;
+    name: string;
+    agentId: AgentId;
+    description: string;
+    /** Steps that must be completed before this one */
+    dependsOn: StepId[];
+    /** Guardrail IDs that apply to this step */
+    guardrails: GuardrailId[];
+    /** Whether a human must approve before entering this step */
+    requiresApprovalBefore: boolean;
+    /** Whether a human must approve the output before moving forward */
+    requiresApprovalAfter: boolean;
+    /** Artifacts that must exist before this step can run */
+    requiredArtifacts: string[];
+    /** Artifacts this step is expected to produce */
+    producedArtifacts: string[];
+    /** Precondition expression (evaluated against job context) */
+    precondition?: string;
+    /** Postcondition expression (evaluated against step output) */
+    postcondition?: string;
+    /** If true, step can loop back to itself or a previous step */
+    allowsLoop?: boolean;
+    /** Next step under normal conditions */
+    nextStepId?: StepId;
+    /** Next step if the agent signals failure */
+    failureStepId?: StepId;
+}
+export type GuardrailSeverity = 'warn' | 'block';
+export interface GuardrailRule {
+    id: GuardrailId;
+    name: string;
+    description: string;
+    severity: GuardrailSeverity;
+    /** The JS function body as string OR a pre-defined rule key */
+    ruleKey: BuiltinGuardrailKey | string;
+    /** Parameters passed to the rule evaluator */
+    params?: Record<string, unknown>;
+}
+export type BuiltinGuardrailKey = 'require_minimum_context' | 'require_artifact_before_step' | 'require_approval_before_publish' | 'require_human_before_deploy' | 'block_invalid_state_transition' | 'require_pr_criteria' | 'no_agent_outside_allowed_states' | 'require_artifact_produced';
+export interface PolicyDefinition {
+    id: string;
+    name: string;
+    description: string;
+    guardrails: GuardrailRule[];
+    /** Actions that are globally prohibited for this squad */
+    prohibitedActions: string[];
+    /** Required approvals for specific actions */
+    requiredApprovals: ApprovalRequirement[];
+}
+export interface ApprovalRequirement {
+    action: string;
+    description: string;
+    approverRole?: string;
+    timeout?: number;
+}
+/**
+ * A Squad is the core, portable, reusable entity.
+ * This JSON/object structure can be serialized and loaded by any host.
+ */
+export interface SquadDefinition {
+    id: SquadId;
+    name: string;
+    domain: SquadDomain;
+    objective: string;
+    description: string;
+    /** Free-form context about the squad's operational environment */
+    context: string;
+    agents: AgentDefinition[];
+    workflow: WorkflowDefinition;
+    policy: PolicyDefinition;
+    /** Artifacts expected at squad completion */
+    expectedArtifacts: ExpectedArtifact[];
+    /** External tools and integrations this squad may use */
+    allowedIntegrations: IntegrationRef[];
+    /** Template IDs used by this squad */
+    templates: string[];
+    /** Criteria for declaring the squad job successful */
+    successCriteria: string[];
+    /** Criteria for declaring the squad job failed */
+    failureCriteria: string[];
+    /** Metadata */
+    metadata: SquadMetadata;
+}
+export interface ExpectedArtifact {
+    id: string;
+    name: string;
+    description: string;
+    path: string;
+    required: boolean;
+    format: 'json' | 'markdown' | 'text' | 'binary';
+}
+export interface IntegrationRef {
+    id: string;
+    type: 'vcs' | 'cicd' | 'social-media' | 'deploy' | 'analytics' | 'docs' | 'mcp' | 'custom';
+    name: string;
+    /** Whether this integration is required or optional */
+    required: boolean;
+    /** Adapter stub status */
+    status: 'real' | 'stub' | 'mock';
+}
+export interface SquadMetadata {
+    version: string;
+    createdAt: string;
+    updatedAt: string;
+    author?: string;
+    tags: string[];
+    hostCompatibility: string[];
+}
+export interface JobDefinition {
+    id: JobId;
+    squadId: SquadId;
+    status: JobStatus;
+    objective: string;
+    /** Human-provided initial context / request */
+    initialInput: string;
+    /** Loaded context from files (PROJECT.md, TASKS.md, etc.) */
+    loadedContext: LoadedContext;
+    artifacts: ArtifactRef[];
+    approvals: ApprovalRecord[];
+    currentStepId: StepId | null;
+    currentAgentId: AgentId | null;
+    history: HistoryEntry[];
+    startedAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    failureReason?: string;
+}
+export interface LoadedContext {
+    projectMd?: string;
+    tasksMd?: string;
+    agentsMd?: string;
+    readmeMd?: string;
+    docs: FileContent[];
+    specs: FileContent[];
+    playbooks: FileContent[];
+    policies: FileContent[];
+    templates: FileContent[];
+    custom: FileContent[];
+}
+export interface FileContent {
+    path: string;
+    content: string;
+    loadedAt: string;
+}
+export interface ArtifactRef {
+    id: ArtifactId;
+    name: string;
+    path: string;
+    producedByAgentId: AgentId;
+    producedAtStepId: StepId;
+    format: 'json' | 'markdown' | 'text' | 'binary';
+    createdAt: string;
+}
+export interface ApprovalRecord {
+    id: string;
+    stepId: StepId;
+    requiredFor: string;
+    status: 'pending' | 'approved' | 'rejected';
+    requestedAt: string;
+    resolvedAt?: string;
+    resolvedBy?: string;
+    notes?: string;
+}
+export interface HistoryEntry {
+    timestamp: string;
+    type: 'state_transition' | 'agent_run' | 'handoff' | 'approval' | 'blocked' | 'error' | 'info';
+    fromStatus?: JobStatus;
+    toStatus?: JobStatus;
+    agentId?: AgentId;
+    stepId?: StepId;
+    message: string;
+    data?: Record<string, unknown>;
+}
+export interface HandoffEvent {
+    id: HandoffId;
+    jobId: JobId;
+    fromAgentId: AgentId;
+    toAgentId: AgentId;
+    fromStepId: StepId;
+    toStepId: StepId;
+    condition: string;
+    payload: HandoffPayload;
+    timestamp: string;
+    requiresApproval: boolean;
+    approved?: boolean;
+}
+export interface HandoffPayload {
+    summary: string;
+    artifacts: ArtifactRef[];
+    notes?: string;
+    data?: Record<string, unknown>;
+}
+export interface ContextDiscoveryResult {
+    rootPath: string;
+    foundFiles: DiscoveredFile[];
+    missingRecommended: string[];
+    loadedAt: string;
+}
+export interface DiscoveredFile {
+    relativePath: string;
+    absolutePath: string;
+    category: ContextFileCategory;
+    priority: number;
+    sizeBytes: number;
+}
+export type ContextFileCategory = 'project' | 'tasks' | 'agents' | 'readme' | 'docs' | 'specs' | 'playbooks' | 'policies' | 'templates' | 'workflows' | 'brand' | 'custom';
+export interface InterviewQuestion {
+    id: string;
+    question: string;
+    hint?: string;
+    category: InterviewCategory;
+    required: boolean;
+    followUpIds?: string[];
+}
+export type InterviewCategory = 'objective' | 'domain' | 'io' | 'steps' | 'approvals' | 'tools' | 'policies' | 'risks' | 'context';
+export interface InterviewAnswer {
+    questionId: string;
+    answer: string;
+}
+export interface InterviewSession {
+    id: string;
+    answers: InterviewAnswer[];
+    startedAt: string;
+    completedAt?: string;
+}
+export interface SquadBuildResult {
+    squadDefinition: SquadDefinition;
+    generatedFiles: GeneratedFile[];
+    warnings: string[];
+}
+export interface GeneratedFile {
+    path: string;
+    content: string;
+    format: 'json' | 'markdown';
+}
+export interface AgentResponse {
+    agentId: AgentId;
+    stepId: StepId;
+    jobId: JobId;
+    content: string;
+    artifacts: PendingArtifact[];
+    handoffSignal?: HandoffSignal;
+    approvalNeeded?: boolean;
+    approvalReason?: string;
+    status: 'success' | 'failure' | 'needs_input' | 'loop_back';
+    metadata?: Record<string, unknown>;
+}
+export interface PendingArtifact {
+    name: string;
+    content: string;
+    format: 'json' | 'markdown' | 'text';
+    description?: string;
+}
+export interface HandoffSignal {
+    targetAgentId: AgentId;
+    condition: string;
+    payload: Omit<HandoffPayload, 'artifacts'>;
+}
+export interface GuardrailEvaluationContext {
+    job: JobDefinition;
+    step: WorkflowStep;
+    agent: AgentDefinition;
+    response?: AgentResponse;
+}
+export interface GuardrailResult {
+    guardrailId: GuardrailId;
+    passed: boolean;
+    severity: GuardrailSeverity;
+    message: string;
+    blockedTransition?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map