@unagents/messenger-broker 0.0.0-stage → 0.10.0

package/dist/index.d.mts

@@ -0,0 +1,111 @@
+import { Peer, Message, RelayedMessage, StoredProtocol } from '@unagents/messenger-protocol';
+
+/**
+ * Broker configuration. Every field can be given to `startBroker(options)`;
+ * anything left out falls back to the environment (`AGENT_MESSENGER_*`,
+ * same names and defaults as the JavaScript `legacy/src/config.js`).
+ */
+interface BrokerOptions {
+    /** HTTP listen port (`AGENT_MESSENGER_PORT`, default 7901). `0` = random free port. */
+    port?: number;
+    /** HTTP bind address (`AGENT_MESSENGER_BIND`, default `0.0.0.0`). */
+    bind?: string;
+    /** Bearer token; `""` disables auth (`AGENT_MESSENGER_TOKEN`, default `""`). */
+    token?: string;
+    /** Broker id shown in `/health` and discovery replies (`AGENT_MESSENGER_BROKER_ID`, default hostname). */
+    id?: string;
+    /** State file (`AGENT_MESSENGER_STATE`, default `~/.agent-messenger/broker.json`). */
+    stateFile?: string;
+    /** UDP discovery responder on/off (`AGENT_MESSENGER_DISCOVERY`, `"off"` disables; default on). */
+    discovery?: boolean;
+    /** UDP discovery port (`AGENT_MESSENGER_DISCOVERY_PORT`, default 7902). */
+    discoveryPort?: number;
+    /** UDP bind address when pinned (`AGENT_MESSENGER_DISCOVERY_ADDR`, default `""` = all interfaces). */
+    discoveryAddr?: string;
+    /**
+     * Run as a local fallback broker (`AGENT_MESSENGER_FALLBACK=1`, set by the client when it spawns one).
+     * A fallback probes for other brokers every `fallbackIntervalMs`; when it finds one it relays its
+     * undelivered messages there and exits. A permanent broker (default) never does this.
+     */
+    fallback?: boolean;
+    /** Fallback discovery interval in ms (`AGENT_MESSENGER_FALLBACK_INTERVAL_MS`, default 10000). */
+    fallbackIntervalMs?: number;
+    /** Called after a fallback broker has relayed its messages and closed itself (`main.ts` exits the process). */
+    onSupersede?: (url: string) => void;
+    /**
+     * Join the permanent-broker mesh (`AGENT_MESSENGER_MESH`, `"on"` enables; default off).
+     * Fallback brokers must leave this off: only brokers started with it take part.
+     */
+    mesh?: boolean;
+    /**
+     * Mesh members to sync with. Empty (default) = the `brokers` list of the client
+     * config file (`AGENT_MESSENGER_CONFIG`, default `~/.agent-messenger/config.json`), re-read every round.
+     */
+    meshBrokers?: string[];
+    /** Mesh sync interval in ms (`AGENT_MESSENGER_MESH_INTERVAL_MS`, default 5000). */
+    meshIntervalMs?: number;
+    /** Replicated peers disappear this long after their origin stopped syncing (`AGENT_MESSENGER_MESH_PEER_TTL_MS`, default 300000). */
+    meshPeerTtlMs?: number;
+    /** Client config file read for the mesh member list (`AGENT_MESSENGER_CONFIG`). */
+    configFile?: string;
+}
+type BrokerConfig = Required<Omit<BrokerOptions, "onSupersede">> & Pick<BrokerOptions, "onSupersede">;
+/** Marks a broker as a local fallback. Broker-private (not in the protocol ENV table, which mirrors legacy). */
+declare const FALLBACK_ENV = "AGENT_MESSENGER_FALLBACK";
+declare const FALLBACK_INTERVAL_ENV = "AGENT_MESSENGER_FALLBACK_INTERVAL_MS";
+/** Directory of the default state file (`~/.agent-messenger`). Not exported by protocol. */
+declare const STATE_DIR: string;
+/** Default state file path (`~/.agent-messenger/broker.json`). Not exported by protocol. */
+declare const DEFAULT_STATE_FILE: string;
+/** Mesh environment variables. Broker-private (not in the protocol's `ENV`, which mirrors the legacy names). */
+declare const MESH_ENV: {
+    readonly MESH: "AGENT_MESSENGER_MESH";
+    readonly INTERVAL_MS: "AGENT_MESSENGER_MESH_INTERVAL_MS";
+    readonly PEER_TTL_MS: "AGENT_MESSENGER_MESH_PEER_TTL_MS";
+};
+/** Read the broker-side environment exactly like `legacy/src/config.js`. */
+declare function configFromEnv(env?: NodeJS.ProcessEnv): BrokerConfig;
+/** `options` over environment over built-in defaults. */
+declare function resolveConfig(options?: BrokerOptions): BrokerConfig;
+
+/**
+ * On-disk shape of `~/.agent-messenger/broker.json` (written by core 0.4.0
+ * `legacy/src/broker.js`). Not part of the protocol package — broker-private.
+ */
+interface BrokerStateFile {
+    peers: Peer[];
+    messages: Message[];
+    nextMsgId: number;
+    /** Relayed messages waiting for their recipient to register (absent in files written before the fallback relay). */
+    pending?: PendingRelay[];
+    /** Protocol definitions (absent in files written before the protocol registry, or when none is held). */
+    protocols?: StoredProtocol[];
+}
+/** A message relayed from a fallback broker whose recipient has not registered here yet. */
+interface PendingRelay extends RelayedMessage {
+    /** ISO 8601; pending items older than the TTL are dropped. */
+    queued_at: string;
+}
+
+/** Package version, reported by `/health` and discovery replies (inlined at build time). */
+declare const VERSION: string;
+interface BrokerHandle {
+    /** Stop HTTP + UDP, flush a pending state save. Idempotent. */
+    close(): Promise<void>;
+    /** Port the HTTP server listens on (actual port when `port: 0` was given). */
+    port: number;
+    /** Broker id (`AGENT_MESSENGER_BROKER_ID`, default hostname). */
+    id: string;
+}
+/**
+ * Start the broker daemon: load state, sweep stale peers, listen on HTTP
+ * (h3 + listhen) and answer UDP discovery probes.
+ *
+ * Unlike the JavaScript `startBroker()`, this does not install SIGINT /
+ * SIGTERM handlers — callers own the lifecycle through `close()`
+ * (`src/main.ts` does that for the standalone entry).
+ */
+declare function startBroker(options?: BrokerOptions): Promise<BrokerHandle>;
+
+export { DEFAULT_STATE_FILE, FALLBACK_ENV, FALLBACK_INTERVAL_ENV, MESH_ENV, STATE_DIR, VERSION, configFromEnv, resolveConfig, startBroker };
+export type { BrokerConfig, BrokerHandle, BrokerOptions, BrokerStateFile };

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+import { Peer, Message, RelayedMessage, StoredProtocol } from '@unagents/messenger-protocol';
+
+/**
+ * Broker configuration. Every field can be given to `startBroker(options)`;
+ * anything left out falls back to the environment (`AGENT_MESSENGER_*`,
+ * same names and defaults as the JavaScript `legacy/src/config.js`).
+ */
+interface BrokerOptions {
+    /** HTTP listen port (`AGENT_MESSENGER_PORT`, default 7901). `0` = random free port. */
+    port?: number;
+    /** HTTP bind address (`AGENT_MESSENGER_BIND`, default `0.0.0.0`). */
+    bind?: string;
+    /** Bearer token; `""` disables auth (`AGENT_MESSENGER_TOKEN`, default `""`). */
+    token?: string;
+    /** Broker id shown in `/health` and discovery replies (`AGENT_MESSENGER_BROKER_ID`, default hostname). */
+    id?: string;
+    /** State file (`AGENT_MESSENGER_STATE`, default `~/.agent-messenger/broker.json`). */
+    stateFile?: string;
+    /** UDP discovery responder on/off (`AGENT_MESSENGER_DISCOVERY`, `"off"` disables; default on). */
+    discovery?: boolean;
+    /** UDP discovery port (`AGENT_MESSENGER_DISCOVERY_PORT`, default 7902). */
+    discoveryPort?: number;
+    /** UDP bind address when pinned (`AGENT_MESSENGER_DISCOVERY_ADDR`, default `""` = all interfaces). */
+    discoveryAddr?: string;
+    /**
+     * Run as a local fallback broker (`AGENT_MESSENGER_FALLBACK=1`, set by the client when it spawns one).
+     * A fallback probes for other brokers every `fallbackIntervalMs`; when it finds one it relays its
+     * undelivered messages there and exits. A permanent broker (default) never does this.
+     */
+    fallback?: boolean;
+    /** Fallback discovery interval in ms (`AGENT_MESSENGER_FALLBACK_INTERVAL_MS`, default 10000). */
+    fallbackIntervalMs?: number;
+    /** Called after a fallback broker has relayed its messages and closed itself (`main.ts` exits the process). */
+    onSupersede?: (url: string) => void;
+    /**
+     * Join the permanent-broker mesh (`AGENT_MESSENGER_MESH`, `"on"` enables; default off).
+     * Fallback brokers must leave this off: only brokers started with it take part.
+     */
+    mesh?: boolean;
+    /**
+     * Mesh members to sync with. Empty (default) = the `brokers` list of the client
+     * config file (`AGENT_MESSENGER_CONFIG`, default `~/.agent-messenger/config.json`), re-read every round.
+     */
+    meshBrokers?: string[];
+    /** Mesh sync interval in ms (`AGENT_MESSENGER_MESH_INTERVAL_MS`, default 5000). */
+    meshIntervalMs?: number;
+    /** Replicated peers disappear this long after their origin stopped syncing (`AGENT_MESSENGER_MESH_PEER_TTL_MS`, default 300000). */
+    meshPeerTtlMs?: number;
+    /** Client config file read for the mesh member list (`AGENT_MESSENGER_CONFIG`). */
+    configFile?: string;
+}
+type BrokerConfig = Required<Omit<BrokerOptions, "onSupersede">> & Pick<BrokerOptions, "onSupersede">;
+/** Marks a broker as a local fallback. Broker-private (not in the protocol ENV table, which mirrors legacy). */
+declare const FALLBACK_ENV = "AGENT_MESSENGER_FALLBACK";
+declare const FALLBACK_INTERVAL_ENV = "AGENT_MESSENGER_FALLBACK_INTERVAL_MS";
+/** Directory of the default state file (`~/.agent-messenger`). Not exported by protocol. */
+declare const STATE_DIR: string;
+/** Default state file path (`~/.agent-messenger/broker.json`). Not exported by protocol. */
+declare const DEFAULT_STATE_FILE: string;
+/** Mesh environment variables. Broker-private (not in the protocol's `ENV`, which mirrors the legacy names). */
+declare const MESH_ENV: {
+    readonly MESH: "AGENT_MESSENGER_MESH";
+    readonly INTERVAL_MS: "AGENT_MESSENGER_MESH_INTERVAL_MS";
+    readonly PEER_TTL_MS: "AGENT_MESSENGER_MESH_PEER_TTL_MS";
+};
+/** Read the broker-side environment exactly like `legacy/src/config.js`. */
+declare function configFromEnv(env?: NodeJS.ProcessEnv): BrokerConfig;
+/** `options` over environment over built-in defaults. */
+declare function resolveConfig(options?: BrokerOptions): BrokerConfig;
+
+/**
+ * On-disk shape of `~/.agent-messenger/broker.json` (written by core 0.4.0
+ * `legacy/src/broker.js`). Not part of the protocol package — broker-private.
+ */
+interface BrokerStateFile {
+    peers: Peer[];
+    messages: Message[];
+    nextMsgId: number;
+    /** Relayed messages waiting for their recipient to register (absent in files written before the fallback relay). */
+    pending?: PendingRelay[];
+    /** Protocol definitions (absent in files written before the protocol registry, or when none is held). */
+    protocols?: StoredProtocol[];
+}
+/** A message relayed from a fallback broker whose recipient has not registered here yet. */
+interface PendingRelay extends RelayedMessage {
+    /** ISO 8601; pending items older than the TTL are dropped. */
+    queued_at: string;
+}
+
+/** Package version, reported by `/health` and discovery replies (inlined at build time). */
+declare const VERSION: string;
+interface BrokerHandle {
+    /** Stop HTTP + UDP, flush a pending state save. Idempotent. */
+    close(): Promise<void>;
+    /** Port the HTTP server listens on (actual port when `port: 0` was given). */
+    port: number;
+    /** Broker id (`AGENT_MESSENGER_BROKER_ID`, default hostname). */
+    id: string;
+}
+/**
+ * Start the broker daemon: load state, sweep stale peers, listen on HTTP
+ * (h3 + listhen) and answer UDP discovery probes.
+ *
+ * Unlike the JavaScript `startBroker()`, this does not install SIGINT /
+ * SIGTERM handlers — callers own the lifecycle through `close()`
+ * (`src/main.ts` does that for the standalone entry).
+ */
+declare function startBroker(options?: BrokerOptions): Promise<BrokerHandle>;
+
+export { DEFAULT_STATE_FILE, FALLBACK_ENV, FALLBACK_INTERVAL_ENV, MESH_ENV, STATE_DIR, VERSION, configFromEnv, resolveConfig, startBroker };
+export type { BrokerConfig, BrokerHandle, BrokerOptions, BrokerStateFile };

