{"_id":"@dreampunchboy/scuad-sdk","name":"@dreampunchboy/scuad-sdk","dist-tags":{"latest":"0.9.1"},"versions":{"0.9.1":{"name":"@dreampunchboy/scuad-sdk","version":"0.9.1","description":"Squad SDK — Programmable multi-agent runtime for GitHub Copilot","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"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"},"./config/agent-source":{"types":"./dist/config/agent-source.d.ts","import":"./dist/config/agent-source.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"},"./agents/personal":{"types":"./dist/agents/personal.d.ts","import":"./dist/agents/personal.js"},"./adapter":{"types":"./dist/adapter/types.d.ts","import":"./dist/adapter/types.js"},"./client":{"types":"./dist/client/index.d.ts","import":"./dist/client/index.js"},"./coordinator":{"types":"./dist/coordinator/index.d.ts","import":"./dist/coordinator/index.js"},"./hooks":{"types":"./dist/hooks/index.d.ts","import":"./dist/hooks/index.js"},"./tools":{"types":"./dist/tools/index.d.ts","import":"./dist/tools/index.js"},"./runtime":{"types":"./dist/runtime/config.d.ts","import":"./dist/runtime/config.js"},"./runtime/streaming":{"types":"./dist/runtime/streaming.d.ts","import":"./dist/runtime/streaming.js"},"./marketplace":{"types":"./dist/marketplace/index.d.ts","import":"./dist/marketplace/index.js"},"./build":{"types":"./dist/build/index.d.ts","import":"./dist/build/index.js"},"./sharing":{"types":"./dist/sharing/index.d.ts","import":"./dist/sharing/index.js"},"./ralph":{"types":"./dist/ralph/index.d.ts","import":"./dist/ralph/index.js"},"./ralph/triage":{"types":"./dist/ralph/triage.d.ts","import":"./dist/ralph/triage.js"},"./ralph/capabilities":{"types":"./dist/ralph/capabilities.d.ts","import":"./dist/ralph/capabilities.js"},"./ralph/rate-limiting":{"types":"./dist/ralph/rate-limiting.d.ts","import":"./dist/ralph/rate-limiting.js"},"./casting":{"types":"./dist/casting/index.d.ts","import":"./dist/casting/index.js"},"./resolution":{"types":"./dist/resolution.d.ts","import":"./dist/resolution.js"},"./adapter/errors":{"types":"./dist/adapter/errors.d.ts","import":"./dist/adapter/errors.js"},"./config/migrations":{"types":"./dist/config/migrations/index.d.ts","import":"./dist/config/migrations/index.js"},"./runtime/event-bus":{"types":"./dist/runtime/event-bus.d.ts","import":"./dist/runtime/event-bus.js"},"./runtime/benchmarks":{"types":"./dist/runtime/benchmarks.d.ts","import":"./dist/runtime/benchmarks.js"},"./runtime/i18n":{"types":"./dist/runtime/i18n.d.ts","import":"./dist/runtime/i18n.js"},"./runtime/telemetry":{"types":"./dist/runtime/telemetry.d.ts","import":"./dist/runtime/telemetry.js"},"./runtime/offline":{"types":"./dist/runtime/offline.d.ts","import":"./dist/runtime/offline.js"},"./runtime/cost-tracker":{"types":"./dist/runtime/cost-tracker.d.ts","import":"./dist/runtime/cost-tracker.js"},"./runtime/otel-api":{"types":"./dist/runtime/otel-api.d.ts","import":"./dist/runtime/otel-api.js"},"./runtime/otel":{"types":"./dist/runtime/otel.d.ts","import":"./dist/runtime/otel.js"},"./runtime/otel-bridge":{"types":"./dist/runtime/otel-bridge.d.ts","import":"./dist/runtime/otel-bridge.js"},"./runtime/otel-metrics":{"types":"./dist/runtime/otel-metrics.d.ts","import":"./dist/runtime/otel-metrics.js"},"./runtime/squad-observer":{"types":"./dist/runtime/squad-observer.d.ts","import":"./dist/runtime/squad-observer.js"},"./runtime/event-payloads":{"types":"./dist/runtime/event-payloads.d.ts","import":"./dist/runtime/event-payloads.js"},"./runtime/event-bus-ws-bridge":{"types":"./dist/runtime/event-bus-ws-bridge.d.ts","import":"./dist/runtime/event-bus-ws-bridge.js"},"./runtime/scheduler":{"types":"./dist/runtime/scheduler.d.ts","import":"./dist/runtime/scheduler.js"},"./runtime/constants":{"types":"./dist/runtime/constants.d.ts","import":"./dist/runtime/constants.js"},"./builders":{"types":"./dist/builders/index.d.ts","import":"./dist/builders/index.js"},"./runtime/cross-squad":{"types":"./dist/runtime/cross-squad.d.ts","import":"./dist/runtime/cross-squad.js"},"./runtime/otel-init":{"types":"./dist/runtime/otel-init.d.ts","import":"./dist/runtime/otel-init.js"},"./config/models":{"types":"./dist/config/models.d.ts","import":"./dist/config/models.js"},"./storage":{"types":"./dist/storage/index.d.ts","import":"./dist/storage/index.js"},"./platform":{"types":"./dist/platform/index.d.ts","import":"./dist/platform/index.js"},"./remote":{"types":"./dist/remote/index.d.ts","import":"./dist/remote/index.js"},"./roles":{"types":"./dist/roles/index.d.ts","import":"./dist/roles/index.js"},"./state":{"types":"./dist/state/index.d.ts","import":"./dist/state/index.js"},"./streams":{"types":"./dist/streams/index.d.ts","import":"./dist/streams/index.js"},"./upstream":{"types":"./dist/upstream/index.d.ts","import":"./dist/upstream/index.js"}},"scripts":{"prepublishOnly":"npm run build","build":"tsc -p tsconfig.json"},"engines":{"node":">=22.5.0"},"dependencies":{"@github/copilot-sdk":"^0.1.32","vscode-jsonrpc":"^8.2.1"},"optionalDependencies":{"@opentelemetry/api":"^1.9.0","@opentelemetry/exporter-metrics-otlp-grpc":"^0.57.2","@opentelemetry/exporter-trace-otlp-grpc":"^0.57.2","@opentelemetry/resources":"^1.30.0","@opentelemetry/sdk-metrics":"^1.30.0","@opentelemetry/sdk-node":"^0.57.2","@opentelemetry/sdk-trace-base":"^1.30.0","@opentelemetry/sdk-trace-node":"^1.30.0","@opentelemetry/semantic-conventions":"^1.28.0","sql.js":"^1.14.1","ws":"^8.18.0"},"devDependencies":{"@types/node":"^22.0.0","@types/sql.js":"^1.4.10","@types/ws":"^8.5.13","typedoc":"~0.28.18","typedoc-plugin-markdown":"~4.11.0","typescript":"^5.7.0"},"keywords":["copilot","multi-agent","squad","sdk"],"license":"MIT","homepage":"https://github.com/Dreampunch/scuad#readme","bugs":{"url":"https://github.com/Dreampunch/scuad/issues"},"repository":{"type":"git","url":"git+https://github.com/Dreampunch/scuad.git","directory":"packages/squad-sdk"},"_id":"@dreampunchboy/scuad-sdk@0.9.1","gitHead":"b846c1d631b4a832a19affce864d3b0d8658770a","_nodeVersion":"24.4.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-wFKUgPRX+sinkXqf+Vv5VSym8ntfoxEXIvXcxGdupveibSbpZt0J/S1hGvktkln/lE2Yr4KiV4FfErauRmNh7g==","shasum":"fe922eb4a26f2cd3cf015a28d884933d41e0929c","tarball":"https://registry.npmjs.org/@dreampunchboy/scuad-sdk/-/scuad-sdk-0.9.1.tgz","fileCount":680,"unpackedSize":2852810,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDQuCo8H8TlbpEk3WQcyz47qt5PYdzHY7pc0bIp9z7RnAIgU8RQmVUvyz+pGjd6hLlnpYmUC3ewzTjonr5Gwl91kDM="}]},"_npmUser":{"name":"dreampunchboy","email":"phillip@vancoller.com"},"directories":{},"maintainers":[{"name":"dreampunchboy","email":"phillip@vancoller.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/scuad-sdk_0.9.1_1775885154851_0.053356368258193454"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-11T05:25:54.699Z","0.9.1":"2026-04-11T05:25:55.006Z","modified":"2026-04-11T05:25:55.249Z"},"maintainers":[{"name":"dreampunchboy","email":"phillip@vancoller.com"}],"description":"Squad SDK — Programmable multi-agent runtime for GitHub Copilot","homepage":"https://github.com/Dreampunch/scuad#readme","keywords":["copilot","multi-agent","squad","sdk"],"repository":{"type":"git","url":"git+https://github.com/Dreampunch/scuad.git","directory":"packages/squad-sdk"},"bugs":{"url":"https://github.com/Dreampunch/scuad/issues"},"license":"MIT","readme":"# @dreampunchboy/scuad-sdk\n\n**Programmable multi-agent runtime for GitHub Copilot.** Build AI teams that persist, learn, and coordinate — with real governance, not vibes.\n\n[![Status](https://img.shields.io/badge/status-production-brightgreen)](#requirements)\n[![Node](https://img.shields.io/badge/node-%E2%89%A520-green)](#requirements)\n[![ESM](https://img.shields.io/badge/module-ESM--only-blue)](#requirements)\n\n---\n\n## Install\n\n```bash\nnpm install @dreampunchboy/scuad-sdk\n```\n\n---\n\n## What Makes This Different\n\nMost 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.\n\nSquad's SDK moves orchestration out of prompts and into code:\n\n**Prompt-only orchestration** stuffs everything into a single context window. The coordinator is text. Agents read it, interpret it, maybe follow it.\n\n```\nPrompt says:\n\"If the agent is Backend, route auth tasks to it.\"\nAgent reads it (consumes tokens), decides what to do (might ignore it).\n```\n\n**SDK orchestration** compiles rules into typed functions. Sessions are objects. Routing is deterministic. Tools are validated before execution.\n\n```typescript\nRouter.matchRoute(message) → { agent: 'Backend', priority: 'high' }\n// TypeScript knows exactly which agent runs, with what permissions.\n// HookPipeline runs file-write guards BEFORE the tool executes.\n// No interpretation. No ambiguity. Just code.\n```\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────┐\n│  Your Code (TypeScript)                     │\n│  - createSession(), spawnParallel()         │\n│  - SquadClient, EventBus, HookPipeline      │\n└─────────────────────────────────────────────┘\n           ↓\n┌─────────────────────────────────────────────┐\n│  Agent Orchestration Runtime                │\n│  - Router (matchRoute, compileRoutingRules) │\n│  - Charter Compiler (permissions, voice)    │\n│  - Tool Registry (squad_route, etc.)        │\n│  - Hook Pipeline (governance enforcement)   │\n└─────────────────────────────────────────────┘\n           ↓\n┌─────────────────────────────────────────────┐\n│  Session Pool + Event Bus                   │\n│  - Each agent gets a persistent session     │\n│  - Cross-session event pub/sub               │\n│  - Crash recovery via session state         │\n└─────────────────────────────────────────────┘\n           ↓\n┌─────────────────────────────────────────────┐\n│  @github/copilot-sdk                        │\n│  - Real-time agent streaming                │\n│  - Tool execution                           │\n└─────────────────────────────────────────────┘\n```\n\nYour 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.\n\n---\n\n## Custom Tools\n\nFive tools let agents coordinate without calling you back. Here are the three you'll reach for first.\n\n### `squad_route` — Hand off work between agents\n\n```typescript\nconst tool = toolRegistry.getTool('squad_route');\nawait tool.handler({\n  targetAgent: 'McManus',\n  task: 'Write a blog post on the new casting system',\n  priority: 'high',\n  context: 'Feature launches next week',\n});\n```\n\nThe 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.\n\n### `squad_decide` — Record a team decision\n\n```typescript\nawait tool.handler({\n  author: 'Keaton',\n  summary: 'Use PostgreSQL, not MongoDB',\n  body: 'Chose PostgreSQL for: (1) transactions, (2) team expertise, (3) JSONB flexibility.',\n  references: ['architecture-spike'],\n});\n```\n\nWrites to the shared decision log. Every agent reads decisions before working — one call propagates context to the entire team.\n\n### `squad_memory` — Teach an agent something permanent\n\n```typescript\nawait tool.handler({\n  agent: 'Frontend',\n  section: 'learnings',\n  content: 'Project uses Tailwind v4 with dark mode plugin. Config at .styles/theme.config.ts',\n});\n```\n\nAgents learn as they work. Next session, Frontend reads this and knows immediately. No context hunting, no re-explaining.\n\n> 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.\n\n---\n\n## Hook Pipeline\n\nRules don't live in prompts. They run as code, before tools execute.\n\n### File-Write Guards\n\n```typescript\nconst pipeline = new HookPipeline({\n  allowedWritePaths: ['src/**/*.ts', '.squad/**', 'docs/**'],\n});\n\n// An agent tries to write to /etc/passwd\n// → Blocked. \"File write blocked: '/etc/passwd' does not match allowed paths\"\n```\n\nNo agent — compromised or confused — can write outside your safe zones. Not because you asked nicely in the prompt. Because code won't let them.\n\n### PII Scrubbing\n\n```typescript\nconst pipeline = new HookPipeline({\n  scrubPii: true,\n});\n\n// Agent logs: \"contact brady@example.com about deploy\"\n// Output becomes: \"contact [EMAIL_REDACTED] about deploy\"\n```\n\nSensitive data never escapes. Automatic, invisible to the agent, applied to every tool output.\n\n### Reviewer Lockout\n\n```typescript\nconst lockout = pipeline.getReviewerLockout();\nlockout.lockout('src/auth.ts', 'Backend');\n\n// Backend tries to re-write auth.ts after a review rejection\n// → Blocked. \"Agent 'Backend' is locked out of artifact 'src/auth.ts'\"\n```\n\nWhen a reviewer says \"no,\" it sticks. The original author can't sneak a fix in. Protocol enforced by code, not convention.\n\n### Ask-User Rate Limiter\n\n```typescript\nconst pipeline = new HookPipeline({\n  maxAskUserPerSession: 3,\n});\n\n// Fourth attempt to prompt the user → Blocked.\n// \"ask_user rate limit exceeded: 3/3 calls used. Proceed without user input.\"\n```\n\nAgents don't stall waiting for you. They decide or move on.\n\n---\n\n## Persistent Sessions & Crash Recovery\n\nSessions aren't ephemeral. They're durable objects that survive failures.\n\n```typescript\nconst session = await client.createSession({\n  agentName: 'Backend',\n  task: 'Implement user auth endpoints',\n  persistPath: '.squad/sessions/backend-auth-001.json',\n});\n\n// Agent dies mid-work — network hiccup, model timeout, anything.\n// Later:\n\nconst resumed = await client.resumeSession(\n  '.squad/sessions/backend-auth-001.json'\n);\n\n// Backend wakes up knowing:\n// - What the task was\n// - What it already wrote\n// - Where it left off\n// No repetition, no lost context.\n```\n\n---\n\n## Storage Abstraction\n\nSquad separates I/O from business logic. All persistent storage — sessions, state, decisions, histories — flows through a pluggable `StorageProvider` interface. Swap the backend (filesystem, database, cloud) without touching orchestration code.\n\n### Built-in Providers\n\n| Provider | Use When |\n|----------|----------|\n| `FSStorageProvider` | Running on Node.js. Stores everything on disk. |\n| `InMemoryStorageProvider` | Writing unit tests or running ephemeral sessions. |\n| `SQLiteStorageProvider` | Need a single portable database file. Works on all platforms (runs on WASM). |\n\n### Build Your Own\n\nImplement the `StorageProvider` interface:\n\n```typescript\nimport type { StorageProvider } from '@dreampunchboy/scuad-sdk';\n\nexport class MyCloudStorageProvider implements StorageProvider {\n  async read(filePath: string): Promise<string | undefined> {\n    // Fetch from Azure Blob, S3, or your service\n    try {\n      return await this.client.getBlob(filePath);\n    } catch (e) {\n      if (e.code === 'NotFound') return undefined;\n      throw e;\n    }\n  }\n\n  async write(filePath: string, data: string): Promise<void> {\n    // Store to cloud\n    await this.client.putBlob(filePath, data);\n  }\n\n  // Implement remaining methods: append, exists, list, delete, deleteDir, isDirectory, mkdir, rename, copy, stat\n  // + sync variants (deprecated in Wave 2)\n}\n```\n\nSee `storage-provider-azure` and `storage-provider-sqlite` samples for complete implementations.\n\n---\n\n## The Casting Engine\n\nAgents 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.\n\n```typescript\nconst casting = new CastingEngine({\n  universe: 'usual-suspects',\n  agentCount: 5,\n});\n\nconst cast = casting.castTeam({\n  roles: ['lead', 'frontend', 'backend', 'tester', 'scribe'],\n});\n// → [\n//   { role: 'lead', agentName: 'Keaton' },\n//   { role: 'frontend', agentName: 'McManus' },\n//   { role: 'backend', agentName: 'Verbal' },\n//   { role: 'tester', agentName: 'Fenster' },\n//   { role: 'scribe', agentName: 'Kobayashi' },\n// ]\n```\n\nNames 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.\n\n---\n\n## Event-Driven Monitoring\n\nRalph is the built-in work monitor — a persistent agent session that subscribes to everything happening on the team.\n\n```typescript\nconst ralph = new RalphMonitor({\n  teamRoot: '.squad',\n  healthCheckInterval: 30000,\n  statePath: '.squad/ralph-state.json',\n});\n\nralph.subscribe('agent:task-complete', (event) => {\n  console.log(`✅ ${event.agentName} finished: ${event.task}`);\n});\n\nralph.subscribe('agent:error', (event) => {\n  console.log(`❌ ${event.agentName} failed: ${event.error}`);\n});\n\nawait ralph.start();\n```\n\nWhen agents complete work, record decisions, or hit errors — Ralph knows. If an agent crashes, Ralph remembers where it left off.\n\n---\n\n## API Reference\n\n| Module | Key Exports | Purpose |\n|--------|------------|---------|\n| `resolution` | `resolveSquad()`, `resolveGlobalSquadPath()`, `ensureSquadPath()` | Find `.squad/` directory; platform-specific global path; path validation |\n| `config` | `loadConfig()`, `loadConfigSync()` | Load and parse squad configuration from disk |\n| `agents` | Agent onboarding utilities | Register and initialize agents; manage team discovery |\n| `casting` | `CastingEngine` | Universe selection, name allocation, persistent registry |\n| `skills` | Skills system | SKILL.md lifecycle, confidence levels |\n| `coordinator` | `selectResponseTier()`, `getTier()` | Route requests to Direct/Lightweight/Standard/Full tiers |\n| `runtime` | Streaming pipeline, cost tracker, telemetry | Core async execution, event streaming, i18n |\n| `cli` | `checkForUpdate()`, `performUpgrade()` | SDK version management and update checking |\n| `marketplace` | Plugin marketplace | Discover and manage plugins |\n\n---\n\n## Requirements\n\n- **Node.js** ≥ 20.0.0\n- **TypeScript** ≥ 5.0\n- **ESM-only** — no CommonJS. Set `\"type\": \"module\"` in your `package.json`.\n\n---\n\n## Links\n\n- **Repository:** [github.com/bradygaster/squad](https://github.com/bradygaster/squad)\n- **CLI package:** [@dreampunchboy/scuad-cli](https://www.npmjs.com/package/@dreampunchboy/scuad-cli)\n- **Issues:** [github.com/bradygaster/squad/issues](https://github.com/bradygaster/squad/issues)\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-d8c993e6d8282af8b9d914f66d41b968"}