@bradygaster/squad-sdk 0.7.0 → 0.8.2-1.4

package/dist/runtime/offline.js

@@ -0,0 +1,108 @@
+/**
+ * Offline Mode — graceful degradation when connectivity is unavailable
+ * Issue #142 (M5-14)
+ */
+// --- Detect connectivity ---
+export function detectConnectivity(checker) {
+    if (!checker) {
+        return Promise.resolve('online');
+    }
+    return checker()
+        .then((ok) => (ok ? 'online' : 'offline'))
+        .catch(() => 'offline');
+}
+// --- OfflineManager ---
+export class OfflineManager {
+    connectivity = 'online';
+    pendingQueue = [];
+    lastSyncTime = null;
+    cachedAgentNames = [];
+    connectivityChecker;
+    syncHandler;
+    constructor(options) {
+        this.connectivityChecker = options?.connectivityChecker;
+        this.syncHandler = options?.syncHandler;
+        this.cachedAgentNames = options?.cachedAgents ?? [];
+    }
+    /** Get what works offline */
+    getOfflineCapabilities() {
+        const isOnline = this.connectivity === 'online';
+        return {
+            localAgents: true,
+            cachedSkills: true,
+            configEditing: true,
+            marketplaceBrowse: isOnline || this.connectivity === 'degraded',
+            publishing: isOnline,
+            remoteAgents: isOnline,
+        };
+    }
+    /** Queue an operation for later sync */
+    queueForSync(operation) {
+        this.pendingQueue.push({ ...operation });
+    }
+    /** Replay queued operations */
+    async syncPending() {
+        if (this.connectivity === 'offline') {
+            return { synced: 0, failed: 0, remaining: this.pendingQueue.length };
+        }
+        let synced = 0;
+        let failed = 0;
+        const remaining = [];
+        for (const op of this.pendingQueue) {
+            try {
+                const success = this.syncHandler
+                    ? await this.syncHandler(op)
+                    : true;
+                if (success) {
+                    synced++;
+                }
+                else {
+                    op.retries++;
+                    remaining.push(op);
+                    failed++;
+                }
+            }
+            catch {
+                op.retries++;
+                remaining.push(op);
+                failed++;
+            }
+        }
+        this.pendingQueue = remaining;
+        this.lastSyncTime = new Date().toISOString();
+        return { synced, failed, remaining: remaining.length };
+    }
+    /** Get current offline status */
+    getOfflineStatus() {
+        return {
+            connectivity: this.connectivity,
+            pendingOps: this.pendingQueue.length,
+            lastSync: this.lastSyncTime,
+            cachedAgents: [...this.cachedAgentNames],
+        };
+    }
+    /** Update connectivity status */
+    async refreshConnectivity() {
+        this.connectivity = await detectConnectivity(this.connectivityChecker);
+        return this.connectivity;
+    }
+    /** Set connectivity directly (useful for testing) */
+    setConnectivity(status) {
+        this.connectivity = status;
+    }
+    /** Add a cached agent name */
+    addCachedAgent(name) {
+        if (!this.cachedAgentNames.includes(name)) {
+            this.cachedAgentNames.push(name);
+        }
+    }
+    /** Get pending operations */
+    getPendingOperations() {
+        return [...this.pendingQueue];
+    }
+    /** Clear all pending operations */
+    clearPending() {
+        this.pendingQueue = [];
+    }
+}
+//# sourceMappingURL=offline.js.map

package/dist/runtime/offline.js.map

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

