@bradygaster/squad-sdk 0.9.0 → 0.9.1

package/README.md

@@ -1,296 +1,296 @@
-# @bradygaster/squad-sdk
-
-**Programmable multi-agent runtime for GitHub Copilot.** Build AI teams that persist, learn, and coordinate — with real governance, not vibes.
-
-[![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
-```
-
----
-
-## 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#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
-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.
-
----
-
-## Event-Driven Monitoring
-
-Ralph is the built-in work monitor — a persistent agent session that subscribes to everything happening on the team.
-
-```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();
-```
-
-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()` | 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` | `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 | Core async execution, event streaming, i18n |
-| `cli` | `checkForUpdate()`, `performUpgrade()` | SDK version management and update checking |
-| `marketplace` | Plugin marketplace | Discover and manage plugins |
-
----
-
-## Requirements
-
-- **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](https://github.com/bradygaster/squad)
-- **CLI package:** [@bradygaster/squad-cli](https://www.npmjs.com/package/@bradygaster/squad-cli)
-- **Issues:** [github.com/bradygaster/squad/issues](https://github.com/bradygaster/squad/issues)
-
----
-
-## License
-
-MIT
+# @bradygaster/squad-sdk
+
+**Programmable multi-agent runtime for GitHub Copilot.** Build AI teams that persist, learn, and coordinate — with real governance, not vibes.
+
+[![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
+```
+
+---
+
+## 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#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
+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.
+
+---
+
+## Event-Driven Monitoring
+
+Ralph is the built-in work monitor — a persistent agent session that subscribes to everything happening on the team.
+
+```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();
+```
+
+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()` | 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` | `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 | Core async execution, event streaming, i18n |
+| `cli` | `checkForUpdate()`, `performUpgrade()` | SDK version management and update checking |
+| `marketplace` | Plugin marketplace | Discover and manage plugins |
+
+---
+
+## Requirements
+
+- **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](https://github.com/bradygaster/squad)
+- **CLI package:** [@bradygaster/squad-cli](https://www.npmjs.com/package/@bradygaster/squad-cli)
+- **Issues:** [github.com/bradygaster/squad/issues](https://github.com/bradygaster/squad/issues)
+
+---
+
+## License
+
+MIT

package/dist/agents/history-shadow.js

@@ -101,36 +101,36 @@ export async function createHistoryShadow(teamRoot, agentName, initialContext) {
         }
         // Create initial shadow content
         const timestamp = new Date().toISOString();
-        const initialContent = `# ${capitalize(agentName)} — Session History
-
-> **Shadow History**: Project-specific learnings for ${agentName} in this repository.
-> This file is separate from the agent's portable charter and captures session context.
-
-**Created:** ${timestamp}
-
-## Context
-
-${initialContext || 'No initial context provided.'}
-
-## Learnings
-
-<!-- Add project-specific learnings here -->
-
-## Decisions
-
-<!-- Record key decisions made by this agent -->
-
-## Patterns
-
-<!-- Note recurring patterns observed -->
-
-## Issues
-
-<!-- Track problems encountered and resolutions -->
-
-## References
-
-<!-- Important files, documentation, or external resources -->
+        const initialContent = `# ${capitalize(agentName)} — Session History
+
+> **Shadow History**: Project-specific learnings for ${agentName} in this repository.
+> This file is separate from the agent's portable charter and captures session context.
+
+**Created:** ${timestamp}
+
+## Context
+
+${initialContext || 'No initial context provided.'}
+
+## Learnings
+
+<!-- Add project-specific learnings here -->
+
+## Decisions
+
+<!-- Record key decisions made by this agent -->
+
+## Patterns
+
+<!-- Note recurring patterns observed -->
+
+## Issues
+
+<!-- Track problems encountered and resolutions -->
+
+## References
+
+<!-- Important files, documentation, or external resources -->
 `;
         await fs.writeFile(shadowPath, initialContent, 'utf-8');
         return shadowPath;