expxagents 0.24.0 → 0.24.2

package/assets/core/runner.pipeline.md

@@ -19,7 +19,14 @@ For each pipeline step:
 
 #### Agent Steps (type: agent or default)
 
-1. **Set agent status** → `working` in state.json
+1. **Update state.json BEFORE executing:**
+   - Set `status` → `running`
+   - Set `step.current` → current step number (1-based)
+   - Set `step.label` → step label from squad.yaml
+   - Set agent `status` → `working`
+   - **CRITICAL: Set agent `stepIndex`** → current step number (1-based). This triggers the dashboard kanban to move the previous task to "done" and the current task to "executing". Without this update, kanban tasks won't transition.
+   - Set agent `stepLabel` → step label
+   - Write state.json immediately (before doing any work)
 2. **Build context:**
    - Agent prompt from `agents/<agent-id>.md`
    - Previous agent output (if `deliverFrom` is set)
@@ -30,12 +37,41 @@ For each pipeline step:
    - `inline` execution: run in current context
    - `subagent` execution: spawn background process
 4. **Save output** to `output/step-XX.md`
-5. **Update state.json:**
+5. **Update state.json AFTER executing:**
    - Agent status → `delivering` (if handoff) or `done`
    - Handoff message
-   - Step progress
+   - Write state.json immediately
 6. **Handoff delay** (2 seconds for dashboard animation)
 
+#### Step Failure Handling (on_fail)
+
+Each step can define `on_fail` in squad.yaml:
+
+- `abort` (default) — stop the pipeline immediately
+- `skip` — log the error, mark agent as done with skip message, continue to next step
+- `retry` — retry the step up to `max_retries` times (default: 2), then abort
+
+Example in squad.yaml:
+```yaml
+pipeline:
+  steps:
+    - id: step-01
+      agent: transcriber
+      label: Extract transcript
+      on_fail: skip      # continue pipeline if transcript fails
+    - id: step-02
+      agent: writer
+      label: Write article
+      on_fail: retry
+      max_retries: 3     # try up to 4 times total
+```
+
+When a step is skipped:
+1. Set agent status → `done`
+2. Set agent message → "Skipped: [error reason]"
+3. Write state.json
+4. Continue to next step (the next agent may need to handle missing input)
+
 #### Checkpoint Steps (type: checkpoint)
 
 1. **Set status** → `checkpoint` in state.json
@@ -50,28 +86,50 @@ For each pipeline step:
 
 ### State Management (state.json)
 
+**IMPORTANT:** The dashboard file watcher monitors state.json for changes. When agent `stepIndex` changes, it automatically updates the kanban board (previous step → done, current step → executing). You MUST update `stepIndex` on each agent before starting their step.
+
 ```json
 {
   "squad": "<squad-code>",
   "status": "running",
-  "step": { "current": 1, "total": 5, "label": "step-01-research" },
+  "step": { "current": 2, "total": 5, "label": "step-02-writing" },
   "agents": [
     {
       "id": "researcher",
       "name": "Angela Researcher",
       "icon": "magnifying-glass",
-      "status": "working",
+      "status": "done",
+      "stepIndex": 1,
+      "stepLabel": "step-01-research",
       "desk": { "col": 1, "row": 1 },
+      "deliverTo": "writer",
+      "message": "Research complete"
+    },
+    {
+      "id": "writer",
+      "name": "Bruno Writer",
+      "icon": "pen",
+      "status": "working",
+      "stepIndex": 2,
+      "stepLabel": "step-02-writing",
+      "desk": { "col": 2, "row": 1 },
       "deliverTo": null,
       "message": ""
     }
   ],
   "handoff": null,
   "startedAt": "2026-03-13T00:00:00Z",
-  "updatedAt": "2026-03-13T00:00:00Z"
+  "updatedAt": "2026-03-13T00:00:05Z"
 }
 ```
 
