@keemakr/observability 0.2.0-dev-20261012160211

package/README.md

@@ -0,0 +1,59 @@
+# @keemakr/observability
+
+Keemakr telemetry, in two entry points. One process registers the host once. Everything else traces
+through the runtime and never learns which backend is behind it.
+
+| Entry                         | Who imports it                                                                           | What it does                                                                                                                                    |
+| ----------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@keemakr/observability/host` | The one instrumentation file of a process: Core, Operator, Task Operator, a Pack Runtime | Registers OpenTelemetry via `@vercel/otel`, adds the Langfuse span processor when its keys are set, applies the sampler and the content policy. |
+| `@keemakr/observability`      | Core libraries, `@keemakr/agent-sdk`, Pack code                                          | Execution-context propagation, trace-context helpers, observation names. Plain OpenTelemetry; a no-op with no host.                             |
+
+This follows the Observability PRD: eve's tracing is the agent span model, the host owns the
+provider and exporter, SDKs only participate, metadata is the default and content is an explicit
+decision, W3C `traceparent` is the propagation contract.
+
+## Host
+
+```ts
+// src/instrumentation.ts (Next.js) — or eve's agent/instrumentation.ts `setup`
+import { registerKeemakrTelemetry } from '@keemakr/observability/host';
+
+const telemetry = await registerKeemakrTelemetry({ service: 'keemakr-core' });
+// telemetry.destination  'langfuse' | 'otlp' | 'none'
+// telemetry.recordContent the content decision — hand it to eve / the AI SDK
+// telemetry.flush()       before a serverless function returns
+```
+
+| Variable                                         | Effect                                                                                                                                                                                                                                                                               |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `LANGFUSE_PUBLIC_KEY` + `LANGFUSE_SECRET_KEY`    | Both set: spans go to Langfuse. `LANGFUSE_BASE_URL` selects the instance (default Langfuse Cloud).                                                                                                                                                                                   |
+| `OTEL_EXPORTER_OTLP_ENDPOINT`                    | Any OTLP backend, read by `@vercel/otel`. Works alongside Langfuse.                                                                                                                                                                                                                  |
+| `OTEL_RECORD_CONTENT`                            | `1`/`true` content on, `0`/`false` off. Unset: on only in `development`.                                                                                                                                                                                                             |
+| `VERCEL_GIT_COMMIT_REF`, `VERCEL_GIT_COMMIT_SHA` | Become Langfuse `environment` and `release`. The branch maps `main`→`production`, `stage`→`staging`, `dev`→`dev`; other branches `preview`; a laptop `development`. `VERCEL_ENV` is `production` on all three projects, so it is not used. `LANGFUSE_TRACING_ENVIRONMENT` overrides. |
+
+What reaches Langfuse: spans with `gen_ai.*` attributes (eve, the Vercel AI SDK), eve's own spans,
+any `keemakr-*` tracer, and the root request span so a trace has a root. Framework internals and
+outbound `fetch` spans do not. Root spans for `/api/internal/*`, middleware, `/_next/*` and
+`/api/health` are not sampled at all.
+
+When content capture is off, `gen_ai.input.messages`, `gen_ai.output.messages`, tool arguments and
+results, and the Langfuse `input`/`output` attributes leave as `[redacted: content capture off]`,
+whichever library produced the span.
+
+## Runtime
+
+```ts
+import { withExecutionContext, OBSERVATION } from '@keemakr/observability';
+
+await withExecutionContext(
+  { component: 'core', lane: 'inline', tenantId, conversationId, contextId, operationId },
+  () => invokeCapability(...),
+);
+```
+
+Every span created inside — by Core, eve, the AI SDK or a library — carries the Langfuse session
+(the conversation, else the task, else the run), tags, and the safe `keemakr` identifiers as trace
+metadata. The tenant is a 12-hex hash, never the id. Nest freely.
+
+Observation names are constants in `OBSERVATION`. Langfuse evaluators, dashboards and saved views
+target names, so a rename is a breaking change.

package/dist/content-policy-processor.d.ts

@@ -0,0 +1,10 @@
+import type { SpanProcessor } from '@opentelemetry/sdk-trace-base';
+/**
+ * Redact native GenAI and Langfuse content before either exporter receives it.
+ *
+ * A query string is dropped from every span whatever the content decision: it is
+ * where bearer values ride when a header is not possible (a provider webhook
+ * secret, an OAuth code, a magic-link token), and a trace is never a place for a
+ * credential. The path stays, so the request is still identifiable.
+ */
+export declare function contentPolicyProcessor(recordContent: boolean): SpanProcessor;

