@bradygaster/squad-sdk 0.8.0 → 0.8.3

package/dist/runtime/otel-metrics.js

@@ -0,0 +1,196 @@
+/**
+ * OTel Metrics (Issues #261, #262, #263, #264)
+ *
+ * Provides counters, histograms, and gauges for token usage,
+ * agent performance, session pool, and response latency.
+ * No-op when OTel is not configured (getMeter returns a no-op meter).
+ *
+ * @module runtime/otel-metrics
+ */
+import { getMeter } from './otel.js';
+let _tokenMetrics;
+function ensureTokenMetrics() {
+    if (!_tokenMetrics) {
+        const meter = getMeter('squad-sdk');
+        _tokenMetrics = {
+            inputCounter: meter.createCounter('squad.tokens.input', {
+                description: 'Total input tokens consumed',
+                unit: 'tokens',
+            }),
+            outputCounter: meter.createCounter('squad.tokens.output', {
+                description: 'Total output tokens produced',
+                unit: 'tokens',
+            }),
+            costCounter: meter.createCounter('squad.tokens.cost', {
+                description: 'Estimated cost in USD',
+                unit: 'USD',
+            }),
+            totalCounter: meter.createUpDownCounter('squad.tokens.total', {
+                description: 'Running total of all tokens',
+                unit: 'tokens',
+            }),
+        };
+    }
+    return _tokenMetrics;
+}
+/**
+ * Record token usage from a UsageEvent.
+ * Safe to call when OTel is not configured — metrics are no-ops.
+ */
+export function recordTokenUsage(event) {
+    const m = ensureTokenMetrics();
+    const attrs = {
+        'agent.name': event.agentName ?? 'unknown',
+        'model': event.model,
+    };
+    m.inputCounter.add(event.inputTokens, attrs);
+    m.outputCounter.add(event.outputTokens, attrs);
+    m.costCounter.add(event.estimatedCost, attrs);
+    m.totalCounter.add(event.inputTokens + event.outputTokens, attrs);
+}
+let _agentMetrics;
+function ensureAgentMetrics() {
+    if (!_agentMetrics) {
+        const meter = getMeter('squad-sdk');
+        _agentMetrics = {
+            spawnsCounter: meter.createCounter('squad.agent.spawns', {
+                description: 'Total agent spawns',
+            }),
+            durationHistogram: meter.createHistogram('squad.agent.duration', {
+                description: 'Agent task duration in milliseconds',
+                unit: 'ms',
+            }),
+            errorsCounter: meter.createCounter('squad.agent.errors', {
+                description: 'Total agent errors',
+            }),
+            activeGauge: meter.createUpDownCounter('squad.agent.active', {
+                description: 'Currently active agent sessions',
+            }),
+        };
+    }
+    return _agentMetrics;
+}
+/** Record an agent spawn event. */
+export function recordAgentSpawn(agentName, mode = 'sync') {
+    const m = ensureAgentMetrics();
+    m.spawnsCounter.add(1, { 'agent.name': agentName, mode });
+    m.activeGauge.add(1, { 'agent.name': agentName });
+}
+/** Record agent task completion with duration. */
+export function recordAgentDuration(agentName, durationMs, status = 'success') {
+    const m = ensureAgentMetrics();
+    m.durationHistogram.record(durationMs, { 'agent.name': agentName, status });
+    if (status === 'error') {
+        m.errorsCounter.add(1, { 'agent.name': agentName, 'error.type': 'task_failure' });
+    }
+}
+/** Record an agent error. */
+export function recordAgentError(agentName, errorType) {
+    const m = ensureAgentMetrics();
+    m.errorsCounter.add(1, { 'agent.name': agentName, 'error.type': errorType });
+}
+/** Record agent session destruction (decrements active count). */
+export function recordAgentDestroy(agentName) {
+    const m = ensureAgentMetrics();
+    m.activeGauge.add(-1, { 'agent.name': agentName });
+}
+let _sessionPoolMetrics;
+function ensureSessionPoolMetrics() {
+    if (!_sessionPoolMetrics) {
+        const meter = getMeter('squad-sdk');
+        _sessionPoolMetrics = {
+            activeCounter: meter.createUpDownCounter('squad.sessions.active', {
+                description: 'Currently active sessions',
+            }),
+            idleCounter: meter.createUpDownCounter('squad.sessions.idle', {
+                description: 'Currently idle pooled sessions',
+            }),
+            createdCounter: meter.createCounter('squad.sessions.created', {
+                description: 'Total sessions created',
+            }),
+            closedCounter: meter.createCounter('squad.sessions.closed', {
+                description: 'Total sessions closed',
+            }),
+            errorsCounter: meter.createCounter('squad.sessions.errors', {
+                description: 'Session creation/streaming failures',
+            }),
+        };
+    }
+    return _sessionPoolMetrics;
+}
+/** Record a new session being created. */
+export function recordSessionCreated() {
+    const m = ensureSessionPoolMetrics();
+    m.createdCounter.add(1);
+    m.activeCounter.add(1);
+}
+/** Record a session becoming idle. */
+export function recordSessionIdle() {
+    const m = ensureSessionPoolMetrics();
+    m.activeCounter.add(-1);
+    m.idleCounter.add(1);
+}
+/** Record an idle session becoming active again. */
+export function recordSessionReactivated() {
+    const m = ensureSessionPoolMetrics();
+    m.idleCounter.add(-1);
+    m.activeCounter.add(1);
+}
+/** Record a session being closed. */
+export function recordSessionClosed() {
+    const m = ensureSessionPoolMetrics();
+    m.activeCounter.add(-1);
+    m.closedCounter.add(1);
+}
+/** Record a session error. */
+export function recordSessionError() {
+    const m = ensureSessionPoolMetrics();
+    m.errorsCounter.add(1);
+}
+let _latencyMetrics;
+function ensureLatencyMetrics() {
+    if (!_latencyMetrics) {
+        const meter = getMeter('squad-sdk');
+        _latencyMetrics = {
+            ttftHistogram: meter.createHistogram('squad.response.ttft', {
+                description: 'Time to first token in milliseconds',
+                unit: 'ms',
+            }),
+            durationHistogram: meter.createHistogram('squad.response.duration', {
+                description: 'Total response duration in milliseconds',
+                unit: 'ms',
+            }),
+            tokensPerSecGauge: meter.createGauge('squad.response.tokens_per_second', {
+                description: 'Streaming throughput (tokens/second)',
+                unit: 'tokens/s',
+            }),
+        };
+    }
+    return _latencyMetrics;
+}
+/** Record time to first token. */
+export function recordTimeToFirstToken(ttftMs) {
+    const m = ensureLatencyMetrics();
+    m.ttftHistogram.record(ttftMs);
+}
+/** Record total response duration. */
+export function recordResponseDuration(durationMs) {
+    const m = ensureLatencyMetrics();
+    m.durationHistogram.record(durationMs);
+}
+/** Record streaming throughput. */
+export function recordTokensPerSecond(tokensPerSec) {
+    const m = ensureLatencyMetrics();
+    m.tokensPerSecGauge.record(tokensPerSec);
+}
+// ============================================================================
+// Reset (for testing)
+// ============================================================================
+/** Reset all cached metric instances. Used in tests only. */
+export function _resetMetrics() {
+    _tokenMetrics = undefined;
+    _agentMetrics = undefined;
+    _sessionPoolMetrics = undefined;
+    _latencyMetrics = undefined;
+}
+//# sourceMappingURL=otel-metrics.js.map

