c8ctl-plugin-nano 1.51.0 → 1.53.0

package/agentic-endpoint.mjs

@@ -108,10 +108,18 @@ function negotiatedSupport(remoteAdvertisement) {
  *   producer fences its stale predecessor on the hub's incarnation ring)
  * @param {{ claimRelease: boolean, steer: boolean }} params.support negotiated capabilities
  * @param {{ warn?: Function, debug?: Function }} [params.logger]
+ * @param {(state: 'connected' | 'disconnected') => void} [params.onConnectionState]
+ *   optional observer invoked on connection-state transitions: `'connected'`
+ *   once the transport opens and `'disconnected'` when it drops (fired at most
+ *   once per drop). A throwing observer is caught and logged, never propagated.
  * @returns {import('./supervisor.dist.js').RawEmitClient}
  */
-function openHostConnection({ url, transportFactory, incarnation, support, logger }) {
+function openHostConnection({ url, transportFactory, incarnation, support, logger, onConnectionState }) {
   const log = logger || {};
+  const notifyState = (state) => {
+    if (typeof onConnectionState !== 'function') return;
+    try { onConnectionState(state); } catch (err) { log.debug?.(`agentic onConnectionState threw — ${err?.message || err}`); }
+  };
   const openCbs = [];
   const closeCbs = [];
   let steerRoute = null;
@@ -139,7 +147,13 @@ function openHostConnection({ url, transportFactory, incarnation, support, logge
     closedFired = true;
     open = false;
     hasClosed = true;
-    for (const cb of closeCbs) cb();
+    // Guard each subscriber: a throwing onClose callback must not abort the loop
+    // or prevent notifyState('disconnected') from firing (which would strand the
+    // connection-state observer and could crash the worker/supervisor on a drop).
+    for (const cb of closeCbs) {
+      try { cb(); } catch (err) { log.debug?.(`agentic onClose subscriber threw — ${err?.message || err}`); }
+    }
+    notifyState('disconnected');
   };
 
   const send = (lane, family, payload) => {
@@ -186,7 +200,12 @@ function openHostConnection({ url, transportFactory, incarnation, support, logge
   transport = transportFactory(url, {
     onOpen() {
       open = true;
-      for (const cb of openCbs) cb();
+      // Guard each subscriber: a throwing onOpen callback must not abort the loop
+      // or prevent notifyState('connected') from firing.
+      for (const cb of openCbs) {
+        try { cb(); } catch (err) { log.debug?.(`agentic onOpen subscriber threw — ${err?.message || err}`); }
+      }
+      notifyState('connected');
     },
     onFrame(bytes) {
       handleInbound(bytes);
@@ -293,11 +312,14 @@ function openHostConnection({ url, transportFactory, incarnation, support, logge
  *   the peer's advertised support; omit to assume full support (see {@link negotiatedSupport})
  * @param {number} [opts.incarnationBase] first transcript incarnation (default `Date.now()`)
  * @param {import('@nanobpm/urban-agent-client').TransportFactory} [opts.transportFactory] injectable transport (tests)
+ * @param {(state: 'connected'|'disconnected') => void} [opts.onConnectionState] observer fired
+ *   when a connection opens/drops, so a caller can track the single host connection's
+ *   liveness (e.g. the supervisor activity marker's agentic status)
  * @param {{ warn?: Function, debug?: Function }} [opts.logger]
  * @returns {Promise<() => import('./supervisor.dist.js').RawEmitClient>} a synchronous `connect` factory
  */
 export async function createRawEmitConnect(opts) {
-  const { url, token, credential, remoteAdvertisement, incarnationBase, transportFactory, logger } = opts || {};
+  const { url, token, credential, remoteAdvertisement, incarnationBase, transportFactory, logger, onConnectionState } = opts || {};
   if (typeof url !== 'string' || url.trim() === '') {
     throw new Error('createRawEmitConnect requires an agentic channel base url');
   }
@@ -318,6 +340,7 @@ export async function createRawEmitConnect(opts) {
       incarnation: generation++,
       support,
       logger,
+      onConnectionState,
     });
 }