@bradygaster/squad-cli 0.8.24 → 0.9.0

package/scripts/patch-esm-imports.mjs

@@ -1,18 +1,19 @@
 #!/usr/bin/env node
 
 /**
- * ESM Import Patcher for @github/copilot-sdk
- * 
- * Patches broken ESM imports in @github/copilot-sdk for Node 24+ compatibility.
- * 
- * Root cause: @github/copilot-sdk@0.1.32 has inconsistent ESM imports:
- * - session.js imports "vscode-jsonrpc/node" (BROKEN - missing .js extension)
- * - client.js imports "vscode-jsonrpc/node.js" (correct)
- * 
- * Node 24+ enforces strict ESM resolution requiring .js extensions.
- * This is a temporary workaround until copilot-sdk fixes upstream.
- * 
- * Issue: bradygaster/squad#XXX
+ * ESM Import Patcher — dual-layer fix for Node 22/24+ compatibility
+ *
+ * Layer 1: Patch vscode-jsonrpc/package.json with `exports` field
+ *   vscode-jsonrpc@8.2.1 has no `exports` field. Node 22+ strict ESM
+ *   rejects subpath imports like 'vscode-jsonrpc/node' without it.
+ *   Injecting the exports map from v9.x fixes ALL subpath imports at once.
+ *
+ * Layer 2: Patch @github/copilot-sdk session.js (defense-in-depth)
+ *   copilot-sdk@0.1.32 imports 'vscode-jsonrpc/node' without .js extension.
+ *   This layer ensures the import works even if Layer 1 somehow fails.
+ *
+ * Issue: bradygaster/squad#449
+ * Upstream: https://github.com/github/copilot-sdk/issues/707
  */
 
 import { readFileSync, writeFileSync, existsSync } from 'fs';
@@ -21,57 +22,85 @@ import { fileURLToPath } from 'url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+// Locations where npm workspaces / global install may place dependencies
+const SEARCH_ROOTS = [
+  join(__dirname, '..', 'node_modules'),              // squad-cli local
+  join(__dirname, '..', '..', '..', 'node_modules'),  // workspace root
+  join(__dirname, '..', '..'),                         // global install (sibling)
+];
+
 /**
- * Patch session.js in @github/copilot-sdk
+ * Layer 1 — Inject `exports` field into vscode-jsonrpc/package.json.
+ * This is the canonical fix: once the package has proper exports, Node's
+ * ESM resolver handles every subpath ('vscode-jsonrpc/node', '/browser', etc.)
+ * without needing per-file patches.
  */