package/dist/index.mjs

@@ -0,0 +1,12 @@
+import 'listhen';
+import 'h3';
+import '@unagents/messenger-protocol';
+export { D as DEFAULT_STATE_FILE, F as FALLBACK_ENV, a as FALLBACK_INTERVAL_ENV, M as MESH_ENV, S as STATE_DIR, V as VERSION, c as configFromEnv, r as resolveConfig, s as startBroker } from './shared/messenger-broker.B8W77sqB.mjs';
+import 'node:os';
+import 'node:path';
+import 'defu';
+import 'node:fs';
+import 'consola';
+import 'node:crypto';
+import 'node:http';
+import 'node:dgram';

package/dist/main.d.mts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/main.mjs

@@ -0,0 +1,23 @@
+import { s as startBroker, l as log } from './shared/messenger-broker.B8W77sqB.mjs';
+import 'listhen';
+import 'h3';
+import '@unagents/messenger-protocol';
+import 'node:os';
+import 'node:path';
+import 'defu';
+import 'node:fs';
+import 'consola';
+import 'node:crypto';
+import 'node:http';
+import 'node:dgram';
+
+const broker = await startBroker({
+  // fallback only: messages are relayed and the broker is closed, nothing left to do
+  onSupersede: () => process.exit(0)
+});
+const shutdown = () => {
+  log.info("shutting down");
+  broker.close().finally(() => process.exit(0));
+};
+process.once("SIGINT", shutdown);
+process.once("SIGTERM", shutdown);