package/dist/runtime/otel-api.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Resilient @opentelemetry/api wrapper (Issue #247)
+ *
+ * Re-exports the subset of @opentelemetry/api that Squad uses, with
+ * automatic no-op fallbacks when the package is not installed.  This
+ * makes telemetry truly optional at runtime — the SDK never crashes
+ * due to a missing OpenTelemetry dependency.
+ *
+ * @module runtime/otel-api
+ */
+declare const _noopTracer: any;
+declare const _noopMeter: any;
+/** Span status codes. */
+export declare const SpanStatusCode: {
+    readonly UNSET: 0;
+    readonly OK: 1;
+    readonly ERROR: 2;
+};
+/** Trace API entry point. */
+export declare const trace: import("@opentelemetry/api").TraceAPI | {
+    getTracer(): typeof _noopTracer;
+};
+/** Metrics API entry point. */
+export declare const metrics: import("@opentelemetry/api").MetricsAPI | {
+    getMeter(): typeof _noopMeter;
+};
+/** Diagnostics API. */
+export declare const diag: any;
+/** Diagnostics console logger class. */
+export declare const DiagConsoleLogger: any;
+/** Diagnostics log level enum. */
+export declare const DiagLogLevel: any;
+/** Whether @opentelemetry/api was successfully loaded. */
+export declare const otelApiAvailable: boolean;
+export type Tracer = import('@opentelemetry/api').Tracer;
+export type Meter = import('@opentelemetry/api').Meter;
+export {};
+//# sourceMappingURL=otel-api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"otel-api.d.ts","sourceRoot":"","sources":["../../src/runtime/otel-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAkCH,QAAA,MAAM,WAAW,EAAE,GAMlB,CAAC;AASF,QAAA,MAAM,UAAU,EAAE,GAQjB,CAAC;AAQF,yBAAyB;AACzB,eAAO,MAAM,cAAc,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CACjB,CAAC;AAEnE,6BAA6B;AAC7B,eAAO,MAAM,KAAK;iBACH,OAAO,WAAW;CAChC,CAAC;AAEF,+BAA+B;AAC/B,eAAO,MAAM,OAAO;gBACN,OAAO,UAAU;CAC9B,CAAC;AAEF,uBAAuB;AACvB,eAAO,MAAM,IAAI,EAAE,GAQlB,CAAC;AAEF,wCAAwC;AACxC,eAAO,MAAM,iBAAiB,EAAE,GAAwD,CAAC;AAEzF,kCAAkC;AAClC,eAAO,MAAM,YAAY,EAAE,GAE1B,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,gBAAgB,EAAE,OAA4B,CAAC;AAG5D,MAAM,MAAM,MAAM,GAAG,OAAO,oBAAoB,EAAE,MAAM,CAAC;AACzD,MAAM,MAAM,KAAK,GAAG,OAAO,oBAAoB,EAAE,KAAK,CAAC"}

package/dist/runtime/otel-api.js

@@ -0,0 +1,94 @@
+/**
+ * Resilient @opentelemetry/api wrapper (Issue #247)
+ *
+ * Re-exports the subset of @opentelemetry/api that Squad uses, with
+ * automatic no-op fallbacks when the package is not installed.  This
+ * makes telemetry truly optional at runtime — the SDK never crashes
+ * due to a missing OpenTelemetry dependency.
+ *
+ * @module runtime/otel-api
+ */
+import { createRequire } from 'node:module';
+// ---------------------------------------------------------------------------
+// Dynamic load — graceful fallback when @opentelemetry/api is absent
+// ---------------------------------------------------------------------------
+let _api;
+try {
+    const _require = createRequire(import.meta.url);
+    _api = _require('@opentelemetry/api');
+}
+catch {
+    // @opentelemetry/api not installed — all telemetry becomes no-op
+}
+// ---------------------------------------------------------------------------
+// No-op implementations (mirror the @opentelemetry/api surface we use)
+// ---------------------------------------------------------------------------
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const _noopSpan = {
+    end() { },
+    setStatus() { return _noopSpan; },
+    setAttribute() { return _noopSpan; },
+    setAttributes() { return _noopSpan; },
+    addEvent() { return _noopSpan; },
+    recordException() { return _noopSpan; },
+    isRecording() { return false; },
+    updateName() { return _noopSpan; },
+    spanContext() { return { traceId: '', spanId: '', traceFlags: 0 }; },
+};
+const _noopTracer = {
+    startSpan() { return _noopSpan; },
+    startActiveSpan(...args) {
+        const fn = args[args.length - 1];
+        if (typeof fn === 'function')
+            return fn(_noopSpan);
+    },
+};
+const _noopInstrument = {
+    add() { },
+    record() { },
+    addCallback() { },
+    removeCallback() { },
+};
+const _noopMeter = {
+    createCounter() { return _noopInstrument; },
+    createUpDownCounter() { return _noopInstrument; },
+    createHistogram() { return _noopInstrument; },
+    createObservableCounter() { return _noopInstrument; },
+    createObservableUpDownCounter() { return _noopInstrument; },
+    createObservableGauge() { return _noopInstrument; },
+    createGauge() { return _noopInstrument; },
+};
+/* eslint-enable @typescript-eslint/no-explicit-any */
+// ---------------------------------------------------------------------------
+// Exports — real API when available, no-ops otherwise
+// ---------------------------------------------------------------------------
+/** Span status codes. */
+export const SpanStatusCode = _api?.SpanStatusCode ?? { UNSET: 0, OK: 1, ERROR: 2 };
+/** Trace API entry point. */
+export const trace = _api?.trace ?? {
+    getTracer() { return _noopTracer; },
+};
+/** Metrics API entry point. */
+export const metrics = _api?.metrics ?? {
+    getMeter() { return _noopMeter; },
+};
+/** Diagnostics API. */
+export const diag = _api?.diag ?? {
+    setLogger() { },
+    disable() { },
+    verbose() { },
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+};
+/** Diagnostics console logger class. */
+export const DiagConsoleLogger = _api?.DiagConsoleLogger ?? class NoopDiagLogger {
+}; // eslint-disable-line @typescript-eslint/no-explicit-any
+/** Diagnostics log level enum. */
+export const DiagLogLevel = _api?.DiagLogLevel ?? {
+    NONE: 0, ERROR: 30, WARN: 50, INFO: 60, DEBUG: 70, VERBOSE: 80, ALL: 9999,
+};
+/** Whether @opentelemetry/api was successfully loaded. */
+export const otelApiAvailable = _api !== undefined;
+//# sourceMappingURL=otel-api.js.map

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

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

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

@@ -0,0 +1,52 @@
+/**
+ * OTel Bridge for TelemetryCollector (Issue #256)
+ *
+ * Converts TelemetryEvents into OpenTelemetry spans, providing a
+ * TelemetryTransport that can be registered via setTelemetryTransport().
+ * Additive — the existing transport pipeline is unaffected.
+ *
+ * @module runtime/otel-bridge
+ */
+import type { TelemetryTransport } from './telemetry.js';
+import type { EventBus, UnsubscribeFn } from './event-bus.js';
+/**
+ * Create a TelemetryTransport that emits OTel spans for each event.
+ *
+ * Usage:
+ * ```ts
+ * import { setTelemetryTransport } from './telemetry.js';
+ * import { createOTelTransport } from './otel-bridge.js';
+ *
+ * setTelemetryTransport(createOTelTransport());
+ * ```
+ *
+ * The bridge ignores the `endpoint` parameter — OTel exporter config is
+ * managed by the OTel provider initialized via `initializeOTel()`.
+ */
+export declare function createOTelTransport(): TelemetryTransport;
+/**
+ * Subscribe an {@link EventBus} to OpenTelemetry, creating a span for every
+ * event that flows through the bus.
+ *
+ * This is the **mid-level** OTel integration point — it wires the Squad
+ * event bus directly into the OTel trace pipeline. If no `TracerProvider`
+ * has been registered (e.g. via {@link initializeOTel}), all spans are
+ * automatically no-ops with zero overhead.
+ *
+ * @param bus - The EventBus instance to bridge.
+ * @returns An unsubscribe function. Call it to detach the bridge.
+ *
+ * @example
+ * ```ts
+ * import { EventBus, initializeOTel, bridgeEventBusToOTel } from 'squad-sdk';
+ *
+ * const bus = new EventBus();
+ * initializeOTel({ endpoint: 'http://localhost:4318' });
+ * const detach = bridgeEventBusToOTel(bus);
+ *
+ * // Later, to stop bridging:
+ * detach();
+ * ```
+ */
+export declare function bridgeEventBusToOTel(bus: EventBus): UnsubscribeFn;
+//# sourceMappingURL=otel-bridge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"otel-bridge.d.ts","sourceRoot":"","sources":["../../src/runtime/otel-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAkB,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAc,MAAM,gBAAgB,CAAC;AAsE1E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,IAAI,kBAAkB,CAMxD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,QAAQ,GAAG,aAAa,CAejE"}

package/dist/runtime/otel-bridge.js

@@ -0,0 +1,132 @@
+/**
+ * OTel Bridge for TelemetryCollector (Issue #256)
+ *
+ * Converts TelemetryEvents into OpenTelemetry spans, providing a
+ * TelemetryTransport that can be registered via setTelemetryTransport().
+ * Additive — the existing transport pipeline is unaffected.
+ *
+ * @module runtime/otel-bridge
+ */
+import { SpanStatusCode } from './otel-api.js';
+import { getTracer } from './otel.js';
+// ============================================================================
+// Span mapping
+// ============================================================================
+function recordSpan(event) {
+    const tracer = getTracer('squad-sdk');
+    const attrs = {};
+    if (event.properties) {
+        for (const [k, v] of Object.entries(event.properties)) {
+            attrs[k] = v;
+        }
+    }
+    if (event.timestamp) {
+        attrs['event.timestamp'] = event.timestamp;
+    }
+    switch (event.name) {
+        case 'squad.init': {
+            const span = tracer.startSpan('squad.init', { attributes: attrs });
+            span.end();
+            break;
+        }
+        case 'squad.agent.spawn': {
+            const span = tracer.startSpan('squad.agent.spawn', { attributes: attrs });
+            span.end();
+            break;
+        }
+        case 'squad.error': {
+            const span = tracer.startSpan('squad.error', { attributes: attrs });
+            span.setStatus({ code: SpanStatusCode.ERROR, message: String(attrs['error'] ?? 'unknown') });
+            span.addEvent('exception', {
+                'exception.message': String(attrs['error'] ?? attrs['message'] ?? 'unknown error'),
+                ...(attrs['stack'] ? { 'exception.stacktrace': String(attrs['stack']) } : {}),
+            });
+            span.end();
+            break;
+        }
+        case 'squad.run': {
+            // Root span for the entire session — start and immediately end
+            // (the real duration would be managed by the caller if needed)
+            const span = tracer.startSpan('squad.run', { attributes: attrs });
+            span.end();
+            break;
+        }
+        case 'squad.upgrade': {
+            const span = tracer.startSpan('squad.upgrade', { attributes: attrs });
+            span.end();
+            break;
+        }
+        default: {
+            // Forward unknown events as generic spans
+            const span = tracer.startSpan(event.name, { attributes: attrs });
+            span.end();
+            break;
+        }
+    }
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Create a TelemetryTransport that emits OTel spans for each event.
+ *
+ * Usage:
+ * ```ts
+ * import { setTelemetryTransport } from './telemetry.js';
+ * import { createOTelTransport } from './otel-bridge.js';
+ *
+ * setTelemetryTransport(createOTelTransport());
+ * ```
+ *
+ * The bridge ignores the `endpoint` parameter — OTel exporter config is
+ * managed by the OTel provider initialized via `initializeOTel()`.
+ */
+export function createOTelTransport() {
+    return async (events, _endpoint) => {
+        for (const event of events) {
+            recordSpan(event);
+        }
+    };
+}
+/**
+ * Subscribe an {@link EventBus} to OpenTelemetry, creating a span for every
+ * event that flows through the bus.
+ *
+ * This is the **mid-level** OTel integration point — it wires the Squad
+ * event bus directly into the OTel trace pipeline. If no `TracerProvider`
+ * has been registered (e.g. via {@link initializeOTel}), all spans are
+ * automatically no-ops with zero overhead.
+ *
+ * @param bus - The EventBus instance to bridge.
+ * @returns An unsubscribe function. Call it to detach the bridge.
+ *
+ * @example
+ * ```ts
+ * import { EventBus, initializeOTel, bridgeEventBusToOTel } from 'squad-sdk';
+ *
+ * const bus = new EventBus();
+ * initializeOTel({ endpoint: 'http://localhost:4318' });
+ * const detach = bridgeEventBusToOTel(bus);
+ *
+ * // Later, to stop bridging:
+ * detach();
+ * ```
+ */
+export function bridgeEventBusToOTel(bus) {
+    return bus.subscribeAll((event) => {
+        const tracer = getTracer('squad-sdk');
+        const attrs = {
+            'event.type': event.type,
+        };
+        if (event.sessionId)
+            attrs['session.id'] = event.sessionId;
+        if (event.agentName)
+            attrs['agent.name'] = event.agentName;
+        const span = tracer.startSpan(`squad.${event.type}`, { attributes: attrs });
+        if (event.type === 'session:error') {
+            span.setStatus({ code: SpanStatusCode.ERROR });
+        }
+        span.end();
+    });
+}
+//# sourceMappingURL=otel-bridge.js.map

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

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

package/dist/runtime/otel-init.d.ts

@@ -0,0 +1,84 @@
+/**
+ * High-Level OTel Initialization (Issue #266)
+ *
+ * One-call setup that wires OTel providers, the EventBus bridge, and
+ * the TelemetryCollector transport in a single invocation. Consumers
+ * who don't use OTel pay nothing — if no provider is registered all
+ * instrumentation is a no-op.
+ *
+ * @module runtime/otel-init
+ */
+import type { OTelConfig } from './otel.js';
+import type { EventBus } from './event-bus.js';
+/** Options for the high-level {@link initSquadTelemetry} helper. */
+export interface SquadTelemetryOptions extends OTelConfig {
+    /**
+     * When provided, all EventBus events are automatically forwarded
+     * as OTel spans via {@link bridgeEventBusToOTel}.
+     */
+    eventBus?: EventBus;
+    /**
+     * When `true`, the OTel-backed TelemetryTransport is registered
+     * as the active transport for {@link TelemetryCollector}.
+     * @default true
+     */
+    installTransport?: boolean;
+}
+/** Handle returned by {@link initSquadTelemetry} for lifecycle control. */
+export interface SquadTelemetryHandle {
+    /** Whether tracing was activated. */
+    tracing: boolean;
+    /** Whether metrics were activated. */
+    metrics: boolean;
+    /**
+     * Flush pending telemetry, detach the EventBus bridge (if any),
+     * and shut down OTel providers. Safe to call multiple times.
+     */
+    shutdown: () => Promise<void>;
+}
+/**
+ * One-call OTel setup for Squad SDK consumers.
+ *
+ * This is the **high-level** entry point. It:
+ * 1. Initializes tracing and metrics via `initializeOTel()`.
+ * 2. Optionally bridges an {@link EventBus} so every Squad event
+ *    becomes an OTel span.
+ * 3. Optionally installs an OTel-backed `TelemetryTransport` so
+ *    the existing `TelemetryCollector` pipeline emits spans too.
+ *
+ * If no `OTEL_EXPORTER_OTLP_ENDPOINT` env var is set **and** no
+ * `endpoint` is provided in `options`, everything remains a no-op.
+ *
+ * @param options - Configuration and optional EventBus.
+ * @returns A handle with `tracing`, `metrics` status booleans and a
+ *          `shutdown()` method for graceful cleanup.
+ *
+ * @example
+ * ```ts
+ * import { initSquadTelemetry, EventBus } from 'squad-sdk';
+ *
+ * const bus = new EventBus();
+ * const telemetry = initSquadTelemetry({
+ *   endpoint: 'http://localhost:4318',
+ *   eventBus: bus,
+ * });
+ *
+ * // … run your squad …
+ *
+ * await telemetry.shutdown();
+ * ```
+ */
+export declare function initSquadTelemetry(options?: SquadTelemetryOptions): SquadTelemetryHandle;
+/**
+ * Convenience wrapper for Copilot agent-mode telemetry.
+ *
+ * Pre-configures `serviceName` to `'squad-copilot-agent'` and
+ * `mode` to `'copilot-agent'` so the two surfaces (CLI vs agent)
+ * are distinguishable in dashboards and trace queries.
+ *
+ * Call this at agent-mode startup; call `handle.shutdown()` on exit.
+ *
+ * @param options - Additional overrides (endpoint, eventBus, etc.).
+ */
+export declare function initAgentModeTelemetry(options?: Omit<SquadTelemetryOptions, 'serviceName' | 'mode'>): SquadTelemetryHandle;
+//# sourceMappingURL=otel-init.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"otel-init.d.ts","sourceRoot":"","sources":["../../src/runtime/otel-init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAU/C,oEAAoE;AACpE,MAAM,WAAW,qBAAsB,SAAQ,UAAU;IACvD;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,2EAA2E;AAC3E,MAAM,WAAW,oBAAoB;IACnC,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,qBAA0B,GAAG,oBAAoB,CAsB5F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,IAAI,CAAC,qBAAqB,EAAE,aAAa,GAAG,MAAM,CAAM,GAAG,oBAAoB,CAM9H"}

package/dist/runtime/otel-init.js

@@ -0,0 +1,86 @@
+/**
+ * High-Level OTel Initialization (Issue #266)
+ *
+ * One-call setup that wires OTel providers, the EventBus bridge, and
+ * the TelemetryCollector transport in a single invocation. Consumers
+ * who don't use OTel pay nothing — if no provider is registered all
+ * instrumentation is a no-op.
+ *
+ * @module runtime/otel-init
+ */
+import { initializeOTel, shutdownOTel } from './otel.js';
+import { bridgeEventBusToOTel, createOTelTransport } from './otel-bridge.js';
+import { setTelemetryTransport } from './telemetry.js';
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * One-call OTel setup for Squad SDK consumers.
+ *
+ * This is the **high-level** entry point. It:
+ * 1. Initializes tracing and metrics via `initializeOTel()`.
+ * 2. Optionally bridges an {@link EventBus} so every Squad event
+ *    becomes an OTel span.
+ * 3. Optionally installs an OTel-backed `TelemetryTransport` so
+ *    the existing `TelemetryCollector` pipeline emits spans too.
+ *
+ * If no `OTEL_EXPORTER_OTLP_ENDPOINT` env var is set **and** no
+ * `endpoint` is provided in `options`, everything remains a no-op.
+ *
+ * @param options - Configuration and optional EventBus.
+ * @returns A handle with `tracing`, `metrics` status booleans and a
+ *          `shutdown()` method for graceful cleanup.
+ *
+ * @example
+ * ```ts
+ * import { initSquadTelemetry, EventBus } from 'squad-sdk';
+ *
+ * const bus = new EventBus();
+ * const telemetry = initSquadTelemetry({
+ *   endpoint: 'http://localhost:4318',
+ *   eventBus: bus,
+ * });
+ *
+ * // … run your squad …
+ *
+ * await telemetry.shutdown();
+ * ```
+ */
+export function initSquadTelemetry(options = {}) {
+    const { eventBus, installTransport = true, ...otelConfig } = options;
+    const result = initializeOTel(otelConfig);
+    let unsubscribeBridge;
+    if (eventBus) {
+        unsubscribeBridge = bridgeEventBusToOTel(eventBus);
+    }
+    if (installTransport) {
+        setTelemetryTransport(createOTelTransport());
+    }
+    return {
+        tracing: result.tracing,
+        metrics: result.metrics,
+        shutdown: async () => {
+            unsubscribeBridge?.();
+            await shutdownOTel();
+        },
+    };
+}
+/**
+ * Convenience wrapper for Copilot agent-mode telemetry.
+ *
+ * Pre-configures `serviceName` to `'squad-copilot-agent'` and
+ * `mode` to `'copilot-agent'` so the two surfaces (CLI vs agent)
+ * are distinguishable in dashboards and trace queries.
+ *
+ * Call this at agent-mode startup; call `handle.shutdown()` on exit.
+ *
+ * @param options - Additional overrides (endpoint, eventBus, etc.).
+ */
+export function initAgentModeTelemetry(options = {}) {
+    return initSquadTelemetry({
+        ...options,
+        serviceName: 'squad-copilot-agent',
+        mode: 'copilot-agent',
+    });
+}
+//# sourceMappingURL=otel-init.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"otel-init.js","sourceRoot":"","sources":["../../src/runtime/otel-init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAmCvD,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAiC,EAAE;IACpE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI,EAAE,GAAG,UAAU,EAAE,GAAG,OAAO,CAAC;IAErE,MAAM,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IAE1C,IAAI,iBAA4C,CAAC;IACjD,IAAI,QAAQ,EAAE,CAAC;QACb,iBAAiB,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IACrD,CAAC;IAED,IAAI,gBAAgB,EAAE,CAAC;QACrB,qBAAqB,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,QAAQ,EAAE,KAAK,IAAI,EAAE;YACnB,iBAAiB,EAAE,EAAE,CAAC;YACtB,MAAM,YAAY,EAAE,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,UAA+D,EAAE;IACtG,OAAO,kBAAkB,CAAC;QACxB,GAAG,OAAO;QACV,WAAW,EAAE,qBAAqB;QAClC,IAAI,EAAE,eAAe;KACtB,CAAC,CAAC;AACL,CAAC"}