@opengeni/events 0.3.36 → 0.3.52

package/dist/coalesce.d.ts

@@ -0,0 +1,4 @@
+import { type SessionEvent } from "@opengeni/contracts";
+/** Flush long runs incrementally before concatenation can become unbounded. */
+export declare const SESSION_EVENT_COALESCED_TEXT_TARGET_BYTES: number;
+export declare function coalesceSessionEventDeltas(events: SessionEvent[]): SessionEvent[];

package/dist/index.d.ts

@@ -1,144 +1,35 @@
-import { SessionEvent, WorkspaceControlEvent } from '@opengeni/contracts';
-import { appendSessionEvents, Database, AppendEventInput } from '@opengeni/db';
-import { connect } from 'nats';
-export { NatsConnection, connect, nkeys } from 'nats';
-
-/** Flush long runs incrementally before concatenation can become unbounded. */
-declare const SESSION_EVENT_COALESCED_TEXT_TARGET_BYTES: number;
-declare function coalesceSessionEventDeltas(events: SessionEvent[]): SessionEvent[];
-
-/** A NATS permission set: subject allow/deny lists (ADR-26 `pub`/`sub` →
- *  `allow`/`deny`). An empty/undefined list means "no explicit grant" — combined
- *  with the agent scope below, the connection can ONLY reach what `allow` lists. */
-interface NatsPermission {
-    allow?: string[];
-    deny?: string[];
-}
-/** The pub/sub permissions embedded in a user JWT. */
-interface NatsPermissions {
-    pub: NatsPermission;
-    sub: NatsPermission;
-}
-/**
- * Input to mint a workspace-scoped NATS user JWT for an enrolled agent.
- *   - `userPublicKey` — the `user_nkey` from the authorization request; it MUST be
- *     the `sub` of the user JWT (nats-server rejects a mismatch).
- *   - `accountSeed` — the callout account SIGNING seed (`SA...`); both the user JWT
- *     `iss` (its public key) and the signature come from it. NEVER logged.
- *   - `name` — a human label for the user (the agent id), for server logs.
- *   - `permissions` — the pub/sub allow/deny lists (the workspace scope).
- *   - `expiresAtSeconds` — optional absolute `exp` (unix seconds). When set the
- *     server will expire the connection's credential; we tie it to the bearer's
- *     remaining life so a revoked/expired enrollment cannot outlive its bearer.
- */
-interface MintUserJwtInput {
-    userPublicKey: string;
-    accountSeed: string;
-    name: string;
-    permissions: NatsPermissions;
-    /** The target account NAME (the `auth_callout.account`) the user binds to; the
-     *  embedded user JWT's `aud` in server-config mode. */
-    audienceAccount: string;
-    expiresAtSeconds?: number;
-}
-/**
- * Mint a signed NATS user JWT scoped by `permissions`. In auth-callout SERVER
- * mode the user JWT is signed by the callout ISSUER ACCOUNT key, and its `iss` is
- * that account's public key. The returned JWT is embedded as `nats.jwt` in the
- * authorization response.
- */
-declare function mintUserJwt(input: MintUserJwtInput): string;
-/**
- * Input to mint the authorization RESPONSE JWT the responder publishes back on the
- * request's reply subject (ADR-26 §3).
- *   - `userPublicKey` — the request's `user_nkey`; the response `sub`.
- *   - `serverId` — the request's `nats.server_id.id` (the server's public key); the
- *     response `aud`.
- *   - `accountSeed` — the callout account signing seed; signs the response and is
- *     its `iss` (public key). NEVER logged.
- *   - `userJwt` — the embedded signed user JWT (omit on a denial).
- *   - `error` — a human-readable denial message (omit on success). When present the
- *     server denies the connection.
- */
-interface MintAuthResponseInput {
-    userPublicKey: string;
-    serverId: string;
-    accountSeed: string;
-    userJwt?: string;
-    error?: string;
-}
-/**
- * Mint the signed authorization-response JWT. On success it carries the embedded
- * user JWT (`nats.jwt`); on denial it carries `nats.error` and NO user JWT, which
- * makes nats-server refuse the connection. Signed by the callout account key (its
- * public key is `iss`); `sub` is the user_nkey, `aud` is the server id.
- */
-declare function mintAuthResponse(input: MintAuthResponseInput): string;
-/**
- * The fields the responder needs out of the authorization REQUEST JWT (ADR-26 §2).
- * The request is itself a NATS JWT (`header.payload.signature`) the server signs;
- * we only DECODE it (the server proves its own identity by the connection, and the
- * embedded `auth_token` is independently HMAC-verified), so we read the payload
- * without re-verifying the server signature.
- */
-interface DecodedAuthRequest {
-    /** The public user nkey the response user JWT MUST be `sub`-scoped to. */
-    userNkey: string;
-    /** The server's public id — the response `aud`. */
-    serverId: string;
-    /** The connect `auth_token` the client presented (our `oge_` bearer), if any. */
-    authToken: string | undefined;
-    /** The connect username, if any (unused today; present for completeness). */
-    user: string | undefined;
-}
-/**
- * Decode the authorization-request JWT payload (the middle base64url segment). The
- * request shape (ADR-26 §2): `nats.user_nkey`, `nats.server_id.id`, and the
- * presented connect options under `nats.connect_opts` (`auth_token` / `user`).
- * Returns null on a malformed token so the caller can deny cleanly.
- */
-declare function decodeAuthRequest(token: string): DecodedAuthRequest | null;
-/**
- * Build the workspace-scoped permission set for an agent: it may publish + subscribe
- * ONLY `agent.<workspaceId>.>` (its own RPC/event/hello subtree) and the reply
- * `_INBOX.>` subtree (so request/reply round-trips work). Everything else is
- * implicitly denied (an allow-list with no other entries IS the deny-all-else).
- *
- * THE isolation assertion (§17): with `workspaceId=A`, the returned allow lists name
- * only `agent.A.>` — so a connection bearing this credential is rejected by
- * nats-server the instant it tries to pub/sub `agent.B.>`. This is the per-workspace
- * tenancy boundary, enforced cryptographically by the signed JWT, not by naming.
- */
-declare function workspaceAgentPermissions(workspaceId: string): NatsPermissions;
-
-type EventLogger = {
+import { type SessionEvent, type WorkspaceControlEvent } from "@opengeni/contracts";
+import { appendSessionEvents, type AppendEventInput, type Database } from "@opengeni/db";
+import { connect } from "nats";
+export type EventLogger = {
     debug?: (message: string, attributes?: Record<string, unknown>) => void;
     warn?: (message: string, attributes?: Record<string, unknown>) => void;
 };
-type EventBusOptions = {
+export type EventBusOptions = {
     logger?: EventLogger;
     /** Test/host transport seam; production defaults to the nats.js connector. */
     connect?: typeof connect;
 };
-
+export { SESSION_EVENT_COALESCED_TEXT_TARGET_BYTES, coalesceSessionEventDeltas } from "./coalesce";
 /** Comfortably below NATS Core's common 1 MiB max_payload default. */
-declare const SESSION_EVENT_NATS_MESSAGE_MAX_BYTES: number;
+export declare const SESSION_EVENT_NATS_MESSAGE_MAX_BYTES: number;
 /** Payload is <=64 KiB; the larger envelope leaves deterministic wire headroom. */
-declare const SESSION_EVENT_SSE_FRAME_MAX_BYTES: number;
+export declare const SESSION_EVENT_SSE_FRAME_MAX_BYTES: number;
 /** Independent count+byte envelope for one durable HTTP replay response. */
-declare const SESSION_EVENT_HTTP_PAGE_MAX_BYTES: number;
+export declare const SESSION_EVENT_HTTP_PAGE_MAX_BYTES: number;
 /** Workspace invalidations are one compact event, never a broker evidence blob. */
-declare const WORKSPACE_CONTROL_NATS_MESSAGE_MAX_BYTES: number;
+export declare const WORKSPACE_CONTROL_NATS_MESSAGE_MAX_BYTES: number;
 /** Count+byte envelope for one workspace-control REST replay page. */
-declare const WORKSPACE_CONTROL_HTTP_PAGE_MAX_BYTES: number;
-
+export declare const WORKSPACE_CONTROL_HTTP_PAGE_MAX_BYTES: number;
+export { decodeAuthRequest, mintAuthResponse, mintUserJwt, workspaceAgentPermissions, type DecodedAuthRequest, type MintAuthResponseInput, type MintUserJwtInput, type NatsPermission, type NatsPermissions, } from "./nats-jwt";
+export { connect, nkeys, type NatsConnection } from "nats";
 /**
  * A raw request/reply reply — just the response bytes. Mirrors the subset of the
  * NATS `Msg` shape a binary request/reply caller needs (`NatsControlRpc` consumes
  * exactly this). Kept minimal so the events package does not leak the `nats` `Msg`
  * type into the agent-loop-free runtime leaf.
  */
-type RequestReply = {
+export type RequestReply = {
     data: Uint8Array;
 };
 /**
@@ -149,7 +40,7 @@ type RequestReply = {
  * natively supports both pub/sub and request/reply, so there is NEVER a second
  * connection.
  */
-interface RequestConnection {
+export interface RequestConnection {
     request(subject: string, payload: Uint8Array, opts: {
         timeout: number;
     }): Promise<RequestReply>;
@@ -162,7 +53,7 @@ interface RequestConnection {
  * (`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 {
+export interface OpStreamConnection {
     subscribe(subject: string): AsyncIterable<{
         data: Uint8Array;
     }> & {
@@ -177,8 +68,8 @@ interface OpStreamConnection {
  * leaves the request unanswered (the caller's request times out / sees no
  * responder), which the control plane maps to `agent_offline` / reconnecting.
  */
-type RequestHandler = (request: Uint8Array, subject: string) => Promise<Uint8Array> | Uint8Array;
-type EventBus = {
+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>;
     /** Best-effort live invalidation; the event is already durable in Postgres. */
@@ -235,7 +126,7 @@ type EventBus = {
  * is omitted the connection is anonymous (local dev / a NATS without auth_callout)
  * — the existing behavior, unchanged.
  */
-declare function createNatsEventBus(natsUrl: string, auth?: {
+export declare function createNatsEventBus(natsUrl: string, auth?: {
     user: string;
     pass: string;
 }, options?: EventBusOptions): Promise<EventBus>;
@@ -252,12 +143,12 @@ declare function createNatsEventBus(natsUrl: string, auth?: {
  * server publishes an authorization request with a reply inbox; the handler returns
  * the signed authorization-response bytes which we `respond` on that inbox.
  */
-interface ResponderConnection {
+export interface ResponderConnection {
     /** Subscribe-and-reply on `subject`; returns an async close that drains. */
     close: () => Promise<void>;
 }
 /** Connection auth for a standalone NATS connection (the callout responder). */
-type NatsConnectAuth = {
+export type NatsConnectAuth = {
     kind: "user-password";
     user: string;
     pass: string;
@@ -276,7 +167,7 @@ type NatsConnectAuth = {
  * connection on its own timeout, which is the correct fail-closed behavior (a
  * responder bug must never accidentally grant access).
  */
-declare function createResponderConnection(natsUrl: string, auth: NatsConnectAuth, subject: string, handler: RequestHandler, options?: {
+export declare function createResponderConnection(natsUrl: string, auth: NatsConnectAuth, subject: string, handler: RequestHandler, options?: {
     name?: string;
     logger?: EventLogger;
     connect?: typeof connect;
@@ -288,7 +179,7 @@ declare function createResponderConnection(natsUrl: string, auth: NatsConnectAut
  * 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 = {
+export type AppendPublishObserver = {
     onAppend?: (info: {
         durationSeconds: number;
         count: number;
@@ -298,7 +189,7 @@ type AppendPublishObserver = {
         count: number;
     }) => void;
 };
-type AppendPublishOptions = AppendPublishObserver & {
+export type AppendPublishOptions = AppendPublishObserver & {
     /** Test/host persistence seam; production uses the database implementation. */
     appendSessionEvents?: typeof appendSessionEvents;
 };
@@ -310,40 +201,40 @@ type AppendPublishOptions = AppendPublishObserver & {
  * `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: {
+export 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[]>;
+export 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>;
+export 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<{
+export declare function publishDurableWorkspaceControlEvent(bus: EventBus, workspaceId: string, event: WorkspaceControlEvent): Promise<void>;
+export 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 {
+export declare function formatSse<T extends {
     sequence: number;
     type: string;
 }>(event: T): string;
 /** Canonical one-event NATS payload with an exact broker byte assertion. */
-declare function workspaceControlEventNatsPayload(event: WorkspaceControlEvent): Uint8Array;
+export declare function workspaceControlEventNatsPayload(event: WorkspaceControlEvent): Uint8Array;
 /** Defensively bounds current and historical workspace invalidations per frame. */
-declare function formatWorkspaceControlEventSse(event: WorkspaceControlEvent): string;
+export declare function formatWorkspaceControlEventSse(event: WorkspaceControlEvent): string;
 /** Defensively bounds historical rows before they become one SSE frame. */
-declare function formatSessionEventSse(event: SessionEvent): string;
+export declare function formatSessionEventSse(event: SessionEvent): string;
 /**
  * Split an already-durable batch by exact encoded NATS bytes. Each event is
  * defensively normalized first so historical oversized rows cannot exceed the
  * broker envelope. Sequence and ordering are unchanged across chunks.
  */
-declare function sessionEventBatchesByBytes(workspaceId: string, sessionId: string, events: readonly SessionEvent[], maxBytes?: number): SessionEvent[][];
+export declare function sessionEventBatchesByBytes(workspaceId: string, sessionId: string, events: readonly SessionEvent[], maxBytes?: number): SessionEvent[][];
 /** Return one count+byte-bounded HTTP page and truthful continuation facts. */
-declare function boundSessionEventHttpPage(events: readonly SessionEvent[], options: {
+export declare function boundSessionEventHttpPage(events: readonly SessionEvent[], options: {
     direction: "after" | "before";
     maxBytes?: number;
 }): {
@@ -353,13 +244,11 @@ declare function boundSessionEventHttpPage(events: readonly SessionEvent[], opti
     bytes: number;
 };
 /** Return one count+byte-bounded workspace-control page and resume cursor. */
-declare function boundWorkspaceControlHttpPage(events: readonly WorkspaceControlEvent[], maxBytes?: number): {
+export declare function boundWorkspaceControlHttpPage(events: readonly WorkspaceControlEvent[], maxBytes?: number): {
     events: WorkspaceControlEvent[];
     truncated: boolean;
     nextSequence: number | null;
     bytes: number;
 };
 /** Raw durable cursor covered by a possibly coalesced compact event. */
-declare function sessionEventResumeSequence(event: SessionEvent): number;
-
-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, SESSION_EVENT_COALESCED_TEXT_TARGET_BYTES, SESSION_EVENT_HTTP_PAGE_MAX_BYTES, SESSION_EVENT_NATS_MESSAGE_MAX_BYTES, SESSION_EVENT_SSE_FRAME_MAX_BYTES, WORKSPACE_CONTROL_HTTP_PAGE_MAX_BYTES, WORKSPACE_CONTROL_NATS_MESSAGE_MAX_BYTES, appendAndPublishEvents, appendAndPublishTurnEventsFenced, boundSessionEventHttpPage, boundWorkspaceControlHttpPage, coalesceSessionEventDeltas, createNatsEventBus, createResponderConnection, decodeAuthRequest, formatSessionEventSse, formatSse, formatWorkspaceControlEventSse, mintAuthResponse, mintUserJwt, observeSince, publishDurableSessionEvents, publishDurableWorkspaceControlEvent, sessionEventBatchesByBytes, sessionEventResumeSequence, workspaceAgentPermissions, workspaceControlEventNatsPayload };
+export declare function sessionEventResumeSequence(event: SessionEvent): number;

package/dist/nats-jwt.d.ts

@@ -0,0 +1,103 @@
+/** A NATS permission set: subject allow/deny lists (ADR-26 `pub`/`sub` →
+ *  `allow`/`deny`). An empty/undefined list means "no explicit grant" — combined
+ *  with the agent scope below, the connection can ONLY reach what `allow` lists. */
+export interface NatsPermission {
+    allow?: string[];
+    deny?: string[];
+}
+/** The pub/sub permissions embedded in a user JWT. */
+export interface NatsPermissions {
+    pub: NatsPermission;
+    sub: NatsPermission;
+}
+/**
+ * Input to mint a workspace-scoped NATS user JWT for an enrolled agent.
+ *   - `userPublicKey` — the `user_nkey` from the authorization request; it MUST be
+ *     the `sub` of the user JWT (nats-server rejects a mismatch).
+ *   - `accountSeed` — the callout account SIGNING seed (`SA...`); both the user JWT
+ *     `iss` (its public key) and the signature come from it. NEVER logged.
+ *   - `name` — a human label for the user (the agent id), for server logs.
+ *   - `permissions` — the pub/sub allow/deny lists (the workspace scope).
+ *   - `expiresAtSeconds` — optional absolute `exp` (unix seconds). When set the
+ *     server will expire the connection's credential; we tie it to the bearer's
+ *     remaining life so a revoked/expired enrollment cannot outlive its bearer.
+ */
+export interface MintUserJwtInput {
+    userPublicKey: string;
+    accountSeed: string;
+    name: string;
+    permissions: NatsPermissions;
+    /** The target account NAME (the `auth_callout.account`) the user binds to; the
+     *  embedded user JWT's `aud` in server-config mode. */
+    audienceAccount: string;
+    expiresAtSeconds?: number;
+}
+/**
+ * Mint a signed NATS user JWT scoped by `permissions`. In auth-callout SERVER
+ * mode the user JWT is signed by the callout ISSUER ACCOUNT key, and its `iss` is
+ * that account's public key. The returned JWT is embedded as `nats.jwt` in the
+ * authorization response.
+ */
+export declare function mintUserJwt(input: MintUserJwtInput): string;
+/**
+ * Input to mint the authorization RESPONSE JWT the responder publishes back on the
+ * request's reply subject (ADR-26 §3).
+ *   - `userPublicKey` — the request's `user_nkey`; the response `sub`.
+ *   - `serverId` — the request's `nats.server_id.id` (the server's public key); the
+ *     response `aud`.
+ *   - `accountSeed` — the callout account signing seed; signs the response and is
+ *     its `iss` (public key). NEVER logged.
+ *   - `userJwt` — the embedded signed user JWT (omit on a denial).
+ *   - `error` — a human-readable denial message (omit on success). When present the
+ *     server denies the connection.
+ */
+export interface MintAuthResponseInput {
+    userPublicKey: string;
+    serverId: string;
+    accountSeed: string;
+    userJwt?: string;
+    error?: string;
+}
+/**
+ * Mint the signed authorization-response JWT. On success it carries the embedded
+ * user JWT (`nats.jwt`); on denial it carries `nats.error` and NO user JWT, which
+ * makes nats-server refuse the connection. Signed by the callout account key (its
+ * public key is `iss`); `sub` is the user_nkey, `aud` is the server id.
+ */
+export declare function mintAuthResponse(input: MintAuthResponseInput): string;
+/**
+ * The fields the responder needs out of the authorization REQUEST JWT (ADR-26 §2).
+ * The request is itself a NATS JWT (`header.payload.signature`) the server signs;
+ * we only DECODE it (the server proves its own identity by the connection, and the
+ * embedded `auth_token` is independently HMAC-verified), so we read the payload
+ * without re-verifying the server signature.
+ */
+export interface DecodedAuthRequest {
+    /** The public user nkey the response user JWT MUST be `sub`-scoped to. */
+    userNkey: string;
+    /** The server's public id — the response `aud`. */
+    serverId: string;
+    /** The connect `auth_token` the client presented (our `oge_` bearer), if any. */
+    authToken: string | undefined;
+    /** The connect username, if any (unused today; present for completeness). */
+    user: string | undefined;
+}
+/**
+ * Decode the authorization-request JWT payload (the middle base64url segment). The
+ * request shape (ADR-26 §2): `nats.user_nkey`, `nats.server_id.id`, and the
+ * presented connect options under `nats.connect_opts` (`auth_token` / `user`).
+ * Returns null on a malformed token so the caller can deny cleanly.
+ */
+export declare function decodeAuthRequest(token: string): DecodedAuthRequest | null;
+/**
+ * Build the workspace-scoped permission set for an agent: it may publish + subscribe
+ * ONLY `agent.<workspaceId>.>` (its own RPC/event/hello subtree) and the reply
+ * `_INBOX.>` subtree (so request/reply round-trips work). Everything else is
+ * implicitly denied (an allow-list with no other entries IS the deny-all-else).
+ *
+ * THE isolation assertion (§17): with `workspaceId=A`, the returned allow lists name
+ * only `agent.A.>` — so a connection bearing this credential is rejected by
+ * nats-server the instant it tries to pub/sub `agent.B.>`. This is the per-workspace
+ * tenancy boundary, enforced cryptographically by the signed JWT, not by naming.
+ */
+export declare function workspaceAgentPermissions(workspaceId: string): NatsPermissions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/events",
-  "version": "0.3.36",
+  "version": "0.3.52",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -26,13 +26,13 @@
     "provenance": true
   },
   "scripts": {
-    "build": "tsup",
-    "typecheck": "tsgo --noEmit",
+    "build": "bun ../../scripts/build-typescript-package.ts",
+    "typecheck": "tsc --noEmit",
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
-    "@opengeni/contracts": "^0.23.0",
-    "@opengeni/db": "^0.14.3",
+    "@opengeni/contracts": "^0.27.0",
+    "@opengeni/db": "^0.17.1",
     "nats": "^2.29.3"
   }
 }