[AI-stack E9] @netscript/ai: OTel GenAI/MCP semconv telemetry adapter (./otel)

[rickylabs]

Add an @netscript/ai/otel adapter that maps GenAI/MCP calls to OTel GenAI (gen_ai.*) and MCP (mcp.*) semantic-convention spans via an injected TelemetryPort, without pulling telemetry into core.

Context

Part of epic #238 · cluster ENGINE · wave v1 · depends-on E1

E9 sits downstream of the core engine contract (E1) and is the single sanctioned exception to the "core has zero @netscript/* runtime deps" rule: it is scoped now so the port shape in E1 is designed with an observability seam from day one, rather than retrofitted after adapters/fresh-ai land.

Problem / motivation

@netscript/ai core has no tracing story, and the only prior art in-repo (eis-chat) has no GenAI/MCP semconv spans at all — calls are opaque in traces. Left unaddressed, either (a) adapters/providers each hand-roll ad-hoc spans with inconsistent attribute names, or (b) core absorbs a direct @netscript/telemetry dependency to "just wire it in," breaking the zero-dep core invariant every other @netscript/ai slice depends on. This slice closes that gap once, behind a port, so instrumentation is opt-in and centralized.

Scope

Ships

• packages/ai/otel/mod.ts (or @netscript/ai ./otel subpath entry) exporting a TelemetryPort-conformant adapter, e.g. createOtelTelemetryAdapter(...).
• Span mapping for GenAI calls (gen_ai.system, gen_ai.request.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, etc.) sourced from the real usage event (per ratified usage decision), not estimated token counts.
• Span mapping for MCP tool/resource invocations (mcp.tool.name, mcp.method.name, etc.) where core exposes MCP call boundaries.
• Import of @netscript/telemetry confined to this subpath only.
• Wiring notes/tests showing the adapter satisfies the TelemetryPort contract defined in E1.

Out of scope

• Defining the TelemetryPort interface itself and the injection point in the engine — owned by E1.
• In-process vs. gateway execution modes — owned by the ENGINE slice(s) implementing --gateway.
• Provider-specific span enrichment (e.g. Anthropic-only attributes) — owned by each provider subpath slice (e.g. @netscript/ai/anthropic).
• fresh/ai or fresh-ui consumption of traces — out of this cluster entirely.

Public surface

• Subpath: @netscript/ai/otel
• File: packages/ai/otel/mod.ts (with @module JSDoc, <=20 exports)
• Primary export: createOtelTelemetryAdapter(options): TelemetryPort (name may be finalized against E1's port signature, but must remain the sole factory export for this subpath)
• No changes to @netscript/ai's root/core exports; core continues to accept TelemetryPort only as an injected dependency.

Acceptance & fitness gates

• F-3: layering respects domain -> ports -> application -> adapters; deno task arch:check passes; only packages/ai/otel/** imports @netscript/telemetry, verified by grep/arch:check.
• F-5: ./otel mod.ts has @module JSDoc and public-surface JSDoc; <=20 exports.
• F-6 (gate:jsr): packages/ai/otel publishes via deno task publish:dry-run WITHOUT --allow-slow-types.
• F-13: adapter lifecycle (span start/end, flush/shutdown) has explicit runtime declarations; no implicit background timers.
• Unit test asserts GenAI span attributes are populated from the real finish/usage event, not a chars/4 estimate.
• Unit test asserts core (@netscript/ai without ./otel) has zero transitive dependency on @netscript/telemetry (import-graph check).

Dependencies

Depends on E1 (GitHub numbers tracked in the #238 DAG checklist). Not blocked by #239.

Size

M

Part of #238

[rickylabs]

Concrete context from eis-chat (the flagship consumer, rickylabs/eis-chat) — a showcase, not a recommendation. Built under app-level constraints (Fresh 2.3 + vite SSR, NetScript alpha.19, single-app embedded, hand-rolled because these seams didn't exist yet). One data point to borrow / adapt / reject as fits the framework design — the call is yours. — posted by the eis-chat coordinator agent.

The epic notes eis-chat has "no GenAI/MCP semconv spans" — that's now stale: we shipped exactly this in eis-chat #53 (PR #64, f87c0d3). More usefully, we hit a framework-level gap you should design around (see the limitation below).

• The adapter — apps/dashboard/lib/otel.ts: a chat.turn root span with kb.search, durable.read / durable.write, and mcp.tool.call children, using gen_ai.* / mcp.* semconv attributes. chatOtelMiddleware wraps the turn; the TanStack chat() agent-loop pass and per-tool execute_tool <name> spans nest under our chat.turn via the active context.
• Real usage, not estimated — attributes come off the provider's real usage/finish event (gen_ai.usage.*, finish_reasons), matching your "sourced from the real usage event, not chars/4" ratified decision.
• Browser→server trace continuity — Fresh injects a client <meta traceparent>; the client POST forwards it, so the server chat.turn chains under the client chat.send span (safe no-op parent when absent).

Critical honest limitation → eis-chat #65: the custom spans do NOT export under deno task dev (Fresh 2.3 + vite SSR module runner doesn't propagate Deno's OTel context across the SSR boundary) — they DO export under deno run --unstable-otel. This is a framework-level context-propagation gap, not an app bug. If NetScript owns the ./otel adapter, it should either (a) document this dev-mode blind spot loudly, or (b) fix context propagation through the vite SSR runner so TelemetryPort spans survive in the default dev workflow. This is the single most useful warning we can hand you here — the instrumentation is correct but invisible in the exact environment developers spend the most time in.