@opengeni/events 0.2.8 → 0.3.1

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { SessionEvent } from '@opengeni/contracts';
-import { Database, AppendEventInput } from '@opengeni/db';
+import { SessionEvent, WorkspaceControlEvent } from '@opengeni/contracts';
+import { appendSessionEvents, Database, AppendEventInput } from '@opengeni/db';
+import { connect } from 'nats';
 export { NatsConnection, connect, nkeys } from 'nats';
 
 declare function coalesceSessionEventDeltas(events: SessionEvent[]): SessionEvent[];
@@ -114,6 +115,8 @@ type EventLogger = {
 };
 type EventBusOptions = {
     logger?: EventLogger;
+    /** Test/host transport seam; production defaults to the nats.js connector. */
+    connect?: typeof connect;
 };
 
 /**
@@ -138,6 +141,22 @@ interface RequestConnection {
         timeout: number;
     }): Promise<RequestReply>;
 }
+/**
+ * The raw subscribe/publish surface the selfhosted OP-STREAM transport consumes
+ * (structurally identical to `@opengeni/runtime`'s `NatsOpStreamConnection`):
+ * a plain subscription for the runner's fire-and-forget op frames
+ * (`agent.<ws>.<id>.op.<op_id>`) and a plain publish for the server's acks
+ * (`agent.<ws>.<id>.ack`). Same managed connection as everything else — a NATS
+ * connection natively supports all of it; there is NEVER a second connection.
+ */
+interface OpStreamConnection {
+    subscribe(subject: string): AsyncIterable<{
+        data: Uint8Array;
+    }> & {
+        unsubscribe(): void;
+    };
+    publish(subject: string, payload: Uint8Array): void;
+}
 /**
  * A handler answering a request/reply on a subscribed subject: given the request
  * bytes (+ the concrete subject the message landed on, for `agent.<ws>.<id>.rpc`
@@ -149,6 +168,10 @@ type RequestHandler = (request: Uint8Array, subject: string) => Promise<Uint8Arr
 type EventBus = {
     publish: (workspaceId: string, sessionId: string, events: SessionEvent[]) => Promise<void>;
     subscribe: (workspaceId: string, sessionId: string, onEvents: (events: SessionEvent[]) => void | Promise<void>) => Promise<() => void>;
+    /** Best-effort live invalidation; the event is already durable in Postgres. */
+    publishWorkspaceControl: (workspaceId: string, event: WorkspaceControlEvent) => Promise<void>;
+    /** One workspace subscription fans a control change to every open descendant view. */
+    subscribeWorkspaceControl: (workspaceId: string, onEvent: (event: WorkspaceControlEvent) => void | Promise<void>) => Promise<() => void>;
     /**
      * Issue a binary request/reply on a subject over the bus's NATS connection
      * (the selfhosted control plane: `agent.<ws>.<id>.rpc`). A new usage of what was
@@ -182,6 +205,12 @@ type EventBus = {
      * plane injects this so the transport never opens a second connection.
      */
     getRequestConnection: () => RequestConnection;
+    /**
+     * The `OpStreamConnection` accessor the selfhosted op-stream transport
+     * consumes (`NatsOpStreamTransport`) — the same managed connection again.
+     * Optional so bus test doubles that never exercise op-stream stay valid.
+     */
+    getOpStreamConnection?: () => OpStreamConnection;
     isConnected?: () => boolean;
     close: () => Promise<void>;
 };
