@naylence/agent-sdk 0.3.12 → 0.3.13

package/dist/browser/index.js

@@ -15277,6 +15277,7 @@
         "./node/admission/direct-admission-client-factory.js",
         "./node/admission/noop-admission-client-factory.js",
         "./node/admission/welcome-service-client-factory.js",
+        "./node/default-connection-retry-policy-factory.js",
         "./node/default-node-identity-policy-factory.js",
         "./node/node-factory.js",
         "./node/node-identity-policy-profile-factory.js",
@@ -15355,6 +15356,7 @@
         "./node/admission/direct-admission-client-factory.js": () => Promise.resolve().then(function () { return directAdmissionClientFactory; }),
         "./node/admission/noop-admission-client-factory.js": () => Promise.resolve().then(function () { return noopAdmissionClientFactory; }),
         "./node/admission/welcome-service-client-factory.js": () => Promise.resolve().then(function () { return welcomeServiceClientFactory; }),
+        "./node/default-connection-retry-policy-factory.js": () => Promise.resolve().then(function () { return defaultConnectionRetryPolicyFactory; }),
         "./node/default-node-identity-policy-factory.js": () => Promise.resolve().then(function () { return defaultNodeIdentityPolicyFactory; }),
         "./node/node-factory.js": () => Promise.resolve().then(function () { return nodeFactory; }),
         "./node/node-identity-policy-profile-factory.js": () => Promise.resolve().then(function () { return nodeIdentityPolicyProfileFactory; }),
@@ -15665,12 +15667,12 @@
     }
 
     // This file is auto-generated during build - do not edit manually
-    // Generated from package.json version: 0.3.15
+    // Generated from package.json version: 0.3.16
     /**
      * The package version, injected at build time.
      * @internal
      */
