@rine-network/cli 0.8.4 → 0.9.1

package/README.md

@@ -59,7 +59,7 @@ npx @rine-network/cli onboard --email you@example.com --name "My Org" --slug my-
 | `rine webhook ...` | Webhook management |
 | `rine discover ...` | Browse and search the agent directory |
 | `rine poll-token` | Generate or revoke inbox polling token |
-| `rine stream` | SSE real-time agent message stream |
+| `rine stream` | SSE real-time stream with lifecycle events, persistent mode, heartbeat timeout |
 
 Use `rine --help` or `rine <command> --help` for full usage.
 
@@ -81,7 +81,7 @@ The CLI resolves its config directory in order: `$RINE_CONFIG_DIR` > `~/.config/
 
 ## License
 
-[EUPL-1.2](LICENSE) — European Union Public Licence v1.2
+[EUPL-1.2](https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12)
 
 ## For AI Agents
 

package/dist/main.js

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
 import { Command } from "commander";
-import { HttpClient, RineApiError, UUID_RE, agentKeysExist, cacheToken, decryptGroupMessage, decryptMessage, encryptGroupMessage, encryptMessage, fetchAgents, fetchAndIngestPendingSKDistributions, fetchOAuthToken, fetchRecipientEncryptionKey, formatError, fromBase64Url, generateAgentKeys, getAgentPublicKeys, getCredentialEntry, getOrCreateSenderKey, getOrRefreshToken, ingestSenderKeyDistribution, isBareAgentName, loadAgentKeys, loadCredentials, loadTokenCache, performAgentCreation, performRegistration, resolveAgent, resolveApiUrl, resolveConfigDir, resolveHandleViaWebFinger, resolveToUuid, saveAgentKeys, saveCredentials, saveTokenCache, toBase64Url, validateEncryptionKey, validateSigningKey, validateSlug } from "@rine-network/core";
+import { HttpClient, RineApiError, UUID_RE, agentKeysExist, cacheToken, decryptGroupMessage, decryptMessage, encryptGroupMessage, encryptMessage, fetchAgents, fetchAndIngestPendingSKDistributions, fetchOAuthToken, fetchRecipientEncryptionKey, formatError, fromBase64Url, generateAgentKeys, getAgentPublicKeys, getCredentialEntry, getOrCreateSenderKey, getOrRefreshToken, ingestSenderKeyDistribution, isBareAgentName, loadAgentKeys, loadCredentials, loadTokenCache, normalizeHandle, performAgentCreation, performRegistration, resolveAgent, resolveApiUrl, resolveConfigDir, resolveHandleViaWebFinger, resolveToUuid, saveAgentKeys, saveCredentials, saveTokenCache, toBase64Url, validateEncryptionKey, validateSigningKey, validateSlug } from "@rine-network/core";
 import readline from "node:readline";
 import * as fs from "node:fs";
 import { join } from "node:path";
@@ -635,7 +635,7 @@ function registerDiscover(program) {
 		let resolvedId = agentIdArg;
 		if (agentIdArg.includes("@")) resolvedId = await resolveHandleViaWebFinger(apiUrl, agentIdArg);
 		if (!UUID_RE.test(resolvedId)) {
-			printError(`Could not resolve '${agentIdArg}' to an agent UUID. Provide a UUID or a valid handle (e.g. agent@org.rine.network).`);
+			printError(`Could not resolve '${agentIdArg}' to an agent UUID. Provide a UUID or a valid handle (e.g. agent@org).`);
 			process.exitCode = 1;
 			return;
 		}
@@ -1027,7 +1027,7 @@ function resolvePayload(payload, payloadFile) {
 	}
 }
 function addMessageCommands(parent, program) {
-	parent.command("send").description("Send an encrypted message").requiredOption("--to <address>", "Recipient: agent handle, agent ID, or #group@org handle").option("--type <type>", "Message type (default: rine.v1.dm)").option("--payload <json>", "Message payload as JSON string").option("--payload-file <path>", "Read payload JSON from file (use - for stdin)").option("--from <address>", "Sender address (agent ID or handle with @)").option("--idempotency-key <key>", "Idempotency key header").action(withClient(program, async ({ client, gOpts, configDir, apiUrl }, opts) => {
+	parent.command("send").description("Send an encrypted message").requiredOption("--to <address>", "Recipient: agent handle (agent@org), agent ID, or group handle (#group@org)").option("--type <type>", "Message type (default: rine.v1.dm)").option("--payload <json>", "Message payload as JSON string").option("--payload-file <path>", "Read payload JSON from file (use - for stdin)").option("--from <address>", "Sender: agent handle (agent@org) or agent ID").option("--idempotency-key <key>", "Idempotency key header").action(withClient(program, async ({ client, gOpts, configDir, apiUrl }, opts) => {
 		const result = resolvePayload(opts.payload, opts.payloadFile);
 		if ("error" in result) {
 			printError(result.error);
@@ -1035,10 +1035,12 @@ function addMessageCommands(parent, program) {
 			return;
 		}
 		const parsedPayload = result.parsed;
+		const to = normalizeHandle(opts.to);
+		const from = opts.from ? normalizeHandle(opts.from) : opts.from;
 		const extraHeaders = {};
 		let senderAgentId;
-		if (opts.from !== void 0) {
-			senderAgentId = await resolveToUuid(apiUrl, opts.from);
+		if (from !== void 0) {
+			senderAgentId = await resolveToUuid(apiUrl, from);
 			extraHeaders["X-Rine-Agent"] = senderAgentId;
 		} else if (!gOpts.as) {
 			senderAgentId = await resolveAgent(apiUrl, await fetchAgents(client), void 0, void 0);
@@ -1046,14 +1048,14 @@ function addMessageCommands(parent, program) {
 		} else senderAgentId = await resolveAgent(apiUrl, await fetchAgents(client), void 0, gOpts.as);
 		if (opts.idempotencyKey) extraHeaders["Idempotency-Key"] = opts.idempotencyKey;
 		let recipientAgentId;
-		if (!opts.to.includes("@")) recipientAgentId = opts.to;
-		else if (!opts.to.startsWith("#")) recipientAgentId = await resolveToUuid(apiUrl, opts.to);
+		if (!to.includes("@")) recipientAgentId = to;
+		else if (!to.startsWith("#")) recipientAgentId = await resolveToUuid(apiUrl, to);
 		const body = { type: opts.type ?? "rine.v1.dm" };
-		if (opts.to.includes("@")) body.to_handle = opts.to;
-		else body.to_agent_id = opts.to;
-		if (opts.from?.includes("@")) body.from_handle = opts.from;
-		if (opts.to.startsWith("#") && senderAgentId) {
-			const { state, groupId } = await getOrCreateSenderKey(client, configDir, senderAgentId, opts.to, Object.keys(extraHeaders).length > 0 ? extraHeaders : void 0);
+		if (to.includes("@")) body.to_handle = to;
+		else body.to_agent_id = to;
+		if (from?.includes("@")) body.from_handle = from;
+		if (to.startsWith("#") && senderAgentId) {
+			const { state, groupId } = await getOrCreateSenderKey(client, configDir, senderAgentId, to, Object.keys(extraHeaders).length > 0 ? extraHeaders : void 0);
 			const { result: encResult } = await encryptGroupMessage(configDir, senderAgentId, groupId, state, parsedPayload);
 			Object.assign(body, encResult);
 		} else if (senderAgentId && recipientAgentId) {
@@ -1326,6 +1328,15 @@ function registerRegister(program) {
 }
 //#endregion
 //#region src/commands/stream.ts
+function emitLifecycle(gOpts, data) {
+	if (gOpts.json) console.log(JSON.stringify({
+		event: "lifecycle",
+		data
+	}));
+}
+function jitteredDelayMs(backoffSeconds) {
+	return Math.round(backoffSeconds * (.5 + Math.random()) * 1e3);
+}
 async function formatMessageLine(dataStr, agentId, configDir, client) {
 	try {
 		const data = JSON.parse(dataStr);
@@ -1360,72 +1371,151 @@ async function formatMessageLine(dataStr, agentId, configDir, client) {
 	}
 }
 function registerStream(program) {
-	program.command("stream").description("Stream incoming messages via SSE").option("--agent <id>", "Agent ID to stream (defaults to your agent)").option("--verbose", "Show heartbeats and reconnect details").action(async (opts) => {
+	program.command("stream").description("Stream incoming messages via SSE").option("--agent <id>", "Agent ID to stream (defaults to your agent)").option("--verbose", "Show heartbeats and reconnect details").option("--persistent", "Disable server-side connection timeout").option("--heartbeat-timeout <seconds>", "Seconds of silence before reconnecting (default: 70)", "70").action(async (opts) => {
 		try {
 			const gOpts = program.opts();
 			const configDir = resolveConfigDir();
 			const apiUrl = resolveApiUrl();
 			const { client, profileName, entry } = await createClient(configDir, apiUrl, gOpts.profile);
 			const agentId = await resolveAgent(apiUrl, await fetchAgents(client), opts.agent, gOpts.as);
-			const url = `${apiUrl}/agents/${agentId}/stream`;
+			let url = `${apiUrl}/agents/${agentId}/stream`;
+			if (opts.persistent) url += "?persistent=true";
+			const heartbeatTimeoutMs = Math.max(Number(opts.heartbeatTimeout) || 70, 10) * 1e3;
 			let lastEventId;
 			let backoff = 1;
+			let attempt = 0;
 			let stopped = false;
 			process.on("SIGINT", () => {
 				stopped = true;
 				process.exitCode = 0;
 			});
-			while (!stopped) try {
-				const envToken = process.env.RINE_TOKEN;
-				const headers = {
-					Authorization: `Bearer ${await getOrRefreshToken(configDir, apiUrl, entry, profileName, {
-						force: false,
-						envToken
-					})}`,
-					Accept: "text/event-stream"
-				};
-				if (lastEventId) headers["Last-Event-ID"] = lastEventId;
-				await new Promise((resolve) => {
-					if (stopped) {
-						resolve();
-						return;
-					}
-					const es = createEventSource({
-						url,
-						headers,
-						onMessage: ({ event, data, id }) => {
-							if (id) lastEventId = id;
-							if (gOpts.json) console.log(JSON.stringify({
-								event,
-								id,
-								data
-							}));
-							else if (event === "message") formatMessageLine(data, agentId, configDir, client).then((line) => console.log(line), () => console.log(`[message] ${data.slice(0, 80)}`));
-							else if (event === "heartbeat" && opts.verbose) process.stderr.write(`[heartbeat] ${data}\n`);
-						},
-						onDisconnect: () => resolve(),
-						onScheduleReconnect: () => {
+			while (!stopped) {
+				attempt++;
+				const state = { disconnectReason: "server_close" };
+				try {
+					const envToken = process.env.RINE_TOKEN;
+					const headers = {
+						Authorization: `Bearer ${await getOrRefreshToken(configDir, apiUrl, entry, profileName, {
+							force: false,
+							envToken
+						})}`,
+						Accept: "text/event-stream"
+					};
+					if (lastEventId) headers["Last-Event-ID"] = lastEventId;
+					emitLifecycle(gOpts, {
+						state: "connecting",
+						attempt,
+						url
+					});
+					await new Promise((resolve) => {
+						if (stopped) {
+							resolve();
+							return;
+						}
+						let heartbeatTimer;
+						const resetHeartbeatTimer = () => {
+							if (heartbeatTimer) clearTimeout(heartbeatTimer);
+							heartbeatTimer = setTimeout(() => {
+								state.disconnectReason = "heartbeat_timeout";
+								es.close();
+								resolve();
+							}, heartbeatTimeoutMs);
+						};
+						const es = createEventSource({
+							url,
+							headers,
+							onMessage: ({ event, data, id }) => {
+								resetHeartbeatTimer();
+								if (id) lastEventId = id;
+								if (gOpts.json) console.log(JSON.stringify({
+									event,
+									id,
+									data
+								}));
+								else if (event === "message") formatMessageLine(data, agentId, configDir, client).then((line) => console.log(line), () => console.log(`[message] ${data.slice(0, 80)}`));
+								else if (event === "heartbeat" && opts.verbose) process.stderr.write(`[heartbeat] ${data}\n`);
+							},
+							onDisconnect: () => {
+								if (heartbeatTimer) clearTimeout(heartbeatTimer);
+								state.disconnectReason = "server_close";
+								resolve();
+							},
+							onScheduleReconnect: () => {
+								if (heartbeatTimer) clearTimeout(heartbeatTimer);
+								es.close();
+								resolve();
+							}
+						});
+						resetHeartbeatTimer();
+						if (attempt === 1 && !gOpts.json) {
+							process.stderr.write(`Connected to stream for agent ${agentId}\n`);
+							if (opts.persistent) process.stderr.write("Persistent mode (no server timeout)\n");
+						}
+						emitLifecycle(gOpts, {
+							state: "connected",
+							attempt
+						});
+						const onStop = () => {
+							if (heartbeatTimer) clearTimeout(heartbeatTimer);
+							state.disconnectReason = "signal";
 							es.close();
 							resolve();
+						};
+						if (stopped) {
+							onStop();
+							return;
 						}
+						process.once("SIGINT", onStop);
 					});
-					const onStop = () => {
-						es.close();
-						resolve();
-					};
+					if (state.disconnectReason === "heartbeat_timeout") {
+						const jitteredBackoff = jitteredDelayMs(backoff);
+						emitLifecycle(gOpts, {
+							state: "reconnecting",
+							reason: "heartbeat_timeout",
+							attempt: attempt + 1,
+							backoff_ms: jitteredBackoff
+						});
+						if (!gOpts.json) process.stderr.write(`Reconnecting (attempt ${attempt + 1}, heartbeat timeout)...\n`);
+						await new Promise((r) => setTimeout(r, jitteredBackoff));
+						backoff = Math.min(backoff * 2, 30);
+					} else if (state.disconnectReason === "signal") {
+						emitLifecycle(gOpts, {
+							state: "stopped",
+							reason: "signal"
+						});
+						break;
+					} else {
+						emitLifecycle(gOpts, {
+							state: "reconnecting",
+							reason: "server_close",
+							attempt: attempt + 1,
+							backoff_ms: 0
+						});
+						if (!gOpts.json) process.stderr.write(`Reconnecting (attempt ${attempt + 1}, server close)...\n`);
+						backoff = 1;
+					}
+				} catch (err) {
 					if (stopped) {
-						onStop();
-						return;
+						emitLifecycle(gOpts, {
+							state: "stopped",
+							reason: "signal"
+						});
+						break;
 					}
-					process.once("SIGINT", onStop);
-				});
-				backoff = 1;
-			} catch {
-				if (stopped) break;
-				if (opts.verbose) process.stderr.write(`Reconnecting in ${backoff}s...\n`);
-				else process.stderr.write("Reconnecting...\n");
-				await new Promise((r) => setTimeout(r, backoff * 1e3));
-				backoff = Math.min(backoff * 2, 30);
+					const errorMsg = err instanceof Error ? err.message : String(err);
+					const jitteredBackoff = jitteredDelayMs(backoff);
+					emitLifecycle(gOpts, {
+						state: "reconnecting",
+						reason: "error",
+						attempt: attempt + 1,
+						backoff_ms: jitteredBackoff,
+						error: errorMsg
+					});
+					if (opts.verbose) process.stderr.write(`Reconnecting in ${Math.round(jitteredBackoff / 1e3)}s (attempt ${attempt + 1}, error: ${errorMsg})...\n`);
+					else process.stderr.write(`Reconnecting (attempt ${attempt + 1}, error)...\n`);
+					await new Promise((r) => setTimeout(r, jitteredBackoff));
+					backoff = Math.min(backoff * 2, 30);
+				}
 			}
 		} catch (err) {
 			printError(formatError(err));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rine-network/cli",
-  "version": "0.8.4",
+  "version": "0.9.1",
   "description": "CLI client for rine.network \u2014 EU-first messaging infrastructure for AI agents",
   "author": "mmmbs <mmmbs@proton.me>",
   "license": "EUPL-1.2",
@@ -28,7 +28,7 @@
     "dev": "tsx src/main.ts"
   },
   "dependencies": {
-    "@rine-network/core": "^0.3.5",
+    "@rine-network/core": "^0.4.1",
     "commander": "^12.0.0",
     "eventsource-client": "^1.1.0"
   },