package/dist/runtime/otel-metrics.js.map

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

package/dist/runtime/otel.d.ts

@@ -0,0 +1,53 @@
+/**
+ * OpenTelemetry Provider Initialization (Issue #255)
+ *
+ * Configures TracerProvider and MeterProvider with OTLP HTTP exporters.
+ * Disabled by default — activates only when explicit config or
+ * OTEL_EXPORTER_OTLP_ENDPOINT env var is present.
+ *
+ * @module runtime/otel
+ */
+import { type Tracer, type Meter } from '@opentelemetry/api';
+/** Configuration for OTel initialization. */
+export interface OTelConfig {
+    /** OTLP endpoint URL (e.g. http://localhost:4318) */
+    endpoint?: string;
+    /** Service name override (default: 'squad-sdk') */
+    serviceName?: string;
+    /** Enable debug diagnostics */
+    debug?: boolean;
+}
+/**
+ * Initialize the TracerProvider with an OTLP HTTP exporter.
+ * Returns `true` if a provider was registered, `false` if disabled.
+ */
+export declare function initializeTracing(config?: OTelConfig): boolean;
+/**
+ * Initialize the MeterProvider with an OTLP HTTP exporter.
+ * Returns `true` if a provider was registered, `false` if disabled.
+ */
+export declare function initializeMetrics(config?: OTelConfig): boolean;
+/**
+ * Convenience wrapper — initializes both tracing and metrics.
+ * Returns an object indicating which subsystems were activated.
+ */
+export declare function initializeOTel(config?: OTelConfig): {
+    tracing: boolean;
+    metrics: boolean;
+};
+/**
+ * Flush pending telemetry and shut down providers.
+ * Safe to call even if OTel was never initialized.
+ */
+export declare function shutdownOTel(): Promise<void>;
+/**
+ * Return a Tracer instance. Falls back to the no-op tracer when
+ * tracing has not been initialized.
+ */
+export declare function getTracer(name?: string): Tracer;
+/**
+ * Return a Meter instance. Falls back to the no-op meter when
+ * metrics have not been initialized.
+ */
+export declare function getMeter(name?: string): Meter;
+//# sourceMappingURL=otel.d.ts.map

