macp-sdk-typescript 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to `macp-sdk-typescript` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 project uses [Semantic Versioning](https://semver.org/).
 
+## [0.21.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.20.0...v0.21.0) (2026-10-26)
+
+
+### Features
+
+* optional OpenTelemetry send spans and W3C trace propagation (W5 S2) ([#212](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/212)) ([28ce7a1](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/28ce7a149e6803f5828416eafbc73e4067f80cd7))
+
 ## [0.20.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.19.0...v0.20.0) (2026-10-26)
 
 

package/README.md

@@ -492,6 +492,14 @@ If you hold the snake_case §3 projection (a receipt's `commitment`) instead of
 
 The `macp-sdk-typescript/receipt` subpath is browser-safe: it pulls in no gRPC, no `node:crypto` and no `Buffer`. The same functions are also exported from the package root. The tests replay the spec's `schemas/conformance/receipt/` vectors and rebuild the spec's example receipt byte for byte.
 
+## OpenTelemetry
+
+Install the optional peer dependency `@opentelemetry/api` and register a tracer provider. The SDK then:
+- emits one CLIENT span per `send()`, named `send {macp.mode.id}`, with the MACP semantic-convention attributes;
+- puts W3C `traceparent`/`tracestate` in the gRPC metadata of every call made while a valid span context is active.
+
+It never records payloads, `reason` text or error messages. Without the package, nothing is loaded or emitted. See [docs/guides/observability.md](docs/guides/observability.md) for the attribute set, the outcome rules and the limitations.
+
 ## Error Handling
 
 ```typescript

package/dist/client.d.ts

@@ -115,6 +115,11 @@ export declare class MacpClient {
      * that one in-flight call (and the first caller's deadline).
      */
     private requireCapability;
+    /**
+     * The single metadata choke point: auth, plus W3C trace context
+     * (RFC-MACP-0006 §2.1) when `@opentelemetry/api` is installed and a valid
+     * span context is active — or, for Send, the send span's own context.
+     */
     private metadata;
     private deadline;
     private unary;

package/dist/client.js

@@ -47,6 +47,7 @@ const path = __importStar(require("node:path"));
 const grpc = __importStar(require("@grpc/grpc-js"));
 const protoLoader = __importStar(require("@grpc/proto-loader"));
 const auth_1 = require("./auth");
+const otel_1 = require("./otel");
 const constants_1 = require("./constants");
 const envelope_1 = require("./envelope");
 const errors_1 = require("./errors");
@@ -339,17 +340,27 @@ class MacpClient {
                 `${rpc} is optional and a client MUST NOT call it otherwise (${rfc})`);
         }
     }
-    metadata(auth) {
+    /**
+     * The single metadata choke point: auth, plus W3C trace context
+     * (RFC-MACP-0006 §2.1) when `@opentelemetry/api` is installed and a valid
+     * span context is active — or, for Send, the send span's own context.
+     */
+    metadata(auth, traceContext) {
         const selected = auth ?? this.auth;
-        if (!selected)
-            return undefined;
-        return (0, auth_1.metadataFromAuth)(selected);
+        const metadata = selected ? (0, auth_1.metadataFromAuth)(selected) : undefined;
+        const headers = (0, otel_1.traceHeaders)(traceContext);
+        if (headers.length === 0)
+            return metadata;
+        const withTrace = metadata ?? new grpc.Metadata();
+        for (const [key, value] of headers)
+            withTrace.set(key, value);
+        return withTrace;
     }
     deadline(deadlineMs) {
         const resolved = deadlineMs ?? this.defaultDeadlineMs;
         return resolved ? new Date(Date.now() + resolved) : undefined;
     }
-    unary(method, request, auth, deadlineMs, ackStatuses, registryCodeAsAck = false) {
+    unary(method, request, auth, deadlineMs, ackStatuses, registryCodeAsAck = false, traceContext) {
         return new Promise((resolve, reject) => {
             const callback = (error, response) => {
                 if (error) {
@@ -373,7 +384,7 @@ class MacpClient {
                 }
             };
             const deadline = this.deadline(deadlineMs);
-            const metadata = this.metadata(auth);
+            const metadata = this.metadata(auth, traceContext);
             if (metadata && deadline)
                 this.client[method](request, metadata, { deadline }, callback);
             else if (metadata)
@@ -410,14 +421,30 @@ class MacpClient {
     }
     async send(envelope, options) {
         const auth = this.requireAuth(options?.auth);
-        const response = await this.unary('Send', { envelope }, auth, options?.deadlineMs, 
+        // A malformed credential fails here, before the span starts: a send that
+        // never reaches the wire emits no span.
+        (0, auth_1.validateAuth)(auth);
+        // One CLIENT span per call (undefined without @opentelemetry/api); its
+        // own context goes into the Send metadata so the runtime's server span
+        // is its child.
+        const span = (0, otel_1.startSendSpan)(envelope);
+        const call = () => this.unary('Send', { envelope }, auth, options?.deadlineMs, 
         // gRPC ALREADY_EXISTS/FAILED_PRECONDITION on Send are application-level
         // rejections the runtime couldn't express as a normal NACK (issue #107);
         // surface them as MacpAckError, matching macp-sdk-python (client.py:442-452).
         // That status map is the pre-0.9.0 fallback: a `macp-error-code` key
         // (runtime ≥ 0.9.0) supplies the exact registry code instead.
-        { ALREADY_EXISTS: constants_1.SESSION_ALREADY_EXISTS, FAILED_PRECONDITION: constants_1.POLICY_DENIED }, true);
-        const ack = response.ack;
+        { ALREADY_EXISTS: constants_1.SESSION_ALREADY_EXISTS, FAILED_PRECONDITION: constants_1.POLICY_DENIED }, true, span?.context);
+        let response;
+        try {
+            response = await (span ? span.run(call) : call());
+        }
+        catch (error) {
+            span?.end({ error });
+            throw error;
+        }
+        const ack = response?.ack;
+        span?.end({ ack: ack ?? {} });
         // Duplicate acks are success — the message was already accepted
         if (ack?.duplicate)
             return ack;
@@ -683,7 +710,7 @@ class MacpClient {
      */
     watchSignals(auth) {
         const selected = this.requireAuth(auth);
-        const metadata = (0, auth_1.metadataFromAuth)(selected);
+        const metadata = this.metadata(selected);
         return this.client.WatchSignals({}, metadata);
     }
     async sendSignal(options) {

package/dist/otel.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Optional OpenTelemetry instrumentation (docs/opentelemetry.md in the spec
+ * repo, semconv `span.macp.send`; propagation per RFC-MACP-0006 §2.1).
+ *
+ * `@opentelemetry/api` is an optional peer dependency. It is required lazily,
+ * on the first RPC, never at import, so loading the SDK never touches it, and
+ * when it is not installed every function here is a no-op. Nothing in this
+ * module may throw into the send path: instrumentation must never fail a call.
+ *
+ * Internal: not exported from `src/index.ts`, and never imported by the
+ * browser-safe `./receipt` subpath.
+ */
+import type * as OtelApiModule from '@opentelemetry/api';
+import type { Ack, Envelope } from './types';
+type OtelApi = typeof OtelApiModule;
+/** A span context, opaque outside this module. */
+export type TraceContext = OtelApiModule.SpanContext;
+/**
+ * Test seam: `null` forces "not installed", a module object replaces the real
+ * one, `undefined` restores normal loading.
+ */
+export declare function setOtelApiForTesting(api: OtelApi | null | undefined): void;
+/**
+ * W3C `traceparent`/`tracestate` for the given span context, or the active
+ * one when none is given. Built from the API alone rather than through the
+ * global propagator, which would also inject `baggage` (arbitrary user data)
+ * and follow a user's B3/Jaeger configuration; §2.1 names only these two.
+ */
+export declare function traceHeaders(explicit?: TraceContext): Array<[string, string]>;
+/** One in-flight `send {macp.mode.id}` CLIENT span. */
+export interface SendSpan {
+    /** The span's own context, injected into the Send metadata. */
+    readonly context: TraceContext | undefined;
+    /**
+     * Run `fn` with this span active, so a transport client span (for example
+     * from gRPC auto-instrumentation) is its child, as the semconv note on
+     * `span.macp.send` requires. Calls `fn` exactly once; an OpenTelemetry
+     * failure falls back to calling it directly.
+     */
+    run<T>(fn: () => T): T;
+    /** Record the outcome and end the span. Safe to call once; never throws. */
+    end(result: {
+        ack: Ack;
+    } | {
+        error: unknown;
+    }): void;
+}
+/**
+ * Start the CLIENT span for one `send()`, or return `undefined` when
+ * OpenTelemetry is not installed (or the tracer fails). Only identifiers and
+ * types are recorded — never payload, `reason`, or any error message.
+ */
+export declare function startSendSpan(envelope: Envelope): SendSpan | undefined;
+export {};

package/dist/otel.js

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setOtelApiForTesting = setOtelApiForTesting;
+exports.traceHeaders = traceHeaders;
+exports.startSendSpan = startSendSpan;
+const errors_1 = require("./errors");
+const TRACER_NAME = 'macp-sdk-typescript';
+/** OpenTelemetry's fallback `error.type` when no better value is known. */
+const ERROR_TYPE_OTHER = '_OTHER';
+// undefined: not tried yet; null: tried, absent.
+let loaded;
+let override;
+let tracerVersion;
+/**
+ * Test seam: `null` forces "not installed", a module object replaces the real
+ * one, `undefined` restores normal loading.
+ */
+function setOtelApiForTesting(api) {
+    override = api;
+}
+function otelApi() {
+    if (override !== undefined)
+        return override ?? undefined;
+    if (loaded === undefined) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            loaded = require('@opentelemetry/api');
+        }
+        catch {
+            loaded = null;
+        }
+    }
+    return loaded ?? undefined;
+}
+function sdkVersion() {
+    if (tracerVersion === undefined) {
+        try {
+            // Resolves to the package root from both src/ and dist/.
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            tracerVersion = String(require('../package.json').version ?? '');
+        }
+        catch {
+            tracerVersion = '';
+        }
+    }
+    return tracerVersion || undefined;
+}
+/**
+ * W3C `traceparent`/`tracestate` for the given span context, or the active
+ * one when none is given. Built from the API alone rather than through the
+ * global propagator, which would also inject `baggage` (arbitrary user data)
+ * and follow a user's B3/Jaeger configuration; §2.1 names only these two.
+ */
+function traceHeaders(explicit) {
+    const api = otelApi();
+    if (!api)
+        return [];
+    try {
+        const spanContext = explicit ?? api.trace.getSpanContext(api.context.active());
+        if (!spanContext || !api.isSpanContextValid(spanContext))
+            return [];
+        const flags = (spanContext.traceFlags & 0xff).toString(16).padStart(2, '0');
+        const headers = [
+            ['traceparent', `00-${spanContext.traceId}-${spanContext.spanId}-${flags}`],
+        ];
+        const tracestate = spanContext.traceState?.serialize();
+        if (tracestate)
+            headers.push(['tracestate', tracestate]);
+        return headers;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Start the CLIENT span for one `send()`, or return `undefined` when
+ * OpenTelemetry is not installed (or the tracer fails). Only identifiers and
+ * types are recorded — never payload, `reason`, or any error message.
+ */
+function startSendSpan(envelope) {
+    const api = otelApi();
+    if (!api)
+        return undefined;
+    try {
+        const attributes = {
+            'macp.operation.name': 'send',
+            'macp.message.id': envelope.messageId,
+            'macp.message.type': envelope.messageType,
+        };
+        if (envelope.macpVersion)
+            attributes['macp.version'] = envelope.macpVersion;
+        if (envelope.sessionId)
+            attributes['macp.session.id'] = envelope.sessionId;
+        if (envelope.mode)
+            attributes['macp.mode.id'] = envelope.mode;
+        if (envelope.sender)
+            attributes['macp.sender.id'] = envelope.sender;
+        const name = envelope.mode ? `send ${envelope.mode}` : 'send';
+        const span = api.trace
+            .getTracer(TRACER_NAME, sdkVersion())
+            .startSpan(name, { kind: api.SpanKind.CLIENT, attributes }, api.context.active());
+        let ended = false;
+        return {
+            context: safe(() => span.spanContext()),
+            run(fn) {
+                let called = false;
+                let returned = false;
+                let result;
+                const once = () => {
+                    called = true;
+                    result = fn();
+                    returned = true;
+                    return result;
+                };
+                try {
+                    return api.context.with(api.trace.setSpan(api.context.active(), span), once);
+                }
+                catch (error) {
+                    // fn's own throw propagates; an OpenTelemetry failure before or
+                    // after fn never replaces the call's real result.
+                    if (!called)
+                        return fn();
+                    if (returned)
+                        return result;
+                    throw error;
+                }
+            },
+            end(result) {
+                if (ended)
+                    return;
+                ended = true;
+                safe(() => {
+                    recordOutcome(api, span, result);
+                });
+                safe(() => span.end());
+            },
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function recordOutcome(api, span, result) {
+    if ('ack' in result) {
+        const { ack } = result;
+        if (ack.duplicate)
+            span.setAttribute('macp.envelope.outcome', 'duplicate');
+        else if (ack.ok)
+            span.setAttribute('macp.envelope.outcome', 'accepted');
+        else
+            rejected(span, ack.error?.code);
+        return;
+    }
+    const { error } = result;
+    // A rejection is a normal protocol outcome: status stays UNSET. The SDK
+    // raises MacpAckError for a NACK, a status carrying `macp-error-code`, and
+    // the pre-0.9 status fallback — the span classifies exactly as the caller's
+    // exception does.
+    if (error instanceof errors_1.MacpAckError) {
+        rejected(span, error.failure.code);
+        return;
+    }
+    const errorType = (error instanceof errors_1.MacpTransportError ? (error.macpErrorCode ?? error.code) : undefined) || ERROR_TYPE_OTHER;
+    span.setAttribute('error.type', errorType);
+    // The description is the code only; exception messages are never recorded.
+    span.setStatus({ code: api.SpanStatusCode.ERROR, message: errorType });
+}
+function rejected(span, code) {
+    span.setAttribute('macp.envelope.outcome', 'rejected');
+    span.setAttribute('error.type', code || ERROR_TYPE_OTHER);
+}
+function safe(fn) {
+    try {
+        return fn();
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * Kept in sync with package.json by release-please (see the
  * `x-release-please-version` annotation).
  */
-export declare const VERSION = "0.20.0";
+export declare const VERSION = "0.21.0";

package/dist/version.js

@@ -7,4 +7,4 @@ exports.VERSION = void 0;
  * Kept in sync with package.json by release-please (see the
  * `x-release-please-version` annotation).
  */
-exports.VERSION = '0.20.0'; // x-release-please-version
+exports.VERSION = '0.21.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macp-sdk-typescript",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "TypeScript SDK for the MACP Rust runtime",
   "license": "Apache-2.0",
   "type": "commonjs",
@@ -65,7 +65,18 @@
     "@noble/hashes": "^1.8.0",
     "protobufjs": "^8.6.5"
   },
+  "peerDependencies": {
+    "@opentelemetry/api": ">=1.3.0 <2"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@opentelemetry/api": "~1.9.1",
+    "@opentelemetry/context-async-hooks": "^2.12.0",
+    "@opentelemetry/sdk-trace-base": "^2.12.0",
     "@types/node": "^26.4.0",
     "@typescript-eslint/eslint-plugin": "^8.68.0",
     "@typescript-eslint/parser": "^8.68.0",