macp-sdk-typescript 0.4.1 → 0.5.0

package/dist/envelope.d.ts

@@ -7,6 +7,12 @@ export declare function buildSessionStartPayload(input: {
     intent: string;
     participants: string[];
     ttlMs: number;
+    /**
+     * Per-session max-suspend cap in ms (proto ≥ 0.1.5). `0`/absent selects the
+     * runtime default (7 days). Emitted as `0` when omitted, matching `ttlMs`'s
+     * "0 = default" convention.
+     */
+    maxSuspendMs?: number;
     modeVersion?: string;
     configurationVersion?: string;
     policyVersion?: string;
@@ -24,6 +30,20 @@ export declare function buildCommitmentRef(input: {
     sessionId: string;
     commitmentHash: string;
 }): CommitmentRef;
+/**
+ * Build a `CommitmentPayload`. Defaults `policyVersion` to
+ * {@link DEFAULT_POLICY_VERSION} (`'policy.default'`) when omitted.
+ *
+ * Policy-version echo (runtime ≥ 0.5.0): a Commitment with an **empty**
+ * `policyVersion` matches the session's bound policy — a session started with an
+ * empty policy_version no longer has to echo `'policy.default'`. A **non-empty**
+ * value must equal the session's resolved policy id exactly. The mode session
+ * helpers (`DecisionSession.commit`, etc.) echo the session-bound value, which
+ * is correct against both old and new runtimes; this standalone builder keeps
+ * the `'policy.default'` default for backward compatibility (older runtimes
+ * rejected an empty echo). Pass `policyVersion: ''` explicitly to opt into the
+ * new empty-matches-bound behavior — `''` is not coalesced by the default.
+ */
 export declare function buildCommitmentPayload(input: {
     action: string;
     authorityScope: string;

package/dist/envelope.js

@@ -36,6 +36,7 @@ function buildSessionStartPayload(input) {
         configurationVersion: input.configurationVersion ?? constants_1.DEFAULT_CONFIGURATION_VERSION,
         policyVersion: input.policyVersion ?? constants_1.DEFAULT_POLICY_VERSION,
         ttlMs: input.ttlMs,
+        maxSuspendMs: input.maxSuspendMs ?? 0,
         contextId: input.contextId ?? '',
         extensions: input.extensions ?? {},
         roots: input.roots ?? [],
@@ -56,6 +57,20 @@ function inferOutcomePositive(action) {
 function buildCommitmentRef(input) {
     return { sessionId: input.sessionId, commitmentHash: input.commitmentHash };
 }
+/**
+ * Build a `CommitmentPayload`. Defaults `policyVersion` to
+ * {@link DEFAULT_POLICY_VERSION} (`'policy.default'`) when omitted.
+ *
+ * Policy-version echo (runtime ≥ 0.5.0): a Commitment with an **empty**
+ * `policyVersion` matches the session's bound policy — a session started with an
+ * empty policy_version no longer has to echo `'policy.default'`. A **non-empty**
+ * value must equal the session's resolved policy id exactly. The mode session
+ * helpers (`DecisionSession.commit`, etc.) echo the session-bound value, which
+ * is correct against both old and new runtimes; this standalone builder keeps
+ * the `'policy.default'` default for backward compatibility (older runtimes
+ * rejected an empty echo). Pass `policyVersion: ''` explicitly to opt into the
+ * new empty-matches-bound behavior — `''` is not coalesced by the default.
+ */
 function buildCommitmentPayload(input) {
     const payload = {
         commitmentId: input.commitmentId ?? newCommitmentId(),

package/dist/errors.d.ts

@@ -3,7 +3,16 @@ export declare class MacpSdkError extends Error {
     constructor(message: string);
 }
 export declare class MacpTransportError extends MacpSdkError {
-    constructor(message: string);
+    /**
+     * gRPC status name (e.g. `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`,
+     * `UNAUTHENTICATED`) when the underlying transport failure carried one.
+     * Lets consumers distinguish, for example, watch-stream consumer lag
+     * (`RESOURCE_EXHAUSTED` → reconnect) from an auth failure (`UNAUTHENTICATED`
+     * → do not reconnect), or a passive-subscribe resume below a compacted base
+     * (`FAILED_PRECONDITION`). Absent for locally-raised transport errors.
+     */
+    readonly code?: string;
+    constructor(message: string, code?: string);
 }
 /**
  * Structured NACK record. Mirrors python-sdk's `AckFailure` dataclass so

package/dist/errors.js

@@ -9,9 +9,19 @@ class MacpSdkError extends Error {
 }
 exports.MacpSdkError = MacpSdkError;
 class MacpTransportError extends MacpSdkError {
-    constructor(message) {
+    /**
+     * gRPC status name (e.g. `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`,
+     * `UNAUTHENTICATED`) when the underlying transport failure carried one.
+     * Lets consumers distinguish, for example, watch-stream consumer lag
+     * (`RESOURCE_EXHAUSTED` → reconnect) from an auth failure (`UNAUTHENTICATED`
+     * → do not reconnect), or a passive-subscribe resume below a compacted base
+     * (`FAILED_PRECONDITION`). Absent for locally-raised transport errors.
+     */
+    code;
+    constructor(message, code) {
         super(message);
         this.name = 'MacpTransportError';
+        this.code = code;
     }
 }
 exports.MacpTransportError = MacpTransportError;

package/dist/handoff.d.ts

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

package/dist/handoff.js

@@ -40,6 +40,7 @@ class HandoffSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
+            maxSuspendMs: input.maxSuspendMs,
             modeVersion: this.modeVersion,
             configurationVersion: this.configurationVersion,
         });
@@ -47,6 +48,7 @@ class HandoffSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
+            maxSuspendMs: input.maxSuspendMs,
             contextId: input.contextId,
             extensions: input.extensions,
             roots: input.roots,
@@ -89,12 +91,18 @@ class HandoffSession {
     }
     async acceptHandoff(input) {
         (0, validation_1.validateRequiredField)('handoffId', input.handoffId);
+        // `implicit` is a runtime-emitted-only flag (RFC-MACP-0010 §5.1); the
+        // runtime rejects client-submitted accepts with implicit=true. Strip it so
+        // a caller can never produce a rejected envelope, regardless of what they
+        // pass — belt and braces with the JSDoc "read-only" contract on the type.
+        const rest = { ...input };
+        delete rest.implicit;
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: constants_1.MODE_HANDOFF,
             messageType: 'HandoffAccept',
             sessionId: this.sessionId,
             sender: this.senderFor(input.sender, input.auth),
-            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_HANDOFF, 'HandoffAccept', (0, envelope_1.toProtoPayload)(input)),
+            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_HANDOFF, 'HandoffAccept', rest),
         });
         return this.sendAndTrack(envelope, input.auth);
     }

package/dist/policy.d.ts

@@ -15,7 +15,18 @@ export interface CommitmentRules {
 }
 export interface VotingRules {
     algorithm?: 'none' | 'majority' | 'supermajority' | 'unanimous' | 'weighted' | 'plurality';
+    /**
+     * Vote-share fraction on a **0–1 scale** (e.g. `0.5` = simple majority). This
+     * is a DIFFERENT field from the quorum `percentage` below — do not confuse
+     * the scales.
+     */
     threshold?: number;
+    /**
+     * Participation quorum. For `type: 'percentage'`, `value` is an **integer
+     * 0–100** (the runtime evaluates it on the same 0–100 scale as the quorum
+     * mode's threshold), NOT a 0–1 fraction. For `type: 'count'`, an absolute
+     * participant count.
+     */
     quorum?: {
         type: 'count' | 'percentage';
         value: number;
@@ -39,6 +50,15 @@ export interface EvaluationRules {
 }
 export interface QuorumThreshold {
     type: 'n_of_m' | 'percentage' | 'weighted';
+    /**
+     * The approval bar (RFC-MACP-0012 §4.2) — how many APPROVE commitments the
+     * request needs, NOT a participation quorum. Scale depends on `type`:
+     * - `n_of_m` / `weighted`: an absolute count (or weight sum).
+     * - `percentage`: an **integer 0–100**; the runtime computes the bar as
+     *   `ceil(value / 100 × participants)`. So `75` means "≥ 75% of participants
+     *   must approve", NOT `0.75`. `buildQuorumPolicy` validates this range and
+     *   throws on a non-integer or out-of-[0,100] value.
+     */
     value: number;
 }
 export interface AbstentionRules {

package/dist/policy.js

@@ -5,6 +5,7 @@ exports.buildQuorumPolicy = buildQuorumPolicy;
 exports.buildProposalPolicy = buildProposalPolicy;
 exports.buildTaskPolicy = buildTaskPolicy;
 exports.buildHandoffPolicy = buildHandoffPolicy;
+const errors_1 = require("./errors");
 // ── Builder helpers ─────────────────────────────────────────────────
 function serializeCommitment(commitment) {
     return {
@@ -49,6 +50,14 @@ function buildDecisionPolicy(policyId, description, rules) {
     };
 }
 function buildQuorumPolicy(policyId, description, rules) {
+    if (rules.threshold?.type === 'percentage') {
+        const v = rules.threshold.value;
+        if (!Number.isInteger(v) || v < 0 || v > 100) {
+            throw new errors_1.MacpSessionError(`quorum percentage threshold must be an integer in [0, 100] (e.g. 75 for 75%), got ${v}. ` +
+                'The runtime computes the approval bar as ceil(value/100 × participants); a fractional value ' +
+                'like 0.75 would round to a ~1% bar.');
+        }
+    }
     const rulesJson = {
         threshold: {
             type: rules.threshold?.type ?? 'n_of_m',

package/dist/projections/handoff.d.ts

@@ -10,6 +10,12 @@ export interface HandoffRecord {
     contextContentType?: string;
     acceptedBy?: string;
     declinedBy?: string;
+    /**
+     * `true` when the accept that resolved this handoff was a runtime-emitted
+     * synthetic implicit accept (RFC-MACP-0010 §5.1, proto ≥ 0.1.6). `false` for
+     * an explicit target accept. Only meaningful once `status === 'accepted'`.
+     */
+    implicit?: boolean;
 }
 export declare class HandoffProjection {
     readonly handoffs: Map<string, HandoffRecord>;
@@ -22,6 +28,12 @@ export declare class HandoffProjection {
     getHandoff(handoffId: string): HandoffRecord | undefined;
     isAccepted(handoffId: string): boolean;
     isDeclined(handoffId: string): boolean;
+    /**
+     * `true` when the handoff was resolved by a runtime-emitted synthetic implicit
+     * accept (RFC-MACP-0010 §5.1) rather than an explicit target accept. Returns
+     * `false` for explicitly-accepted or not-yet-accepted handoffs.
+     */
+    isImplicitlyAccepted(handoffId: string): boolean;
     pendingHandoffs(): HandoffRecord[];
     hasAcceptedOffer(handoffId?: string): boolean;
     activeOffer(): HandoffRecord | undefined;

package/dist/projections/handoff.js

@@ -47,6 +47,10 @@ class HandoffProjection {
                 if (handoff) {
                     handoff.status = 'accepted';
                     handoff.acceptedBy = record.acceptedBy;
+                    // proto3 bool defaults are materialized to `false` on decode
+                    // (proto-registry), so this is always a real boolean once proto 0.1.6
+                    // is loaded — `true` marks a runtime synthetic implicit accept.
+                    handoff.implicit = record.implicit ?? false;
                 }
                 this.phase = 'Accepted';
                 break;
@@ -89,6 +93,15 @@ class HandoffProjection {
     isDeclined(handoffId) {
         return this.handoffs.get(handoffId)?.status === 'declined';
     }
+    /**
+     * `true` when the handoff was resolved by a runtime-emitted synthetic implicit
+     * accept (RFC-MACP-0010 §5.1) rather than an explicit target accept. Returns
+     * `false` for explicitly-accepted or not-yet-accepted handoffs.
+     */
+    isImplicitlyAccepted(handoffId) {
+        const handoff = this.handoffs.get(handoffId);
+        return handoff?.status === 'accepted' && handoff.implicit === true;
+    }
     pendingHandoffs() {
         return [...this.handoffs.values()].filter((h) => h.status === 'offered' || h.status === 'context_sent');
     }

package/dist/proposal.d.ts

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

package/dist/proposal.js

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

package/dist/proto-registry.d.ts

@@ -7,6 +7,16 @@ export declare class ProtoRegistry {
     decodeMessage(typeName: string, payload: Buffer): Record<string, unknown>;
     encodeKnownPayload(mode: string, messageType: string, value: Record<string, unknown>): Buffer;
     decodeKnownPayload(mode: string, messageType: string, payload: Buffer): Record<string, unknown> | undefined;
+    /**
+     * Decode an `ext.multi_round.v1` `Contribute` payload, accepting both wire
+     * formats: legacy JSON (`{"value":"..."}`, still replayed verbatim from
+     * pre-proto histories) and canonical protobuf (`ContributePayload`). JSON is
+     * tried first — mirroring the runtime's permanent decode order — and the two
+     * encodings are disjoint on their first byte (`{` = 0x7b vs proto field-1
+     * tag 0x0A), so a canonical proto payload never mis-parses as JSON and vice
+     * versa. Both normalize to `{ value: string }`.
+     */
+    private decodeMultiRoundContribute;
     private lookupType;
     private tryDecodeUtf8;
 }

package/dist/proto-registry.js

@@ -46,6 +46,9 @@ const CORE_MAP = {
     Signal: 'macp.v1.SignalPayload',
     Progress: 'macp.v1.ProgressPayload',
 };
+// The one mapping whose historical payloads may be legacy JSON. Runtime replays
+// pre-proto histories byte-identically, so decode must accept both encodings.
+const MULTI_ROUND_CONTRIBUTE = 'macp.modes.multi_round.v1.ContributePayload';
 const MODE_MAP = {
     [constants_1.MODE_DECISION]: {
         Proposal: 'macp.modes.decision.v1.ProposalPayload',
@@ -81,7 +84,10 @@ const MODE_MAP = {
         Abstain: 'macp.modes.quorum.v1.AbstainPayload',
     },
     [constants_1.MODE_MULTI_ROUND]: {
-        Contribute: '__json__',
+        // Canonical protobuf as of proto 0.1.4 / runtime 0.5.0. Encode is always
+        // protobuf; decode tries legacy JSON (`{"value":"..."}`) first, then
+        // protobuf — see `MULTI_ROUND_CONTRIBUTE` handling in decodeKnownPayload.
+        Contribute: MULTI_ROUND_CONTRIBUTE,
     },
 };
 const PROTO_FILES = [
@@ -93,6 +99,7 @@ const PROTO_FILES = [
     'macp/modes/task/v1/task.proto',
     'macp/modes/handoff/v1/handoff.proto',
     'macp/modes/quorum/v1/quorum.proto',
+    'macp/modes/multi_round/v1/multi_round.proto',
 ];
 class ProtoRegistry {
     protoDir;
@@ -155,8 +162,34 @@ class ProtoRegistry {
             return this.tryDecodeUtf8(payload);
         if (typeName === '__json__')
             return this.tryDecodeUtf8(payload);
+        if (typeName === MULTI_ROUND_CONTRIBUTE)
+            return this.decodeMultiRoundContribute(payload);
         return this.decodeMessage(typeName, payload);
     }
+    /**
+     * Decode an `ext.multi_round.v1` `Contribute` payload, accepting both wire
+     * formats: legacy JSON (`{"value":"..."}`, still replayed verbatim from
+     * pre-proto histories) and canonical protobuf (`ContributePayload`). JSON is
+     * tried first — mirroring the runtime's permanent decode order — and the two
+     * encodings are disjoint on their first byte (`{` = 0x7b vs proto field-1
+     * tag 0x0A), so a canonical proto payload never mis-parses as JSON and vice
+     * versa. Both normalize to `{ value: string }`.
+     */
+    decodeMultiRoundContribute(payload) {
+        if (!payload.length)
+            return this.decodeMessage(MULTI_ROUND_CONTRIBUTE, payload);
+        if (payload[0] === 0x7b) {
+            // Leading `{` — legacy JSON. Parse and normalize to { value }.
+            try {
+                const parsed = JSON.parse(payload.toString('utf8'));
+                return { value: typeof parsed.value === 'string' ? parsed.value : String(parsed.value ?? '') };
+            }
+            catch {
+                // Not valid JSON despite the leading brace — fall through to protobuf.
+            }
+        }
+        return this.decodeMessage(MULTI_ROUND_CONTRIBUTE, payload);
+    }
     lookupType(typeName) {
         const lookedUp = this.root.lookupType(typeName);
         if (!(lookedUp instanceof protobufjs_1.default.Type))

package/dist/quorum.d.ts

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

package/dist/quorum.js

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

package/dist/retry.d.ts

@@ -5,6 +5,13 @@ export interface RetryPolicy {
     maxRetries: number;
     backoffBase: number;
     backoffMax: number;
+    /**
+     * Retryable **ack** (NACK) codes — MACP application-level error codes on a
+     * `Send` response (e.g. `RATE_LIMITED`, `INTERNAL_ERROR`). This is distinct
+     * from a gRPC **stream** status such as `RESOURCE_EXHAUSTED` (watch-stream
+     * consumer lag), which is not an ack code and is not handled here — reconnect
+     * the stream instead (see the watcher classes' reconnect JSDoc).
+     */
     retryableCodes: Set<string>;
 }
 export declare const DEFAULT_RETRY_POLICY: RetryPolicy;

package/dist/task.d.ts

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

package/dist/task.js

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

package/dist/types.d.ts

@@ -106,6 +106,15 @@ export interface SessionStartPayload {
     configurationVersion: string;
     policyVersion?: string;
     ttlMs: number;
+    /**
+     * Maximum cumulative suspended duration (ms) before a SUSPENDED session
+     * transitions to EXPIRED (RFC-MACP-0001 §7.5, proto ≥ 0.1.5). Bound at
+     * session start like {@link ttlMs}: `0` (or absent) selects the runtime's
+     * configured default (7 days). The runtime records the resolved cap so
+     * replay is deterministic. Negative values are rejected at SessionStart.
+     * Decoded as a string (int64) but accepted as `number` on input.
+     */
+    maxSuspendMs?: number | string;
     contextId?: string;
     extensions?: Record<string, Buffer>;
     roots?: Root[];
@@ -251,6 +260,15 @@ export interface HandoffAcceptPayload {
     handoffId: string;
     acceptedBy: string;
     reason?: string;
+    /**
+     * Runtime-emitted synthetic accepts ONLY (RFC-MACP-0010 §5.1): `true` on the
+     * accept the runtime produces when a handoff's `implicit_accept_timeout_ms`
+     * elapses (`message_id` = `implicit-accept:<handoff_id>`, proto ≥ 0.1.6).
+     * Read-only — clients MUST NOT submit an accept with `implicit = true`; the
+     * runtime rejects it. `HandoffSession.acceptHandoff` strips this field before
+     * encoding so a caller can never produce a rejected envelope.
+     */
+    implicit?: boolean;
 }
 export interface HandoffDeclinePayload {
     handoffId: string;

package/dist/validation.d.ts

@@ -6,12 +6,14 @@ export declare function validateSeverity(value: string): string;
 export declare function validateParticipantCount(count: number): void;
 export declare function validateSignalType(signalType: string, data?: Buffer | Uint8Array): void;
 export declare function validateTtlMs(ttlMs: number): void;
+export declare function validateMaxSuspendMs(maxSuspendMs: number): void;
 export declare function validateParticipants(participants: string[]): void;
 export declare function validateRequiredField(fieldName: string, value: string): void;
 export declare function validateSessionStart(input: {
     intent: string;
     participants: string[];
     ttlMs: number;
+    maxSuspendMs?: number;
     modeVersion: string;
     configurationVersion: string;
 }): void;

package/dist/validation.js

@@ -8,6 +8,7 @@ exports.validateSeverity = validateSeverity;
 exports.validateParticipantCount = validateParticipantCount;
 exports.validateSignalType = validateSignalType;
 exports.validateTtlMs = validateTtlMs;
+exports.validateMaxSuspendMs = validateMaxSuspendMs;
 exports.validateParticipants = validateParticipants;
 exports.validateRequiredField = validateRequiredField;
 exports.validateSessionStart = validateSessionStart;
@@ -65,6 +66,13 @@ function validateTtlMs(ttlMs) {
         throw new errors_1.MacpSessionError(`ttl_ms must be in [1, ${MAX_TTL_MS}], got ${ttlMs}`);
     }
 }
+function validateMaxSuspendMs(maxSuspendMs) {
+    // 0 = "use runtime default"; only negatives are rejected (matches the
+    // runtime, which rejects negative max_suspend_ms at SessionStart).
+    if (!Number.isFinite(maxSuspendMs) || maxSuspendMs < 0) {
+        throw new errors_1.MacpSessionError(`max_suspend_ms must be >= 0 (0 = runtime default), got ${maxSuspendMs}`);
+    }
+}
 function validateParticipants(participants) {
     if (!participants.length) {
         throw new errors_1.MacpSessionError('participants must be non-empty');
@@ -87,6 +95,8 @@ function validateSessionStart(input) {
     validateRequiredField('intent', input.intent);
     validateParticipants(input.participants);
     validateTtlMs(input.ttlMs);
+    if (input.maxSuspendMs !== undefined)
+        validateMaxSuspendMs(input.maxSuspendMs);
     validateRequiredField('modeVersion', input.modeVersion);
     validateRequiredField('configurationVersion', input.configurationVersion);
 }

package/dist/watchers.d.ts

@@ -1,5 +1,5 @@
 import type { AuthConfig } from './auth';
-import type { MacpClient } from './client';
+import { type MacpClient } from './client';
 import type { Envelope, PolicyDescriptor, RegistryChanged, RootsChanged, SessionLifecycleEvent, SessionLifecycleEventType } from './types';
 /**
  * The lifecycle event types after which a session emits no further events.
@@ -43,6 +43,16 @@ export declare class RootsWatcher {
     watch(handler: (change: RootsChanged) => void | Promise<void>): Promise<void>;
     nextChange(): Promise<RootsChanged>;
 }
+/**
+ * Watches the ambient signal plane. **Requires auth** as of runtime 0.5.0: if
+ * no credential is configured on the watcher or the client, iterating
+ * {@link SignalWatcher.signals} throws immediately (via `client.watchSignals`).
+ *
+ * Consumer lag terminates the stream with a coded `MacpTransportError`
+ * (`code === 'RESOURCE_EXHAUSTED'`); the correct response is to reconnect.
+ * A missing/invalid credential surfaces as `code === 'UNAUTHENTICATED'` — fix
+ * auth, do not reconnect.
+ */
 export declare class SignalWatcher {
     private readonly client;
     private readonly auth?;
@@ -67,26 +77,20 @@ export declare class PolicyWatcher {
     watch(handler: (change: PolicyChange) => void | Promise<void>): Promise<void>;
     nextChange(): Promise<PolicyChange>;
 }
+/**
+ * Watches session lifecycle events (`WatchSessions`). Consumer lag terminates
+ * the stream with a coded `MacpTransportError` (`code === 'RESOURCE_EXHAUSTED'`);
+ * the correct response is to reconnect and re-sync current state via
+ * {@link MacpClient.listSessions}, since events emitted during the gap are lost.
+ */
 export declare class SessionLifecycleWatcher {
     private readonly client;
     private readonly auth?;
-    private deprecatedEventsWarned;
-    private deprecatedNextEventWarned;
     constructor(client: MacpClient, options?: {
         auth?: AuthConfig;
     });
     changes(signal?: AbortSignal): AsyncGenerator<SessionLifecycleEvent, void, void>;
     watch(handler: (event: SessionLifecycleEvent) => void | Promise<void>): Promise<void>;
     nextChange(): Promise<SessionLifecycleEvent>;
-    /**
-     * @deprecated Use {@link changes} — renamed for parity with python-sdk's
-     * `SessionLifecycleWatcher.changes()` and the uniform `changes()` name
-     * used by all other watchers in both SDKs. Will be removed in 0.5.0.
-     */
-    events(signal?: AbortSignal): AsyncGenerator<SessionLifecycleEvent, void, void>;
-    /**
-     * @deprecated Use {@link nextChange}. Will be removed in 0.5.0.
-     */
-    nextEvent(): Promise<SessionLifecycleEvent>;
 }
 export {};

package/dist/watchers.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SessionLifecycleWatcher = exports.PolicyWatcher = exports.SignalWatcher = exports.RootsWatcher = exports.ModeRegistryWatcher = exports.isTerminalSessionLifecycleEvent = exports.isSessionResumed = exports.isSessionSuspended = exports.isSessionCancelled = exports.isSessionExpired = exports.isSessionResolved = exports.isSessionCreated = exports.TERMINAL_SESSION_LIFECYCLE_EVENT_TYPES = void 0;
-const logging_1 = require("./logging");
+const client_1 = require("./client");
+const errors_1 = require("./errors");
 /**
  * The lifecycle event types after which a session emits no further events.
  * `EVENT_TYPE_CANCELLED` (proto 0.1.3) is terminal alongside `RESOLVED` and
@@ -48,7 +49,14 @@ function serverStreamToAsyncGenerator(stream) {
         }
     });
     stream.on('error', (error) => {
-        queue.push({ error });
+        // Wrap the raw gRPC ServiceError into a coded MacpTransportError so
+        // consumers can branch on `.code`: consumer lag terminates a watch stream
+        // with RESOURCE_EXHAUSTED (reconnect + re-sync), an unauthenticated
+        // WatchSignals with UNAUTHENTICATED (fix auth, do NOT reconnect).
+        const code = (0, client_1.grpcStatusName)(error.code);
+        const serviceErr = error;
+        const wrapped = new errors_1.MacpTransportError(serviceErr.details || error.message, code);
+        queue.push({ error: wrapped });
         if (resolve) {
             resolve();
             resolve = null;
@@ -148,6 +156,16 @@ class RootsWatcher {
     }
 }
 exports.RootsWatcher = RootsWatcher;
+/**
+ * Watches the ambient signal plane. **Requires auth** as of runtime 0.5.0: if
+ * no credential is configured on the watcher or the client, iterating
+ * {@link SignalWatcher.signals} throws immediately (via `client.watchSignals`).
+ *
+ * Consumer lag terminates the stream with a coded `MacpTransportError`
+ * (`code === 'RESOURCE_EXHAUSTED'`); the correct response is to reconnect.
+ * A missing/invalid credential surfaces as `code === 'UNAUTHENTICATED'` — fix
+ * auth, do not reconnect.
+ */
 class SignalWatcher {
     client;
     auth;
@@ -210,11 +228,15 @@ class PolicyWatcher {
     }
 }
 exports.PolicyWatcher = PolicyWatcher;
+/**
+ * Watches session lifecycle events (`WatchSessions`). Consumer lag terminates
+ * the stream with a coded `MacpTransportError` (`code === 'RESOURCE_EXHAUSTED'`);
+ * the correct response is to reconnect and re-sync current state via
+ * {@link MacpClient.listSessions}, since events emitted during the gap are lost.
+ */
 class SessionLifecycleWatcher {
     client;
     auth;
-    deprecatedEventsWarned = false;
-    deprecatedNextEventWarned = false;
     constructor(client, options) {
         this.client = client;
         this.auth = options?.auth;
@@ -243,27 +265,5 @@ class SessionLifecycleWatcher {
             throw new Error('stream ended before receiving a session lifecycle event');
         return result.value;
     }
-    /**
-     * @deprecated Use {@link changes} — renamed for parity with python-sdk's
-     * `SessionLifecycleWatcher.changes()` and the uniform `changes()` name
-     * used by all other watchers in both SDKs. Will be removed in 0.5.0.
-     */
-    async *events(signal) {
-        if (!this.deprecatedEventsWarned) {
-            this.deprecatedEventsWarned = true;
-            logging_1.logger.warn('[deprecated] SessionLifecycleWatcher.events() — use changes() instead');
-        }
-        yield* this.changes(signal);
-    }
-    /**
-     * @deprecated Use {@link nextChange}. Will be removed in 0.5.0.
-     */
-    async nextEvent() {
-        if (!this.deprecatedNextEventWarned) {
-            this.deprecatedNextEventWarned = true;
-            logging_1.logger.warn('[deprecated] SessionLifecycleWatcher.nextEvent() — use nextChange() instead');
-        }
-        return this.nextChange();
-    }
 }
 exports.SessionLifecycleWatcher = SessionLifecycleWatcher;