package/dist/runtime/otel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../../src/runtime/otel.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAkB,KAAK,MAAM,EAAE,KAAK,KAAK,EAAyC,MAAM,oBAAoB,CAAC;AAapH,6CAA6C;AAC7C,MAAM,WAAW,UAAU;IACzB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AA8DD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAO9D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAO9D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAK1F;AAED;;;GAGG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAOlD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,SAAc,GAAG,MAAM,CAEpD;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,SAAc,GAAG,KAAK,CAElD"}

package/dist/runtime/otel.js

@@ -0,0 +1,127 @@
+/**
+ * OpenTelemetry Provider Initialization (Issue #255)
+ *
+ * Configures TracerProvider and MeterProvider with OTLP HTTP exporters.
+ * Disabled by default — activates only when explicit config or
+ * OTEL_EXPORTER_OTLP_ENDPOINT env var is present.
+ *
+ * @module runtime/otel
+ */
+import { trace, metrics, DiagConsoleLogger, DiagLogLevel, diag } from '@opentelemetry/api';
+import { NodeSDK, resources, metrics as sdkMetrics } from '@opentelemetry/sdk-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
+import { createRequire } from 'module';
+const { Resource } = resources;
+const { PeriodicExportingMetricReader } = sdkMetrics;
+// ============================================================================
+// Internal state
+// ============================================================================
+let _sdk;
+let _tracingActive = false;
+let _metricsActive = false;
+// ============================================================================
+// Helpers
+// ============================================================================
+function resolveEndpoint(config) {
+    return config?.endpoint ?? process.env['OTEL_EXPORTER_OTLP_ENDPOINT'] ?? undefined;
+}
+function buildResource(config) {
+    const req = createRequire(import.meta.url);
+    let version = 'unknown';
+    try {
+        const pkg = req('../../package.json');
+        version = pkg.version;
+    }
+    catch {
+        // package.json not resolvable — use fallback
+    }
+    return new Resource({
+        'service.name': config?.serviceName ?? 'squad-sdk',
+        'squad.version': version,
+    });
+}
+function ensureSDK(config) {
+    if (_sdk)
+        return;
+    const endpoint = resolveEndpoint(config);
+    if (!endpoint)
+        return;
+    if (config?.debug) {
+        diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);
+    }
+    const resource = buildResource(config);
+    _sdk = new NodeSDK({
+        resource,
+        traceExporter: new OTLPTraceExporter({ url: `${endpoint}/v1/traces` }),
+        metricReader: new PeriodicExportingMetricReader({
+            exporter: new OTLPMetricExporter({ url: `${endpoint}/v1/metrics` }),
+            exportIntervalMillis: 30_000,
+        }),
+    });
+    _sdk.start();
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Initialize the TracerProvider with an OTLP HTTP exporter.
+ * Returns `true` if a provider was registered, `false` if disabled.
+ */
+export function initializeTracing(config) {
+    const endpoint = resolveEndpoint(config);
+    if (!endpoint)
+        return false;
+    ensureSDK(config);
+    _tracingActive = true;
+    return true;
+}
+/**
+ * Initialize the MeterProvider with an OTLP HTTP exporter.
+ * Returns `true` if a provider was registered, `false` if disabled.
+ */
+export function initializeMetrics(config) {
+    const endpoint = resolveEndpoint(config);
+    if (!endpoint)
+        return false;
+    ensureSDK(config);
+    _metricsActive = true;
+    return true;
+}
+/**
+ * Convenience wrapper — initializes both tracing and metrics.
+ * Returns an object indicating which subsystems were activated.
+ */
+export function initializeOTel(config) {
+    return {
+        tracing: initializeTracing(config),
+        metrics: initializeMetrics(config),
+    };
+}
+/**
+ * Flush pending telemetry and shut down providers.
+ * Safe to call even if OTel was never initialized.
+ */
+export async function shutdownOTel() {
+    if (_sdk) {
+        await _sdk.shutdown();
+        _sdk = undefined;
+    }
+    _tracingActive = false;
+    _metricsActive = false;
+}
+/**
+ * Return a Tracer instance. Falls back to the no-op tracer when
+ * tracing has not been initialized.
+ */
+export function getTracer(name = 'squad-sdk') {
+    return trace.getTracer(name);
+}
+/**
+ * Return a Meter instance. Falls back to the no-op meter when
+ * metrics have not been initialized.
+ */
+export function getMeter(name = 'squad-sdk') {
+    return metrics.getMeter(name);
+}
+//# sourceMappingURL=otel.js.map

