@bradygaster/squad-sdk 0.6.1 → 0.7.0

package/README.md

@@ -1,50 +1,296 @@
 # @bradygaster/squad-sdk
 
-Programmable multi-agent runtime for GitHub Copilot. Resolves squad configuration, loads agent teams, and manages the SDK lifecycle.
+**Programmable multi-agent runtime for GitHub Copilot.** Build AI teams that persist, learn, and coordinate — with real governance, not vibes.
 
-## Installation
+[![Status](https://img.shields.io/badge/status-production-brightgreen)](#requirements)
+[![Node](https://img.shields.io/badge/node-%E2%89%A520-green)](#requirements)
+[![ESM](https://img.shields.io/badge/module-ESM--only-blue)](#requirements)
+
+---
+
+## Install
 
 ```bash
 npm install @bradygaster/squad-sdk
 ```
 
-## Quick Example
+---
+
+## What Makes This Different
+
+Most multi-agent setups are prompt engineering. You write a wall of text describing who each agent is, what they can do, and hope the model follows the rules. It works — until it doesn't. Agents ignore routing. They write files they shouldn't. They leak data. There's no enforcement, just suggestions.
+
+Squad's SDK moves orchestration out of prompts and into code:
+
+**Prompt-only orchestration** stuffs everything into a single context window. The coordinator is text. Agents read it, interpret it, maybe follow it.
+
+```
+Prompt says:
+"If the agent is Backend, route auth tasks to it."
+Agent reads it (consumes tokens), decides what to do (might ignore it).
+```
+
+**SDK orchestration** compiles rules into typed functions. Sessions are objects. Routing is deterministic. Tools are validated before execution.
+
+```typescript
+Router.matchRoute(message) → { agent: 'Backend', priority: 'high' }
+// TypeScript knows exactly which agent runs, with what permissions.
+// HookPipeline runs file-write guards BEFORE the tool executes.
+// No interpretation. No ambiguity. Just code.
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│  Your Code (TypeScript)                     │
+│  - createSession(), spawnParallel()         │
+│  - SquadClient, EventBus, HookPipeline      │
+└─────────────────────────────────────────────┘
+           ↓
+┌─────────────────────────────────────────────┐
+│  Agent Orchestration Runtime                │
+│  - Router (matchRoute, compileRoutingRules) │
+│  - Charter Compiler (permissions, voice)    │
+│  - Tool Registry (squad_route, etc.)        │
+│  - Hook Pipeline (governance enforcement)   │
+└─────────────────────────────────────────────┘
+           ↓
+┌─────────────────────────────────────────────┐
+│  Session Pool + Event Bus                   │
+│  - Each agent gets a persistent session     │
+│  - Cross-session event pub/sub               │
+│  - Crash recovery via session state         │
+└─────────────────────────────────────────────┘
+           ↓
+┌─────────────────────────────────────────────┐
+│  @github/copilot-sdk                        │
+│  - Real-time agent streaming                │
+│  - Tool execution                           │
+└─────────────────────────────────────────────┘
+```
+
+Your code sits at the top. The runtime handles routing, permissions, and governance. Sessions are persistent and recoverable. Everything runs on top of the official Copilot SDK.
+
+---
+
+## Custom Tools
+
+Five tools let agents coordinate without calling you back. Here are the three you'll reach for first.
+
+### `squad_route` — Hand off work between agents
+
+```typescript
+const tool = toolRegistry.getTool('squad_route');
+await tool.handler({
+  targetAgent: 'McManus',
+  task: 'Write a blog post on the new casting system',
+  priority: 'high',
+  context: 'Feature launches next week',
+});
+```
+
+The lead routes a task to DevRel. A new session is created, context is passed, and the task is queued with priority. No human in the loop.
+
+### `squad_decide` — Record a team decision
+
+```typescript
+await tool.handler({
+  author: 'Keaton',
+  summary: 'Use PostgreSQL, not MongoDB',
+  body: 'Chose PostgreSQL for: (1) transactions, (2) team expertise, (3) JSONB flexibility.',
+  references: ['architecture-spike'],
+});
+```
+
+Writes to the shared decision log. Every agent reads decisions before working — one call propagates context to the entire team.
+
+### `squad_memory` — Teach an agent something permanent
+
+```typescript
+await tool.handler({
+  agent: 'Frontend',
+  section: 'learnings',
+  content: 'Project uses Tailwind v4 with dark mode plugin. Config at .styles/theme.config.ts',
+});
+```
+
+Agents learn as they work. Next session, Frontend reads this and knows immediately. No context hunting, no re-explaining.
+
+> Two more tools — `squad_status` (query the session pool) and `squad_skill` (read/write compressed learnings) — round out the coordination layer. See the [full docs](https://github.com/bradygaster/squad-pr#the-custom-tools) for details.
+
+---
+
+## Hook Pipeline
+
+Rules don't live in prompts. They run as code, before tools execute.
+
+### File-Write Guards
+
+```typescript
+const pipeline = new HookPipeline({
+  allowedWritePaths: ['src/**/*.ts', '.squad/**', 'docs/**'],
+});
+
+// An agent tries to write to /etc/passwd
+// → Blocked. "File write blocked: '/etc/passwd' does not match allowed paths"
+```
+
+No agent — compromised or confused — can write outside your safe zones. Not because you asked nicely in the prompt. Because code won't let them.
+
+### PII Scrubbing
+
+```typescript
+const pipeline = new HookPipeline({
+  scrubPii: true,
+});
+
+// Agent logs: "contact brady@example.com about deploy"
+// Output becomes: "contact [EMAIL_REDACTED] about deploy"
+```
+
+Sensitive data never escapes. Automatic, invisible to the agent, applied to every tool output.
+
+### Reviewer Lockout
+
+```typescript
+const lockout = pipeline.getReviewerLockout();
+lockout.lockout('src/auth.ts', 'Backend');
+
+// Backend tries to re-write auth.ts after a review rejection
+// → Blocked. "Agent 'Backend' is locked out of artifact 'src/auth.ts'"
+```
+
+When a reviewer says "no," it sticks. The original author can't sneak a fix in. Protocol enforced by code, not convention.
+
+### Ask-User Rate Limiter
+
+```typescript
+const pipeline = new HookPipeline({
+  maxAskUserPerSession: 3,
+});
+
+// Fourth attempt to prompt the user → Blocked.
+// "ask_user rate limit exceeded: 3/3 calls used. Proceed without user input."
+```
+
+Agents don't stall waiting for you. They decide or move on.
+
+---
+
+## Persistent Sessions & Crash Recovery
+
+Sessions aren't ephemeral. They're durable objects that survive failures.
+
+```typescript
+const session = await client.createSession({
+  agentName: 'Backend',
+  task: 'Implement user auth endpoints',
+  persistPath: '.squad/sessions/backend-auth-001.json',
+});
+
+// Agent dies mid-work — network hiccup, model timeout, anything.
+// Later:
+
+const resumed = await client.resumeSession(
+  '.squad/sessions/backend-auth-001.json'
+);
+
+// Backend wakes up knowing:
+// - What the task was
+// - What it already wrote
+// - Where it left off
+// No repetition, no lost context.
+```
+
+---
+
+## The Casting Engine
+
+Agents aren't `role-1`, `role-2`. They have names, personalities, and persistent identities across sessions. The casting engine assigns them automatically from a thematic universe.
 
 ```typescript
-import { resolveSquad, loadConfig } from '@bradygaster/squad-sdk';
+const casting = new CastingEngine({
+  universe: 'usual-suspects',
+  agentCount: 5,
+});
+
+const cast = casting.castTeam({
+  roles: ['lead', 'frontend', 'backend', 'tester', 'scribe'],
+});
+// → [
+//   { role: 'lead', agentName: 'Keaton' },
+//   { role: 'frontend', agentName: 'McManus' },
+//   { role: 'backend', agentName: 'Verbal' },
+//   { role: 'tester', agentName: 'Fenster' },
+//   { role: 'scribe', agentName: 'Kobayashi' },
+// ]
+```
+
+Names are memorable ("Keaton handles routing"), persistent (same name every session), and extensible (add a sixth agent — the casting engine picks the next name from the universe). You build a relationship with your agents over time.
+
+---
 
-// Find the .squad/ directory by walking up from cwd
-const squadDir = await resolveSquad();
+## Event-Driven Monitoring
 
-// Load squad configuration
-const config = await loadConfig();
+Ralph is the built-in work monitor — a persistent agent session that subscribes to everything happening on the team.
 
-console.log('Loaded team:', config.team.name);
+```typescript
+const ralph = new RalphMonitor({
+  teamRoot: '.squad',
+  healthCheckInterval: 30000,
+  statePath: '.squad/ralph-state.json',
+});
+
+ralph.subscribe('agent:task-complete', (event) => {
+  console.log(`✅ ${event.agentName} finished: ${event.task}`);
+});
+
+ralph.subscribe('agent:error', (event) => {
+  console.log(`❌ ${event.agentName} failed: ${event.error}`);
+});
+
+await ralph.start();
 ```
 
-## API Overview
+When agents complete work, record decisions, or hit errors — Ralph knows. If an agent crashes, Ralph remembers where it left off.
+
+---
+
+## API Reference
 
 | Module | Key Exports | Purpose |
 |--------|------------|---------|
-| `resolution` | `resolveSquad()`, `resolveGlobalSquadPath()`, `ensureSquadPath()` | Walk-up to find `.squad/` directory; platform-specific global squad path; validate paths stay inside `.squad/` |
+| `resolution` | `resolveSquad()`, `resolveGlobalSquadPath()`, `ensureSquadPath()` | Find `.squad/` directory; platform-specific global path; path validation |
 | `config` | `loadConfig()`, `loadConfigSync()` | Load and parse squad configuration from disk |
 | `agents` | Agent onboarding utilities | Register and initialize agents; manage team discovery |
-| `casting` | Casting engine | Universe selection, name allocation, registry management |
-| `skills` | Skills system | Load SKILL.md lifecycle, manage confidence levels |
+| `casting` | `CastingEngine` | Universe selection, name allocation, persistent registry |
+| `skills` | Skills system | SKILL.md lifecycle, confidence levels |
 | `coordinator` | `selectResponseTier()`, `getTier()` | Route requests to Direct/Lightweight/Standard/Full tiers |
-| `runtime` | Streaming pipeline, cost tracker, telemetry, offline mode | Core async execution, event streaming, i18n support |
+| `runtime` | Streaming pipeline, cost tracker, telemetry | Core async execution, event streaming, i18n |
 | `cli` | `checkForUpdate()`, `performUpgrade()` | SDK version management and update checking |
-| `cli` | Output helpers, GitHub utilities | `success()`, `error()`, `warn()`, `info()`, GitHub issue management |
-| `marketplace` | Plugin marketplace management | Discover and manage plugins |
+| `marketplace` | Plugin marketplace | Discover and manage plugins |
+
+---
 
 ## Requirements
 
-- **Node.js:** ≥20
-- **TypeScript:** ≥5.0 (for type definitions)
-- **Module system:** ESM-only (no CommonJS)
+- **Node.js** ≥ 20.0.0
+- **TypeScript** ≥ 5.0
+- **ESM-only** — no CommonJS. Set `"type": "module"` in your `package.json`.
+
+---
 
 ## Links
 
 - **Repository:** [github.com/bradygaster/squad-pr](https://github.com/bradygaster/squad-pr)
+- **CLI package:** [@bradygaster/squad-cli](https://www.npmjs.com/package/@bradygaster/squad-cli)
 - **Issues:** [github.com/bradygaster/squad-pr/issues](https://github.com/bradygaster/squad-pr/issues)
-- **Main README:** [github.com/bradygaster/squad-pr#readme](https://github.com/bradygaster/squad-pr#readme)
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bradygaster/squad-sdk",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Squad SDK — Programmable multi-agent runtime for GitHub Copilot",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,6 +9,30 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./parsers": {
+      "types": "./dist/parsers.d.ts",
+      "import": "./dist/parsers.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js"
+    },
+    "./skills": {
+      "types": "./dist/skills/index.d.ts",
+      "import": "./dist/skills/index.js"
+    },
+    "./agents": {
+      "types": "./dist/agents/index.d.ts",
+      "import": "./dist/agents/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "import": "./dist/cli/index.js"
     }
   },
   "files": [