macp-sdk-typescript 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,83 @@ 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.5.0] - 2026-07-06
+
+Absorbs `macp-runtime` 0.5.0 and `@multiagentcoordinationprotocol/proto` 0.1.6
+(resolves to ≥ 0.1.6; content identical through 0.1.8). Plan:
+`plans/absorb-runtime-v0.5.0.md`.
+
+**Requires `macp-runtime` ≥ 0.5.0** for: protobuf `Contribute` encoding, the
+empty-`policy_version` commitment echo, the external task orchestrator, and the
+bearer-only dev-auth flow (the runtime no longer reads `x-macp-agent-id`, and
+refuses to start with no auth unless `MACP_ALLOW_INSECURE=1`). Pin `0.4.x` to
+talk to an older runtime.
+
+### Added
+
+- **`SessionStartPayload.maxSuspendMs`** (proto ≥ 0.1.5) — per-session cap on
+  cumulative suspended time before a `SUSPENDED` session `EXPIRE`s (RFC-MACP-0001
+  §7.5). Threaded through `buildSessionStartPayload`, every mode session's
+  `start()`, the `Participant` initiator config, and the bootstrap runner
+  (`session_start.max_suspend_ms`). `0`/absent = runtime default (7 days);
+  negatives are rejected client-side.
+- **`HandoffAcceptPayload.implicit` decode support** (proto ≥ 0.1.6) — surfaced
+  read-only on `HandoffRecord.implicit` and `HandoffProjection.isImplicitlyAccepted()`
+  for the runtime-emitted synthetic accept (RFC-MACP-0010 §5.1). Client-submitted
+  `implicit` is stripped before encoding so it can never reach the wire.
+- **`ListSessions` pagination** (proto ≥ 0.1.6) — new
+  `MacpClient.listSessionsPage({ pageSize, pageToken })` returning
+  `{ sessions, nextPageToken }`; `listSessions()` now transparently auto-paginates
+  so it still returns the complete listing.
+- **`ext.multi_round.v1` `Contribute` uses canonical protobuf** — encodes as
+  `ContributePayload`; decode tries legacy JSON (`{"value":"..."}`) first for
+  byte-identical replay of pre-proto histories.
+- **`MacpTransportError.code`** — carries the gRPC status name
+  (`RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `UNAUTHENTICATED`, …) surfaced on
+  unary calls, `MacpStream`, and watch streams, so consumers can distinguish
+  watch-stream lag (reconnect) from auth failure (don't) and passive-subscribe
+  resume below a compacted base.
+- **`GrpcTransportAdapter.lastSequence`** — the 1-based accepted-envelope ordinal
+  of the last delivered envelope, a resume cursor for `sendSubscribe`.
+
+### Changed
+
+- **Dev auth is bearer-only.** `Auth.devAgent(agentId)` now sends
+  `Authorization: Bearer <agentId>` (was the `x-macp-agent-id` header). The
+  runtime's dev fallback authenticates any bearer value as its sender, so
+  behavior is transparent for existing callers — but the wire header changed.
+  Integration/runbook: drop `MACP_ALLOW_DEV_SENDER_HEADER=1`, keep the now-mandatory
+  `MACP_ALLOW_INSECURE=1`.
+- **`MacpClient.watchSignals` requires auth** (runtime 0.5.0) — routed through
+  `requireAuth`, so a missing credential fails fast client-side instead of as a
+  stream `UNAUTHENTICATED`. Breaking for anyone watching signals without auth.
+- **`buildQuorumPolicy` validates percentage thresholds.** A `percentage`
+  `threshold.value` must be an integer 0–100 (the approval bar =
+  `ceil(value/100 × participants)`); a fractional value like `0.75` (previously a
+  silent ~1% bar) now throws `MacpSessionError`. Bug-surfacing by design.
+- **`registerExtMode` pre-validates descriptors** — throws if
+  `terminalMessageTypes` lacks `'Commitment'` (mirrors the runtime, which rejects
+  such descriptors).
+- **Canonical conformance fixtures + harness.** Vendored fixtures byte-synced to
+  the spec canonical pack (fully-qualified `payload_type`, `expected_error_code`,
+  `schema.json`); the harness parses FQ names only, with a format guard rejecting
+  legacy shorthand.
+- **`SessionStartPayload` bodies now emit `maxSuspendMs`** (`0` when unset).
+
+### Removed
+
+- **`AuthConfig.agentId`** and the `x-macp-agent-id` metadata path — no supported
+  runtime reads the header. Use `Auth.devAgent` / `Auth.bearer`.
+- **`SessionLifecycleWatcher.events()` / `nextEvent()`** — deprecated aliases;
+  use `changes()` / `nextChange()`.
+- **`MacpClient._watchModeRegistry` / `_watchRoots` / `_watchSignals` /
+  `_watchPolicies`** — deprecated underscored aliases; use the un-prefixed
+  `watch*` methods.
+
+### Fixed
+
+- `MacpClient.clientVersion` default was a stale `'0.3.0'`; now `'0.5.0'`.
+
 ## [0.4.0] - 2026-06-22
 
 Adopts `@multiagentcoordinationprotocol/proto` 0.1.3 — session

package/README.md

@@ -297,7 +297,8 @@ See [`docs/api/cancel-callback.md`](docs/api/cancel-callback.md) and
 ## Authentication
 
 ```typescript
-// Development (uses x-macp-agent-id header)
+// Development (bearer-only; sends Authorization: Bearer my-agent).
+// Requires the runtime to run with MACP_ALLOW_INSECURE=1.
 const auth = Auth.devAgent('my-agent');
 
 // Production (Bearer token with authenticated identity — RFC-MACP-0004 §4).
@@ -417,7 +418,7 @@ Run the full SDK against a live MACP runtime:
 docker build -t macp-runtime ../macp-runtime/
 docker run -d --name macp-runtime-test -p 50051:50051 \
   -e MACP_BIND_ADDR=0.0.0.0:50051 -e MACP_ALLOW_INSECURE=1 \
-  -e MACP_ALLOW_DEV_SENDER_HEADER=1 -e MACP_MEMORY_ONLY=1 macp-runtime
+  -e MACP_MEMORY_ONLY=1 macp-runtime
 
 # Run tests
 npm run test:integration

package/dist/agent/participant.d.ts

@@ -9,6 +9,8 @@ export interface InitiatorConfig {
         intent: string;
         participants: string[];
         ttlMs: number;
+        /** Per-session max-suspend cap (ms, proto ≥ 0.1.5). 0/absent = runtime default. */
+        maxSuspendMs?: number;
         contextId?: string;
         extensions?: Record<string, Buffer>;
         context?: Record<string, unknown>;

package/dist/agent/participant.js

@@ -298,6 +298,7 @@ class Participant {
                 intent: ss.intent,
                 participants: ss.participants,
                 ttlMs: ss.ttlMs,
+                maxSuspendMs: ss.maxSuspendMs,
                 contextId: ss.contextId,
                 extensions: ss.extensions,
                 roots: ss.roots,

package/dist/agent/runner.d.ts

@@ -18,6 +18,7 @@ export interface BootstrapPayload {
             intent: string;
             participants: string[];
             ttl_ms: number;
+            max_suspend_ms?: number;
             mode_version?: string;
             configuration_version?: string;
             policy_version?: string;

package/dist/agent/runner.js

@@ -77,6 +77,7 @@ function fromBootstrap(bootstrapPath) {
                 intent: ss.intent,
                 participants: ss.participants,
                 ttlMs: ss.ttl_ms,
+                maxSuspendMs: ss.max_suspend_ms,
                 contextId: ss.context_id,
                 extensions: encodeExtensions(ss.extensions),
                 roots: ss.roots,

package/dist/agent/transports.d.ts

@@ -11,7 +11,17 @@ export declare class GrpcTransportAdapter implements TransportAdapter {
     private readonly auth?;
     private stream;
     private seq;
+    private delivered;
     constructor(client: MacpClient, sessionId: string, auth?: AuthConfig | undefined);
+    /**
+     * The server passive-subscribe ordinal of the last delivered envelope (the
+     * 1-based count of accepted envelopes delivered on this stream, RFC-MACP-0006
+     * §3.2). `0` before anything is delivered. Pass this as `afterSequence` to
+     * `MacpStream.sendSubscribe` on a reconnect to resume exactly-once — ordinals
+     * are stable across compaction/restart. Distinct from `IncomingMessage.seq`,
+     * which is a client-local 0-based delivery index.
+     */
+    get lastSequence(): number;
     start(): AsyncIterable<IncomingMessage>;
     stop(): Promise<void>;
 }

package/dist/agent/transports.js

@@ -18,11 +18,23 @@ class GrpcTransportAdapter {
     auth;
     stream = null;
     seq = 0;
+    delivered = 0;
     constructor(client, sessionId, auth) {
         this.client = client;
         this.sessionId = sessionId;
         this.auth = auth;
     }
+    /**
+     * The server passive-subscribe ordinal of the last delivered envelope (the
+     * 1-based count of accepted envelopes delivered on this stream, RFC-MACP-0006
+     * §3.2). `0` before anything is delivered. Pass this as `afterSequence` to
+     * `MacpStream.sendSubscribe` on a reconnect to resume exactly-once — ordinals
+     * are stable across compaction/restart. Distinct from `IncomingMessage.seq`,
+     * which is a client-local 0-based delivery index.
+     */
+    get lastSequence() {
+        return this.delivered;
+    }
     async *start() {
         this.stream = this.client.openStream({ auth: this.auth });
         // RFC-MACP-0006-A1: Subscribe to the session with history replay.
@@ -33,6 +45,7 @@ class GrpcTransportAdapter {
         for await (const envelope of this.stream.responses()) {
             if (envelope.sessionId !== this.sessionId)
                 continue;
+            this.delivered++;
             yield normalizeEnvelope(envelope, (mode, mt, p) => this.client.protoRegistry.decodeKnownPayload(mode, mt, p), this.seq++);
         }
     }

package/dist/auth.d.ts

@@ -1,7 +1,6 @@
 import * as grpc from '@grpc/grpc-js';
 export interface AuthConfig {
     bearerToken?: string;
-    agentId?: string;
     senderHint?: string;
     /**
      * The authenticated sender this credential represents. When present, the SDK
@@ -22,10 +21,16 @@ export type BearerAuthOptions = string | {
 };
 export declare const Auth: {
     /**
-     * Dev-mode agent identity. Uses the `x-macp-agent-id` header — only accepted
-     * by runtimes started with `MACP_ALLOW_DEV_SENDER_HEADER=1`. Not for
-     * production. Does not set {@link AuthConfig.expectedSender}; dev flows stay
-     * permissive so tests can reuse a single credential across senders.
+     * Dev-mode agent identity (bearer-only, runtime ≥ 0.5.0). Sends
+     * `Authorization: Bearer <agentId>`; the runtime's dev fallback authenticates
+     * any bearer value as the sender of that value, so `Auth.devAgent('alice')`
+     * authenticates as sender `alice`. Requires the runtime to be started with
+     * `MACP_ALLOW_INSECURE=1` (it refuses to start with no auth configured
+     * otherwise). Not for production — use {@link Auth.bearer}.
+     *
+     * The legacy `x-macp-agent-id` header was removed in 0.5.0: no supported
+     * runtime reads it. Does not set {@link AuthConfig.expectedSender}; dev flows
+     * stay permissive so tests can reuse a single credential across senders.
      */
     devAgent(agentId: string): AuthConfig;
     /**

package/dist/auth.js

@@ -42,13 +42,19 @@ const grpc = __importStar(require("@grpc/grpc-js"));
 const errors_1 = require("./errors");
 exports.Auth = {
     /**
-     * Dev-mode agent identity. Uses the `x-macp-agent-id` header — only accepted
-     * by runtimes started with `MACP_ALLOW_DEV_SENDER_HEADER=1`. Not for
-     * production. Does not set {@link AuthConfig.expectedSender}; dev flows stay
-     * permissive so tests can reuse a single credential across senders.
+     * Dev-mode agent identity (bearer-only, runtime ≥ 0.5.0). Sends
+     * `Authorization: Bearer <agentId>`; the runtime's dev fallback authenticates
+     * any bearer value as the sender of that value, so `Auth.devAgent('alice')`
+     * authenticates as sender `alice`. Requires the runtime to be started with
+     * `MACP_ALLOW_INSECURE=1` (it refuses to start with no auth configured
+     * otherwise). Not for production — use {@link Auth.bearer}.
+     *
+     * The legacy `x-macp-agent-id` header was removed in 0.5.0: no supported
+     * runtime reads it. Does not set {@link AuthConfig.expectedSender}; dev flows
+     * stay permissive so tests can reuse a single credential across senders.
      */
     devAgent(agentId) {
-        return { agentId, senderHint: agentId };
+        return { bearerToken: agentId, senderHint: agentId };
     },
     /**
      * Production bearer-token credential. Pass `{ expectedSender }` to have the
@@ -75,17 +81,14 @@ exports.Auth = {
     },
 };
 function validateAuth(auth) {
-    if (!auth.bearerToken && !auth.agentId) {
-        throw new Error('either bearerToken or agentId is required');
-    }
-    if (auth.bearerToken && auth.agentId) {
-        throw new Error('choose either bearerToken or agentId, not both');
+    if (!auth.bearerToken) {
+        throw new Error('bearerToken is required');
     }
 }
 function authSender(auth) {
     if (!auth)
         return undefined;
-    return auth.expectedSender ?? auth.senderHint ?? auth.agentId;
+    return auth.expectedSender ?? auth.senderHint;
 }
 /**
  * Throw {@link MacpIdentityMismatchError} when a caller-supplied `sender`
@@ -104,9 +107,6 @@ function assertSenderMatchesIdentity(auth, sender) {
 function metadataFromAuth(auth) {
     validateAuth(auth);
     const metadata = new grpc.Metadata();
-    if (auth.bearerToken)
-        metadata.set('authorization', `Bearer ${auth.bearerToken}`);
-    if (auth.agentId)
-        metadata.set('x-macp-agent-id', auth.agentId);
+    metadata.set('authorization', `Bearer ${auth.bearerToken}`);
     return metadata;
 }

package/dist/base-session.d.ts

@@ -40,6 +40,7 @@ export declare abstract class BaseSession<P extends BaseProjection> {
         intent: string;
         participants: string[];
         ttlMs: number;
+        maxSuspendMs?: number;
         contextId?: string;
         extensions?: Record<string, Buffer>;
         roots?: Root[];

package/dist/base-session.js

@@ -58,10 +58,13 @@ class BaseSession {
     /** Send SessionStart and begin tracking via the projection. */
     async start(input) {
         (0, validation_1.validateParticipantCount)(input.participants.length);
+        if (input.maxSuspendMs !== undefined)
+            (0, validation_1.validateMaxSuspendMs)(input.maxSuspendMs);
         const payload = (0, envelope_1.buildSessionStartPayload)({
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
+            maxSuspendMs: input.maxSuspendMs,
             contextId: input.contextId,
             extensions: input.extensions,
             roots: input.roots,

package/dist/client.d.ts

@@ -23,6 +23,12 @@ interface MacpClientOptions {
     clientVersion?: string;
     protoDir?: string;
 }
+/**
+ * Map a gRPC `ServiceError.code` (numeric `grpc.status`) to its status name
+ * (e.g. `8` → `'RESOURCE_EXHAUSTED'`). Returns `undefined` for non-numeric or
+ * unknown codes. Used to populate {@link MacpTransportError.code}.
+ */
+export declare function grpcStatusName(code: unknown): string | undefined;
 export type InlineErrorCallback = (error: {
     code?: string;
     message?: string;
@@ -36,9 +42,19 @@ export declare class MacpStream {
     onInlineError(callback: InlineErrorCallback): void;
     send(envelope: Envelope): Promise<void>;
     /**
-     * RFC-MACP-0006-A1: Send a subscribe-only frame to receive session history
-     * + live broadcast. The runtime replays accepted envelopes from
-     * `afterSequence` onwards, then continues with live broadcast.
+     * RFC-MACP-0006 §3.2: Send a subscribe-only frame to receive session history
+     * + live broadcast. The runtime replays accepted envelopes strictly after
+     * `afterSequence`, then continues with live broadcast.
+     *
+     * `afterSequence` is the **1-based accepted-envelope ordinal**, exclusive:
+     * `0` (default) replays from the very start; `k` replays envelopes with
+     * ordinal `> k`. Clients derive the ordinal by counting delivered envelopes
+     * (the Nth accepted envelope has ordinal N) — see
+     * `IncomingMessage.seq`, which is exactly this ordinal under the new contract.
+     * Ordinals are stable across log compaction and runtime restart. Resuming
+     * below a compacted base returns `FAILED_PRECONDITION` (inspectable via
+     * `MacpTransportError.code`) rather than silently skipping history (runtime
+     * ≥ 0.5.0; older runtimes compared inclusively against a raw log index).
      */
     sendSubscribe(sessionId: string, afterSequence?: number): Promise<void>;
     responses(): AsyncGenerator<Envelope, void, void>;
@@ -135,6 +151,20 @@ export declare class MacpClient {
     listRoots(deadlineMs?: number): Promise<{
         roots: Root[];
     }>;
+    /**
+     * Register an extension-mode descriptor (runtime 0.5.0 guardrails,
+     * change-review A5):
+     * - the descriptor MUST declare `Commitment` among `terminalMessageTypes` —
+     *   an ext mode without a terminal `Commitment` can never resolve, so the
+     *   runtime rejects it. This method fails fast client-side to match.
+     * - a later {@link promoteMode} into the reserved `macp.mode.*` namespace is
+     *   rejected by the runtime.
+     * - a SessionStart with an empty `mode_version` binds the registered
+     *   descriptor's `modeVersion`; a subsequent Commitment must echo that bound
+     *   version (echoing `""` no longer matches vacuously). `BaseSession`
+     *   defaults `modeVersion` to `'1.0.0'`, so set the descriptor's version to
+     *   match, or override the session's `modeVersion`.
+     */
     registerExtMode(descriptor: ModeDescriptor, options?: {
         auth?: AuthConfig;
         deadlineMs?: number;
@@ -179,30 +209,46 @@ export declare class MacpClient {
         auth?: AuthConfig;
         deadlineMs?: number;
     }): Promise<PolicyDescriptor[]>;
+    /**
+     * 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
+     * NOT assume the listing is complete unless `nextPageToken` is empty. Pass a
+     * returned non-empty `nextPageToken` back as `pageToken` to fetch the next
+     * page; a stale token yields `INVALID_ARGUMENT`.
+     */
+    listSessionsPage(options?: {
+        pageSize?: number;
+        pageToken?: string;
+        auth?: AuthConfig;
+        deadlineMs?: number;
+    }): Promise<{
+        sessions: SessionMetadata[];
+        nextPageToken: string;
+    }>;
+    /**
+     * Enumerate ALL sessions, transparently walking pages until the runtime
+     * returns an empty `nextPageToken`. Preserves the "complete list" semantics
+     * this method has always documented, even against runtimes that cap page
+     * sizes (proto ≥ 0.1.6). For manual page control, use {@link listSessionsPage}.
+     */
     listSessions(options?: {
         auth?: AuthConfig;
         deadlineMs?: number;
+        pageSize?: number;
     }): Promise<SessionMetadata[]>;
     watchSessions(auth?: AuthConfig): grpc.ClientReadableStream<any>;
     watchPolicies(auth?: AuthConfig): grpc.ClientReadableStream<any>;
-    /** @deprecated Use {@link watchPolicies}. Scheduled for removal in 0.4.0. */
-    _watchPolicies(auth?: AuthConfig): grpc.ClientReadableStream<any>;
     openStream(options?: {
         auth?: AuthConfig;
     }): MacpStream;
     watchModeRegistry(auth?: AuthConfig): grpc.ClientReadableStream<any>;
     watchRoots(auth?: AuthConfig): grpc.ClientReadableStream<any>;
-    watchSignals(auth?: AuthConfig): grpc.ClientReadableStream<any>;
     /**
-     * @deprecated Use {@link watchModeRegistry}, {@link watchRoots},
-     * {@link watchSignals}. Scheduled for removal in 0.4.0 — the underscored
-     * aliases were kept while `src/watchers.ts` migrated.
+     * Subscribe to the ambient signal plane. Requires auth as of runtime 0.5.0 —
+     * routed through {@link requireAuth} so a missing credential fails fast with a
+     * clear client-side error instead of a stream `UNAUTHENTICATED`.
      */
-    _watchModeRegistry(auth?: AuthConfig): grpc.ClientReadableStream<any>;
-    /** @deprecated Use {@link watchRoots}. Scheduled for removal in 0.4.0. */
-    _watchRoots(auth?: AuthConfig): grpc.ClientReadableStream<any>;
-    /** @deprecated Use {@link watchSignals}. Scheduled for removal in 0.4.0. */
-    _watchSignals(auth?: AuthConfig): grpc.ClientReadableStream<any>;
+    watchSignals(auth?: AuthConfig): grpc.ClientReadableStream<any>;
     sendSignal(options: {
         signalType: string;
         data?: Buffer;

package/dist/client.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MacpClient = exports.MacpStream = void 0;
+exports.grpcStatusName = grpcStatusName;
 /* eslint-disable @typescript-eslint/no-explicit-any --
  * The gRPC service client returned by `protoLoader.loadSync()` is typed as
  * `any` by `@grpc/proto-loader`; method signatures (Send, StreamSession,
@@ -98,6 +99,17 @@ class AsyncQueue {
         });
     }
 }
+/**
+ * Map a gRPC `ServiceError.code` (numeric `grpc.status`) to its status name
+ * (e.g. `8` → `'RESOURCE_EXHAUSTED'`). Returns `undefined` for non-numeric or
+ * unknown codes. Used to populate {@link MacpTransportError.code}.
+ */
+function grpcStatusName(code) {
+    if (typeof code !== 'number')
+        return undefined;
+    const name = grpc.status[code];
+    return typeof name === 'string' ? name : undefined;
+}
 const TIMEOUT = Symbol('stream-read-timeout');
 const STREAM_END = Symbol('stream-end');
 class MacpStream {
@@ -120,7 +132,7 @@ class MacpStream {
             }
         });
         call.on('error', (error) => {
-            this.queue.push(new errors_1.MacpTransportError(error.details || error.message));
+            this.queue.push(new errors_1.MacpTransportError(error.details || error.message, grpcStatusName(error.code)));
         });
         call.on('end', () => {
             this.queue.push(STREAM_END);
@@ -142,9 +154,19 @@ class MacpStream {
         });
     }
     /**
-     * RFC-MACP-0006-A1: Send a subscribe-only frame to receive session history
-     * + live broadcast. The runtime replays accepted envelopes from
-     * `afterSequence` onwards, then continues with live broadcast.
+     * RFC-MACP-0006 §3.2: Send a subscribe-only frame to receive session history
+     * + live broadcast. The runtime replays accepted envelopes strictly after
+     * `afterSequence`, then continues with live broadcast.
+     *
+     * `afterSequence` is the **1-based accepted-envelope ordinal**, exclusive:
+     * `0` (default) replays from the very start; `k` replays envelopes with
+     * ordinal `> k`. Clients derive the ordinal by counting delivered envelopes
+     * (the Nth accepted envelope has ordinal N) — see
+     * `IncomingMessage.seq`, which is exactly this ordinal under the new contract.
+     * Ordinals are stable across log compaction and runtime restart. Resuming
+     * below a compacted base returns `FAILED_PRECONDITION` (inspectable via
+     * `MacpTransportError.code`) rather than silently skipping history (runtime
+     * ≥ 0.5.0; older runtimes compared inclusively against a raw log index).
      */
     sendSubscribe(sessionId, afterSequence = 0) {
         if (this.closed)
@@ -223,7 +245,7 @@ class MacpClient {
         }
         this.defaultDeadlineMs = options.defaultDeadlineMs;
         this.clientName = options.clientName ?? 'macp-sdk-typescript';
-        this.clientVersion = options.clientVersion ?? '0.3.0';
+        this.clientVersion = options.clientVersion ?? '0.5.0';
         // eslint-disable-next-line @typescript-eslint/no-require-imports
         const { protoDir: defaultProtoDir } = require('@multiagentcoordinationprotocol/proto');
         const protoDir = options.protoDir ?? defaultProtoDir;
@@ -266,7 +288,7 @@ class MacpClient {
         return new Promise((resolve, reject) => {
             const callback = (error, response) => {
                 if (error)
-                    reject(new errors_1.MacpTransportError(error.details || error.message));
+                    reject(new errors_1.MacpTransportError(error.details || error.message, grpcStatusName(error.code)));
                 else
                     resolve(response);
             };
@@ -382,7 +404,25 @@ class MacpClient {
     async listRoots(deadlineMs) {
         return this.unary('ListRoots', {}, undefined, deadlineMs);
     }
+    /**
+     * Register an extension-mode descriptor (runtime 0.5.0 guardrails,
+     * change-review A5):
+     * - the descriptor MUST declare `Commitment` among `terminalMessageTypes` —
+     *   an ext mode without a terminal `Commitment` can never resolve, so the
+     *   runtime rejects it. This method fails fast client-side to match.
+     * - a later {@link promoteMode} into the reserved `macp.mode.*` namespace is
+     *   rejected by the runtime.
+     * - a SessionStart with an empty `mode_version` binds the registered
+     *   descriptor's `modeVersion`; a subsequent Commitment must echo that bound
+     *   version (echoing `""` no longer matches vacuously). `BaseSession`
+     *   defaults `modeVersion` to `'1.0.0'`, so set the descriptor's version to
+     *   match, or override the session's `modeVersion`.
+     */
     async registerExtMode(descriptor, options) {
+        if (!descriptor.terminalMessageTypes?.includes('Commitment')) {
+            throw new errors_1.MacpSessionError(`ext-mode descriptor '${descriptor.mode}' must declare 'Commitment' in terminalMessageTypes; ` +
+                'a mode without a terminal Commitment can never resolve and the runtime rejects it.');
+        }
         const auth = this.requireAuth(options?.auth);
         return this.unary('RegisterExtMode', { modeDescriptor: descriptor }, auth, options?.deadlineMs);
     }
@@ -412,10 +452,42 @@ class MacpClient {
         const res = await this.unary('ListPolicies', { mode: mode || '' }, auth, options?.deadlineMs);
         return res.descriptors || [];
     }
-    async listSessions(options) {
+    /**
+     * 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
+     * NOT assume the listing is complete unless `nextPageToken` is empty. Pass a
+     * returned non-empty `nextPageToken` back as `pageToken` to fetch the next
+     * page; a stale token yields `INVALID_ARGUMENT`.
+     */
+    async listSessionsPage(options) {
         const auth = this.requireAuth(options?.auth);
-        const res = await this.unary('ListSessions', {}, auth, options?.deadlineMs);
-        return res.sessions || [];
+        const res = await this.unary('ListSessions', { pageSize: options?.pageSize ?? 0, pageToken: options?.pageToken ?? '' }, auth, options?.deadlineMs);
+        return { sessions: res.sessions ?? [], nextPageToken: res.nextPageToken ?? '' };
+    }
+    /**
+     * Enumerate ALL sessions, transparently walking pages until the runtime
+     * returns an empty `nextPageToken`. Preserves the "complete list" semantics
+     * this method has always documented, even against runtimes that cap page
+     * sizes (proto ≥ 0.1.6). For manual page control, use {@link listSessionsPage}.
+     */
+    async listSessions(options) {
+        const all = [];
+        let pageToken = '';
+        // Bound the walk defensively so a misbehaving runtime that never returns an
+        // empty token cannot spin forever.
+        for (let page = 0; page < 100_000; page++) {
+            const res = await this.listSessionsPage({
+                pageSize: options?.pageSize,
+                pageToken,
+                auth: options?.auth,
+                deadlineMs: options?.deadlineMs,
+            });
+            all.push(...res.sessions);
+            if (!res.nextPageToken)
+                return all;
+            pageToken = res.nextPageToken;
+        }
+        return all;
     }
     watchSessions(auth) {
         const metadata = this.metadata(auth);
@@ -425,10 +497,6 @@ class MacpClient {
         const metadata = this.metadata(auth);
         return metadata ? this.client.WatchPolicies({}, metadata) : this.client.WatchPolicies({});
     }
-    /** @deprecated Use {@link watchPolicies}. Scheduled for removal in 0.4.0. */
-    _watchPolicies(auth) {
-        return this.watchPolicies(auth);
-    }
     openStream(options) {
         const auth = this.requireAuth(options?.auth);
         const metadata = this.metadata(auth);
@@ -443,25 +511,15 @@ class MacpClient {
         const metadata = this.metadata(auth);
         return metadata ? this.client.WatchRoots({}, metadata) : this.client.WatchRoots({});
     }
-    watchSignals(auth) {
-        const metadata = this.metadata(auth);
-        return metadata ? this.client.WatchSignals({}, metadata) : this.client.WatchSignals({});
-    }
     /**
-     * @deprecated Use {@link watchModeRegistry}, {@link watchRoots},
-     * {@link watchSignals}. Scheduled for removal in 0.4.0 — the underscored
-     * aliases were kept while `src/watchers.ts` migrated.
+     * Subscribe to the ambient signal plane. Requires auth as of runtime 0.5.0 —
+     * routed through {@link requireAuth} so a missing credential fails fast with a
+     * clear client-side error instead of a stream `UNAUTHENTICATED`.
      */
-    _watchModeRegistry(auth) {
-        return this.watchModeRegistry(auth);
-    }
-    /** @deprecated Use {@link watchRoots}. Scheduled for removal in 0.4.0. */
-    _watchRoots(auth) {
-        return this.watchRoots(auth);
-    }
-    /** @deprecated Use {@link watchSignals}. Scheduled for removal in 0.4.0. */
-    _watchSignals(auth) {
-        return this.watchSignals(auth);
+    watchSignals(auth) {
+        const selected = this.requireAuth(auth);
+        const metadata = (0, auth_1.metadataFromAuth)(selected);
+        return this.client.WatchSignals({}, metadata);
     }
     async sendSignal(options) {
         (0, validation_1.validateSignalType)(options.signalType, options.data);

package/dist/decision.d.ts

@@ -30,6 +30,7 @@ export declare class DecisionSession {
             uri: string;
             name?: string;
         }[];
+        maxSuspendMs?: number;
         sender?: string;
     }): Promise<Ack>;
     propose(input: DecisionProposalPayload & {

package/dist/decision.js

@@ -40,6 +40,7 @@ class DecisionSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
+            maxSuspendMs: input.maxSuspendMs,
             modeVersion: this.modeVersion,
             configurationVersion: this.configurationVersion,
         });
@@ -47,6 +48,7 @@ class DecisionSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
+            maxSuspendMs: input.maxSuspendMs,
             contextId: input.contextId,
             extensions: input.extensions,
             roots: input.roots,