macp-sdk-typescript 0.10.0 → 0.12.0

package/dist/agent/participant.js

@@ -29,7 +29,23 @@ class Participant {
     modeVersion;
     configurationVersion;
     policyVersion;
+    /** Whether the event loop is currently inside {@link run}. */
     running = false;
+    /**
+     * Latching: set once a terminal result is dispatched (a terminal phase,
+     * or the {@code SessionCancel} fallback in {@link processMessage}). A
+     * terminal `Participant` is single-use — {@link run} refuses to
+     * re-enter, because the projection is resolved and the runtime will
+     * accept nothing further for this session.
+     */
+    terminal = false;
+    /**
+     * The cooperative cancel flag {@link stop} sets and {@link run} clears
+     * on entry — the loop's break predicate. Distinct from {@link terminal}:
+     * a `stop()`-exited, non-terminal `Participant` is a resumable pause
+     * (see {@link isStopped}), not single-use.
+     */
+    stopRequested = false;
     lastPhase;
     cancelCallbackServer;
     cancelCallbackConfig;
@@ -170,13 +186,19 @@ class Participant {
         this.dispatcher.onTerminal(handler);
         return this;
     }
-    /** Whether {@link stop} has been called (or the loop has exited). */
+    /**
+     * `true` after a terminal outcome (single-use from here on), or while a
+     * `stop()` request is pending/has taken effect on a `Participant` whose
+     * loop has not (yet) been resumed by a later {@link run}. A `stop()`
+     * exit is resumable — see {@link run} and {@link terminal}'s own doc.
+     */
     get isStopped() {
-        return !this.running;
+        return this.terminal || this.stopRequested;
     }
     async run() {
-        if (this.running)
+        if (this.running || this.terminal)
             return;
+        this.stopRequested = false;
         this.running = true;
         if (this.cancelCallbackConfig && !this.cancelCallbackServer) {
             this.cancelCallbackServer = await (0, cancel_callback_1.startCancelCallbackServer)({
@@ -193,7 +215,7 @@ class Participant {
         }
         try {
             for await (const message of this.transport.start()) {
-                if (!this.running)
+                if (this.stopRequested)
                     break;
                 const reachedTerminal = await this.processMessage(message);
                 if (reachedTerminal)
@@ -202,6 +224,7 @@ class Participant {
         }
         finally {
             this.running = false;
+            await this.teardown();
         }
     }
     /**
@@ -244,6 +267,7 @@ class Participant {
     /** Returns true if a terminal state was reached. */
     async processMessage(message) {
         const ctx = this.buildHandlerContext();
+        const alreadyTerminal = this.terminal;
         if (this.session && message.raw) {
             const applyMethod = this.session.projection
                 .applyEnvelope;
@@ -252,24 +276,64 @@ class Participant {
             }
         }
         await this.dispatcher.dispatch(message, ctx);
+        let firedTerminal = false;
         const currentPhase = this.projection.phase;
         if (currentPhase !== this.lastPhase) {
             this.lastPhase = currentPhase;
             await this.dispatcher.dispatchPhaseChange(currentPhase, ctx);
             if (TERMINAL_PHASES.has(currentPhase)) {
+                this.terminal = true;
+                firedTerminal = true;
                 const terminalResult = {
                     state: currentPhase,
                     commitment: this.projection.commitment,
                 };
                 await this.dispatcher.dispatchTerminal(terminalResult);
-                return true;
             }
         }
-        return false;
+        // Fallback for envelopes no projection maps to a phase (issue #106.1):
+        // no built-in projection maps `SessionCancel` to a terminal phase, so the
+        // phase-driven path above never fires for it. Against the current
+        // macp-runtime, `run()`'s streamed path never even observes this branch —
+        // `cancel_session` stores `SessionCancel` as `EntryKind::Internal`
+        // (runtime.rs `make_internal_entry`/`cancel_session`), and
+        // `get_incoming_after` (macp-storage `log_store.rs`) filters strictly to
+        // `EntryKind::Incoming`, so `StreamSession`/`GrpcTransportAdapter` never
+        // delivers it; cancellation surfaces via the separate
+        // `session_lifecycle_bus`/`WatchSessions` mechanism instead. This
+        // fallback's real, currently-reachable value is `processEvent()` callers
+        // driving their own foreign message loop (where a `SessionCancel` can be
+        // handed in directly) and cross-SDK parity with `macp-sdk-python`'s
+        // identical fallback — not the streamed `run()` path today. Gated on
+        // `!alreadyTerminal` (captured before this call's own phase-driven
+        // branch could have just set it) so a `SessionCancel` arriving on an
+        // already-terminal session — one whose own terminal dispatch already
+        // ran, this call or an earlier one — cannot double-dispatch
+        // `onTerminal`.
+        if (!firedTerminal && !alreadyTerminal && message.messageType === 'SessionCancel') {
+            this.terminal = true;
+            this.lastPhase = 'Cancelled';
+            await this.dispatcher.dispatchTerminal({ state: 'Cancelled' });
+            return true;
+        }
+        return firedTerminal;
     }
-    async stop() {
-        this.running = false;
-        await this.transport.stop();
+    /**
+     * Idempotent teardown of everything {@link run} started: the transport
+     * subscription and the cancel-callback HTTP listener, if any. Called
+     * from both {@link stop} and every exit from {@link run}'s loop (issue
+     * #106.2) — a normal terminal exit or a transport running out of
+     * messages used to leak both. A rejecting `transport.stop()` is caught
+     * rather than propagated, so a transport fault on teardown cannot mask
+     * a clean session outcome as a thrown error from {@link run}.
+     */
+    async teardown() {
+        try {
+            await this.transport.stop();
+        }
+        catch (err) {
+            logging_1.logger.debug('transport stop failed', err);
+        }
         if (this.cancelCallbackServer) {
             const srv = this.cancelCallbackServer;
             this.cancelCallbackServer = undefined;
@@ -281,9 +345,23 @@ class Participant {
             }
         }
     }
+    /**
+     * Request that {@link run}'s loop stop. This SDK's {@link TransportAdapter}
+     * has no `cancel()` — `stop()` on the transport is the only thing that can
+     * wake a loop suspended awaiting the next envelope, so teardown (including
+     * the transport) runs here unconditionally, not just the flag. Safe to
+     * call whether or not `run()` is currently active; does not itself flip
+     * {@link running} — only `run()`'s own loop exit does that, since it is
+     * the only place that actually knows the loop has left.
+     */
+    async stop() {
+        this.stopRequested = true;
+        await this.teardown();
+    }
     /**
      * Attach a running cancel-callback HTTP server to this participant.
-     * The server is closed automatically when {@link stop} is called.
+     * The server is closed automatically on any exit from {@link run} — see
+     * {@link teardown}.
      * Parity with python-sdk's `Participant.attach_cancel_callback_server`.
      */
     attachCancelCallbackServer(server) {

package/dist/agent/strategies.js

@@ -9,15 +9,23 @@ exports.commitmentHandler = commitmentHandler;
 exports.functionCommitter = functionCommitter;
 exports.majorityCommitter = majorityCommitter;
 const envelope_1 = require("../envelope");
+const validation_1 = require("../validation");
 function evaluationHandler(strategy) {
     return async (event, ctx) => {
         if (event.messageType !== 'Proposal')
             return;
         const result = await strategy.evaluate(event.payload, ctx.session);
+        // Issue #108.7/4g: validate the strategy's own output — reusing this
+        // repo's own validators (they throw MacpSessionError, the documented
+        // error contract) rather than porting Python's inline ValueError checks
+        // — and dispatch the normalized value, so a bad strategy fails loudly at
+        // the handler naming the strategy, not later from the session.
+        const recommendation = (0, validation_1.validateRecommendation)(result.recommendation);
+        (0, validation_1.validateConfidence)(result.confidence);
         if (ctx.actions.evaluate) {
             await ctx.actions.evaluate({
                 proposalId: event.proposalId ?? event.payload.proposalId ?? event.payload.proposal_id,
-                recommendation: result.recommendation,
+                recommendation,
                 confidence: result.confidence,
                 reason: result.reason,
             });
@@ -35,11 +43,12 @@ function votingHandler(strategy) {
         if (!strategy.shouldVote(projection))
             return;
         const result = await strategy.decideVote(projection);
+        const vote = (0, validation_1.validateVote)(result.vote);
         if (ctx.actions.vote) {
             const proposalId = event.proposalId ?? event.payload.proposalId ?? event.payload.proposal_id;
             await ctx.actions.vote({
                 proposalId,
-                vote: result.vote,
+                vote,
                 reason: result.reason,
             });
         }
@@ -52,17 +61,24 @@ function majorityVoter(options) {
     const threshold = options?.positiveThreshold ?? 0.5;
     return {
         shouldVote(projection) {
-            return projection.evaluations.length > 0;
+            // RFC-MACP-0007 §4 (`rfcs/RFC-MACP-0007-decision-mode.md:73`): REVIEW
+            // evaluations "do not block or approve a proposal; they serve as
+            // informational analysis records only." A set of only REVIEWs has no
+            // decisive evaluation to vote on -- mirroring RFC-MACP-0012:137's
+            // denominator rule ("the denominator is the decisive votes ...
+            // Abstentions are excluded") for votes (issue #124 item 2).
+            return projection.evaluations.some((e) => e.recommendation.toLowerCase() !== 'review');
         },
         async decideVote(projection) {
-            const positive = projection.evaluations.filter((e) => ['approve', 'accept', 'yes'].includes(e.recommendation.toLowerCase()));
-            const ratio = projection.evaluations.length > 0 ? positive.length / projection.evaluations.length : 0;
+            const decisive = projection.evaluations.filter((e) => e.recommendation.toLowerCase() !== 'review');
+            const positive = decisive.filter((e) => ['approve', 'accept', 'yes'].includes(e.recommendation.toLowerCase()));
+            const ratio = decisive.length > 0 ? positive.length / decisive.length : 0;
             if (ratio >= threshold) {
-                return { vote: 'APPROVE', reason: `${positive.length}/${projection.evaluations.length} evaluations positive` };
+                return { vote: 'APPROVE', reason: `${positive.length}/${decisive.length} evaluations positive` };
             }
             return {
                 vote: 'REJECT',
-                reason: `Only ${positive.length}/${projection.evaluations.length} evaluations positive`,
+                reason: `Only ${positive.length}/${decisive.length} evaluations positive`,
             };
         },
     };

package/dist/agent/transports.d.ts

@@ -5,6 +5,23 @@ export interface TransportAdapter {
     start(): AsyncIterable<IncomingMessage>;
     stop(): Promise<void>;
 }
+/**
+ * Bounded retry policy for the startup subscribe race (issue #100, ported
+ * from macp-sdk-python#75): the runtime replies `NOT_FOUND` to `StreamSession`/`sendSubscribe` when a
+ * sibling participant hasn't finished the initiator's SessionStart yet, so
+ * the session doesn't exist *yet* rather than not existing at all. Distinct
+ * from `src/retry.ts`'s `RetryPolicy`, which is scoped to retryable **ack**
+ * (NACK) codes on `Send` — this policy is a gRPC **stream**-open retry and
+ * has no `retryableCodes` set: the one retryable condition (transient
+ * `NOT_FOUND` before any envelope has been delivered) is hardcoded in
+ * `GrpcTransportAdapter.start()`, not configurable per-code.
+ */
+export interface SubscribeRetryPolicy {
+    maxRetries: number;
+    backoffBase: number;
+    backoffMax: number;
+}
+export declare const DEFAULT_SUBSCRIBE_RETRY_POLICY: SubscribeRetryPolicy;
 export declare class GrpcTransportAdapter implements TransportAdapter {
     private readonly client;
     private readonly sessionId;
@@ -12,6 +29,7 @@ export declare class GrpcTransportAdapter implements TransportAdapter {
     private stream;
     private seq;
     private delivered;
+    private readonly subscribeRetryPolicy;
     /**
      * `message_id`s already counted into `delivered`, so the resume cursor
      * advances once per distinct accepted envelope rather than once per raw
@@ -28,7 +46,7 @@ export declare class GrpcTransportAdapter implements TransportAdapter {
      * TTL-bounded by protocol.
      */
     private readonly seenMessageIds;
-    constructor(client: MacpClient, sessionId: string, auth?: AuthConfig | undefined);
+    constructor(client: MacpClient, sessionId: string, auth?: AuthConfig | undefined, subscribeRetryPolicy?: Partial<SubscribeRetryPolicy>);
     /**
      * The server passive-subscribe ordinal of the last delivered envelope (the
      * 1-based count of *distinct* accepted envelopes delivered on this stream,

package/dist/agent/transports.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HttpTransportAdapter = exports.GrpcTransportAdapter = void 0;
+exports.HttpTransportAdapter = exports.GrpcTransportAdapter = exports.DEFAULT_SUBSCRIBE_RETRY_POLICY = void 0;
+const errors_1 = require("../errors");
 function normalizeEnvelope(envelope, decodePayload, seq) {
     const payload = decodePayload(envelope.mode, envelope.messageType, envelope.payload) ?? {};
     return {
@@ -12,6 +13,14 @@ function normalizeEnvelope(envelope, decodePayload, seq) {
         seq,
     };
 }
+exports.DEFAULT_SUBSCRIBE_RETRY_POLICY = {
+    maxRetries: 4,
+    backoffBase: 0.1,
+    backoffMax: 2.0,
+};
+function sleep(seconds) {
+    return new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+}
 class GrpcTransportAdapter {
     client;
     sessionId;
@@ -19,6 +28,7 @@ class GrpcTransportAdapter {
     stream = null;
     seq = 0;
     delivered = 0;
+    subscribeRetryPolicy;
     /**
      * `message_id`s already counted into `delivered`, so the resume cursor
      * advances once per distinct accepted envelope rather than once per raw
@@ -35,10 +45,11 @@ class GrpcTransportAdapter {
      * TTL-bounded by protocol.
      */
     seenMessageIds = new Set();
-    constructor(client, sessionId, auth) {
+    constructor(client, sessionId, auth, subscribeRetryPolicy) {
         this.client = client;
         this.sessionId = sessionId;
         this.auth = auth;
+        this.subscribeRetryPolicy = { ...exports.DEFAULT_SUBSCRIBE_RETRY_POLICY, ...subscribeRetryPolicy };
     }
     /**
      * The server passive-subscribe ordinal of the last delivered envelope (the
@@ -61,72 +72,103 @@ class GrpcTransportAdapter {
         return this.delivered;
     }
     async *start() {
-        // A prior stream from an earlier start() (without an intervening stop())
-        // must not keep feeding this adapter's counter — two live generators
-        // would both advance `delivered` from two differently-positioned
-        // replays. `MacpStream.close()` is `this.call.end()` (`src/client.ts:223-227`),
-        // a write-side half-close — it does not itself force the server to stop
-        // pushing. It is enough here because macp-runtime's StreamSession loop
-        // reads the resulting end-of-request-stream as `StreamAction::ClientDone`,
-        // whose arm drains any already-buffered envelopes once and then breaks,
-        // ending that stream's response side too
-        // (macp-runtime/src/server.rs:654-666). Close it before opening the new
-        // one so re-entrant start() and stop()-then-start() behave identically.
-        if (this.stream) {
-            this.stream.close();
-            this.stream = null;
-        }
-        this.stream = this.client.openStream({ auth: this.auth });
-        // RFC-MACP-0006 §3.2: subscribe to the session, resuming from this
-        // adapter's own cursor. `this.delivered` is 0 before anything has been
-        // delivered, by construction, and `afterSequence = 0` is normatively
-        // "replay from the session's first accepted envelope" — so the first
-        // subscribe and every later one (e.g. after stop()+start()) are the same
-        // expression. There is no separate first-subscribe/reconnect branch to
-        // keep in sync with the counter.
-        await this.stream.sendSubscribe(this.sessionId, this.delivered);
-        for await (const envelope of this.stream.responses()) {
-            if (envelope.sessionId !== this.sessionId)
-                continue;
-            // Count this envelope into the resume cursor only *after* the
-            // consumer has come back for more, not when it is handed off. `yield`
-            // suspends here until the consumer's `for await` either calls
-            // `.next()` again (it took this envelope and kept iterating — the
-            // code below runs) or closes the iterator via `break`/`return`/throw
-            // (e.g. `Participant.run()` observing `!this.running` and breaking
-            // out of its loop without processing this envelope). In the latter
-            // case `.return()` on this generator resumes at this `yield` as if a
-            // `return` had been written here, so nothing below it runs: the
-            // cursor is never advanced past an envelope the consumer never
-            // actually took past the loop boundary, and the next `start()`
-            // redelivers it instead of silently skipping it. See #66 — counting
-            // before yielding let a stop-mid-stream permanently drop an envelope
-            // once #65 made the resume cursor authoritative.
-            const message = normalizeEnvelope(envelope, (mode, mt, p) => this.client.protoRegistry.decodeKnownPayload(mode, mt, p), this.seq++);
-            yield message;
-            // RFC-MACP-0006 §3.2 Redelivery: a redelivery MUST NOT advance the
-            // resume cursor, and a consumer that accumulates state per envelope
-            // MUST be idempotent w.r.t. `message_id`. An empty/absent messageId
-            // has no identity to dedup on and increments unconditionally — the
-            // same carve-out the projection guard documents at
-            // `src/projections/base.ts:224-227`, so the two dedup sites read the
-            // same way. In practice the `else` below can never run against a
-            // conformant runtime: `validate_envelope_shape` rejects any envelope
-            // with an empty `message_id` as `InvalidEnvelope` before it can be
-            // accepted (`macp-runtime/src/server.rs:118`), and RFC-MACP-0001 §8.2
-            // makes `message_id` the runtime's dedup identity, so no accepted
-            // envelope in any session history can carry one. The branch stays
-            // anyway — it costs nothing and errs toward still counting the
-            // envelope instead of silently dropping it if a non-conformant server
-            // ever sends one.
-            if (envelope.messageId) {
-                if (!this.seenMessageIds.has(envelope.messageId)) {
-                    this.seenMessageIds.add(envelope.messageId);
-                    this.delivered++;
+        // Startup subscribe race (issue #100, ported from macp-sdk-python#75): a
+        // sibling participant may not have observed the initiator's SessionStart
+        // yet, so the runtime's very first reply to sendSubscribe() can be a
+        // transient NOT_FOUND for a session that simply doesn't exist *yet* —
+        // not a real error. `receivedAny` seeds `true` when `this.delivered > 0`
+        // (a prior start() on this same adapter already proved the session
+        // exists), so a stop()+start() reconnect never re-enters the retry
+        // budget it doesn't need. Once any envelope for this session has been
+        // delivered in this call, the session demonstrably exists and a later
+        // NOT_FOUND (e.g. the session expired mid-stream) must propagate
+        // immediately, not retry.
+        let receivedAny = this.delivered > 0;
+        let attempt = 0;
+        while (true) {
+            // A prior stream from an earlier start() (without an intervening stop())
+            // must not keep feeding this adapter's counter — two live generators
+            // would both advance `delivered` from two differently-positioned
+            // replays. `MacpStream.close()` is `this.call.end()` (`src/client.ts:223-227`),
+            // a write-side half-close — it does not itself force the server to stop
+            // pushing. It is enough here because macp-runtime's StreamSession loop
+            // reads the resulting end-of-request-stream as `StreamAction::ClientDone`,
+            // whose arm drains any already-buffered envelopes once and then breaks,
+            // ending that stream's response side too
+            // (macp-runtime/src/server.rs:654-666). Close it before opening the new
+            // one so re-entrant start() and stop()-then-start() (including a
+            // subscribe-retry reconnect) behave identically.
+            if (this.stream) {
+                this.stream.close();
+                this.stream = null;
+            }
+            this.stream = this.client.openStream({ auth: this.auth });
+            // RFC-MACP-0006 §3.2: subscribe to the session, resuming from this
+            // adapter's own cursor. `this.delivered` is 0 before anything has been
+            // delivered, by construction, and `afterSequence = 0` is normatively
+            // "replay from the session's first accepted envelope" — so the first
+            // subscribe and every later one (e.g. after stop()+start(), or a
+            // subscribe retry below) are the same expression. There is no separate
+            // first-subscribe/reconnect branch to keep in sync with the counter.
+            await this.stream.sendSubscribe(this.sessionId, this.delivered);
+            try {
+                for await (const envelope of this.stream.responses()) {
+                    if (envelope.sessionId !== this.sessionId)
+                        continue;
+                    receivedAny = true;
+                    // Count this envelope into the resume cursor only *after* the
+                    // consumer has come back for more, not when it is handed off. `yield`
+                    // suspends here until the consumer's `for await` either calls
+                    // `.next()` again (it took this envelope and kept iterating — the
+                    // code below runs) or closes the iterator via `break`/`return`/throw
+                    // (e.g. `Participant.run()` observing its `stopRequested` flag and
+                    // breaking out of its loop without processing this envelope). In the latter
+                    // case `.return()` on this generator resumes at this `yield` as if a
+                    // `return` had been written here, so nothing below it runs: the
+                    // cursor is never advanced past an envelope the consumer never
+                    // actually took past the loop boundary, and the next `start()`
+                    // redelivers it instead of silently skipping it. See #66 — counting
+                    // before yielding let a stop-mid-stream permanently drop an envelope
+                    // once #65 made the resume cursor authoritative.
+                    const message = normalizeEnvelope(envelope, (mode, mt, p) => this.client.protoRegistry.decodeKnownPayload(mode, mt, p), this.seq++);
+                    yield message;
+                    // RFC-MACP-0006 §3.2 Redelivery: a redelivery MUST NOT advance the
+                    // resume cursor, and a consumer that accumulates state per envelope
+                    // MUST be idempotent w.r.t. `message_id`. An empty/absent messageId
+                    // has no identity to dedup on and increments unconditionally — the
+                    // same carve-out the projection guard documents at
+                    // `src/projections/base.ts:224-227`, so the two dedup sites read the
+                    // same way. In practice the `else` below can never run against a
+                    // conformant runtime: `validate_envelope_shape` rejects any envelope
+                    // with an empty `message_id` as `InvalidEnvelope` before it can be
+                    // accepted (`macp-runtime/src/server.rs:118`), and RFC-MACP-0001 §8.2
+                    // makes `message_id` the runtime's dedup identity, so no accepted
+                    // envelope in any session history can carry one. The branch stays
+                    // anyway — it costs nothing and errs toward still counting the
+                    // envelope instead of silently dropping it if a non-conformant server
+                    // ever sends one.
+                    if (envelope.messageId) {
+                        if (!this.seenMessageIds.has(envelope.messageId)) {
+                            this.seenMessageIds.add(envelope.messageId);
+                            this.delivered++;
+                        }
+                    }
+                    else {
+                        this.delivered++;
+                    }
                 }
+                return;
             }
-            else {
-                this.delivered++;
+            catch (err) {
+                const isTransientNotFound = !receivedAny &&
+                    err instanceof errors_1.MacpTransportError &&
+                    err.code === 'NOT_FOUND' &&
+                    attempt < this.subscribeRetryPolicy.maxRetries;
+                if (!isTransientNotFound)
+                    throw err;
+                attempt++;
+                const delay = Math.min(this.subscribeRetryPolicy.backoffBase * 2 ** (attempt - 1), this.subscribeRetryPolicy.backoffMax);
+                await sleep(delay);
             }
         }
     }

package/dist/auth.d.ts

@@ -29,8 +29,15 @@ export declare const Auth: {
      * 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.
+     * runtime reads it. Sets {@link AuthConfig.expectedSender} to `agentId`
+     * (issue #124): the runtime already refuses a mismatched `sender`
+     * unconditionally for dev credentials (`macp-runtime/src/server.rs:229-231`,
+     * no insecure/dev exemption), so this SDK now enforces the same guarantee
+     * client-side instead of surfacing the runtime's rejection late and
+     * confusingly. A caller that genuinely wants the pre-0.2 permissive
+     * behavior — reusing one credential across multiple senders — should use
+     * `Auth.bearer(token, senderHint)` (the legacy two-arg form) instead, which
+     * never sets `expectedSender`.
      */
     devAgent(agentId: string): AuthConfig;
     /**
@@ -50,8 +57,12 @@ export declare function validateAuth(auth: AuthConfig): void;
 export declare function authSender(auth?: AuthConfig): string | undefined;
 /**
  * Throw {@link MacpIdentityMismatchError} when a caller-supplied `sender`
- * conflicts with `auth.expectedSender`. Silent when either is undefined, so
- * dev credentials and legacy bearer usage retain pre-0.2 behavior.
+ * conflicts with `auth.expectedSender`. Silent when `auth.expectedSender` is
+ * undefined, or when `sender` is undefined or `''` — an empty `sender` is
+ * treated the same as absent, matching `macp-runtime/src/server.rs:229`'s
+ * `!env.sender.is_empty() && ...` guard (issue #124): the runtime always
+ * accepts an empty `sender`, so this client-side guard must too, or it would
+ * reject a payload the runtime would accept.
  */
 export declare function assertSenderMatchesIdentity(auth: AuthConfig | undefined, sender: string | undefined): void;
 export declare function metadataFromAuth(auth: AuthConfig): grpc.Metadata;

package/dist/auth.js

@@ -50,11 +50,18 @@ exports.Auth = {
      * 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.
+     * runtime reads it. Sets {@link AuthConfig.expectedSender} to `agentId`
+     * (issue #124): the runtime already refuses a mismatched `sender`
+     * unconditionally for dev credentials (`macp-runtime/src/server.rs:229-231`,
+     * no insecure/dev exemption), so this SDK now enforces the same guarantee
+     * client-side instead of surfacing the runtime's rejection late and
+     * confusingly. A caller that genuinely wants the pre-0.2 permissive
+     * behavior — reusing one credential across multiple senders — should use
+     * `Auth.bearer(token, senderHint)` (the legacy two-arg form) instead, which
+     * never sets `expectedSender`.
      */
     devAgent(agentId) {
-        return { bearerToken: agentId, senderHint: agentId };
+        return { bearerToken: agentId, senderHint: agentId, expectedSender: agentId };
     },
     /**
      * Production bearer-token credential. Pass `{ expectedSender }` to have the
@@ -82,7 +89,12 @@ exports.Auth = {
 };
 function validateAuth(auth) {
     if (!auth.bearerToken) {
-        throw new Error('bearerToken is required');
+        // MacpSdkError (issue #108.8), not a bare Error: the documented pattern
+        // in both SDKs' docs is `catch (e) { if (e instanceof MacpSdkError) ... }`,
+        // so a plain Error escaped it. MacpSdkError, not MacpSessionError — this
+        // is a client configuration fault, not a session-payload fault. Message
+        // text unchanged so any existing message-matching caller still matches.
+        throw new errors_1.MacpSdkError('bearerToken is required');
     }
 }
 function authSender(auth) {
@@ -92,13 +104,17 @@ function authSender(auth) {
 }
 /**
  * Throw {@link MacpIdentityMismatchError} when a caller-supplied `sender`
- * conflicts with `auth.expectedSender`. Silent when either is undefined, so
- * dev credentials and legacy bearer usage retain pre-0.2 behavior.
+ * conflicts with `auth.expectedSender`. Silent when `auth.expectedSender` is
+ * undefined, or when `sender` is undefined or `''` — an empty `sender` is
+ * treated the same as absent, matching `macp-runtime/src/server.rs:229`'s
+ * `!env.sender.is_empty() && ...` guard (issue #124): the runtime always
+ * accepts an empty `sender`, so this client-side guard must too, or it would
+ * reject a payload the runtime would accept.
  */
 function assertSenderMatchesIdentity(auth, sender) {
     if (!auth?.expectedSender)
         return;
-    if (sender === undefined)
+    if (sender === undefined || sender === '')
         return;
     if (sender !== auth.expectedSender) {
         throw new errors_1.MacpIdentityMismatchError(auth.expectedSender, sender);

package/dist/base-session.js

@@ -57,9 +57,19 @@ 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);
+        // Bring this extension point's validation up to parity with the five
+        // built-in mode sessions (issue #108.4/4d): previously only participant
+        // count + maxSuspendMs were checked, so an ext-mode built on this
+        // documented extension point was the weakest-validated mode — an empty
+        // intent or an out-of-range ttlMs reached the wire unvalidated.
+        (0, validation_1.validateSessionStart)({
+            intent: input.intent,
+            participants: input.participants,
+            ttlMs: input.ttlMs,
+            maxSuspendMs: input.maxSuspendMs,
+            modeVersion: this.modeVersion,
+            configurationVersion: this.configurationVersion,
+        });
         const payload = (0, envelope_1.buildSessionStartPayload)({
             intent: input.intent,
             participants: input.participants,