@portel/photon 1.21.0 → 1.22.1

package/dist/shared/logger.js

@@ -1,3 +1,5 @@
+import { getRequestContext } from '../telemetry/context.js';
+import { emitOtelLog } from '../telemetry/logs.js';
 const LEVEL_PRIORITY = {
     error: 0,
     warn: 1,
@@ -45,6 +47,21 @@ export class Logger {
             component: this.component,
             scope: this.scope,
         };
+        // Enrich with ambient request context so every log line emitted during a
+        // tool call carries photon/tool/traceId without callers threading it.
+        // Static ESM import — same module instance as the rest of the runtime
+        // so the AsyncLocalStorage store is shared.
+        const ctx = getRequestContext();
+        if (ctx) {
+            if (ctx.photon && record.photon == null)
+                record.photon = ctx.photon;
+            if (ctx.tool && record.tool == null)
+                record.tool = ctx.tool;
+            if (ctx.traceId && record.traceId == null)
+                record.traceId = ctx.traceId;
+            if (ctx.caller?.id && record.callerId == null)
+                record.callerId = ctx.caller.id;
+        }
         if (meta && Object.keys(meta).length > 0) {
             Object.assign(record, meta);
         }
@@ -85,6 +102,23 @@ export class Logger {
         if (this.sink) {
             this.sink({ ...record });
         }
+        // Forward to the OTel logs bridge when the SDK is installed. The bridge
+        // is a no-op otherwise so this adds no cost when unused.
+        try {
+            const attrs = {};
+            if (this.component)
+                attrs['log.component'] = this.component;
+            if (this.scope)
+                attrs['log.scope'] = this.scope;
+            if (meta) {
+                for (const [k, v] of Object.entries(meta))
+                    attrs[k] = v;
+            }
+            emitOtelLog({ level, message, attributes: attrs });
+        }
+        catch {
+            /* logs bridge unavailable */
+        }
     }
     info(message, meta) {
         this.log('info', message, meta);

package/dist/shared/logger.js.map

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

package/dist/telemetry/context.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Per-request ambient context for Photon tool execution.
+ *
+ * Uses Node's AsyncLocalStorage to make trace/caller context available
+ * anywhere in the async call tree without parameter threading. Populated
+ * by PhotonLoader.executeTool; consumed by the structured Logger, metrics
+ * recorders, and any user code via getRequestContext().
+ */
+import type { CallerInfo } from '@portel/photon-core';
+export interface RequestContext {
+    photon: string;
+    tool: string;
+    /** W3C 32-hex trace ID when the execution is async or correlated. */
+    traceId?: string;
+    /** Inbound W3C traceparent (`00-{traceId}-{spanId}-{flags}`) when present. */
+    parentTraceparent?: string;
+    /** Authenticated caller when available. */
+    caller?: CallerInfo;
+    /** Wall-clock start of the tool call. */
+    startedAt: number;
+}
+export declare function runWithRequestContext<T>(ctx: RequestContext, fn: () => T): T;
+export declare function getRequestContext(): RequestContext | undefined;
+//# sourceMappingURL=context.d.ts.map

package/dist/telemetry/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/telemetry/context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE5E;AAED,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D"}

package/dist/telemetry/context.js

@@ -0,0 +1,17 @@
+/**
+ * Per-request ambient context for Photon tool execution.
+ *
+ * Uses Node's AsyncLocalStorage to make trace/caller context available
+ * anywhere in the async call tree without parameter threading. Populated
+ * by PhotonLoader.executeTool; consumed by the structured Logger, metrics
+ * recorders, and any user code via getRequestContext().
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+const storage = new AsyncLocalStorage();
+export function runWithRequestContext(ctx, fn) {
+    return storage.run(ctx, fn);
+}
+export function getRequestContext() {
+    return storage.getStore();
+}
+//# sourceMappingURL=context.js.map

package/dist/telemetry/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/telemetry/context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAgBrD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAkB,CAAC;AAExD,MAAM,UAAU,qBAAqB,CAAI,GAAmB,EAAE,EAAW;IACvE,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC"}

package/dist/telemetry/logs.d.ts

@@ -0,0 +1,38 @@
+/**
+ * OpenTelemetry Logs bridge for Photon.
+ *
+ * Zero-dep no-op that upgrades gracefully when
+ * `@opentelemetry/api-logs` is installed. Mirrors the dynamic-import
+ * pattern used in otel.ts and metrics.ts so the runtime stays
+ * dependency-free by default and production deployments can wire up
+ * any OTLP-compatible log backend by installing the SDK.
+ *
+ * The photon Logger pushes each emitted record through `emitOtelLog`
+ * after writing to its local stream. When the SDK is present the
+ * record is forwarded to the OTel logs bridge with severity mapped
+ * to the standard scale and ambient trace context auto-attached.
+ */
+export interface OtelLogRecord {
+    level: 'debug' | 'info' | 'warn' | 'error';
+    message: string;
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Emit a log record to OpenTelemetry if the SDK is installed. No-op otherwise.
+ * The ambient request context (photon/tool/traceId/callerId) is pulled lazily
+ * so callers do not have to thread it through.
+ */
+export declare function emitOtelLog(record: OtelLogRecord): void;
+/**
+ * Returns true if the OTel logs SDK is available.
+ */
+export declare function isOtelLogsEnabled(): boolean;
+/**
+ * Wait for the initial probe. For tests.
+ */
+export declare function waitForLogsProbe(): Promise<void>;
+/**
+ * Reset cached state. For tests only.
+ */
+export declare function _resetLogsCache(): void;
+//# sourceMappingURL=logs.d.ts.map

package/dist/telemetry/logs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logs.d.ts","sourceRoot":"","sources":["../../src/telemetry/logs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA6CH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAyBvD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED;;GAEG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAEtD;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAGtC"}

package/dist/telemetry/logs.js

@@ -0,0 +1,108 @@
+/**
+ * OpenTelemetry Logs bridge for Photon.
+ *
+ * Zero-dep no-op that upgrades gracefully when
+ * `@opentelemetry/api-logs` is installed. Mirrors the dynamic-import
+ * pattern used in otel.ts and metrics.ts so the runtime stays
+ * dependency-free by default and production deployments can wire up
+ * any OTLP-compatible log backend by installing the SDK.
+ *
+ * The photon Logger pushes each emitted record through `emitOtelLog`
+ * after writing to its local stream. When the SDK is present the
+ * record is forwarded to the OTel logs bridge with severity mapped
+ * to the standard scale and ambient trace context auto-attached.
+ */
+import { getRequestContext } from './context.js';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let otelLogsApi;
+async function loadOtelLogsApi() {
+    if (otelLogsApi !== undefined)
+        return otelLogsApi;
+    try {
+        const moduleName = '@opentelemetry/api-logs';
+        otelLogsApi = await import(/* webpackIgnore: true */ moduleName);
+        return otelLogsApi;
+    }
+    catch {
+        otelLogsApi = null;
+        return null;
+    }
+}
+const logsReady = loadOtelLogsApi();
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let cachedLogger;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function getOtelLogger() {
+    if (!otelLogsApi)
+        return null;
+    if (cachedLogger)
+        return cachedLogger;
+    try {
+        cachedLogger = otelLogsApi.logs?.getLogger?.('photon', '1.0.0') ?? null;
+        return cachedLogger;
+    }
+    catch {
+        return null;
+    }
+}
+// OTel SeverityNumber scale (RFC 5424-ish).
+const SEVERITY = {
+    debug: 5,
+    info: 9,
+    warn: 13,
+    error: 17,
+    fatal: 21,
+};
+/**
+ * Emit a log record to OpenTelemetry if the SDK is installed. No-op otherwise.
+ * The ambient request context (photon/tool/traceId/callerId) is pulled lazily
+ * so callers do not have to thread it through.
+ */
+export function emitOtelLog(record) {
+    const otelLogger = getOtelLogger();
+    if (!otelLogger)
+        return;
+    const attributes = { ...(record.attributes ?? {}) };
+    const ctx = getRequestContext();
+    if (ctx) {
+        if (ctx.photon && attributes['photon.name'] == null)
+            attributes['photon.name'] = ctx.photon;
+        if (ctx.tool && attributes['photon.tool'] == null)
+            attributes['photon.tool'] = ctx.tool;
+        if (ctx.traceId && attributes['photon.trace_id'] == null)
+            attributes['photon.trace_id'] = ctx.traceId;
+        if (ctx.caller?.id && attributes['photon.caller_id'] == null)
+            attributes['photon.caller_id'] = ctx.caller.id;
+    }
+    try {
+        otelLogger.emit({
+            severityNumber: SEVERITY[record.level] ?? SEVERITY.info,
+            severityText: record.level.toUpperCase(),
+            body: record.message,
+            attributes,
+        });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Returns true if the OTel logs SDK is available.
+ */
+export function isOtelLogsEnabled() {
+    return otelLogsApi != null && getOtelLogger() != null;
+}
+/**
+ * Wait for the initial probe. For tests.
+ */
+export async function waitForLogsProbe() {
+    await logsReady;
+}
+/**
+ * Reset cached state. For tests only.
+ */
+export function _resetLogsCache() {
+    otelLogsApi = undefined;
+    cachedLogger = undefined;
+}
+//# sourceMappingURL=logs.js.map

package/dist/telemetry/logs.js.map

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

package/dist/telemetry/metrics.d.ts

@@ -0,0 +1,71 @@
+/**
+ * OpenTelemetry GenAI Metrics for Photon
+ *
+ * Zero-dependency metrics wrappers that no-op when @opentelemetry/api is not
+ * installed. Mirrors the pattern in otel.ts for traces.
+ *
+ * Metric names follow OTel GenAI semantic conventions where applicable and
+ * `photon.*` for runtime-specific instruments.
+ */
+export interface PhotonCounter {
+    add(value: number, attributes?: Record<string, string | number | boolean>): void;
+}
+export interface PhotonHistogram {
+    record(value: number, attributes?: Record<string, string | number | boolean>): void;
+}
+/**
+ * Record a tool-call completion. Emits to both a latency histogram and a call
+ * counter so operators can derive rate, error rate, and p95/p99 from one pair.
+ */
+export declare function recordToolCall(params: {
+    photon: string;
+    tool: string;
+    durationMs: number;
+    status: 'ok' | 'error';
+    errorType?: string;
+    stateful?: boolean;
+}): void;
+/**
+ * Record a rate-limit rejection. Incremented every time a `@throttled`
+ * or `@rateLimit` middleware throws `PhotonRateLimitError`.
+ */
+export declare function recordRateLimitRejection(params: {
+    photon: string;
+    tool: string;
+    instance?: string;
+}): void;
+/**
+ * Record a bulkhead rejection. Incremented every time the @bulkhead
+ * middleware throws PhotonBulkheadFullError because concurrent-execution
+ * cap was reached.
+ */
+export declare function recordBulkheadRejection(params: {
+    photon: string;
+    tool: string;
+    instance?: string;
+}): void;
+/**
+ * Record a circuit-breaker state transition.
+ * Attributes capture the photon/tool key and the new state so dashboards can
+ * alert on "open" without sampling the call stream.
+ */
+export declare function recordCircuitStateChange(params: {
+    photon: string;
+    tool: string;
+    instance?: string;
+    from: 'closed' | 'open' | 'half-open';
+    to: 'closed' | 'open' | 'half-open';
+}): void;
+/**
+ * Returns true if OpenTelemetry metrics are available.
+ */
+export declare function isMetricsEnabled(): boolean;
+/**
+ * Wait for the initial OTel probe. For tests.
+ */
+export declare function waitForMetricsProbe(): Promise<void>;
+/**
+ * Reset cached state. For tests only.
+ */
+export declare function _resetMetricsCache(): void;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/telemetry/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/telemetry/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC;CAClF;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC;CACrF;AA0FD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,IAAI,CAgBP;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,IAAI,CAWP;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,IAAI,CAWP;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,EAAE,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;CACrC,GAAG,IAAI,CAYP;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED;;GAEG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAEzD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAIzC"}

package/dist/telemetry/metrics.js

@@ -0,0 +1,184 @@
+/**
+ * OpenTelemetry GenAI Metrics for Photon
+ *
+ * Zero-dependency metrics wrappers that no-op when @opentelemetry/api is not
+ * installed. Mirrors the pattern in otel.ts for traces.
+ *
+ * Metric names follow OTel GenAI semantic conventions where applicable and
+ * `photon.*` for runtime-specific instruments.
+ */
+const noopCounter = { add() { } };
+const noopHistogram = { record() { } };
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let otelApi;
+async function loadOtelApi() {
+    if (otelApi !== undefined)
+        return otelApi;
+    try {
+        const moduleName = '@opentelemetry/api';
+        otelApi = await import(/* webpackIgnore: true */ moduleName);
+        return otelApi;
+    }
+    catch {
+        otelApi = null;
+        return null;
+    }
+}
+const metricsReady = loadOtelApi();
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function getMeterSync() {
+    if (!otelApi)
+        return null;
+    try {
+        return otelApi.metrics?.getMeter?.('photon', '1.0.0') ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// Cache instruments — creating them is cheap but caching makes hot paths snappier.
+const counterCache = new Map();
+const histogramCache = new Map();
+function wrapCounter(otelCounter) {
+    return {
+        add(value, attributes) {
+            try {
+                otelCounter.add(value, attributes);
+            }
+            catch {
+                /* best-effort */
+            }
+        },
+    };
+}
+function wrapHistogram(otelHistogram) {
+    return {
+        record(value, attributes) {
+            try {
+                otelHistogram.record(value, attributes);
+            }
+            catch {
+                /* best-effort */
+            }
+        },
+    };
+}
+function getCounter(name, description, unit) {
+    const cached = counterCache.get(name);
+    if (cached)
+        return cached;
+    const meter = getMeterSync();
+    if (!meter)
+        return noopCounter;
+    try {
+        const counter = meter.createCounter(name, { description, unit });
+        const wrapped = wrapCounter(counter);
+        counterCache.set(name, wrapped);
+        return wrapped;
+    }
+    catch {
+        return noopCounter;
+    }
+}
+function getHistogram(name, description, unit) {
+    const cached = histogramCache.get(name);
+    if (cached)
+        return cached;
+    const meter = getMeterSync();
+    if (!meter)
+        return noopHistogram;
+    try {
+        const histogram = meter.createHistogram(name, { description, unit });
+        const wrapped = wrapHistogram(histogram);
+        histogramCache.set(name, wrapped);
+        return wrapped;
+    }
+    catch {
+        return noopHistogram;
+    }
+}
+/**
+ * Record a tool-call completion. Emits to both a latency histogram and a call
+ * counter so operators can derive rate, error rate, and p95/p99 from one pair.
+ */
+export function recordToolCall(params) {
+    const attrs = {
+        'gen_ai.agent.name': params.photon,
+        'gen_ai.tool.name': params.tool,
+        'gen_ai.operation.name': 'execute_tool',
+        status: params.status,
+    };
+    if (typeof params.stateful === 'boolean')
+        attrs['photon.stateful'] = params.stateful;
+    if (params.errorType)
+        attrs['photon.error_type'] = params.errorType;
+    getHistogram('photon.tool.duration', 'Tool-call duration', 'ms').record(params.durationMs, attrs);
+    getCounter('photon.tool.calls', 'Tool-call count', '1').add(1, attrs);
+    if (params.status === 'error') {
+        getCounter('photon.tool.errors', 'Tool-call errors', '1').add(1, attrs);
+    }
+}
+/**
+ * Record a rate-limit rejection. Incremented every time a `@throttled`
+ * or `@rateLimit` middleware throws `PhotonRateLimitError`.
+ */
+export function recordRateLimitRejection(params) {
+    const attrs = {
+        'gen_ai.agent.name': params.photon,
+        'gen_ai.tool.name': params.tool,
+    };
+    if (params.instance)
+        attrs['photon.instance'] = params.instance;
+    getCounter('photon.rate_limit.rejections', 'Rate-limit rejections (throttled middleware)', '1').add(1, attrs);
+}
+/**
+ * Record a bulkhead rejection. Incremented every time the @bulkhead
+ * middleware throws PhotonBulkheadFullError because concurrent-execution
+ * cap was reached.
+ */
+export function recordBulkheadRejection(params) {
+    const attrs = {
+        'gen_ai.agent.name': params.photon,
+        'gen_ai.tool.name': params.tool,
+    };
+    if (params.instance)
+        attrs['photon.instance'] = params.instance;
+    getCounter('photon.bulkhead.rejections', 'Bulkhead rejections (concurrent-cap exceeded)', '1').add(1, attrs);
+}
+/**
+ * Record a circuit-breaker state transition.
+ * Attributes capture the photon/tool key and the new state so dashboards can
+ * alert on "open" without sampling the call stream.
+ */
+export function recordCircuitStateChange(params) {
+    const attrs = {
+        'gen_ai.agent.name': params.photon,
+        'gen_ai.tool.name': params.tool,
+        from: params.from,
+        to: params.to,
+    };
+    if (params.instance)
+        attrs['photon.instance'] = params.instance;
+    getCounter('photon.circuit_breaker.transitions', 'Circuit-breaker state transitions', '1').add(1, attrs);
+}
+/**
+ * Returns true if OpenTelemetry metrics are available.
+ */
+export function isMetricsEnabled() {
+    return otelApi != null && getMeterSync() != null;
+}
+/**
+ * Wait for the initial OTel probe. For tests.
+ */
+export async function waitForMetricsProbe() {
+    await metricsReady;
+}
+/**
+ * Reset cached state. For tests only.
+ */
+export function _resetMetricsCache() {
+    otelApi = undefined;
+    counterCache.clear();
+    histogramCache.clear();
+}
+//# sourceMappingURL=metrics.js.map

package/dist/telemetry/metrics.js.map

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

package/dist/telemetry/otel.d.ts

@@ -9,12 +9,31 @@ export interface PhotonSpan {
     setAttribute(key: string, value: string | number | boolean): void;
     addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
     setStatus(code: 'OK' | 'ERROR', message?: string): void;
+    recordException(error: unknown): void;
     end(): void;
 }
+/**
+ * Parse a W3C traceparent header into its components.
+ * Format: `{version}-{traceId}-{parentSpanId}-{flags}` (e.g. `00-abc...-def...-01`).
+ * Returns null if the header is malformed.
+ */
+export declare function parseTraceparent(traceparent: string | undefined | null): {
+    version: string;
+    traceId: string;
+    spanId: string;
+    flags: string;
+} | null;
 /**
  * Start a span for tool execution following GenAI semantic conventions.
+ * @param traceId - Optional W3C-compatible trace ID (32 hex chars) for async executions.
+ *   When provided, set as `photon.trace_id` on the span so async executions are
+ *   correlated with the execution ID returned to the caller.
+ * @param stateful - When true, sets `photon.stateful=true` on the span.
+ * @param parentTraceparent - Optional W3C traceparent header. When provided, the new
+ *   span is created as a child of that remote span context so distributed traces
+ *   chain across client → photon → downstream calls.
  */
-export declare function startToolSpan(photon: string, tool: string, params?: Record<string, unknown>): PhotonSpan;
+export declare function startToolSpan(photon: string, tool: string, params?: Record<string, unknown>, traceId?: string, stateful?: boolean, parentTraceparent?: string): PhotonSpan;
 /**
  * Start a span for agent-level invocation following GenAI semantic conventions.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../../src/telemetry/otel.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,UAAU;IACzB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC;IACrF,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxD,GAAG,IAAI,IAAI,CAAC;CACb;AA0DD;;GAEG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,UAAU,CAmBZ;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU,CAa/E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAEtD;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}
+{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../../src/telemetry/otel.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,UAAU;IACzB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC;IACrF,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxD,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACtC,GAAG,IAAI,IAAI,CAAC;CACb;AA8ED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GACrC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAY5E;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,OAAO,EAClB,iBAAiB,CAAC,EAAE,MAAM,GACzB,UAAU,CA2CZ;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU,CAa/E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAEtD;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}