package/dist/runtime/otel.js.map

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

package/dist/runtime/squad-observer.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Squad Observer — File watcher for .squad/ directory changes (Issue #268)
+ *
+ * Monitors the .squad/ directory for file changes and emits OTel spans
+ * and EventBus events for real-time observability of squad state changes.
+ * Ported from paulyuk/squad#1.
+ *
+ * @module runtime/squad-observer
+ */
+import { EventBus } from './event-bus.js';
+/** Categories of .squad/ file changes. */
+export type SquadFileCategory = 'agent' | 'casting' | 'config' | 'decision' | 'skill' | 'unknown';
+/** A detected file change in the .squad/ directory. */
+export interface SquadFileChange {
+    /** Relative path from .squad/ root */
+    relativePath: string;
+    /** Absolute path on disk */
+    absolutePath: string;
+    /** Type of change */
+    changeType: 'created' | 'modified' | 'deleted';
+    /** Category of the changed file */
+    category: SquadFileCategory;
+    /** Timestamp of detection */
+    timestamp: Date;
+}
+/** Configuration for the observer. */
+export interface SquadObserverConfig {
+    /** Path to the .squad/ directory to watch */
+    squadDir: string;
+    /** Optional EventBus to emit events to */
+    eventBus?: EventBus;
+    /** Debounce interval in ms (default: 200) */
+    debounceMs?: number;
+}
+/**
+ * Classify a file path within .squad/ into a category.
+ */
+export declare function classifyFile(relativePath: string): SquadFileCategory;
+/**
+ * File watcher that monitors .squad/ directory and emits OTel events.
+ *
+ * Usage:
+ * ```typescript
+ * const observer = new SquadObserver({
+ *   squadDir: '/path/to/.squad',
+ *   eventBus: myEventBus,
+ * });
+ * observer.start();
+ * // ... later
+ * observer.stop();
+ * ```
+ */
+export declare class SquadObserver {
+    private config;
+    private watcher;
+    private debounceTimers;
+    private running;
+    constructor(config: SquadObserverConfig);
+    /**
+     * Start watching the .squad/ directory for changes.
+     * Emits OTel spans and EventBus events for each detected change.
+     */
+    start(): void;
+    /**
+     * Stop watching and clean up.
+     */
+    stop(): void;
+    /** Whether the observer is currently running. */
+    get isRunning(): boolean;
+    private handleChange;
+    private processChange;
+    private emitSpan;
+    private emitEvent;
+}
+//# sourceMappingURL=squad-observer.d.ts.map

package/dist/runtime/squad-observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"squad-observer.d.ts","sourceRoot":"","sources":["../../src/runtime/squad-observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,EAAE,QAAQ,EAAmB,MAAM,gBAAgB,CAAC;AAM3D,0CAA0C;AAC1C,MAAM,MAAM,iBAAiB,GACzB,OAAO,GACP,SAAS,GACT,QAAQ,GACR,UAAU,GACV,OAAO,GACP,SAAS,CAAC;AAEd,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,qBAAqB;IACrB,UAAU,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;IAC/C,mCAAmC;IACnC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,6BAA6B;IAC7B,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,sCAAsC;AACtC,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD;;GAEG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,iBAAiB,CAQpE;AAMD;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAyG;IACvH,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,cAAc,CAAyD;IAC/E,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,EAAE,mBAAmB;IAQvC;;;OAGG;IACH,KAAK,IAAI,IAAI;IAwCb;;OAEG;IACH,IAAI,IAAI,IAAI;IAkBZ,iDAAiD;IACjD,IAAI,SAAS,IAAI,OAAO,CAEvB;IAMD,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,aAAa;IAyBrB,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,SAAS;CAmBlB"}

package/dist/runtime/squad-observer.js

@@ -0,0 +1,190 @@
+/**
+ * Squad Observer — File watcher for .squad/ directory changes (Issue #268)
+ *
+ * Monitors the .squad/ directory for file changes and emits OTel spans
+ * and EventBus events for real-time observability of squad state changes.
+ * Ported from paulyuk/squad#1.
+ *
+ * @module runtime/squad-observer
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { SpanStatusCode } from '@opentelemetry/api';
+import { getTracer } from './otel.js';
+// ============================================================================
+// Category classification
+// ============================================================================
+/**
+ * Classify a file path within .squad/ into a category.
+ */
+export function classifyFile(relativePath) {
+    const normalized = relativePath.replace(/\\/g, '/');
+    if (normalized.startsWith('agents/'))
+        return 'agent';
+    if (normalized.startsWith('casting/'))
+        return 'casting';
+    if (normalized.startsWith('skills/'))
+        return 'skill';
+    if (normalized.startsWith('decisions/') || normalized === 'decisions.md')
+        return 'decision';
+    if (normalized === 'config.json' || normalized === 'team.md' || normalized.startsWith('config/'))
+        return 'config';
+    return 'unknown';
+}
+// ============================================================================
+// Observer implementation
+// ============================================================================
+/**
+ * File watcher that monitors .squad/ directory and emits OTel events.
+ *
+ * Usage:
+ * ```typescript
+ * const observer = new SquadObserver({
+ *   squadDir: '/path/to/.squad',
+ *   eventBus: myEventBus,
+ * });
+ * observer.start();
+ * // ... later
+ * observer.stop();
+ * ```
+ */
+export class SquadObserver {
+    config;
+    watcher;
+    debounceTimers = new Map();
+    running = false;
+    constructor(config) {
+        this.config = {
+            squadDir: config.squadDir,
+            eventBus: config.eventBus,
+            debounceMs: config.debounceMs ?? 200,
+        };
+    }
+    /**
+     * Start watching the .squad/ directory for changes.
+     * Emits OTel spans and EventBus events for each detected change.
+     */
+    start() {
+        if (this.running)
+            return;
+        if (!fs.existsSync(this.config.squadDir)) {
+            throw new Error(`Squad directory not found: ${this.config.squadDir}`);
+        }
+        const tracer = getTracer('squad-observer');
+        const span = tracer.startSpan('squad.observer.start', {
+            attributes: {
+                'squad.dir': this.config.squadDir,
+                'debounce_ms': this.config.debounceMs,
+            },
+        });
+        try {
+            this.watcher = fs.watch(this.config.squadDir, { recursive: true }, (eventType, filename) => {
+                if (!filename)
+                    return;
+                this.handleChange(eventType, filename);
+            });
+            this.watcher.on('error', (err) => {
+                const errSpan = tracer.startSpan('squad.observer.error', {
+                    attributes: { 'error.message': err.message },
+                });
+                errSpan.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+                errSpan.recordException(err);
+                errSpan.end();
+            });
+            this.running = true;
+            span.end();
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+            span.recordException(error);
+            span.end();
+            throw err;
+        }
+    }
+    /**
+     * Stop watching and clean up.
+     */
+    stop() {
+        if (!this.running)
+            return;
+        const tracer = getTracer('squad-observer');
+        const span = tracer.startSpan('squad.observer.stop');
+        // Clear all pending debounce timers
+        for (const timer of this.debounceTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.debounceTimers.clear();
+        this.watcher?.close();
+        this.watcher = undefined;
+        this.running = false;
+        span.end();
+    }
+    /** Whether the observer is currently running. */
+    get isRunning() {
+        return this.running;
+    }
+    // --------------------------------------------------------------------------
+    // Internal
+    // --------------------------------------------------------------------------
+    handleChange(eventType, filename) {
+        // Debounce rapid changes to the same file
+        const existing = this.debounceTimers.get(filename);
+        if (existing)
+            clearTimeout(existing);
+        this.debounceTimers.set(filename, setTimeout(() => {
+            this.debounceTimers.delete(filename);
+            this.processChange(filename);
+        }, this.config.debounceMs));
+    }
+    processChange(filename) {
+        const absolutePath = path.join(this.config.squadDir, filename);
+        const category = classifyFile(filename);
+        const exists = fs.existsSync(absolutePath);
+        // Determine change type — basic heuristic since fs.watch doesn't tell us
+        const changeType = exists ? 'modified' : 'deleted';
+        const change = {
+            relativePath: filename,
+            absolutePath,
+            changeType,
+            category,
+            timestamp: new Date(),
+        };
+        // Emit OTel span
+        this.emitSpan(change);
+        // Emit EventBus event
+        if (this.config.eventBus) {
+            this.emitEvent(change);
+        }
+    }
+    emitSpan(change) {
+        const tracer = getTracer('squad-observer');
+        const span = tracer.startSpan('squad.observer.file_change', {
+            attributes: {
+                'file.path': change.relativePath,
+                'file.category': change.category,
+                'change.type': change.changeType,
+            },
+        });
+        span.end();
+    }
+    emitEvent(change) {
+        if (!this.config.eventBus)
+            return;
+        // Map file categories to appropriate event types
+        const event = {
+            type: 'agent:milestone',
+            agentName: change.category === 'agent' ? path.basename(path.dirname(change.relativePath)) : undefined,
+            payload: {
+                action: 'file_change',
+                file: change.relativePath,
+                category: change.category,
+                changeType: change.changeType,
+            },
+            timestamp: change.timestamp,
+        };
+        // Fire and forget — errors handled by EventBus
+        void this.config.eventBus.emit(event);
+    }
+}
+//# sourceMappingURL=squad-observer.js.map