macp-sdk-typescript 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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)
+
+
+### Features
+
+* runtime-issued decision receipts — getDecisionReceipt, getReceiptKeys, trustedKeysFromJwks (RFC-MACP-0013 §13) ([#210](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/210)) ([931d9e1](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/931d9e13d7695a9f4659d0538e85dcb709eaeb20))
+
 ## [0.19.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.18.0...v0.19.0) (2026-10-26)
 
 

package/README.md

@@ -72,7 +72,7 @@ client.close();
 
 The SDK uses a **three-layer** design:
 
-- **Low-level transport** (`MacpClient`): typed wrappers around every `MACPRuntimeService` RPC — `initialize`, `send`, `openStream`, `getSession`, `cancelSession`, `suspendSession`, `resumeSession`, `listSessions`, `getManifest`, `listModes`, `listRoots`, `listExtModes`, `registerExtMode`, `unregisterExtMode`, `promoteMode`, the policy RPCs (`register`/`unregister`/`get`/`listPolicies`, and `whatIfReplay` where the runtime advertises it), plus streaming watchers (`ModeRegistryWatcher`, `RootsWatcher`, `SignalWatcher`, `PolicyWatcher`, `SessionLifecycleWatcher`).
+- **Low-level transport** (`MacpClient`): typed wrappers around every `MACPRuntimeService` RPC — `initialize`, `send`, `openStream`, `getSession`, `cancelSession`, `suspendSession`, `resumeSession`, `listSessions`, `getManifest`, `listModes`, `listRoots`, `listExtModes`, `registerExtMode`, `unregisterExtMode`, `promoteMode`, the policy RPCs (`register`/`unregister`/`get`/`listPolicies`, and `whatIfReplay` where the runtime advertises it), `getDecisionReceipt`/`getReceiptKeys` where the runtime advertises receipts, plus streaming watchers (`ModeRegistryWatcher`, `RootsWatcher`, `SignalWatcher`, `PolicyWatcher`, `SessionLifecycleWatcher`).
 - **High-level session helpers**: one class per coordination mode (`DecisionSession`, `ProposalSession`, `TaskSession`, `HandoffSession`, `QuorumSession`) — wraps `MacpClient`, builds envelopes, encodes payloads, and maintains a local state projection.
 - **Agent framework** (`src/agent/`): event-driven `Participant` with strategy-based handlers, bootstrap runner (`fromBootstrap`), gRPC/HTTP transports, and the optional cancel-callback HTTP server.
 
@@ -463,12 +463,43 @@ const result = verifyReceipt(receipt, { 'prod-2026': 'TDVzkxaSf6_Oxu7mmn5TbCkF80
 | `attestations[i]` | `valid`, `invalid`, `unknown_key` or `unsupported` (any other `alg`, and every `vendor` attestation)                                                                                           |
 | `verdict`         | `attested` (integrity holds and at least one attestation is valid), `integrity_only`, `unverified` (integrity fails, so attestations are not checked), or `refused` (unknown `receipt_format`) |
 
+To trust a published key set (a JWK Set, such as a runtime's `GetReceiptKeys` response; RFC-MACP-0013 §13), convert it with `trustedKeysFromJwks(jwks)`:
+
+```typescript
+import { trustedKeysFromJwks, verifyReceipt } from 'macp-sdk-typescript/receipt';
+
+const trustedKeys = trustedKeysFromJwks(jwks); // { 'example-1': 'TDVzkxaSf6_…' }
+verifyReceipt(receipt, trustedKeys).verdict; // 'attested'
+```
+
+It keeps only Ed25519 public keys (`kty` `OKP`, `crv` `Ed25519`) with a `kid` and an `x`, whose `alg` (if any) is `EdDSA` and `use` (if any) is `sig`. It drops a key that carries a private member (`d`, `k`, …) and any `kid` that more than one entry of the set claims, even when the other entry is a key it can't use (an EC key, say). It never throws: anything that isn't a key set gives `{}`. Deciding to trust the set is still up to you.
+
+### Fetching a runtime-issued receipt
+
+A runtime that advertises `capabilities.decisionReceipt.getDecisionReceipt` issues receipts itself (RFC-MACP-0013 §13). Fetch one for a resolved session, fetch the runtime's key set, and verify:
+
+```typescript
+const { receipt, raw } = await client.getDecisionReceipt(sessionId); // raw: the exact bytes served
+const jwks = await client.getReceiptKeys(); // { keys: [] } from an unsigned runtime
+verifyReceipt(receipt, trustedKeysFromJwks(jwks)).verdict; // 'attested', or 'integrity_only' if unsigned
+```
+
+Both methods throw `MacpSdkError` without sending anything when the runtime doesn't advertise the capability. A session the runtime can't issue a receipt for (not resolved yet, or resolved without a `CommitmentPayload`) gives `MacpTransportError` with `macpErrorCode` `RECEIPT_UNAVAILABLE`.
+
 If you hold the snake_case §3 projection (a receipt's `commitment`) instead of a `CommitmentPayload`, convert it with `commitmentFromProjection(projection)`.
 
 `verifyReceipt` never throws. `buildReceipt` throws `MacpSdkError` on a missing field, and when `commitmentWire` is not the wire encoding of the commitment. Signing is deterministic: the same inputs always produce the same receipt.
 
 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

@@ -1,6 +1,7 @@
 import * as grpc from '@grpc/grpc-js';
 import { type AuthConfig } from './auth';
 import { ProtoRegistry } from './proto-registry';
+import type { DecisionReceiptResult, ReceiptKeySet } from './receipt';
 import type { Ack, AgentManifest, Envelope, InitializeResult, ModeDescriptor, PolicyDescriptor, SessionMetadata, Root, WhatIfReplayResult } from './types';
 interface MacpClientOptions {
     address: string;
@@ -99,12 +100,26 @@ export declare class MacpClient {
     private readonly defaultDeadlineMs?;
     private readonly clientName;
     private readonly clientVersion;
-    /** The last {@link initialize} result; {@link whatIfReplay} reads its capabilities. */
+    /** The last {@link initialize} result; capability-gated RPCs read its capabilities. */
     private initializeResult?;
+    /** An `Initialize` that {@link requireCapability} started and is still in flight. */
+    private pendingInit?;
     /** The runtime's capabilities from the last {@link initialize}; `undefined` before one. */
     get serverCapabilities(): Record<string, unknown> | undefined;
     constructor(options: MacpClientOptions);
     private requireAuth;
+    /**
+     * Throws {@link MacpSdkError}, without sending anything, unless
+     * `capabilities.<group>.<flag>` from {@link initialize} is `true`. Calls
+     * `Initialize` once if this client hasn't; concurrent first callers share
+     * 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;
@@ -249,6 +264,45 @@ export declare class MacpClient {
         auth?: AuthConfig;
         deadlineMs?: number;
     }): Promise<WhatIfReplayResult>;
+    /**
+     * Fetch the runtime-issued decision receipt for a resolved session
+     * (RFC-MACP-0013 §13). Returns the parsed `macp-receipt/1` object and `raw`,
+     * the exact JSON text the runtime served, which is stable across calls
+     * (§13 item 6), so it can be stored or forwarded byte for byte. Verify it
+     * with `verifyReceipt(receipt, trustedKeysFromJwks(await getReceiptKeys()))`;
+     * this method does not.
+     *
+     * The RPC is optional, so this checks
+     * `capabilities.decisionReceipt.getDecisionReceipt` from {@link initialize}
+     * first (calling it once if this client hasn't) and throws
+     * {@link MacpSdkError} without sending anything when the runtime doesn't
+     * advertise it. Authorized as {@link getSession}. Runtime refusals arrive as
+     * {@link MacpTransportError} with `macpErrorCode` set: `RECEIPT_UNAVAILABLE`
+     * (no receipt can be issued: not resolved yet, or resolved without a
+     * `CommitmentPayload`), `SESSION_NOT_FOUND`, `FORBIDDEN`,
+     * `INTERNAL_ERROR`. A `receipt_json` that isn't a JSON object throws
+     * {@link MacpSdkError}.
+     */
+    getDecisionReceipt(sessionId: string, options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+    }): Promise<DecisionReceiptResult>;
+    /**
+     * Fetch the JWK Set of public keys the runtime signs receipts with
+     * (RFC-MACP-0013 §13 item 8); an unsigned runtime returns `{keys: []}`. Pass
+     * it to `trustedKeysFromJwks` for the map `verifyReceipt` takes. Whether
+     * to trust these keys is the caller's decision.
+     *
+     * Gated on `capabilities.decisionReceipt.getDecisionReceipt` like
+     * {@link getDecisionReceipt}. Needs transport auth only, like
+     * {@link getManifest}: `auth` is optional and falls back to the client's.
+     * A `jwks_json` that isn't a JSON object with a `keys` array throws
+     * {@link MacpSdkError}.
+     */
+    getReceiptKeys(options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+    }): Promise<ReceiptKeySet>;
     /**
      * Fetch a single page of sessions (proto ≥ 0.1.6). `pageSize: 0` (or absent)
      * lets the server choose the page size; the server MAY cap it. Callers MUST

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");
@@ -276,8 +277,10 @@ class MacpClient {
     defaultDeadlineMs;
     clientName;
     clientVersion;
-    /** The last {@link initialize} result; {@link whatIfReplay} reads its capabilities. */
+    /** The last {@link initialize} result; capability-gated RPCs read its capabilities. */
     initializeResult;
+    /** An `Initialize` that {@link requireCapability} started and is still in flight. */
+    pendingInit;
     /** The runtime's capabilities from the last {@link initialize}; `undefined` before one. */
     get serverCapabilities() {
         return this.initializeResult?.capabilities;
@@ -320,17 +323,44 @@ class MacpClient {
             throw new errors_1.MacpSdkError('this operation requires auth; pass auth= or configure client.auth');
         return selected;
     }
-    metadata(auth) {
+    /**
+     * Throws {@link MacpSdkError}, without sending anything, unless
+     * `capabilities.<group>.<flag>` from {@link initialize} is `true`. Calls
+     * `Initialize` once if this client hasn't; concurrent first callers share
+     * that one in-flight call (and the first caller's deadline).
+     */
+    async requireCapability(group, flag, rpc, rfc, deadlineMs) {
+        const capabilities = this.serverCapabilities ??
+            (await (this.pendingInit ??= this.initialize(deadlineMs).finally(() => {
+                this.pendingInit = undefined;
+            }))).capabilities;
+        const advertised = capabilities?.[group];
+        if (advertised?.[flag] !== true) {
+            throw new errors_1.MacpSdkError(`this runtime does not advertise capabilities.${group}.${flag}; ` +
+                `${rpc} is optional and a client MUST NOT call it otherwise (${rfc})`);
+        }
+    }
+    /**
+     * 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) {
@@ -354,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)
@@ -391,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;
@@ -538,12 +584,7 @@ class MacpClient {
      */
     async whatIfReplay(sessionId, candidate, options) {
         const auth = this.requireAuth(options?.auth);
-        const capabilities = this.serverCapabilities ?? (await this.initialize(options?.deadlineMs)).capabilities;
-        const policyRegistry = capabilities?.policyRegistry;
-        if (!policyRegistry?.whatIfReplay) {
-            throw new errors_1.MacpSdkError('this runtime does not advertise capabilities.policyRegistry.whatIfReplay; ' +
-                'WhatIfReplay is optional and a client MUST NOT call it otherwise (RFC-MACP-0012 §8.1)');
-        }
+        await this.requireCapability('policyRegistry', 'whatIfReplay', 'WhatIfReplay', 'RFC-MACP-0012 §8.1', options?.deadlineMs);
         const res = await this.unary('WhatIfReplay', { sessionId, candidate }, auth, options?.deadlineMs);
         // proto3 `optional` decodes with a synthetic oneof discriminator; an unset
         // first_divergence is absent, never "0" (index 0 is the SessionStart).
@@ -555,6 +596,54 @@ class MacpClient {
         delete result._firstDivergence;
         return result;
     }
+    /**
+     * Fetch the runtime-issued decision receipt for a resolved session
+     * (RFC-MACP-0013 §13). Returns the parsed `macp-receipt/1` object and `raw`,
+     * the exact JSON text the runtime served, which is stable across calls
+     * (§13 item 6), so it can be stored or forwarded byte for byte. Verify it
+     * with `verifyReceipt(receipt, trustedKeysFromJwks(await getReceiptKeys()))`;
+     * this method does not.
+     *
+     * The RPC is optional, so this checks
+     * `capabilities.decisionReceipt.getDecisionReceipt` from {@link initialize}
+     * first (calling it once if this client hasn't) and throws
+     * {@link MacpSdkError} without sending anything when the runtime doesn't
+     * advertise it. Authorized as {@link getSession}. Runtime refusals arrive as
+     * {@link MacpTransportError} with `macpErrorCode` set: `RECEIPT_UNAVAILABLE`
+     * (no receipt can be issued: not resolved yet, or resolved without a
+     * `CommitmentPayload`), `SESSION_NOT_FOUND`, `FORBIDDEN`,
+     * `INTERNAL_ERROR`. A `receipt_json` that isn't a JSON object throws
+     * {@link MacpSdkError}.
+     */
+    async getDecisionReceipt(sessionId, options) {
+        const auth = this.requireAuth(options?.auth);
+        await this.requireCapability('decisionReceipt', 'getDecisionReceipt', 'GetDecisionReceipt', 'RFC-MACP-0013 §13', options?.deadlineMs);
+        const res = await this.unary('GetDecisionReceipt', { sessionId }, auth, options?.deadlineMs);
+        const raw = res.receiptJson ?? '';
+        const receipt = parseJsonObject(raw, 'receipt_json');
+        return { receipt: receipt, raw };
+    }
+    /**
+     * Fetch the JWK Set of public keys the runtime signs receipts with
+     * (RFC-MACP-0013 §13 item 8); an unsigned runtime returns `{keys: []}`. Pass
+     * it to `trustedKeysFromJwks` for the map `verifyReceipt` takes. Whether
+     * to trust these keys is the caller's decision.
+     *
+     * Gated on `capabilities.decisionReceipt.getDecisionReceipt` like
+     * {@link getDecisionReceipt}. Needs transport auth only, like
+     * {@link getManifest}: `auth` is optional and falls back to the client's.
+     * A `jwks_json` that isn't a JSON object with a `keys` array throws
+     * {@link MacpSdkError}.
+     */
+    async getReceiptKeys(options) {
+        await this.requireCapability('decisionReceipt', 'getDecisionReceipt', 'GetReceiptKeys', 'RFC-MACP-0013 §13', options?.deadlineMs);
+        const res = await this.unary('GetReceiptKeys', {}, options?.auth, options?.deadlineMs);
+        const jwks = parseJsonObject(res.jwksJson ?? '', 'jwks_json');
+        if (!Array.isArray(jwks.keys)) {
+            throw new errors_1.MacpSdkError('runtime returned a jwks_json with no keys array');
+        }
+        return jwks;
+    }
     /**
      * Fetch a single page of sessions (proto ≥ 0.1.6). `pageSize: 0` (or absent)
      * lets the server choose the page size; the server MAY cap it. Callers MUST
@@ -621,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) {
@@ -683,3 +772,17 @@ class MacpClient {
     }
 }
 exports.MacpClient = MacpClient;
+/** Parses runtime-served JSON text that must be an object, else throws {@link MacpSdkError}. */
+function parseJsonObject(text, field) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (err) {
+        throw new errors_1.MacpSdkError(`runtime returned a ${field} that is not valid JSON: ${err.message}`);
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new errors_1.MacpSdkError(`runtime returned a ${field} that is not a JSON object`);
+    }
+    return value;
+}

package/dist/constants.d.ts

@@ -42,6 +42,13 @@ export declare const AGENT_NOT_FOUND = "AGENT_NOT_FOUND";
  * holds (e.g. compacted when it ended) — FAILED_PRECONDITION. RFC-MACP-0012 §8.1.
  */
 export declare const HISTORY_UNAVAILABLE = "HISTORY_UNAVAILABLE";
+/**
+ * GetDecisionReceipt named a session no receipt can be issued for: not
+ * RESOLVED, resolved without a `CommitmentPayload`, or issuance failed —
+ * FAILED_PRECONDITION. RFC-MACP-0013 §13. **Provisional** in the spec's error
+ * registry (not yet in the parity contract's permanent set).
+ */
+export declare const RECEIPT_UNAVAILABLE = "RECEIPT_UNAVAILABLE";
 export declare const DENY_VETO = "veto";
 export declare const DENY_VETO_HOLD = "veto_hold";
 export declare const DENY_QUORUM_NOT_MET = "quorum_not_met";

package/dist/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KNOWN_DENY_CODES = exports.DENY_UNSPECIFIED = exports.DENY_INVALID_RULES = exports.DENY_UNSUPPORTED_SCHEMA_VERSION = exports.DENY_REASSIGNMENT_NOT_ALLOWED = exports.DENY_OUTPUT_REQUIRED = exports.DENY_CRITERION_NOT_MET = exports.DENY_DECLINE_NOT_BACKED = exports.DENY_DECLINE_OVER_APPROVAL = exports.DENY_NO_VOTES = exports.DENY_EVALUATION_REQUIRED = exports.DENY_CONFIDENCE_BELOW_MINIMUM = exports.DENY_THRESHOLD_NOT_MET = exports.DENY_QUORUM_NOT_MET = exports.DENY_VETO_HOLD = exports.DENY_VETO = exports.HISTORY_UNAVAILABLE = exports.AGENT_NOT_FOUND = exports.STREAM_LAGGED = exports.INVALID_REQUEST = exports.REGISTRY_READ_ONLY = exports.INVALID_POLICY_DEFINITION = exports.UNKNOWN_POLICY_VERSION = exports.INVALID_SESSION_ID = exports.POLICY_DENIED = exports.INTERNAL_ERROR = exports.RATE_LIMITED = exports.PAYLOAD_TOO_LARGE = exports.DUPLICATE_MESSAGE = exports.UNAUTHENTICATED = exports.FORBIDDEN = exports.MODE_NOT_SUPPORTED = exports.SESSION_NOT_OPEN = exports.SESSION_NOT_FOUND = exports.SESSION_ALREADY_EXISTS = exports.INVALID_ENVELOPE = exports.UNSUPPORTED_PROTOCOL_VERSION = exports.STANDARD_MODES = exports.MODE_MULTI_ROUND = exports.MODE_QUORUM = exports.MODE_HANDOFF = exports.MODE_TASK = exports.MODE_PROPOSAL = exports.MODE_DECISION = exports.DEFAULT_POLICY_VERSION = exports.DEFAULT_CONFIGURATION_VERSION = exports.DEFAULT_MODE_VERSION = exports.MACP_VERSION = void 0;
+exports.KNOWN_DENY_CODES = exports.DENY_UNSPECIFIED = exports.DENY_INVALID_RULES = exports.DENY_UNSUPPORTED_SCHEMA_VERSION = exports.DENY_REASSIGNMENT_NOT_ALLOWED = exports.DENY_OUTPUT_REQUIRED = exports.DENY_CRITERION_NOT_MET = exports.DENY_DECLINE_NOT_BACKED = exports.DENY_DECLINE_OVER_APPROVAL = exports.DENY_NO_VOTES = exports.DENY_EVALUATION_REQUIRED = exports.DENY_CONFIDENCE_BELOW_MINIMUM = exports.DENY_THRESHOLD_NOT_MET = exports.DENY_QUORUM_NOT_MET = exports.DENY_VETO_HOLD = exports.DENY_VETO = exports.RECEIPT_UNAVAILABLE = exports.HISTORY_UNAVAILABLE = exports.AGENT_NOT_FOUND = exports.STREAM_LAGGED = exports.INVALID_REQUEST = exports.REGISTRY_READ_ONLY = exports.INVALID_POLICY_DEFINITION = exports.UNKNOWN_POLICY_VERSION = exports.INVALID_SESSION_ID = exports.POLICY_DENIED = exports.INTERNAL_ERROR = exports.RATE_LIMITED = exports.PAYLOAD_TOO_LARGE = exports.DUPLICATE_MESSAGE = exports.UNAUTHENTICATED = exports.FORBIDDEN = exports.MODE_NOT_SUPPORTED = exports.SESSION_NOT_OPEN = exports.SESSION_NOT_FOUND = exports.SESSION_ALREADY_EXISTS = exports.INVALID_ENVELOPE = exports.UNSUPPORTED_PROTOCOL_VERSION = exports.STANDARD_MODES = exports.MODE_MULTI_ROUND = exports.MODE_QUORUM = exports.MODE_HANDOFF = exports.MODE_TASK = exports.MODE_PROPOSAL = exports.MODE_DECISION = exports.DEFAULT_POLICY_VERSION = exports.DEFAULT_CONFIGURATION_VERSION = exports.DEFAULT_MODE_VERSION = exports.MACP_VERSION = void 0;
 exports.MACP_VERSION = '1.0';
 exports.DEFAULT_MODE_VERSION = '1.0.0';
 exports.DEFAULT_CONFIGURATION_VERSION = 'config.default';
@@ -49,6 +49,13 @@ exports.AGENT_NOT_FOUND = 'AGENT_NOT_FOUND';
  * holds (e.g. compacted when it ended) — FAILED_PRECONDITION. RFC-MACP-0012 §8.1.
  */
 exports.HISTORY_UNAVAILABLE = 'HISTORY_UNAVAILABLE';
+/**
+ * GetDecisionReceipt named a session no receipt can be issued for: not
+ * RESOLVED, resolved without a `CommitmentPayload`, or issuance failed —
+ * FAILED_PRECONDITION. RFC-MACP-0013 §13. **Provisional** in the spec's error
+ * registry (not yet in the parity contract's permanent set).
+ */
+exports.RECEIPT_UNAVAILABLE = 'RECEIPT_UNAVAILABLE';
 // Structured POLICY_DENIED denial codes (`PolicyDenial.code`, runtime ≥ 0.9.0;
 // RFC-MACP-0012 §6.2). Open set — names match python-sdk's exports.
 exports.DENY_VETO = 'veto';

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export * from './proposal';
 export * from './proto-registry';
 export * from './retry';
 export * from './quorum';
-export { RECEIPT_FORMAT, buildReceipt, commitmentFromProjection, verifyReceipt, type AttestationOutcome, type BuildReceiptOptions, type DecisionReceipt, type JwsAttestation, type ReceiptAttestation, type ReceiptCommitment, type ReceiptIntegrity, type ReceiptSigner, type ReceiptVerdict, type ReceiptVerification, type VendorAttestation, } from './receipt';
+export { RECEIPT_FORMAT, buildReceipt, commitmentFromProjection, trustedKeysFromJwks, verifyReceipt, type AttestationOutcome, type BuildReceiptOptions, type DecisionReceipt, type DecisionReceiptResult, type JwsAttestation, type ReceiptAttestation, type ReceiptCommitment, type ReceiptIntegrity, type ReceiptJwk, type ReceiptKeySet, type ReceiptSigner, type ReceiptVerdict, type ReceiptVerification, type VendorAttestation, } from './receipt';
 export * from './task';
 export * from './types';
 export * from './validation';

package/dist/index.js

@@ -36,7 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.agent = exports.VERSION = exports.verifyReceipt = exports.commitmentFromProjection = exports.buildReceipt = exports.RECEIPT_FORMAT = exports.logger = exports.configureLogging = exports.verifyCommitmentHash = exports.isCanonicalCommitmentHash = exports.commitmentHash = exports.Auth = void 0;
+exports.agent = exports.VERSION = exports.verifyReceipt = exports.trustedKeysFromJwks = exports.commitmentFromProjection = exports.buildReceipt = exports.RECEIPT_FORMAT = exports.logger = exports.configureLogging = exports.verifyCommitmentHash = exports.isCanonicalCommitmentHash = exports.commitmentHash = exports.Auth = void 0;
 // Auth: export only the public constructors and types. The helpers
 // `validateAuth`, `authSender`, `assertSenderMatchesIdentity`, and
 // `metadataFromAuth` are SDK-internal — importable from the `./auth`
@@ -84,6 +84,7 @@ var receipt_1 = require("./receipt");
 Object.defineProperty(exports, "RECEIPT_FORMAT", { enumerable: true, get: function () { return receipt_1.RECEIPT_FORMAT; } });
 Object.defineProperty(exports, "buildReceipt", { enumerable: true, get: function () { return receipt_1.buildReceipt; } });
 Object.defineProperty(exports, "commitmentFromProjection", { enumerable: true, get: function () { return receipt_1.commitmentFromProjection; } });
+Object.defineProperty(exports, "trustedKeysFromJwks", { enumerable: true, get: function () { return receipt_1.trustedKeysFromJwks; } });
 Object.defineProperty(exports, "verifyReceipt", { enumerable: true, get: function () { return receipt_1.verifyReceipt; } });
 __exportStar(require("./task"), exports);
 __exportStar(require("./types"), exports);

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/receipt.d.ts

@@ -49,6 +49,32 @@ export interface DecisionReceipt {
     issued_at: string;
     attestations: ReceiptAttestation[];
 }
+/**
+ * {@link MacpClient.getDecisionReceipt}'s result: the parsed receipt and the
+ * `receipt_json` text exactly as the runtime served it, so a caller can store
+ * the issued bytes unchanged (RFC-MACP-0013 §13 item 6 serves them
+ * byte-identical). `receipt` is parsed, not validated: {@link verifyReceipt}
+ * is the authority on whether it is a well-formed `macp-receipt/1`.
+ */
+export interface DecisionReceiptResult {
+    receipt: DecisionReceipt;
+    raw: string;
+}
+/** One JWK of a receipt key set (`schemas/json/macp-receipt-keys.schema.json`). */
+export interface ReceiptJwk {
+    kid: string;
+    kty: string;
+    crv?: string;
+    x?: string;
+    alg?: string;
+    use?: string;
+    [member: string]: unknown;
+}
+/** A JWK Set [RFC 7517] of receipt verification keys, as `GetReceiptKeys` returns it. */
+export interface ReceiptKeySet {
+    keys: ReceiptJwk[];
+    [member: string]: unknown;
+}
 /**
  * Signs a receipt with Ed25519: either a 32-byte private key seed, or a
  * callback that returns the 64-byte signature over `signingInput` (for a key
@@ -122,3 +148,19 @@ export declare function buildReceipt(commitment: CommitmentPayload, options: Bui
  * Never throws: malformed input yields an outcome, not an exception.
  */
 export declare function verifyReceipt(receipt: unknown, trustedKeys: Record<string, string>): ReceiptVerification;
+/**
+ * Turns a receipt key set (the JWK Set `GetReceiptKeys` returns, RFC-MACP-0013
+ * §13 item 8) into the `kid → x` map {@link verifyReceipt} takes. Choosing to
+ * trust the set is the caller's decision; this only converts it.
+ *
+ * A key is kept only if it is an Ed25519 public key (`kty` `OKP`, `crv`
+ * `Ed25519`) with a non-empty `kid` and `x`, an `alg` (if any) of `EdDSA`, a
+ * `use` (if any) of `sig`, and no private member (`d`, `p`, `q`, `dp`, `dq`,
+ * `qi`, `oth`, `k`): a key set that publishes private key material is
+ * misconfigured and is not trusted silently. A `kid` that more than one entry
+ * of the set claims is dropped entirely, even when the other entry is a key
+ * this function can't use (an EC key, say): item 8 makes kids unique across
+ * the whole set, so a repeated one leaves the set ambiguous about which key it
+ * names. Never throws: input that is not a key set yields `{}`.
+ */
+export declare function trustedKeysFromJwks(jwks: unknown): Record<string, string>;

package/dist/receipt.js

@@ -4,6 +4,7 @@ exports.RECEIPT_FORMAT = void 0;
 exports.commitmentFromProjection = commitmentFromProjection;
 exports.buildReceipt = buildReceipt;
 exports.verifyReceipt = verifyReceipt;
+exports.trustedKeysFromJwks = trustedKeysFromJwks;
 /**
  * RFC-MACP-0013 Appendix A decision receipts (`macp-receipt/1`).
  *
@@ -374,3 +375,54 @@ function verifyReceipt(receipt, trustedKeys) {
         verdict: outcomes.includes('valid') ? 'attested' : 'integrity_only',
     };
 }
+/** JWK private-key members (RFC 7518 §6); RFC-MACP-0013 §13 item 8 forbids them in a key set. */
+const PRIVATE_JWK_MEMBERS = ['d', 'p', 'q', 'dp', 'dq', 'qi', 'oth', 'k'];
+const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
+/** An Ed25519 public verification key usable for an EdDSA `jws` attestation. */
+function usableEd25519Key(key) {
+    if (!isRecord(key))
+        return false;
+    if (key.kty !== 'OKP' || key.crv !== 'Ed25519')
+        return false;
+    if (!isNonEmptyString(key.kid) || !isNonEmptyString(key.x))
+        return false;
+    if (key.alg !== undefined && key.alg !== 'EdDSA')
+        return false;
+    if (key.use !== undefined && key.use !== 'sig')
+        return false;
+    return !PRIVATE_JWK_MEMBERS.some((m) => Object.prototype.hasOwnProperty.call(key, m));
+}
+/**
+ * Turns a receipt key set (the JWK Set `GetReceiptKeys` returns, RFC-MACP-0013
+ * §13 item 8) into the `kid → x` map {@link verifyReceipt} takes. Choosing to
+ * trust the set is the caller's decision; this only converts it.
+ *
+ * A key is kept only if it is an Ed25519 public key (`kty` `OKP`, `crv`
+ * `Ed25519`) with a non-empty `kid` and `x`, an `alg` (if any) of `EdDSA`, a
+ * `use` (if any) of `sig`, and no private member (`d`, `p`, `q`, `dp`, `dq`,
+ * `qi`, `oth`, `k`): a key set that publishes private key material is
+ * misconfigured and is not trusted silently. A `kid` that more than one entry
+ * of the set claims is dropped entirely, even when the other entry is a key
+ * this function can't use (an EC key, say): item 8 makes kids unique across
+ * the whole set, so a repeated one leaves the set ambiguous about which key it
+ * names. Never throws: input that is not a key set yields `{}`.
+ */
+function trustedKeysFromJwks(jwks) {
+    const result = {};
+    if (!isRecord(jwks) || !Array.isArray(jwks.keys))
+        return result;
+    // Count every entry's string kid, usable or not, before keeping any.
+    const claims = new Map();
+    for (const key of jwks.keys) {
+        if (isRecord(key) && typeof key.kid === 'string')
+            claims.set(key.kid, (claims.get(key.kid) ?? 0) + 1);
+    }
+    for (const key of jwks.keys) {
+        if (!usableEd25519Key(key) || claims.get(key.kid) !== 1)
+            continue;
+        // defineProperty, not assignment: a kid of "__proto__" must become an own
+        // key (which verifyReceipt's hasOwnProperty lookup finds), not a prototype.
+        Object.defineProperty(result, key.kid, { value: key.x, enumerable: true, writable: true, configurable: true });
+    }
+    return result;
+}

package/dist/types.d.ts

@@ -107,6 +107,23 @@ export interface PolicyRegistryCapability {
      */
     whatIfReplay?: boolean;
 }
+/**
+ * `capabilities.decisionReceipt` (`macp.v1.DecisionReceiptCapability`, proto
+ * ≥ 0.1.13): optional runtime-issued decision receipts (RFC-MACP-0013 §13).
+ */
+export interface DecisionReceiptCapability {
+    /**
+     * The runtime implements `GetDecisionReceipt` and `GetReceiptKeys`;
+     * {@link MacpClient.getDecisionReceipt} and {@link MacpClient.getReceiptKeys}
+     * refuse to call them otherwise.
+     */
+    getDecisionReceipt?: boolean;
+    /**
+     * Every receipt issued from now on carries at least one EdDSA `jws`
+     * attestation. Says nothing about receipts issued earlier.
+     */
+    signed?: boolean;
+}
 /** How one replay handled one history entry (`macp.v1.WhatIfEntryOutcome`). */
 export interface WhatIfEntryOutcome {
     kind: 'KIND_UNSPECIFIED' | 'KIND_APPLIED' | 'KIND_NOT_OPEN' | 'KIND_REFUSED' | 'KIND_NO_SESSION';

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.19.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.19.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.19.0",
+  "version": "0.21.0",
   "description": "TypeScript SDK for the MACP Rust runtime",
   "license": "Apache-2.0",
   "type": "commonjs",
@@ -60,12 +60,23 @@
   "dependencies": {
     "@grpc/grpc-js": "^1.14.3",
     "@grpc/proto-loader": "^0.8.0",
-    "@multiagentcoordinationprotocol/proto": "^0.1.12",
+    "@multiagentcoordinationprotocol/proto": "^0.1.13",
     "@noble/curves": "^1.9.7",
     "@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",