+**Key fields for kanban integration:**
+- `step.current` — global step number (1-based)
+- `agent.stepIndex` — the step number this agent is currently on (1-based). Changes to this field trigger kanban task transitions
+- `agent.stepLabel` — label of the current step
+- `agent.status` — `working` | `delivering` | `done` | `idle` | `checkpoint`
+```
+
 ### Output Versioning
 
 - First run: `output/v1/`

package/dist/cli/src/commands/run.js

@@ -178,6 +178,7 @@ export async function runCommand(name) {
         console.log(`Pipeline: ${config.squad.pipeline.steps.length} steps\n`);
     }
     const steps = config.squad.pipeline.steps;
+    const stepAttempts = new Map();
     for (let i = 0; i < steps.length; i++) {
         const step = steps[i];
         const stepNumber = i + 1;
@@ -210,7 +211,32 @@ export async function runCommand(name) {
             output = await runWithProvider(prompt, agent, squadDir, spawnClaudeCode);
         }
         catch (err) {
-            console.error(`\nStep ${stepNumber} failed: ${err.message}`);
+            const failAction = step.onFail ?? 'abort';
+            console.error(`\nStep ${stepNumber} failed: ${err.message} [on_fail: ${failAction}]`);
+            if (failAction === 'retry') {
+                const maxRetries = step.maxRetries ?? 2;
+                const attempt = stepAttempts.get(step.id) ?? 0;
+                if (attempt < maxRetries) {
+                    stepAttempts.set(step.id, attempt + 1);
+                    console.log(`\nRetrying step ${stepNumber} (attempt ${attempt + 2}/${maxRetries + 1})...\n`);
+                    state = updateAgentStatus(state, step.agent, 'idle');
+                    writeState(squadDir, state);
+                    i--;
+                    continue;
+                }
+                console.error(`\nStep ${stepNumber} failed after ${maxRetries + 1} attempts. Aborting.`);
+            }
+            if (failAction === 'skip') {
+                console.log(`\nSkipping step ${stepNumber} (on_fail: skip). Continuing pipeline.\n`);
+                state = updateAgentStatus(state, step.agent, 'done');
+                state = {
+                    ...state,
+                    agents: state.agents.map((a) => a.id === step.agent ? { ...a, message: `Skipped: ${err.message}` } : a),
+                };
+                writeState(squadDir, state);
+                continue;
+            }
+            // Default: abort
             state = updateAgentStatus(state, step.agent, 'idle');
             state = setSquadStatus(state, 'idle');
             writeState(squadDir, state);

package/dist/core/squad-loader.d.ts

@@ -12,6 +12,8 @@ export interface PipelineStep {
     agent: string;
     label: string;
     deliverFrom?: string;
+    onFail?: 'skip' | 'retry' | 'abort';
+    maxRetries?: number;
 }
 export interface ScheduleConfig {
     enabled: boolean;

package/dist/core/squad-loader.js

@@ -122,6 +122,14 @@ export function loadSquad(squadDir) {
         };
     }
     const mcps = Array.isArray(squad.mcps) ? squad.mcps : [];
+    const mappedSteps = steps.map((s) => ({
+        id: s.id,
+        agent: s.agent,
+        label: s.label,
+        deliverFrom: s.deliverFrom ?? s.deliver_from,
+        onFail: ['skip', 'retry', 'abort'].includes(s.on_fail) ? s.on_fail : undefined,
+        maxRetries: typeof s.max_retries === 'number' ? s.max_retries : undefined,
+    }));
     return {
         squad: {
             code: squad.code,
@@ -134,7 +142,7 @@ export function loadSquad(squadDir) {
             icon: squad.icon,
             agents,
             skills,
-            pipeline: { steps },
+            pipeline: { steps: mappedSteps },
             schedule,
             chain,
             webhooks,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expxagents",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "description": "Multi-agent orchestration platform for AI squads",
   "author": "ExpxAgents",
   "license": "MIT",