@lunora/agent 1.0.0-alpha.5 → 1.0.0-alpha.7

package/dist/packem_shared/otlpTelemetry-DL6iZ9e2.mjs

@@ -0,0 +1,164 @@
+import { s as summarizeUsage, c as contentText, r as readField, t as toolInputOf, a as toolNameOf } from './common-DAeFCot5.mjs';
+
+const otlpUnixNano = (ms) => `${String(Math.round(ms))}000000`;
+const otlpRandomHex = (bytes) => {
+  const buffer = new Uint8Array(bytes);
+  crypto.getRandomValues(buffer);
+  let hex = "";
+  for (const byte of buffer) {
+    hex += byte.toString(16).padStart(2, "0");
+  }
+  return hex;
+};
+const encodeAttribute = (key, value) => {
+  if (typeof value === "boolean") {
+    return { key, value: { boolValue: value } };
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      return { key, value: { stringValue: String(value) } };
+    }
+    return Number.isSafeInteger(value) ? { key, value: { intValue: String(value) } } : { key, value: { doubleValue: value } };
+  }
+  return { key, value: { stringValue: value } };
+};
+const mergeHeaders = (defaults, overrides, token) => {
+  const merged = {};
+  const seen = /* @__PURE__ */ new Map();
+  const put = (name, value) => {
+    const lower = name.toLowerCase();
+    const existing = seen.get(lower);
+    if (existing === void 0) {
+      seen.set(lower, name);
+      merged[name] = value;
+    } else {
+      merged[existing] = value;
+    }
+  };
+  for (const [name, value] of Object.entries(defaults)) {
+    put(name, value);
+  }
+  for (const [name, value] of Object.entries(overrides ?? {})) {
+    put(name, value);
+  }
+  if (token !== void 0 && token.length > 0) {
+    put("authorization", `Bearer ${token}`);
+  }
+  return merged;
+};
+const wrapResourceSpans = (span, scopeName, serviceName) => {
+  return {
+    resourceSpans: [
+      {
+        resource: { attributes: [encodeAttribute("service.name", serviceName)] },
+        scopeSpans: [{ scope: { name: scopeName }, spans: [span] }]
+      }
+    ]
+  };
+};
+
+const pushAttribute = (attributes, key, value) => {
+  if (value === void 0 || value === null) {
+    return;
+  }
+  if (typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+    attributes.push(encodeAttribute(key, value));
+    return;
+  }
+  attributes.push(encodeAttribute(key, JSON.stringify(value)));
+};
+const otlpTelemetry = (options) => {
+  const { endpoint, headers, recordInputs = false, recordOutputs = false, token, traceId: fixedTraceId, waitUntil } = options;
+  const serviceName = options.serviceName ?? "lunora";
+  let base = endpoint;
+  while (base.endsWith("/")) {
+    base = base.slice(0, -1);
+  }
+  const tracesUrl = `${base}/v1/traces`;
+  const mergedHeaders = mergeHeaders({ "content-type": "application/json" }, headers, token);
+  const emitSpan = (name, startTs, ok, message, attributes) => {
+    const span = {
+      attributes,
+      endTimeUnixNano: otlpUnixNano(Date.now()),
+      // SPAN_KIND_INTERNAL — matches the runtime's `ctx.trace` spans.
+      kind: 1,
+      name,
+      spanId: otlpRandomHex(8),
+      startTimeUnixNano: otlpUnixNano(startTs),
+      // STATUS_CODE_OK (1) / STATUS_CODE_ERROR (2).
+      status: ok ? { code: 1 } : { code: 2, message: message ?? "" },
+      traceId: fixedTraceId ?? otlpRandomHex(16)
+    };
+    try {
+      const sent = fetch(tracesUrl, {
+        body: JSON.stringify(wrapResourceSpans(span, "@lunora/agent", serviceName)),
+        headers: mergedHeaders,
+        method: "POST"
+      }).catch(() => {
+      });
+      waitUntil?.(sent);
+    } catch {
+    }
+  };
+  return {
+    executeLanguageModelCall: (options_) => {
+      const startTs = Date.now();
+      const modelId = readField(options_, "modelId");
+      const promise = options_.execute();
+      const emit = (ok, message, result) => {
+        const attributes = [];
+        pushAttribute(attributes, "gen_ai.operation.name", "chat");
+        pushAttribute(attributes, "gen_ai.request.model", modelId);
+        pushAttribute(attributes, "gen_ai.system", readField(options_, "provider"));
+        const usage = summarizeUsage(readField(result, "usage"));
+        if (usage) {
+          pushAttribute(attributes, "gen_ai.usage.input_tokens", usage.inputTokens);
+          pushAttribute(attributes, "gen_ai.usage.output_tokens", usage.outputTokens);
+          pushAttribute(attributes, "gen_ai.usage.total_tokens", usage.totalTokens);
+        }
+        if (recordInputs) {
+          pushAttribute(attributes, "gen_ai.prompt", readField(options_, "messages"));
+        }
+        if (recordOutputs) {
+          pushAttribute(attributes, "gen_ai.completion", contentText(readField(result, "content")));
+        }
+        emitSpan(typeof modelId === "string" ? `chat ${modelId}` : "language_model_call", startTs, ok, message, attributes);
+      };
+      promise.then(
+        (result) => {
+          emit(true, void 0, result);
+        },
+        (error) => {
+          emit(false, error instanceof Error ? error.message : String(error), void 0);
+        }
+      );
+      return promise;
+    },
+    executeTool: (options_) => {
+      const startTs = Date.now();
+      const toolName = toolNameOf(options_);
+      const promise = options_.execute();
+      const emit = (ok, message) => {
+        const attributes = [];
+        pushAttribute(attributes, "gen_ai.operation.name", "execute_tool");
+        pushAttribute(attributes, "gen_ai.tool.name", toolName);
+        pushAttribute(attributes, "gen_ai.tool.call.id", readField(options_, "toolCallId"));
+        if (recordInputs) {
+          pushAttribute(attributes, "gen_ai.tool.input", toolInputOf(options_));
+        }
+        emitSpan(typeof toolName === "string" ? `execute_tool ${toolName}` : "execute_tool", startTs, ok, message, attributes);
+      };
+      promise.then(
+        () => {
+          emit(true, void 0);
+        },
+        (error) => {
+          emit(false, error instanceof Error ? error.message : String(error));
+        }
+      );
+      return promise;
+    }
+  };
+};
+
+export { otlpTelemetry };