package/dist/content-policy-processor.js

@@ -0,0 +1,34 @@
+import { isContentAttribute, REDACTED } from './policy.js';
+/** HTTP span attributes that carry the request URL with its query string. */
+const URL_ATTRIBUTES = ['http.target', 'http.url', 'url.full'];
+/**
+ * Redact native GenAI and Langfuse content before either exporter receives it.
+ *
+ * A query string is dropped from every span whatever the content decision: it is
+ * where bearer values ride when a header is not possible (a provider webhook
+ * secret, an OAuth code, a magic-link token), and a trace is never a place for a
+ * credential. The path stays, so the request is still identifiable.
+ */
+export function contentPolicyProcessor(recordContent) {
+    return {
+        onStart() { },
+        onEnd(span) {
+            for (const key of URL_ATTRIBUTES) {
+                const value = span.attributes[key];
+                if (typeof value === 'string' && value.includes('?')) {
+                    span.attributes[key] = value.slice(0, value.indexOf('?'));
+                }
+            }
+            if ('url.query' in span.attributes)
+                span.attributes['url.query'] = REDACTED;
+            if (recordContent)
+                return;
+            for (const key of Object.keys(span.attributes)) {
+                if (isContentAttribute(key))
+                    span.attributes[key] = REDACTED;
+            }
+        },
+        async forceFlush() { },
+        async shutdown() { },
+    };
+}

package/dist/eve-session.d.ts

@@ -0,0 +1,3 @@
+import type { SpanProcessor } from '@opentelemetry/sdk-trace-base';
+/** AI SDK v7 prefixes Eve runtime context; Langfuse expects session.id. */
+export declare function eveSessionProcessor(): SpanProcessor;

package/dist/eve-session.js

@@ -0,0 +1,16 @@
+import { trace } from '@opentelemetry/api';
+/** AI SDK v7 prefixes Eve runtime context; Langfuse expects session.id. */
+export function eveSessionProcessor() {
+    return {
+        onStart(span, parentContext) {
+            const parent = trace.getSpan(parentContext);
+            const session = span.attributes['ai.settings.context.keemakr.conversation_id'] ??
+                parent?.attributes?.['session.id'];
+            if (typeof session === 'string' && session.trim())
+                span.setAttribute('session.id', session);
+        },
+        onEnd() { },
+        async forceFlush() { },
+        async shutdown() { },
+    };
+}

package/dist/host.d.ts