-function patchCopilotSdk() {
-  // Try multiple possible locations (npm workspaces can hoist dependencies)
-  const possiblePaths = [
-    // squad-cli package node_modules
-    join(__dirname, '..', 'node_modules', '@github', 'copilot-sdk', 'dist', 'session.js'),
-    // Workspace root node_modules (common with npm workspaces)
-    join(__dirname, '..', '..', '..', 'node_modules', '@github', 'copilot-sdk', 'dist', 'session.js'),
-    // Global install location (node_modules at parent of package)
-    join(__dirname, '..', '..', '@github', 'copilot-sdk', 'dist', 'session.js'),
-  ];
-
-  let sessionJsPath = null;
-  for (const path of possiblePaths) {
-    if (existsSync(path)) {
-      sessionJsPath = path;
-      break;
+function patchVscodeJsonrpcExports() {
+  const exportsField = {
+    '.': { types: './lib/common/api.d.ts', default: './lib/node/main.js' },
+    './node': { node: './lib/node/main.js', types: './lib/node/main.d.ts' },
+    './node.js': { node: './lib/node/main.js', types: './lib/node/main.d.ts' },
+    './browser': { types: './lib/browser/main.d.ts', browser: './lib/browser/main.js' },
+  };
+
+  for (const root of SEARCH_ROOTS) {
+    const pkgPath = join(root, 'vscode-jsonrpc', 'package.json');
+    if (!existsSync(pkgPath)) continue;
+
+    try {
+      const raw = readFileSync(pkgPath, 'utf8');
+      const pkg = JSON.parse(raw);
+
+      if (pkg.exports && pkg.exports['./node.js']) {
+        console.log('⏭️  vscode-jsonrpc already has complete exports field — skipping');
+        return false;
+      }
+
+      pkg.exports = exportsField;
+      writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+      console.log('✅ Patched vscode-jsonrpc/package.json with exports field (Node 22/24+ ESM fix)');
+      return true;
+    } catch (err) {
+      console.warn('⚠️  Failed to patch vscode-jsonrpc exports:', err.message);
+      return false;
     }
   }
 
-  if (!sessionJsPath) {
-    // copilot-sdk not installed (maybe optionalDependency or CI without install)
-    // This is fine - exit silently
-    return false;
-  }
+  return false;
+}
 
-  try {
-    let content = readFileSync(sessionJsPath, 'utf8');
-    
-    // Replace extensionless import with .js extension
-    const patched = content.replace(
-      /from\s+["']vscode-jsonrpc\/node["']/g,
-      'from "vscode-jsonrpc/node.js"'
-    );
-
-    if (patched !== content) {
-      writeFileSync(sessionJsPath, patched, 'utf8');
-      console.log('✅ Patched @github/copilot-sdk ESM imports for Node 24+ compatibility');
-      return true;
-    } else {
-      // Already patched or upstream fixed
+/**
+ * Layer 2 — Patch copilot-sdk session.js import (defense-in-depth).
+ * Rewrites extensionless 'vscode-jsonrpc/node' to 'vscode-jsonrpc/node.js'.
+ */
+function patchCopilotSdkSessionJs() {
+  for (const root of SEARCH_ROOTS) {
+    const sessionJsPath = join(root, '@github', 'copilot-sdk', 'dist', 'session.js');
+    if (!existsSync(sessionJsPath)) continue;
+
+    try {
+      const content = readFileSync(sessionJsPath, 'utf8');
+
+      const patched = content.replace(
+        /from\s+["']vscode-jsonrpc\/node["']/g,
+        'from "vscode-jsonrpc/node.js"'
+      );
+
+      if (patched !== content) {
+        writeFileSync(sessionJsPath, patched, 'utf8');
+        console.log('✅ Patched @github/copilot-sdk session.js ESM imports');
+        return true;
+      }
+      return false;
+    } catch (err) {
+      console.warn('⚠️  Failed to patch copilot-sdk session.js:', err.message);
       return false;
     }
-  } catch (err) {
-    console.warn('⚠️  Failed to patch @github/copilot-sdk ESM imports:', err.message);
-    console.warn('    This may cause issues on Node 24+ if copilot-sdk loads.');
-    return false;
   }
+
+  return false;
 }
 
-// Run patch
-patchCopilotSdk();
+// Run both layers
+patchVscodeJsonrpcExports();
+patchCopilotSdkSessionJs();

package/scripts/patch-ink-rendering.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+/**
+ * Ink Rendering Patcher for Squad CLI
+ *
+ * Patches ink/build/ink.js to fix scroll flicker on Windows Terminal.
+ * Three patches are applied:
+ *
+ * 1. Remove trailing newline — the extra '\n' appended to output causes
+ *    logUpdate's previousLineCount to be off by one, pushing the bottom of
+ *    the UI below the viewport.
+ *
+ * 2. Disable clearTerminal fullscreen path — when output fills the terminal,
+ *    Ink clears the entire screen, causing violent scroll-to-top flicker.
+ *    We force the condition to `false` so logUpdate's incremental
+ *    erase-and-rewrite is always used instead.
+ *
+ * 3. Verify incrementalRendering passthrough — confirms that Ink forwards
+ *    the incrementalRendering option to logUpdate.create(). No code change
+ *    needed if already wired up.
+ *
+ * All patches are idempotent (safe to run multiple times).
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function patchInkRendering() {
+  // Try multiple possible locations (npm workspaces can hoist dependencies)
+  const possiblePaths = [
+    // squad-cli package node_modules
+    join(__dirname, '..', 'node_modules', 'ink', 'build', 'ink.js'),
+    // Workspace root node_modules (common with npm workspaces)
+    join(__dirname, '..', '..', '..', 'node_modules', 'ink', 'build', 'ink.js'),
+    // Global install location (node_modules at parent of package)
+    join(__dirname, '..', '..', 'ink', 'build', 'ink.js'),
+  ];
+
+  const inkJsPath = possiblePaths.find(p => existsSync(p)) ?? null;
+
+  if (!inkJsPath) {
+    // ink not installed yet — exit silently
+    return false;
+  }
+
+  try {
+    let content = readFileSync(inkJsPath, 'utf8');
+    let patchCount = 0;
+
+    // --- Patch 1: Remove trailing newline ---
+    // Original:  const outputToRender = output + '\n';
+    // Patched:   const outputToRender = output;
+    const trailingNewlineSearch = "const outputToRender = output + '\\n';";
+    const trailingNewlineReplace = 'const outputToRender = output;';
+    if (content.includes(trailingNewlineSearch)) {
+      content = content.replace(trailingNewlineSearch, trailingNewlineReplace);
+      console.log('  ✅ Patch 1/3: Removed trailing newline from outputToRender');
+      patchCount++;
+    } else if (content.includes(trailingNewlineReplace)) {
+      console.log('  ⏭️  Patch 1/3: Trailing newline already removed');
+    } else {
+      console.warn('  ⚠️  Patch 1/3: Could not find outputToRender pattern — Ink version may have changed');
+    }
+
+    // --- Patch 2: Disable clearTerminal fullscreen path ---
+    // Original:  if (isFullscreen) {
+    //              const sync = shouldSynchronize(this.options.stdout);
+    //              ...
+    //              this.options.stdout.write(ansiEscapes.clearTerminal + ...
+    // Patched:   if (false) {
+    //
+    // We match `if (isFullscreen) {` only when followed by the clearTerminal
+    // usage to avoid replacing unrelated isFullscreen references.
+    const fullscreenSearch = /if \(isFullscreen\) \{\s*\n\s*const sync = shouldSynchronize/;
+    const fullscreenAlreadyPatched = /if \(false\) \{\s*\n\s*const sync = shouldSynchronize/;
+    if (fullscreenSearch.test(content)) {
+      content = content.replace(
+        /if \(isFullscreen\) (\{\s*\n\s*const sync = shouldSynchronize)/,
+        'if (false) $1'
+      );
+      console.log('  ✅ Patch 2/3: Disabled clearTerminal fullscreen path');
+      patchCount++;
+    } else if (fullscreenAlreadyPatched.test(content)) {
+      console.log('  ⏭️  Patch 2/3: clearTerminal path already disabled');
+    } else {
+      console.warn('  ⚠️  Patch 2/3: Could not find isFullscreen pattern — Ink version may have changed');
+    }
+
+    // --- Patch 3: Verify incrementalRendering passthrough ---
+    const incrementalPattern = 'incremental: options.incrementalRendering';
+    if (content.includes(incrementalPattern)) {
+      console.log('  ✅ Patch 3/3: incrementalRendering passthrough verified (no change needed)');
+    } else {
+      console.warn('  ⚠️  Patch 3/3: incrementalRendering passthrough not found — Ink version may have changed');
+    }
+
+    if (patchCount > 0) {
+      writeFileSync(inkJsPath, content, 'utf8');
+      console.log(`✅ Patched ink.js with ${patchCount} rendering fix(es) for scroll flicker`);
+      return true;
+    }
+
+    return false;
+  } catch (err) {
+    console.warn('⚠️  Failed to patch ink.js rendering:', err.message);
+    console.warn('    Scroll flicker may occur on Windows Terminal.');
+    return false;
+  }
+}
+
+// Run patch
+patchInkRendering();

package/templates/casting/Futurama.json

@@ -0,0 +1,10 @@
+[
+    "Fry",
+    "Leela",
+    "Bender",
+    "Farnsworth",
+    "Zoidberg",
+    "Amy",
+    "Zapp",
+    "Kif"
+]

package/templates/casting-policy.json

@@ -14,7 +14,8 @@
     "Breaking Bad",
     "Lost",
     "Marvel Cinematic Universe",
-    "DC Universe"
+    "DC Universe",
+    "Futurama"
   ],
   "universe_capacity": {
     "The Usual Suspects": 6,
@@ -30,6 +31,7 @@
     "Breaking Bad": 12,
     "Lost": 18,
     "Marvel Cinematic Universe": 25,
-    "DC Universe": 18
+    "DC Universe": 18,
+    "Futurama": 12
   }
 }

package/templates/casting-reference.md

@@ -0,0 +1,104 @@
+# Casting Reference
+
+On-demand reference for Squad's casting system. Loaded during Init Mode or when adding team members.
+
+## Universe Table
+
+| Universe | Capacity | Shape Tags | Resonance Signals |
+|---|---|---|---|
+| The Usual Suspects | 6 | small, noir, ensemble | crime, heist, mystery, deception |
+| Reservoir Dogs | 8 | small, noir, ensemble | crime, heist, tension, loyalty |
+| Alien | 8 | small, sci-fi, survival | space, isolation, threat, engineering |
+| Ocean's Eleven | 14 | medium, heist, ensemble | planning, coordination, roles, charm |
+| Arrested Development | 15 | medium, comedy, ensemble | dysfunction, business, family, satire |
+| Star Wars | 12 | medium, sci-fi, epic | conflict, mentorship, legacy, rebellion |
+| The Matrix | 10 | medium, sci-fi, cyberpunk | systems, reality, hacking, philosophy |
+| Firefly | 10 | medium, sci-fi, western | frontier, crew, independence, smuggling |
+| The Goonies | 8 | small, adventure, ensemble | exploration, treasure, kids, teamwork |
+| The Simpsons | 20 | large, comedy, ensemble | satire, community, family, absurdity |
+| Breaking Bad | 12 | medium, drama, tension | chemistry, transformation, consequence, power |
+| Lost | 18 | large, mystery, ensemble | survival, mystery, groups, leadership |
+| Marvel Cinematic Universe | 25 | large, action, ensemble | heroism, teamwork, powers, scale |
+| DC Universe | 18 | large, action, ensemble | justice, duality, powers, mythology |
+| Futurama | 12 | medium, sci-fi, comedy | future, robots, space, absurdity |
+
+**Total: 15 universes** — capacity range 6–25.
+
+## Selection Algorithm
+
+Universe selection is deterministic. Score each universe and pick the highest:
+
+```
+score = size_fit + shape_fit + resonance_fit + LRU
+```
+
+| Factor | Description |
+|---|---|
+| `size_fit` | How well the universe capacity matches the team size. Prefer universes where capacity ≥ agent_count with minimal waste. |
+| `shape_fit` | Match universe shape tags against the assignment shape derived from the project description. |
+| `resonance_fit` | Match universe resonance signals against session and repo context signals. |
+| `LRU` | Least-recently-used bonus — prefer universes not used in recent assignments (from `history.json`). |
+
+Same inputs → same choice (unless LRU changes between assignments).
+
+## Casting State File Schemas
+
+### policy.json
+
+Source template: `.squad/templates/casting-policy.json`
+Runtime location: `.squad/casting/policy.json`
+
+```json
+{
+  "casting_policy_version": "1.1",
+  "allowlist_universes": ["Universe Name", "..."],
+  "universe_capacity": {
+    "Universe Name": 10
+  }
+}
+```
+
+### registry.json
+
+Source template: `.squad/templates/casting-registry.json`
+Runtime location: `.squad/casting/registry.json`
+
+```json
+{
+  "agents": {
+    "agent-role-id": {
+      "persistent_name": "CharacterName",
+      "universe": "Universe Name",
+      "created_at": "ISO-8601",
+      "legacy_named": false,
+      "status": "active"
+    }
+  }
+}
+```
+
+### history.json
+
+Source template: `.squad/templates/casting-history.json`
+Runtime location: `.squad/casting/history.json`
+
+```json
+{
+  "universe_usage_history": [
+    {
+      "universe": "Universe Name",
+      "assignment_id": "unique-id",
+      "used_at": "ISO-8601"
+    }
+  ],
+  "assignment_cast_snapshots": {
+    "assignment-id": {
+      "universe": "Universe Name",
+      "agents": {
+        "role-id": "CharacterName"
+      },
+      "created_at": "ISO-8601"
+    }
+  }
+}
+```

package/templates/cooperative-rate-limiting.md

@@ -0,0 +1,229 @@
+# Cooperative Rate Limiting for Multi-Agent Deployments
+
+> Coordinate API quota across multiple Ralph instances to prevent cascading failures.
+
+## Problem
+
+The [circuit breaker template](ralph-circuit-breaker.md) handles single-instance rate limiting well. But when multiple Ralphs run across machines (or pods on K8s), each instance independently hits API limits:
+
+- **No coordination** — 5 Ralphs each think they have full API quota
+- **Thundering herd** — All Ralphs retry simultaneously after rate limit resets
+- **Priority inversion** — Low-priority work exhausts quota before critical work runs
+- **Reactive only** — Circuit opens AFTER 429, wasting the failed request
+
+## Solution: 6-Pattern Architecture
+
+These patterns layer on top of the existing circuit breaker. Each is independent — adopt one or all.
+
+### Pattern 1: Traffic Light (RAAS — Rate-Aware Agent Scheduling)
+
+Map GitHub API `X-RateLimit-Remaining` to traffic light states:
+
+| State | Remaining % | Behavior |
+|-------|------------|----------|
+| 🟢 GREEN | >20% | Normal operation |
+| 🟡 AMBER | 5–20% | Only P0 agents proceed |
+| 🔴 RED | <5% | Block all except emergency P0 |
+
+```typescript
+type TrafficLight = 'green' | 'amber' | 'red';
+
+function getTrafficLight(remaining: number, limit: number): TrafficLight {
+  const pct = remaining / limit;
+  if (pct > 0.20) return 'green';
+  if (pct > 0.05) return 'amber';
+  return 'red';
+}
+
+function shouldProceed(light: TrafficLight, agentPriority: number): boolean {
+  if (light === 'green') return true;
+  if (light === 'amber') return agentPriority === 0; // P0 only
+  return false; // RED — block all
+}
+```
+
+### Pattern 2: Cooperative Token Pool (CMARP)
+
+A shared JSON file (`~/.squad/rate-pool.json`) distributes API quota:
+
+```json
+{
+  "totalLimit": 5000,
+  "resetAt": "2026-03-22T20:00:00Z",
+  "allocations": {
+    "picard": { "priority": 0, "allocated": 2000, "used": 450, "leaseExpiry": "2026-03-22T19:55:00Z" },
+    "data": { "priority": 1, "allocated": 1750, "used": 200, "leaseExpiry": "2026-03-22T19:55:00Z" },
+    "ralph": { "priority": 2, "allocated": 1250, "used": 100, "leaseExpiry": "2026-03-22T19:55:00Z" }
+  }
+}
+```
+
+**Rules:**
+- P0 agents (Lead) get 40% of quota
+- P1 agents (specialists) get 35%
+- P2 agents (Ralph, Scribe) get 25%
+- Stale leases (>5 minutes without heartbeat) are auto-recovered
+- Each agent checks their remaining allocation before making API calls
+
+```typescript
+interface RatePoolAllocation {
+  priority: number;
+  allocated: number;
+  used: number;
+  leaseExpiry: string;
+}
+
+interface RatePool {
+  totalLimit: number;
+  resetAt: string;
+  allocations: Record<string, RatePoolAllocation>;
+}
+
+function canUseQuota(pool: RatePool, agentName: string): boolean {
+  const alloc = pool.allocations[agentName];
+  if (!alloc) return true; // Unknown agent — allow (graceful)
+  
+  // Reclaim stale leases from crashed agents
+  const now = new Date();
+  for (const [name, a] of Object.entries(pool.allocations)) {
+    if (new Date(a.leaseExpiry) < now && name !== agentName) {
+      a.allocated = 0; // Reclaim
+    }
+  }
+  
+  return alloc.used < alloc.allocated;
+}
+```
+
+### Pattern 3: Predictive Circuit Breaker (PCB)
+
+Opens the circuit BEFORE getting a 429 by predicting when quota will run out:
+
+```typescript
+interface RateSample {
+  timestamp: number;  // Date.now()
+  remaining: number;  // from X-RateLimit-Remaining header
+}
+
+class PredictiveCircuitBreaker {
+  private samples: RateSample[] = [];
+  private readonly maxSamples = 10;
+  private readonly warningThresholdSeconds = 120;
+
+  addSample(remaining: number): void {
+    this.samples.push({ timestamp: Date.now(), remaining });
+    if (this.samples.length > this.maxSamples) {
+      this.samples.shift();
+    }
+  }
+
+  /** Predict seconds until quota exhaustion using linear regression */
+  predictExhaustion(): number | null {
+    if (this.samples.length < 3) return null;
+
+    const n = this.samples.length;
+    const first = this.samples[0];
+    const last = this.samples[n - 1];
+    
+    const elapsedMs = last.timestamp - first.timestamp;
+    if (elapsedMs === 0) return null;
+    
+    const consumedPerMs = (first.remaining - last.remaining) / elapsedMs;
+    if (consumedPerMs <= 0) return null; // Not consuming — safe
+    
+    const msUntilExhausted = last.remaining / consumedPerMs;
+    return msUntilExhausted / 1000;
+  }
+
+  shouldOpen(): boolean {
+    const eta = this.predictExhaustion();
+    if (eta === null) return false;
+    return eta < this.warningThresholdSeconds;
+  }
+}
+```
+
+### Pattern 4: Priority Retry Windows (PWJG)
+
+Non-overlapping jitter windows prevent thundering herd:
+
+| Priority | Retry Window | Description |
+|----------|-------------|-------------|
+| P0 (Lead) | 500ms–5s | Recovers first |
+| P1 (Specialists) | 2s–30s | Moderate delay |
+| P2 (Ralph/Scribe) | 5s–60s | Most patient |
+
+```typescript
+function getRetryDelay(priority: number, attempt: number): number {
+  const windows: Record<number, [number, number]> = {
+    0: [500, 5000],     // P0: 500ms–5s
+    1: [2000, 30000],   // P1: 2s–30s
+    2: [5000, 60000],   // P2: 5s–60s
+  };
+  
+  const [min, max] = windows[priority] ?? windows[2];
+  const base = Math.min(min * Math.pow(2, attempt), max);
+  const jitter = Math.random() * base * 0.5;
+  return base + jitter;
+}
+```
+
+### Pattern 5: Resource Epoch Tracker (RET)
+
+Heartbeat-based lease system for multi-machine deployments:
+
+```typescript
+interface ResourceLease {
+  agent: string;
+  machine: string;
+  leaseStart: string;
+  leaseExpiry: string;  // Typically 5 minutes from now
+  allocated: number;
+}
+
+// Each agent renews its lease every 2 minutes
+// If lease expires (agent crashed), allocation is reclaimed
+```
+
+### Pattern 6: Cascade Dependency Detector (CDD)
+
+Track downstream failures and apply backpressure:
+
+```
+Agent A (rate limited) → Agent B (waiting for A) → Agent C (waiting for B)
+                         ↑ Backpressure signal: "don't start new work"
+```
+
+When a dependency is rate-limited, upstream agents should pause new work rather than queuing requests that will fail.
+
+## Kubernetes Integration
+
+On K8s, cooperative rate limiting can use KEDA to scale pods based on API quota:
+
+```yaml
+apiVersion: keda.sh/v1alpha1
+kind: ScaledObject
+spec:
+  scaleTargetRef:
+    name: ralph-deployment
+  triggers:
+  - type: external
+    metadata:
+      scalerAddress: keda-copilot-scaler:6000
+      # Scaler returns 0 when rate limited → pods scale to zero
+```
+
+See [keda-copilot-scaler](https://github.com/tamirdresher/keda-copilot-scaler) for a complete implementation.
+
+## Quick Start
+
+1. **Minimum viable:** Adopt Pattern 1 (Traffic Light) — read `X-RateLimit-Remaining` from API responses
+2. **Multi-machine:** Add Pattern 2 (Cooperative Pool) — shared `rate-pool.json`
+3. **Production:** Add Pattern 3 (Predictive CB) — prevent 429s entirely
+4. **Kubernetes:** Add KEDA scaler for automatic pod scaling
+
+## References
+
+- [Circuit Breaker Template](ralph-circuit-breaker.md) — Foundation patterns
+- [Squad on AKS](https://github.com/tamirdresher/squad-on-aks) — Production K8s deployment
+- [KEDA Copilot Scaler](https://github.com/tamirdresher/keda-copilot-scaler) — Custom KEDA external scaler