package/dist/telemetry/index.d.mts

@@ -122,6 +122,78 @@ interface ConsoleTelemetryOptions extends CommonOptions {
  * @experimental
  */
 declare const consoleTelemetry: (options?: ConsoleTelemetryOptions) => Telemetry;
+/**
+ * Options for {@link otlpTelemetry}.
+ * @experimental
+ */
+interface OtlpTelemetryOptions extends CommonOptions {
+  /**
+   * The OTLP-over-HTTP collector base endpoint (e.g. the Lunora Cloud's `/v1`
+   * base). Spans are POSTed to `${endpoint}/v1/traces`; a trailing slash is
+   * tolerated. On the platform this is the injected `LUNORA_OTLP_ENDPOINT`.
+   */
+  endpoint: string;
+  /**
+   * Extra headers merged onto every POST — typically the correlation headers
+   * the platform injects. `Content-Type: application/json` is set by default.
+   */
+  headers?: Record<string, string>;
+  /** `service.name` resource attribute on every span. Defaults to `lunora`. */
+  serviceName?: string;
+  /**
+   * Bearer token added as `Authorization: Bearer` (wins over any authorization
+   * in `headers`) — the injected `LUNORA_OTLP_TOKEN`. Omit for an
+   * unauthenticated collector.
+   */
+  token?: string;
+  /**
+   * Trace id (32-hex) to hang every span of this run under, so one agent run
+   * reads as one trace. Pass a stable id derived from the run (e.g. the
+   * workflow run id). Omitted → each span mints its own trace id (still valid,
+   * just ungrouped).
+   */
+  traceId?: string;
+  /**
+   * The Worker request's `waitUntil`, so a fire-and-forget export survives
+   * isolate teardown after the turn returns. Omit and the send degrades to
+   * best-effort.
+   */
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * An OTLP-over-HTTP telemetry integration for `@lunora/agent`.
+ *
+ * The OTLP counterpart to {@link sentryTelemetry} / {@link braintrustTelemetry}:
+ * it wraps each language-model call and tool execution in an OTLP **span**
+ * (`gen_ai.*` semantic-convention attributes — model, provider, token usage,
+ * tool name) and ships it to a collector, so agent generations land in the same
+ * trace store as the rest of an app's telemetry (the Lunora Cloud, or any OTel
+ * collector). Plug it into `defineAgent({ telemetry: { isEnabled: true,
+ * integrations: [otlpTelemetry({ endpoint, token })] } })`.
+ *
+ * Emitting inside the turn's execution wrapper means one span per **real** turn:
+ * the agent loop memoizes each `step.do('llm:turn:N')`, so a Workflow replay
+ * returns the cached result without re-invoking `execute`, and no duplicate span
+ * is emitted. Privacy-safe by default — `recordInputs`/`recordOutputs` both
+ * default `false`, so no prompt or generated text leaves the worker without an
+ * explicit opt-in; only structural metadata + token counts are recorded.
+ *
+ * Each export is fire-and-forget (registered with `waitUntil` when supplied);
+ * every rejection is swallowed so a flaky collector never surfaces to the run.
+ *
+ * Two deliberate differences from the SDK-backed integrations (`sentryTelemetry`
+ * / `braintrustTelemetry`), which delegate to a host tracer:
+ * - **No `onError`.** A failed call already emits a span with `status.code === 2`,
+ *   so the failure is on the trace; there is no host client to also notify.
+ * - **Flat, not nested.** Every span gets `traceId` (shared when `traceId` is set)
+ *   but no `parentSpanId`, so model-call and tool spans are siblings under the run
+ *   rather than a tree — OTLP has no ambient span context to parent to here.
+ * @param options `endpoint` (+ optional `token`/`headers`/`serviceName`),
+ * `traceId` to group a run's spans, `waitUntil`, and the `recordInputs`/
+ * `recordOutputs` privacy flags.
+ * @experimental
+ */
+declare const otlpTelemetry: (options: OtlpTelemetryOptions) => Telemetry;
 /**
  * The minimal, **structural** slice of `@sentry/cloudflare` (equivalently
  * `@sentry/node`/`@sentry/browser`) this bridge needs. `@sentry/cloudflare` is
@@ -170,4 +242,4 @@ interface SentryTelemetryOptions extends CommonOptions {
  * @experimental
  */
 declare const sentryTelemetry: (options: SentryTelemetryOptions) => Telemetry;
-export { type BraintrustLike, type BraintrustSpan, type BraintrustTelemetryOptions, type CommonOptions, type ConsoleLogLevel, type ConsoleLogger, type ConsoleTelemetryOptions, type SentryLike, type SentryTelemetryOptions, braintrustTelemetry, combineTelemetry, consoleTelemetry, sentryTelemetry };
+export { type BraintrustLike, type BraintrustSpan, type BraintrustTelemetryOptions, type CommonOptions, type ConsoleLogLevel, type ConsoleLogger, type ConsoleTelemetryOptions, type OtlpTelemetryOptions, type SentryLike, type SentryTelemetryOptions, braintrustTelemetry, combineTelemetry, consoleTelemetry, otlpTelemetry, sentryTelemetry };

package/dist/telemetry/index.d.ts

@@ -122,6 +122,78 @@ interface ConsoleTelemetryOptions extends CommonOptions {
  * @experimental
  */
 declare const consoleTelemetry: (options?: ConsoleTelemetryOptions) => Telemetry;
+/**
+ * Options for {@link otlpTelemetry}.
+ * @experimental
+ */
+interface OtlpTelemetryOptions extends CommonOptions {
+  /**
+   * The OTLP-over-HTTP collector base endpoint (e.g. the Lunora Cloud's `/v1`
+   * base). Spans are POSTed to `${endpoint}/v1/traces`; a trailing slash is
+   * tolerated. On the platform this is the injected `LUNORA_OTLP_ENDPOINT`.
+   */
+  endpoint: string;
+  /**
+   * Extra headers merged onto every POST — typically the correlation headers
+   * the platform injects. `Content-Type: application/json` is set by default.
+   */
+  headers?: Record<string, string>;
+  /** `service.name` resource attribute on every span. Defaults to `lunora`. */
+  serviceName?: string;
+  /**
+   * Bearer token added as `Authorization: Bearer` (wins over any authorization
+   * in `headers`) — the injected `LUNORA_OTLP_TOKEN`. Omit for an
+   * unauthenticated collector.
+   */
+  token?: string;
+  /**
+   * Trace id (32-hex) to hang every span of this run under, so one agent run
+   * reads as one trace. Pass a stable id derived from the run (e.g. the
+   * workflow run id). Omitted → each span mints its own trace id (still valid,
+   * just ungrouped).
+   */
+  traceId?: string;
+  /**
+   * The Worker request's `waitUntil`, so a fire-and-forget export survives
+   * isolate teardown after the turn returns. Omit and the send degrades to
+   * best-effort.
+   */
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * An OTLP-over-HTTP telemetry integration for `@lunora/agent`.
+ *
+ * The OTLP counterpart to {@link sentryTelemetry} / {@link braintrustTelemetry}:
+ * it wraps each language-model call and tool execution in an OTLP **span**
+ * (`gen_ai.*` semantic-convention attributes — model, provider, token usage,
+ * tool name) and ships it to a collector, so agent generations land in the same
+ * trace store as the rest of an app's telemetry (the Lunora Cloud, or any OTel
+ * collector). Plug it into `defineAgent({ telemetry: { isEnabled: true,
+ * integrations: [otlpTelemetry({ endpoint, token })] } })`.
+ *
+ * Emitting inside the turn's execution wrapper means one span per **real** turn:
+ * the agent loop memoizes each `step.do('llm:turn:N')`, so a Workflow replay
+ * returns the cached result without re-invoking `execute`, and no duplicate span
+ * is emitted. Privacy-safe by default — `recordInputs`/`recordOutputs` both
+ * default `false`, so no prompt or generated text leaves the worker without an
+ * explicit opt-in; only structural metadata + token counts are recorded.
+ *
+ * Each export is fire-and-forget (registered with `waitUntil` when supplied);
+ * every rejection is swallowed so a flaky collector never surfaces to the run.
+ *
+ * Two deliberate differences from the SDK-backed integrations (`sentryTelemetry`
+ * / `braintrustTelemetry`), which delegate to a host tracer:
+ * - **No `onError`.** A failed call already emits a span with `status.code === 2`,
+ *   so the failure is on the trace; there is no host client to also notify.
+ * - **Flat, not nested.** Every span gets `traceId` (shared when `traceId` is set)
+ *   but no `parentSpanId`, so model-call and tool spans are siblings under the run
+ *   rather than a tree — OTLP has no ambient span context to parent to here.
+ * @param options `endpoint` (+ optional `token`/`headers`/`serviceName`),
+ * `traceId` to group a run's spans, `waitUntil`, and the `recordInputs`/
+ * `recordOutputs` privacy flags.
+ * @experimental
+ */
+declare const otlpTelemetry: (options: OtlpTelemetryOptions) => Telemetry;
 /**
  * The minimal, **structural** slice of `@sentry/cloudflare` (equivalently
  * `@sentry/node`/`@sentry/browser`) this bridge needs. `@sentry/cloudflare` is
@@ -170,4 +242,4 @@ interface SentryTelemetryOptions extends CommonOptions {
  * @experimental
  */
 declare const sentryTelemetry: (options: SentryTelemetryOptions) => Telemetry;
-export { type BraintrustLike, type BraintrustSpan, type BraintrustTelemetryOptions, type CommonOptions, type ConsoleLogLevel, type ConsoleLogger, type ConsoleTelemetryOptions, type SentryLike, type SentryTelemetryOptions, braintrustTelemetry, combineTelemetry, consoleTelemetry, sentryTelemetry };
+export { type BraintrustLike, type BraintrustSpan, type BraintrustTelemetryOptions, type CommonOptions, type ConsoleLogLevel, type ConsoleLogger, type ConsoleTelemetryOptions, type OtlpTelemetryOptions, type SentryLike, type SentryTelemetryOptions, braintrustTelemetry, combineTelemetry, consoleTelemetry, otlpTelemetry, sentryTelemetry };

package/dist/telemetry/index.mjs

@@ -1,4 +1,5 @@
 export { braintrustTelemetry } from '../packem_shared/braintrustTelemetry-wuGDErob.mjs';
 export { combineTelemetry } from '../packem_shared/combineTelemetry-DCyaaWAI.mjs';
 export { consoleTelemetry } from '../packem_shared/consoleTelemetry-z2MiP1jt.mjs';
+export { otlpTelemetry } from '../packem_shared/otlpTelemetry-DL6iZ9e2.mjs';
 export { sentryTelemetry } from '../packem_shared/sentryTelemetry-CgqFJyLO.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/agent",
-  "version": "1.0.0-alpha.5",
+  "version": "1.0.0-alpha.7",
   "description": "Durable AI agents for Lunora: defineAgent compiles a replay-safe tool-loop onto Cloudflare Workflows, with DO SQLite threads and live message subscriptions",
   "keywords": [
     "agent",
@@ -76,10 +76,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/ai": "1.0.0-alpha.17",
+    "@lunora/ai": "1.0.0-alpha.18",
     "@lunora/errors": "1.0.0-alpha.6",
     "@lunora/mail": "1.0.0-alpha.16",
-    "@lunora/server": "1.0.0-alpha.28",
+    "@lunora/server": "1.0.0-alpha.29",
     "@lunora/values": "1.0.0-alpha.9",
     "@lunora/workflow": "1.0.0-alpha.11",
     "@modelcontextprotocol/sdk": "^1.29.0",