@portel/photon 1.21.0 → 1.22.0

package/dist/telemetry/otel.js

@@ -9,6 +9,7 @@ const noopSpan = {
     setAttribute() { },
     addEvent() { },
     setStatus() { },
+    recordException() { },
     end() { },
 };
 // Cached reference to the OTel API (undefined = not yet checked, null = not available)
@@ -53,23 +54,99 @@ function wrapOtelSpan(otelSpan, otelApi) {
         setStatus(code, message) {
             const statusCode = code === 'OK' ? otelApi.SpanStatusCode.OK : otelApi.SpanStatusCode.ERROR;
             otelSpan.setStatus({ code: statusCode, message });
+            // Force-sample failed spans even under head-based sampling
+            if (code === 'ERROR') {
+                try {
+                    otelSpan.setAttribute('sampling.priority', 1);
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+        },
+        recordException(error) {
+            try {
+                if (error instanceof Error) {
+                    otelSpan.recordException(error);
+                }
+                else {
+                    otelSpan.recordException(new Error(String(error)));
+                }
+            }
+            catch {
+                /* best-effort */
+            }
         },
         end() {
             otelSpan.end();
         },
     };
 }
+/**
+ * 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 function parseTraceparent(traceparent) {
+    if (!traceparent || typeof traceparent !== 'string')
+        return null;
+    const parts = traceparent.trim().split('-');
+    if (parts.length !== 4)
+        return null;
+    const [version, traceId, spanId, flags] = parts;
+    if (version.length !== 2 || traceId.length !== 32 || spanId.length !== 16 || flags.length !== 2) {
+        return null;
+    }
+    if (!/^[0-9a-f]+$/i.test(traceId) || !/^[0-9a-f]+$/i.test(spanId))
+        return null;
+    // All-zero trace/span IDs are invalid per the spec.
+    if (/^0+$/.test(traceId) || /^0+$/.test(spanId))
+        return null;
+    return { version, traceId, spanId, flags };
+}
 /**
  * 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 function startToolSpan(photon, tool, params) {
+export function startToolSpan(photon, tool, params, traceId, stateful, parentTraceparent) {
     const tracer = getTracerSync();
     if (!tracer)
         return noopSpan;
-    const span = tracer.startSpan(`gen_ai.tool.call ${photon}.${tool}`);
+    const parent = parseTraceparent(parentTraceparent);
+    let span;
+    if (parent && otelApi?.trace && otelApi?.context) {
+        try {
+            const spanContext = {
+                traceId: parent.traceId,
+                spanId: parent.spanId,
+                traceFlags: parseInt(parent.flags, 16) || 0,
+                isRemote: true,
+            };
+            const ctx = otelApi.trace.setSpanContext(otelApi.context.active(), spanContext);
+            span = tracer.startSpan(`gen_ai.tool.call ${photon}.${tool}`, undefined, ctx);
+        }
+        catch {
+            span = tracer.startSpan(`gen_ai.tool.call ${photon}.${tool}`);
+        }
+    }
+    else {
+        span = tracer.startSpan(`gen_ai.tool.call ${photon}.${tool}`);
+    }
     span.setAttribute('gen_ai.tool.name', tool);
     span.setAttribute('gen_ai.agent.name', photon);
     span.setAttribute('gen_ai.operation.name', 'execute_tool');
+    if (traceId) {
+        span.setAttribute('photon.trace_id', traceId);
+    }
+    if (typeof stateful === 'boolean') {
+        span.setAttribute('photon.stateful', stateful);
+    }
     if (params) {
         const paramKeys = Object.keys(params);
         if (paramKeys.length > 0) {

package/dist/telemetry/otel.js.map

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

package/dist/telemetry/sdk.d.ts

@@ -0,0 +1,49 @@
+/**
+ * OpenTelemetry NodeSDK bootstrap for Photon.
+ *
+ * Zero required dependencies. When `OTEL_EXPORTER_OTLP_ENDPOINT` is set in
+ * the environment AND `@opentelemetry/sdk-node` is installed, the runtime
+ * wires up OTLP exporters for traces, metrics, and logs so every span,
+ * counter, histogram, and log record emitted elsewhere in the codebase
+ * lands in an OTLP-compatible backend (Jaeger, Grafana Tempo, SigNoz,
+ * Honeycomb, DataDog, etc.) without further configuration.
+ *
+ * This is the final piece that makes the instrumentation shipped in
+ * otel.ts / metrics.ts / logs.ts observable in practice.
+ */
+import type { PhotonSpan } from './otel.js';
+/**
+ * Returns true if the caller has opted into OTel export via the standard
+ * environment variable. The OTel spec treats `OTEL_EXPORTER_OTLP_ENDPOINT`
+ * as the universal switch.
+ */
+export declare function isOtelRequested(): boolean;
+export interface OtelSdkOptions {
+    /** Service name attached to every exported record. Defaults to `photon`. */
+    serviceName?: string;
+    /** Service version. Defaults to PHOTON_VERSION if available. */
+    serviceVersion?: string;
+    /** Deployment environment (e.g. "prod", "staging"). */
+    deploymentEnvironment?: string;
+}
+/**
+ * Start the OTel NodeSDK if the env + dependencies are present.
+ *
+ * Idempotent — safe to call multiple times. Returns true if the SDK was
+ * actually started, false if the bootstrap was skipped (env missing, SDK
+ * not installed, or already running).
+ *
+ * Call this as early as possible in process startup, before any photon
+ * code runs, so spans from the very first tool call are captured.
+ */
+export declare function initOtelSdk(options?: OtelSdkOptions): Promise<boolean>;
+/**
+ * Shut down the SDK and flush exporters. For tests.
+ */
+export declare function shutdownOtelSdk(): Promise<void>;
+/**
+ * Returns true if the SDK has been started in this process.
+ */
+export declare function isOtelSdkStarted(): boolean;
+export type { PhotonSpan };
+//# sourceMappingURL=sdk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/telemetry/sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAK5C;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAyDhF;AAED;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAWrD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAID,YAAY,EAAE,UAAU,EAAE,CAAC"}

package/dist/telemetry/sdk.js

@@ -0,0 +1,110 @@
+/**
+ * OpenTelemetry NodeSDK bootstrap for Photon.
+ *
+ * Zero required dependencies. When `OTEL_EXPORTER_OTLP_ENDPOINT` is set in
+ * the environment AND `@opentelemetry/sdk-node` is installed, the runtime
+ * wires up OTLP exporters for traces, metrics, and logs so every span,
+ * counter, histogram, and log record emitted elsewhere in the codebase
+ * lands in an OTLP-compatible backend (Jaeger, Grafana Tempo, SigNoz,
+ * Honeycomb, DataDog, etc.) without further configuration.
+ *
+ * This is the final piece that makes the instrumentation shipped in
+ * otel.ts / metrics.ts / logs.ts observable in practice.
+ */
+let started = false;
+let sdkInstance;
+/**
+ * Returns true if the caller has opted into OTel export via the standard
+ * environment variable. The OTel spec treats `OTEL_EXPORTER_OTLP_ENDPOINT`
+ * as the universal switch.
+ */
+export function isOtelRequested() {
+    return Boolean(process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.OTEL_SDK_DISABLED === '0');
+}
+/**
+ * Start the OTel NodeSDK if the env + dependencies are present.
+ *
+ * Idempotent — safe to call multiple times. Returns true if the SDK was
+ * actually started, false if the bootstrap was skipped (env missing, SDK
+ * not installed, or already running).
+ *
+ * Call this as early as possible in process startup, before any photon
+ * code runs, so spans from the very first tool call are captured.
+ */
+export async function initOtelSdk(options = {}) {
+    if (started)
+        return false;
+    if (!isOtelRequested())
+        return false;
+    try {
+        const sdkNodeModule = '@opentelemetry/sdk-node';
+        const resourcesModule = '@opentelemetry/resources';
+        const semconvModule = '@opentelemetry/semantic-conventions';
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const sdkNode = await import(/* webpackIgnore: true */ sdkNodeModule);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const resources = await import(/* webpackIgnore: true */ resourcesModule);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const semconv = await import(/* webpackIgnore: true */ semconvModule);
+        const attrs = {
+            [semconv.SemanticResourceAttributes?.SERVICE_NAME ?? 'service.name']: options.serviceName || process.env.OTEL_SERVICE_NAME || 'photon',
+        };
+        if (options.serviceVersion) {
+            attrs[semconv.SemanticResourceAttributes?.SERVICE_VERSION ?? 'service.version'] =
+                options.serviceVersion;
+        }
+        if (options.deploymentEnvironment) {
+            attrs['deployment.environment'] = options.deploymentEnvironment;
+        }
+        const resource = resources.Resource?.default
+            ? resources.Resource.default().merge(new resources.Resource(attrs))
+            : new resources.Resource(attrs);
+        const sdk = new sdkNode.NodeSDK({
+            resource,
+            // The SDK auto-detects OTLP exporters from OTEL_EXPORTER_OTLP_ENDPOINT
+            // and OTEL_EXPORTER_OTLP_PROTOCOL (grpc, http/protobuf, http/json).
+        });
+        sdk.start();
+        sdkInstance = sdk;
+        started = true;
+        // Graceful shutdown on process exit — flush pending spans/metrics/logs.
+        const shutdown = () => {
+            void sdk.shutdown?.().catch(() => {
+                /* best-effort */
+            });
+        };
+        process.once('SIGTERM', shutdown);
+        process.once('SIGINT', shutdown);
+        process.once('beforeExit', shutdown);
+        return true;
+    }
+    catch {
+        // SDK not installed or bootstrap failed — stay silent. The runtime's
+        // no-op wrappers in otel.ts/metrics.ts/logs.ts continue to work.
+        return false;
+    }
+}
+/**
+ * Shut down the SDK and flush exporters. For tests.
+ */
+export async function shutdownOtelSdk() {
+    if (!started)
+        return;
+    started = false;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const sdk = sdkInstance;
+    try {
+        await sdk?.shutdown?.();
+    }
+    catch {
+        /* best-effort */
+    }
+    sdkInstance = undefined;
+}
+/**
+ * Returns true if the SDK has been started in this process.
+ */
+export function isOtelSdkStarted() {
+    return started;
+}
+//# sourceMappingURL=sdk.js.map

package/dist/telemetry/sdk.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portel/photon",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "description": "You focus on the business logic. We'll enable the rest. Build MCP servers and CLI tools in a single TypeScript file.",
   "type": "module",
   "main": "dist/index.js",
@@ -112,7 +112,7 @@
     "@modelcontextprotocol/ext-apps": "^1.0.1",
     "@modelcontextprotocol/sdk": "^1.25.2",
     "@portel/cli": "^1.1.0",
-    "@portel/photon-core": "^2.19.1",
+    "@portel/photon-core": "^2.22.0",
     "boxen": "^8.0.1",
     "chalk": "^5.4.1",
     "chart.js": "^4.5.1",