@bradygaster/squad-sdk 0.7.0 → 0.8.2

package/dist/runtime/cost-tracker.js

@@ -0,0 +1,157 @@
+/**
+ * Cost Tracker
+ *
+ * Accumulates cost and token data across a squad run with per-agent and
+ * per-session breakdowns. Wires into EventBus for real-time updates.
+ *
+ * @module runtime/cost-tracker
+ */
+// ============================================================================
+// CostTracker
+// ============================================================================
+/**
+ * Accumulates cost/token data across the squad run.
+ *
+ * Can be wired to an EventBus to receive live usage events or fed
+ * data manually via `recordUsage()`.
+ */
+export class CostTracker {
+    agents = new Map();
+    sessions = new Map();
+    unsubscribe = null;
+    /**
+     * Record a single usage event.
+     */
+    recordUsage(opts) {
+        const agentKey = opts.agentName ?? 'unknown';
+        // Per-agent
+        const agent = this.agents.get(agentKey);
+        if (agent) {
+            agent.inputTokens += opts.inputTokens;
+            agent.outputTokens += opts.outputTokens;
+            agent.estimatedCost += opts.estimatedCost;
+            agent.turnCount += 1;
+            agent.model = opts.model;
+            if (opts.isFallback)
+                agent.fallbackCount += 1;
+        }
+        else {
+            this.agents.set(agentKey, {
+                agentName: agentKey,
+                model: opts.model,
+                inputTokens: opts.inputTokens,
+                outputTokens: opts.outputTokens,
+                estimatedCost: opts.estimatedCost,
+                turnCount: 1,
+                fallbackCount: opts.isFallback ? 1 : 0,
+            });
+        }
+        // Per-session
+        const session = this.sessions.get(opts.sessionId);
+        if (session) {
+            session.inputTokens += opts.inputTokens;
+            session.outputTokens += opts.outputTokens;
+            session.estimatedCost += opts.estimatedCost;
+            session.turnCount += 1;
+        }
+        else {
+            this.sessions.set(opts.sessionId, {
+                sessionId: opts.sessionId,
+                agentName: opts.agentName,
+                inputTokens: opts.inputTokens,
+                outputTokens: opts.outputTokens,
+                estimatedCost: opts.estimatedCost,
+                turnCount: 1,
+            });
+        }
+    }
+    /** Record a model fallback for an agent (increments fallback counter). */
+    recordFallback(agentName) {
+        const agent = this.agents.get(agentName);
+        if (agent) {
+            agent.fallbackCount += 1;
+        }
+    }
+    /** Get the full cost summary. */
+    getSummary() {
+        let totalInputTokens = 0;
+        let totalOutputTokens = 0;
+        let totalEstimatedCost = 0;
+        for (const entry of this.agents.values()) {
+            totalInputTokens += entry.inputTokens;
+            totalOutputTokens += entry.outputTokens;
+            totalEstimatedCost += entry.estimatedCost;
+        }
+        return {
+            totalInputTokens,
+            totalOutputTokens,
+            totalEstimatedCost,
+            agents: new Map(this.agents),
+            sessions: new Map(this.sessions),
+        };
+    }
+    /** Get formatted summary string suitable for terminal output. */
+    formatSummary() {
+        const summary = this.getSummary();
+        const lines = [];
+        lines.push('=== Squad Cost Summary ===');
+        lines.push(`Total input tokens:  ${summary.totalInputTokens.toLocaleString()}`);
+        lines.push(`Total output tokens: ${summary.totalOutputTokens.toLocaleString()}`);
+        lines.push(`Estimated cost:      $${summary.totalEstimatedCost.toFixed(4)}`);
+        if (summary.agents.size > 0) {
+            lines.push('');
+            lines.push('--- By Agent ---');
+            for (const [name, entry] of summary.agents) {
+                lines.push(`  ${name}: ${entry.inputTokens.toLocaleString()}in / ${entry.outputTokens.toLocaleString()}out` +
+                    ` ($${entry.estimatedCost.toFixed(4)}) [${entry.turnCount} turns, model: ${entry.model}` +
+                    `${entry.fallbackCount > 0 ? `, ${entry.fallbackCount} fallbacks` : ''}]`);
+            }
+        }
+        if (summary.sessions.size > 0) {
+            lines.push('');
+            lines.push('--- By Session ---');
+            for (const [id, entry] of summary.sessions) {
+                lines.push(`  ${id}: ${entry.inputTokens.toLocaleString()}in / ${entry.outputTokens.toLocaleString()}out` +
+                    ` ($${entry.estimatedCost.toFixed(4)}) [${entry.turnCount} turns]`);
+            }
+        }
+        return lines.join('\n');
+    }
+    /** Clear all accumulated data. */
+    reset() {
+        this.agents.clear();
+        this.sessions.clear();
+    }
+    /**
+     * Wire into an EventBus to receive real-time `session:message` events
+     * that carry usage payloads. Returns an unsubscribe function.
+     */
+    wireToEventBus(bus) {
+        const handler = (event) => {
+            const payload = event.payload;
+            if (!payload)
+                return;
+            // Accept events with usage data in the payload
+            if (typeof payload.inputTokens === 'number' &&
+                typeof payload.outputTokens === 'number') {
+                this.recordUsage({
+                    sessionId: event.sessionId ?? 'unknown',
+                    agentName: event.agentName,
+                    model: payload.model ?? 'unknown',
+                    inputTokens: payload.inputTokens,
+                    outputTokens: payload.outputTokens,
+                    estimatedCost: payload.estimatedCost ?? 0,
+                    isFallback: payload.isFallback ?? false,
+                });
+            }
+        };
+        this.unsubscribe = bus.subscribe('session:message', handler);
+        return () => {
+            if (this.unsubscribe) {
+                this.unsubscribe();
+                this.unsubscribe = null;
+            }
+        };
+    }
+}
+//# sourceMappingURL=cost-tracker.js.map