-    const VERSION$2 = '0.3.15';
+    const VERSION$2 = '0.3.16';
 
     let initialized$1 = false;
     const runtimePlugin = {
@@ -16401,7 +16403,7 @@
      * Provides functionality similar to Python's asyncio TaskSpawner with proper
      * error handling, cancellation, and graceful shutdown capabilities.
      */
-    const logger$1g = getLogger('naylence.fame.util.task_spawner');
+    const logger$1h = getLogger('naylence.fame.util.task_spawner');
     function firstDefined(source, keys) {
         for (const key of keys) {
             if (Object.prototype.hasOwnProperty.call(source, key)) {
@@ -16562,7 +16564,7 @@
             const taskId = `task-${++this._taskCounter}`;
             const taskName = normalizedOptions.name || `unnamed-${taskId}`;
             const timeout = normalizedOptions.timeout ?? this._config.defaultTimeout;
-            logger$1g.debug('starting_background_task', {
+            logger$1h.debug('starting_background_task', {
                 task_name: taskName,
                 task_id: taskId,
             });
@@ -16579,7 +16581,7 @@
             task.promise
                 .then(() => {
                 if (!this._suppressCompletionLogging) {
-                    logger$1g.debug('task_completed_successfully', {
+                    logger$1h.debug('task_completed_successfully', {
                         task_name: taskName,
                         task_id: taskId,
                         duration_ms: Date.now() - task.startTime,
@@ -16633,7 +16635,7 @@
                 error.name === 'AbortError' ||
                 error.message === 'Task cancelled' ||
                 error.message === 'Aborted') {
-                logger$1g.debug('task_cancelled', {
+                logger$1h.debug('task_cancelled', {
                     task_name: taskName,
                     note: 'Task cancelled as requested',
                 });
@@ -16641,7 +16643,7 @@
             }
             // Handle timeout
             if (error instanceof TaskTimeoutError) {
-                logger$1g.warning('task_timed_out', {
+                logger$1h.warning('task_timed_out', {
                     task_name: taskName,
                     error: error.message,
                 });
@@ -16653,7 +16655,7 @@
             // Handle known WebSocket shutdown race condition (similar to Python version)
             if (error.message.includes("await wasn't used with future") ||
                 error.message.includes('WebSocket closed during receive')) {
-                logger$1g.debug('task_shutdown_race_condition_handled', {
+                logger$1h.debug('task_shutdown_race_condition_handled', {
                     task_name: taskName,
                     note: 'Normal WebSocket close timing during shutdown - not an error',
                 });
@@ -16663,7 +16665,7 @@
             if (error.name === 'FameTransportClose' ||
                 error.message.includes('normal closure') ||
                 error.message.includes('Connection closed')) {
-                logger$1g.debug('task_shutdown_completed_normally', {
+                logger$1h.debug('task_shutdown_completed_normally', {
                     task_name: taskName,
                     note: 'Task closed normally during shutdown',
                 });
@@ -16671,7 +16673,7 @@
             }
             // Handle PKCE redirect "errors" as info
             if (error.name === 'OAuth2PkceRedirectInitiatedError') {
-                logger$1g.debug('background_task_redirecting', {
+                logger$1h.debug('background_task_redirecting', {
                     task_name: taskName,
                     note: 'Task interrupted for PKCE redirect',
                 });
@@ -16684,14 +16686,14 @@
             // Log retriable errors as warnings (they'll be retried by upstream logic)
             // Log non-retriable errors as errors (fatal failures)
             if (isRetriableError) {
-                logger$1g.warning('background_task_failed', {
+                logger$1h.warning('background_task_failed', {
                     task_name: taskName,
                     error: error.message,
                     retriable: true,
                 });
             }
             else {
-                logger$1g.error('background_task_failed', {
+                logger$1h.error('background_task_failed', {
                     task_name: taskName,
                     error: error.message,
                     stack: error.stack,
@@ -16710,11 +16712,11 @@
         async shutdownTasks(options = {}) {
             const { gracePeriod, cancelHanging, joinTimeout } = normalizeShutdownOptions(options);
             if (this._tasks.size === 0) {
-                logger$1g.debug('shutdown_tasks_no_tasks_to_shutdown');
+                logger$1h.debug('shutdown_tasks_no_tasks_to_shutdown');
                 return;
             }
             this._suppressCompletionLogging = true;
-            logger$1g.debug('shutting_down_tasks', {
+            logger$1h.debug('shutting_down_tasks', {
                 task_count: this._tasks.size,
                 task_names: Array.from(this._tasks.values()).map((t) => t.name),
                 grace_period_ms: gracePeriod,
@@ -16729,7 +16731,7 @@
             if (cancelHanging) {
                 const stillRunning = tasks.filter((task) => task.getState() === TaskState.RUNNING && !completed.has(task));
                 if (stillRunning.length > 0) {
-                    logger$1g.debug('tasks_did_not_complete_within_grace_period', {
+                    logger$1h.debug('tasks_did_not_complete_within_grace_period', {
                         hanging_count: stillRunning.length,
                     });
                     // Wait for them to finish with individual timeouts
@@ -16739,7 +16741,7 @@
                         }
                         catch (error) {
                             if (error instanceof TaskTimeoutError) {
-                                logger$1g.warning('task_did_not_shutdown', {
+                                logger$1h.warning('task_did_not_shutdown', {
                                     task_name: task.name || task.id,
                                     join_timeout_ms: joinTimeout,
                                 });
@@ -16750,7 +16752,7 @@
                             }
                             else if (!(error instanceof TaskCancelledError)) {
                                 /* istanbul ignore next - unreachable defensive branch */
-                                logger$1g.error('task_raised_during_cancellation', {
+                                logger$1h.error('task_raised_during_cancellation', {
                                     task_name: task.name || task.id,
                                     error: error instanceof Error ? error.message : String(error),
                                 });
@@ -17368,7 +17370,7 @@
      * condition/promise and ensure at most one notifier coroutine exists for a
      * flow at any time.
      */
-    const logger$1f = getLogger('naylence.fame.flow.flow_controller');
+    const logger$1g = getLogger('naylence.fame.flow.flow_controller');
     /**
      * Simple condition variable implementation for TypeScript/Node.js
      * Similar to Python's asyncio.Condition
@@ -17502,7 +17504,7 @@
             const newBalance = Math.max(0, Math.min(this.initialWindow, prev + delta));
             this.credits.set(flowId, newBalance);
             const crossedZero = prev <= 0 && newBalance > 0;
-            logger$1f.debug('flow_controller_add_credits', {
+            logger$1g.debug('flow_controller_add_credits', {
                 flow_id: flowId,
                 delta,
                 prev_balance: prev,
@@ -17522,12 +17524,12 @@
         async acquire(flowId) {
             this.ensureFlow(flowId);
             const condition = this.conditions.get(flowId);
-            logger$1f.debug('flow_controller_acquire_attempt', {
+            logger$1g.debug('flow_controller_acquire_attempt', {
                 flow_id: flowId,
                 current_balance: this.credits.get(flowId),
             });
             while (this.credits.get(flowId) <= 0) {
-                logger$1f.debug('flow_controller_waiting_for_credits', {
+                logger$1g.debug('flow_controller_waiting_for_credits', {
                     flow_id: flowId,
                     current_balance: this.credits.get(flowId),
                 });
@@ -17535,12 +17537,12 @@
             }
             const newBalance = this.credits.get(flowId) - 1;
             this.credits.set(flowId, newBalance);
-            logger$1f.debug('flow_controller_acquire_success', {
+            logger$1g.debug('flow_controller_acquire_success', {
                 flow_id: flowId,
                 new_balance: newBalance,
             });
             if (newBalance <= this.lowWatermark) {
-                logger$1f.debug('flow_controller_acquire_below_low_watermark', {
+                logger$1g.debug('flow_controller_acquire_below_low_watermark', {
                     flow_id: flowId,
                     low_watermark: this.lowWatermark,
                 });
@@ -17564,7 +17566,7 @@
             const current = this.credits.get(flowId);
             const remaining = Math.max(current - credits, 0);
             this.credits.set(flowId, remaining);
-            logger$1f.debug('flow_controller_consume', {
+            logger$1g.debug('flow_controller_consume', {
                 flow_id: flowId,
                 requested: credits,
                 prev_balance: current,
@@ -17590,7 +17592,7 @@
             this.windowIds.delete(flowId);
             this.credits.set(flowId, this.initialWindow);
             this.wakeWaiters(flowId);
-            logger$1f.debug('flow_controller_flow_reset', {
+            logger$1g.debug('flow_controller_flow_reset', {
                 flow_id: flowId,
                 reset_balance: this.initialWindow,
             });
@@ -17971,7 +17973,7 @@
             return new EnvCredentialProvider(resolved.varName);
         }
     }
-    const FACTORY_META$1b = {
+    const FACTORY_META$1c = {
         base: CREDENTIAL_PROVIDER_FACTORY_BASE_TYPE,
         key: 'EnvCredentialProvider',
     };
@@ -17979,7 +17981,7 @@
     var envCredentialProviderFactory = /*#__PURE__*/Object.freeze({
         __proto__: null,
         EnvCredentialProviderFactory: EnvCredentialProviderFactory,
-        FACTORY_META: FACTORY_META$1b,
+        FACTORY_META: FACTORY_META$1c,
         default: EnvCredentialProviderFactory,
         normalizeEnvConfig: normalizeEnvConfig
     });
@@ -18077,14 +18079,14 @@
             return new PromptCredentialProvider(resolved.credentialName);
         }
     }
-    const FACTORY_META$1a = {
+    const FACTORY_META$1b = {
         base: CREDENTIAL_PROVIDER_FACTORY_BASE_TYPE,
         key: 'PromptCredentialProvider',
     };
 
     var promptCredentialProviderFactory = /*#__PURE__*/Object.freeze({
         __proto__: null,
-        FACTORY_META: FACTORY_META$1a,
+        FACTORY_META: FACTORY_META$1b,
         PromptCredentialProviderFactory: PromptCredentialProviderFactory,
         default: PromptCredentialProviderFactory,
         normalizePromptConfig: normalizePromptConfig
@@ -18138,14 +18140,14 @@
             return new SecretStoreCredentialProvider(resolved.secretName);
         }
     }
-    const FACTORY_META$19 = {
+    const FACTORY_META$1a = {
         base: CREDENTIAL_PROVIDER_FACTORY_BASE_TYPE,
         key: 'SecretStoreCredentialProvider',
     };
 
     var secretStoreCredentialProviderFactory = /*#__PURE__*/Object.freeze({
         __proto__: null,
-        FACTORY_META: FACTORY_META$19,
+        FACTORY_META: FACTORY_META$1a,
         SecretStoreCredentialProviderFactory: SecretStoreCredentialProviderFactory,
         default: SecretStoreCredentialProviderFactory,
         normalizeSecretStoreConfig: normalizeSecretStoreConfig
@@ -18194,14 +18196,14 @@
             return new StaticCredentialProvider(resolved.credentialValue);
         }
     }
-    const FACTORY_META$18 = {
+    const FACTORY_META$19 = {
         base: CREDENTIAL_PROVIDER_FACTORY_BASE_TYPE,
         key: 'StaticCredentialProvider',
     };
 
     var staticCredentialProviderFactory = /*#__PURE__*/Object.freeze({
         __proto__: null,
-        FACTORY_META: FACTORY_META$18,
+        FACTORY_META: FACTORY_META$19,
         StaticCredentialProviderFactory: StaticCredentialProviderFactory,
         default: StaticCredentialProviderFactory,
         normalizeStaticConfig: normalizeStaticConfig
@@ -19412,7 +19414,7 @@
         return value;
     }
 
-    const logger$1d = getLogger('naylence.fame.node.binding_manager');
+    const logger$1e = getLogger('naylence.fame.node.binding_manager');
     const SYSTEM_INBOX$3 = '__sys__';
     const DEFAULT_ACK_TIMEOUT_MS = 20000;
     class BindingStoreEntryRecord {
@@ -19498,7 +19500,7 @@
                 if (!this.bindings.has(key)) {
                     const binding = this.bindingFactory(new FameAddress(key));
                     this.bindings.set(key, binding);
-                    logger$1d.debug('restored_binding', { address: key });
+                    logger$1e.debug('restored_binding', { address: key });
                 }
             }
             if (!this.hasUpstream) {
@@ -19508,13 +19510,13 @@
             await this.readvertiseCapabilitiesUpstream();
         }
         async bind(participant, capabilities) {
-            logger$1d.debug('binding_participant', { participant });
+            logger$1e.debug('binding_participant', { participant });
             const { prefixAddress, addresses, propagateAddress, capabilityAddress } = this.computeBindingAddresses(participant);
             for (const address of addresses) {
                 if (!this.bindings.has(address)) {
                     const binding = this.bindingFactory(new FameAddress(address));
                     this.bindings.set(address, binding);
-                    logger$1d.debug('bound_address', { address, participant });
+                    logger$1e.debug('bound_address', { address, participant });
                 }
             }
             let propagatedAddress = null;
@@ -19543,7 +19545,7 @@
                             await this.unbindAddressUpstream(propagatedAddress);
                         }
                         catch (rollbackError) {
-                            logger$1d.error('bind_rollback_failed', {
+                            logger$1e.error('bind_rollback_failed', {
                                 address: propagatedAddress.toString(),
                                 error: rollbackError.message,
                             });
@@ -19562,7 +19564,7 @@
                     physicalPath: null,
                 });
             }
-            logger$1d.debug('bind_success', {
+            logger$1e.debug('bind_success', {
                 participant,
                 address: prefixAddress.toString(),
                 capabilities,
@@ -19598,7 +19600,7 @@
                     await this.bindingStore.delete(address);
                 }
             }
-            logger$1d.debug('unbind_success', {
+            logger$1e.debug('unbind_success', {
                 participant,
                 address: prefixAddress.toString(),
                 totalBindings: this.bindings.size,
@@ -19628,7 +19630,7 @@
                     await this.bindAddressUpstream(new FameAddress(address));
                 }
                 catch (error) {
-                    logger$1d.error('rebind_failed', {
+                    logger$1e.error('rebind_failed', {
                         address,
                         error: error.message,
                     });
@@ -19647,7 +19649,7 @@
                     await this.advertiseCapabilities(new FameAddress(address), Array.from(capabilities));
                 }
                 catch (error) {
-                    logger$1d.error('capability_replay_failed', {
+                    logger$1e.error('capability_replay_failed', {
                         address,
                         error: error.message,
                     });
@@ -19914,7 +19916,7 @@
         }
     }
 
-    const logger$1c = getLogger('naylence.fame.node.response_context_manager');
+    const logger$1d = getLogger('naylence.fame.node.response_context_manager');
     function cloneSecurityContext(source) {
         if (!source) {
             return undefined;
@@ -19942,7 +19944,7 @@
                 security: responseSecurity,
                 expectedResponseType: FameResponseType.NONE,
             };
-            logger$1c.debug('created_response_context', {
+            logger$1d.debug('created_response_context', {
                 request_id: requestEnvelope.id,
                 inherited_crypto_level: responseSecurity?.inboundCryptoLevel ?? null,
                 channel_id: responseSecurity?.cryptoChannelId ?? null,
@@ -19962,14 +19964,14 @@
                 responseContext.fromSystemId = this.getId();
             }
             // Envelope-level metadata is intentionally omitted to defer to context usage.
-            logger$1c.debug('ensured_response_metadata', {
+            logger$1d.debug('ensured_response_metadata', {
                 response_id: responseEnvelope.id,
                 request_id: requestEnvelope.id,
             });
         }
     }
 
-    const logger$1b = getLogger('naylence.fame.node.streaming_response_handler');
+    const logger$1c = getLogger('naylence.fame.node.streaming_response_handler');
     function isObject$1(value) {
         return typeof value === 'object' && value !== null;
     }
@@ -20088,12 +20090,12 @@
         }
         async handleStreamingFameMessageResponses(responses, requestEnvelope, requestContext) {
             const asyncResponses = toAsyncIterable(responses);
-            logger$1b.debug('handling_streaming_fame_message_responses', {
+            logger$1c.debug('handling_streaming_fame_message_responses', {
                 request_id: requestEnvelope.id,
             });
             for await (const response of asyncResponses) {
                 if (!response?.envelope) {
-                    logger$1b.warning('invalid_streaming_response_type', {
+                    logger$1c.warning('invalid_streaming_response_type', {
                         request_id: requestEnvelope.id,
                         actual_type: typeof response,
                     });
@@ -20107,7 +20109,7 @@
         }
         async handleStreamingResponse(result, requestEnvelope, requestContext, replyTo, requestId) {
             const iterable = toAsyncIterable(result);
-            logger$1b.debug('handling_streaming_response', {
+            logger$1c.debug('handling_streaming_response', {
                 request_id: requestId,
                 reply_to: replyTo,
             });
@@ -20118,7 +20120,7 @@
                 await this.sendRpcResponse(null, requestEnvelope, requestContext, replyTo, requestId);
             }
             catch (error) {
-                logger$1b.error('streaming_response_handler_error', {
+                logger$1c.error('streaming_response_handler_error', {
                     request_id: requestId,
                     error: error instanceof Error ? error.message : String(error),
                 });
@@ -20145,7 +20147,7 @@
             });
             const responseContext = this.responseContextManager.createResponseContext(requestEnvelope, requestContext);
             this.responseContextManager.ensureResponseMetadata(responseEnvelope, requestEnvelope, responseContext);
-            logger$1b.debug('sending_streaming_rpc_response', {
+            logger$1c.debug('sending_streaming_rpc_response', {
                 request_id: requestId,
                 response_envelope_id: responseEnvelope.id,
                 reply_to: replyTo,
@@ -20158,7 +20160,7 @@
         }
     }
 
-    const logger$1a = getLogger('naylence.fame.node.channel_polling_manager');
+    const logger$1b = getLogger('naylence.fame.node.channel_polling_manager');
     class ChannelPollingManager {
         constructor(deliverWrapper, responseContextManager, streamingResponseHandler) {
             this.deliverWrapper = deliverWrapper;
@@ -20166,7 +20168,7 @@
             this.streamingResponseHandler = streamingResponseHandler;
         }
         async startPollingLoop(serviceName, channel, handler, stopState, pollTimeoutMs = DEFAULT_POLLING_TIMEOUT_MS) {
-            logger$1a.debug('poll_loop_started', {
+            logger$1b.debug('poll_loop_started', {
                 recipient: serviceName,
             });
             try {
@@ -20174,7 +20176,7 @@
                 while (true) {
                     if (this.isStopRequested(stopState) && !draining) {
                         draining = true;
-                        logger$1a.debug('poll_loop_draining_pending_messages', {
+                        logger$1b.debug('poll_loop_draining_pending_messages', {
                             recipient: serviceName,
                         });
                     }
@@ -20184,7 +20186,7 @@
                     }
                     catch (error) {
                         if (error instanceof FameTransportClose) {
-                            logger$1a.debug('channel_closed', {
+                            logger$1b.debug('channel_closed', {
                                 recipient: serviceName,
                                 message: error.message,
                             });
@@ -20197,7 +20199,7 @@
                             continue;
                         }
                         if (error instanceof Error && error.name === 'AbortError') {
-                            logger$1a.debug('listener_cancelled', {
+                            logger$1b.debug('listener_cancelled', {
                                 recipient: serviceName,
                             });
                             throw error;
@@ -20209,13 +20211,13 @@
                             continue;
                         }
                         if (error instanceof Error && error.message === 'Channel is closed') {
-                            logger$1a.debug('channel_closed', {
+                            logger$1b.debug('channel_closed', {
                                 recipient: serviceName,
                             });
                             break;
                         }
                         if (error instanceof Error && error.name === 'TaskCancelledError') {
-                            logger$1a.debug('listener_cancelled', {
+                            logger$1b.debug('listener_cancelled', {
                                 recipient: serviceName,
                             });
                             throw error;
@@ -20227,12 +20229,12 @@
                             continue;
                         }
                         if (error instanceof Error && error.message.includes('closed')) {
-                            logger$1a.debug('channel_closed', {
+                            logger$1b.debug('channel_closed', {
                                 recipient: serviceName,
                             });
                             break;
                         }
-                        logger$1a.error('transport_error', {
+                        logger$1b.error('transport_error', {
                             recipient: serviceName,
                             error: error instanceof Error ? error.message : String(error),
                         });
@@ -20248,7 +20250,7 @@
                 }
             }
             finally {
-                logger$1a.debug('poll_loop_exiting', {
+                logger$1b.debug('poll_loop_exiting', {
                     recipient: serviceName,
                 });
             }
@@ -20261,7 +20263,7 @@
                     await this.processHandlerResult(result, envelope, deliveryContext, serviceName);
                 }
                 catch (error) {
-                    logger$1a.error('handler_crashed', {
+                    logger$1b.error('handler_crashed', {
                         recipient: serviceName,
                         error: error instanceof Error ? error.message : String(error),
                     });
@@ -20275,7 +20277,7 @@
                 return;
             }
             if (this.streamingResponseHandler.isStreamingFameMessageResponse(result)) {
-                logger$1a.debug('handling_streaming_fame_message_responses', {
+                logger$1b.debug('handling_streaming_fame_message_responses', {
                     service_name: serviceName,
                     envelope_id: envelope.id,
                 });
@@ -20283,7 +20285,7 @@
             }
         }
         async handleMessageResponse(response, requestEnvelope, requestContext, serviceName) {
-            logger$1a.debug('delivering_envelope_response_message', {
+            logger$1b.debug('delivering_envelope_response_message', {
                 service_name: serviceName,
                 response_envelope_id: response.envelope.id,
             });
@@ -20303,7 +20305,7 @@
         }
     }
 
-    const logger$19 = getLogger('naylence.fame.node.rpc_server_handler');
+    const logger$1a = getLogger('naylence.fame.node.rpc_server_handler');
     function isPlainRecord$6(value) {
         if (typeof value !== 'object' || value === null) {
             return false;
@@ -20347,13 +20349,13 @@
         }
         async handleRpcRequest(envelope, handlerContext, handler, serviceName) {
             if (!this.isDataFrame(envelope.frame)) {
-                logger$19.warning('rpc_request_missing_data_frame', {
+                logger$1a.warning('rpc_request_missing_data_frame', {
                     service_name: serviceName,
                     envelope_id: envelope.id,
                 });
                 return;
             }
-            logger$19.debug('rpc_request_received', {
+            logger$1a.debug('rpc_request_received', {
                 service_name: serviceName,
                 envelope_id: envelope.id,
                 trace_id: envelope.traceId,
@@ -20365,7 +20367,7 @@
                 request = parseRequest(envelope.frame.payload);
                 params = cloneParams(request.params);
                 const paramKeys = Object.keys(params);
-                logger$19.debug('parsed_rpc_request', {
+                logger$1a.debug('parsed_rpc_request', {
                     service_name: serviceName,
                     method: request.method,
                     request_id: request.id,
@@ -20374,7 +20376,7 @@
                 });
             }
             catch (error) {
-                logger$19.warning('request_decode_error', {
+                logger$1a.warning('request_decode_error', {
                     service_name: serviceName,
                     envelope_id: envelope.id,
                     error: error instanceof Error ? error.message : String(error),
@@ -20382,7 +20384,7 @@
                 return;
             }
             if (request.id == null) {
-                logger$19.warning('request_missing_id', {
+                logger$1a.warning('request_missing_id', {
                     service_name: serviceName,
                     envelope_id: envelope.id,
                 });
@@ -20390,7 +20392,7 @@
             }
             const replyTo = this.resolveReplyTo(envelope, params);
             if (!replyTo) {
-                logger$19.warning('missing_reply_to', {
+                logger$1a.warning('missing_reply_to', {
                     service_name: serviceName,
                     envelope_id: envelope.id,
                     request_id: request.id,
@@ -20399,13 +20401,13 @@
             }
             let handlerResult;
             try {
-                logger$19.debug('calling_rpc_handler', {
+                logger$1a.debug('calling_rpc_handler', {
                     service_name: serviceName,
                     method: request.method,
                     request_id: request.id,
                 });
                 handlerResult = await handler(request.method, params);
-                logger$19.debug('rpc_handler_returned', {
+                logger$1a.debug('rpc_handler_returned', {
                     service_name: serviceName,
                     method: request.method,
                     request_id: request.id,
@@ -20414,7 +20416,7 @@
                 });
             }
             catch (error) {
-                logger$19.error('rpc_handler_error', {
+                logger$1a.error('rpc_handler_error', {
                     service_name: serviceName,
                     request_id: request.id,
                     envelope_id: envelope.id,
@@ -20424,7 +20426,7 @@
                 return this.createTraditionalResponse(response, request.id, envelope, replyTo, handlerContext, serviceName);
             }
             if (isFameMessageResponse(handlerResult)) {
-                logger$19.debug('returning_response_message', {
+                logger$1a.debug('returning_response_message', {
                     service_name: serviceName,
                     request_id: request.id,
                     response_envelope_id: handlerResult.envelope.id,
@@ -20432,7 +20434,7 @@
                 return handlerResult;
             }
             if (this.streamingResponseHandler.isStreamingResult(handlerResult)) {
-                logger$19.debug('handling_streaming_response', {
+                logger$1a.debug('handling_streaming_response', {
                     service_name: serviceName,
                     request_id: request.id,
                     envelope_id: envelope.id,
@@ -20461,7 +20463,7 @@
             return null;
         }
         async createTraditionalResponse(payload, requestId, requestEnvelope, replyTo, handlerContext, serviceName) {
-            logger$19.debug('creating_traditional_response_envelope', {
+            logger$1a.debug('creating_traditional_response_envelope', {
                 service_name: serviceName,
                 request_id: requestId,
                 envelope_id: requestEnvelope.id,
@@ -20485,7 +20487,7 @@
             if (requestEnvelope.id) {
                 responseContext.meta['response-to-id'] = requestEnvelope.id;
             }
-            logger$19.debug('returning_traditional_response', {
+            logger$1a.debug('returning_traditional_response', {
                 service_name: serviceName,
                 request_id: requestId,
                 envelope_id: requestEnvelope.id,
@@ -20550,7 +20552,7 @@
         return code;
     }
 
-    const logger$18 = getLogger('naylence.fame.node.rpc_client_manager');
+    const logger$19 = getLogger('naylence.fame.node.rpc_client_manager');
     function isPlainRecord$5(value) {
         if (typeof value !== 'object' || value === null) {
             return false;
@@ -20767,7 +20769,7 @@
             const metaReason = tracked.meta?.['nack_reason'];
             const formattedMessage = formatDeliveryErrorMessage(typeof metaCode === 'string' ? metaCode : 'DELIVERY_ERROR', reason ??
                 (typeof metaReason === 'string' ? metaReason : undefined));
-            logger$18.debug('pending_request_rejected_by_delivery_nack', {
+            logger$19.debug('pending_request_rejected_by_delivery_nack', {
                 envelope_id: envelopeId,
                 request_id: requestId,
                 code: typeof metaCode === 'string' ? metaCode : 'DELIVERY_ERROR',
@@ -20790,7 +20792,7 @@
                     this.trackerWithEvents.removeEventHandler?.(this.trackerEventHandler);
                 }
                 catch (error) {
-                    logger$18.debug('rpc_tracker_handler_remove_failed', {
+                    logger$19.debug('rpc_tracker_handler_remove_failed', {
                         error: error instanceof Error ? error.message : String(error),
                     });
                 }
@@ -20833,7 +20835,7 @@
             this.rpcListenerAddress = await this.listenCallback(recipient, handler);
             this.rpcBound = true;
             this.boundPhysicalPath = currentPhysicalPath;
-            logger$18.debug('rpc_reply_listener_bound', {
+            logger$19.debug('rpc_reply_listener_bound', {
                 reply_recipient: recipient,
                 reply_address: this.rpcReplyAddress?.toString(),
                 listener_address: this.rpcListenerAddress?.toString(),
@@ -20927,7 +20929,7 @@
                 const finalizePromise = this.notifyStreamClosed(envelopeId);
                 if (finalizePromise) {
                     finalizePromise.catch((notifyError) => {
-                        logger$18.debug('stream_tracker_finalize_failed', {
+                        logger$19.debug('stream_tracker_finalize_failed', {
                             request_id: requestId,
                             envelope_id: envelopeId,
                             error: notifyError instanceof Error
@@ -20988,7 +20990,7 @@
             return iterator;
         }
         async sendRpcRequest(requestId, envelope, expectedResponseType, timeoutMs) {
-            logger$18.debug('sending_rpc_request', {
+            logger$19.debug('sending_rpc_request', {
                 envp_id: envelope.id,
                 corr_id: envelope.corrId,
                 request_id: requestId,
@@ -21004,7 +21006,7 @@
                 }
             }
             catch (error) {
-                logger$18.warning('delivery_tracker_track_failed', {
+                logger$19.warning('delivery_tracker_track_failed', {
                     request_id: requestId,
                     error: error instanceof Error ? error.message : String(error),
                 });
@@ -21017,14 +21019,14 @@
             await this.deliverWrapper()(envelope, context);
         }
         async handleReplyEnvelope(envelope) {
-            logger$18.debug('handle_reply_envelope_received', {
+            logger$19.debug('handle_reply_envelope_received', {
                 envelope_id: envelope.id,
                 corr_id: envelope.corrId,
                 frame_type: envelope.frame?.['type'],
             });
             let requestId = envelope.corrId ?? envelope.id;
             if (!requestId) {
-                logger$18.warning('reply_envelope_missing_corr_id', {
+                logger$19.warning('reply_envelope_missing_corr_id', {
                     envelope_id: envelope.id,
                 });
                 return;
@@ -21042,12 +21044,12 @@
                 }
             }
             if (!entry) {
-                logger$18.debug('no_pending_request_for_reply', {
+                logger$19.debug('no_pending_request_for_reply', {
                     request_id: requestId,
                 });
                 return;
             }
-            logger$18.debug('handle_reply_envelope', {
+            logger$19.debug('handle_reply_envelope', {
                 envelope_id: envelope.id,
                 request_id: requestId,
                 corr_id: envelope.corrId,
@@ -21060,7 +21062,7 @@
                 const ackIndicatesSuccess = frame.ok === true ||
                     (frame.ok === undefined && !frame.code && !frame.reason);
                 if (ackIndicatesSuccess) {
-                    logger$18.debug('pending_request_delivery_acknowledged', {
+                    logger$19.debug('pending_request_delivery_acknowledged', {
                         request_id: requestId,
                         envelope_id: envelope.id,
                         ref_id: frame.refId ?? null,
@@ -21088,7 +21090,7 @@
                 entry.timer = null;
             }
             if (!this.isDataFrame(envelope.frame)) {
-                logger$18.warning('unexpected_reply_frame_type', {
+                logger$19.warning('unexpected_reply_frame_type', {
                     request_id: requestId,
                     frame_type: envelope.frame?.['type'],
                 });
@@ -21154,7 +21156,7 @@
                 return;
             }
             Promise.resolve(this.deliveryTracker.onStreamItem(envelopeId, envelope)).catch((error) => {
-                logger$18.debug('stream_tracker_push_failed', {
+                logger$19.debug('stream_tracker_push_failed', {
                     envelope_id: envelopeId,
                     error: error instanceof Error ? error.message : String(error),
                 });
@@ -21269,7 +21271,7 @@
         return mailbox;
     }
 
-    const logger$17 = getLogger('naylence.fame.node.envelope_listener_manager');
+    const logger$18 = getLogger('naylence.fame.node.envelope_listener_manager');
     const SYSTEM_INBOX$2 = '__sys__';
     class EnvelopeListener {
         constructor(stopFn, task) {
@@ -21277,7 +21279,7 @@
             this.task = task;
         }
         stop() {
-            logger$17.debug('stopping_listener', {
+            logger$18.debug('stopping_listener', {
                 task_name: this.task.name,
             });
             try {
@@ -21285,7 +21287,7 @@
                 if (maybeCleanup &&
                     typeof maybeCleanup.then === 'function') {
                     void maybeCleanup.catch((error) => {
-                        logger$17.debug('listener_stop_cleanup_failed', {
+                        logger$18.debug('listener_stop_cleanup_failed', {
                             task_name: this.task.name,
                             error: error instanceof Error ? error.message : String(error),
                         });
@@ -21293,7 +21295,7 @@
                 }
             }
             catch (error) {
-                logger$17.debug('listener_stop_cleanup_failed', {
+                logger$18.debug('listener_stop_cleanup_failed', {
                     task_name: this.task.name,
                     error: error instanceof Error ? error.message : String(error),
                 });
@@ -21323,7 +21325,7 @@
                         envelope.replyTo = formatAddress(SYSTEM_INBOX$2, this.nodeLike.physicalPath);
                     }
                     catch (error) {
-                        logger$17.warning('default_reply_to_assignment_failed', {
+                        logger$18.warning('default_reply_to_assignment_failed', {
                             envelope_id: envelope.id,
                             service_name: envelope.capabilities?.[0] ?? null,
                             error: error instanceof Error ? error.message : String(error),
@@ -21348,7 +21350,7 @@
                     if (serviceName === SYSTEM_INBOX$2) {
                         continue;
                     }
-                    logger$17.debug('stopping_listener_for_service', {
+                    logger$18.debug('stopping_listener_for_service', {
                         service_name: serviceName,
                     });
                     entry.listener.stop();
@@ -21358,7 +21360,7 @@
                     catch (error) {
                         if (!(error instanceof Error) ||
                             error.name !== 'TaskCancelledError') {
-                            logger$17.debug('listener_task_stopped', {
+                            logger$18.debug('listener_task_stopped', {
                                 service_name: serviceName,
                                 error: error instanceof Error ? error.message : String(error),
                             });
@@ -21366,7 +21368,7 @@
                     }
                 }
                 if (systemEntry) {
-                    logger$17.debug('stopping_listener_for_service', {
+                    logger$18.debug('stopping_listener_for_service', {
                         service_name: SYSTEM_INBOX$2,
                     });
                     systemEntry.listener.stop();
@@ -21376,7 +21378,7 @@
                     catch (error) {
                         if (!(error instanceof Error) ||
                             error.name !== 'TaskCancelledError') {
-                            logger$17.debug('listener_task_stopped', {
+                            logger$18.debug('listener_task_stopped', {
                                 service_name: SYSTEM_INBOX$2,
                                 error: error instanceof Error ? error.message : String(error),
                             });
@@ -21393,13 +21395,13 @@
         }
         async recoverUnhandledInboundEnvelopes() {
             if (typeof this.deliveryTracker.listInbound !== 'function') {
-                logger$17.debug('delivery_tracker_missing_inbound_listing');
+                logger$18.debug('delivery_tracker_missing_inbound_listing');
                 return;
             }
             const failedInbound = await this.deliveryTracker.listInbound((env) => env.status === EnvelopeStatus.RECEIVED ||
                 env.status === EnvelopeStatus.FAILED_TO_HANDLE);
             if (!failedInbound.length) {
-                logger$17.debug('no_failed_inbound_envelopes_to_recover');
+                logger$18.debug('no_failed_inbound_envelopes_to_recover');
                 return;
             }
             const grouped = new Map();
@@ -21416,7 +21418,7 @@
                     this.pendingRecoveryEnvelopes.set(serviceName, envelopes);
                 }
             });
-            logger$17.debug('discovered_failed_inbound_envelopes', {
+            logger$18.debug('discovered_failed_inbound_envelopes', {
                 total: failedInbound.length,
                 services: Array.from(grouped.keys()),
             });
@@ -21426,7 +21428,7 @@
             const pollTimeoutMs = options.pollTimeoutMs ??
                 options.poll_timeout_ms ??
                 DEFAULT_POLLING_TIMEOUT_MS;
-            logger$17.debug('listen_start', {
+            logger$18.debug('listen_start', {
                 recipient: serviceName,
                 poll_timeout_ms: pollTimeoutMs ?? DEFAULT_POLLING_TIMEOUT_MS,
             });
@@ -21457,7 +21459,7 @@
                         tracked?.mailboxType === MailboxType.OUTBOX ||
                         envelope.frame?.['type'] === 'DeliveryAck';
                     if (!shouldInvoke) {
-                        logger$17.debug('skipping_listener_handler', {
+                        logger$18.debug('skipping_listener_handler', {
                             recipient: serviceName,
                             envelope_id: envelope.id,
                             tracked_status: tracked?.status,
@@ -21471,13 +21473,13 @@
                         ? undefined
                         : (tracked ?? undefined);
                     if (trackedForHandler && trackedForHandler.attempt > 0) {
-                        logger$17.info('resuming_handler_retry_after_restart', {
+                        logger$18.info('resuming_handler_retry_after_restart', {
                             envelope_id: envelope.id,
                             current_attempts: trackedForHandler.attempt,
                             service_name: serviceName,
                         });
                     }
-                    logger$17.debug('forwarding_to_listener_handler', {
+                    logger$18.debug('forwarding_to_listener_handler', {
                         recipient: serviceName,
                         envelope_id: envelope.id,
                         frame_type: envelope.frame?.['type'],
@@ -21496,7 +21498,7 @@
                     await channel.send(null);
                 }
                 catch (error) {
-                    logger$17.debug('listener_stop_signal_failed', {
+                    logger$18.debug('listener_stop_signal_failed', {
                         service_name: serviceName,
                         error: error instanceof Error ? error.message : String(error),
                     });
@@ -21505,7 +21507,7 @@
             await this.listenersLock.runExclusive(async () => {
                 const existing = this.listeners.get(serviceName);
                 if (existing) {
-                    logger$17.debug('replacing_envelope_listener', { recipient: serviceName });
+                    logger$18.debug('replacing_envelope_listener', { recipient: serviceName });
                     existing.listener.stop();
                     try {
                         await existing.listener.task.promise;
@@ -21523,13 +21525,13 @@
             return binding.address;
         }
         async listenRpc(serviceName, handler, options = {}) {
-            logger$17.debug('rpc_listen_start', { service_name: serviceName });
+            logger$18.debug('rpc_listen_start', { service_name: serviceName });
             const rpcHandler = async (envelope, context) => {
                 const result = await this.rpcServerHandler.handleRpcRequest(envelope, context, handler, serviceName);
                 return result ?? null;
             };
             const address = await this.listen(serviceName, rpcHandler, options);
-            logger$17.debug('rpc_listen_bound', {
+            logger$18.debug('rpc_listen_bound', {
                 service_name: serviceName,
                 address: address.toString(),
             });
@@ -21598,12 +21600,12 @@
                     return cached;
                 });
                 if (!envelopes.length) {
-                    logger$17.debug('no_cached_recovery_for_service', {
+                    logger$18.debug('no_cached_recovery_for_service', {
                         service_name: serviceName,
                     });
                     return;
                 }
-                logger$17.debug('recovering_unhandled_envelopes_on_listen', {
+                logger$18.debug('recovering_unhandled_envelopes_on_listen', {
                     service_name: serviceName,
                     count: envelopes.length,
                     envelope_ids: envelopes.map((trackedEnvelope) => trackedEnvelope.envelopeId),
@@ -21614,7 +21616,7 @@
         async recoverServiceEnvelopes(serviceName, envelopes, handler) {
             for (const tracked of envelopes) {
                 try {
-                    logger$17.warning('recovering_unhandled_envelope', {
+                    logger$18.warning('recovering_unhandled_envelope', {
                         envelope_id: tracked.envelopeId,
                         service_name: serviceName,
                         current_attempts: tracked.attempt,
@@ -21623,13 +21625,13 @@
                     const originalEnvelope = tracked.originalEnvelope;
                     const receiverPolicy = this.nodeLike.deliveryPolicy?.receiverRetryPolicy ?? undefined;
                     await this.executeHandlerWithRetries(handler, originalEnvelope, undefined, receiverPolicy, tracked, serviceName);
-                    logger$17.debug('envelope_recovery_completed', {
+                    logger$18.debug('envelope_recovery_completed', {
                         envelope_id: tracked.envelopeId,
                         service_name: serviceName,
                     });
                 }
                 catch (error) {
-                    logger$17.error('envelope_recovery_failed', {
+                    logger$18.error('envelope_recovery_failed', {
                         envelope_id: tracked.envelopeId,
                         service_name: serviceName,
                         error: error instanceof Error ? error.message : String(error),
@@ -21675,7 +21677,7 @@
                         await this.deliveryTracker.onEnvelopeHandled(trackedEnvelope);
                     }
                     if (currentAttempt > 0) {
-                        logger$17.info('handler_retry_succeeded', {
+                        logger$18.info('handler_retry_succeeded', {
                             envelope_id: envelope.id,
                             attempt: currentAttempt + 1,
                             total_attempts: currentAttempt + 1,
@@ -21691,7 +21693,7 @@
                         await this.deliveryTracker.onEnvelopeHandleFailed(inboxName, trackedEnvelope, context, error instanceof Error ? error : new Error(String(error)), isFinalAttempt);
                     }
                     if (isFinalAttempt) {
-                        logger$17.error('handler_execution_failed_exhausted_retries', {
+                        logger$18.error('handler_execution_failed_exhausted_retries', {
                             envelope_id: envelope.id,
                             total_attempts: attemptNumber,
                             max_retries: retryPolicy?.maxRetries ?? 0,
@@ -21700,7 +21702,7 @@
                         break;
                     }
                     const delayMs = retryPolicy?.nextDelayMs(attemptNumber) ?? 0;
-                    logger$17.warning('handler_execution_failed_will_retry', {
+                    logger$18.warning('handler_execution_failed_will_retry', {
                         envelope_id: envelope.id,
                         attempt: attemptNumber,
                         max_retries: retryPolicy?.maxRetries ?? 0,
@@ -21730,7 +21732,7 @@
         }
     }
 
-    const logger$16 = getLogger('naylence.fame.delivery.default_delivery_tracker');
+    const logger$17 = getLogger('naylence.fame.delivery.default_delivery_tracker');
     const STREAM_END = Symbol('stream-end');
     const SWEEPER_TICK = Symbol('tracker-sweeper-tick');
     function createDeferred$2() {
@@ -21949,7 +21951,7 @@
             const expectedResponseType = options.expectedResponseType;
             const tracked = await this.lock.runExclusive(async () => {
                 if (this.ackFutures.has(envelope.id)) {
-                    logger$16.debug('tracker_envelope_already_tracked', {
+                    logger$17.debug('tracker_envelope_already_tracked', {
                         envp_id: envelope.id,
                     });
                     return null;
@@ -21959,7 +21961,7 @@
                 if (expectedResponseType & FameResponseType.REPLY ||
                     expectedResponseType & FameResponseType.STREAM) {
                     if (existingEnvId && existingEnvId !== envelope.id) {
-                        logger$16.debug('envelope_already_tracked_for_replies', {
+                        logger$17.debug('envelope_already_tracked_for_replies', {
                             envp_id: envelope.id,
                             corr_id: corrId,
                             expected_response_type: expectedResponseType,
@@ -22008,7 +22010,7 @@
                 return null;
             }
             await this.scheduleTimer(tracked, options.retryPolicy ?? null, options.retryHandler ?? null);
-            logger$16.debug('tracker_registered_envelope', {
+            logger$17.debug('tracker_registered_envelope', {
                 envp_id: envelope.id,
                 corr_id: tracked.originalEnvelope.corrId,
                 expected_response: tracked.expectedResponseType,
@@ -22032,21 +22034,21 @@
             return this.awaitEnvelopeFuture(envelopeId, FameResponseType.REPLY | FameResponseType.STREAM, future, timeoutMs);
         }
         async onEnvelopeDelivered(inboxName, envelope, context) {
-            logger$16.debug('envelope_delivered', {
+            logger$17.debug('envelope_delivered', {
                 envp_id: envelope.id,
                 corr_id: envelope.corrId,
                 rtype: envelope.rtype ?? FameResponseType.NONE,
                 frame_type: envelope.frame?.type ?? 'unknown',
             });
             if (!envelope.corrId) {
-                logger$16.debug('envelope_delivered_no_corr_id', {
+                logger$17.debug('envelope_delivered_no_corr_id', {
                     envelope_id: envelope.id,
                 });
                 return null;
             }
             if (this.isDeliveryAckFrame(envelope.frame)) {
                 if (!envelope.frame.refId) {
-                    logger$16.debug('envelope_delivered_no_ref_id', {
+                    logger$17.debug('envelope_delivered_no_ref_id', {
                         envelope_id: envelope.id,
                     });
                     return null;
@@ -22083,7 +22085,7 @@
                         await inbox.set(envelope.id, tracked);
                     }
                     else {
-                        logger$16.debug('tracker_duplicate_envelope_already_handled', {
+                        logger$17.debug('tracker_duplicate_envelope_already_handled', {
                             envp_id: envelope.id,
                             status: tracked.status,
                         });
@@ -22125,7 +22127,7 @@
             }
             if (isFinalFailure) {
                 envelope.status = EnvelopeStatus.FAILED_TO_HANDLE;
-                logger$16.error('envelope_handle_failed_final', {
+                logger$17.error('envelope_handle_failed_final', {
                     inbox_name: inboxName,
                     envp_id: envelope.originalEnvelope.id,
                     error: error?.message ?? 'unknown',
@@ -22136,7 +22138,7 @@
                 await inbox.delete(envelope.originalEnvelope.id);
                 return;
             }
-            logger$16.warning('envelope_handle_failed_retry', {
+            logger$17.warning('envelope_handle_failed_retry', {
                 inbox_name: inboxName,
                 envp_id: envelope.originalEnvelope.id,
                 error: error?.message ?? 'unknown',
@@ -22181,14 +22183,14 @@
                 if (handledViaFuture) {
                     await this.markDoneSince(this.ackFutures, refId, this.ackDoneSince);
                     await this.clearTimer(refId);
-                    logger$16.debug('tracker_ack_resolved_without_tracked_envelope', {
+                    logger$17.debug('tracker_ack_resolved_without_tracked_envelope', {
                         envp_id: envelope.id,
                         ref_id: refId,
                         corr_id: envelope.corrId,
                     });
                     return;
                 }
-                logger$16.debug('tracker_ack_for_unknown_envelope', {
+                logger$17.debug('tracker_ack_for_unknown_envelope', {
                     envp_id: envelope.id,
                     ref_id: refId,
                     corr_id: envelope.corrId,
@@ -22196,7 +22198,7 @@
                 return;
             }
             if (tracked.originalEnvelope.corrId !== envelope.corrId) {
-                logger$16.debug('tracker_ack_corr_id_mismatch', {
+                logger$17.debug('tracker_ack_corr_id_mismatch', {
                     envp_id: envelope.id,
                     expected_corr_id: tracked.originalEnvelope.corrId,
                     actual_corr_id: envelope.corrId,
@@ -22221,7 +22223,7 @@
             for (const handler of this.eventHandlers) {
                 await handler.onEnvelopeAcked?.(tracked);
             }
-            logger$16.debug('tracker_envelope_acked', {
+            logger$17.debug('tracker_envelope_acked', {
                 envp_id: tracked.originalEnvelope.id,
             });
         }
@@ -22238,13 +22240,13 @@
             const outbox = this.ensureOutbox();
             const tracked = await outbox.get(envelope.frame.refId);
             if (!tracked) {
-                logger$16.debug('tracker_nack_for_unknown_envelope', {
+                logger$17.debug('tracker_nack_for_unknown_envelope', {
                     envp_id: envelope.id,
                 });
                 return;
             }
             if (tracked.originalEnvelope.corrId !== envelope.corrId) {
-                logger$16.debug('tracker_nack_corr_id_mismatch', {
+                logger$17.debug('tracker_nack_corr_id_mismatch', {
                     envp_id: envelope.id,
                     expected_corr_id: tracked.originalEnvelope.corrId,
                     actual_corr_id: envelope.corrId,
@@ -22286,7 +22288,7 @@
             for (const handler of this.eventHandlers) {
                 await handler.onEnvelopeNacked?.(tracked, ackFrame.reason ?? null);
             }
-            logger$16.debug('tracker_envelope_nacked', {
+            logger$17.debug('tracker_envelope_nacked', {
                 envp_id: tracked.originalEnvelope.id,
                 reason: ackFrame.reason,
             });
@@ -22333,7 +22335,7 @@
             for (const handler of this.eventHandlers) {
                 await handler.onEnvelopeReplied?.(trackedEnvelope, envelope);
             }
-            logger$16.debug('tracked_envelope_replied', {
+            logger$17.debug('tracked_envelope_replied', {
                 envp_id: trackedEnvelope.originalEnvelope.id,
                 corr_id: envelope.corrId,
             });
@@ -22407,7 +22409,7 @@
         async addToInboxDlq(trackedEnvelope, reason = null) {
             const dlq = this.inboxDlq;
             if (!dlq) {
-                logger$16.error('dlq_not_initialized', {
+                logger$17.error('dlq_not_initialized', {
                     envp_id: trackedEnvelope.originalEnvelope.id,
                 });
                 return;
@@ -22422,7 +22424,7 @@
             const deadLetteredAt = Date.now();
             setMetaWithLegacy(trackedEnvelope.meta, 'deadLetteredAtMs', 'dead_lettered_at_ms', deadLetteredAt);
             await dlq.set(trackedEnvelope.originalEnvelope.id, trackedEnvelope);
-            logger$16.warning('envelope_moved_to_dlq', {
+            logger$17.warning('envelope_moved_to_dlq', {
                 envp_id: trackedEnvelope.originalEnvelope.id,
                 service_name: trackedEnvelope.serviceName,
             });
@@ -22451,7 +22453,7 @@
             const toDelete = Object.entries(items).filter(([, value]) => predicate ? predicate(value) : true);
             await Promise.all(toDelete.map(([key]) => dlq.delete(key)));
             if (toDelete.length) {
-                logger$16.debug('dlq_purged', { count: toDelete.length });
+                logger$17.debug('dlq_purged', { count: toDelete.length });
             }
             return toDelete.length;
         }
@@ -22504,11 +22506,11 @@
                 }
                 this.futuresSweeper = null;
             }
-            logger$16.debug('tracker_cleanup_completed');
+            logger$17.debug('tracker_cleanup_completed');
         }
         async recoverPending() {
             const pending = await this.listPending();
-            logger$16.debug('tracker_recovering_pending', { count: pending.length });
+            logger$17.debug('tracker_recovering_pending', { count: pending.length });
             await this.lock.runExclusive(async () => {
                 for (const tracked of pending) {
                     if (tracked.expectedResponseType & FameResponseType.ACK) {
@@ -22534,7 +22536,7 @@
             for (const tracked of pending) {
                 await this.scheduleTimer(tracked, null, null);
             }
-            logger$16.debug('tracker_recovery_completed', { count: pending.length });
+            logger$17.debug('tracker_recovery_completed', { count: pending.length });
         }
         ensureOutbox() {
             if (!this.outbox) {
@@ -22549,7 +22551,7 @@
             return this.inbox;
         }
         async waitForPendingAcks() {
-            logger$16.debug('tracker_node_preparing_to_stop_waiting_for_pending_acks');
+            logger$17.debug('tracker_node_preparing_to_stop_waiting_for_pending_acks');
             const outbox = this.outbox;
             if (!outbox) {
                 return;
@@ -22561,7 +22563,7 @@
                         continue;
                     }
                     if (!future.done) {
-                        logger$16.debug('tracker_pending_ack_future_detected', {
+                        logger$17.debug('tracker_pending_ack_future_detected', {
                             envelope_id: envelopeId,
                         });
                         pending.push({ envelopeId, future });
@@ -22569,10 +22571,10 @@
                 }
             });
             if (!pending.length) {
-                logger$16.debug('tracker_no_pending_acks_to_wait_for');
+                logger$17.debug('tracker_no_pending_acks_to_wait_for');
                 return;
             }
-            logger$16.debug('tracker_waiting_for_pending_acks', { count: pending.length });
+            logger$17.debug('tracker_waiting_for_pending_acks', { count: pending.length });
             for (const entry of pending) {
                 if (!entry) {
                     continue;
@@ -22589,19 +22591,19 @@
                     }
                     try {
                         await this.awaitWithTimeout(entry.future.promise, remainingMs);
-                        logger$16.debug('tracker_received_ack', {
+                        logger$17.debug('tracker_received_ack', {
                             envelope_id: entry.envelopeId,
                         });
                         await outbox.delete(entry.envelopeId);
                     }
                     catch (error) {
                         if (error instanceof Error && error.name === 'TimeoutError') {
-                            logger$16.debug('tracker_ack_timeout_expired', {
+                            logger$17.debug('tracker_ack_timeout_expired', {
                                 envelope_id: entry.envelopeId,
                             });
                         }
                         else {
-                            logger$16.debug('tracker_ack_wait_error', {
+                            logger$17.debug('tracker_ack_wait_error', {
                                 envelope_id: entry.envelopeId,
                                 error: error instanceof Error ? error.message : String(error),
                             });
@@ -22609,13 +22611,13 @@
                     }
                 }
                 catch (error) {
-                    logger$16.error('tracker_error_waiting_for_ack', {
+                    logger$17.error('tracker_error_waiting_for_ack', {
                         envelope_id: entry.envelopeId,
                         error: error instanceof Error ? error.message : String(error),
                     });
                 }
             }
-            logger$16.debug('tracker_finished_waiting_for_pending_acks');
+            logger$17.debug('tracker_finished_waiting_for_pending_acks');
         }
         async waitForPendingAckDispatches() {
             while (this.pendingAckDispatches.size > 0) {
@@ -22673,7 +22675,7 @@
                             for (const handler of this.eventHandlers) {
                                 await handler.onEnvelopeTimeout?.(currentTracked);
                             }
-                            logger$16.debug('tracker_envelope_timed_out', {
+                            logger$17.debug('tracker_envelope_timed_out', {
                                 envp_id: tracked.originalEnvelope.id,
                             });
                             return;
@@ -22686,7 +22688,7 @@
                                 currentTracked.timeoutAtMs = nextTimeoutAt;
                                 await outbox.set(tracked.originalEnvelope.id, currentTracked);
                                 await this.scheduleTimer(currentTracked, retryPolicy, retryHandler);
-                                logger$16.debug('tracker_retry_deferred_during_shutdown', {
+                                logger$17.debug('tracker_retry_deferred_during_shutdown', {
                                     envp_id: tracked.originalEnvelope.id,
                                     defer_ms: shutdownDeferMs,
                                 });
@@ -22709,7 +22711,7 @@
                                 });
                             }
                             await this.scheduleTimer(currentTracked, retryPolicy, retryHandler);
-                            logger$16.debug('envelope_delivery_retry_scheduled', {
+                            logger$17.debug('envelope_delivery_retry_scheduled', {
                                 envp_id: tracked.originalEnvelope.id,
                                 attempt: currentTracked.attempt,
                                 max_retries: retryPolicy.maxRetries,
@@ -22721,7 +22723,7 @@
                             currentTracked.timeoutAtMs = currentTracked.overallTimeoutAtMs;
                             await outbox.set(tracked.originalEnvelope.id, currentTracked);
                             await this.scheduleTimer(currentTracked, retryPolicy, retryHandler);
-                            logger$16.debug('envelope_retries_exhausted_waiting_until_overall_timeout', {
+                            logger$17.debug('envelope_retries_exhausted_waiting_until_overall_timeout', {
                                 envp_id: tracked.originalEnvelope.id,
                                 attempt: currentTracked.attempt,
                                 overall_timeout_at_ms: currentTracked.overallTimeoutAtMs,
@@ -22741,7 +22743,7 @@
                         for (const handler of this.eventHandlers) {
                             await handler.onEnvelopeTimeout?.(currentTracked);
                         }
-                        logger$16.debug('tracker_envelope_timed_out', {
+                        logger$17.debug('tracker_envelope_timed_out', {
                             envp_id: tracked.originalEnvelope.id,
                         });
                     }
@@ -22749,7 +22751,7 @@
                         if (error instanceof TaskCancelledError) {
                             return;
                         }
-                        logger$16.error('tracker_timer_error', {
+                        logger$17.error('tracker_timer_error', {
                             envp_id: tracked.originalEnvelope.id,
                             error: error instanceof Error ? error.message : String(error),
                         });
@@ -22804,7 +22806,7 @@
                 if (timeoutSeconds !== null) {
                     return await this.awaitWithTimeout(future.promise, timeoutSeconds);
                 }
-                logger$16.debug('await_envelope_no_timeout_wait', {
+                logger$17.debug('await_envelope_no_timeout_wait', {
                     envelope_id: envelopeId,
                 });
                 return await future.promise;
@@ -22813,7 +22815,7 @@
                 if (error instanceof Error && error.name !== 'TimeoutError') {
                     throw error;
                 }
-                logger$16.error('await_envelope_timeout_error', {
+                logger$17.error('await_envelope_timeout_error', {
                     envelope_id: envelopeId,
                     timeout_ms: timeoutSeconds,
                     future_done: false,
@@ -22974,7 +22976,7 @@
                                 this.replyDoneSince.delete(envId);
                             }
                         });
-                        logger$16.debug('tracker_swept_completed_futures', {
+                        logger$17.debug('tracker_swept_completed_futures', {
                             ack_removed: toRemoveAck.length,
                             reply_removed: toRemoveReply.length,
                             grace_secs: this.futGcGraceSecs,
@@ -22988,7 +22990,7 @@
                     if (error instanceof Error && error.name === 'TimeoutError') {
                         continue;
                     }
-                    logger$16.error('tracker_sweeper_error', {
+                    logger$17.error('tracker_sweeper_error', {
                         error: error instanceof Error ? error.message : String(error),
                     });
                 }
@@ -23019,14 +23021,14 @@
             }
             const node = this.node;
             if (!envelope.replyTo) {
-                logger$16.error('cannot_send_ack_no_reply_to', { envp_id: envelope.id });
+                logger$17.error('cannot_send_ack_no_reply_to', { envp_id: envelope.id });
                 return;
             }
             if (!envelope.corrId) {
-                logger$16.error('cannot_send_ack_no_corr_id', { envp_id: envelope.id });
+                logger$17.error('cannot_send_ack_no_corr_id', { envp_id: envelope.id });
                 return;
             }
-            logger$16.debug('tracker_sending_ack', {
+            logger$17.debug('tracker_sending_ack', {
                 envp_id: envelope.id,
                 ref_id: envelope.id,
                 to: envelope.replyTo,
@@ -23046,7 +23048,7 @@
                 .send(ackEnvelope)
                 .then(() => undefined)
                 .catch((error) => {
-                logger$16.error('tracker_ack_dispatch_failed', {
+                logger$17.error('tracker_ack_dispatch_failed', {
                     envp_id: envelope.id,
                     error: error instanceof Error ? error.message : String(error),
                 });
@@ -23132,7 +23134,7 @@
         }
     }
 
-    const logger$15 = getLogger('naylence.fame.node.root_session_manager');
+    const logger$16 = getLogger('naylence.fame.node.root_session_manager');
     function resolveOption$1(options, primary, ...aliases) {
         const record = options;
         const primaryKey = primary;
@@ -23213,7 +23215,7 @@
             this.onAdmissionFailed =
                 typeof onAdmissionFailed === 'function' ? onAdmissionFailed : undefined;
             this.enableContinuousRefresh = enableContinuousRefresh ?? true;
-            logger$15.debug('created_root_session_manager');
+            logger$16.debug('created_root_session_manager');
         }
         get isReady() {
             return this.readyEvent.isSet();
@@ -23238,7 +23240,7 @@
             if (this.admissionTask) {
                 return;
             }
-            logger$15.debug('root_session_manager_starting');
+            logger$16.debug('root_session_manager_starting');
             this.stopEvent.clear();
             this.readyEvent.clear();
             const taskName = `root-admission-${this.admissionEpoch}`;
@@ -23258,10 +23260,10 @@
                 await this.admissionTask.promise;
                 throw new FameConnectError('Root session manager failed to become ready');
             }
-            logger$15.debug('root_session_manager_started');
+            logger$16.debug('root_session_manager_started');
         }
         async stop() {
-            logger$15.debug('root_session_manager_stopping');
+            logger$16.debug('root_session_manager_stopping');
             this.stopEvent.set();
             if (this.admissionTask) {
                 this.admissionTask.cancel();
@@ -23273,7 +23275,7 @@
                 await this.consumeTask(this.expiryGuardTask);
                 this.expiryGuardTask = null;
             }
-            logger$15.debug('root_session_manager_stopped');
+            logger$16.debug('root_session_manager_stopped');
         }
         async awaitReady(timeoutMs) {
             if (this.isReady) {
@@ -23314,12 +23316,12 @@
                 await this.onEpochChange(epoch);
             }
             else {
-                logger$15.debug('epoch_change_ignored_no_handler', { epoch });
+                logger$16.debug('epoch_change_ignored_no_handler', { epoch });
             }
         }
         static createForRootSentinel(node, admissionClient, requestedLogicals = [], enableContinuousRefresh = true, onEpochChange) {
             const handleWelcome = async (frame) => {
-                logger$15.info('root_admission_successful', {
+                logger$16.info('root_admission_successful', {
                     system_id: frame.systemId,
                     assigned_path: frame.assignedPath ?? null,
                     accepted_logicals: frame.acceptedLogicals ?? [],
@@ -23330,12 +23332,12 @@
                         ? grant.purpose
                         : undefined;
                     if (purpose) {
-                        logger$15.debug('received_admission_grant', { purpose });
+                        logger$16.debug('received_admission_grant', { purpose });
                     }
                 }
             };
             const handleFailure = async (error) => {
-                logger$15.error('root_admission_failed_permanently', {
+                logger$16.error('root_admission_failed_permanently', {
                     error: error.message,
                 });
             };
@@ -23364,10 +23366,10 @@
                         this.readyEvent.set();
                     }
                     if (this.hadSuccessfulAdmission) {
-                        logger$15.debug('root_admission_refreshed');
+                        logger$16.debug('root_admission_refreshed');
                     }
                     else {
-                        logger$15.debug('root_admission_completed');
+                        logger$16.debug('root_admission_completed');
                     }
                     this.hadSuccessfulAdmission = true;
                     delay = RootSessionManager.BACKOFF_INITIAL;
@@ -23376,7 +23378,7 @@
                         await this.startExpiryGuard(welcomeFrame);
                         const expiryTriggered = await this.waitForExpiryOrStop();
                         if (expiryTriggered && !this.stopEvent.isSet()) {
-                            logger$15.debug('performing_scheduled_re_admission');
+                            logger$16.debug('performing_scheduled_re_admission');
                             continue;
                         }
                     }
@@ -23388,7 +23390,7 @@
                     }
                     const errorObject = error instanceof Error ? error : new Error(String(error));
                     const willRetry = attempts < RootSessionManager.RETRY_MAX_ATTEMPTS;
-                    logger$15.warning('root_admission_failed', {
+                    logger$16.warning('root_admission_failed', {
                         error: errorObject.message,
                         attempt: attempts,
                         will_retry: willRetry,
@@ -23406,7 +23408,7 @@
                 }
             }
             if (attempts >= RootSessionManager.RETRY_MAX_ATTEMPTS) {
-                logger$15.error('root_admission_max_attempts_exceeded', {
+                logger$16.error('root_admission_max_attempts_exceeded', {
                     max_attempts: RootSessionManager.RETRY_MAX_ATTEMPTS,
                 });
             }
@@ -23483,7 +23485,7 @@
         }
         async expiryGuard(welcomeFrame, signal) {
             if (!welcomeFrame.expiresAt) {
-                logger$15.debug('no_admission_expiry_configured');
+                logger$16.debug('no_admission_expiry_configured');
                 await Promise.race([this.stopEvent.wait(), this.waitForAbort(signal)]);
                 return;
             }
@@ -23492,7 +23494,7 @@
             let delaySeconds = (expiresAt.getTime() - now.getTime()) / 1000 -
                 RootSessionManager.JWT_REFRESH_SAFETY;
             delaySeconds = Math.max(delaySeconds, 0);
-            logger$15.debug('admission_expiry_guard_started', {
+            logger$16.debug('admission_expiry_guard_started', {
                 welcome_expires_at: expiresAt.toISOString(),
                 delay_seconds: delaySeconds,
                 refresh_safety_seconds: RootSessionManager.JWT_REFRESH_SAFETY,
@@ -23501,7 +23503,7 @@
             if (this.stopEvent.isSet() || signal?.aborted) {
                 return;
             }
-            logger$15.debug('admission_expiry_triggered_refresh', {
+            logger$16.debug('admission_expiry_triggered_refresh', {
                 expires_at: expiresAt.toISOString(),
                 current_time: new Date().toISOString(),
                 seconds_before_expiry: RootSessionManager.JWT_REFRESH_SAFETY,
@@ -23516,7 +23518,7 @@
                     return;
                 }
                 const errorObject = error instanceof Error ? error : new Error(String(error));
-                logger$15.debug('background_task_error', {
+                logger$16.debug('background_task_error', {
                     task_name: task.name,
                     error: errorObject.message,
                 });
@@ -23557,7 +23559,7 @@
      * Concrete implementations must define supported grant types and provide grant-to-connector
      * conversion logic.
      */
-    const logger$14 = getLogger('naylence.fame.connector.connector_factory');
+    const logger$15 = getLogger('naylence.fame.connector.connector_factory');
     const CONNECTOR_FACTORY_BASE_TYPE = 'ConnectorFactory';
     /**
      * Abstract base class for connector factories
@@ -23593,7 +23595,7 @@
                     }
                 }
                 catch (error) {
-                    logger$14.warning(`Failed to evaluate grant with factory ${factoryInfo.constructor.name}: ${error}`);
+                    logger$15.warning(`Failed to evaluate grant with factory ${factoryInfo.constructor.name}: ${error}`);
                     continue;
                 }
             }
@@ -23636,7 +23638,7 @@
                     }
                 }
                 catch (error) {
-                    logger$14.warning(`Failed to create connector config from grant: ${error}`);
+                    logger$15.warning(`Failed to create connector config from grant: ${error}`);
                     continue;
                 }
             }
@@ -23703,20 +23705,20 @@
                 return existing;
             }
             if (existing && !this.isGrantAware(existing)) {
-                logger$14.warning(`Factory ${factoryInfo.constructor.name} is registered under ${CONNECTOR_FACTORY_BASE_TYPE} but is missing grant conversion APIs; skipping.`);
+                logger$15.warning(`Factory ${factoryInfo.constructor.name} is registered under ${CONNECTOR_FACTORY_BASE_TYPE} but is missing grant conversion APIs; skipping.`);
                 return null;
             }
             try {
                 const instance = new factoryInfo.constructor();
                 if (!this.isGrantAware(instance)) {
-                    logger$14.warning(`Factory ${factoryInfo.constructor.name} does not implement grant conversion APIs required by ${CONNECTOR_FACTORY_BASE_TYPE}; skipping.`);
+                    logger$15.warning(`Factory ${factoryInfo.constructor.name} does not implement grant conversion APIs required by ${CONNECTOR_FACTORY_BASE_TYPE}; skipping.`);
                     return null;
                 }
                 factoryInfo.instance = instance;
                 return instance;
             }
             catch (error) {
-                logger$14.warning(`Failed to instantiate factory ${factoryInfo.constructor.name} while resolving grant conversion APIs: ${error}`);
+                logger$15.warning(`Failed to instantiate factory ${factoryInfo.constructor.name} while resolving grant conversion APIs: ${error}`);
                 return null;
             }
         }
@@ -23819,7 +23821,7 @@
             this.name = 'TaskCancellationError';
         }
     }
-    const logger$13 = getLogger('naylence.fame.connector.base_async_connector');
+    const logger$14 = getLogger('naylence.fame.connector.base_async_connector');
     // Environment variables
     const ENV_VAR_FAME_FLOW_CONTROL = 'FAME_FLOW_CONTROL';
     const FLOW_CONTROL_ENABLED = typeof process !== 'undefined' && process?.env
@@ -23902,7 +23904,7 @@
             if (this._state !== newState) {
                 const oldState = this._state;
                 this._state = newState;
-                logger$13.debug('connector_state_transition', {
+                logger$14.debug('connector_state_transition', {
                     connector_id: this._connectorFlowId,
                     old_state: oldState,
                     new_state: newState,
@@ -23941,12 +23943,12 @@
          * Stop the connector gracefully
          */
         async stop() {
-            logger$13.debug('stopping_connector', {
+            logger$14.debug('stopping_connector', {
                 current_state: this._state,
                 connector_id: this._connectorFlowId,
             });
             if (!ConnectorStateUtils.canStop(this._state)) {
-                logger$13.debug('connector_stop_already_stopped', {
+                logger$14.debug('connector_stop_already_stopped', {
                     current_state: this._state,
                     connector_id: this._connectorFlowId,
                 });
@@ -23957,7 +23959,7 @@
             if (this._lastError) {
                 throw this._lastError;
             }
-            logger$13.debug('connector_stopped', {
+            logger$14.debug('connector_stopped', {
                 current_state: this._state,
                 connector_id: this._connectorFlowId,
             });
@@ -23966,19 +23968,19 @@
          * Pause the connector (suspends heartbeat and housekeeping, but keeps connection alive)
          */
         async pause() {
-            logger$13.debug('pausing_connector', {
+            logger$14.debug('pausing_connector', {
                 current_state: this._state,
                 connector_id: this._connectorFlowId,
             });
             if (this._state !== ConnectorState.STARTED) {
-                logger$13.debug('connector_pause_invalid_state', {
+                logger$14.debug('connector_pause_invalid_state', {
                     current_state: this._state,
                     connector_id: this._connectorFlowId,
                 });
                 return;
             }
             this._setState(ConnectorState.PAUSED);
-            logger$13.debug('connector_paused', {
+            logger$14.debug('connector_paused', {
                 current_state: this._state,
                 connector_id: this._connectorFlowId,
             });
@@ -23987,19 +23989,19 @@
          * Resume the connector from paused state
          */
         async resume() {
-            logger$13.debug('resuming_connector', {
+            logger$14.debug('resuming_connector', {
                 current_state: this._state,
                 connector_id: this._connectorFlowId,
             });
             if (this._state !== ConnectorState.PAUSED) {
-                logger$13.debug('connector_resume_invalid_state', {
+                logger$14.debug('connector_resume_invalid_state', {
                     current_state: this._state,
                     connector_id: this._connectorFlowId,
                 });
                 return;
             }
             this._setState(ConnectorState.STARTED);
-            logger$13.debug('connector_resumed', {
+            logger$14.debug('connector_resumed', {
                 current_state: this._state,
                 connector_id: this._connectorFlowId,
             });
@@ -24009,7 +24011,7 @@
          */
         async close(code = 1000, reason = 'normal closure') {
             if (!ConnectorStateUtils.canClose(this._state)) {
-                logger$13.warning('connector_close_invalid_state', {
+                logger$14.warning('connector_close_invalid_state', {
                     current_state: this._state,
                     connector_id: this._connectorFlowId,
                 });
@@ -24090,7 +24092,7 @@
             // Add to queue and notify send loop
             this._sendQueue.push(raw);
             // Log for debugging
-            logger$13.debug('send_envelope_queued', {
+            logger$14.debug('send_envelope_queued', {
                 queue_length: this._sendQueue.length,
                 max_queue_size: this._maxQueueSize,
             });
@@ -24139,14 +24141,14 @@
                     const item = this._sendQueue[0];
                     if (!item)
                         continue;
-                    logger$13.debug('send_loop_processing_item', {
+                    logger$14.debug('send_loop_processing_item', {
                         queue_length_before_send: this._sendQueue.length,
                     });
                     // Send through transport (this may block)
                     await this._transportSendBytes(item);
                     // Only remove from queue after successful send
                     this._sendQueue.shift();
-                    logger$13.debug('send_loop_item_sent', {
+                    logger$14.debug('send_loop_item_sent', {
                         queue_length_after_send: this._sendQueue.length,
                     });
                 }
@@ -24159,14 +24161,14 @@
                 }
                 else if (error instanceof TaskCancellationError) {
                     // Task cancellation is expected during shutdown - log as debug, not critical
-                    logger$13.debug('send loop cancelled', {
+                    logger$14.debug('send loop cancelled', {
                         connector: this.constructor.name,
                         reason: error.message,
                     });
                     // Don't re-throw - this is normal during shutdown
                 }
                 else {
-                    logger$13.critical('unexpected exception in send loop', {
+                    logger$14.critical('unexpected exception in send loop', {
                         connector: this.constructor.name,
                         error: error instanceof Error ? error.message : String(error),
                     });
@@ -24207,7 +24209,7 @@
                             env = JSON.parse(jsonStr);
                         }
                         catch (error) {
-                            logger$13.error('Invalid envelope', {
+                            logger$14.error('Invalid envelope', {
                                 message: message.toString(),
                                 error: error instanceof Error ? error.message : String(error),
                             });
@@ -24231,7 +24233,7 @@
                     };
                     await withEnvelopeContextAsync(envelopeContext, async () => {
                         const prettyEnvelope = prettyModel$1(env);
-                        logger$13.trace('connector_received_envelope', {
+                        logger$14.trace('connector_received_envelope', {
                             envelope: env,
                             pretty: prettyEnvelope,
                         });
@@ -24260,7 +24262,7 @@
                             if (error instanceof TaskCancellationError) {
                                 throw error;
                             }
-                            logger$13.error('handler_failed', {
+                            logger$14.error('handler_failed', {
                                 error: error instanceof Error ? error.message : String(error),
                                 envelope_id: env.id ?? null,
                                 trace_id: env.traceId ?? null,
@@ -24281,14 +24283,14 @@
                 }
                 else if (error instanceof TaskCancellationError) {
                     // Task cancellation is expected during shutdown - log as debug, not critical
-                    logger$13.debug('receive loop cancelled', {
+                    logger$14.debug('receive loop cancelled', {
                         connector: this.constructor.name,
                         reason: error.message,
                     });
                     // Don't re-throw - this is normal during shutdown
                 }
                 else {
-                    logger$13.critical('unexpected_error_in recv_loop', {
+                    logger$14.critical('unexpected_error_in recv_loop', {
                         error: error instanceof Error ? error.message : String(error),
                     });
                     throw error;
@@ -24304,7 +24306,7 @@
         async _maybeEmitCredit(flowId, traceId) {
             const remainingCredits = this._flowCtrl.getCredits(flowId);
             const needsRefill = this._flowCtrl.needsRefill(flowId);
-            logger$13.debug('maybe_emit_credit_check', {
+            logger$14.debug('maybe_emit_credit_check', {
                 connector_id: this._connectorFlowId,
                 flow_id: flowId,
                 trace_id: traceId ?? null,
@@ -24320,7 +24322,7 @@
             }
             const delta = this._initialWindow;
             this._flowCtrl.addCredits(flowId, delta);
-            logger$13.debug('maybe_emit_credit_emit', {
+            logger$14.debug('maybe_emit_credit_emit', {
                 connector_id: this._connectorFlowId,
                 flow_id: flowId,
                 trace_id: traceId ?? null,
@@ -24340,7 +24342,7 @@
             });
             try {
                 await this.send(ackEnv);
-                logger$13.debug('maybe_emit_credit_sent', {
+                logger$14.debug('maybe_emit_credit_sent', {
                     connector_id: this._connectorFlowId,
                     flow_id: flowId,
                     trace_id: traceId ?? null,
@@ -24348,7 +24350,7 @@
                 });
             }
             catch (error) {
-                logger$13.error('maybe_emit_credit_send_failed', {
+                logger$14.error('maybe_emit_credit_send_failed', {
                     connector_id: this._connectorFlowId,
                     flow_id: flowId,
                     trace_id: traceId ?? null,
@@ -24373,13 +24375,13 @@
          */
         async _shutdown(code, reason, gracePeriod, exc) {
             if (this._closed) {
-                logger$13.debug('shutdown_already_closed', {
+                logger$14.debug('shutdown_already_closed', {
                     connector_id: this._connectorFlowId,
                     current_state: this._state,
                 });
                 return;
             }
-            logger$13.debug('connector_shutdown_starting', {
+            logger$14.debug('connector_shutdown_starting', {
                 connector_id: this._connectorFlowId,
                 connector_type: this.constructor.name,
                 code,
@@ -24409,19 +24411,19 @@
                 this._sendPromiseResolve = undefined;
             }
             // Close transport
-            logger$13.debug('connector_closing_transport', {
+            logger$14.debug('connector_closing_transport', {
                 connector_id: this._connectorFlowId,
                 connector_type: this.constructor.name,
                 timestamp: new Date().toISOString(),
             });
             await this._transportClose(code, reason);
-            logger$13.debug('connector_transport_closed', {
+            logger$14.debug('connector_transport_closed', {
                 connector_id: this._connectorFlowId,
                 connector_type: this.constructor.name,
                 timestamp: new Date().toISOString(),
             });
             // Shutdown spawned tasks
-            logger$13.debug('connector_shutting_down_tasks', {
+            logger$14.debug('connector_shutting_down_tasks', {
                 connector_id: this._connectorFlowId,
                 connector_type: this.constructor.name,
                 grace_period_ms: effectiveGracePeriod * 1000,
@@ -24433,14 +24435,14 @@
                     gracePeriod: effectiveGracePeriod * 1000, // Convert to milliseconds
                     joinTimeout: this._shutdownJoinTimeout,
                 });
-                logger$13.debug('connector_tasks_shutdown_complete', {
+                logger$14.debug('connector_tasks_shutdown_complete', {
                     connector_id: this._connectorFlowId,
                     connector_type: this.constructor.name,
                     timestamp: new Date().toISOString(),
                 });
             }
             catch (error) {
-                logger$13.warning('task_shutdown_error', {
+                logger$14.warning('task_shutdown_error', {
                     connector_id: this._connectorFlowId,
                     error: error instanceof Error ? error.message : String(error),
                 });
@@ -24453,7 +24455,7 @@
             if (this._closeResolver) {
                 this._closeResolver();
             }
-            logger$13.debug('connector_shutdown_complete', {
+            logger$14.debug('connector_shutdown_complete', {
                 connector_id: this._connectorFlowId,
                 connector_type: this.constructor.name,
                 final_state: this._state,
@@ -24529,7 +24531,7 @@
         }
     }
 
-    const logger$12 = getLogger('naylence.fame.connector.broadcast_channel_connector');
+    const logger$13 = getLogger('naylence.fame.connector.broadcast_channel_connector');
     const BROADCAST_CHANNEL_CONNECTOR_TYPE = 'broadcast-channel-connector';
     const DEFAULT_CHANNEL$7 = 'naylence-fabric';
     const DEFAULT_INBOX_CAPACITY$7 = 2048;
@@ -24618,7 +24620,7 @@
             this.localNodeId = normalizedLocalNodeId;
             this.targetNodeId = BroadcastChannelConnector.normalizeTargetNodeId(config.initialTargetNodeId);
             this.channel = new BroadcastChannel(this.channelName);
-            logger$12.debug('broadcast_channel_connector_created', {
+            logger$13.debug('broadcast_channel_connector_created', {
                 channel: this.channelName,
                 connector_id: this.connectorId,
                 local_node_id: this.localNodeId,
@@ -24630,7 +24632,7 @@
             this.onMsg = (event) => {
                 // Guard: Don't process if listener was unregistered
                 if (!this.listenerRegistered) {
-                    logger$12.warning('broadcast_channel_message_after_unregister', {
+                    logger$13.warning('broadcast_channel_message_after_unregister', {
                         channel: this.channelName,
                         connector_id: this.connectorId,
                         timestamp: new Date().toISOString(),
@@ -24638,7 +24640,7 @@
                     return;
                 }
                 const message = event.data;
-                logger$12.debug('broadcast_channel_raw_event', {
+                logger$13.debug('broadcast_channel_raw_event', {
                     channel: this.channelName,
                     connector_id: this.connectorId,
                     message_type: message && typeof message === 'object'
@@ -24654,7 +24656,7 @@
                 const busMessage = message;
                 const senderNodeId = BroadcastChannelConnector.normalizeNodeId(busMessage.senderNodeId);
                 if (!senderNodeId) {
-                    logger$12.debug('broadcast_channel_message_rejected', {
+                    logger$13.debug('broadcast_channel_message_rejected', {
                         channel: this.channelName,
                         connector_id: this.connectorId,
                         reason: 'missing_sender_node_id',
@@ -24662,7 +24664,7 @@
                     return;
                 }
                 if (senderNodeId === this.localNodeId) {
-                    logger$12.debug('broadcast_channel_message_rejected', {
+                    logger$13.debug('broadcast_channel_message_rejected', {
                         channel: this.channelName,
                         connector_id: this.connectorId,
                         reason: 'self_echo',
@@ -24676,14 +24678,14 @@
                 }
                 const payload = BroadcastChannelConnector.coercePayload(busMessage.payload);
                 if (!payload) {
-                    logger$12.debug('broadcast_channel_payload_rejected', {
+                    logger$13.debug('broadcast_channel_payload_rejected', {
                         channel: this.channelName,
                         connector_id: this.connectorId,
                         reason: 'unrecognized_payload_type',
                     });
                     return;
                 }
-                logger$12.debug('broadcast_channel_message_received', {
+                logger$13.debug('broadcast_channel_message_received', {
                     channel: this.channelName,
                     sender_id: message?.senderId,
                     sender_node_id: senderNodeId,
@@ -24712,14 +24714,14 @@
                 }
                 catch (error) {
                     if (error instanceof QueueFullError) {
-                        logger$12.warning('broadcast_channel_receive_queue_full', {
+                        logger$13.warning('broadcast_channel_receive_queue_full', {
                             channel: this.channelName,
                             inbox_capacity: this.inboxCapacity,
                             inbox_remaining_capacity: this.inbox.remainingCapacity,
                         });
                     }
                     else {
-                        logger$12.error('broadcast_channel_receive_error', {
+                        logger$13.error('broadcast_channel_receive_error', {
                             channel: this.channelName,
                             error: error instanceof Error ? error.message : String(error),
                         });
@@ -24733,7 +24735,7 @@
             // Setup visibility change monitoring
             this.visibilityChangeHandler = () => {
                 const isHidden = document.hidden;
-                logger$12.debug('broadcast_channel_visibility_changed', {
+                logger$13.debug('broadcast_channel_visibility_changed', {
                     channel: this.channelName,
                     connector_id: this.connectorId,
                     visibility: isHidden ? 'hidden' : 'visible',
@@ -24742,7 +24744,7 @@
                 // Pause/resume connector based on visibility
                 if (isHidden && this.state === ConnectorState.STARTED) {
                     this.pause().catch((err) => {
-                        logger$12.warning('broadcast_channel_pause_failed', {
+                        logger$13.warning('broadcast_channel_pause_failed', {
                             channel: this.channelName,
                             connector_id: this.connectorId,
                             error: err instanceof Error ? err.message : String(err),
@@ -24751,7 +24753,7 @@
                 }
                 else if (!isHidden && this.state === ConnectorState.PAUSED) {
                     this.resume().catch((err) => {
-                        logger$12.warning('broadcast_channel_resume_failed', {
+                        logger$13.warning('broadcast_channel_resume_failed', {
                             channel: this.channelName,
                             connector_id: this.connectorId,
                             error: err instanceof Error ? err.message : String(err),
@@ -24765,7 +24767,7 @@
                 // Track page lifecycle events to detect browser unload/discard
                 if (typeof window !== 'undefined') {
                     const lifecycleLogger = (event) => {
-                        logger$12.debug('broadcast_channel_page_lifecycle', {
+                        logger$13.debug('broadcast_channel_page_lifecycle', {
                             channel: this.channelName,
                             connector_id: this.connectorId,
                             event_type: event.type,
@@ -24781,7 +24783,7 @@
                     document.addEventListener('resume', lifecycleLogger);
                 }
                 // Log initial state with detailed visibility info
-                logger$12.debug('broadcast_channel_initial_visibility', {
+                logger$13.debug('broadcast_channel_initial_visibility', {
                     channel: this.channelName,
                     connector_id: this.connectorId,
                     visibility: document.hidden ? 'hidden' : 'visible',
@@ -24813,14 +24815,14 @@
             }
             catch (error) {
                 if (error instanceof QueueFullError) {
-                    logger$12.warning('broadcast_channel_push_queue_full', {
+                    logger$13.warning('broadcast_channel_push_queue_full', {
                         channel: this.channelName,
                         inbox_capacity: this.inboxCapacity,
                         inbox_remaining_capacity: this.inbox.remainingCapacity,
                     });
                     throw error;
                 }
-                logger$12.error('broadcast_channel_push_failed', {
+                logger$13.error('broadcast_channel_push_failed', {
                     channel: this.channelName,
                     error: error instanceof Error ? error.message : String(error),
                 });
@@ -24830,7 +24832,7 @@
         async _transportSendBytes(data) {
             ensureBroadcastEnvironment();
             const targetNodeId = this.targetNodeId ?? '*';
-            logger$12.debug('broadcast_channel_message_sending', {
+            logger$13.debug('broadcast_channel_message_sending', {
                 channel: this.channelName,
                 sender_id: this.connectorId,
                 sender_node_id: this.localNodeId,
@@ -24851,7 +24853,7 @@
             return item;
         }
         async _transportClose(code, reason) {
-            logger$12.debug('broadcast_channel_transport_closing', {
+            logger$13.debug('broadcast_channel_transport_closing', {
                 channel: this.channelName,
                 connector_id: this.connectorId,
                 code,
@@ -24860,14 +24862,14 @@
                 timestamp: new Date().toISOString(),
             });
             if (this.listenerRegistered) {
-                logger$12.debug('broadcast_channel_removing_listener', {
+                logger$13.debug('broadcast_channel_removing_listener', {
                     channel: this.channelName,
                     connector_id: this.connectorId,
                     timestamp: new Date().toISOString(),
                 });
                 this.channel.removeEventListener('message', this.onMsg);
                 this.listenerRegistered = false;
-                logger$12.debug('broadcast_channel_listener_removed', {
+                logger$13.debug('broadcast_channel_listener_removed', {
                     channel: this.channelName,
                     connector_id: this.connectorId,
                     timestamp: new Date().toISOString(),
@@ -24880,13 +24882,13 @@
                 this.visibilityChangeListenerRegistered = false;
                 this.visibilityChangeHandler = undefined;
             }
-            logger$12.debug('broadcast_channel_closing', {
+            logger$13.debug('broadcast_channel_closing', {
                 channel: this.channelName,
                 connector_id: this.connectorId,
                 timestamp: new Date().toISOString(),
             });
             this.channel.close();
-            logger$12.debug('broadcast_channel_closed', {
+            logger$13.debug('broadcast_channel_closed', {
                 channel: this.channelName,
                 connector_id: this.connectorId,
                 timestamp: new Date().toISOString(),
@@ -24910,7 +24912,7 @@
                 if (targetNodeId &&
                     targetNodeId !== '*' &&
                     targetNodeId !== this.localNodeId) {
-                    logger$12.debug('broadcast_channel_message_rejected', {
+                    logger$13.debug('broadcast_channel_message_rejected', {
                         channel: this.channelName,
                         connector_id: this.connectorId,
                         reason: 'wildcard_target_mismatch',
@@ -24926,7 +24928,7 @@
             if (expectedSender &&
                 expectedSender !== '*' &&
                 senderNodeId !== expectedSender) {
-                logger$12.debug('broadcast_channel_message_rejected', {
+                logger$13.debug('broadcast_channel_message_rejected', {
                     channel: this.channelName,
                     connector_id: this.connectorId,
                     reason: 'unexpected_sender',
@@ -24939,7 +24941,7 @@
             if (targetNodeId &&
                 targetNodeId !== '*' &&
                 targetNodeId !== this.localNodeId) {
-                logger$12.debug('broadcast_channel_message_rejected', {
+                logger$13.debug('broadcast_channel_message_rejected', {
                     channel: this.channelName,
                     connector_id: this.connectorId,
                     reason: 'unexpected_target',
@@ -24964,7 +24966,7 @@
             return 'unknown';
         }
         logInboxSnapshot(event, extra = {}) {
-            logger$12.debug(event, {
+            logger$13.debug(event, {
                 channel: this.channelName,
                 connector_id: this.connectorId,
                 connector_state: this.state,
@@ -24980,7 +24982,7 @@
             await super.start(inboundHandler);
             // After transitioning to STARTED, check if tab is already hidden
             if (typeof document !== 'undefined' && document.hidden) {
-                logger$12.debug('broadcast_channel_start_in_hidden_tab', {
+                logger$13.debug('broadcast_channel_start_in_hidden_tab', {
                     channel: this.channelName,
                     connector_id: this.connectorId,
                     document_hidden: document.hidden,
@@ -24990,7 +24992,7 @@
                 });
                 // Immediately pause if tab is hidden at start time
                 await this.pause().catch((err) => {
-                    logger$12.warning('broadcast_channel_initial_pause_failed', {
+                    logger$13.warning('broadcast_channel_initial_pause_failed', {
                         channel: this.channelName,
                         connector_id: this.connectorId,
                         error: err instanceof Error ? err.message : String(err),
@@ -25008,7 +25010,7 @@
                 return;
             }
             this.targetNodeId = normalized;
-            logger$12.debug('broadcast_channel_target_updated', {
+            logger$13.debug('broadcast_channel_target_updated', {
                 channel: this.channelName,
                 connector_id: this.connectorId,
                 local_node_id: this.localNodeId,
@@ -25018,7 +25020,7 @@
         }
         setWildcardTarget() {
             this.targetNodeId = '*';
-            logger$12.debug('broadcast_channel_target_updated', {
+            logger$13.debug('broadcast_channel_target_updated', {
                 channel: this.channelName,
                 connector_id: this.connectorId,
                 local_node_id: this.localNodeId,
@@ -25164,7 +25166,7 @@
         return config;
     }
 
-    const logger$11 = getLogger('naylence.fame.node.upstream_session_manager');
+    const logger$12 = getLogger('naylence.fame.node.upstream_session_manager');
     function isPlainRecord$4(value) {
         if (typeof value !== 'object' || value === null) {
             return false;
@@ -25237,6 +25239,7 @@
         const onEpochChangeValue = pickOption$2(record, 'onEpochChange', 'on_epoch_change');
         const onEpochChange = typeof onEpochChangeValue === 'function' ? onEpochChangeValue : undefined;
         const admissionClient = pickOption$2(record, 'admissionClient', 'admission_client');
+        const retryPolicy = pickOption$2(record, 'retryPolicy', 'retry_policy');
         return {
             node,
             attachClient,
@@ -25248,6 +25251,7 @@
             onAttach: validatedOnAttach,
             onEpochChange,
             admissionClient: admissionClient ?? undefined,
+            retryPolicy: retryPolicy ?? undefined,
         };
     }
     class UpstreamSessionManager extends TaskSpawner {
@@ -25267,6 +25271,7 @@
             this.hadSuccessfulAttach = false;
             this.lastConnectorState = null;
             this.connectEpoch = 0;
+            this.initialAttempts = 0;
             this._visibilityHandler = null;
             const options = normalizeOptions$k(optionsInput);
             this.node = options.node;
@@ -25280,31 +25285,34 @@
             this.admissionClient =
                 options.admissionClient ?? options.node.admissionClient;
             this.wrappedHandler = this.makeHeartbeatEnabledHandler(options.inboundHandler);
-            logger$11.debug('created_upstream_session_manager', {
+            // Store the connection retry policy (can be null, in which case default behavior applies)
+            this.connectionRetryPolicy = options.retryPolicy ?? null;
+            logger$12.debug('created_upstream_session_manager', {
                 target_system_id: this.targetSystemId,
+                has_retry_policy: this.connectionRetryPolicy !== null,
             });
         }
         get systemId() {
             return this.targetSystemId;
         }
         setupVisibilityListener() {
-            logger$11.debug('setup_visibility_listener_called', {
+            logger$12.debug('setup_visibility_listener_called', {
                 has_document: typeof document !== 'undefined',
             });
             if (typeof document !== 'undefined' && document.addEventListener) {
                 this._visibilityHandler = () => {
-                    logger$11.debug('visibility_change_event_fired', {
+                    logger$12.debug('visibility_change_event_fired', {
                         state: document.visibilityState,
                     });
                     if (document.visibilityState === 'visible') {
-                        logger$11.debug('visibility_change_detected_waking_up');
+                        logger$12.debug('visibility_change_detected_waking_up');
                         this.wakeEvent.set();
                     }
                 };
                 document.addEventListener('visibilitychange', this._visibilityHandler);
             }
             else {
-                logger$11.debug('setup_visibility_listener_skipped_no_document');
+                logger$12.debug('setup_visibility_listener_skipped_no_document');
             }
         }
         teardownVisibilityListener() {
@@ -25337,13 +25345,13 @@
                 }
                 throw new FameConnectError('Upstream session manager failed to attach');
             }
-            logger$11.debug('upstream_session_manager_started');
+            logger$12.debug('upstream_session_manager_started');
         }
         getActiveConnector() {
             return this.connector;
         }
         async stop() {
-            logger$11.debug('upstream_session_manager_stopping');
+            logger$12.debug('upstream_session_manager_stopping');
             this.teardownVisibilityListener();
             this.stopEvent.set();
             this.currentStopSubtasks?.set();
@@ -25354,7 +25362,7 @@
                 }
                 catch (error) {
                     if (!(error instanceof TaskCancelledError)) {
-                        logger$11.debug('fsm_task_stopped_with_error', {
+                        logger$12.debug('fsm_task_stopped_with_error', {
                             error: error.message,
                         });
                     }
@@ -25363,13 +25371,13 @@
             }
             if (this.connector) {
                 await this.connector.stop().catch((error) => {
-                    logger$11.debug('connector_stop_error', {
+                    logger$12.debug('connector_stop_error', {
                         error: error.message,
                     });
                 });
                 this.connector = null;
             }
-            logger$11.debug('upstream_session_manager_stopped');
+            logger$12.debug('upstream_session_manager_stopped');
         }
         async send(envelope) {
             if (this.messageQueue.length >= UpstreamSessionManager.TX_QUEUE_MAX) {
@@ -25397,11 +25405,14 @@
         }
         async fsmLoop() {
             let delay = UpstreamSessionManager.BACKOFF_INITIAL;
+            this.initialAttempts = 0;
             while (!this.stopEvent.isSet()) {
                 const startTime = Date.now();
+                this.initialAttempts += 1;
                 try {
                     await this.connectCycle();
                     delay = UpstreamSessionManager.BACKOFF_INITIAL;
+                    this.initialAttempts = 0; // Reset on success
                 }
                 catch (error) {
                     // Reset backoff if the connection was alive for more than 10 seconds
@@ -25411,32 +25422,38 @@
                     if (error instanceof TaskCancelledError) {
                         throw error;
                     }
+                    // Determine if we should fail-fast or retry
+                    const shouldFailFast = this.shouldFailFastOnError(error);
                     if (error instanceof FameTransportClose ||
                         error instanceof FameConnectError) {
-                        logger$11.warning('upstream_link_closed', {
+                        logger$12.warning('upstream_link_closed', {
                             error: error.message,
-                            will_retry: true,
+                            will_retry: !shouldFailFast,
+                            attempt: this.initialAttempts,
+                            has_retry_policy: this.connectionRetryPolicy !== null,
                         });
-                        if (!this.hadSuccessfulAttach && error instanceof FameConnectError) {
+                        if (shouldFailFast && error instanceof FameConnectError) {
                             throw error;
                         }
                     }
                     else {
                         const err = error;
                         if (err.name === 'OAuth2PkceRedirectInitiatedError') {
-                            logger$11.info('upstream_link_redirecting', {
+                            logger$12.info('upstream_link_redirecting', {
                                 error: err.message,
                                 will_retry: true,
                             });
                         }
                         else {
-                            logger$11.warning('upstream_link_closed', {
+                            logger$12.warning('upstream_link_closed', {
                                 error: err.message,
-                                will_retry: true,
+                                will_retry: !shouldFailFast,
+                                attempt: this.initialAttempts,
+                                has_retry_policy: this.connectionRetryPolicy !== null,
                                 exc_info: true,
                             });
                         }
-                        if (!this.hadSuccessfulAttach) {
+                        if (shouldFailFast) {
                             throw error;
                         }
                     }
@@ -25444,52 +25461,77 @@
                 }
             }
         }
+        /**
+         * Determine whether to fail immediately or continue retrying.
+         * Returns true if we should throw the error instead of retrying.
+         */
+        shouldFailFastOnError(error) {
+            // If no policy is configured, use legacy behavior (fail-fast after first attempt)
+            if (!this.connectionRetryPolicy) {
+                // After first successful attach, always retry (existing behavior)
+                if (this.hadSuccessfulAttach) {
+                    return false;
+                }
+                // Without a policy, fail on first error
+                return true;
+            }
+            // Delegate decision to the policy
+            const shouldRetry = this.connectionRetryPolicy.shouldRetry({
+                hadSuccessfulAttach: this.hadSuccessfulAttach,
+                attemptNumber: this.initialAttempts,
+                error,
+            });
+            return !shouldRetry;
+        }
         async applyBackoff(delay) {
             const jitter = Math.random() * delay;
-            await this.sleepWithStop(delay + jitter);
+            const wasWoken = await this.sleepWithStop(delay + jitter);
+            // If sleep was interrupted by visibility change (user returned to tab),
+            // reset backoff to initial delay for immediate retry with fresh backoff
+            if (wasWoken) {
+                logger$12.debug('backoff_reset_on_visibility_change', {
+                    previous_delay: delay,
+                    new_delay: UpstreamSessionManager.BACKOFF_INITIAL,
+                });
+                return UpstreamSessionManager.BACKOFF_INITIAL;
+            }
             return Math.min(delay * 2, UpstreamSessionManager.BACKOFF_CAP);
         }
+        /**
+         * Sleep for the specified duration, but can be interrupted by stop or wake events.
+         * @returns true if interrupted by wake event (e.g., visibility change), false otherwise
+         */
         async sleepWithStop(delaySeconds) {
             if (delaySeconds <= 0) {
-                return;
-            }
-            // If the document is visible, cap the backoff delay to improve UX
-            // This ensures that if the user is watching, we retry quickly (e.g. 1s)
-            // instead of waiting for the full exponential backoff (up to 30s).
-            let effectiveDelay = delaySeconds;
-            if (typeof document !== 'undefined' &&
-                document.visibilityState === 'visible') {
-                effectiveDelay = Math.min(delaySeconds, 1.0);
-                if (effectiveDelay < delaySeconds) {
-                    logger$11.debug('sleep_reduced_document_visible', {
-                        original: delaySeconds,
-                        new: effectiveDelay,
-                    });
-                }
+                return false;
             }
+            // Check if wake event is already set (e.g., visibility just changed)
             if (this.wakeEvent.isSet()) {
                 this.wakeEvent.clear();
-                return;
+                logger$12.debug('sleep_skipped_wake_event_pending');
+                return true;
             }
             let timeout;
             const sleepPromise = new Promise((resolve) => {
                 timeout = setTimeout(() => {
                     timeout = undefined;
                     resolve();
-                }, effectiveDelay * 1000);
+                }, delaySeconds * 1000);
             });
             await Promise.race([
                 sleepPromise,
                 this.stopEvent.wait(),
                 this.wakeEvent.wait(),
             ]);
-            if (this.wakeEvent.isSet()) {
-                logger$11.debug('sleep_interrupted_by_wake_event');
+            const wasWoken = this.wakeEvent.isSet();
+            if (wasWoken) {
+                logger$12.debug('sleep_interrupted_by_wake_event');
                 this.wakeEvent.clear();
             }
             if (timeout !== undefined) {
                 clearTimeout(timeout);
             }
+            return wasWoken;
         }
         getNodeAttachGrant(connectionGrants) {
             if (!connectionGrants) {
@@ -25546,7 +25588,7 @@
             await connector.start(this.wrappedHandler);
             this.connector = connector;
             const callbackGrants = this.node.gatherSupportedCallbackGrants();
-            logger$11.debug('callback_grants_before_augmentation', {
+            logger$12.debug('callback_grants_before_augmentation', {
                 count: callbackGrants.length,
                 types: callbackGrants.map((g) => g.type),
             });
@@ -25556,7 +25598,7 @@
             const broadcastCallbackGrant = shouldAddBroadcastGrant
                 ? this.createBroadcastCallbackGrant(grant)
                 : null;
-            logger$11.debug('broadcast_callback_grant_check', {
+            logger$12.debug('broadcast_callback_grant_check', {
                 should_add: shouldAddBroadcastGrant,
                 grant_created: !!broadcastCallbackGrant,
             });
@@ -25575,12 +25617,12 @@
                         const isDuplicate = callbackGrants.some((existing) => JSON.stringify(existing) === JSON.stringify(grant));
                         if (!isDuplicate) {
                             callbackGrants.push(grant);
-                            logger$11.debug('added_connection_grant_as_callback', {
+                            logger$12.debug('added_connection_grant_as_callback', {
                                 type: grant.type,
                             });
                         }
                         else {
-                            logger$11.debug('skipped_duplicate_connection_grant', {
+                            logger$12.debug('skipped_duplicate_connection_grant', {
                                 type: grant.type,
                             });
                         }
@@ -25592,12 +25634,12 @@
             if (broadcastCallbackGrant &&
                 this.shouldAdvertiseBroadcastGrant(grant, callbackGrants)) {
                 callbackGrants.push(broadcastCallbackGrant);
-                logger$11.debug('added_broadcast_callback_grant');
+                logger$12.debug('added_broadcast_callback_grant');
             }
             else if (broadcastCallbackGrant) {
-                logger$11.debug('skipped_duplicate_broadcast_callback_grant');
+                logger$12.debug('skipped_duplicate_broadcast_callback_grant');
             }
-            logger$11.debug('callback_grants_after_augmentation', {
+            logger$12.debug('callback_grants_after_augmentation', {
                 count: callbackGrants.length,
                 types: callbackGrants.map((g) => g.type),
             });
@@ -25610,7 +25652,7 @@
                         targetAware.setTargetNodeId(this.targetSystemId);
                     }
                     catch (error) {
-                        logger$11.warning('broadcast_channel_target_apply_failed', {
+                        logger$12.warning('broadcast_channel_target_apply_failed', {
                             error: error instanceof Error ? error.message : String(error),
                             target_node_id: this.targetSystemId,
                         });
@@ -25632,14 +25674,14 @@
                     });
                 }
                 else {
-                    logger$11.warning('parent_epoch_changed', { epoch });
+                    logger$12.warning('parent_epoch_changed', { epoch });
                 }
             }
             if (!this.readyEvent.isSet()) {
                 this.readyEvent.set();
             }
             if (this.messageQueue.length > 0) {
-                logger$11.debug('flushing_buffered_frames', {
+                logger$12.debug('flushing_buffered_frames', {
                     queue_size: this.messageQueue.length,
                 });
                 this.queueEvent.set();
@@ -25656,12 +25698,12 @@
                 name: `expiry-guard-${this.connectEpoch}`,
             });
             if (this.hadSuccessfulAttach) {
-                logger$11.debug('reconnected_to_upstream', {
+                logger$12.debug('reconnected_to_upstream', {
                     attach_expires_at: attachInfo.attachExpiresAt?.toISOString?.() ?? null,
                 });
             }
             else {
-                logger$11.debug('connected_to_upstream', {
+                logger$12.debug('connected_to_upstream', {
                     attach_expires_at: attachInfo.attachExpiresAt?.toISOString?.() ?? null,
                 });
             }
@@ -25679,18 +25721,18 @@
                 this.currentStopSubtasks = null;
                 await Promise.allSettled(tasks.map((task) => task.promise));
                 if (this.connector) {
-                    logger$11.debug('upstream_stopping_old_connector', {
+                    logger$12.debug('upstream_stopping_old_connector', {
                         connect_epoch: this.connectEpoch,
                         target_system_id: this.targetSystemId,
                         timestamp: new Date().toISOString(),
                     });
                     await this.connector.stop().catch((err) => {
-                        logger$11.warning('upstream_connector_stop_error', {
+                        logger$12.warning('upstream_connector_stop_error', {
                             connect_epoch: this.connectEpoch,
                             error: err instanceof Error ? err.message : String(err),
                         });
                     });
-                    logger$11.debug('upstream_old_connector_stopped', {
+                    logger$12.debug('upstream_old_connector_stopped', {
                         connect_epoch: this.connectEpoch,
                         target_system_id: this.targetSystemId,
                         timestamp: new Date().toISOString(),
@@ -25743,7 +25785,7 @@
                 });
             }
             catch (error) {
-                logger$11.debug('broadcast_callback_grant_generation_failed', {
+                logger$12.debug('broadcast_callback_grant_generation_failed', {
                     error: error instanceof Error ? error.message : String(error),
                 });
                 return null;
@@ -25798,7 +25840,7 @@
             }
         }
         async heartbeatLoop(connector, stopEvt, signal) {
-            logger$11.debug('starting_heartbeat_loop');
+            logger$12.debug('starting_heartbeat_loop');
             const intervalMs = UpstreamSessionManager.HEARTBEAT_INTERVAL * 1000;
             const graceMs = intervalMs * UpstreamSessionManager.HEARTBEAT_GRACE;
             this.lastHeartbeatAckTime = Date.now();
@@ -25834,7 +25876,7 @@
                 // Skip heartbeat if connector is paused (e.g., tab is hidden)
                 // Keep ack time current so we don't timeout immediately after resuming
                 if (currentState === ConnectorState.PAUSED) {
-                    logger$11.debug('skipping_heartbeat_connector_paused', {
+                    logger$12.debug('skipping_heartbeat_connector_paused', {
                         connector_state: currentState,
                     });
                     this.lastHeartbeatAckTime = Date.now();
@@ -25843,14 +25885,14 @@
                 // Reset ack time if just resumed from pause (prevents immediate timeout)
                 if (previousState === ConnectorState.PAUSED &&
                     currentState === ConnectorState.STARTED) {
-                    logger$11.debug('connector_just_resumed_resetting_ack_time', {
+                    logger$12.debug('connector_just_resumed_resetting_ack_time', {
                         previous_state: previousState,
                         current_state: currentState,
                     });
                     this.lastHeartbeatAckTime = Date.now();
                 }
                 const envelope = await this.makeHeartbeatEnvelope();
-                logger$11.debug('sending_heartbeat', {
+                logger$12.debug('sending_heartbeat', {
                     hb_corr_id: envelope.corrId,
                     hb_env_id: envelope.id,
                 });
@@ -25876,7 +25918,7 @@
                     throw new FameConnectError('missed heartbeat acknowledgement');
                 }
             }
-            logger$11.debug('completed_heartbeat_loop');
+            logger$12.debug('completed_heartbeat_loop');
         }
         async messagePumpLoop(connector, stopEvt, signal) {
             while (!stopEvt.isSet() && !signal?.aborted) {
@@ -25893,19 +25935,19 @@
                 if (!envelope) {
                     continue;
                 }
-                logger$11.debug('upstream_pump_sending_envelope', {
+                logger$12.debug('upstream_pump_sending_envelope', {
                     envelopeId: envelope.id,
                     type: envelope.frame?.type,
                 });
                 try {
                     await connector.send(envelope);
-                    logger$11.debug('upstream_pump_sent_envelope', {
+                    logger$12.debug('upstream_pump_sent_envelope', {
                         envelopeId: envelope.id,
                     });
                 }
                 catch (error) {
                     if (error instanceof FameMessageTooLarge) {
-                        logger$11.error('failed_to_send_message', { error: error.message });
+                        logger$12.error('failed_to_send_message', { error: error.message });
                         await this.handleMessageTooLarge(envelope, error.message);
                     }
                     else if (error instanceof FameTransportClose) {
@@ -25967,7 +26009,7 @@
                 await fabric.send(ackEnvelope);
             }
             catch (error) {
-                logger$11.warning('failed_to_send_nack', {
+                logger$12.warning('failed_to_send_nack', {
                     error: error.message,
                 });
             }
@@ -25981,7 +26023,7 @@
                 timestamps.push(info.attachExpiresAt);
             }
             if (!timestamps.length) {
-                logger$11.debug('no_ttl_expiry_configured');
+                logger$12.debug('no_ttl_expiry_configured');
                 await this.waitEvent(stopEvt, signal);
                 return;
             }
@@ -25990,7 +26032,7 @@
             let delaySeconds = (earliest.getTime() - now.getTime()) / 1000 -
                 UpstreamSessionManager.JWT_REFRESH_SAFETY;
             delaySeconds = Math.max(delaySeconds, UpstreamSessionManager.JWT_REFRESH_SAFETY);
-            logger$11.debug('ttl_expiry_guard_started', {
+            logger$12.debug('ttl_expiry_guard_started', {
                 welcome_expires_at: welcome.frame.expiresAt ?? null,
                 attach_expires_at: info.attachExpiresAt?.toISOString?.() ?? null,
                 earliest_expiry: earliest.toISOString(),
@@ -26018,7 +26060,7 @@
                 }
             }
             if (!stopEvt.isSet()) {
-                logger$11.debug('ttl_expiry_triggered_reconnect', {
+                logger$12.debug('ttl_expiry_triggered_reconnect', {
                     expires_at: earliest.toISOString(),
                     current_time: new Date().toISOString(),
                     seconds_before_expiry: UpstreamSessionManager.JWT_REFRESH_SAFETY,
@@ -26063,7 +26105,7 @@
                 }
                 await this.node.dispatchEnvelopeEvent('onEnvelopeReceived', this.node, env, context);
                 if (env.frame.type === 'NodeHeartbeatAck') {
-                    logger$11.debug('received_heartbeat_ack', {
+                    logger$12.debug('received_heartbeat_ack', {
                         hb_ack_env_id: env.id,
                         hb_ack_corr_id: env.corrId,
                         hb_routing_epoch: env.frame.routingEpoch,
@@ -26077,7 +26119,7 @@
                             await this.onEpochChange(epoch);
                         }
                         else {
-                            logger$11.warning('parent_epoch_changed', { epoch });
+                            logger$12.warning('parent_epoch_changed', { epoch });
                         }
                     }
                     return;
@@ -26096,7 +26138,7 @@
     UpstreamSessionManager.BACKOFF_INITIAL = 1; // seconds
     UpstreamSessionManager.BACKOFF_CAP = 30; // seconds
 
-    const logger$10 = getLogger('naylence.fame.node.admission.noop_admission_client');
+    const logger$11 = getLogger('naylence.fame.node.admission.noop_admission_client');
     class NoopAdmissionClient {
         constructor(options = {}) {
             this.hasUpstream = false;
@@ -26110,7 +26152,7 @@
             const acceptedLogicals = this.autoAcceptLogicals
                 ? [...(requestedLogicals ?? [])]
                 : [];
-            logger$10.debug('noop_admission_hello', {
+            logger$11.debug('noop_admission_hello', {
                 systemId: effectiveSystemId,
                 instanceId,
                 requestedLogicals,
@@ -26128,7 +26170,7 @@
             });
         }
         async close() {
-            logger$10.debug('noop_admission_close');
+            logger$11.debug('noop_admission_close');
         }
     }
 
@@ -26334,7 +26376,7 @@
     }
 
     const SYSTEM_INBOX$1 = '__sys__';
-    const logger$$ = getLogger('naylence.fame.node.node');
+    const logger$10 = getLogger('naylence.fame.node.node');
     function isSnakeCase(name) {
         return name.includes('_');
     }
@@ -26461,6 +26503,8 @@
             this._acceptedLogicals = new Set(acceptedLogicalsOption);
             const deliveryPolicyOption = resolveOption(options, 'deliveryPolicy', 'delivery_policy');
             this._deliveryPolicy = deliveryPolicyOption ?? null;
+            const connectionRetryPolicyOption = resolveOption(options, 'connectionRetryPolicy', 'connection_retry_policy');
+            this._connectionRetryPolicy = connectionRetryPolicyOption ?? null;
             const admissionClientOption = resolveOption(options, 'admissionClient', 'admission_client');
             this._admissionClient = admissionClientOption ?? null;
             const attachClientOption = resolveOption(options, 'attachClient', 'attach_client');
@@ -26590,6 +26634,7 @@
                 onAttach: (info, connector) => this.handleAttach(info, connector),
                 onEpochChange: (epoch) => this.handleEpochChange(epoch),
                 admissionClient: this._admissionClient,
+                retryPolicy: this._connectionRetryPolicy,
             });
             this._sessionManager = manager;
             await manager.start();
@@ -26601,7 +26646,7 @@
         confirmIdentity(systemId, source) {
             if (this._confirmedId) {
                 if (this._confirmedId !== systemId) {
-                    logger$$.error('node_identity_mismatch', {
+                    logger$10.error('node_identity_mismatch', {
                         current_id: this._confirmedId,
                         new_id: systemId,
                         source,
@@ -26613,14 +26658,14 @@
             const isReassignment = this._provisionalId !== systemId;
             this._confirmedId = systemId;
             if (isReassignment) {
-                logger$$.debug('node_identity_reassigned', {
+                logger$10.debug('node_identity_reassigned', {
                     system_id: systemId,
                     previous_id: this._provisionalId,
                     source,
                 });
             }
             else {
-                logger$$.debug('node_identity_confirmed', {
+                logger$10.debug('node_identity_confirmed', {
                     system_id: systemId,
                     source,
                 });
@@ -26688,7 +26733,7 @@
                 return;
             }
             if (frameType === 'NodeHeartbeat') {
-                logger$$.debug('received_heartbeat_frame', {
+                logger$10.debug('received_heartbeat_frame', {
                     envelopeId: envelope.id,
                     corrId: envelope.corrId ?? null,
                 });
@@ -26700,7 +26745,7 @@
                 await this.handleDeliveryAck(envelope, context);
                 return;
             }
-            logger$$.debug('unhandled_system_frame', {
+            logger$10.debug('unhandled_system_frame', {
                 envelopeId: envelope.id,
                 frameType,
             });
@@ -26712,13 +26757,13 @@
             }
             await this._deliveryTracker.onEnvelopeDelivered(SYSTEM_INBOX$1, envelope, context);
             if (frame.ok !== false) {
-                logger$$.debug('delivery_ack_received', {
+                logger$10.debug('delivery_ack_received', {
                     envelopeId: envelope.id,
                     corrId: envelope.corrId ?? null,
                 });
                 return;
             }
-            logger$$.warning('delivery_nack_received', {
+            logger$10.warning('delivery_nack_received', {
                 envelopeId: envelope.id,
                 corrId: envelope.corrId ?? null,
                 code: frame.code ?? null,
@@ -26728,7 +26773,7 @@
             await this.onDeliveryNack(frame, envelope, context);
         }
         async onDeliveryNack(frame, envelope, _context) {
-            logger$$.debug('delivery_nack_processed', {
+            logger$10.debug('delivery_nack_processed', {
                 envelopeId: envelope.id,
                 code: frame.code ?? null,
                 reason: frame.reason ?? null,
@@ -26843,7 +26888,7 @@
                 await this._bindingManager.restore();
                 await this._envelopeListenerManager.start();
                 this._isStarted = true;
-                logger$$.debug('node_started', {
+                logger$10.debug('node_started', {
                     node_id: this.id,
                     sid: this.sid,
                     path: this.physicalPath,
@@ -26875,7 +26920,7 @@
             await this._serviceManager.stop();
             await this.dispatchEvent('onNodeStopped', this);
             this._isStarted = false;
-            logger$$.debug('node_stopped', {
+            logger$10.debug('node_stopped', {
                 node_id: this.id,
             });
         }
@@ -27065,20 +27110,20 @@
                     await this.forwardUpstream(processedEnvelope, context);
                 }
                 else {
-                    logger$$.error('attempted_upstream_loop', {
+                    logger$10.error('attempted_upstream_loop', {
                         envelopeId: processedEnvelope.id,
                     });
                 }
                 return;
             }
             if (!processedEnvelope.to) {
-                logger$$.error('dropping_envelope_without_destination', {
+                logger$10.error('dropping_envelope_without_destination', {
                     envelopeId: processedEnvelope.id,
                     capabilities: processedEnvelope.capabilities ?? [],
                 });
                 return;
             }
-            logger$$.warning('no_local_handler_for_address', {
+            logger$10.warning('no_local_handler_for_address', {
                 address: processedEnvelope.to.toString?.() ?? String(processedEnvelope.to),
                 originType: context?.originType ?? null,
             });
@@ -27202,7 +27247,7 @@
                     }
                 }
                 catch (error) {
-                    logger$$.warning('callback_grant_collection_failed', {
+                    logger$10.warning('callback_grant_collection_failed', {
                         error: error instanceof Error ? error.message : String(error),
                     });
                 }
@@ -27265,7 +27310,7 @@
                 await store.set('self', record);
             }
             catch (error) {
-                logger$$.warning('node_meta_persist_failed', {
+                logger$10.warning('node_meta_persist_failed', {
                     error: error instanceof Error ? error.message : String(error),
                 });
             }
@@ -27294,6 +27339,7 @@
         telemetry: unknown().optional().nullable(),
         requestedCapabilities: array(string$1()).optional(),
         identityPolicy: unknown().optional().nullable(),
+        connectionRetryPolicy: unknown().optional().nullable(),
     })
         .passthrough();
     function normalizeFameNodeConfig(input) {
@@ -27335,6 +27381,9 @@
             identityPolicy: parsed.identityPolicy === undefined
                 ? null
                 : parsed.identityPolicy,
+            connectionRetryPolicy: parsed.connectionRetryPolicy === undefined
+                ? null
+                : parsed.connectionRetryPolicy,
         };
         if (parsed.requestedCapabilities) {
             normalized.requestedCapabilities = coerceStringArray$1(parsed.requestedCapabilities);
@@ -27379,6 +27428,24 @@
         }
     }
 
+    const CONNECTION_RETRY_POLICY_FACTORY_BASE_TYPE = 'ConnectionRetryPolicyFactory';
+    class ConnectionRetryPolicyFactory extends AbstractResourceFactory {
+        static async createConnectionRetryPolicy(config, options = {}) {
+            if (config) {
+                const policy = await createResource$1(CONNECTION_RETRY_POLICY_FACTORY_BASE_TYPE, config, options);
+                if (!policy) {
+                    throw new Error('Failed to create connection retry policy from configuration');
+                }
+                return policy;
+            }
+            const policy = await createDefaultResource(CONNECTION_RETRY_POLICY_FACTORY_BASE_TYPE, null, options);
+            if (!policy) {
+                throw new Error('Failed to create default connection retry policy');
+            }
+            return policy;
+        }
+    }
+
     const TOKEN_PROVIDER_FACTORY_BASE_TYPE = 'TokenProviderFactory';
     class TokenProviderFactory extends AbstractResourceFactory {
         static async createTokenProvider(config, options = {}) {
@@ -27416,7 +27483,7 @@
                 'function');
     }
 
-    const logger$_ = getLogger('naylence.fame.node.default_node_identity_policy');
+    const logger$$ = getLogger('naylence.fame.node.default_node_identity_policy');
     class DefaultNodeIdentityPolicy {
         async resolveInitialNodeId(context) {
             if (context.configuredId) {
@@ -27446,7 +27513,7 @@
                         if (isIdentityExposingTokenProvider(provider)) {
                             const identity = await provider.getIdentity();
                             if (identity && identity.subject) {
-                                logger$_.debug('identity_extracted_from_grant', {
+                                logger$$.debug('identity_extracted_from_grant', {
                                     identity_id: identity.subject,
                                     grant_type: grant.type,
                                 });
@@ -27455,7 +27522,7 @@
                         }
                     }
                     catch (error) {
-                        logger$_.warning('identity_extraction_failed', {
+                        logger$$.warning('identity_extraction_failed', {
                             error: error instanceof Error ? error.message : String(error),
                             grant_type: grant.type,
                         });
@@ -27539,7 +27606,7 @@
         }
     }
 
-    const logger$Z = getLogger('naylence.fame.node.admission.default_node_attach_client');
+    const logger$_ = getLogger('naylence.fame.node.admission.default_node_attach_client');
     const HANDSHAKE_POLL_INTERVAL_MS = 20;
     class DefaultNodeAttachClient {
         constructor(options = {}) {
@@ -27563,7 +27630,7 @@
                     }
                     else {
                         // Silently ignore frames from other agents during concurrent handshakes
-                        logger$Z.debug('handshake_ignoring_frame_from_different_system', {
+                        logger$_.debug('handshake_ignoring_frame_from_different_system', {
                             frame_type: envelope.frame.type,
                             frame_system_id: frameSystemId,
                             expected_system_id: this.expectedSystemId,
@@ -27606,7 +27673,7 @@
                 }
             }
             catch (error) {
-                logger$Z.debug('stickiness_offer_skipped', {
+                logger$_.debug('stickiness_offer_skipped', {
                     error: error instanceof Error ? error.message : String(error),
                 });
             }
@@ -27627,7 +27694,7 @@
                 if (!processedEnvelope) {
                     throw new Error('Envelope was blocked by onForwardUpstream event');
                 }
-                logger$Z.debug('sending_node_attach_envelope', {
+                logger$_.debug('sending_node_attach_envelope', {
                     envp_id: processedEnvelope.id ?? envelope.id ?? null,
                     frame_type: processedEnvelope.frame?.type ?? 'unknown',
                     trace_id: processedEnvelope.traceId ?? envelope.traceId ?? null,
@@ -27663,7 +27730,7 @@
                 try {
                     const keyInfos = await this.attachmentKeyValidator.validateKeys(parentKeys);
                     if (Array.isArray(keyInfos) && keyInfos.length > 0) {
-                        logger$Z.debug('parent_certificate_validation_passed', {
+                        logger$_.debug('parent_certificate_validation_passed', {
                             parent_id: parentId,
                             correlation_id: corrId,
                             validated_keys: keyInfos.length,
@@ -27672,7 +27739,7 @@
                 }
                 catch (error) {
                     if (error instanceof KeyValidationError) {
-                        logger$Z.error('parent_certificate_validation_failed', {
+                        logger$_.error('parent_certificate_validation_failed', {
                             parent_id: parentId,
                             correlation_id: corrId,
                             error_code: error.code,
@@ -27686,12 +27753,12 @@
                 }
             }
             else {
-                logger$Z.debug('parent_certificate_validation_skipped', {
+                logger$_.debug('parent_certificate_validation_skipped', {
                     parent_id: parentId,
                     reason: 'no_validator',
                 });
             }
-            logger$Z.debug('processing_node_attach_ack', {
+            logger$_.debug('processing_node_attach_ack', {
                 parent_id: ackFrame.targetSystemId,
             });
             this.inHandshake = false;
@@ -27722,7 +27789,7 @@
                 }
             }
             catch (error) {
-                logger$Z.debug('stickiness_accept_skipped', {
+                logger$_.debug('stickiness_accept_skipped', {
                     error: error instanceof Error ? error.message : String(error),
                 });
             }
@@ -27776,7 +27843,7 @@
                     // NodeAttach frames during handshake are expected in multi-agent scenarios
                     // where multiple agents attach concurrently to the same channel
                     if (envelope.frame.type === 'NodeAttach') {
-                        logger$Z.debug('handshake_ignoring_concurrent_attach', {
+                        logger$_.debug('handshake_ignoring_concurrent_attach', {
                             frame_type: envelope.frame.type,
                             frame_system_id: envelope.frame?.systemId ??
                                 'unknown',
@@ -27784,7 +27851,7 @@
                     }
                     else {
                         // Other unexpected frames are still logged as errors
-                        logger$Z.error('unexpected_frame_during_handshake', {
+                        logger$_.error('unexpected_frame_during_handshake', {
                             frame_type: envelope.frame.type,
                         });
                     }
@@ -27919,7 +27986,7 @@
     // void import('./trace-emitter-profile-factory.js');
 
     const BINDING_STORE_NAMESPACE = '__binding_store';
-    const logger$Y = getLogger('naylence.fame.node.factory_commons');
+    const logger$Z = getLogger('naylence.fame.node.factory_commons');
     function isPlainRecord$2(value) {
         return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
     }
@@ -28026,6 +28093,7 @@
         const telemetryConfig = pickOption$1(config.telemetry ?? null, aliasRecord, 'trace_emitter', 'telemetry_config');
         const securityConfig = pickOption$1(config.security ?? null, aliasRecord, 'security_manager', 'security_profile');
         const identityPolicyConfig = pickOption$1(config.identityPolicy ?? null, aliasRecord, 'identity_policy', 'node_identity_policy');
+        const connectionRetryPolicyConfig = pickOption$1(config.connectionRetryPolicy ?? null, aliasRecord, 'connection_retry_policy', 'retry_policy');
         const publicUrl = pickString$2(config.publicUrl ?? null, aliasRecord, 'public_url') ?? null;
         const directParentUrl = pickString$2(config.directParentUrl ?? null, aliasRecord, 'direct_parent_url') ?? null;
         const hasParentFlag = config.hasParent || Boolean(aliasRecord.has_parent ?? false);
@@ -28035,6 +28103,7 @@
         const nodeMetaStore = await storageProvider.getKeyValueStore(NodeMetaRecord, NODE_META_NAMESPACE);
         const nodeMeta = await nodeMetaStore.get('self');
         const identityPolicy = await resolveNodeIdentityPolicy(identityPolicyConfig ?? null, expressionOptions);
+        const connectionRetryPolicy = await resolveConnectionRetryPolicy(connectionRetryPolicyConfig ?? null, expressionOptions);
         const admissionClient = await resolveAdmissionClient(admissionConfig ?? null, expressionOptions, identityPolicy ?? undefined);
         const hasParent = determineHasParent(hasParentFlag, directParentUrl, admissionClient);
         const replicaStickinessManager = await resolveReplicaStickinessManager(hasParent, requestedLogicals, expressionOptions);
@@ -28103,6 +28172,7 @@
             transportListeners,
             traceEmitter,
             identityPolicy: identityPolicy ?? undefined,
+            connectionRetryPolicy: connectionRetryPolicy ?? undefined,
         };
     }
     async function resolveNodeIdentityPolicy(config, options) {
@@ -28110,7 +28180,18 @@
             return await NodeIdentityPolicyFactory.createNodeIdentityPolicy(config ?? undefined, cloneCreateOptions(options));
         }
         catch (error) {
-            logger$Y.warning('node_identity_policy_creation_failed', {
+            logger$Z.warning('node_identity_policy_creation_failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+    async function resolveConnectionRetryPolicy(config, options) {
+        try {
+            return await ConnectionRetryPolicyFactory.createConnectionRetryPolicy(config ?? undefined, cloneCreateOptions(options));
+        }
+        catch (error) {
+            logger$Z.warning('connection_retry_policy_creation_failed', {
                 error: error instanceof Error ? error.message : String(error),
             });
             return null;
@@ -28122,7 +28203,7 @@
                 return await StorageProviderFactory.createStorageProvider(config, cloneCreateOptions(options));
             }
             catch (error) {
-                logger$Y.warning('storage_provider_creation_failed', {
+                logger$Z.warning('storage_provider_creation_failed', {
                     error: error instanceof Error ? error.message : String(error),
                 });
             }
@@ -28144,7 +28225,7 @@
             return await AdmissionClientFactory.createAdmissionClient((config ?? null), createOptions);
         }
         catch (error) {
-            logger$Y.warning('admission_client_creation_failed', {
+            logger$Z.warning('admission_client_creation_failed', {
                 error: error instanceof Error ? error.message : String(error),
             });
             return null;
@@ -28171,7 +28252,7 @@
             return await ReplicaStickinessManagerFactory.createReplicaStickinessManager(undefined, cloneCreateOptions(options));
         }
         catch (error) {
-            logger$Y.debug('replica_stickiness_manager_unavailable', { error });
+            logger$Z.debug('replica_stickiness_manager_unavailable', { error });
             return null;
         }
     }
@@ -28180,7 +28261,7 @@
             return await AttachmentKeyValidatorFactory.createAttachmentKeyValidator(config ?? undefined, cloneCreateOptions(options));
         }
         catch (error) {
-            logger$Y.warning('attachment_key_validator_creation_failed', {
+            logger$Z.warning('attachment_key_validator_creation_failed', {
                 error: error instanceof Error ? error.message : String(error),
             });
             return null;
@@ -28198,7 +28279,7 @@
             return await DeliveryPolicyFactory.createDeliveryPolicy(config ?? undefined, cloneCreateOptions(options));
         }
         catch (error) {
-            logger$Y.warning('delivery_policy_creation_failed', {
+            logger$Z.warning('delivery_policy_creation_failed', {
                 error: error instanceof Error ? error.message : String(error),
             });
             return null;
@@ -28212,7 +28293,7 @@
             return await TransportListenerFactory.createTransportListeners(configs, eventListeners, cloneCreateOptions(options));
         }
         catch (error) {
-            logger$Y.warning('transport_listener_creation_failed', {
+            logger$Z.warning('transport_listener_creation_failed', {
                 error: error instanceof Error ? error.message : String(error),
             });
             return [];
@@ -28223,7 +28304,7 @@
             return await TraceEmitterFactory.createTraceEmitter(config ?? undefined, cloneCreateOptions(options));
         }
         catch (error) {
-            logger$Y.warning('trace_emitter_creation_failed', {
+            logger$Z.warning('trace_emitter_creation_failed', {
                 error: error instanceof Error ? error.message : String(error),
             });
             return null;
@@ -28279,7 +28360,7 @@
             return manager ?? null;
         }
         catch (error) {
-            logger$Y.warning('security_manager_creation_failed', {
+            logger$Z.warning('security_manager_creation_failed', {
                 error: error instanceof Error ? error.message : String(error),
             });
             return null;
@@ -28308,7 +28389,7 @@
         // This happens with overlay security profiles that need envelope signing
         if (requiresCryptoProvider(config)) {
             try {
-                logger$Y.debug('auto_creating_crypto_provider', {
+                logger$Z.debug('auto_creating_crypto_provider', {
                     reason: 'overlay_security_requires_signing',
                 });
                 // Dynamically import to avoid circular dependencies
@@ -28328,7 +28409,7 @@
                 });
             }
             catch (error) {
-                logger$Y.error('failed_to_auto_create_crypto_provider', {
+                logger$Z.error('failed_to_auto_create_crypto_provider', {
                     error: error instanceof Error ? error.message : String(error),
                 });
                 throw error;
@@ -28871,7 +28952,7 @@
     //   registerFactory(NODE_LIKE_FACTORY_BASE_TYPE, type, factory);
     // }
 
-    const FACTORY_META$17 = {
+    const FACTORY_META$18 = {
         base: NODE_LIKE_FACTORY_BASE_TYPE,
         key: 'Node',
     };
@@ -28905,6 +28986,7 @@
                 nodeMetaStore: components.nodeMetaStore,
                 transportListeners: components.transportListeners,
                 defaultServiceConfigs: serviceConfigs,
+                connectionRetryPolicy: components.connectionRetryPolicy,
             });
             return node;
         }
@@ -28912,7 +28994,7 @@
 
     var nodeFactory = /*#__PURE__*/Object.freeze({
         __proto__: null,
-        FACTORY_META: FACTORY_META$17,
+        FACTORY_META: FACTORY_META$18,
         NodeFactory: NodeFactory,
         default: NodeFactory
     });
@@ -29446,7 +29528,7 @@
         };
     }
 
-    const logger$X = getLogger('naylence.fame.node.envelope_security_handler');
+    const logger$Y = getLogger('naylence.fame.node.envelope_security_handler');
     const ENCRYPTION_OPTION_ALIAS_PAIRS = [
         ['recipKid', 'recip_kid'],
         ['recipientKeyId', 'recipient_key_id'],
@@ -29495,7 +29577,7 @@
             const shouldSign = this.securityPolicy
                 ? await this.securityPolicy.shouldSignEnvelope(envelope, context, this.node)
                 : false;
-            logger$X.debug('checking_signing', {
+            logger$Y.debug('checking_signing', {
                 has_signer: Boolean(this.envelopeSigner),
                 should_sign: shouldSign,
                 envp_id: envelope.id,
@@ -29517,7 +29599,7 @@
             const shouldEncrypt = this.securityPolicy
                 ? await this.securityPolicy.shouldEncryptEnvelope(envelope, context, this.node)
                 : false;
-            logger$X.debug('checking_encryption', {
+            logger$Y.debug('checking_encryption', {
                 has_encryption_manager: Boolean(this.encryptionManager),
                 should_encrypt: shouldEncrypt,
                 envp_id: envelope.id,
@@ -29525,7 +29607,7 @@
             });
             if (this.encryptionManager && this.securityPolicy) {
                 if (envelope.sec?.enc) {
-                    logger$X.debug('skipping_encryption_already_encrypted', {
+                    logger$Y.debug('skipping_encryption_already_encrypted', {
                         envp_id: envelope.id,
                         destination: envelope.to ? String(envelope.to) : undefined,
                     });
@@ -29538,7 +29620,7 @@
                         CryptoLevel.PLAINTEXT;
                     desiredCryptoLevel =
                         await this.securityPolicy.decideResponseCryptoLevel(requestCryptoLevel, envelope, context);
-                    logger$X.debug('response_crypto_level_decided', {
+                    logger$Y.debug('response_crypto_level_decided', {
                         envp_id: envelope.id,
                         crypto_level: desiredCryptoLevel,
                         destination: envelope.to ? String(envelope.to) : undefined,
@@ -29549,7 +29631,7 @@
                 else {
                     desiredCryptoLevel =
                         await this.securityPolicy.decideOutboundCryptoLevel(envelope, context, this.node);
-                    logger$X.debug('outbound_crypto_level_decided', {
+                    logger$Y.debug('outbound_crypto_level_decided', {
                         envp_id: envelope.id,
                         frame_type: envelope.frame.type,
                         crypto_level: desiredCryptoLevel,
@@ -29557,11 +29639,11 @@
                     });
                 }
                 if (desiredCryptoLevel === CryptoLevel.SEALED) {
-                    logger$X.debug('applying_sealed_encryption', { envp_id: envelope.id });
+                    logger$Y.debug('applying_sealed_encryption', { envp_id: envelope.id });
                     return await this.handleSealedEncryption(envelope, context);
                 }
                 if (desiredCryptoLevel === CryptoLevel.CHANNEL) {
-                    logger$X.debug('applying_channel_encryption', { envp_id: envelope.id });
+                    logger$Y.debug('applying_channel_encryption', { envp_id: envelope.id });
                     return await this.handleChannelEncryption(envelope, context);
                 }
             }
@@ -29612,7 +29694,7 @@
                     frameType === 'KeyAnnounce' ||
                     frameType === 'SecureOpen' ||
                     frameType === 'SecureAccept') {
-                    logger$X.error('critical_frame_unsigned_rejected', {
+                    logger$Y.error('critical_frame_unsigned_rejected', {
                         envp_id: envelope.id,
                         frame_type: frameType,
                         reason: 'critical_frames_must_be_signed',
@@ -29620,7 +29702,7 @@
                     return [envelope, false];
                 }
                 const action = this.securityPolicy.getUnsignedViolationAction(envelope, context);
-                logger$X.warning('unsigned_envelope_violation', {
+                logger$Y.warning('unsigned_envelope_violation', {
                     envp_id: envelope.id,
                     frame_type: frameType,
                     action,
@@ -29632,26 +29714,26 @@
             return [envelope, true];
         }
         async handleChannelHandshakeComplete(channelId, destination) {
-            logger$X.debug('channel_handshake_completed', {
+            logger$Y.debug('channel_handshake_completed', {
                 channel_id: channelId,
                 destination,
             });
             if (this.encryptionManager?.notifyChannelEstablished) {
                 await this.encryptionManager.notifyChannelEstablished(channelId);
-                logger$X.debug('notified_encryption_manager_channel_ready', {
+                logger$Y.debug('notified_encryption_manager_channel_ready', {
                     channel_id: channelId,
                 });
             }
         }
         async handleChannelHandshakeFailed(channelId, destination, reason = 'handshake_failed') {
-            logger$X.debug('channel_handshake_failed', {
+            logger$Y.debug('channel_handshake_failed', {
                 channel_id: channelId,
                 destination,
                 reason,
             });
             if (this.encryptionManager?.notifyChannelFailed) {
                 await this.encryptionManager.notifyChannelFailed(channelId, reason);
-                logger$X.debug('notified_encryption_manager_channel_failed', {
+                logger$Y.debug('notified_encryption_manager_channel_failed', {
                     channel_id: channelId,
                     reason,
                 });
@@ -29698,7 +29780,7 @@
                     checkPayload: false,
                 });
                 if (verified) {
-                    logger$X.debug('envelope_verified', {
+                    logger$Y.debug('envelope_verified', {
                         envp_id: envelope.id,
                         sid: envelope.sid,
                         kid,
@@ -29709,7 +29791,7 @@
             }
             this.keyManagementHandler.queuePendingSignedEnvelope(kid, envelope, context);
             await this.keyManagementHandler.maybeRequestSigningKey(kid, context.originType, fromSystemId);
-            logger$X.debug('queued_envelope_missing_signing_key', {
+            logger$Y.debug('queued_envelope_missing_signing_key', {
                 kid,
                 envp_id: envelope.id,
             });
@@ -29717,7 +29799,7 @@
         }
         async handleSealedEncryption(envelope, context) {
             if (!envelope.to) {
-                logger$X.warning('sealed_encryption_requested_but_no_destination', {
+                logger$Y.warning('sealed_encryption_requested_but_no_destination', {
                     envp_id: envelope.id,
                 });
                 return true;
@@ -29729,20 +29811,20 @@
                     : undefined;
                 if (options) {
                     if (options.encryptionType === 'channel') {
-                        logger$X.warning('policy_returned_channel_for_sealed_request', {
+                        logger$Y.warning('policy_returned_channel_for_sealed_request', {
                             envp_id: envelope.id,
                         });
                         return await this.handleToBeEncryptedEnvelopeWithOptions(envelope, context, normalizeEncryptionOptions({
                             requestAddress: envelope.to,
                         }));
                     }
-                    logger$X.debug('using_sealed_encryption_options', {
+                    logger$Y.debug('using_sealed_encryption_options', {
                         envp_id: envelope.id,
                         options,
                     });
                     return await this.handleToBeEncryptedEnvelopeWithOptions(envelope, context, options);
                 }
-                logger$X.debug('no_encryption_options_requesting_key', {
+                logger$Y.debug('no_encryption_options_requesting_key', {
                     envp_id: envelope.id,
                 });
                 return await this.handleToBeEncryptedEnvelopeWithOptions(envelope, context, normalizeEncryptionOptions({
@@ -29750,7 +29832,7 @@
                 }));
             }
             catch (error) {
-                logger$X.debug('sealed_key_lookup_failed_requesting', {
+                logger$Y.debug('sealed_key_lookup_failed_requesting', {
                     envp_id: envelope.id,
                     error: error instanceof Error ? error.message : String(error),
                 });
@@ -29761,7 +29843,7 @@
         }
         async handleChannelEncryption(envelope, context) {
             if (!envelope.to) {
-                logger$X.warning('channel_encryption_requested_but_no_destination', {
+                logger$Y.warning('channel_encryption_requested_but_no_destination', {
                     envp_id: envelope.id,
                 });
                 return true;
@@ -29776,13 +29858,13 @@
                 return true;
             }
             if (context.originType !== DeliveryOriginType.LOCAL) {
-                logger$X.warning('envelope_encryption_rejected_non_local', {
+                logger$Y.warning('envelope_encryption_rejected_non_local', {
                     origin: context.originType,
                 });
                 return true;
             }
             if (!isDataFrame$4(envelope.frame)) {
-                logger$X.trace('skipping_encryption_non_dataframe', {
+                logger$Y.trace('skipping_encryption_non_dataframe', {
                     envp_id: envelope.id,
                     frame_type: envelope.frame.type,
                 });
@@ -29793,7 +29875,7 @@
                 ? normalizeEncryptionOptions(rawOptions)
                 : undefined;
             if (!options) {
-                logger$X.warning('no_encryption_options_provided', {
+                logger$Y.warning('no_encryption_options_provided', {
                     envp_id: envelope.id,
                 });
                 return true;
@@ -29805,13 +29887,13 @@
                 return true;
             }
             if (context.originType !== DeliveryOriginType.LOCAL) {
-                logger$X.warning('envelope_encryption_rejected_non_local', {
+                logger$Y.warning('envelope_encryption_rejected_non_local', {
                     origin: context.originType,
                 });
                 return true;
             }
             if (!isDataFrame$4(envelope.frame)) {
-                logger$X.trace('skipping_encryption_non_dataframe', {
+                logger$Y.trace('skipping_encryption_non_dataframe', {
                     envp_id: envelope.id,
                     frame_type: envelope.frame.type,
                 });
@@ -29828,7 +29910,7 @@
             // Skip encryption if envelope is already encrypted
             // This prevents re-queuing when replayed envelopes go through security again
             if (envelope.sec?.enc) {
-                logger$X.debug('skipping_encryption_already_encrypted', {
+                logger$Y.debug('skipping_encryption_already_encrypted', {
                     envp_id: envelope.id,
                     destination: envelope.to ? String(envelope.to) : undefined,
                 });
@@ -29837,14 +29919,14 @@
             try {
                 const result = await this.encryptionManager.encryptEnvelope(envelope, normalizedOptions);
                 if (result.status === EncryptionStatus.QUEUED) {
-                    logger$X.debug('envelope_queued_for_encryption', {
+                    logger$Y.debug('envelope_queued_for_encryption', {
                         envp_id: envelope.id,
                     });
                     await this.handleEncryptionQueueing(envelope, context, normalizedOptions);
                     return false;
                 }
                 if (result.status === EncryptionStatus.OK) {
-                    logger$X.debug('envelope_encrypted', { envp_id: envelope.id });
+                    logger$Y.debug('envelope_encrypted', { envp_id: envelope.id });
                     if (result.envelope) {
                         envelope.frame = result.envelope.frame;
                         envelope.sec = result.envelope.sec;
@@ -29852,17 +29934,17 @@
                     return true;
                 }
                 if (result.status === EncryptionStatus.SKIPPED) {
-                    logger$X.debug('envelope_encryption_skipped', { envp_id: envelope.id });
+                    logger$Y.debug('envelope_encryption_skipped', { envp_id: envelope.id });
                     return true;
                 }
-                logger$X.warning('unknown_encryption_status', {
+                logger$Y.warning('unknown_encryption_status', {
                     envp_id: envelope.id,
                     status: result.status,
                 });
                 return true;
             }
             catch (error) {
-                logger$X.error('encryption_failed', {
+                logger$Y.error('encryption_failed', {
                     envp_id: envelope.id,
                     error: error instanceof Error ? error.message : String(error),
                 });
@@ -29901,7 +29983,7 @@
                 return;
             }
             if (normalizedOptions.encryptionType === 'channel') {
-                logger$X.debug('channel_encryption_queueing_handled_internally', {
+                logger$Y.debug('channel_encryption_queueing_handled_internally', {
                     envp_id: envelope.id,
                     destination: normalizedOptions.destination
                         ? String(normalizedOptions.destination)
@@ -29909,13 +29991,13 @@
                 });
                 return;
             }
-            logger$X.warning('unknown_encryption_queueing_options', {
+            logger$Y.warning('unknown_encryption_queueing_options', {
                 envp_id: envelope.id,
                 options: normalizedOptions,
             });
         }
         async handleFailedChannelEnvelopeCleanup(destination, reason) {
-            logger$X.debug('channel_handshake_failure_cleanup_attempted', {
+            logger$Y.debug('channel_handshake_failure_cleanup_attempted', {
                 destination,
                 reason,
                 note: 'envelope_cleanup_handled_by_encryption_manager',
@@ -29926,7 +30008,7 @@
         }
     }
 
-    const logger$W = getLogger('naylence.fame.node.secure_channel_frame_handler');
+    const logger$X = getLogger('naylence.fame.node.secure_channel_frame_handler');
     function isPlainRecord$1(value) {
         if (typeof value !== 'object' || value === null) {
             return false;
@@ -30016,7 +30098,7 @@
             assertSecureChannelManager(this.secureChannelManager);
             const frame = envelope.frame;
             assertFrameType(frame, 'SecureOpen');
-            logger$W.debug('received_secure_open', {
+            logger$X.debug('received_secure_open', {
                 cid: frame.cid,
                 algorithm: frame.alg,
             });
@@ -30039,13 +30121,13 @@
                     stickySid: envelope.sid ?? undefined,
                     expectedResponseType: FameResponseType.NONE,
                 };
-                logger$W.debug('stickiness_requested_for_channel_encryption', {
+                logger$X.debug('stickiness_requested_for_channel_encryption', {
                     cid: frame.cid,
                     reason: 'secure_channel_established',
                 });
             }
             await this.sendCallback(responseEnvelope, responseContext);
-            logger$W.debug('sent_secure_accept', { cid: frame.cid, ok: acceptFrame.ok });
+            logger$X.debug('sent_secure_accept', { cid: frame.cid, ok: acceptFrame.ok });
             if (acceptFrame.ok && this.envelopeSecurityHandler) {
                 const destination = extractDestinationFromChannelId(frame.cid);
                 if (destination) {
@@ -30057,13 +30139,13 @@
             assertSecureChannelManager(this.secureChannelManager);
             const frame = envelope.frame;
             assertFrameType(frame, 'SecureAccept');
-            logger$W.debug('received_secure_accept', { cid: frame.cid, ok: frame.ok });
+            logger$X.debug('received_secure_accept', { cid: frame.cid, ok: frame.ok });
             const success = await this.secureChannelManager.handleAcceptFrame(frame);
             if (!success) {
-                logger$W.warning('failed_to_complete_channel', { cid: frame.cid });
+                logger$X.warning('failed_to_complete_channel', { cid: frame.cid });
             }
             else {
-                logger$W.debug('channel_established', { cid: frame.cid });
+                logger$X.debug('channel_established', { cid: frame.cid });
                 if (this.envelopeSecurityHandler) {
                     const destination = extractDestinationFromChannelId(frame.cid);
                     if (destination) {
@@ -30075,7 +30157,7 @@
                 const destination = extractDestinationFromChannelId(frame.cid);
                 if (destination) {
                     await this.envelopeSecurityHandler.handleChannelHandshakeFailed(frame.cid, destination, 'negative_secure_accept');
-                    logger$W.debug('notified_handshake_failure', {
+                    logger$X.debug('notified_handshake_failure', {
                         cid: frame.cid,
                         destination,
                     });
@@ -30086,7 +30168,7 @@
             assertSecureChannelManager(this.secureChannelManager);
             const frame = envelope.frame;
             assertFrameType(frame, 'SecureClose');
-            logger$W.debug('received_secure_close', {
+            logger$X.debug('received_secure_close', {
                 cid: frame.cid,
                 reason: frame.reason,
             });
@@ -30110,7 +30192,7 @@
         }).optional(),
     });
 
-    const FACTORY_META$16 = {
+    const FACTORY_META$17 = {
         base: NODE_IDENTITY_POLICY_FACTORY_BASE_TYPE,
         key: 'DefaultNodeIdentityPolicy',
     };
@@ -30128,11 +30210,11 @@
     var defaultNodeIdentityPolicyFactory = /*#__PURE__*/Object.freeze({
         __proto__: null,
         DefaultNodeIdentityPolicyFactory: DefaultNodeIdentityPolicyFactory,
-        FACTORY_META: FACTORY_META$16,
+        FACTORY_META: FACTORY_META$17,
         default: DefaultNodeIdentityPolicyFactory
     });
 
-    const logger$V = getLogger('naylence.fame.node.token_subject_node_identity_policy');
+    const logger$W = getLogger('naylence.fame.node.token_subject_node_identity_policy');
     class TokenSubjectNodeIdentityPolicy {
         async resolveInitialNodeId(context) {
             if (context.configuredId) {
@@ -30144,7 +30226,7 @@
             return generateIdAsync();
         }
         async resolveAdmissionNodeId(context) {
-            logger$V.debug('resolve_admission_node_id_start', {
+            logger$W.debug('resolve_admission_node_id_start', {
                 grantsCount: context.grants?.length ?? 0,
                 currentNodeId: context.currentNodeId,
             });
@@ -30153,31 +30235,31 @@
                     try {
                         const auth = grant.auth;
                         if (!auth) {
-                            logger$V.debug('skipping_grant_no_auth', { grantType: grant.type });
+                            logger$W.debug('skipping_grant_no_auth', { grantType: grant.type });
                             continue;
                         }
                         const tokenProviderConfig = (auth.tokenProvider ??
                             auth.token_provider);
                         if (!tokenProviderConfig ||
                             typeof tokenProviderConfig.type !== 'string') {
-                            logger$V.debug('skipping_grant_invalid_token_provider_config', {
+                            logger$W.debug('skipping_grant_invalid_token_provider_config', {
                                 grantType: grant.type,
                                 config: tokenProviderConfig,
                             });
                             continue;
                         }
-                        logger$V.debug('creating_token_provider', {
+                        logger$W.debug('creating_token_provider', {
                             type: tokenProviderConfig.type,
                         });
                         const provider = await TokenProviderFactory.createTokenProvider(tokenProviderConfig);
                         const isExposing = isIdentityExposingTokenProvider(provider);
-                        logger$V.debug('token_provider_created', {
+                        logger$W.debug('token_provider_created', {
                             type: tokenProviderConfig.type,
                             isIdentityExposing: isExposing,
                         });
                         if (isExposing) {
                             const identity = await provider.getIdentity();
-                            logger$V.debug('retrieved_identity', { identity });
+                            logger$W.debug('retrieved_identity', { identity });
                             if (identity && identity.subject) {
                                 const hashedSubject = await generateIdAsync({
                                     mode: 'fingerprint',
@@ -30185,7 +30267,7 @@
                                     length: 8,
                                 });
                                 const newNodeId = `${hashedSubject}-${context.currentNodeId}`;
-                                logger$V.info('resolved_identity_from_token', {
+                                logger$W.info('resolved_identity_from_token', {
                                     subject: identity.subject,
                                     hashedSubject,
                                     newNodeId,
@@ -30193,17 +30275,17 @@
                                 return newNodeId;
                             }
                             else {
-                                logger$V.debug('identity_missing_subject', { identity });
+                                logger$W.debug('identity_missing_subject', { identity });
                             }
                         }
                     }
                     catch (err) {
-                        logger$V.warning('failed_to_extract_identity_from_grant', { error: err });
+                        logger$W.warning('failed_to_extract_identity_from_grant', { error: err });
                     }
                 }
             }
             else {
-                logger$V.debug('no_grants_available');
+                logger$W.debug('no_grants_available');
             }
             return context.currentNodeId;
         }
@@ -30214,7 +30296,7 @@
         TokenSubjectNodeIdentityPolicy: TokenSubjectNodeIdentityPolicy
     });
 
-    const FACTORY_META$15 = {
+    const FACTORY_META$16 = {
         base: NODE_IDENTITY_POLICY_FACTORY_BASE_TYPE,
         key: 'TokenSubjectNodeIdentityPolicy',
     };
@@ -30233,12 +30315,12 @@
 
     var tokenSubjectNodeIdentityPolicyFactory = /*#__PURE__*/Object.freeze({
         __proto__: null,
-        FACTORY_META: FACTORY_META$15,
+        FACTORY_META: FACTORY_META$16,
         TokenSubjectNodeIdentityPolicyFactory: TokenSubjectNodeIdentityPolicyFactory,
         default: TokenSubjectNodeIdentityPolicyFactory
     });
 
-    const logger$U = getLogger('naylence.fame.node.node_identity_policy_profile_factory');
+    const logger$V = getLogger('naylence.fame.node.node_identity_policy_profile_factory');
     const PROFILE_NAME_DEFAULT = 'default';
     const PROFILE_NAME_TOKEN_SUBJECT = 'token-subject';
     const PROFILE_NAME_TOKEN_SUBJECT_ALIAS = 'token_subject';
@@ -30253,7 +30335,7 @@
         [PROFILE_NAME_TOKEN_SUBJECT]: TOKEN_SUBJECT_PROFILE,
         [PROFILE_NAME_TOKEN_SUBJECT_ALIAS]: TOKEN_SUBJECT_PROFILE,
     };
-    const FACTORY_META$14 = {
+    const FACTORY_META$15 = {
         base: NODE_IDENTITY_POLICY_FACTORY_BASE_TYPE,
         key: 'NodeIdentityPolicyProfile',
     };
@@ -30265,7 +30347,7 @@
         async create(config) {
             const normalized = normalizeConfig$t(config);
             const profileConfig = resolveProfileConfig$4(normalized.profile);
-            logger$U.debug('enabling_node_identity_policy_profile', {
+            logger$V.debug('enabling_node_identity_policy_profile', {
                 profile: normalized.profile,
             });
             return NodeIdentityPolicyFactory.createNodeIdentityPolicy(profileConfig);
@@ -30301,11 +30383,95 @@
 
     var nodeIdentityPolicyProfileFactory = /*#__PURE__*/Object.freeze({
         __proto__: null,
-        FACTORY_META: FACTORY_META$14,
+        FACTORY_META: FACTORY_META$15,
         NodeIdentityPolicyProfileFactory: NodeIdentityPolicyProfileFactory,
         default: NodeIdentityPolicyProfileFactory
     });
 
+    /**
+     * Environment variable for overriding max initial attempts.
+     */
+    const ENV_VAR_SESSION_MAX_INITIAL_ATTEMPTS = 'FAME_SESSION_MAX_INITIAL_ATTEMPTS';
+    /**
+     * Default implementation of connection retry policy.
+     *
+     * Before first successful attach:
+     * - Respects maxInitialAttempts configuration
+     * - Uses exponential backoff with jitter
+     *
+     * After first successful attach:
+     * - Always retries (unlimited) to maintain connection
+     * - Resets backoff if connection was stable for >10 seconds
+     */
+    class DefaultConnectionRetryPolicy {
+        constructor(options = {}) {
+            // Check for environment variable override
+            const envValue = typeof process !== 'undefined'
+                ? process.env?.[ENV_VAR_SESSION_MAX_INITIAL_ATTEMPTS]
+                : undefined;
+            if (envValue !== undefined && envValue !== '') {
+                const parsed = parseInt(envValue, 10);
+                this.maxInitialAttempts = isNaN(parsed) ? (options.maxInitialAttempts ?? 1) : parsed;
+            }
+            else {
+                this.maxInitialAttempts = options.maxInitialAttempts ?? 1;
+            }
+        }
+        shouldRetry(context) {
+            // After first successful attach, always retry to maintain connection
+            if (context.hadSuccessfulAttach) {
+                return true;
+            }
+            // maxInitialAttempts = 0 means unlimited retries
+            if (this.maxInitialAttempts === 0) {
+                return true;
+            }
+            // Fail if we've exceeded the configured max attempts
+            return context.attemptNumber < this.maxInitialAttempts;
+        }
+        calculateRetryDelay(_context, baseDelay) {
+            // Add jitter to prevent thundering herd
+            const jitter = Math.random() * baseDelay;
+            return baseDelay + jitter;
+        }
+    }
+
+    const logger$U = getLogger('naylence.fame.node.default-connection-retry-policy-factory');
+    const FACTORY_META$14 = {
+        base: CONNECTION_RETRY_POLICY_FACTORY_BASE_TYPE,
+        key: 'DefaultConnectionRetryPolicy',
+    };
+    class DefaultConnectionRetryPolicyFactory extends ConnectionRetryPolicyFactory {
+        constructor() {
+            super(...arguments);
+            this.type = 'DefaultConnectionRetryPolicy';
+            this.isDefault = true;
+        }
+        async create(config) {
+            const options = {};
+            if (config) {
+                const rawMax = config.maxInitialAttempts ??
+                    config.max_initial_attempts;
+                if (rawMax !== undefined && rawMax !== null) {
+                    options.maxInitialAttempts =
+                        typeof rawMax === 'string' ? parseInt(rawMax, 10) : Number(rawMax);
+                }
+            }
+            const policy = new DefaultConnectionRetryPolicy(options);
+            logger$U.debug('connection_retry_policy_created', {
+                maxInitialAttempts: policy.maxInitialAttempts,
+            });
+            return policy;
+        }
+    }
+
+    var defaultConnectionRetryPolicyFactory = /*#__PURE__*/Object.freeze({
+        __proto__: null,
+        DefaultConnectionRetryPolicyFactory: DefaultConnectionRetryPolicyFactory,
+        FACTORY_META: FACTORY_META$14,
+        default: DefaultConnectionRetryPolicyFactory
+    });
+
     const LOAD_BALANCER_STICKINESS_MANAGER_FACTORY_BASE_TYPE = 'LoadBalancerStickinessManagerFactory';
     class LoadBalancerStickinessManagerFactory extends AbstractResourceFactory {
         static async createLoadBalancerStickinessManager(config, options = {}) {
@@ -33377,6 +33543,7 @@
             this.maxAttachTtlSec = opts.maxAttachTtlSec ?? null;
             this.requestedLogicals = opts.requestedLogicals ?? [];
             this.attachClient = opts.attachClient ?? null;
+            this.connectionRetryPolicy = opts.connectionRetryPolicy ?? null;
             this.nodeAttachFrameHandler = new NodeAttachFrameHandler({
                 routingNode: this,
                 routeManager: this.routeManager,
@@ -33926,6 +34093,7 @@
                 onAttach: (info, connector) => this.onNodeAttachToPeer(info, connector),
                 onEpochChange: (epoch) => this.onEpochChange(epoch),
                 onWelcome: async () => undefined,
+                retryPolicy: this.connectionRetryPolicy,
             });
             await sessionManager.start();
             const systemId = sessionManager.systemId;
@@ -55055,12 +55223,12 @@
     });
 
     // This file is auto-generated during build - do not edit manually
-    // Generated from package.json version: 0.3.12
+    // Generated from package.json version: 0.3.13
     /**
      * The package version, injected at build time.
      * @internal
      */
-    const VERSION$1 = '0.3.12';
+    const VERSION$1 = '0.3.13';
 
     let initialized = false;
     const agentSdkPlugin = {
@@ -55434,6 +55602,20 @@
         return registeredAgentProxyCtor;
     }
 
+    /**
+     * Agent module providing the abstract {@link Agent} class.
+     *
+     * An Agent is a self-contained unit of work that can receive tasks, process them,
+     * and return results. Agents communicate over the Fame fabric using a standard
+     * task-based protocol.
+     *
+     * @remarks
+     * For concrete implementations:
+     * - Use {@link BaseAgent} when you need full control over task handling and state.
+     * - Use {@link BackgroundTaskAgent} for long-running or async background work.
+     *
+     * @module
+     */
     const logger$2 = getLogger('naylence.agent.agent');
     let registeredBaseAgentCtor = null;
     function requireBaseAgentCtor() {
@@ -55446,7 +55628,9 @@
     function registerBaseAgentConstructor(ctor) {
         registeredBaseAgentCtor = ctor;
     }
+    /** @internal */
     const isNodeRuntime = () => typeof process !== 'undefined' && process.release?.name === 'node';
+    /** @internal */
     const LOG_LEVEL_KEYWORDS = {
         critical: LogLevel.CRITICAL,
         error: LogLevel.ERROR,
@@ -55456,6 +55640,7 @@
         debug: LogLevel.DEBUG,
         trace: LogLevel.TRACE,
     };
+    /** @internal */
     function normalizeLogLevel(level) {
         if (typeof level === 'number') {
             if (Object.values(LogLevel).includes(level)) {
@@ -55473,6 +55658,7 @@
         }
         return level;
     }
+    /** @internal */
     class Deferred {
         constructor() {
             this.settled = false;
@@ -55494,6 +55680,7 @@
             this.internalReject(reason);
         }
     }
+    /** @internal */
     async function setupSignalHandlers(stop) {
         if (!isNodeRuntime()) {
             return () => { };
@@ -55518,6 +55705,7 @@
             }
         };
     }
+    /** @internal */
     async function acquireFabric(options) {
         const manageContext = fabricStack.length === 0;
         const fabric = await FameFabric.getOrCreate(options ?? {});
@@ -55539,19 +55727,68 @@
             },
         };
     }
+    /** @internal */
     function toFameAddress$1(value) {
         return value instanceof FameAddress ? value : new FameAddress(String(value));
     }
+    /** @internal */
     function invokeProxyRunTask(proxy, payload, taskId) {
         if (typeof proxy.runTask === 'function') {
             return proxy.runTask(payload, taskId);
         }
         throw new Error('AgentProxy must implement runTask');
     }
+    /**
+     * Abstract base class for all agents.
+     *
+     * Agents are addressable services that handle tasks over the Fame fabric.
+     * This class defines the core protocol methods every agent must implement.
+     *
+     * @remarks
+     * Do not extend Agent directly. Instead:
+     * - Extend {@link BaseAgent} for standard request-response agents.
+     * - Extend {@link BackgroundTaskAgent} for long-running background work.
+     *
+     * Use {@link Agent.remote} or {@link Agent.remoteByAddress} to create proxies
+     * for communicating with remote agents.
+     *
+     * @example
+     * ```typescript
+     * import { BaseAgent, Payload } from '@naylence/agent-sdk';
+     *
+     * class EchoAgent extends BaseAgent {
+     *   async runTask(payload: Payload): Promise<Payload> {
+     *     return payload;
+     *   }
+     * }
+     *
+     * const agent = new EchoAgent('echo');
+     * await agent.serve('fame://echo');
+     * ```
+     */
     class Agent extends RpcMixin {
+        /**
+         * Capabilities advertised by this agent for discovery.
+         */
         get capabilities() {
             return undefined;
         }
+        /**
+         * Creates a proxy for communicating with a remote agent.
+         *
+         * @remarks
+         * Provide exactly one of `address` or `capabilities` in the options.
+         *
+         * @example
+         * ```typescript
+         * const proxy = Agent.remote<EchoAgent>({ address: 'fame://echo' });
+         * const result = await proxy.runTask('hello');
+         * ```
+         *
+         * @param options - Remote agent options.
+         * @returns A proxy for the remote agent.
+         * @throws Error if both or neither of address/capabilities are provided.
+         */
         static remote(options) {
             const { address, capabilities, fabric } = options;
             const selected = Number(address != null) + Number(capabilities != null);
@@ -55568,6 +55805,13 @@
                 fabric: resolvedFabric,
             });
         }
+        /**
+         * Creates a proxy for a remote agent by its address.
+         *
+         * @param address - The target agent's address.
+         * @param options - Optional fabric configuration.
+         * @returns A proxy for the remote agent.
+         */
         static remoteByAddress(address, options = {}) {
             const remoteOptions = { address };
             if (options.fabric !== undefined) {
@@ -55575,6 +55819,13 @@
             }
             return this.remote(remoteOptions);
         }
+        /**
+         * Creates a proxy for a remote agent by required capabilities.
+         *
+         * @param capabilities - Required capabilities for discovery.
+         * @param options - Optional fabric configuration.
+         * @returns A proxy for a matching remote agent.
+         */
         static remoteByCapabilities(capabilities, options = {}) {
             const remoteOptions = { capabilities };
             if (options.fabric !== undefined) {
@@ -55582,6 +55833,15 @@
             }
             return this.remote(remoteOptions);
         }
+        /**
+         * Creates an agent from a simple handler function.
+         *
+         * @remarks
+         * Useful for quick prototyping without defining a full agent class.
+         *
+         * @param handler - Function that processes task payloads.
+         * @returns A new agent instance wrapping the handler.
+         */
         static async fromHandler(handler) {
             if (!registeredBaseAgentCtor) {
                 await Promise.resolve().then(function () { return baseAgent; });
@@ -55598,10 +55858,25 @@
             }
             return new HandlerAgent();
         }
+        /**
+         * Sends the same payload to multiple agents.
+         *
+         * @param addresses - List of agent addresses.
+         * @param payload - Payload to send to all agents.
+         * @param options - Execution options.
+         * @returns Array of [address, result|error] tuples.
+         */
         static async broadcast(addresses, payload = null, options = {}) {
             const targets = addresses.map((address) => [address, payload]);
             return this.runMany(targets, options);
         }
+        /**
+         * Runs tasks on multiple agents with individual payloads.
+         *
+         * @param targets - Iterable of [address, payload] pairs.
+         * @param options - Execution options.
+         * @returns Array of [address, result|error] tuples.
+         */
         static async runMany(targets, options = {}) {
             const { fabric, gatherExceptions = true } = options;
             const resolvedFabric = fabric ?? FameFabric.current();
@@ -55637,6 +55912,16 @@
                 return [addressKey, result.reason];
             });
         }
+        /**
+         * Starts serving this agent at the given address.
+         *
+         * @remarks
+         * In Node.js, the agent listens for SIGINT/SIGTERM to shut down gracefully.
+         * The method returns when the agent stops serving.
+         *
+         * @param address - The address to serve at (e.g., 'fame://my-agent').
+         * @param options - Serve options including log level and fabric config.
+         */
         async aserve(address, options = {}) {
             // Extract logLevel, pass everything else to fabric
             const { logLevel = null, ...fabricOptions } = options;
@@ -55665,6 +55950,12 @@
                 await release();
             }
         }
+        /**
+         * Alias for {@link Agent.aserve}.
+         *
+         * @param address - The address to serve at.
+         * @param options - Serve options.
+         */
         serve(address, options = {}) {
             return this.aserve(address, options);
         }
@@ -56098,6 +56389,7 @@
 
     var _BaseAgent_instances, _BaseAgent_createTaskFromPayloadResponse;
     const logger$1 = getLogger('naylence.agent.base_agent');
+    /** @internal */
     class StateContext {
         constructor(acquireLock, loadState, saveState) {
             this.acquireLock = acquireLock;
@@ -56329,17 +56621,20 @@
      * ```
      */
     BaseAgentState.schema = object({});
+    /** @internal */
     function camelToSnakeCase(name) {
         return name
             .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
             .replace(/([A-Z])([A-Z][a-z])/g, '$1_$2')
             .toLowerCase();
     }
+    /** @internal */
     function sanitizeNamespace(ns) {
         const replaced = ns.replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^[._-]+|[._-]+$/g, '');
         const safe = replaced.length > 0 ? replaced : 'ns';
         return safe.slice(0, 120);
     }
+    /** @internal */
     async function delay$1(ms) {
         await new Promise((resolve) => {
             const timeout = globalThis.setTimeout;
@@ -56349,19 +56644,71 @@
             timeout(resolve, ms);
         });
     }
+    /** @internal */
     function resolveRpcParams(params) {
         if (params && typeof params === 'object') {
             return params;
         }
         return {};
     }
+    /** @internal */
     function resolveReplyTarget(explicit, params) {
         const fromParams = params['reply_to'] ??
             params['replyTo'];
         const resolved = explicit ?? fromParams ?? null;
         return resolved === undefined ? null : resolved;
     }
+    /**
+     * Standard implementation of the {@link Agent} protocol.
+     *
+     * Provides built-in state management, message handling, and task lifecycle support.
+     * Extend this class and override {@link BaseAgent.runTask} to implement your agent logic.
+     *
+     * @remarks
+     * BaseAgent handles:
+     * - JSON-RPC message routing
+     * - State persistence with optional Zod validation
+     * - Task creation from runTask results
+     * - Graceful shutdown via SIGINT/SIGTERM
+     *
+     * For background/async task execution, use {@link BackgroundTaskAgent} instead.
+     *
+     * @example
+     * ```typescript
+     * import { BaseAgent, Payload, BaseAgentState } from '@naylence/agent-sdk';
+     * import { z } from 'zod';
+     *
+     * const CounterSchema = z.object({ count: z.number() });
+     *
+     * class CounterState extends BaseAgentState {
+     *   static readonly schema = CounterSchema;
+     *   count = 0;
+     * }
+     *
+     * class CounterAgent extends BaseAgent<CounterState> {
+     *   static STATE_MODEL = CounterState;
+     *
+     *   async runTask(payload: Payload): Promise<number> {
+     *     return await this.withState(async (state) => {
+     *       state.count += 1;
+     *       return state.count;
+     *     });
+     *   }
+     * }
+     *
+     * const agent = new CounterAgent('counter');
+     * await agent.serve('fame://counter');
+     * ```
+     *
+     * @typeParam StateT - The state model type, defaults to {@link BaseAgentState}.
+     */
     class BaseAgent extends Agent {
+        /**
+         * Creates a new BaseAgent.
+         *
+         * @param name - Agent name. Defaults to snake_case of the class name.
+         * @param options - Configuration options for state and storage.
+         */
         constructor(name = null, options = {}) {
             super();
             _BaseAgent_instances.add(this);
@@ -56382,9 +56729,14 @@
             this._stateKey = options.stateKey ?? 'state';
             this._stateFactory = options.stateFactory ?? null;
         }
+        /**
+         * Capabilities advertised by this agent.
+         * Includes the standard agent capability by default.
+         */
         get capabilities() {
             return [...this._capabilities];
         }
+        /** The agent's name. */
         get name() {
             return this._name;
         }
@@ -56393,12 +56745,18 @@
                 address: this._address?.toString() ?? null,
             };
         }
+        /** The address this agent is registered at. */
         get address() {
             return this._address;
         }
+        /** @internal */
         set address(value) {
             this._address = value;
         }
+        /**
+         * Storage provider for state persistence.
+         * @throws Error if no storage provider is available.
+         */
         get storageProvider() {
             if (!this._storageProvider) {
                 if (this._node) {
@@ -56423,6 +56781,7 @@
             // Look up the fabric from the registry (set by InProcessFameFabric.start())
             this._fabric = getFabricForNode(node) ?? null;
         }
+        /** @internal */
         async acquireStateLock() {
             let acquiredResolve;
             const acquired = new Promise((resolve) => {
@@ -56449,12 +56808,14 @@
                 });
             };
         }
+        /** @internal */
         ensureStateModel() {
             if (this._stateModel) {
                 return this._stateModel;
             }
             throw new Error("No state model configured. Provide via Generic, STATE_MODEL, constructor 'stateModel', or 'stateFactory'.");
         }
+        /** @internal */
         async ensureStateStore(modelType) {
             if (this._stateStore) {
                 return;
@@ -56467,12 +56828,14 @@
             const namespace = sanitizeNamespace(namespaceRaw);
             this._stateStore = await provider.getKeyValueStore(modelType, namespace);
         }
+        /** @internal */
         defaultStateNamespace() {
             if (!this._name) {
                 throw new Error("Cannot derive default state namespace without agent name. Set 'name' or provide 'stateNamespace'.");
             }
             return `__agent_${this._name}`;
         }
+        /** @internal */
         async loadStateInternal() {
             if (this._stateCache) {
                 return this._stateCache;
@@ -56502,6 +56865,7 @@
             this._stateCache = state;
             return state;
         }
+        /** @internal */
         async saveStateInternal(state) {
             const modelType = this.ensureStateModel();
             await this.ensureStateStore(modelType);
@@ -56513,15 +56877,45 @@
             await this._stateStore.set(this._stateKey, state);
             this._stateCache = state;
         }
+        /**
+         * State context for lock-protected state access.
+         *
+         * @remarks
+         * Prefer using {@link BaseAgent.withState} for simpler access patterns.
+         *
+         * @throws Error if no state model is configured.
+         */
         get state() {
             if (!this._stateModel && !this._stateFactory) {
                 throw new Error('No state model configured');
             }
             return new StateContext(() => this.acquireStateLock(), () => this.loadStateInternal(), (state) => this.saveStateInternal(state));
         }
+        /**
+         * Executes a callback with exclusive access to the agent's state.
+         *
+         * State changes are automatically persisted after the callback completes.
+         *
+         * @param callback - Function receiving the current state.
+         * @returns The callback's return value.
+         *
+         * @example
+         * ```typescript
+         * const count = await this.withState(async (state) => {
+         *   state.count += 1;
+         *   return state.count;
+         * });
+         * ```
+         */
         async withState(callback) {
             return await this.state.use(callback);
         }
+        /**
+         * Retrieves a snapshot of the current state.
+         *
+         * @remarks
+         * Returns a point-in-time copy. For modifications, use {@link BaseAgent.withState}.
+         */
         async getState() {
             const release = await this.acquireStateLock();
             try {
@@ -56531,6 +56925,9 @@
                 release();
             }
         }
+        /**
+         * Deletes all persisted state for this agent.
+         */
         async clearState() {
             const release = await this.acquireStateLock();
             try {
@@ -56543,6 +56940,7 @@
                 release();
             }
         }
+        /** @internal */
         static isRpcRequest(payload) {
             if (!payload || typeof payload !== 'object') {
                 return false;
@@ -56557,6 +56955,7 @@
             }
             return true;
         }
+        /** @internal */
         async handleMessage(envelope, _context) {
             const frame = envelope.frame;
             if (frame.type === 'DeliveryAck') {
@@ -56579,10 +56978,20 @@
             }
             return await this.handleRpcMessage(decoded, envelope);
         }
+        /**
+         * Override to handle non-RPC messages.
+         *
+         * Called when the agent receives a message that is not a JSON-RPC request.
+         * The default implementation logs a warning and returns null.
+         *
+         * @param message - The decoded message payload.
+         * @returns Optional response to send back.
+         */
         async onMessage(message) {
             logger$1.warning('unhandled_inbound_message', { message });
             return null;
         }
+        /** @internal */
         async handleRpcMessage(rpcRequest, envelope) {
             if (rpcRequest.method === 'tasks/sendSubscribe') {
                 this.startSubscriptionTask(rpcRequest, envelope.replyTo ?? null);
@@ -56619,6 +57028,7 @@
             }.bind(this);
             return generator();
         }
+        /** @internal */
         startSubscriptionTask(rpcRequest, replyTo) {
             const id = rpcRequest.id != null ? String(rpcRequest.id) : null;
             if (!id) {
@@ -56643,6 +57053,7 @@
                 });
             }
         }
+        /** @internal */
         async streamSendSubscribe(rpcRequest, replyTo, signal) {
             try {
                 const params = resolveRpcParams(rpcRequest.params);
@@ -56728,9 +57139,40 @@
         async getTaskStatus(_params) {
             throw new UnsupportedOperationException(`Agent ${this.constructor.name} does not support operation 'getTaskStatus'`);
         }
+        /**
+         * Override to implement task execution logic.
+         *
+         * This is the primary extension point for agent behavior. Return the task result
+         * or throw an error to fail the task.
+         *
+         * @param _payload - The task payload.
+         * @param _id - Optional task identifier.
+         * @returns The task result.
+         * @throws UnsupportedOperationException if not overridden.
+         *
+         * @example
+         * ```typescript
+         * async runTask(payload: Payload): Promise<string> {
+         *   const input = typeof payload === 'string' ? payload : '';
+         *   return `Hello, ${input}!`;
+         * }
+         * ```
+         */
         async runTask(_payload, _id) {
             throw new UnsupportedOperationException(`Agent ${this.constructor.name} does not support operation 'runTask'`);
         }
+        /**
+         * Initiates a task and returns its status.
+         *
+         * @remarks
+         * If you override {@link BaseAgent.runTask}, this method automatically
+         * creates a Task from the result. Override this method for custom
+         * task lifecycle management.
+         *
+         * @param params - Task parameters including message and metadata.
+         * @returns The completed task with result.
+         * @throws Error if neither startTask nor runTask is implemented.
+         */
         async startTask(params) {
             const ctor = this.constructor;
             const parts = params.message?.parts ?? [];
@@ -56758,7 +57200,9 @@
             await super.aserve(address, options);
         }
     }
-    _BaseAgent_instances = new WeakSet(), _BaseAgent_createTaskFromPayloadResponse = async function _BaseAgent_createTaskFromPayloadResponse(params, payload, runner) {
+    _BaseAgent_instances = new WeakSet(), _BaseAgent_createTaskFromPayloadResponse = 
+    /** @internal */
+    async function _BaseAgent_createTaskFromPayloadResponse(params, payload, runner) {
         const responsePayload = await runner(payload, params.id ?? null);
         let sanitizedPayload = null;
         if (typeof responsePayload === 'string') {
@@ -56774,6 +57218,10 @@
             sessionId: params.sessionId ?? null,
         });
     };
+    /**
+     * Default state model class. Override in subclasses to set state type.
+     * @internal
+     */
     BaseAgent.STATE_MODEL = null;
     registerBaseAgentConstructor(BaseAgent);
 
@@ -56784,8 +57232,27 @@
         TERMINAL_TASK_STATES: TERMINAL_TASK_STATES
     });
 
+    /**
+     * Agent base for running background work (polling/cron-like).
+     *
+     * {@link BackgroundTaskAgent} extends {@link BaseAgent} with infrastructure for
+     * long-running, asynchronous task execution. Tasks run in the background after
+     * being started, with status updates streamed to subscribers.
+     *
+     * @remarks
+     * Use BackgroundTaskAgent when:
+     * - Task execution takes significant time (seconds to minutes)
+     * - You need to report progress updates during execution
+     * - Clients should not block waiting for completion
+     *
+     * For simple request-response patterns, use {@link BaseAgent} instead.
+     *
+     * @module
+     */
     const logger = getLogger('naylence.agent.background_task_agent');
+    /** @internal */
     const DEFAULT_EVENT_QUEUE_SIZE = 1000;
+    /** @internal */
     const END_OF_STREAM_SENTINEL = Object.freeze({
         id: '__sentinel__',
         status: {
@@ -56796,13 +57263,16 @@
         final: false,
         metadata: null,
     });
+    /** @internal */
     const TIMEOUT_SYMBOL = Symbol('background-task-queue-timeout');
+    /** @internal */
     function monotonicSeconds() {
         if (typeof performance !== 'undefined' && typeof performance.now === 'function') {
             return performance.now() / 1000;
         }
         return Date.now() / 1000;
     }
+    /** @internal */
     async function delay(ms) {
         await new Promise((resolve) => {
             const timeout = globalThis.setTimeout;
@@ -56812,6 +57282,7 @@
             timeout(resolve, ms);
         });
     }
+    /** @internal */
     class AsyncEventQueue {
         constructor(maxSize) {
             this.maxSize = maxSize;
@@ -56854,6 +57325,7 @@
             }
         }
     }
+    /** @internal */
     function createTaskFromStatus(id, status) {
         return {
             id,
@@ -56864,6 +57336,7 @@
             metadata: null,
         };
     }
+    /** @internal */
     function errorToString(error) {
         if (error instanceof Error) {
             return error.message || error.toString();
@@ -56878,19 +57351,75 @@
             return String(error);
         }
     }
+    /**
+     * Base class for agents that execute long-running background tasks.
+     *
+     * Unlike {@link BaseAgent} which runs tasks synchronously in startTask,
+     * BackgroundTaskAgent starts tasks in the background and streams status
+     * updates to subscribers. This is ideal for work that takes significant time.
+     *
+     * @remarks
+     * Lifecycle:
+     * 1. Client calls startTask, which returns immediately with WORKING status
+     * 2. runBackgroundTask executes asynchronously
+     * 3. Status updates are queued and delivered to subscribers
+     * 4. Task completes with COMPLETED, FAILED, or CANCELED status
+     *
+     * Completed tasks are cached briefly for late subscribers to retrieve final status.
+     *
+     * @example
+     * ```typescript
+     * import {
+     *   BackgroundTaskAgent,
+     *   TaskSendParams,
+     *   TaskState,
+     * } from '@naylence/agent-sdk';
+     *
+     * class SlowAgent extends BackgroundTaskAgent {
+     *   protected async runBackgroundTask(params: TaskSendParams): Promise<string> {
+     *     // Report progress
+     *     await this.updateTaskState(params.id, TaskState.WORKING);
+     *
+     *     // Do expensive work
+     *     await someSlowOperation();
+     *
+     *     // Return value becomes the task result
+     *     return 'done';
+     *   }
+     * }
+     *
+     * const agent = new SlowAgent('slow-worker', {
+     *   maxTaskLifetimeMs: 60_000, // 1 minute timeout
+     * });
+     * await agent.serve('fame://slow-worker');
+     * ```
+     *
+     * @typeParam StateT - The state model type, defaults to {@link BaseAgentState}.
+     */
     class BackgroundTaskAgent extends BaseAgent {
+        /**
+         * Creates a new BackgroundTaskAgent.
+         *
+         * @param name - Agent name. Defaults to snake_case of the class name.
+         * @param options - Configuration options for task execution and caching.
+         */
         constructor(name = null, options = {}) {
             const { maxQueueSize = DEFAULT_EVENT_QUEUE_SIZE, maxTaskLifetimeMs = null, completedCacheSize = 100, completedCacheTtlSec = 300, ...baseOptions } = options;
             super(name, baseOptions);
+            /** @internal */
             this.taskStatuses = new Map();
+            /** @internal */
             this.taskEventQueues = new Map();
+            /** @internal */
             this.completed = new Map();
+            /** @internal */
             this.statusLock = new AsyncLock();
             this.maxQueueSize = maxQueueSize;
             this.maxTaskLifetimeMs = maxTaskLifetimeMs;
             this.completedCacheSize = completedCacheSize;
             this.completedCacheTtlSec = completedCacheTtlSec;
         }
+        /** @internal */
         isTerminalTaskState(taskId) {
             const status = this.taskStatuses.get(taskId);
             if (status && TERMINAL_TASK_STATES.has(status.state)) {
@@ -56898,6 +57427,15 @@
             }
             return this.completed.has(taskId);
         }
+        /**
+         * Starts a background task.
+         *
+         * Returns immediately with WORKING status. The task executes asynchronously
+         * via {@link BackgroundTaskAgent.runBackgroundTask}.
+         *
+         * @param params - Task parameters.
+         * @returns The task with initial WORKING status.
+         */
         async startTask(params) {
             this.taskEventQueues.set(params.id, new AsyncEventQueue(this.maxQueueSize));
             await this.updateTaskState(params.id, exports.TaskState.WORKING);
@@ -56907,6 +57445,7 @@
             }
             return await this.getTaskStatus({ id: params.id });
         }
+        /** @internal */
         async enforceMaxLifetime(taskId) {
             if (this.maxTaskLifetimeMs === null) {
                 return;
@@ -56920,6 +57459,7 @@
                 await queue.put(END_OF_STREAM_SENTINEL);
             }
         }
+        /** @internal */
         async runBackgroundTaskInternal(params) {
             try {
                 const result = await this.runBackgroundTask(params);
@@ -56942,6 +57482,12 @@
                 }
             }
         }
+        /**
+         * Gets the current state of a task.
+         *
+         * @param taskId - The task identifier.
+         * @returns The current task state, or UNKNOWN if not found.
+         */
         async getTaskState(taskId) {
             try {
                 const task = await this.getTaskStatus({ id: taskId });
@@ -56951,6 +57497,13 @@
                 return exports.TaskState.UNKNOWN;
             }
         }
+        /**
+         * Retrieves the full status of a task.
+         *
+         * @param params - Query parameters including the task ID.
+         * @returns The task with current status.
+         * @throws Error if the task is unknown or expired.
+         */
         async getTaskStatus(params) {
             return await this.statusLock.runExclusive(async () => {
                 const status = this.taskStatuses.get(params.id);
@@ -56967,6 +57520,17 @@
                 throw new Error(`Unknown or expired task ${params.id}`);
             });
         }
+        /**
+         * Updates the state of a running task.
+         *
+         * Call this from {@link BackgroundTaskAgent.runBackgroundTask} to report progress.
+         * Status updates are delivered to subscribers.
+         *
+         * @param taskId - The task identifier.
+         * @param state - The new task state.
+         * @param message - Optional message with details.
+         * @returns True if the update was applied, false if the task is already terminal.
+         */
         async updateTaskState(taskId, state, message) {
             return await this.statusLock.runExclusive(async () => {
                 if (this.isTerminalTaskState(taskId)) {
@@ -56998,6 +57562,7 @@
                 return true;
             });
         }
+        /** @internal */
         addToCompleted(taskId, status) {
             if (this.completedCacheSize <= 0) {
                 return;
@@ -57017,6 +57582,14 @@
                 timestamp: monotonicSeconds(),
             });
         }
+        /**
+         * Emits an artifact for a running task.
+         *
+         * Artifacts are delivered to subscribers as TaskArtifactUpdateEvents.
+         *
+         * @param taskId - The task identifier.
+         * @param artifact - The artifact to emit.
+         */
         async updateTaskArtifact(taskId, artifact) {
             const queue = this.taskEventQueues.get(taskId);
             if (!queue) {
@@ -57030,6 +57603,15 @@
             };
             await queue.put(event);
         }
+        /**
+         * Subscribes to updates for a task.
+         *
+         * Returns an async iterable that yields status and artifact events.
+         * For completed tasks, yields the cached final status if still available.
+         *
+         * @param params - Task parameters including the task ID.
+         * @returns Async iterable of task events.
+         */
         subscribeToTaskUpdates(params) {
             const queue = this.taskEventQueues.get(params.id);
             const self = this;
@@ -57073,6 +57655,11 @@
             };
             return stream();
         }
+        /**
+         * Cancels a task subscription.
+         *
+         * @param params - Parameters including the task ID.
+         */
         async unsubscribeTask(params) {
             const queue = this.taskEventQueues.get(params.id);
             if (queue) {
@@ -57080,15 +57667,26 @@
                 await queue.put(END_OF_STREAM_SENTINEL);
             }
         }
+        /**
+         * Cancels a running task.
+         *
+         * Sets the task state to CANCELED. Does not interrupt runBackgroundTask,
+         * but prevents further state updates.
+         *
+         * @param params - Parameters including the task ID.
+         * @returns The task with CANCELED status.
+         */
         async cancelTask(params) {
             await this.updateTaskState(params.id, exports.TaskState.CANCELED);
             return await this.getTaskStatus({ id: params.id });
         }
+        /** @internal */
         async purgeCompletedAfterTtl(taskId) {
             await delay(this.completedCacheTtlSec * 1000);
             this.completed.delete(taskId);
             this.taskEventQueues.delete(taskId);
         }
+        /** @internal */
         normalizeResultPayload(result) {
             if (result === null || result === undefined) {
                 return null;
@@ -57103,15 +57701,31 @@
         }
     }
 
+    /**
+     * Agent proxy module for remote agent communication.
+     *
+     * An {@link AgentProxy} is a client-side handle for invoking methods on a remote
+     * agent. Use it when you need to call an agent that lives in another process,
+     * container, or network location.
+     *
+     * @remarks
+     * Create proxies via {@link Agent.remote}, {@link Agent.remoteByAddress}, or
+     * {@link Agent.remoteByCapabilities} rather than instantiating AgentProxy directly.
+     *
+     * @module
+     */
+    /** @internal */
     function toRecord(value) {
         if (!value || typeof value !== 'object') {
             return {};
         }
         return value;
     }
+    /** @internal */
     function toFameAddress(address) {
         return address instanceof FameAddress ? address : new FameAddress(String(address));
     }
+    /** @internal */
     function wrapAgentProxy(proxy) {
         // Create RPC proxy options - only include address or capabilities, not both
         const proxyOptions = {
@@ -57140,6 +57754,7 @@
             },
         });
     }
+    /** @internal */
     async function nextWithTimeout(iterator, timeoutMs) {
         if (timeoutMs == null) {
             return await iterator.next();
@@ -57157,7 +57772,44 @@
             }
         }
     }
+    /**
+     * Client-side proxy for communicating with remote agents.
+     *
+     * AgentProxy implements the {@link Agent} interface, allowing you to call
+     * remote agents as if they were local objects. Method calls are serialized
+     * and sent over the Fame fabric.
+     *
+     * @remarks
+     * Do not instantiate AgentProxy directly. Use the factory methods on
+     * {@link Agent} to create proxies:
+     * - {@link Agent.remote} for flexible options
+     * - {@link Agent.remoteByAddress} for direct addressing
+     * - {@link Agent.remoteByCapabilities} for capability-based discovery
+     *
+     * The proxy also supports arbitrary RPC method calls. Any method not defined
+     * on the proxy class is forwarded as an RPC call to the remote agent.
+     *
+     * @example
+     * ```typescript
+     * import { Agent } from '@naylence/agent-sdk';
+     *
+     * // Create a proxy to a remote agent
+     * const proxy = Agent.remoteByAddress('fame://calculator');
+     *
+     * // Run a task synchronously
+     * const result = await proxy.runTask({ a: 1, b: 2 });
+     *
+     * // Or start a task and poll for completion
+     * const task = await proxy.startTask({
+     *   id: 'task-1',
+     *   message: { role: 'user', parts: [{ type: 'text', text: 'compute' }] },
+     * });
+     * ```
+     *
+     * @typeParam TAgent - The type of the remote agent for result typing.
+     */
     class AgentProxy extends Agent {
+        /** @internal */
         constructor(options) {
             const { address = null, capabilities = null, intentNl = null, fabric } = options;
             const provided = Number(address != null) + Number(capabilities != null) + Number(intentNl != null);
@@ -57173,9 +57825,11 @@
             this.intentNl = intentNl;
             this.fabric = fabric;
         }
+        /** Returns null as proxies do not have a local name. */
         get name() {
             return null;
         }
+        /** Returns the proxy's targeting specification. */
         get spec() {
             const spec = {
                 address: this.targetAddress ? this.targetAddress.toString() : null,
@@ -57188,15 +57842,22 @@
             }
             return spec;
         }
+        /**
+         * The target agent's address, if specified.
+         * @deprecated Use {@link AgentProxy.address} instead.
+         */
         get addressRef() {
             return this.targetAddress;
         }
+        /** The target agent's address, if specified. */
         get address() {
             return this.targetAddress;
         }
+        /** The required capabilities for discovery, if specified. */
         get capabilities() {
             return this.targetCapabilities ?? undefined;
         }
+        /** The fabric this proxy uses for communication. */
         get proxyFabric() {
             return this.fabric;
         }
@@ -57206,6 +57867,24 @@
         authenticate(_credentials) {
             throw new Error('Proxy authentication is not supported');
         }
+        /**
+         * Executes a task on the remote agent and waits for completion.
+         *
+         * Starts the task, subscribes to updates, and returns when the task reaches
+         * a terminal state (completed, failed, or canceled).
+         *
+         * @param payload - The task payload to send.
+         * @param id - Optional task identifier. Generated if not provided.
+         * @returns The task result extracted from the final status message.
+         * @throws Error if the task fails.
+         *
+         * @example
+         * ```typescript
+         * const proxy = Agent.remoteByAddress('fame://echo');
+         * const result = await proxy.runTask('hello');
+         * console.log(result); // 'hello'
+         * ```
+         */
         async runTask(payload = null, id = null) {
             const taskId = id ?? generateId();
             const params = makeTaskParams({ id: taskId, payload });
@@ -57279,16 +57958,38 @@
             const result = await this._invokeTarget('tasks/send', params);
             return TaskSchema.parse(result);
         }
+        /**
+         * Retrieves the current status of a task.
+         *
+         * @param params - Query parameters including the task ID.
+         * @returns The task with current status.
+         */
         async getTaskStatus(params) {
             const payload = TaskQueryParamsSchema.parse(params);
             const result = await this._invokeTarget('tasks/get', payload);
             return TaskSchema.parse(result);
         }
+        /**
+         * Requests cancellation of a running task.
+         *
+         * @param params - Parameters including the task ID.
+         * @returns The task with updated status.
+         */
         async cancelTask(params) {
             const payload = TaskIdParamsSchema.parse(params);
             const result = await this._invokeTarget('tasks/cancel', payload);
             return TaskSchema.parse(result);
         }
+        /**
+         * Subscribes to real-time updates for a task.
+         *
+         * Returns an async iterable that yields status and artifact events
+         * until the task reaches a terminal state or the stream is closed.
+         *
+         * @param params - Task parameters.
+         * @param options - Optional timeout and item limit settings.
+         * @returns Async iterable of task events.
+         */
         subscribeToTaskUpdates(params, options = {}) {
             const payload = TaskSendParamsSchema.parse(params);
             return this._streamRpc('tasks/sendSubscribe', payload, (frame) => {
@@ -57298,20 +57999,38 @@
                 return TaskStatusUpdateEventSchema.parse(frame);
             }, 'tasks/sendUnsubscribe', TaskIdParamsSchema.parse({ id: payload.id }), options);
         }
+        /**
+         * Cancels a task subscription.
+         *
+         * @param params - Parameters including the task ID.
+         */
         async unsubscribeTask(params) {
             const payload = TaskIdParamsSchema.parse(params);
             return await this._invokeTarget('tasks/sendUnsubscribe', payload);
         }
+        /**
+         * Registers a push notification endpoint for task updates.
+         *
+         * @param config - Push notification configuration.
+         * @returns The registered configuration.
+         */
         async registerPushEndpoint(config) {
             const payload = TaskPushNotificationConfigSchema.parse(config);
             const result = await this._invokeTarget('tasks/pushNotification/set', payload);
             return TaskPushNotificationConfigSchema.parse(result ?? payload);
         }
+        /**
+         * Retrieves the push notification config for a task.
+         *
+         * @param params - Parameters including the task ID.
+         * @returns The push notification configuration.
+         */
         async getPushNotificationConfig(params) {
             const payload = TaskIdParamsSchema.parse(params);
             const result = await this._invokeTarget('tasks/pushNotification/get', payload);
             return TaskPushNotificationConfigSchema.parse(result ?? payload);
         }
+        /** @internal */
         _streamRpc(method, params, parseFrame, unsubscribeMethod, unsubscribeParams, options) {
             const self = this;
             return {
@@ -57380,6 +58099,7 @@
                 },
             };
         }
+        /** @internal */
         async _invokeTarget(method, params, options = {}) {
             if (this.intentNl) {
                 throw new Error('Intent-based routing not yet supported');
@@ -57399,10 +58119,18 @@
             }
             throw new Error('Proxy has no routing target');
         }
+        /**
+         * Creates a proxy for a remote agent by address.
+         * @internal Use {@link Agent.remoteByAddress} instead.
+         */
         static remoteByAddress(address, options) {
             const proxy = new AgentProxy({ address, fabric: options.fabric });
             return wrapAgentProxy(proxy);
         }
+        /**
+         * Creates a proxy for a remote agent by capabilities.
+         * @internal Use {@link Agent.remoteByCapabilities} instead.
+         */
         static remoteByCapabilities(capabilities, options) {
             const proxy = new AgentProxy({ capabilities, fabric: options.fabric });
             return wrapAgentProxy(proxy);