@@ -0,0 +1,45 @@
+import type { ReadableSpan, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { keemakrSampler } from './sampler.js';
+export interface TelemetryHostOptions {
+    /** `service.name` on every span. */
+    service: string;
+    /** Defaults to `telemetryEnvironment()`. */
+    environment?: string;
+    /** Defaults to `telemetryRelease()`. */
+    release?: string;
+    /** Defaults to `contentCaptureAllowed()`. */
+    recordContent?: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+export interface TelemetryHost {
+    exporting: boolean;
+    destination: 'langfuse' | 'otlp' | 'none';
+    environment: string;
+    /** Hand this to eve and the AI SDK so every producer obeys one content decision. */
+    recordContent: boolean;
+    /** Serverless handlers call this before they return. */
+    flush(): Promise<void>;
+}
+export declare function langfuseConfigured(env?: NodeJS.ProcessEnv): boolean;
+export declare function otlpConfigured(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * On top of the Langfuse SDK default (its own spans, `gen_ai.*`, known LLM
+ * scopes): eve's spans, durable workflow spans, Keemakr's tracers, and the host framework's ROOT span
+ * so the trace has a root and its children are not orphans in the UI.
+ * Framework internals (rendering, fetch, DB) stay out.
+ */
+export declare function shouldExportToLangfuse(span: ReadableSpan): boolean;
+/**
+ * Keemakr's span pipeline without registering a provider, for a host that
+ * owns OpenTelemetry itself (eve's `otelIntegration`). With nothing
+ * configured no span leaves.
+ */
+export declare function keemakrTelemetry(opts: TelemetryHostOptions): TelemetryHost & {
+    spanProcessors: SpanProcessor[];
+};
+/**
+ * Idempotent per process (`@vercel/otel` guards). With nothing configured the
+ * provider is still installed so context propagates, and no span leaves.
+ */
+export declare function registerKeemakrTelemetry(opts: TelemetryHostOptions): Promise<TelemetryHost>;
+export { keemakrSampler };

package/dist/host.js

@@ -0,0 +1,88 @@
+// The one module per process that owns OpenTelemetry (Observability PRD: the
+// host owns provider, sampling, exporters and shutdown; libraries participate).
+// Only this file knows Langfuse exists; the runtime entry is exporter-neutral.
+import { LangfuseSpanProcessor, isDefaultExportSpan } from '@langfuse/otel';
+import { contentCaptureAllowed, telemetryEnvironment, telemetryRelease } from './policy.js';
+import { keemakrSampler } from './sampler.js';
+import { KEEMAKR_TRACER_PREFIX } from './index.js';
+import { eveSessionProcessor } from './eve-session.js';
+import { contentPolicyProcessor } from './content-policy-processor.js';
+export function langfuseConfigured(env = process.env) {
+    return Boolean(env.LANGFUSE_PUBLIC_KEY?.trim() && env.LANGFUSE_SECRET_KEY?.trim());
+}
+export function otlpConfigured(env = process.env) {
+    return Boolean(env.OTEL_EXPORTER_OTLP_ENDPOINT || env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT);
+}
+/**
+ * On top of the Langfuse SDK default (its own spans, `gen_ai.*`, known LLM
+ * scopes): eve's spans, durable workflow spans, Keemakr's tracers, and the host framework's ROOT span
+ * so the trace has a root and its children are not orphans in the UI.
+ * Framework internals (rendering, fetch, DB) stay out.
+ */
+export function shouldExportToLangfuse(span) {
+    if (isDefaultExportSpan(span))
+        return true;
+    const scope = span.instrumentationScope.name;
+    // Eve's durable workflow steps are ancestors of ai.eve.turn.
+    if (scope === 'workflow')
+        return true;
+    if (scope === 'eve' || scope.startsWith('eve/'))
+        return true;
+    if (scope.startsWith(KEEMAKR_TRACER_PREFIX))
+        return true;
+    return span.parentSpanContext === undefined;
+}
+/**
+ * Keemakr's span pipeline without registering a provider, for a host that
+ * owns OpenTelemetry itself (eve's `otelIntegration`). With nothing
+ * configured no span leaves.
+ */
+export function keemakrTelemetry(opts) {
+    const env = opts.env ?? process.env;
+    const environment = opts.environment ?? telemetryEnvironment(env);
+    const recordContent = opts.recordContent ?? contentCaptureAllowed(env);
+    const langfuse = langfuseConfigured(env);
+    const otlp = otlpConfigured(env);
+    const processor = langfuse
+        ? new LangfuseSpanProcessor({
+            environment,
+            release: opts.release ?? telemetryRelease(env),
+            shouldExportSpan: ({ otelSpan }) => shouldExportToLangfuse(otelSpan),
+            // A serverless function can be frozen right after it responds.
+            exportMode: env.VERCEL ? 'immediate' : 'batched',
+        })
+        : null;
+    return {
+        spanProcessors: [
+            contentPolicyProcessor(recordContent),
+            eveSessionProcessor(),
+            ...(processor ? [processor] : []),
+        ],
+        exporting: langfuse || otlp,
+        destination: langfuse ? 'langfuse' : otlp ? 'otlp' : 'none',
+        environment,
+        recordContent,
+        flush: async () => {
+            await processor?.forceFlush();
+        },
+    };
+}
+/**
+ * Idempotent per process (`@vercel/otel` guards). With nothing configured the
+ * provider is still installed so context propagates, and no span leaves.
+ */
+export async function registerKeemakrTelemetry(opts) {
+    const { spanProcessors, ...host } = keemakrTelemetry(opts);
+    const [contentPolicy, eveSession, ...exporters] = spanProcessors;
+    // `@vercel/otel` is an optional peer and its Node bundle must load as ESM.
+    const { registerOTel } = await import('@vercel/otel');
+    registerOTel({
+        serviceName: opts.service,
+        attributes: { 'deployment.environment.name': host.environment },
+        traceSampler: keemakrSampler(),
+        // 'auto' keeps @vercel/otel's own exporter (Vercel tracing or OTEL_EXPORTER_OTLP_*).
+        spanProcessors: [contentPolicy, eveSession, 'auto', ...exporters],
+    });
+    return host;
+}
+export { keemakrSampler };

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+export { getActiveSpanId, getActiveTraceId, observe, startActiveObservation, startObservation, updateActiveObservation, type LangfuseObservationType, } from '@langfuse/tracing';
+export { contentCaptureAllowed, telemetryEnvironment } from './policy.js';
+/** Every Keemakr tracer name starts with this, so a host can allowlist them. */
+export declare const KEEMAKR_TRACER_PREFIX = "keemakr";
+export declare function keemakrTracer(component: string): import("@opentelemetry/api").Tracer;
+export type ExecutionLane = 'inline' | 'agent_task' | 'workflow_task' | 'delegation' | 'planning';
+/** Durable Keemakr identifiers only. Never a raw tenant, user, or content (PRD). */
+export interface ExecutionIdentity {
+    component: 'core' | 'operator' | 'task-operator' | 'agent-sdk' | (string & {});
+    lane?: ExecutionLane;
+    tenantId?: string | null;
+    conversationId?: string | null;
+    taskId?: string | null;
+    runId?: string | null;
+    contextId?: string | null;
+    parentContextId?: string | null;
+    operationId?: string | null;
+    capabilityId?: string | null;
+    workflowId?: string | null;
+    delegationId?: string | null;
+    callerKind?: string | null;
+    /** A version to compare across: the Pack version, a configuration version. */
+    version?: string | null;
+}
+/** A tenant is never exported raw (PRD: opaque identifiers for third parties). */
+export declare function opaqueTenant(tenantId: string): string;
+export declare function sessionIdFor(id: ExecutionIdentity): string | undefined;
+export declare function propagatedAttributes(id: ExecutionIdentity): {
+    sessionId: string | undefined;
+    tags: string[];
+    metadata: Record<string, string>;
+    version: string | undefined;
+};
+/**
+ * Put this execution's identity on EVERY span beneath `fn`, whoever creates it.
+ * Langfuse filters per observation, so an attribute only on the root is
+ * invisible to a filter on a child. Nested contexts add to the outer one.
+ */
+export declare function withExecutionContext<T>(id: ExecutionIdentity, fn: () => T): T;
+export declare function isTraceId(id: string | null | undefined): id is string;
+/** A reference for a durable row to remember, never a key (PRD: telemetry identity is not product identity). */
+export declare function activeTraceId(): string | null;
+/** Add `traceparent` and `tracestate` to headers for a call leaving this process. */
+export declare function injectTraceparent(headers: Record<string, string>): Record<string, string>;
+/** Langfuse evaluators, dashboards and saved views target these names. Renaming one breaks them. */
+export declare const OBSERVATION: {
+    readonly capabilityInvoke: "capability.invoke";
+    readonly workflowDispatch: "workflow.dispatch";
+};
+export type ObservationName = (typeof OBSERVATION)[keyof typeof OBSERVATION];

package/dist/index.js

@@ -0,0 +1,80 @@
+// The exporter-neutral runtime entry. With no host registered every call is a
+// no-op, and nothing here may throw into the caller.
+import { createHash } from 'node:crypto';
+import { context, propagation, trace } from '@opentelemetry/api';
+import { propagateAttributes } from '@langfuse/tracing';
+export { getActiveSpanId, getActiveTraceId, observe, startActiveObservation, startObservation, updateActiveObservation, } from '@langfuse/tracing';
+export { contentCaptureAllowed, telemetryEnvironment } from './policy.js';
+/** Every Keemakr tracer name starts with this, so a host can allowlist them. */
+export const KEEMAKR_TRACER_PREFIX = 'keemakr';
+export function keemakrTracer(component) {
+    return trace.getTracer(`${KEEMAKR_TRACER_PREFIX}-${component}`);
+}
+/** A tenant is never exported raw (PRD: opaque identifiers for third parties). */
+export function opaqueTenant(tenantId) {
+    return createHash('sha256').update(tenantId).digest('hex').slice(0, 12);
+}
+export function sessionIdFor(id) {
+    return id.conversationId ?? id.taskId ?? id.runId ?? undefined;
+}
+export function propagatedAttributes(id) {
+    const metadata = { component: id.component };
+    const put = (k, v) => {
+        if (v)
+            metadata[k] = v;
+    };
+    put('lane', id.lane);
+    put('tenant', id.tenantId ? opaqueTenant(id.tenantId) : undefined);
+    put('conversation_id', id.conversationId);
+    put('task_id', id.taskId);
+    put('run_id', id.runId);
+    put('context_id', id.contextId);
+    put('parent_context_id', id.parentContextId);
+    put('operation_id', id.operationId);
+    put('capability_id', id.capabilityId);
+    put('workflow_id', id.workflowId);
+    put('delegation_id', id.delegationId);
+    put('caller_kind', id.callerKind);
+    const tags = [id.component, id.lane, id.callerKind].filter((t) => !!t);
+    return {
+        sessionId: sessionIdFor(id),
+        tags,
+        metadata,
+        version: id.version ?? undefined,
+    };
+}
+/**
+ * Put this execution's identity on EVERY span beneath `fn`, whoever creates it.
+ * Langfuse filters per observation, so an attribute only on the root is
+ * invisible to a filter on a child. Nested contexts add to the outer one.
+ */
+export function withExecutionContext(id, fn) {
+    // propagateAttributes drops a bad value with a warning and never throws.
+    return propagateAttributes(propagatedAttributes(id), fn);
+}
+const W3C_TRACE_ID = /^[0-9a-f]{32}$/;
+const NO_TRACE = '0'.repeat(32);
+export function isTraceId(id) {
+    return !!id && W3C_TRACE_ID.test(id) && id !== NO_TRACE;
+}
+/** A reference for a durable row to remember, never a key (PRD: telemetry identity is not product identity). */
+export function activeTraceId() {
+    const id = trace.getSpanContext(context.active())?.traceId;
+    return isTraceId(id) ? id : null;
+}
+/** Add `traceparent` and `tracestate` to headers for a call leaving this process. */
+export function injectTraceparent(headers) {
+    const out = { ...headers };
+    try {
+        propagation.inject(context.active(), out);
+    }
+    catch {
+        // no propagator installed: the headers go out without trace context
+    }
+    return out;
+}
+/** Langfuse evaluators, dashboards and saved views target these names. Renaming one breaks them. */
+export const OBSERVATION = {
+    capabilityInvoke: 'capability.invoke',
+    workflowDispatch: 'workflow.dispatch',
+};

package/dist/policy.d.ts

@@ -0,0 +1,18 @@
+export type TelemetryEnvironment = 'development' | 'dev' | 'staging' | 'production' | 'preview' | (string & {});
+/** The Langfuse `environment` of this process. `LANGFUSE_TRACING_ENVIRONMENT`
+ *  when set; else the tier from the deployed branch; a feature-branch deploy is
+ *  `preview`; a machine with no Vercel context is `development`. */
+export declare function telemetryEnvironment(env?: NodeJS.ProcessEnv): TelemetryEnvironment;
+export declare function telemetryRelease(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ *   OTEL_RECORD_CONTENT=1|true   yes, an explicit decision for this deployment
+ *   OTEL_RECORD_CONTENT=0|false  no
+ *   unset                        only in `development`
+ */
+export declare function contentCaptureAllowed(env?: NodeJS.ProcessEnv): boolean;
+/** A marker, so a reader knows content existed and was withheld. */
+export declare const REDACTED = "[redacted: content capture off]";
+/** `langfuse.observation.*` is the Langfuse SDK, `gen_ai.*` the OpenTelemetry
+ *  GenAI convention (eve, the AI SDK), `ai.*` the AI SDK's own names. */
+export declare const CONTENT_ATTRIBUTE_PREFIXES: readonly string[];
+export declare function isContentAttribute(key: string): boolean;

package/dist/policy.js

@@ -0,0 +1,66 @@
+// The one decision on whether model and tool content may leave a process
+// (Observability PRD: metadata by default, content by explicit destination decision).
+/** Keemakr runs three Vercel projects, one per branch, and each is that
+ *  project's "production" deployment — so `VERCEL_ENV` is `production` on all
+ *  three and cannot tell them apart. The branch can (docs/prod-git-rules.md). */
+const BRANCH_ENVIRONMENT = {
+    main: 'production',
+    stage: 'staging',
+    dev: 'dev',
+};
+/** The Langfuse `environment` of this process. `LANGFUSE_TRACING_ENVIRONMENT`
+ *  when set; else the tier from the deployed branch; a feature-branch deploy is
+ *  `preview`; a machine with no Vercel context is `development`. */
+export function telemetryEnvironment(env = process.env) {
+    const explicit = env.LANGFUSE_TRACING_ENVIRONMENT?.trim();
+    if (explicit)
+        return explicit;
+    const branch = env.VERCEL_GIT_COMMIT_REF?.trim();
+    if (branch)
+        return BRANCH_ENVIRONMENT[branch] ?? 'preview';
+    if (env.VERCEL)
+        return 'preview';
+    return 'development';
+}
+export function telemetryRelease(env = process.env) {
+    return env.LANGFUSE_RELEASE?.trim() || env.VERCEL_GIT_COMMIT_SHA?.trim() || undefined;
+}
+/**
+ *   OTEL_RECORD_CONTENT=1|true   yes, an explicit decision for this deployment
+ *   OTEL_RECORD_CONTENT=0|false  no
+ *   unset                        only in `development`
+ */
+export function contentCaptureAllowed(env = process.env) {
+    const flag = env.OTEL_RECORD_CONTENT?.trim().toLowerCase();
+    if (flag === '1' || flag === 'true')
+        return true;
+    if (flag === '0' || flag === 'false')
+        return false;
+    return telemetryEnvironment(env) === 'development';
+}
+/** A marker, so a reader knows content existed and was withheld. */
+export const REDACTED = '[redacted: content capture off]';
+/** `langfuse.observation.*` is the Langfuse SDK, `gen_ai.*` the OpenTelemetry
+ *  GenAI convention (eve, the AI SDK), `ai.*` the AI SDK's own names. */
+export const CONTENT_ATTRIBUTE_PREFIXES = [
+    'langfuse.observation.input',
+    'langfuse.observation.output',
+    'langfuse.trace.input',
+    'langfuse.trace.output',
+    'gen_ai.input.messages',
+    'gen_ai.output.messages',
+    'gen_ai.prompt',
+    'gen_ai.completion',
+    'gen_ai.system_instructions',
+    'gen_ai.tool.call.arguments',
+    'gen_ai.tool.call.result',
+    'ai.prompt',
+    'ai.response.text',
+    'ai.response.object',
+    'ai.response.toolCalls',
+    'ai.toolCall.args',
+    'ai.toolCall.result',
+];
+export function isContentAttribute(key) {
+    return CONTENT_ATTRIBUTE_PREFIXES.some((p) => key === p || key.startsWith(`${p}.`));
+}

package/dist/sampler.d.ts

@@ -0,0 +1,8 @@
+import { type Attributes, type Context } from '@opentelemetry/api';
+export declare function keepRootSpan(name: string, attributes: Attributes): boolean;
+export declare function keemakrSampler(): {
+    shouldSample(ctx: Context, _traceId: string, name: string, _kind: unknown, attrs: Attributes): {
+        decision: number;
+    };
+    toString(): string;
+};

package/dist/sampler.js

@@ -0,0 +1,41 @@
+// Parent-based, including a parent propagated in over `traceparent`, so one
+// Keemakr execution is kept or dropped whole across deployments.
+import { trace, TraceFlags } from '@opentelemetry/api';
+/** Root spans nobody debugs from, which would otherwise be most of what a backend stores. */
+const NOISE_ROUTES = [/^\/api\/internal\//, /^\/_next\//, /^\/api\/health$/, /^\/favicon/];
+function routeOf(name, attributes) {
+    for (const key of ['http.route', 'next.route', 'http.target', 'url.path']) {
+        const v = attributes[key];
+        if (typeof v === 'string' && v)
+            return v;
+    }
+    const m = /^(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+(\/\S*)/.exec(name);
+    return m ? m[1] : null;
+}
+export function keepRootSpan(name, attributes) {
+    if (name === 'middleware' || name.startsWith('middleware '))
+        return false;
+    const route = routeOf(name, attributes);
+    if (route && NOISE_ROUTES.some((re) => re.test(route)))
+        return false;
+    return true;
+}
+// @opentelemetry/sdk-trace-base's SamplingDecision values, so this stays a
+// structural sampler with no runtime import of that package.
+const NOT_RECORD = 0;
+const RECORD_AND_SAMPLED = 2;
+export function keemakrSampler() {
+    return {
+        shouldSample(ctx, _traceId, name, _kind, attrs) {
+            const parent = trace.getSpanContext(ctx);
+            if (parent && trace.isSpanContextValid(parent)) {
+                const sampled = (parent.traceFlags & TraceFlags.SAMPLED) !== 0;
+                return { decision: sampled ? RECORD_AND_SAMPLED : NOT_RECORD };
+            }
+            return { decision: keepRootSpan(name, attrs ?? {}) ? RECORD_AND_SAMPLED : NOT_RECORD };
+        },
+        toString() {
+            return 'KeemakrSampler';
+        },
+    };
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@keemakr/observability",
+  "version": "0.2.0-dev-20261012160211",
+  "description": "Keemakr telemetry: the host registration for a process (Core, Operator, Task Operator, Pack Runtime) and the exporter-neutral runtime that Core libraries, the Agents SDK and Pack code trace with.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./host": {
+      "types": "./dist/host.d.ts",
+      "import": "./dist/host.js",
+      "default": "./dist/host.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fsztpartners/keemakr.git",
+    "directory": "packages/observability"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@langfuse/otel": "^5.11.1",
+    "@langfuse/tracing": "^5.11.1"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^2.0.1",
+    "@opentelemetry/sdk-trace-base": "^2.0.1",
+    "@vercel/otel": "^2.1.3"
+  },
+  "peerDependenciesMeta": {
+    "@vercel/otel": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@opentelemetry/api": "1.9.1",
+    "@opentelemetry/core": "^2.0.1",
+    "@opentelemetry/sdk-trace-base": "^2.0.1",
+    "@types/node": "^20.19.43",
+    "@vercel/otel": "^2.1.3",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=20.9"
+  }
+}