package/dist/runtime/cost-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-tracker.js","sourceRoot":"","sources":["../../src/runtime/cost-tracker.ts"],"names":[],"mappings":"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"}

package/dist/runtime/event-bus-otel-bridge.d.ts

@@ -0,0 +1,19 @@
+/**
+ * EventBus → OTel Span Bridge (Issue #304)
+ *
+ * Subscribes to EventBus events and creates OpenTelemetry spans for each.
+ * Complements the existing otel-bridge.ts which handles TelemetryEvent
+ * (dot-separated names like squad.init). This bridge handles runtime
+ * SquadEvent types (colon-separated like session:created).
+ *
+ * @module runtime/event-bus-otel-bridge
+ */
+import type { EventBus, UnsubscribeFn } from './event-bus.js';
+/**
+ * Attach an OTel span bridge to an EventBus.
+ * Every event emitted on the bus produces a corresponding OTel span.
+ *
+ * @returns Unsubscribe function to detach the bridge.
+ */
+export declare function attachOTelBridge(bus: EventBus): UnsubscribeFn;
+//# sourceMappingURL=event-bus-otel-bridge.d.ts.map

package/dist/runtime/event-bus-otel-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus-otel-bridge.d.ts","sourceRoot":"","sources":["../../src/runtime/event-bus-otel-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAc,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG1E;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,GAAG,aAAa,CAuC7D"}

package/dist/runtime/event-bus-otel-bridge.js