@@ -237,8 +266,56 @@ type NatsConnectAuth = {
 declare function createResponderConnection(natsUrl: string, auth: NatsConnectAuth, subject: string, handler: RequestHandler, options?: {
     name?: string;
     logger?: EventLogger;
+    connect?: typeof connect;
 }): Promise<ResponderConnection>;
-declare function appendAndPublishEvents(db: Database, bus: EventBus, workspaceId: string, sessionId: string, events: AppendEventInput[]): Promise<SessionEvent[]>;
-declare function formatSse(event: SessionEvent): string;
+/**
+ * Optional timing seam for {@link appendAndPublishEvents}: `onAppend` fires after
+ * the durable DB write, `onPublish` after the best-effort live fan-out (on both
+ * success AND failure of the publish, so a broker blip still records its latency).
+ * Kept as a plain callback so the events package takes no dependency on the
+ * observability package; the worker wires it to Prometheus histograms.
+ */
+type AppendPublishObserver = {
+    onAppend?: (info: {
+        durationSeconds: number;
+        count: number;
+    }) => void;
+    onPublish?: (info: {
+        durationSeconds: number;
+        count: number;
+    }) => void;
+};
+type AppendPublishOptions = AppendPublishObserver & {
+    /** Test/host persistence seam; production uses the database implementation. */
+    appendSessionEvents?: typeof appendSessionEvents;
+};
+/**
+ * Invoke a phase-timing callback with the elapsed seconds since `startedAt` and the
+ * event count, swallowing any throw so a metrics sink can never break the
+ * append/publish path. Exported for direct unit testing: the wider test suite
+ * installs a process-global `mock.module("@opengeni/events")` that stubs
+ * `appendAndPublishEvents` (spreading the real module for everything else), so the
+ * observer wiring can only be exercised through a helper that survives that mock.
+ */
+declare function observeSince(fn: ((info: {
+    durationSeconds: number;
+    count: number;
+}) => void) | undefined, startedAt: number, count: number): void;
+declare function appendAndPublishEvents(db: Database, bus: EventBus, workspaceId: string, sessionId: string, events: AppendEventInput[], options?: AppendPublishOptions): Promise<SessionEvent[]>;
+/**
+ * Best-effort live fanout for events another DB helper already committed in
+ * the same transaction as related durable state. This must never append again.
+ */
+declare function publishDurableSessionEvents(bus: EventBus, workspaceId: string, sessionId: string, appended: SessionEvent[], observe?: AppendPublishObserver): Promise<void>;
+/** Best-effort fanout for a workspace-control event already committed in PostgreSQL. */
+declare function publishDurableWorkspaceControlEvent(bus: EventBus, workspaceId: string, event: WorkspaceControlEvent): Promise<void>;
+declare function appendAndPublishTurnEventsFenced(db: Database, bus: EventBus, workspaceId: string, sessionId: string, turnId: string, executionGeneration: number, attemptId: string, events: AppendEventInput[]): Promise<{
+    events: SessionEvent[];
+    accepted: boolean;
+}>;
+declare function formatSse<T extends {
+    sequence: number;
+    type: string;
+}>(event: T): string;
 
-export { type DecodedAuthRequest, type EventBus, type EventBusOptions, type EventLogger, type MintAuthResponseInput, type MintUserJwtInput, type NatsConnectAuth, type NatsPermission, type NatsPermissions, type RequestConnection, type RequestHandler, type RequestReply, type ResponderConnection, appendAndPublishEvents, coalesceSessionEventDeltas, createNatsEventBus, createResponderConnection, decodeAuthRequest, formatSse, mintAuthResponse, mintUserJwt, workspaceAgentPermissions };
+export { type AppendPublishObserver, type AppendPublishOptions, type DecodedAuthRequest, type EventBus, type EventBusOptions, type EventLogger, type MintAuthResponseInput, type MintUserJwtInput, type NatsConnectAuth, type NatsPermission, type NatsPermissions, type OpStreamConnection, type RequestConnection, type RequestHandler, type RequestReply, type ResponderConnection, appendAndPublishEvents, appendAndPublishTurnEventsFenced, coalesceSessionEventDeltas, createNatsEventBus, createResponderConnection, decodeAuthRequest, formatSse, mintAuthResponse, mintUserJwt, observeSince, publishDurableSessionEvents, publishDurableWorkspaceControlEvent, workspaceAgentPermissions };

package/dist/index.js

@@ -1,6 +1,13 @@
 // src/index.ts
-import { appendSessionEvents, sessionSubject } from "@opengeni/db";
-import { connect, JSONCodec } from "nats";
+import {
+  appendSessionEvents,
+  appendSessionEventsForTurnAttempt,
+  sessionSubject
+} from "@opengeni/db";
+import {
+  connect,
+  JSONCodec
+} from "nats";
 
 // src/coalesce.ts
 var COALESCIBLE_DELTA_TYPES = /* @__PURE__ */ new Set([
@@ -17,13 +24,17 @@ function coalesceSessionEventDeltas(events) {
     }
     coalesced.push({
       ...run.first,
-      payload: run.first.type === "sandbox.command.output.delta" ? {
-        chunk: run.text,
-        coalescedUntil: run.lastSequence,
-        ...run.sandboxStream !== void 0 ? { stream: run.sandboxStream } : {},
-        ...run.sandboxCommandId !== void 0 ? { commandId: run.sandboxCommandId } : {},
-        ...run.sandboxName !== void 0 ? { name: run.sandboxName } : {}
-      } : {
+      payload: run.first.type === "sandbox.command.output.delta" ? (
+        // Sandbox output keeps its CANONICAL field (`chunk` — the terminal and
+        // projection read it) plus the stream/commandId identity of the run.
+        {
+          chunk: run.text,
+          coalescedUntil: run.lastSequence,
+          ...run.sandboxStream !== void 0 ? { stream: run.sandboxStream } : {},
+          ...run.sandboxCommandId !== void 0 ? { commandId: run.sandboxCommandId } : {},
+          ...run.sandboxName !== void 0 ? { name: run.sandboxName } : {}
+        }
+      ) : {
         text: run.text,
         coalescedUntil: run.lastSequence
       }
@@ -318,7 +329,7 @@ async function createNatsEventBus(natsUrl, auth, options = {}) {
     connectOptions.user = auth.user;
     connectOptions.pass = auth.pass;
   }
-  const nc = await connect(withReconnectDefaults(connectOptions));
+  const nc = await (options.connect ?? connect)(withReconnectDefaults(connectOptions));
   let connected = true;
   logConnectionStatus(nc, "event-bus", options.logger, (type) => {
     if (type === "disconnect" || type === "reconnecting" || type === "staleConnection" || type === "error") {
@@ -330,28 +341,66 @@ async function createNatsEventBus(natsUrl, auth, options = {}) {
   const requestConnection = {
     request: async (subject, payload, opts) => requestReply(nc, subject, payload, opts.timeout)
   };
+  const opStreamConnection = {
+    subscribe: (subject) => nc.subscribe(subject),
+    publish: (subject, payload) => {
+      nc.publish(subject, payload);
+    }
+  };
   return {
     publish: async (workspaceId, sessionId, events) => {
       if (events.length === 0) {
         return;
       }
       try {
-        nc.publish(sessionSubject(workspaceId, sessionId), codec.encode({ workspaceId, sessionId, events }));
+        nc.publish(
+          sessionSubject(workspaceId, sessionId),
+          codec.encode({ workspaceId, sessionId, events })
+        );
       } catch (error) {
-        (options.logger?.warn ?? silentLogger.warn)("NATS live publish dropped; events are durable in the DB and reconcile on stream replay", {
-          workspaceId,
-          sessionId,
-          error: error instanceof Error ? error.message : String(error)
-        });
+        (options.logger?.warn ?? silentLogger.warn)(
+          "NATS live publish dropped; events are durable in the DB and reconcile on stream replay",
+          {
+            workspaceId,
+            sessionId,
+            error: error instanceof Error ? error.message : String(error)
+          }
+        );
         return;
       }
       await flushWithTimeout(nc, PUBLISH_FLUSH_TIMEOUT_MS);
     },
     subscribe: async (workspaceId, sessionId, onEvents) => subscribeSession(nc, workspaceId, sessionId, onEvents),
+    publishWorkspaceControl: async (workspaceId, event) => {
+      try {
+        nc.publish(workspaceControlSubject(workspaceId), codec.encode(event));
+      } catch (error) {
+        (options.logger?.warn ?? silentLogger.warn)(
+          "NATS workspace-control invalidation dropped; clients reconcile from Postgres",
+          {
+            workspaceId,
+            revision: event.revision,
+            error: error instanceof Error ? error.message : String(error)
+          }
+        );
+        return;
+      }
+      await flushWithTimeout(nc, PUBLISH_FLUSH_TIMEOUT_MS);
+    },
+    subscribeWorkspaceControl: async (workspaceId, onEvent) => {
+      const sub = nc.subscribe(workspaceControlSubject(workspaceId));
+      void (async () => {
+        for await (const msg of sub) {
+          await onEvent(codec.decode(msg.data));
+        }
+      })();
+      return () => sub.unsubscribe();
+    },
     request: async (subject, payload, opts) => requestReply(nc, subject, payload, opts.timeoutMs),
     subscribeRequests: (subject, handler) => subscribeRequests(nc, subject, handler),
     subscribeAgentEvents: (subject, handler) => subscribeAgentEvents(nc, subject, handler),
     getRequestConnection: () => requestConnection,
+    getOpStreamConnection: () => opStreamConnection,
     isConnected: () => connected && !nc.isClosed() && !nc.isDraining(),
     close: async () => {
       await nc.drain();
@@ -369,8 +418,12 @@ async function createResponderConnection(natsUrl, auth, subject, handler, option
   } else if (auth.kind === "token") {
     connectOptions.token = auth.token;
   }
-  const nc = await connect(withReconnectDefaults(connectOptions));
-  logConnectionStatus(nc, options.name ? `auth-callout:${options.name}` : "auth-callout", options.logger);
+  const nc = await (options.connect ?? connect)(withReconnectDefaults(connectOptions));
+  logConnectionStatus(
+    nc,
+    options.name ? `auth-callout:${options.name}` : "auth-callout",
+    options.logger
+  );
   const sub = nc.subscribe(subject);
   void (async () => {
     for await (const msg of sub) {
@@ -391,8 +444,32 @@ async function createResponderConnection(natsUrl, auth, subject, handler, option
     }
   };
 }
-async function appendAndPublishEvents(db, bus, workspaceId, sessionId, events) {
-  const appended = await appendSessionEvents(db, workspaceId, sessionId, events);
+function observeSince(fn, startedAt, count) {
+  if (!fn) {
+    return;
+  }
+  try {
+    fn({ durationSeconds: Math.max(0, (performance.now() - startedAt) / 1e3), count });
+  } catch {
+  }
+}
+async function appendAndPublishEvents(db, bus, workspaceId, sessionId, events, options = {}) {
+  const appendStartedAt = performance.now();
+  const appended = await (options.appendSessionEvents ?? appendSessionEvents)(
+    db,
+    workspaceId,
+    sessionId,
+    events
+  );
+  observeSince(options.onAppend, appendStartedAt, appended.length);
+  await publishDurableSessionEvents(bus, workspaceId, sessionId, appended, options);
+  return appended;
+}
+async function publishDurableSessionEvents(bus, workspaceId, sessionId, appended, observe) {
+  if (appended.length === 0) {
+    return;
+  }
+  const publishStartedAt = performance.now();
   try {
     await bus.publish(workspaceId, sessionId, appended);
   } catch (error) {
@@ -401,7 +478,38 @@ async function appendAndPublishEvents(db, bus, workspaceId, sessionId, events) {
       error
     );
   }
-  return appended;
+  observeSince(observe?.onPublish, publishStartedAt, appended.length);
+}
+async function publishDurableWorkspaceControlEvent(bus, workspaceId, event) {
+  try {
+    await bus.publishWorkspaceControl(workspaceId, event);
+  } catch (error) {
+    console.warn(
+      `[events] workspace-control live publish failed for ${workspaceId} at revision ${event.revision}; the event is durable and reconciles on stream replay`,
+      error
+    );
+  }
+}
+async function appendAndPublishTurnEventsFenced(db, bus, workspaceId, sessionId, turnId, executionGeneration, attemptId, events) {
+  const result = await appendSessionEventsForTurnAttempt(
+    db,
+    workspaceId,
+    sessionId,
+    turnId,
+    executionGeneration,
+    attemptId,
+    events
+  );
+  if (result.events.length === 0) return result;
+  try {
+    await bus.publish(workspaceId, sessionId, result.events);
+  } catch (error) {
+    console.warn(
+      `[events] live fenced publish failed for ${workspaceId}/${sessionId}/${turnId}@${executionGeneration}/${attemptId}; ${result.events.length} event(s) are durable`,
+      error
+    );
+  }
+  return result;
 }
 function subscribeSession(nc, workspaceId, sessionId, onEvents) {
   const sub = nc.subscribe(sessionSubject(workspaceId, sessionId));
@@ -461,8 +569,12 @@ function formatSse(event) {
     ""
   ].join("\n");
 }
+function workspaceControlSubject(workspaceId) {
+  return `workspaces.${workspaceId}.control`;
+}
 export {
   appendAndPublishEvents,
+  appendAndPublishTurnEventsFenced,
   coalesceSessionEventDeltas,
   connect2 as connect,
   createNatsEventBus,
@@ -472,6 +584,9 @@ export {
   mintAuthResponse,
   mintUserJwt,
   nkeys2 as nkeys,
+  observeSince,
+  publishDurableSessionEvents,
+  publishDurableWorkspaceControlEvent,
   workspaceAgentPermissions
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/coalesce.ts","../src/nats-jwt.ts"],"sourcesContent":["import type { SessionBusMessage, SessionEvent } from \"@opengeni/contracts\";\nimport { appendSessionEvents, sessionSubject, type AppendEventInput, type Database } from \"@opengeni/db\";\nimport { connect, JSONCodec, type ConnectionOptions, type Msg, type NatsConnection, type Subscription } from \"nats\";\n\nconst codec = JSONCodec<SessionBusMessage | SessionEvent>();\n\nexport type EventLogger = {\n  debug?: (message: string, attributes?: Record<string, unknown>) => void;\n  warn?: (message: string, attributes?: Record<string, unknown>) => void;\n};\n\nexport type EventBusOptions = {\n  logger?: EventLogger;\n};\n\nconst silentLogger: Required<EventLogger> = {\n  debug: () => {},\n  warn: () => {},\n};\n\nexport { coalesceSessionEventDeltas } from \"./coalesce\";\n\n/**\n * Reconnect + keepalive defaults applied to EVERY long-lived NATS connection\n * this package opens (the event bus AND the standalone auth-callout responder).\n *\n * The production outage these guard against: an in-cluster NATS broker pod\n * restart. nats.js's stock policy gives up after ~10 attempts (~20s) and the\n * client goes permanently CONNECTION_CLOSED — which takes the whole control\n * plane down with it: every session-create publishes events to NATS, and the\n * API-hosted auth-callout responder dies so BYO agents get \"authorization\n * violation\". Recovery then required a MANUAL api+worker restart. With these\n * options the client retries forever and auto-recovers the moment the broker\n * returns. Factored into one source of truth so the call sites never drift.\n *\n *  - `reconnect` + `maxReconnectAttempts: -1` — never give up (infinite retry).\n *  - `reconnectTimeWait` (2s base) + `reconnectJitter`/`reconnectJitterTLS`\n *    (up to 1s) — a fleet of api/worker pods doesn't thundering-herd the broker\n *    on recovery.\n *  - `waitOnFirstConnect` — a broker briefly unavailable at boot must not\n *    hard-fail the process; the client keeps trying instead of throwing.\n *  - `pingInterval`/`maxPingOut` — promptly detect a silently-dead socket so the\n *    reconnect machinery actually engages instead of hanging on a zombie.\n */\nconst RECONNECT_OPTIONS = {\n  reconnect: true,\n  maxReconnectAttempts: -1,\n  reconnectTimeWait: 2_000,\n  reconnectJitter: 1_000,\n  reconnectJitterTLS: 1_000,\n  waitOnFirstConnect: true,\n  pingInterval: 20_000,\n  maxPingOut: 3,\n} satisfies ConnectionOptions;\n\n/**\n * The single source of truth for a long-lived connection's resilience: merge the\n * reconnect/keepalive defaults UNDER the caller's connection options (servers +\n * optional auth/name). Every long-lived `connect()` in this package goes through\n * here so the two call sites can never diverge.\n */\nfunction withReconnectDefaults(options: ConnectionOptions): ConnectionOptions {\n  return { ...RECONNECT_OPTIONS, ...options };\n}\n\n/** How long a best-effort publish waits on `flush()` before giving up (see `publish`). */\nconst PUBLISH_FLUSH_TIMEOUT_MS = 2_000;\n\n/**\n * Await `nc.flush()` but never longer than `timeoutMs`. With infinite reconnect a\n * `flush()` issued while the broker is down does NOT reject — it pends until the\n * broker returns, which can be minutes. Racing it against a timer keeps a long\n * outage from stalling an in-flight turn; the published message stays buffered\n * and is delivered on reconnect regardless. A flush rejection (connection fully\n * CLOSED) is swallowed here so the timeout race never leaks an unhandled\n * rejection — the caller's publish path is what logs the drop.\n */\nasync function flushWithTimeout(nc: NatsConnection, timeoutMs: number): Promise<void> {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  const timeout = new Promise<void>((resolve) => {\n    timer = setTimeout(resolve, timeoutMs);\n  });\n  try {\n    await Promise.race([nc.flush().catch(() => undefined), timeout]);\n  } finally {\n    if (timer) {\n      clearTimeout(timer);\n    }\n  }\n}\n\n/**\n * Drain a long-lived connection's status async-iterator to the log so a future\n * broker outage is OBSERVABLE (disconnect → reconnecting → reconnect → update).\n * Fire-and-forget for the connection's lifetime; the loop ends when the\n * connection closes. `label` distinguishes the event-bus connection from the\n * auth-callout responder in the logs.\n */\nfunction logConnectionStatus(\n  nc: NatsConnection,\n  label: string,\n  logger: EventLogger = silentLogger,\n  onStatus?: (type: string) => void,\n): void {\n  void (async () => {\n    try {\n      for await (const status of nc.status()) {\n        onStatus?.(status.type);\n        const attributes = { label, status: status.type, data: status.data };\n        if (isWarnNatsStatus(status.type)) {\n          (logger.warn ?? silentLogger.warn)(\"NATS connection status\", attributes);\n        } else {\n          (logger.debug ?? silentLogger.debug)(\"NATS connection status\", attributes);\n        }\n      }\n    } catch {\n      // The status iterator simply ends when the connection closes; never let it\n      // throw out of this background loop.\n    }\n  })();\n}\n\nfunction isWarnNatsStatus(type: string): boolean {\n  return type === \"disconnect\" || type === \"error\" || type === \"staleConnection\";\n}\n\nexport {\n  decodeAuthRequest,\n  mintAuthResponse,\n  mintUserJwt,\n  workspaceAgentPermissions,\n  type DecodedAuthRequest,\n  type MintAuthResponseInput,\n  type MintUserJwtInput,\n  type NatsPermission,\n  type NatsPermissions,\n} from \"./nats-jwt\";\n\n// Re-export the raw NATS primitives a consumer needs to open a direct connection or\n// generate nkeys (the auth-callout responder's standalone connection, the\n// agent-simulating integration tests). This keeps `nats` an internal dependency of\n// this leaf — callers in the bun workspace reach it through @opengeni/events rather\n// than depending on `nats` directly.\nexport { connect, nkeys, type NatsConnection } from \"nats\";\n\n/**\n * A raw request/reply reply — just the response bytes. Mirrors the subset of the\n * NATS `Msg` shape a binary request/reply caller needs (`NatsControlRpc` consumes\n * exactly this). Kept minimal so the events package does not leak the `nats` `Msg`\n * type into the agent-loop-free runtime leaf.\n */\nexport type RequestReply = { data: Uint8Array };\n\n/**\n * The minimal request/reply connection the selfhosted control plane consumes\n * (structurally identical to `@opengeni/runtime`'s `NatsRequestConnection`). The\n * API/worker hand this accessor to `NatsControlRpc` so the control transport rides\n * the SAME managed NATS connection the event bus already owns — a NATS connection\n * natively supports both pub/sub and request/reply, so there is NEVER a second\n * connection.\n */\nexport interface RequestConnection {\n  request(subject: string, payload: Uint8Array, opts: { timeout: number }): Promise<RequestReply>;\n}\n\n/**\n * A handler answering a request/reply on a subscribed subject: given the request\n * bytes (+ the concrete subject the message landed on, for `agent.<ws>.<id>.rpc`\n * style wildcard routing), return the response bytes to reply with. A thrown error\n * leaves the request unanswered (the caller's request times out / sees no\n * responder), which the control plane maps to `agent_offline` / reconnecting.\n */\nexport type RequestHandler = (request: Uint8Array, subject: string) => Promise<Uint8Array> | Uint8Array;\n\nexport type EventBus = {\n  publish: (workspaceId: string, sessionId: string, events: SessionEvent[]) => Promise<void>;\n  subscribe: (workspaceId: string, sessionId: string, onEvents: (events: SessionEvent[]) => void | Promise<void>) => Promise<() => void>;\n  /**\n   * Issue a binary request/reply on a subject over the bus's NATS connection\n   * (the selfhosted control plane: `agent.<ws>.<id>.rpc`). A new usage of what was\n   * a one-way bus — same connection, native NATS request/reply. Rejects on a\n   * no-responder (NATS 503) or a request timeout; the caller (`NatsControlRpc`)\n   * maps those to `agent_offline` / `agent_reconnecting`, never a NotFound.\n   */\n  request: (subject: string, payload: Uint8Array, opts: { timeoutMs: number }) => Promise<RequestReply>;\n  /**\n   * Subscribe-and-reply on a subject (the responder side — the enrolled agent, or\n   * a test stand-in for it): for every request on `subject`, call `handler` and\n   * `respond` with its bytes over the SAME connection. Returns an unsubscribe fn.\n   * A subject may be a NATS wildcard (e.g. `agent.*.*.rpc`).\n   */\n  subscribeRequests: (subject: string, handler: RequestHandler) => () => void;\n  /**\n   * Subscribe to the agent EVENT plane (the one-way fire-and-forget heartbeats +\n   * going-offline the agent PUBLISHES on `agent.<ws>.<id>.events`, NOT a\n   * request/reply). The M10 metrics-ingestion consumer subscribes the wildcard\n   * `agent.*.*.events` and gets each raw payload plus its concrete subject (so it\n   * can extract `<ws>`/`<id>` for the per-enrollment upsert). Returns an\n   * unsubscribe fn. Decoding the AgentEvent is the caller's concern (this leaf\n   * does not depend on `@opengeni/agent-proto`).\n   */\n  subscribeAgentEvents: (\n    subject: string,\n    handler: (payload: Uint8Array, subject: string) => void | Promise<void>,\n  ) => () => void;\n  /**\n   * The `RequestConnection` accessor the selfhosted `NatsControlRpc` consumes —\n   * the SAME managed connection (pub/sub + request/reply share it). The control\n   * plane injects this so the transport never opens a second connection.\n   */\n  getRequestConnection: () => RequestConnection;\n  isConnected?: () => boolean;\n  close: () => Promise<void>;\n};\n\n/**\n * Connect the event bus + control-plane request/reply over ONE managed NATS\n * connection. `auth` is the PRIVILEGED control-plane login (M-AUTH): when the\n * server runs with auth_callout, the api/worker authenticates as a static account\n * user permitted to request `agent.*.rpc` + receive its inbox replies. When `auth`\n * is omitted the connection is anonymous (local dev / a NATS without auth_callout)\n * — the existing behavior, unchanged.\n */\nexport async function createNatsEventBus(\n  natsUrl: string,\n  auth?: { user: string; pass: string },\n  options: EventBusOptions = {},\n): Promise<EventBus> {\n  const connectOptions: ConnectionOptions = { servers: natsUrl };\n  if (auth) {\n    connectOptions.user = auth.user;\n    connectOptions.pass = auth.pass;\n  }\n  const nc = await connect(withReconnectDefaults(connectOptions));\n  let connected = true;\n  logConnectionStatus(nc, \"event-bus\", options.logger, (type) => {\n    if (type === \"disconnect\" || type === \"reconnecting\" || type === \"staleConnection\" || type === \"error\") {\n      connected = false;\n    } else if (type === \"connect\" || type === \"reconnect\") {\n      connected = true;\n    }\n  });\n  const requestConnection: RequestConnection = {\n    request: async (subject, payload, opts) => requestReply(nc, subject, payload, opts.timeout),\n  };\n  return {\n    publish: async (workspaceId, sessionId, events) => {\n      if (events.length === 0) {\n        return;\n      }\n      // Best-effort LIVE fan-out. These events are ALREADY durably appended to\n      // the DB before we get here (they carry a DB-assigned `sequence`), and\n      // every consumer reconciles from that durable log — the server SSE stream\n      // replays + gap-backfills via `listSessionEvents`, and the SDK client\n      // reconnects and replays from the durable events endpoint. So a publish\n      // that fails during a broker blip only delays LIVE delivery (healed by the\n      // next successful publish's gap-backfill, or a stream reconnect); it must\n      // never throw the in-flight turn to death.\n      try {\n        nc.publish(sessionSubject(workspaceId, sessionId), codec.encode({ workspaceId, sessionId, events }));\n      } catch (error) {\n        // `publish()` throws synchronously only when the connection is fully\n        // CLOSED (with infinite reconnect, effectively never outside shutdown).\n        (options.logger?.warn ?? silentLogger.warn)(\"NATS live publish dropped; events are durable in the DB and reconcile on stream replay\", {\n          workspaceId,\n          sessionId,\n          error: error instanceof Error ? error.message : String(error),\n        });\n        return;\n      }\n      await flushWithTimeout(nc, PUBLISH_FLUSH_TIMEOUT_MS);\n    },\n    subscribe: async (workspaceId, sessionId, onEvents) => subscribeSession(nc, workspaceId, sessionId, onEvents),\n    request: async (subject, payload, opts) => requestReply(nc, subject, payload, opts.timeoutMs),\n    subscribeRequests: (subject, handler) => subscribeRequests(nc, subject, handler),\n    subscribeAgentEvents: (subject, handler) => subscribeAgentEvents(nc, subject, handler),\n    getRequestConnection: () => requestConnection,\n    isConnected: () => connected && !nc.isClosed() && !nc.isDraining(),\n    close: async () => {\n      await nc.drain();\n    },\n  };\n}\n\n/**\n * A standalone NATS connection answering request/reply on ONE subject — the\n * transport primitive the auth-callout responder uses. It is DELIBERATELY a\n * SEPARATE connection from the event bus: the callout responder authenticates as\n * the callout account's `auth_users` user (a username/password or token in the\n * `AUTH` account), which is a DIFFERENT identity from the control-plane's\n * privileged account that the event bus + `NatsControlRpc` ride. One connection\n * per identity; never multiplex the two.\n *\n * `request`/`reply` here is the RAW NATS request/reply (`$SYS.REQ.USER.AUTH`): the\n * server publishes an authorization request with a reply inbox; the handler returns\n * the signed authorization-response bytes which we `respond` on that inbox.\n */\nexport interface ResponderConnection {\n  /** Subscribe-and-reply on `subject`; returns an async close that drains. */\n  close: () => Promise<void>;\n}\n\n/** Connection auth for a standalone NATS connection (the callout responder). */\nexport type NatsConnectAuth =\n  | { kind: \"user-password\"; user: string; pass: string }\n  | { kind: \"token\"; token: string }\n  | { kind: \"anonymous\" };\n\n/**\n * Open a standalone NATS connection and subscribe `subject`, replying to every\n * request with `handler(requestBytes, subject)`. Used by the auth-callout\n * responder to serve `$SYS.REQ.USER.AUTH` as the callout auth user. Returns a\n * handle whose `close()` drains the connection. A handler that throws leaves the\n * request UNANSWERED — for auth-callout that means the server denies the\n * connection on its own timeout, which is the correct fail-closed behavior (a\n * responder bug must never accidentally grant access).\n */\nexport async function createResponderConnection(\n  natsUrl: string,\n  auth: NatsConnectAuth,\n  subject: string,\n  handler: RequestHandler,\n  options: { name?: string; logger?: EventLogger } = {},\n): Promise<ResponderConnection> {\n  const connectOptions: ConnectionOptions = { servers: natsUrl };\n  if (options.name) {\n    connectOptions.name = options.name;\n  }\n  if (auth.kind === \"user-password\") {\n    connectOptions.user = auth.user;\n    connectOptions.pass = auth.pass;\n  } else if (auth.kind === \"token\") {\n    connectOptions.token = auth.token;\n  }\n  const nc = await connect(withReconnectDefaults(connectOptions));\n  logConnectionStatus(nc, options.name ? `auth-callout:${options.name}` : \"auth-callout\", options.logger);\n  const sub: Subscription = nc.subscribe(subject);\n  void (async () => {\n    for await (const msg of sub) {\n      if (!msg.reply) {\n        continue;\n      }\n      try {\n        const reply = await handler(msg.data, msg.subject);\n        msg.respond(reply);\n      } catch {\n        // Leave UNANSWERED — fail-closed. The server denies the connect attempt\n        // on its callout timeout; a responder error never grants access.\n      }\n    }\n  })();\n  return {\n    close: async () => {\n      sub.unsubscribe();\n      await nc.drain();\n    },\n  };\n}\n\nexport async function appendAndPublishEvents(db: Database, bus: EventBus, workspaceId: string, sessionId: string, events: AppendEventInput[]): Promise<SessionEvent[]> {\n  const appended = await appendSessionEvents(db, workspaceId, sessionId, events);\n  // The DB append above is the durable system of record; the publish is only a\n  // best-effort LIVE fan-out. Guard it so NO EventBus implementation can throw an\n  // in-flight agent turn to death on a transient NATS disconnect — consumers\n  // reconcile any missed live events from the durable log via the events/stream\n  // endpoint (DB replay + gap-backfill). The managed `createNatsEventBus` bus\n  // already swallows internally, so this catch is the belt-and-suspenders guard\n  // for any other bus impl (and a fully CLOSED connection during shutdown).\n  try {\n    await bus.publish(workspaceId, sessionId, appended);\n  } catch (error) {\n    console.warn(\n      `[events] live publish failed for ${workspaceId}/${sessionId}; ${appended.length} event(s) are durable and reconcile on stream replay`,\n      error,\n    );\n  }\n  return appended;\n}\n\nfunction subscribeSession(nc: NatsConnection, workspaceId: string, sessionId: string, onEvents: (events: SessionEvent[]) => void | Promise<void>): () => void {\n  const sub: Subscription = nc.subscribe(sessionSubject(workspaceId, sessionId));\n  void (async () => {\n    for await (const msg of sub) {\n      const decoded = codec.decode(msg.data) as SessionBusMessage | SessionEvent;\n      const events = \"events\" in decoded ? decoded.events : [decoded];\n      await onEvents(events);\n    }\n  })();\n  return () => {\n    sub.unsubscribe();\n  };\n}\n\n/**\n * A binary request/reply over the managed connection. Returns ONLY the reply\n * bytes (the `RequestReply` shape) — the request/reply error semantics (a\n * no-responder NATS 503, a request timeout) propagate as the rejected promise so\n * the caller owns the mapping. The reply is delivered via the connection's\n * built-in mux inbox; no extra subscription is created here.\n */\nasync function requestReply(nc: NatsConnection, subject: string, payload: Uint8Array, timeout: number): Promise<RequestReply> {\n  const msg: Msg = await nc.request(subject, payload, { timeout });\n  return { data: msg.data };\n}\n\n/**\n * Subscribe to `subject` and reply to every request with the handler's bytes,\n * over the SAME connection. The responder side of request/reply: each delivered\n * `Msg` carries a `reply` inbox; `msg.respond(bytes)` publishes the answer there.\n * A handler that throws (or a message with no `reply` subject) is left unanswered\n * — the requester then sees a timeout, never a malformed reply.\n */\nfunction subscribeRequests(nc: NatsConnection, subject: string, handler: RequestHandler): () => void {\n  const sub: Subscription = nc.subscribe(subject);\n  void (async () => {\n    for await (const msg of sub) {\n      // A request always carries a reply inbox; a plain publish to this subject\n      // (no reply) is ignored — request/reply is the only contract here.\n      if (!msg.reply) {\n        continue;\n      }\n      try {\n        const reply = await handler(msg.data, msg.subject);\n        msg.respond(reply);\n      } catch {\n        // Leave the request unanswered: the requester's request times out, which\n        // the selfhosted control plane reads as a transient blip (reconnecting),\n        // never a malformed reply. The responder stays subscribed for the next op.\n      }\n    }\n  })();\n  return () => {\n    sub.unsubscribe();\n  };\n}\n\n/**\n * Subscribe to the one-way agent event plane: deliver each published payload (the\n * agent's `AgentEvent` heartbeat / going-offline, NOT a request/reply) to the\n * handler with its concrete subject. A plain `nc.subscribe` (no reply); a handler\n * that throws is swallowed so one bad event never tears down the subscription\n * (ingestion is best-effort — a metrics gap is never fatal).\n */\nfunction subscribeAgentEvents(\n  nc: NatsConnection,\n  subject: string,\n  handler: (payload: Uint8Array, subject: string) => void | Promise<void>,\n): () => void {\n  const sub: Subscription = nc.subscribe(subject);\n  void (async () => {\n    for await (const msg of sub) {\n      try {\n        await handler(msg.data, msg.subject);\n      } catch {\n        // Swallow: best-effort ingestion. The subscription stays live for the\n        // next event.\n      }\n    }\n  })();\n  return () => {\n    sub.unsubscribe();\n  };\n}\n\nexport function formatSse(event: SessionEvent): string {\n  return [\n    `id: ${event.sequence}`,\n    `event: ${event.type}`,\n    `data: ${JSON.stringify(event)}`,\n    \"\",\n    \"\",\n  ].join(\"\\n\");\n}\n","import type { SessionEvent } from \"@opengeni/contracts\";\n\nconst COALESCIBLE_DELTA_TYPES = new Set([\n  \"agent.message.delta\",\n  \"agent.reasoning.delta\",\n  \"sandbox.command.output.delta\",\n]);\n\ntype DeltaRun = {\n  first: SessionEvent;\n  lastSequence: number;\n  text: string;\n  sandboxName: string | undefined;\n  sandboxStream: string | undefined;\n  sandboxCommandId: string | undefined;\n};\n\nexport function coalesceSessionEventDeltas(events: SessionEvent[]): SessionEvent[] {\n  const coalesced: SessionEvent[] = [];\n  let run: DeltaRun | null = null;\n\n  const flush = () => {\n    if (!run) {\n      return;\n    }\n    coalesced.push({\n      ...run.first,\n      payload: run.first.type === \"sandbox.command.output.delta\"\n        // Sandbox output keeps its CANONICAL field (`chunk` — the terminal and\n        // projection read it) plus the stream/commandId identity of the run.\n        ? {\n            chunk: run.text,\n            coalescedUntil: run.lastSequence,\n            ...(run.sandboxStream !== undefined ? { stream: run.sandboxStream } : {}),\n            ...(run.sandboxCommandId !== undefined ? { commandId: run.sandboxCommandId } : {}),\n            ...(run.sandboxName !== undefined ? { name: run.sandboxName } : {}),\n          }\n        : {\n            text: run.text,\n            coalescedUntil: run.lastSequence,\n          },\n    });\n    run = null;\n  };\n\n  for (const event of events) {\n    if (!isCoalescibleDelta(event)) {\n      flush();\n      coalesced.push(event);\n      continue;\n    }\n\n    const isSandbox = event.type === \"sandbox.command.output.delta\";\n    const sandboxName = isSandbox ? sandboxDeltaName(event.payload) : undefined;\n    const sandboxStream = isSandbox ? sandboxDeltaString(event.payload, \"stream\") : undefined;\n    const sandboxCommandId = isSandbox ? sandboxDeltaString(event.payload, \"commandId\") : undefined;\n    if (\n      run\n      && sameDeltaRun(run.first, event, run.sandboxName, sandboxName)\n      && run.sandboxStream === sandboxStream\n      && run.sandboxCommandId === sandboxCommandId\n    ) {\n      run.text += deltaText(event);\n      run.lastSequence = event.sequence;\n      continue;\n    }\n\n    flush();\n    run = {\n      first: event,\n      lastSequence: event.sequence,\n      text: deltaText(event),\n      sandboxName,\n      sandboxStream,\n      sandboxCommandId,\n    };\n  }\n\n  flush();\n  return coalesced;\n}\n\nfunction isCoalescibleDelta(event: SessionEvent): boolean {\n  return COALESCIBLE_DELTA_TYPES.has(event.type);\n}\n\nfunction sameDeltaRun(\n  first: SessionEvent,\n  next: SessionEvent,\n  firstSandboxName: string | undefined,\n  nextSandboxName: string | undefined,\n): boolean {\n  if (first.type !== next.type) {\n    return false;\n  }\n  if ((first.turnId ?? null) !== (next.turnId ?? null)) {\n    return false;\n  }\n  return first.type !== \"sandbox.command.output.delta\" || firstSandboxName === nextSandboxName;\n}\n\nfunction deltaText(event: SessionEvent): string {\n  if (event.type === \"agent.reasoning.delta\") {\n    return reasoningText(event.payload);\n  }\n  const payload = asRecord(event.payload);\n  if (event.type === \"sandbox.command.output.delta\") {\n    // `chunk` is the canonical wire field (contracts SandboxCommandOutputDeltaPayload);\n    // text/output are tolerated legacy shapes.\n    for (const key of [\"chunk\", \"text\", \"output\"] as const) {\n      if (typeof payload[key] === \"string\") {\n        return payload[key] as string;\n      }\n    }\n    return \"\";\n  }\n  return typeof payload.text === \"string\" ? payload.text : \"\";\n}\n\nfunction reasoningText(payload: unknown): string {\n  const record = asRecord(payload);\n  if (typeof record.text === \"string\") {\n    return record.text;\n  }\n  const content = asRecord(asRecord(record.item).rawItem).content;\n  if (!Array.isArray(content)) {\n    return \"\";\n  }\n  return content\n    .map((part) => {\n      const text = asRecord(part).text;\n      return typeof text === \"string\" ? text : \"\";\n    })\n    .join(\"\");\n}\n\nfunction sandboxDeltaName(payload: unknown): string | undefined {\n  const name = asRecord(payload).name;\n  return typeof name === \"string\" ? name : undefined;\n}\n\nfunction sandboxDeltaString(payload: unknown, key: \"stream\" | \"commandId\"): string | undefined {\n  const value = asRecord(payload)[key];\n  return typeof value === \"string\" ? value : undefined;\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> {\n  return value && typeof value === \"object\" ? value as Record<string, unknown> : {};\n}\n","// packages/events/src/nats-jwt.ts — NATS JWT v2 signing for the auth-callout\n// responder (bring-your-own-compute M-AUTH; dossier §10.1 NATS Accounts per\n// workspace + §17 the isolation smoke).\n//\n// This is the cryptographic core of the auth-callout tenancy boundary. When an\n// external agent connects to NATS presenting its `oge_` enrollment bearer as the\n// connect auth-token, nats-server (configured with `auth_callout`) issues an\n// authorization request on `$SYS.REQ.USER.AUTH`. Our responder (auth-callout.ts)\n// validates the bearer and answers with a SIGNED authorization-response JWT that\n// embeds a SIGNED user JWT scoping the connection to publish/subscribe ONLY\n// `agent.<workspaceId>.>` (+ the reply `_INBOX.>`). That per-subject permission\n// set IS the per-workspace isolation: workspace A's agent literally cannot\n// pub/sub workspace B's subjects (§19 the NATS-Accounts-misconfig leak risk is\n// closed at the JWT-permission layer, not just by subject naming).\n//\n// WHY HAND-ROLL THE JWT ENCODING (vs a dep): the NATS JWT v2 wire format is small,\n// stable, and fully specified (ADR-26 + nats-io/jwt): a base64url header\n// `{\"typ\":\"JWT\",\"alg\":\"ed25519-nkey\"}`, base64url JSON claims whose `jti` is the\n// base32(SHA-512/256(claims-with-blank-jti)), and an ed25519 nkey signature over\n// `header.payload`. nkeys (re-exported by the `nats` package we already depend on)\n// gives us the ed25519 sign primitive; Node `crypto` gives SHA-512/256. So we own\n// the encoding in a few well-tested functions rather than pull an alpha\n// `@nats-io/jwt` (0.0.x) whose nkeys-version compat is uncertain. No `xkey`\n// encryption is used (the bearer is already an authenticated identity claim and\n// the wire is TLS — encryption is an optional ADR-26 hardening, off here).\n//\n// SECURITY: the account SIGNING SEED never leaves this process and is NEVER logged.\n// Callers pass it as a `string` seed; we `fromSeed` it once per sign. The bearer\n// the responder validates is HMAC-verified elsewhere (verifyEnrollmentBearer); this\n// module only mints the scoped NATS credential once identity is proven.\n\nimport { createHash } from \"node:crypto\";\nimport { nkeys } from \"nats\";\n\n/** The NATS JWT v2 header — constant for every token we mint (ADR-26 / nats-io/jwt:\n *  `TokenTypeJwt=\"JWT\"`, `AlgorithmNkey=\"ed25519-nkey\"`). */\nconst JWT_HEADER = { typ: \"JWT\", alg: \"ed25519-nkey\" } as const;\n\n/** NATS user-claim `nats.type` discriminator + `nats.version` for v2 claims. */\nconst USER_CLAIM_TYPE = \"user\";\nconst AUTH_RESPONSE_CLAIM_TYPE = \"authorization_response\";\nconst NATS_CLAIM_VERSION = 2;\n\n/** A NATS permission set: subject allow/deny lists (ADR-26 `pub`/`sub` →\n *  `allow`/`deny`). An empty/undefined list means \"no explicit grant\" — combined\n *  with the agent scope below, the connection can ONLY reach what `allow` lists. */\nexport interface NatsPermission {\n  allow?: string[];\n  deny?: string[];\n}\n\n/** The pub/sub permissions embedded in a user JWT. */\nexport interface NatsPermissions {\n  pub: NatsPermission;\n  sub: NatsPermission;\n}\n\n/**\n * The minimal nkey keypair surface this module needs — exactly what\n * `nkeys.fromSeed(seed)` returns. Declared structurally so the module does not\n * leak the `nats` nkeys type through its public signature.\n */\ninterface NkeyPair {\n  getPublicKey(): string;\n  sign(input: Uint8Array): Uint8Array;\n}\n\n/** base64url (RawURLEncoding — no padding), matching nats-io/jwt's `serialize`. */\nfunction base64UrlEncode(bytes: Uint8Array): string {\n  return Buffer.from(bytes).toString(\"base64url\");\n}\n\n/** RFC 4648 base32 (standard alphabet, NO padding) — the encoding nats-io/jwt\n *  uses for the `jti` hash. Node has no built-in base32, so a tiny encoder. */\nconst BASE32_ALPHABET = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ234567\";\nfunction base32NoPadding(bytes: Uint8Array): string {\n  let bits = 0;\n  let value = 0;\n  let out = \"\";\n  for (const byte of bytes) {\n    value = (value << 8) | byte;\n    bits += 8;\n    while (bits >= 5) {\n      bits -= 5;\n      out += BASE32_ALPHABET[(value >>> bits) & 31];\n    }\n  }\n  if (bits > 0) {\n    out += BASE32_ALPHABET[(value << (5 - bits)) & 31];\n  }\n  return out;\n}\n\n/**\n * Compute the canonical NATS `jti`: base32(NoPadding, std-alphabet) of the\n * SHA-512/256 of the claims object SERIALIZED WITH AN EMPTY `jti` (nats-io/jwt's\n * `hash`). nats-server recomputes + verifies this on decode, so it must match\n * byte-for-byte. We serialize the SAME object we will sign, only with `jti:\"\"`.\n */\nfunction computeJti(claimsWithBlankJti: object): string {\n  const json = JSON.stringify(claimsWithBlankJti);\n  const digest = createHash(\"sha512-256\").update(json, \"utf8\").digest();\n  return base32NoPadding(digest);\n}\n\n/**\n * Encode + sign a NATS v2 JWT. The `claims` MUST already carry `iss`/`sub`/`iat`\n * (+ optional `aud`/`exp`) and a `nats` block; this function fills `jti` (the\n * canonical hash), serializes `header.payload`, signs that with `signingKey`, and\n * appends the base64url signature. Returns the compact `header.payload.signature`.\n */\nfunction encodeJwt(claims: Record<string, unknown>, signingKey: NkeyPair): string {\n  // jti is the hash of the claims with jti blanked — set it blank, hash, then set.\n  const withBlankJti = { ...claims, jti: \"\" };\n  const jti = computeJti(withBlankJti);\n  const finalClaims = { ...claims, jti };\n\n  const header = base64UrlEncode(Buffer.from(JSON.stringify(JWT_HEADER), \"utf8\"));\n  const payload = base64UrlEncode(Buffer.from(JSON.stringify(finalClaims), \"utf8\"));\n  const signingInput = `${header}.${payload}`;\n  const signature = signingKey.sign(Buffer.from(signingInput, \"utf8\"));\n  return `${signingInput}.${base64UrlEncode(signature)}`;\n}\n\n/**\n * Input to mint a workspace-scoped NATS user JWT for an enrolled agent.\n *   - `userPublicKey` — the `user_nkey` from the authorization request; it MUST be\n *     the `sub` of the user JWT (nats-server rejects a mismatch).\n *   - `accountSeed` — the callout account SIGNING seed (`SA...`); both the user JWT\n *     `iss` (its public key) and the signature come from it. NEVER logged.\n *   - `name` — a human label for the user (the agent id), for server logs.\n *   - `permissions` — the pub/sub allow/deny lists (the workspace scope).\n *   - `expiresAtSeconds` — optional absolute `exp` (unix seconds). When set the\n *     server will expire the connection's credential; we tie it to the bearer's\n *     remaining life so a revoked/expired enrollment cannot outlive its bearer.\n */\nexport interface MintUserJwtInput {\n  userPublicKey: string;\n  accountSeed: string;\n  name: string;\n  permissions: NatsPermissions;\n  /** The target account NAME (the `auth_callout.account`) the user binds to; the\n   *  embedded user JWT's `aud` in server-config mode. */\n  audienceAccount: string;\n  expiresAtSeconds?: number;\n}\n\n/**\n * Mint a signed NATS user JWT scoped by `permissions`. In auth-callout SERVER\n * mode the user JWT is signed by the callout ISSUER ACCOUNT key, and its `iss` is\n * that account's public key. The returned JWT is embedded as `nats.jwt` in the\n * authorization response.\n */\nexport function mintUserJwt(input: MintUserJwtInput): string {\n  const accountKey = nkeys.fromSeed(Buffer.from(input.accountSeed)) as unknown as NkeyPair;\n  const accountPublicKey = accountKey.getPublicKey();\n  const nowSeconds = Math.floor(Date.now() / 1000);\n\n  const natsBlock: Record<string, unknown> = {\n    type: USER_CLAIM_TYPE,\n    version: NATS_CLAIM_VERSION,\n    pub: input.permissions.pub,\n    sub: input.permissions.sub,\n    // Unlimited subscriptions / data / payload (the workspace subject scope, NOT\n    // a connection-resource quota, is the boundary here).\n    subs: -1,\n    data: -1,\n    payload: -1,\n  };\n\n  const claims: Record<string, unknown> = {\n    jti: \"\",\n    iat: nowSeconds,\n    iss: accountPublicKey,\n    name: input.name,\n    sub: input.userPublicKey,\n    // SERVER-config-mode placement: nats-server reads the embedded user JWT's `aud`\n    // as the target account NAME (the configured `auth_callout.account`). This is\n    // how the authenticated user binds to that account; the workspace isolation is\n    // then carried by the pub/sub permissions below.\n    aud: input.audienceAccount,\n    nats: natsBlock,\n  };\n  if (typeof input.expiresAtSeconds === \"number\") {\n    claims.exp = input.expiresAtSeconds;\n  }\n  return encodeJwt(claims, accountKey);\n}\n\n/**\n * Input to mint the authorization RESPONSE JWT the responder publishes back on the\n * request's reply subject (ADR-26 §3).\n *   - `userPublicKey` — the request's `user_nkey`; the response `sub`.\n *   - `serverId` — the request's `nats.server_id.id` (the server's public key); the\n *     response `aud`.\n *   - `accountSeed` — the callout account signing seed; signs the response and is\n *     its `iss` (public key). NEVER logged.\n *   - `userJwt` — the embedded signed user JWT (omit on a denial).\n *   - `error` — a human-readable denial message (omit on success). When present the\n *     server denies the connection.\n */\nexport interface MintAuthResponseInput {\n  userPublicKey: string;\n  serverId: string;\n  accountSeed: string;\n  userJwt?: string;\n  error?: string;\n}\n\n/**\n * Mint the signed authorization-response JWT. On success it carries the embedded\n * user JWT (`nats.jwt`); on denial it carries `nats.error` and NO user JWT, which\n * makes nats-server refuse the connection. Signed by the callout account key (its\n * public key is `iss`); `sub` is the user_nkey, `aud` is the server id.\n */\nexport function mintAuthResponse(input: MintAuthResponseInput): string {\n  const accountKey = nkeys.fromSeed(Buffer.from(input.accountSeed)) as unknown as NkeyPair;\n  const accountPublicKey = accountKey.getPublicKey();\n  const nowSeconds = Math.floor(Date.now() / 1000);\n\n  const natsBlock: Record<string, unknown> = {\n    type: AUTH_RESPONSE_CLAIM_TYPE,\n    version: NATS_CLAIM_VERSION,\n  };\n  if (input.userJwt) {\n    natsBlock.jwt = input.userJwt;\n  }\n  if (input.error) {\n    natsBlock.error = input.error;\n  }\n\n  const claims: Record<string, unknown> = {\n    jti: \"\",\n    iat: nowSeconds,\n    iss: accountPublicKey,\n    // The response `aud` MUST be the SERVER public key in server-config mode\n    // (nats-server validates \"Audience must be a server public key\"). The\n    // authenticated user is placed into the configured `auth_callout.account` (the\n    // SAME account the responder + the privileged control plane connect into), so\n    // `agent.<ws>.<id>.rpc` request/reply routes; the workspace isolation is carried\n    // entirely by the user JWT's pub/sub subject permissions (NOT by cross-account\n    // placement, which server-config-mode nats does not support — nats-io#4335).\n    aud: input.serverId,\n    sub: input.userPublicKey,\n    nats: natsBlock,\n  };\n  return encodeJwt(claims, accountKey);\n}\n\n/**\n * The fields the responder needs out of the authorization REQUEST JWT (ADR-26 §2).\n * The request is itself a NATS JWT (`header.payload.signature`) the server signs;\n * we only DECODE it (the server proves its own identity by the connection, and the\n * embedded `auth_token` is independently HMAC-verified), so we read the payload\n * without re-verifying the server signature.\n */\nexport interface DecodedAuthRequest {\n  /** The public user nkey the response user JWT MUST be `sub`-scoped to. */\n  userNkey: string;\n  /** The server's public id — the response `aud`. */\n  serverId: string;\n  /** The connect `auth_token` the client presented (our `oge_` bearer), if any. */\n  authToken: string | undefined;\n  /** The connect username, if any (unused today; present for completeness). */\n  user: string | undefined;\n}\n\n/**\n * Decode the authorization-request JWT payload (the middle base64url segment). The\n * request shape (ADR-26 §2): `nats.user_nkey`, `nats.server_id.id`, and the\n * presented connect options under `nats.connect_opts` (`auth_token` / `user`).\n * Returns null on a malformed token so the caller can deny cleanly.\n */\nexport function decodeAuthRequest(token: string): DecodedAuthRequest | null {\n  const parts = token.split(\".\");\n  if (parts.length !== 3) {\n    return null;\n  }\n  let payload: unknown;\n  try {\n    payload = JSON.parse(Buffer.from(parts[1]!, \"base64url\").toString(\"utf8\"));\n  } catch {\n    return null;\n  }\n  if (typeof payload !== \"object\" || payload === null) {\n    return null;\n  }\n  const nats = (payload as { nats?: unknown }).nats;\n  if (typeof nats !== \"object\" || nats === null) {\n    return null;\n  }\n  const natsObj = nats as {\n    user_nkey?: unknown;\n    server_id?: { id?: unknown } | unknown;\n    connect_opts?: { auth_token?: unknown; user?: unknown } | unknown;\n  };\n  const userNkey = typeof natsObj.user_nkey === \"string\" ? natsObj.user_nkey : null;\n  if (!userNkey) {\n    return null;\n  }\n  const serverIdRaw =\n    typeof natsObj.server_id === \"object\" && natsObj.server_id !== null\n      ? (natsObj.server_id as { id?: unknown }).id\n      : undefined;\n  const serverId = typeof serverIdRaw === \"string\" ? serverIdRaw : \"\";\n  const connectOpts =\n    typeof natsObj.connect_opts === \"object\" && natsObj.connect_opts !== null\n      ? (natsObj.connect_opts as { auth_token?: unknown; user?: unknown })\n      : {};\n  const authToken = typeof connectOpts.auth_token === \"string\" ? connectOpts.auth_token : undefined;\n  const user = typeof connectOpts.user === \"string\" ? connectOpts.user : undefined;\n  return { userNkey, serverId, authToken, user };\n}\n\n/**\n * Build the workspace-scoped permission set for an agent: it may publish + subscribe\n * ONLY `agent.<workspaceId>.>` (its own RPC/event/hello subtree) and the reply\n * `_INBOX.>` subtree (so request/reply round-trips work). Everything else is\n * implicitly denied (an allow-list with no other entries IS the deny-all-else).\n *\n * THE isolation assertion (§17): with `workspaceId=A`, the returned allow lists name\n * only `agent.A.>` — so a connection bearing this credential is rejected by\n * nats-server the instant it tries to pub/sub `agent.B.>`. This is the per-workspace\n * tenancy boundary, enforced cryptographically by the signed JWT, not by naming.\n */\nexport function workspaceAgentPermissions(workspaceId: string): NatsPermissions {\n  const agentScope = `agent.${workspaceId}.>`;\n  // The reply-inbox subtree must be reachable for request/reply (the control plane\n  // requests on agent.<ws>.<id>.rpc with a reply inbox; the agent responds there).\n  const inboxScope = \"_INBOX.>\";\n  return {\n    pub: { allow: [agentScope, inboxScope] },\n    sub: { allow: [agentScope, inboxScope] },\n  };\n}\n"],"mappings":"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","names":["connect","nkeys"]}
+{"version":3,"sources":["../src/index.ts","../src/coalesce.ts","../src/nats-jwt.ts"],"sourcesContent":["import type { SessionBusMessage, SessionEvent, WorkspaceControlEvent } from \"@opengeni/contracts\";\nimport {\n  appendSessionEvents,\n  appendSessionEventsForTurnAttempt,\n  sessionSubject,\n  type AppendEventInput,\n  type Database,\n} from \"@opengeni/db\";\nimport {\n  connect,\n  JSONCodec,\n  type ConnectionOptions,\n  type Msg,\n  type NatsConnection,\n  type Subscription,\n} from \"nats\";\n\nconst codec = JSONCodec<SessionBusMessage | SessionEvent | WorkspaceControlEvent>();\n\nexport type EventLogger = {\n  debug?: (message: string, attributes?: Record<string, unknown>) => void;\n  warn?: (message: string, attributes?: Record<string, unknown>) => void;\n};\n\nexport type EventBusOptions = {\n  logger?: EventLogger;\n  /** Test/host transport seam; production defaults to the nats.js connector. */\n  connect?: typeof connect;\n};\n\nconst silentLogger: Required<EventLogger> = {\n  debug: () => {},\n  warn: () => {},\n};\n\nexport { coalesceSessionEventDeltas } from \"./coalesce\";\n\n/**\n * Reconnect + keepalive defaults applied to EVERY long-lived NATS connection\n * this package opens (the event bus AND the standalone auth-callout responder).\n *\n * The production outage these guard against: an in-cluster NATS broker pod\n * restart. nats.js's stock policy gives up after ~10 attempts (~20s) and the\n * client goes permanently CONNECTION_CLOSED — which takes the whole control\n * plane down with it: every session-create publishes events to NATS, and the\n * API-hosted auth-callout responder dies so BYO agents get \"authorization\n * violation\". Recovery then required a MANUAL api+worker restart. With these\n * options the client retries forever and auto-recovers the moment the broker\n * returns. Factored into one source of truth so the call sites never drift.\n *\n *  - `reconnect` + `maxReconnectAttempts: -1` — never give up (infinite retry).\n *  - `reconnectTimeWait` (2s base) + `reconnectJitter`/`reconnectJitterTLS`\n *    (up to 1s) — a fleet of api/worker pods doesn't thundering-herd the broker\n *    on recovery.\n *  - `waitOnFirstConnect` — a broker briefly unavailable at boot must not\n *    hard-fail the process; the client keeps trying instead of throwing.\n *  - `pingInterval`/`maxPingOut` — promptly detect a silently-dead socket so the\n *    reconnect machinery actually engages instead of hanging on a zombie.\n */\nconst RECONNECT_OPTIONS = {\n  reconnect: true,\n  maxReconnectAttempts: -1,\n  reconnectTimeWait: 2_000,\n  reconnectJitter: 1_000,\n  reconnectJitterTLS: 1_000,\n  waitOnFirstConnect: true,\n  pingInterval: 20_000,\n  maxPingOut: 3,\n} satisfies ConnectionOptions;\n\n/**\n * The single source of truth for a long-lived connection's resilience: merge the\n * reconnect/keepalive defaults UNDER the caller's connection options (servers +\n * optional auth/name). Every long-lived `connect()` in this package goes through\n * here so the two call sites can never diverge.\n */\nfunction withReconnectDefaults(options: ConnectionOptions): ConnectionOptions {\n  return { ...RECONNECT_OPTIONS, ...options };\n}\n\n/** How long a best-effort publish waits on `flush()` before giving up (see `publish`). */\nconst PUBLISH_FLUSH_TIMEOUT_MS = 2_000;\n\n/**\n * Await `nc.flush()` but never longer than `timeoutMs`. With infinite reconnect a\n * `flush()` issued while the broker is down does NOT reject — it pends until the\n * broker returns, which can be minutes. Racing it against a timer keeps a long\n * outage from stalling an in-flight turn; the published message stays buffered\n * and is delivered on reconnect regardless. A flush rejection (connection fully\n * CLOSED) is swallowed here so the timeout race never leaks an unhandled\n * rejection — the caller's publish path is what logs the drop.\n */\nasync function flushWithTimeout(nc: NatsConnection, timeoutMs: number): Promise<void> {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  const timeout = new Promise<void>((resolve) => {\n    timer = setTimeout(resolve, timeoutMs);\n  });\n  try {\n    await Promise.race([nc.flush().catch(() => undefined), timeout]);\n  } finally {\n    if (timer) {\n      clearTimeout(timer);\n    }\n  }\n}\n\n/**\n * Drain a long-lived connection's status async-iterator to the log so a future\n * broker outage is OBSERVABLE (disconnect → reconnecting → reconnect → update).\n * Fire-and-forget for the connection's lifetime; the loop ends when the\n * connection closes. `label` distinguishes the event-bus connection from the\n * auth-callout responder in the logs.\n */\nfunction logConnectionStatus(\n  nc: NatsConnection,\n  label: string,\n  logger: EventLogger = silentLogger,\n  onStatus?: (type: string) => void,\n): void {\n  void (async () => {\n    try {\n      for await (const status of nc.status()) {\n        onStatus?.(status.type);\n        const attributes = { label, status: status.type, data: status.data };\n        if (isWarnNatsStatus(status.type)) {\n          (logger.warn ?? silentLogger.warn)(\"NATS connection status\", attributes);\n        } else {\n          (logger.debug ?? silentLogger.debug)(\"NATS connection status\", attributes);\n        }\n      }\n    } catch {\n      // The status iterator simply ends when the connection closes; never let it\n      // throw out of this background loop.\n    }\n  })();\n}\n\nfunction isWarnNatsStatus(type: string): boolean {\n  return type === \"disconnect\" || type === \"error\" || type === \"staleConnection\";\n}\n\nexport {\n  decodeAuthRequest,\n  mintAuthResponse,\n  mintUserJwt,\n  workspaceAgentPermissions,\n  type DecodedAuthRequest,\n  type MintAuthResponseInput,\n  type MintUserJwtInput,\n  type NatsPermission,\n  type NatsPermissions,\n} from \"./nats-jwt\";\n\n// Re-export the raw NATS primitives a consumer needs to open a direct connection or\n// generate nkeys (the auth-callout responder's standalone connection, the\n// agent-simulating integration tests). This keeps `nats` an internal dependency of\n// this leaf — callers in the bun workspace reach it through @opengeni/events rather\n// than depending on `nats` directly.\nexport { connect, nkeys, type NatsConnection } from \"nats\";\n\n/**\n * A raw request/reply reply — just the response bytes. Mirrors the subset of the\n * NATS `Msg` shape a binary request/reply caller needs (`NatsControlRpc` consumes\n * exactly this). Kept minimal so the events package does not leak the `nats` `Msg`\n * type into the agent-loop-free runtime leaf.\n */\nexport type RequestReply = { data: Uint8Array };\n\n/**\n * The minimal request/reply connection the selfhosted control plane consumes\n * (structurally identical to `@opengeni/runtime`'s `NatsRequestConnection`). The\n * API/worker hand this accessor to `NatsControlRpc` so the control transport rides\n * the SAME managed NATS connection the event bus already owns — a NATS connection\n * natively supports both pub/sub and request/reply, so there is NEVER a second\n * connection.\n */\nexport interface RequestConnection {\n  request(subject: string, payload: Uint8Array, opts: { timeout: number }): Promise<RequestReply>;\n}\n\n/**\n * The raw subscribe/publish surface the selfhosted OP-STREAM transport consumes\n * (structurally identical to `@opengeni/runtime`'s `NatsOpStreamConnection`):\n * a plain subscription for the runner's fire-and-forget op frames\n * (`agent.<ws>.<id>.op.<op_id>`) and a plain publish for the server's acks\n * (`agent.<ws>.<id>.ack`). Same managed connection as everything else — a NATS\n * connection natively supports all of it; there is NEVER a second connection.\n */\nexport interface OpStreamConnection {\n  subscribe(subject: string): AsyncIterable<{ data: Uint8Array }> & { unsubscribe(): void };\n  publish(subject: string, payload: Uint8Array): void;\n}\n\n/**\n * A handler answering a request/reply on a subscribed subject: given the request\n * bytes (+ the concrete subject the message landed on, for `agent.<ws>.<id>.rpc`\n * style wildcard routing), return the response bytes to reply with. A thrown error\n * leaves the request unanswered (the caller's request times out / sees no\n * responder), which the control plane maps to `agent_offline` / reconnecting.\n */\nexport type RequestHandler = (\n  request: Uint8Array,\n  subject: string,\n) => Promise<Uint8Array> | Uint8Array;\n\nexport type EventBus = {\n  publish: (workspaceId: string, sessionId: string, events: SessionEvent[]) => Promise<void>;\n  subscribe: (\n    workspaceId: string,\n    sessionId: string,\n    onEvents: (events: SessionEvent[]) => void | Promise<void>,\n  ) => Promise<() => void>;\n  /** Best-effort live invalidation; the event is already durable in Postgres. */\n  publishWorkspaceControl: (workspaceId: string, event: WorkspaceControlEvent) => Promise<void>;\n  /** One workspace subscription fans a control change to every open descendant view. */\n  subscribeWorkspaceControl: (\n    workspaceId: string,\n    onEvent: (event: WorkspaceControlEvent) => void | Promise<void>,\n  ) => Promise<() => void>;\n  /**\n   * Issue a binary request/reply on a subject over the bus's NATS connection\n   * (the selfhosted control plane: `agent.<ws>.<id>.rpc`). A new usage of what was\n   * a one-way bus — same connection, native NATS request/reply. Rejects on a\n   * no-responder (NATS 503) or a request timeout; the caller (`NatsControlRpc`)\n   * maps those to `agent_offline` / `agent_reconnecting`, never a NotFound.\n   */\n  request: (\n    subject: string,\n    payload: Uint8Array,\n    opts: { timeoutMs: number },\n  ) => Promise<RequestReply>;\n  /**\n   * Subscribe-and-reply on a subject (the responder side — the enrolled agent, or\n   * a test stand-in for it): for every request on `subject`, call `handler` and\n   * `respond` with its bytes over the SAME connection. Returns an unsubscribe fn.\n   * A subject may be a NATS wildcard (e.g. `agent.*.*.rpc`).\n   */\n  subscribeRequests: (subject: string, handler: RequestHandler) => () => void;\n  /**\n   * Subscribe to the agent EVENT plane (the one-way fire-and-forget heartbeats +\n   * going-offline the agent PUBLISHES on `agent.<ws>.<id>.events`, NOT a\n   * request/reply). The M10 metrics-ingestion consumer subscribes the wildcard\n   * `agent.*.*.events` and gets each raw payload plus its concrete subject (so it\n   * can extract `<ws>`/`<id>` for the per-enrollment upsert). Returns an\n   * unsubscribe fn. Decoding the AgentEvent is the caller's concern (this leaf\n   * does not depend on `@opengeni/agent-proto`).\n   */\n  subscribeAgentEvents: (\n    subject: string,\n    handler: (payload: Uint8Array, subject: string) => void | Promise<void>,\n  ) => () => void;\n  /**\n   * The `RequestConnection` accessor the selfhosted `NatsControlRpc` consumes —\n   * the SAME managed connection (pub/sub + request/reply share it). The control\n   * plane injects this so the transport never opens a second connection.\n   */\n  getRequestConnection: () => RequestConnection;\n  /**\n   * The `OpStreamConnection` accessor the selfhosted op-stream transport\n   * consumes (`NatsOpStreamTransport`) — the same managed connection again.\n   * Optional so bus test doubles that never exercise op-stream stay valid.\n   */\n  getOpStreamConnection?: () => OpStreamConnection;\n  isConnected?: () => boolean;\n  close: () => Promise<void>;\n};\n\n/**\n * Connect the event bus + control-plane request/reply over ONE managed NATS\n * connection. `auth` is the PRIVILEGED control-plane login (M-AUTH): when the\n * server runs with auth_callout, the api/worker authenticates as a static account\n * user permitted to request `agent.*.rpc` + receive its inbox replies. When `auth`\n * is omitted the connection is anonymous (local dev / a NATS without auth_callout)\n * — the existing behavior, unchanged.\n */\nexport async function createNatsEventBus(\n  natsUrl: string,\n  auth?: { user: string; pass: string },\n  options: EventBusOptions = {},\n): Promise<EventBus> {\n  const connectOptions: ConnectionOptions = { servers: natsUrl };\n  if (auth) {\n    connectOptions.user = auth.user;\n    connectOptions.pass = auth.pass;\n  }\n  const nc = await (options.connect ?? connect)(withReconnectDefaults(connectOptions));\n  let connected = true;\n  logConnectionStatus(nc, \"event-bus\", options.logger, (type) => {\n    if (\n      type === \"disconnect\" ||\n      type === \"reconnecting\" ||\n      type === \"staleConnection\" ||\n      type === \"error\"\n    ) {\n      connected = false;\n    } else if (type === \"connect\" || type === \"reconnect\") {\n      connected = true;\n    }\n  });\n  const requestConnection: RequestConnection = {\n    request: async (subject, payload, opts) => requestReply(nc, subject, payload, opts.timeout),\n  };\n  const opStreamConnection: OpStreamConnection = {\n    subscribe: (subject) => nc.subscribe(subject),\n    publish: (subject, payload) => {\n      nc.publish(subject, payload);\n    },\n  };\n  return {\n    publish: async (workspaceId, sessionId, events) => {\n      if (events.length === 0) {\n        return;\n      }\n      // Best-effort LIVE fan-out. These events are ALREADY durably appended to\n      // the DB before we get here (they carry a DB-assigned `sequence`), and\n      // every consumer reconciles from that durable log — the server SSE stream\n      // replays + gap-backfills via `listSessionEvents`, and the SDK client\n      // reconnects and replays from the durable events endpoint. So a publish\n      // that fails during a broker blip only delays LIVE delivery (healed by the\n      // next successful publish's gap-backfill, or a stream reconnect); it must\n      // never throw the in-flight turn to death.\n      try {\n        nc.publish(\n          sessionSubject(workspaceId, sessionId),\n          codec.encode({ workspaceId, sessionId, events }),\n        );\n      } catch (error) {\n        // `publish()` throws synchronously only when the connection is fully\n        // CLOSED (with infinite reconnect, effectively never outside shutdown).\n        (options.logger?.warn ?? silentLogger.warn)(\n          \"NATS live publish dropped; events are durable in the DB and reconcile on stream replay\",\n          {\n            workspaceId,\n            sessionId,\n            error: error instanceof Error ? error.message : String(error),\n          },\n        );\n        return;\n      }\n      await flushWithTimeout(nc, PUBLISH_FLUSH_TIMEOUT_MS);\n    },\n    subscribe: async (workspaceId, sessionId, onEvents) =>\n      subscribeSession(nc, workspaceId, sessionId, onEvents),\n    publishWorkspaceControl: async (workspaceId, event) => {\n      try {\n        nc.publish(workspaceControlSubject(workspaceId), codec.encode(event));\n      } catch (error) {\n        (options.logger?.warn ?? silentLogger.warn)(\n          \"NATS workspace-control invalidation dropped; clients reconcile from Postgres\",\n          {\n            workspaceId,\n            revision: event.revision,\n            error: error instanceof Error ? error.message : String(error),\n          },\n        );\n        return;\n      }\n      await flushWithTimeout(nc, PUBLISH_FLUSH_TIMEOUT_MS);\n    },\n    subscribeWorkspaceControl: async (workspaceId, onEvent) => {\n      const sub = nc.subscribe(workspaceControlSubject(workspaceId));\n      void (async () => {\n        for await (const msg of sub) {\n          await onEvent(codec.decode(msg.data) as WorkspaceControlEvent);\n        }\n      })();\n      return () => sub.unsubscribe();\n    },\n    request: async (subject, payload, opts) => requestReply(nc, subject, payload, opts.timeoutMs),\n    subscribeRequests: (subject, handler) => subscribeRequests(nc, subject, handler),\n    subscribeAgentEvents: (subject, handler) => subscribeAgentEvents(nc, subject, handler),\n    getRequestConnection: () => requestConnection,\n    getOpStreamConnection: () => opStreamConnection,\n    isConnected: () => connected && !nc.isClosed() && !nc.isDraining(),\n    close: async () => {\n      await nc.drain();\n    },\n  };\n}\n\n/**\n * A standalone NATS connection answering request/reply on ONE subject — the\n * transport primitive the auth-callout responder uses. It is DELIBERATELY a\n * SEPARATE connection from the event bus: the callout responder authenticates as\n * the callout account's `auth_users` user (a username/password or token in the\n * `AUTH` account), which is a DIFFERENT identity from the control-plane's\n * privileged account that the event bus + `NatsControlRpc` ride. One connection\n * per identity; never multiplex the two.\n *\n * `request`/`reply` here is the RAW NATS request/reply (`$SYS.REQ.USER.AUTH`): the\n * server publishes an authorization request with a reply inbox; the handler returns\n * the signed authorization-response bytes which we `respond` on that inbox.\n */\nexport interface ResponderConnection {\n  /** Subscribe-and-reply on `subject`; returns an async close that drains. */\n  close: () => Promise<void>;\n}\n\n/** Connection auth for a standalone NATS connection (the callout responder). */\nexport type NatsConnectAuth =\n  | { kind: \"user-password\"; user: string; pass: string }\n  | { kind: \"token\"; token: string }\n  | { kind: \"anonymous\" };\n\n/**\n * Open a standalone NATS connection and subscribe `subject`, replying to every\n * request with `handler(requestBytes, subject)`. Used by the auth-callout\n * responder to serve `$SYS.REQ.USER.AUTH` as the callout auth user. Returns a\n * handle whose `close()` drains the connection. A handler that throws leaves the\n * request UNANSWERED — for auth-callout that means the server denies the\n * connection on its own timeout, which is the correct fail-closed behavior (a\n * responder bug must never accidentally grant access).\n */\nexport async function createResponderConnection(\n  natsUrl: string,\n  auth: NatsConnectAuth,\n  subject: string,\n  handler: RequestHandler,\n  options: { name?: string; logger?: EventLogger; connect?: typeof connect } = {},\n): Promise<ResponderConnection> {\n  const connectOptions: ConnectionOptions = { servers: natsUrl };\n  if (options.name) {\n    connectOptions.name = options.name;\n  }\n  if (auth.kind === \"user-password\") {\n    connectOptions.user = auth.user;\n    connectOptions.pass = auth.pass;\n  } else if (auth.kind === \"token\") {\n    connectOptions.token = auth.token;\n  }\n  const nc = await (options.connect ?? connect)(withReconnectDefaults(connectOptions));\n  logConnectionStatus(\n    nc,\n    options.name ? `auth-callout:${options.name}` : \"auth-callout\",\n    options.logger,\n  );\n  const sub: Subscription = nc.subscribe(subject);\n  void (async () => {\n    for await (const msg of sub) {\n      if (!msg.reply) {\n        continue;\n      }\n      try {\n        const reply = await handler(msg.data, msg.subject);\n        msg.respond(reply);\n      } catch {\n        // Leave UNANSWERED — fail-closed. The server denies the connect attempt\n        // on its callout timeout; a responder error never grants access.\n      }\n    }\n  })();\n  return {\n    close: async () => {\n      sub.unsubscribe();\n      await nc.drain();\n    },\n  };\n}\n\n/**\n * Optional timing seam for {@link appendAndPublishEvents}: `onAppend` fires after\n * the durable DB write, `onPublish` after the best-effort live fan-out (on both\n * success AND failure of the publish, so a broker blip still records its latency).\n * Kept as a plain callback so the events package takes no dependency on the\n * observability package; the worker wires it to Prometheus histograms.\n */\nexport type AppendPublishObserver = {\n  onAppend?: (info: { durationSeconds: number; count: number }) => void;\n  onPublish?: (info: { durationSeconds: number; count: number }) => void;\n};\n\nexport type AppendPublishOptions = AppendPublishObserver & {\n  /** Test/host persistence seam; production uses the database implementation. */\n  appendSessionEvents?: typeof appendSessionEvents;\n};\n\n/**\n * Invoke a phase-timing callback with the elapsed seconds since `startedAt` and the\n * event count, swallowing any throw so a metrics sink can never break the\n * append/publish path. Exported for direct unit testing: the wider test suite\n * installs a process-global `mock.module(\"@opengeni/events\")` that stubs\n * `appendAndPublishEvents` (spreading the real module for everything else), so the\n * observer wiring can only be exercised through a helper that survives that mock.\n */\nexport function observeSince(\n  fn: ((info: { durationSeconds: number; count: number }) => void) | undefined,\n  startedAt: number,\n  count: number,\n): void {\n  if (!fn) {\n    return;\n  }\n  try {\n    fn({ durationSeconds: Math.max(0, (performance.now() - startedAt) / 1000), count });\n  } catch {\n    // Metrics emission must never affect the append/publish path.\n  }\n}\n\nexport async function appendAndPublishEvents(\n  db: Database,\n  bus: EventBus,\n  workspaceId: string,\n  sessionId: string,\n  events: AppendEventInput[],\n  options: AppendPublishOptions = {},\n): Promise<SessionEvent[]> {\n  const appendStartedAt = performance.now();\n  const appended = await (options.appendSessionEvents ?? appendSessionEvents)(\n    db,\n    workspaceId,\n    sessionId,\n    events,\n  );\n  observeSince(options.onAppend, appendStartedAt, appended.length);\n  await publishDurableSessionEvents(bus, workspaceId, sessionId, appended, options);\n  return appended;\n}\n\n/**\n * Best-effort live fanout for events another DB helper already committed in\n * the same transaction as related durable state. This must never append again.\n */\nexport async function publishDurableSessionEvents(\n  bus: EventBus,\n  workspaceId: string,\n  sessionId: string,\n  appended: SessionEvent[],\n  observe?: AppendPublishObserver,\n): Promise<void> {\n  if (appended.length === 0) {\n    return;\n  }\n  // The committed DB events are the durable system of record; this publish is only a\n  // best-effort LIVE fan-out. Guard it so NO EventBus implementation can throw an\n  // in-flight agent turn to death on a transient NATS disconnect — consumers\n  // reconcile any missed live events from the durable log via the events/stream\n  // endpoint (DB replay + gap-backfill). The managed `createNatsEventBus` bus\n  // already swallows internally, so this catch is the belt-and-suspenders guard\n  // for any other bus impl (and a fully CLOSED connection during shutdown).\n  const publishStartedAt = performance.now();\n  try {\n    await bus.publish(workspaceId, sessionId, appended);\n  } catch (error) {\n    console.warn(\n      `[events] live publish failed for ${workspaceId}/${sessionId}; ${appended.length} event(s) are durable and reconcile on stream replay`,\n      error,\n    );\n  }\n  observeSince(observe?.onPublish, publishStartedAt, appended.length);\n}\n\n/** Best-effort fanout for a workspace-control event already committed in PostgreSQL. */\nexport async function publishDurableWorkspaceControlEvent(\n  bus: EventBus,\n  workspaceId: string,\n  event: WorkspaceControlEvent,\n): Promise<void> {\n  try {\n    await bus.publishWorkspaceControl(workspaceId, event);\n  } catch (error) {\n    console.warn(\n      `[events] workspace-control live publish failed for ${workspaceId} at revision ${event.revision}; the event is durable and reconciles on stream replay`,\n      error,\n    );\n  }\n}\n\nexport async function appendAndPublishTurnEventsFenced(\n  db: Database,\n  bus: EventBus,\n  workspaceId: string,\n  sessionId: string,\n  turnId: string,\n  executionGeneration: number,\n  attemptId: string,\n  events: AppendEventInput[],\n): Promise<{ events: SessionEvent[]; accepted: boolean }> {\n  const result = await appendSessionEventsForTurnAttempt(\n    db,\n    workspaceId,\n    sessionId,\n    turnId,\n    executionGeneration,\n    attemptId,\n    events,\n  );\n  if (result.events.length === 0) return result;\n  try {\n    await bus.publish(workspaceId, sessionId, result.events);\n  } catch (error) {\n    console.warn(\n      `[events] live fenced publish failed for ${workspaceId}/${sessionId}/${turnId}@${executionGeneration}/${attemptId}; ${result.events.length} event(s) are durable`,\n      error,\n    );\n  }\n  return result;\n}\n\nfunction subscribeSession(\n  nc: NatsConnection,\n  workspaceId: string,\n  sessionId: string,\n  onEvents: (events: SessionEvent[]) => void | Promise<void>,\n): () => void {\n  const sub: Subscription = nc.subscribe(sessionSubject(workspaceId, sessionId));\n  void (async () => {\n    for await (const msg of sub) {\n      const decoded = codec.decode(msg.data) as SessionBusMessage | SessionEvent;\n      const events = \"events\" in decoded ? decoded.events : [decoded];\n      await onEvents(events);\n    }\n  })();\n  return () => {\n    sub.unsubscribe();\n  };\n}\n\n/**\n * A binary request/reply over the managed connection. Returns ONLY the reply\n * bytes (the `RequestReply` shape) — the request/reply error semantics (a\n * no-responder NATS 503, a request timeout) propagate as the rejected promise so\n * the caller owns the mapping. The reply is delivered via the connection's\n * built-in mux inbox; no extra subscription is created here.\n */\nasync function requestReply(\n  nc: NatsConnection,\n  subject: string,\n  payload: Uint8Array,\n  timeout: number,\n): Promise<RequestReply> {\n  const msg: Msg = await nc.request(subject, payload, { timeout });\n  return { data: msg.data };\n}\n\n/**\n * Subscribe to `subject` and reply to every request with the handler's bytes,\n * over the SAME connection. The responder side of request/reply: each delivered\n * `Msg` carries a `reply` inbox; `msg.respond(bytes)` publishes the answer there.\n * A handler that throws (or a message with no `reply` subject) is left unanswered\n * — the requester then sees a timeout, never a malformed reply.\n */\nfunction subscribeRequests(\n  nc: NatsConnection,\n  subject: string,\n  handler: RequestHandler,\n): () => void {\n  const sub: Subscription = nc.subscribe(subject);\n  void (async () => {\n    for await (const msg of sub) {\n      // A request always carries a reply inbox; a plain publish to this subject\n      // (no reply) is ignored — request/reply is the only contract here.\n      if (!msg.reply) {\n        continue;\n      }\n      try {\n        const reply = await handler(msg.data, msg.subject);\n        msg.respond(reply);\n      } catch {\n        // Leave the request unanswered: the requester's request times out, which\n        // the selfhosted control plane reads as a transient blip (reconnecting),\n        // never a malformed reply. The responder stays subscribed for the next op.\n      }\n    }\n  })();\n  return () => {\n    sub.unsubscribe();\n  };\n}\n\n/**\n * Subscribe to the one-way agent event plane: deliver each published payload (the\n * agent's `AgentEvent` heartbeat / going-offline, NOT a request/reply) to the\n * handler with its concrete subject. A plain `nc.subscribe` (no reply); a handler\n * that throws is swallowed so one bad event never tears down the subscription\n * (ingestion is best-effort — a metrics gap is never fatal).\n */\nfunction subscribeAgentEvents(\n  nc: NatsConnection,\n  subject: string,\n  handler: (payload: Uint8Array, subject: string) => void | Promise<void>,\n): () => void {\n  const sub: Subscription = nc.subscribe(subject);\n  void (async () => {\n    for await (const msg of sub) {\n      try {\n        await handler(msg.data, msg.subject);\n      } catch {\n        // Swallow: best-effort ingestion. The subscription stays live for the\n        // next event.\n      }\n    }\n  })();\n  return () => {\n    sub.unsubscribe();\n  };\n}\n\nexport function formatSse<T extends { sequence: number; type: string }>(event: T): string {\n  return [\n    `id: ${event.sequence}`,\n    `event: ${event.type}`,\n    `data: ${JSON.stringify(event)}`,\n    \"\",\n    \"\",\n  ].join(\"\\n\");\n}\n\nfunction workspaceControlSubject(workspaceId: string): string {\n  return `workspaces.${workspaceId}.control`;\n}\n","import type { SessionEvent } from \"@opengeni/contracts\";\n\nconst COALESCIBLE_DELTA_TYPES = new Set([\n  \"agent.message.delta\",\n  \"agent.reasoning.delta\",\n  \"sandbox.command.output.delta\",\n]);\n\ntype DeltaRun = {\n  first: SessionEvent;\n  lastSequence: number;\n  text: string;\n  sandboxName: string | undefined;\n  sandboxStream: string | undefined;\n  sandboxCommandId: string | undefined;\n};\n\nexport function coalesceSessionEventDeltas(events: SessionEvent[]): SessionEvent[] {\n  const coalesced: SessionEvent[] = [];\n  let run: DeltaRun | null = null;\n\n  const flush = () => {\n    if (!run) {\n      return;\n    }\n    coalesced.push({\n      ...run.first,\n      payload:\n        run.first.type === \"sandbox.command.output.delta\"\n          ? // Sandbox output keeps its CANONICAL field (`chunk` — the terminal and\n            // projection read it) plus the stream/commandId identity of the run.\n            {\n              chunk: run.text,\n              coalescedUntil: run.lastSequence,\n              ...(run.sandboxStream !== undefined ? { stream: run.sandboxStream } : {}),\n              ...(run.sandboxCommandId !== undefined ? { commandId: run.sandboxCommandId } : {}),\n              ...(run.sandboxName !== undefined ? { name: run.sandboxName } : {}),\n            }\n          : {\n              text: run.text,\n              coalescedUntil: run.lastSequence,\n            },\n    });\n    run = null;\n  };\n\n  for (const event of events) {\n    if (!isCoalescibleDelta(event)) {\n      flush();\n      coalesced.push(event);\n      continue;\n    }\n\n    const isSandbox = event.type === \"sandbox.command.output.delta\";\n    const sandboxName = isSandbox ? sandboxDeltaName(event.payload) : undefined;\n    const sandboxStream = isSandbox ? sandboxDeltaString(event.payload, \"stream\") : undefined;\n    const sandboxCommandId = isSandbox ? sandboxDeltaString(event.payload, \"commandId\") : undefined;\n    if (\n      run &&\n      sameDeltaRun(run.first, event, run.sandboxName, sandboxName) &&\n      run.sandboxStream === sandboxStream &&\n      run.sandboxCommandId === sandboxCommandId\n    ) {\n      run.text += deltaText(event);\n      run.lastSequence = event.sequence;\n      continue;\n    }\n\n    flush();\n    run = {\n      first: event,\n      lastSequence: event.sequence,\n      text: deltaText(event),\n      sandboxName,\n      sandboxStream,\n      sandboxCommandId,\n    };\n  }\n\n  flush();\n  return coalesced;\n}\n\nfunction isCoalescibleDelta(event: SessionEvent): boolean {\n  return COALESCIBLE_DELTA_TYPES.has(event.type);\n}\n\nfunction sameDeltaRun(\n  first: SessionEvent,\n  next: SessionEvent,\n  firstSandboxName: string | undefined,\n  nextSandboxName: string | undefined,\n): boolean {\n  if (first.type !== next.type) {\n    return false;\n  }\n  if ((first.turnId ?? null) !== (next.turnId ?? null)) {\n    return false;\n  }\n  return first.type !== \"sandbox.command.output.delta\" || firstSandboxName === nextSandboxName;\n}\n\nfunction deltaText(event: SessionEvent): string {\n  if (event.type === \"agent.reasoning.delta\") {\n    return reasoningText(event.payload);\n  }\n  const payload = asRecord(event.payload);\n  if (event.type === \"sandbox.command.output.delta\") {\n    // `chunk` is the canonical wire field (contracts SandboxCommandOutputDeltaPayload);\n    // text/output are tolerated legacy shapes.\n    for (const key of [\"chunk\", \"text\", \"output\"] as const) {\n      if (typeof payload[key] === \"string\") {\n        return payload[key] as string;\n      }\n    }\n    return \"\";\n  }\n  return typeof payload.text === \"string\" ? payload.text : \"\";\n}\n\nfunction reasoningText(payload: unknown): string {\n  const record = asRecord(payload);\n  if (typeof record.text === \"string\") {\n    return record.text;\n  }\n  const content = asRecord(asRecord(record.item).rawItem).content;\n  if (!Array.isArray(content)) {\n    return \"\";\n  }\n  return content\n    .map((part) => {\n      const text = asRecord(part).text;\n      return typeof text === \"string\" ? text : \"\";\n    })\n    .join(\"\");\n}\n\nfunction sandboxDeltaName(payload: unknown): string | undefined {\n  const name = asRecord(payload).name;\n  return typeof name === \"string\" ? name : undefined;\n}\n\nfunction sandboxDeltaString(payload: unknown, key: \"stream\" | \"commandId\"): string | undefined {\n  const value = asRecord(payload)[key];\n  return typeof value === \"string\" ? value : undefined;\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> {\n  return value && typeof value === \"object\" ? (value as Record<string, unknown>) : {};\n}\n","// packages/events/src/nats-jwt.ts — NATS JWT v2 signing for the auth-callout\n// responder (bring-your-own-compute M-AUTH; dossier §10.1 NATS Accounts per\n// workspace + §17 the isolation smoke).\n//\n// This is the cryptographic core of the auth-callout tenancy boundary. When an\n// external agent connects to NATS presenting its `oge_` enrollment bearer as the\n// connect auth-token, nats-server (configured with `auth_callout`) issues an\n// authorization request on `$SYS.REQ.USER.AUTH`. Our responder (auth-callout.ts)\n// validates the bearer and answers with a SIGNED authorization-response JWT that\n// embeds a SIGNED user JWT scoping the connection to publish/subscribe ONLY\n// `agent.<workspaceId>.>` (+ the reply `_INBOX.>`). That per-subject permission\n// set IS the per-workspace isolation: workspace A's agent literally cannot\n// pub/sub workspace B's subjects (§19 the NATS-Accounts-misconfig leak risk is\n// closed at the JWT-permission layer, not just by subject naming).\n//\n// WHY HAND-ROLL THE JWT ENCODING (vs a dep): the NATS JWT v2 wire format is small,\n// stable, and fully specified (ADR-26 + nats-io/jwt): a base64url header\n// `{\"typ\":\"JWT\",\"alg\":\"ed25519-nkey\"}`, base64url JSON claims whose `jti` is the\n// base32(SHA-512/256(claims-with-blank-jti)), and an ed25519 nkey signature over\n// `header.payload`. nkeys (re-exported by the `nats` package we already depend on)\n// gives us the ed25519 sign primitive; Node `crypto` gives SHA-512/256. So we own\n// the encoding in a few well-tested functions rather than pull an alpha\n// `@nats-io/jwt` (0.0.x) whose nkeys-version compat is uncertain. No `xkey`\n// encryption is used (the bearer is already an authenticated identity claim and\n// the wire is TLS — encryption is an optional ADR-26 hardening, off here).\n//\n// SECURITY: the account SIGNING SEED never leaves this process and is NEVER logged.\n// Callers pass it as a `string` seed; we `fromSeed` it once per sign. The bearer\n// the responder validates is HMAC-verified elsewhere (verifyEnrollmentBearer); this\n// module only mints the scoped NATS credential once identity is proven.\n\nimport { createHash } from \"node:crypto\";\nimport { nkeys } from \"nats\";\n\n/** The NATS JWT v2 header — constant for every token we mint (ADR-26 / nats-io/jwt:\n *  `TokenTypeJwt=\"JWT\"`, `AlgorithmNkey=\"ed25519-nkey\"`). */\nconst JWT_HEADER = { typ: \"JWT\", alg: \"ed25519-nkey\" } as const;\n\n/** NATS user-claim `nats.type` discriminator + `nats.version` for v2 claims. */\nconst USER_CLAIM_TYPE = \"user\";\nconst AUTH_RESPONSE_CLAIM_TYPE = \"authorization_response\";\nconst NATS_CLAIM_VERSION = 2;\n\n/** A NATS permission set: subject allow/deny lists (ADR-26 `pub`/`sub` →\n *  `allow`/`deny`). An empty/undefined list means \"no explicit grant\" — combined\n *  with the agent scope below, the connection can ONLY reach what `allow` lists. */\nexport interface NatsPermission {\n  allow?: string[];\n  deny?: string[];\n}\n\n/** The pub/sub permissions embedded in a user JWT. */\nexport interface NatsPermissions {\n  pub: NatsPermission;\n  sub: NatsPermission;\n}\n\n/**\n * The minimal nkey keypair surface this module needs — exactly what\n * `nkeys.fromSeed(seed)` returns. Declared structurally so the module does not\n * leak the `nats` nkeys type through its public signature.\n */\ninterface NkeyPair {\n  getPublicKey(): string;\n  sign(input: Uint8Array): Uint8Array;\n}\n\n/** base64url (RawURLEncoding — no padding), matching nats-io/jwt's `serialize`. */\nfunction base64UrlEncode(bytes: Uint8Array): string {\n  return Buffer.from(bytes).toString(\"base64url\");\n}\n\n/** RFC 4648 base32 (standard alphabet, NO padding) — the encoding nats-io/jwt\n *  uses for the `jti` hash. Node has no built-in base32, so a tiny encoder. */\nconst BASE32_ALPHABET = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ234567\";\nfunction base32NoPadding(bytes: Uint8Array): string {\n  let bits = 0;\n  let value = 0;\n  let out = \"\";\n  for (const byte of bytes) {\n    value = (value << 8) | byte;\n    bits += 8;\n    while (bits >= 5) {\n      bits -= 5;\n      out += BASE32_ALPHABET[(value >>> bits) & 31];\n    }\n  }\n  if (bits > 0) {\n    out += BASE32_ALPHABET[(value << (5 - bits)) & 31];\n  }\n  return out;\n}\n\n/**\n * Compute the canonical NATS `jti`: base32(NoPadding, std-alphabet) of the\n * SHA-512/256 of the claims object SERIALIZED WITH AN EMPTY `jti` (nats-io/jwt's\n * `hash`). nats-server recomputes + verifies this on decode, so it must match\n * byte-for-byte. We serialize the SAME object we will sign, only with `jti:\"\"`.\n */\nfunction computeJti(claimsWithBlankJti: object): string {\n  const json = JSON.stringify(claimsWithBlankJti);\n  const digest = createHash(\"sha512-256\").update(json, \"utf8\").digest();\n  return base32NoPadding(digest);\n}\n\n/**\n * Encode + sign a NATS v2 JWT. The `claims` MUST already carry `iss`/`sub`/`iat`\n * (+ optional `aud`/`exp`) and a `nats` block; this function fills `jti` (the\n * canonical hash), serializes `header.payload`, signs that with `signingKey`, and\n * appends the base64url signature. Returns the compact `header.payload.signature`.\n */\nfunction encodeJwt(claims: Record<string, unknown>, signingKey: NkeyPair): string {\n  // jti is the hash of the claims with jti blanked — set it blank, hash, then set.\n  const withBlankJti = { ...claims, jti: \"\" };\n  const jti = computeJti(withBlankJti);\n  const finalClaims = { ...claims, jti };\n\n  const header = base64UrlEncode(Buffer.from(JSON.stringify(JWT_HEADER), \"utf8\"));\n  const payload = base64UrlEncode(Buffer.from(JSON.stringify(finalClaims), \"utf8\"));\n  const signingInput = `${header}.${payload}`;\n  const signature = signingKey.sign(Buffer.from(signingInput, \"utf8\"));\n  return `${signingInput}.${base64UrlEncode(signature)}`;\n}\n\n/**\n * Input to mint a workspace-scoped NATS user JWT for an enrolled agent.\n *   - `userPublicKey` — the `user_nkey` from the authorization request; it MUST be\n *     the `sub` of the user JWT (nats-server rejects a mismatch).\n *   - `accountSeed` — the callout account SIGNING seed (`SA...`); both the user JWT\n *     `iss` (its public key) and the signature come from it. NEVER logged.\n *   - `name` — a human label for the user (the agent id), for server logs.\n *   - `permissions` — the pub/sub allow/deny lists (the workspace scope).\n *   - `expiresAtSeconds` — optional absolute `exp` (unix seconds). When set the\n *     server will expire the connection's credential; we tie it to the bearer's\n *     remaining life so a revoked/expired enrollment cannot outlive its bearer.\n */\nexport interface MintUserJwtInput {\n  userPublicKey: string;\n  accountSeed: string;\n  name: string;\n  permissions: NatsPermissions;\n  /** The target account NAME (the `auth_callout.account`) the user binds to; the\n   *  embedded user JWT's `aud` in server-config mode. */\n  audienceAccount: string;\n  expiresAtSeconds?: number;\n}\n\n/**\n * Mint a signed NATS user JWT scoped by `permissions`. In auth-callout SERVER\n * mode the user JWT is signed by the callout ISSUER ACCOUNT key, and its `iss` is\n * that account's public key. The returned JWT is embedded as `nats.jwt` in the\n * authorization response.\n */\nexport function mintUserJwt(input: MintUserJwtInput): string {\n  const accountKey = nkeys.fromSeed(Buffer.from(input.accountSeed)) as unknown as NkeyPair;\n  const accountPublicKey = accountKey.getPublicKey();\n  const nowSeconds = Math.floor(Date.now() / 1000);\n\n  const natsBlock: Record<string, unknown> = {\n    type: USER_CLAIM_TYPE,\n    version: NATS_CLAIM_VERSION,\n    pub: input.permissions.pub,\n    sub: input.permissions.sub,\n    // Unlimited subscriptions / data / payload (the workspace subject scope, NOT\n    // a connection-resource quota, is the boundary here).\n    subs: -1,\n    data: -1,\n    payload: -1,\n  };\n\n  const claims: Record<string, unknown> = {\n    jti: \"\",\n    iat: nowSeconds,\n    iss: accountPublicKey,\n    name: input.name,\n    sub: input.userPublicKey,\n    // SERVER-config-mode placement: nats-server reads the embedded user JWT's `aud`\n    // as the target account NAME (the configured `auth_callout.account`). This is\n    // how the authenticated user binds to that account; the workspace isolation is\n    // then carried by the pub/sub permissions below.\n    aud: input.audienceAccount,\n    nats: natsBlock,\n  };\n  if (typeof input.expiresAtSeconds === \"number\") {\n    claims.exp = input.expiresAtSeconds;\n  }\n  return encodeJwt(claims, accountKey);\n}\n\n/**\n * Input to mint the authorization RESPONSE JWT the responder publishes back on the\n * request's reply subject (ADR-26 §3).\n *   - `userPublicKey` — the request's `user_nkey`; the response `sub`.\n *   - `serverId` — the request's `nats.server_id.id` (the server's public key); the\n *     response `aud`.\n *   - `accountSeed` — the callout account signing seed; signs the response and is\n *     its `iss` (public key). NEVER logged.\n *   - `userJwt` — the embedded signed user JWT (omit on a denial).\n *   - `error` — a human-readable denial message (omit on success). When present the\n *     server denies the connection.\n */\nexport interface MintAuthResponseInput {\n  userPublicKey: string;\n  serverId: string;\n  accountSeed: string;\n  userJwt?: string;\n  error?: string;\n}\n\n/**\n * Mint the signed authorization-response JWT. On success it carries the embedded\n * user JWT (`nats.jwt`); on denial it carries `nats.error` and NO user JWT, which\n * makes nats-server refuse the connection. Signed by the callout account key (its\n * public key is `iss`); `sub` is the user_nkey, `aud` is the server id.\n */\nexport function mintAuthResponse(input: MintAuthResponseInput): string {\n  const accountKey = nkeys.fromSeed(Buffer.from(input.accountSeed)) as unknown as NkeyPair;\n  const accountPublicKey = accountKey.getPublicKey();\n  const nowSeconds = Math.floor(Date.now() / 1000);\n\n  const natsBlock: Record<string, unknown> = {\n    type: AUTH_RESPONSE_CLAIM_TYPE,\n    version: NATS_CLAIM_VERSION,\n  };\n  if (input.userJwt) {\n    natsBlock.jwt = input.userJwt;\n  }\n  if (input.error) {\n    natsBlock.error = input.error;\n  }\n\n  const claims: Record<string, unknown> = {\n    jti: \"\",\n    iat: nowSeconds,\n    iss: accountPublicKey,\n    // The response `aud` MUST be the SERVER public key in server-config mode\n    // (nats-server validates \"Audience must be a server public key\"). The\n    // authenticated user is placed into the configured `auth_callout.account` (the\n    // SAME account the responder + the privileged control plane connect into), so\n    // `agent.<ws>.<id>.rpc` request/reply routes; the workspace isolation is carried\n    // entirely by the user JWT's pub/sub subject permissions (NOT by cross-account\n    // placement, which server-config-mode nats does not support — nats-io#4335).\n    aud: input.serverId,\n    sub: input.userPublicKey,\n    nats: natsBlock,\n  };\n  return encodeJwt(claims, accountKey);\n}\n\n/**\n * The fields the responder needs out of the authorization REQUEST JWT (ADR-26 §2).\n * The request is itself a NATS JWT (`header.payload.signature`) the server signs;\n * we only DECODE it (the server proves its own identity by the connection, and the\n * embedded `auth_token` is independently HMAC-verified), so we read the payload\n * without re-verifying the server signature.\n */\nexport interface DecodedAuthRequest {\n  /** The public user nkey the response user JWT MUST be `sub`-scoped to. */\n  userNkey: string;\n  /** The server's public id — the response `aud`. */\n  serverId: string;\n  /** The connect `auth_token` the client presented (our `oge_` bearer), if any. */\n  authToken: string | undefined;\n  /** The connect username, if any (unused today; present for completeness). */\n  user: string | undefined;\n}\n\n/**\n * Decode the authorization-request JWT payload (the middle base64url segment). The\n * request shape (ADR-26 §2): `nats.user_nkey`, `nats.server_id.id`, and the\n * presented connect options under `nats.connect_opts` (`auth_token` / `user`).\n * Returns null on a malformed token so the caller can deny cleanly.\n */\nexport function decodeAuthRequest(token: string): DecodedAuthRequest | null {\n  const parts = token.split(\".\");\n  if (parts.length !== 3) {\n    return null;\n  }\n  let payload: unknown;\n  try {\n    payload = JSON.parse(Buffer.from(parts[1]!, \"base64url\").toString(\"utf8\"));\n  } catch {\n    return null;\n  }\n  if (typeof payload !== \"object\" || payload === null) {\n    return null;\n  }\n  const nats = (payload as { nats?: unknown }).nats;\n  if (typeof nats !== \"object\" || nats === null) {\n    return null;\n  }\n  const natsObj = nats as {\n    user_nkey?: unknown;\n    server_id?: { id?: unknown } | unknown;\n    connect_opts?: { auth_token?: unknown; user?: unknown } | unknown;\n  };\n  const userNkey = typeof natsObj.user_nkey === \"string\" ? natsObj.user_nkey : null;\n  if (!userNkey) {\n    return null;\n  }\n  const serverIdRaw =\n    typeof natsObj.server_id === \"object\" && natsObj.server_id !== null\n      ? (natsObj.server_id as { id?: unknown }).id\n      : undefined;\n  const serverId = typeof serverIdRaw === \"string\" ? serverIdRaw : \"\";\n  const connectOpts =\n    typeof natsObj.connect_opts === \"object\" && natsObj.connect_opts !== null\n      ? (natsObj.connect_opts as { auth_token?: unknown; user?: unknown })\n      : {};\n  const authToken = typeof connectOpts.auth_token === \"string\" ? connectOpts.auth_token : undefined;\n  const user = typeof connectOpts.user === \"string\" ? connectOpts.user : undefined;\n  return { userNkey, serverId, authToken, user };\n}\n\n/**\n * Build the workspace-scoped permission set for an agent: it may publish + subscribe\n * ONLY `agent.<workspaceId>.>` (its own RPC/event/hello subtree) and the reply\n * `_INBOX.>` subtree (so request/reply round-trips work). Everything else is\n * implicitly denied (an allow-list with no other entries IS the deny-all-else).\n *\n * THE isolation assertion (§17): with `workspaceId=A`, the returned allow lists name\n * only `agent.A.>` — so a connection bearing this credential is rejected by\n * nats-server the instant it tries to pub/sub `agent.B.>`. This is the per-workspace\n * tenancy boundary, enforced cryptographically by the signed JWT, not by naming.\n */\nexport function workspaceAgentPermissions(workspaceId: string): NatsPermissions {\n  const agentScope = `agent.${workspaceId}.>`;\n  // The reply-inbox subtree must be reachable for request/reply (the control plane\n  // requests on agent.<ws>.<id>.rpc with a reply inbox; the agent responds there).\n  const inboxScope = \"_INBOX.>\";\n  return {\n    pub: { allow: [agentScope, inboxScope] },\n    sub: { allow: [agentScope, inboxScope] },\n  };\n}\n"],"mappings":"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","names":["connect","nkeys"]}

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "@opengeni/events",
-  "version": "0.2.8",
-  "type": "module",
+  "version": "0.3.1",
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cloudgeni-ai/opengeni.git",
+    "directory": "packages/events"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,27 +21,18 @@
       "import": "./dist/index.js"
     }
   },
-  "files": [
-    "dist",
-    "src"
-  ],
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "scripts": {
     "build": "tsup",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo --noEmit",
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
-    "@opengeni/contracts": "^0.9.0",
-    "@opengeni/db": "^0.6.1",
+    "@opengeni/contracts": "^0.10.0",
+    "@opengeni/db": "^0.7.1",
     "nats": "^2.29.3"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Cloudgeni-ai/opengeni.git",
-    "directory": "packages/events"
   }
 }

package/src/coalesce.ts

@@ -25,20 +25,21 @@ export function coalesceSessionEventDeltas(events: SessionEvent[]): SessionEvent
     }
     coalesced.push({
       ...run.first,
-      payload: run.first.type === "sandbox.command.output.delta"
-        // Sandbox output keeps its CANONICAL field (`chunk` — the terminal and
-        // projection read it) plus the stream/commandId identity of the run.
-        ? {
-            chunk: run.text,
-            coalescedUntil: run.lastSequence,
-            ...(run.sandboxStream !== undefined ? { stream: run.sandboxStream } : {}),
-            ...(run.sandboxCommandId !== undefined ? { commandId: run.sandboxCommandId } : {}),
-            ...(run.sandboxName !== undefined ? { name: run.sandboxName } : {}),
-          }
-        : {
-            text: run.text,
-            coalescedUntil: run.lastSequence,
-          },
+      payload:
+        run.first.type === "sandbox.command.output.delta"
+          ? // Sandbox output keeps its CANONICAL field (`chunk` — the terminal and
+            // projection read it) plus the stream/commandId identity of the run.
+            {
+              chunk: run.text,
+              coalescedUntil: run.lastSequence,
+              ...(run.sandboxStream !== undefined ? { stream: run.sandboxStream } : {}),
+              ...(run.sandboxCommandId !== undefined ? { commandId: run.sandboxCommandId } : {}),
+              ...(run.sandboxName !== undefined ? { name: run.sandboxName } : {}),
+            }
+          : {
+              text: run.text,
+              coalescedUntil: run.lastSequence,
+            },
     });
     run = null;
   };
@@ -55,10 +56,10 @@ export function coalesceSessionEventDeltas(events: SessionEvent[]): SessionEvent
     const sandboxStream = isSandbox ? sandboxDeltaString(event.payload, "stream") : undefined;
     const sandboxCommandId = isSandbox ? sandboxDeltaString(event.payload, "commandId") : undefined;
     if (
-      run
-      && sameDeltaRun(run.first, event, run.sandboxName, sandboxName)
-      && run.sandboxStream === sandboxStream
-      && run.sandboxCommandId === sandboxCommandId
+      run &&
+      sameDeltaRun(run.first, event, run.sandboxName, sandboxName) &&
+      run.sandboxStream === sandboxStream &&
+      run.sandboxCommandId === sandboxCommandId
     ) {
       run.text += deltaText(event);
       run.lastSequence = event.sequence;
@@ -145,5 +146,5 @@ function sandboxDeltaString(payload: unknown, key: "stream" | "commandId"): stri
 }
 
 function asRecord(value: unknown): Record<string, unknown> {
-  return value && typeof value === "object" ? value as Record<string, unknown> : {};
+  return value && typeof value === "object" ? (value as Record<string, unknown>) : {};
 }

package/src/index.ts

@@ -1,8 +1,21 @@
-import type { SessionBusMessage, SessionEvent } from "@opengeni/contracts";
-import { appendSessionEvents, sessionSubject, type AppendEventInput, type Database } from "@opengeni/db";
-import { connect, JSONCodec, type ConnectionOptions, type Msg, type NatsConnection, type Subscription } from "nats";
+import type { SessionBusMessage, SessionEvent, WorkspaceControlEvent } from "@opengeni/contracts";
+import {
+  appendSessionEvents,
+  appendSessionEventsForTurnAttempt,
+  sessionSubject,
+  type AppendEventInput,
+  type Database,
+} from "@opengeni/db";
+import {
+  connect,
+  JSONCodec,
+  type ConnectionOptions,
+  type Msg,
+  type NatsConnection,
+  type Subscription,
+} from "nats";
 
-const codec = JSONCodec<SessionBusMessage | SessionEvent>();
+const codec = JSONCodec<SessionBusMessage | SessionEvent | WorkspaceControlEvent>();
 
 export type EventLogger = {
   debug?: (message: string, attributes?: Record<string, unknown>) => void;
@@ -11,6 +24,8 @@ export type EventLogger = {
 
 export type EventBusOptions = {
   logger?: EventLogger;
+  /** Test/host transport seam; production defaults to the nats.js connector. */
+  connect?: typeof connect;
 };
 
 const silentLogger: Required<EventLogger> = {
@@ -163,6 +178,19 @@ export interface RequestConnection {
   request(subject: string, payload: Uint8Array, opts: { timeout: number }): Promise<RequestReply>;
 }
 
+/**
+ * The raw subscribe/publish surface the selfhosted OP-STREAM transport consumes
+ * (structurally identical to `@opengeni/runtime`'s `NatsOpStreamConnection`):
+ * a plain subscription for the runner's fire-and-forget op frames
+ * (`agent.<ws>.<id>.op.<op_id>`) and a plain publish for the server's acks
+ * (`agent.<ws>.<id>.ack`). Same managed connection as everything else — a NATS
+ * connection natively supports all of it; there is NEVER a second connection.
+ */
+export interface OpStreamConnection {
+  subscribe(subject: string): AsyncIterable<{ data: Uint8Array }> & { unsubscribe(): void };
+  publish(subject: string, payload: Uint8Array): void;
+}
+
 /**
  * A handler answering a request/reply on a subscribed subject: given the request
  * bytes (+ the concrete subject the message landed on, for `agent.<ws>.<id>.rpc`
@@ -170,11 +198,25 @@ export interface RequestConnection {
  * leaves the request unanswered (the caller's request times out / sees no
  * responder), which the control plane maps to `agent_offline` / reconnecting.
  */
-export type RequestHandler = (request: Uint8Array, subject: string) => Promise<Uint8Array> | Uint8Array;
+export type RequestHandler = (
+  request: Uint8Array,
+  subject: string,
+) => Promise<Uint8Array> | Uint8Array;
 
 export type EventBus = {
   publish: (workspaceId: string, sessionId: string, events: SessionEvent[]) => Promise<void>;
-  subscribe: (workspaceId: string, sessionId: string, onEvents: (events: SessionEvent[]) => void | Promise<void>) => Promise<() => void>;
+  subscribe: (
+    workspaceId: string,
+    sessionId: string,
+    onEvents: (events: SessionEvent[]) => void | Promise<void>,
+  ) => Promise<() => void>;
+  /** Best-effort live invalidation; the event is already durable in Postgres. */
+  publishWorkspaceControl: (workspaceId: string, event: WorkspaceControlEvent) => Promise<void>;
+  /** One workspace subscription fans a control change to every open descendant view. */
+  subscribeWorkspaceControl: (
+    workspaceId: string,
+    onEvent: (event: WorkspaceControlEvent) => void | Promise<void>,
+  ) => Promise<() => void>;
   /**
    * Issue a binary request/reply on a subject over the bus's NATS connection
    * (the selfhosted control plane: `agent.<ws>.<id>.rpc`). A new usage of what was
@@ -182,7 +224,11 @@ export type EventBus = {
    * no-responder (NATS 503) or a request timeout; the caller (`NatsControlRpc`)
    * maps those to `agent_offline` / `agent_reconnecting`, never a NotFound.
    */
-  request: (subject: string, payload: Uint8Array, opts: { timeoutMs: number }) => Promise<RequestReply>;
+  request: (
+    subject: string,
+    payload: Uint8Array,
+    opts: { timeoutMs: number },
+  ) => Promise<RequestReply>;
   /**
    * Subscribe-and-reply on a subject (the responder side — the enrolled agent, or
    * a test stand-in for it): for every request on `subject`, call `handler` and
@@ -209,6 +255,12 @@ export type EventBus = {
    * plane injects this so the transport never opens a second connection.
    */
   getRequestConnection: () => RequestConnection;
+  /**
+   * The `OpStreamConnection` accessor the selfhosted op-stream transport
+   * consumes (`NatsOpStreamTransport`) — the same managed connection again.
+   * Optional so bus test doubles that never exercise op-stream stay valid.
+   */
+  getOpStreamConnection?: () => OpStreamConnection;
   isConnected?: () => boolean;
   close: () => Promise<void>;
 };
@@ -231,10 +283,15 @@ export async function createNatsEventBus(
     connectOptions.user = auth.user;
     connectOptions.pass = auth.pass;
   }
-  const nc = await connect(withReconnectDefaults(connectOptions));
+  const nc = await (options.connect ?? connect)(withReconnectDefaults(connectOptions));
   let connected = true;
   logConnectionStatus(nc, "event-bus", options.logger, (type) => {
-    if (type === "disconnect" || type === "reconnecting" || type === "staleConnection" || type === "error") {
+    if (
+      type === "disconnect" ||
+      type === "reconnecting" ||
+      type === "staleConnection" ||
+      type === "error"
+    ) {
       connected = false;
     } else if (type === "connect" || type === "reconnect") {
       connected = true;
@@ -243,6 +300,12 @@ export async function createNatsEventBus(
   const requestConnection: RequestConnection = {
     request: async (subject, payload, opts) => requestReply(nc, subject, payload, opts.timeout),
   };
+  const opStreamConnection: OpStreamConnection = {
+    subscribe: (subject) => nc.subscribe(subject),
+    publish: (subject, payload) => {
+      nc.publish(subject, payload);
+    },
+  };
   return {
     publish: async (workspaceId, sessionId, events) => {
       if (events.length === 0) {
@@ -257,24 +320,57 @@ export async function createNatsEventBus(
       // next successful publish's gap-backfill, or a stream reconnect); it must
       // never throw the in-flight turn to death.
       try {
-        nc.publish(sessionSubject(workspaceId, sessionId), codec.encode({ workspaceId, sessionId, events }));
+        nc.publish(
+          sessionSubject(workspaceId, sessionId),
+          codec.encode({ workspaceId, sessionId, events }),
+        );
       } catch (error) {
         // `publish()` throws synchronously only when the connection is fully
         // CLOSED (with infinite reconnect, effectively never outside shutdown).
-        (options.logger?.warn ?? silentLogger.warn)("NATS live publish dropped; events are durable in the DB and reconcile on stream replay", {
-          workspaceId,
-          sessionId,
-          error: error instanceof Error ? error.message : String(error),
-        });
+        (options.logger?.warn ?? silentLogger.warn)(
+          "NATS live publish dropped; events are durable in the DB and reconcile on stream replay",
+          {
+            workspaceId,
+            sessionId,
+            error: error instanceof Error ? error.message : String(error),
+          },
+        );
+        return;
+      }
+      await flushWithTimeout(nc, PUBLISH_FLUSH_TIMEOUT_MS);
+    },
+    subscribe: async (workspaceId, sessionId, onEvents) =>
+      subscribeSession(nc, workspaceId, sessionId, onEvents),
+    publishWorkspaceControl: async (workspaceId, event) => {
+      try {
+        nc.publish(workspaceControlSubject(workspaceId), codec.encode(event));
+      } catch (error) {
+        (options.logger?.warn ?? silentLogger.warn)(
+          "NATS workspace-control invalidation dropped; clients reconcile from Postgres",
+          {
+            workspaceId,
+            revision: event.revision,
+            error: error instanceof Error ? error.message : String(error),
+          },
+        );
         return;
       }
       await flushWithTimeout(nc, PUBLISH_FLUSH_TIMEOUT_MS);
     },
-    subscribe: async (workspaceId, sessionId, onEvents) => subscribeSession(nc, workspaceId, sessionId, onEvents),
+    subscribeWorkspaceControl: async (workspaceId, onEvent) => {
+      const sub = nc.subscribe(workspaceControlSubject(workspaceId));
+      void (async () => {
+        for await (const msg of sub) {
+          await onEvent(codec.decode(msg.data) as WorkspaceControlEvent);
+        }
+      })();
+      return () => sub.unsubscribe();
+    },
     request: async (subject, payload, opts) => requestReply(nc, subject, payload, opts.timeoutMs),
     subscribeRequests: (subject, handler) => subscribeRequests(nc, subject, handler),
     subscribeAgentEvents: (subject, handler) => subscribeAgentEvents(nc, subject, handler),
     getRequestConnection: () => requestConnection,
+    getOpStreamConnection: () => opStreamConnection,
     isConnected: () => connected && !nc.isClosed() && !nc.isDraining(),
     close: async () => {
       await nc.drain();
@@ -320,7 +416,7 @@ export async function createResponderConnection(
   auth: NatsConnectAuth,
   subject: string,
   handler: RequestHandler,
-  options: { name?: string; logger?: EventLogger } = {},
+  options: { name?: string; logger?: EventLogger; connect?: typeof connect } = {},
 ): Promise<ResponderConnection> {
   const connectOptions: ConnectionOptions = { servers: natsUrl };
   if (options.name) {
@@ -332,8 +428,12 @@ export async function createResponderConnection(
   } else if (auth.kind === "token") {
     connectOptions.token = auth.token;
   }
-  const nc = await connect(withReconnectDefaults(connectOptions));
-  logConnectionStatus(nc, options.name ? `auth-callout:${options.name}` : "auth-callout", options.logger);
+  const nc = await (options.connect ?? connect)(withReconnectDefaults(connectOptions));
+  logConnectionStatus(
+    nc,
+    options.name ? `auth-callout:${options.name}` : "auth-callout",
+    options.logger,
+  );
   const sub: Subscription = nc.subscribe(subject);
   void (async () => {
     for await (const msg of sub) {
@@ -357,15 +457,88 @@ export async function createResponderConnection(
   };
 }
 
-export async function appendAndPublishEvents(db: Database, bus: EventBus, workspaceId: string, sessionId: string, events: AppendEventInput[]): Promise<SessionEvent[]> {
-  const appended = await appendSessionEvents(db, workspaceId, sessionId, events);
-  // The DB append above is the durable system of record; the publish is only a
+/**
+ * Optional timing seam for {@link appendAndPublishEvents}: `onAppend` fires after
+ * the durable DB write, `onPublish` after the best-effort live fan-out (on both
+ * success AND failure of the publish, so a broker blip still records its latency).
+ * Kept as a plain callback so the events package takes no dependency on the
+ * observability package; the worker wires it to Prometheus histograms.
+ */
+export type AppendPublishObserver = {
+  onAppend?: (info: { durationSeconds: number; count: number }) => void;
+  onPublish?: (info: { durationSeconds: number; count: number }) => void;
+};
+
+export type AppendPublishOptions = AppendPublishObserver & {
+  /** Test/host persistence seam; production uses the database implementation. */
+  appendSessionEvents?: typeof appendSessionEvents;
+};
+
+/**
+ * Invoke a phase-timing callback with the elapsed seconds since `startedAt` and the
+ * event count, swallowing any throw so a metrics sink can never break the
+ * append/publish path. Exported for direct unit testing: the wider test suite
+ * installs a process-global `mock.module("@opengeni/events")` that stubs
+ * `appendAndPublishEvents` (spreading the real module for everything else), so the
+ * observer wiring can only be exercised through a helper that survives that mock.
+ */
+export function observeSince(
+  fn: ((info: { durationSeconds: number; count: number }) => void) | undefined,
+  startedAt: number,
+  count: number,
+): void {
+  if (!fn) {
+    return;
+  }
+  try {
+    fn({ durationSeconds: Math.max(0, (performance.now() - startedAt) / 1000), count });
+  } catch {
+    // Metrics emission must never affect the append/publish path.
+  }
+}
+
+export async function appendAndPublishEvents(
+  db: Database,
+  bus: EventBus,
+  workspaceId: string,
+  sessionId: string,
+  events: AppendEventInput[],
+  options: AppendPublishOptions = {},
+): Promise<SessionEvent[]> {
+  const appendStartedAt = performance.now();
+  const appended = await (options.appendSessionEvents ?? appendSessionEvents)(
+    db,
+    workspaceId,
+    sessionId,
+    events,
+  );
+  observeSince(options.onAppend, appendStartedAt, appended.length);
+  await publishDurableSessionEvents(bus, workspaceId, sessionId, appended, options);
+  return appended;
+}
+
+/**
+ * Best-effort live fanout for events another DB helper already committed in
+ * the same transaction as related durable state. This must never append again.
+ */
+export async function publishDurableSessionEvents(
+  bus: EventBus,
+  workspaceId: string,
+  sessionId: string,
+  appended: SessionEvent[],
+  observe?: AppendPublishObserver,
+): Promise<void> {
+  if (appended.length === 0) {
+    return;
+  }
+  // The committed DB events are the durable system of record; this publish is only a
   // best-effort LIVE fan-out. Guard it so NO EventBus implementation can throw an
   // in-flight agent turn to death on a transient NATS disconnect — consumers
   // reconcile any missed live events from the durable log via the events/stream
   // endpoint (DB replay + gap-backfill). The managed `createNatsEventBus` bus
   // already swallows internally, so this catch is the belt-and-suspenders guard
   // for any other bus impl (and a fully CLOSED connection during shutdown).
+  const publishStartedAt = performance.now();
   try {
     await bus.publish(workspaceId, sessionId, appended);
   } catch (error) {
@@ -374,10 +547,62 @@ export async function appendAndPublishEvents(db: Database, bus: EventBus, worksp
       error,
     );
   }
-  return appended;
+  observeSince(observe?.onPublish, publishStartedAt, appended.length);
+}
+
+/** Best-effort fanout for a workspace-control event already committed in PostgreSQL. */
+export async function publishDurableWorkspaceControlEvent(
+  bus: EventBus,
+  workspaceId: string,
+  event: WorkspaceControlEvent,
+): Promise<void> {
+  try {
+    await bus.publishWorkspaceControl(workspaceId, event);
+  } catch (error) {
+    console.warn(
+      `[events] workspace-control live publish failed for ${workspaceId} at revision ${event.revision}; the event is durable and reconciles on stream replay`,
+      error,
+    );
+  }
+}
+
+export async function appendAndPublishTurnEventsFenced(
+  db: Database,
+  bus: EventBus,
+  workspaceId: string,
+  sessionId: string,
+  turnId: string,
+  executionGeneration: number,
+  attemptId: string,
+  events: AppendEventInput[],
+): Promise<{ events: SessionEvent[]; accepted: boolean }> {
+  const result = await appendSessionEventsForTurnAttempt(
+    db,
+    workspaceId,
+    sessionId,
+    turnId,
+    executionGeneration,
+    attemptId,
+    events,
+  );
+  if (result.events.length === 0) return result;
+  try {
+    await bus.publish(workspaceId, sessionId, result.events);
+  } catch (error) {
+    console.warn(
+      `[events] live fenced publish failed for ${workspaceId}/${sessionId}/${turnId}@${executionGeneration}/${attemptId}; ${result.events.length} event(s) are durable`,
+      error,
+    );
+  }
+  return result;
 }
 
-function subscribeSession(nc: NatsConnection, workspaceId: string, sessionId: string, onEvents: (events: SessionEvent[]) => void | Promise<void>): () => void {
+function subscribeSession(
+  nc: NatsConnection,
+  workspaceId: string,
+  sessionId: string,
+  onEvents: (events: SessionEvent[]) => void | Promise<void>,
+): () => void {
   const sub: Subscription = nc.subscribe(sessionSubject(workspaceId, sessionId));
   void (async () => {
     for await (const msg of sub) {
@@ -398,7 +623,12 @@ function subscribeSession(nc: NatsConnection, workspaceId: string, sessionId: st
  * the caller owns the mapping. The reply is delivered via the connection's
  * built-in mux inbox; no extra subscription is created here.
  */
-async function requestReply(nc: NatsConnection, subject: string, payload: Uint8Array, timeout: number): Promise<RequestReply> {
+async function requestReply(
+  nc: NatsConnection,
+  subject: string,
+  payload: Uint8Array,
+  timeout: number,
+): Promise<RequestReply> {
   const msg: Msg = await nc.request(subject, payload, { timeout });
   return { data: msg.data };
 }
@@ -410,7 +640,11 @@ async function requestReply(nc: NatsConnection, subject: string, payload: Uint8A
  * A handler that throws (or a message with no `reply` subject) is left unanswered
  * — the requester then sees a timeout, never a malformed reply.
  */
-function subscribeRequests(nc: NatsConnection, subject: string, handler: RequestHandler): () => void {
+function subscribeRequests(
+  nc: NatsConnection,
+  subject: string,
+  handler: RequestHandler,
+): () => void {
   const sub: Subscription = nc.subscribe(subject);
   void (async () => {
     for await (const msg of sub) {
@@ -462,7 +696,7 @@ function subscribeAgentEvents(
   };
 }
 
-export function formatSse(event: SessionEvent): string {
+export function formatSse<T extends { sequence: number; type: string }>(event: T): string {
   return [
     `id: ${event.sequence}`,
     `event: ${event.type}`,
@@ -471,3 +705,7 @@ export function formatSse(event: SessionEvent): string {
     "",
   ].join("\n");
 }
+
+function workspaceControlSubject(workspaceId: string): string {
+  return `workspaces.${workspaceId}.control`;
+}