@@ -0,0 +1,61 @@
+/**
+ * EventBus → OTel Span Bridge (Issue #304)
+ *
+ * Subscribes to EventBus events and creates OpenTelemetry spans for each.
+ * Complements the existing otel-bridge.ts which handles TelemetryEvent
+ * (dot-separated names like squad.init). This bridge handles runtime
+ * SquadEvent types (colon-separated like session:created).
+ *
+ * @module runtime/event-bus-otel-bridge
+ */
+import { SpanStatusCode } from '@opentelemetry/api';
+import { getTracer } from './otel.js';
+import { isSquadEventOfType } from './event-payloads.js';
+/**
+ * Attach an OTel span bridge to an EventBus.
+ * Every event emitted on the bus produces a corresponding OTel span.
+ *
+ * @returns Unsubscribe function to detach the bridge.
+ */
+export function attachOTelBridge(bus) {
+    return bus.subscribeAll((event) => {
+        const tracer = getTracer('squad-sdk');
+        const spanName = `squad.event.${event.type.replace(':', '.')}`;
+        const attrs = {
+            'squad.event.type': event.type,
+        };
+        if (event.sessionId)
+            attrs['squad.session.id'] = event.sessionId;
+        if (event.agentName)
+            attrs['squad.agent.name'] = event.agentName;
+        // Extract payload attributes for known event types
+        if (isSquadEventOfType(event, 'session:error')) {
+            attrs['squad.error'] = event.payload.error;
+            attrs['squad.error.agent'] = event.payload.agentName;
+        }
+        else if (isSquadEventOfType(event, 'session:tool_call')) {
+            attrs['squad.tool.name'] = event.payload.toolName;
+            if (event.payload.resultType) {
+                attrs['squad.tool.result'] = event.payload.resultType;
+            }
+        }
+        else if (isSquadEventOfType(event, 'coordinator:routing')) {
+            attrs['squad.routing.phase'] = event.payload.phase;
+        }
+        else if (isSquadEventOfType(event, 'agent:milestone')) {
+            attrs['squad.milestone.event'] = event.payload.event;
+            attrs['squad.milestone.agent'] = event.payload.agentName;
+        }
+        else if (isSquadEventOfType(event, 'pool:health')) {
+            attrs['squad.pool.active'] = event.payload.activeSessions;
+            attrs['squad.pool.available'] = event.payload.availableSlots;
+            attrs['squad.pool.queued'] = event.payload.queuedRequests;
+        }
+        const span = tracer.startSpan(spanName, { attributes: attrs });
+        if (event.type === 'session:error') {
+            span.setStatus({ code: SpanStatusCode.ERROR });
+        }
+        span.end();
+    });
+}
+//# sourceMappingURL=event-bus-otel-bridge.js.map

package/dist/runtime/event-bus-otel-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus-otel-bridge.js","sourceRoot":"","sources":["../../src/runtime/event-bus-otel-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAa;IAC5C,OAAO,GAAG,CAAC,YAAY,CAAC,CAAC,KAAiB,EAAE,EAAE;QAC5C,MAAM,MAAM,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;QACtC,MAAM,QAAQ,GAAG,eAAe,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;QAE/D,MAAM,KAAK,GAA8C;YACvD,kBAAkB,EAAE,KAAK,CAAC,IAAI;SAC/B,CAAC;QACF,IAAI,KAAK,CAAC,SAAS;YAAE,KAAK,CAAC,kBAAkB,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC;QACjE,IAAI,KAAK,CAAC,SAAS;YAAE,KAAK,CAAC,kBAAkB,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC;QAEjE,mDAAmD;QACnD,IAAI,kBAAkB,CAAC,KAAK,EAAE,eAAe,CAAC,EAAE,CAAC;YAC/C,KAAK,CAAC,aAAa,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAC3C,KAAK,CAAC,mBAAmB,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;QACvD,CAAC;aAAM,IAAI,kBAAkB,CAAC,KAAK,EAAE,mBAAmB,CAAC,EAAE,CAAC;YAC1D,KAAK,CAAC,iBAAiB,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;YAClD,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;gBAC7B,KAAK,CAAC,mBAAmB,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;YACxD,CAAC;QACH,CAAC;aAAM,IAAI,kBAAkB,CAAC,KAAK,EAAE,qBAAqB,CAAC,EAAE,CAAC;YAC5D,KAAK,CAAC,qBAAqB,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACrD,CAAC;aAAM,IAAI,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,CAAC,EAAE,CAAC;YACxD,KAAK,CAAC,uBAAuB,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YACrD,KAAK,CAAC,uBAAuB,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;QAC3D,CAAC;aAAM,IAAI,kBAAkB,CAAC,KAAK,EAAE,aAAa,CAAC,EAAE,CAAC;YACpD,KAAK,CAAC,mBAAmB,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC;YAC1D,KAAK,CAAC,sBAAsB,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC;YAC7D,KAAK,CAAC,mBAAmB,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC;QAC5D,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;QAE/D,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;YACnC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC;QACjD,CAAC;QAED,IAAI,CAAC,GAAG,EAAE,CAAC;IACb,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/runtime/event-bus-ws-bridge.d.ts

@@ -0,0 +1,35 @@
+/**
+ * EventBus to WebSocket Bridge (Issue #304)
+ *
+ * Broadcasts EventBus events over a WebSocket server so external
+ * consumers (e.g., SquadOffice visualization) can subscribe to
+ * real-time SDK events without coupling to OTel.
+ *
+ * @module runtime/event-bus-ws-bridge
+ */
+import type { EventBus } from './event-bus.js';
+export interface WSBridgeOptions {
+    /** WebSocket server port. Defaults to 6277. */
+    port?: number;
+    /** Optional host to bind to. Defaults to '127.0.0.1'. */
+    host?: string;
+}
+export interface WSBridgeHandle {
+    /** Stop the bridge and close the WebSocket server. */
+    close: () => Promise<void>;
+    /** The port the WebSocket server is listening on. */
+    port: number;
+}
+/**
+ * Start a WebSocket server that broadcasts every EventBus event
+ * as a JSON message to all connected clients.
+ *
+ * Message format matches the SquadOffice WSMessage envelope:
+ * ```json
+ * { "kind": "event", "payload": { ...SquadEvent... } }
+ * ```
+ *
+ * @returns A handle to close the bridge.
+ */
+export declare function startWSBridge(bus: EventBus, options?: WSBridgeOptions): WSBridgeHandle;
+//# sourceMappingURL=event-bus-ws-bridge.d.ts.map

package/dist/runtime/event-bus-ws-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus-ws-bridge.d.ts","sourceRoot":"","sources":["../../src/runtime/event-bus-ws-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAA6B,MAAM,gBAAgB,CAAC;AAE1E,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,QAAQ,EACb,OAAO,GAAE,eAAoB,GAC5B,cAAc,CA2BhB"}

package/dist/runtime/event-bus-ws-bridge.js

@@ -0,0 +1,55 @@
+/**
+ * EventBus to WebSocket Bridge (Issue #304)
+ *
+ * Broadcasts EventBus events over a WebSocket server so external
+ * consumers (e.g., SquadOffice visualization) can subscribe to
+ * real-time SDK events without coupling to OTel.
+ *
+ * @module runtime/event-bus-ws-bridge
+ */
+import { WebSocketServer, WebSocket } from 'ws';
+/**
+ * Start a WebSocket server that broadcasts every EventBus event
+ * as a JSON message to all connected clients.
+ *
+ * Message format matches the SquadOffice WSMessage envelope:
+ * ```json
+ * { "kind": "event", "payload": { ...SquadEvent... } }
+ * ```
+ *
+ * @returns A handle to close the bridge.
+ */
+export function startWSBridge(bus, options = {}) {
+    const port = options.port ?? 6277;
+    const host = options.host ?? '127.0.0.1';
+    const wss = new WebSocketServer({ port, host });
+    const unsubscribe = bus.subscribeAll((event) => {
+        const message = JSON.stringify({
+            kind: 'event',
+            payload: serializeEvent(event),
+        });
+        for (const client of wss.clients) {
+            if (client.readyState === WebSocket.OPEN) {
+                client.send(message);
+            }
+        }
+    });
+    return {
+        port,
+        close: () => new Promise((resolve, reject) => {
+            unsubscribe();
+            wss.close((err) => (err ? reject(err) : resolve()));
+        }),
+    };
+}
+/** Serialize a SquadEvent for JSON transport (Date to ISO string). */
+function serializeEvent(event) {
+    return {
+        type: event.type,
+        sessionId: event.sessionId,
+        agentName: event.agentName,
+        payload: event.payload,
+        timestamp: event.timestamp.toISOString(),
+    };
+}
+//# sourceMappingURL=event-bus-ws-bridge.js.map

package/dist/runtime/event-bus-ws-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus-ws-bridge.js","sourceRoot":"","sources":["../../src/runtime/event-bus-ws-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAiBhD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAa,EACb,UAA2B,EAAE;IAE7B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC;IAClC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,WAAW,CAAC;IAEzC,MAAM,GAAG,GAAG,IAAI,eAAe,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAEhD,MAAM,WAAW,GAAkB,GAAG,CAAC,YAAY,CAAC,CAAC,KAAiB,EAAE,EAAE;QACxE,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;YAC7B,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC;SAC/B,CAAC,CAAC;QAEH,KAAK,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;YACjC,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;gBACzC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,IAAI;QACJ,KAAK,EAAE,GAAG,EAAE,CACV,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACpC,WAAW,EAAE,CAAC;YACd,GAAG,CAAC,KAAK,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAC9D,CAAC,CAAC;KACL,CAAC;AACJ,CAAC;AAED,sEAAsE;AACtE,SAAS,cAAc,CAAC,KAAiB;IACvC,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,EAAE;KACzC,CAAC;AACJ,CAAC"}

package/dist/runtime/event-bus.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Cross-Session Event Bus (M0-5, Issue #77)
+ *
+ * Pub/sub event bus for session lifecycle events with cross-session aggregation.
+ * Enables the coordinator to observe all agent sessions from a single subscription point.
+ * Decouples event producers (sessions) from consumers (coordinator, Ralph, UI).
+ *
+ * @module runtime/event-bus
+ */
+/**
+ * Core lifecycle events emitted by Squad sessions.
+ * All lifecycle events are persistent and logged for debugging.
+ */
+export type SquadLifecycleEvent = 'session:created' | 'session:idle' | 'session:error' | 'session:destroyed';
+/**
+ * Additional operational events for coordination and monitoring.
+ */
+export type SquadOperationalEvent = 'session:message' | 'session:tool_call' | 'agent:milestone' | 'coordinator:routing' | 'pool:health';
+/**
+ * All event types supported by the event bus.
+ */
+export type SquadEventType = SquadLifecycleEvent | SquadOperationalEvent;
+/**
+ * Base event structure with required metadata.
+ * All events include a timestamp for chronological ordering and debugging.
+ */
+export interface SquadEvent {
+    /** Event type identifier */
+    type: SquadEventType;
+    /** Session ID that originated this event (optional for pool-level events) */
+    sessionId?: string;
+    /** Agent name associated with this event (optional) */
+    agentName?: string;
+    /** Event-specific payload data */
+    payload: unknown;
+    /** Timestamp when event was created */
+    timestamp: Date;
+}
+/**
+ * Handler function for processing events.
+ * Handlers may be synchronous or asynchronous.
+ * Errors in handlers are isolated and do not affect other handlers.
+ */
+export type EventHandler = (event: SquadEvent) => void | Promise<void>;
+/**
+ * Unsubscribe function returned from subscription methods.
+ * Call this function to remove the handler from the event bus.
+ */
+export type UnsubscribeFn = () => void;
+/**
+ * Cross-session event aggregation bus.
+ *
+ * Key features:
+ * - Subscribe to specific event types or all events
+ * - Async/sync handler support with error isolation
+ * - No race conditions — handlers run in subscription order
+ * - Lifecycle events: session:created, session:idle, session:error, session:destroyed
+ * - Cross-session aggregation — single subscription point for all sessions
+ *
+ * Usage:
+ * ```typescript
+ * const bus = new EventBus();
+ *
+ * // Subscribe to specific event
+ * const unsubscribe = bus.subscribe('session:created', (event) => {
+ *   console.log('New session:', event.sessionId);
+ * });
+ *
+ * // Subscribe to all events
+ * const unsubscribeAll = bus.subscribeAll((event) => {
+ *   console.log('Event:', event.type);
+ * });
+ *
+ * // Emit event
+ * await bus.emit({
+ *   type: 'session:created',
+ *   sessionId: 'abc-123',
+ *   agentName: 'Ralph',
+ *   payload: { model: 'claude-sonnet-4.5' },
+ *   timestamp: new Date()
+ * });
+ *
+ * // Clean up
+ * unsubscribe();
+ * unsubscribeAll();
+ * ```
+ */
+export declare class EventBus {
+    private handlers;
+    private allHandlers;
+    private errorHandlers;
+    /**
+     * Subscribe to a specific event type.
+     *
+     * @param type - Event type to listen for
+     * @param handler - Handler function to call when event occurs
+     * @returns Unsubscribe function to remove this handler
+     *
+     * @example
+     * ```typescript
+     * const bus = new EventBus();
+     * const unsubscribe = bus.subscribe('session:created', (event) => {
+     *   console.log('Session created:', event.sessionId);
+     * });
+     *
+     * // Later, remove subscription
+     * unsubscribe();
+     * ```
+     */
+    subscribe(type: SquadEventType, handler: EventHandler): UnsubscribeFn;
+    /**
+     * Subscribe to all events regardless of type.
+     * Useful for logging, monitoring, or debugging.
+     *
+     * @param handler - Handler function to call for every event
+     * @returns Unsubscribe function to remove this handler
+     *
+     * @example
+     * ```typescript
+     * const bus = new EventBus();
+     * const unsubscribe = bus.subscribeAll((event) => {
+     *   console.log(`[${event.type}] ${event.sessionId || 'global'}`);
+     * });
+     * ```
+     */
+    subscribeAll(handler: EventHandler): UnsubscribeFn;
+    /**
+     * Unsubscribe a handler from a specific event type.
+     *
+     * @param type - Event type to unsubscribe from
+     * @param handler - Handler function to remove
+     */
+    unsubscribe(type: SquadEventType, handler: EventHandler): void;
+    /**
+     * Register an error handler for handler execution failures.
+     * Error handlers are called when a subscribed handler throws an error.
+     *
+     * @param handler - Error handler function
+     * @returns Unsubscribe function to remove this error handler
+     */
+    onError(handler: (error: Error, event: SquadEvent) => void): UnsubscribeFn;
+    /**
+     * Emit an event to all matching subscribers.
+     * Handlers are called in subscription order with error isolation.
+     * One handler failure does not prevent other handlers from executing.
+     *
+     * @param event - Event to emit
+     * @returns Promise that resolves when all handlers complete
+     *
+     * @example
+     * ```typescript
+     * await bus.emit({
+     *   type: 'session:created',
+     *   sessionId: 'abc-123',
+     *   agentName: 'Ralph',
+     *   payload: { model: 'claude-sonnet-4.5' },
+     *   timestamp: new Date()
+     * });
+     * ```
+     */
+    emit(event: SquadEvent): Promise<void>;
+    /**
+     * Execute a single handler with error isolation.
+     * Catches and reports handler errors without propagating them.
+     *
+     * @param handler - Handler function to execute
+     * @param event - Event to pass to handler
+     */
+    private executeHandler;
+    /**
+     * Remove all handlers and reset the event bus.
+     * Useful for cleanup in tests or when shutting down.
+     */
+    clear(): void;
+    /**
+     * Get count of handlers for a specific event type.
+     * Useful for debugging and testing.
+     *
+     * @param type - Event type to count handlers for
+     * @returns Number of handlers subscribed to this event type
+     */
+    getHandlerCount(type: SquadEventType): number;
+    /**
+     * Get count of wildcard handlers.
+     *
+     * @returns Number of handlers subscribed to all events
+     */
+    getAllHandlerCount(): number;
+}
+//# sourceMappingURL=event-bus.d.ts.map

package/dist/runtime/event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/runtime/event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAC3B,iBAAiB,GACjB,cAAc,GACd,eAAe,GACf,mBAAmB,CAAC;AAExB;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAC7B,iBAAiB,GACjB,mBAAmB,GACnB,iBAAiB,GACjB,qBAAqB,GACrB,aAAa,CAAC;AAElB;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,mBAAmB,GAAG,qBAAqB,CAAC;AAEzE;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,IAAI,EAAE,cAAc,CAAC;IACrB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,uCAAuC;IACvC,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEvE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC;AAMvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAqD;IACrE,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,aAAa,CAA6D;IAElF;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,GAAG,aAAa;IASrE;;;;;;;;;;;;;;OAcG;IACH,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,aAAa;IAKlD;;;;;OAKG;IACH,WAAW,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAS9D;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,aAAa;IAK1E;;;;;;;;;;;;;;;;;;OAkBG;IACG,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB5C;;;;;;OAMG;YACW,cAAc;IA2B5B;;;OAGG;IACH,KAAK,IAAI,IAAI;IAMb;;;;;;OAMG;IACH,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM;IAI7C;;;;OAIG;IACH,kBAAkB,IAAI,MAAM;CAG7B"}