@dotrino/remote-agent 0.10.0 → 0.12.0

package/README.md

@@ -34,7 +34,8 @@ Provee lo común — y **solo** eso:
 | `@dotrino/remote-agent/agent` | Node | `startRemoteAgent(opts)` |
 | `@dotrino/remote-agent/client` | navegador | `RemoteAgentClient` |
 | `@dotrino/remote-agent/link` | Node | `enroll`, `loadLink`, `saveLink`, `dataDir`, `parseQr`, `identityFromLink`, `clientLink`, `renewLink` |
-| `@dotrino/remote-agent/discover` | navegador | `listAgentsByLabel` |
+| `@dotrino/remote-agent/discover` | navegador | `listAgentsByLabel`, `probeAgents` |
+| `@dotrino/remote-agent/instances` | Node | `resolveInstance`, `listInstances`, `lockInstance`, `instancesRoot` |
 
 ## Uso
 
@@ -93,6 +94,23 @@ parámetros (`{ ns, proxyUrl: link.proxy, masterPubkey: link.iss, device, cert,
 Un agente que corre UNA vez (un bot por cron) no tiene el tic de renovación de
 `startRemoteAgent`: que llame a `renewLink(link)` en cada corrida, o su cert muere a los 30 días.
 
+### Dónde vive el enlace: `~/.dotrino/agent/<tipo>/<nombre>/` (el estándar)
+
+Todo agente guarda su enlace ahí, igual que `dotrino-env` guarda el suyo en
+`~/.dotrino/service/<bóveda>/<cajón>`. El **tipo** es el `label` de `startRemoteAgent`; el
+**nombre** lo elige quien lo lanza (`--name`), y así pueden correr dos del mismo tipo a la
+vez (uno por proyecto), cada uno como un aparato aparte del acta.
+
+```js
+import { resolveInstance, lockInstance } from '@dotrino/remote-agent/instances'
+const { name, dir } = resolveInstance('ia-agent', opt('--name'))  // sin nombre: se busca
+process.on('exit', lockInstance(dir))   // dos procesos con el mismo enlace = la misma llave
+```
+
+Sin nombre: si no hay ninguno enlazado es `default`; si hay uno, ese; si hay varios, se
+para y dice cuáles hay (la misma regla que `dotrino-env`). La raíz común se cambia con
+`DOTRINO_AGENT_HOME`.
+
 ### Un agente como CLIENTE de otro agente (Node)
 
 Un agente Node también puede hablar con otro agente —un bot que guarda en el node de
@@ -123,6 +141,20 @@ chat.send({ type: 'msg', text: 'arreglá el bug en auth.js' })
 const online = await chat.ping()  // liveness sin abrir sesión
 ```
 
+**Encontrar los agentes de UN tipo: pregúntaselo a ellos, no al nombre del acta.** El label
+del acta lo pone el dueño al emparejar («TerminalLocal»), así que filtrar por él no encuentra
+nada. El pong de cada agente dice qué es (el `label` con que arrancó `startRemoteAgent`):
+
+```js
+import { listAgentsByLabel, probeAgents } from '@dotrino/remote-agent/discover'
+const miembros = await listAgentsByLabel(id)                    // todos, sin filtrar
+const vivos = await probeAgents(proxyClient, miembros.map((m) => m.sub))
+const terminales = miembros.filter((m) => vivos.get(m.sub)?.kind === 'terminal-agent')
+```
+
+Un agente apagado no contesta y no sale: sin preguntarle no se sabe qué es. El pong con
+`kind` existe desde 0.11.0; uno más viejo contesta con `kind: null`.
+
 ### `link` (la PWA lo obtiene del vault)
 
 Ver `dotrino-terminal/src/vault.js` (`getLink` / `getSelfLink`) como referencia: es

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotrino/remote-agent",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Middleware compartido del ecosistema Dotrino para apps de agente remoto cifrado punto a punto (handshake E2E, emparejamiento SAS con vault, revocación, descubrimiento). Lo consumen dotrino-terminal (PTY) y dotrino-ia (chat con IA).",
   "type": "module",
   "main": "./index.js",
@@ -10,7 +10,8 @@
     "./client": "./src/client.js",
     "./link": "./src/link.js",
     "./discover": "./src/discover.js",
-    "./node-globals": "./node-globals.js"
+    "./node-globals": "./node-globals.js",
+    "./instances": "./src/instances.js"
   },
   "files": [
     "index.js",

package/src/agent.js

@@ -66,7 +66,8 @@ class AgentSession {
  * Arranca el agente. Devuelve `{ machine, machineId, master, close }`.
  *
  * @param {object} opts
- * @param {string} [opts.label]       label del dispositivo (para logging; el real vive en link.json).
+ * @param {string} [opts.label]       qué agente es (`terminal-agent`, `ia-agent`…): lo contesta el pong
+ *   para que las apps lo encuentren (`probeAgents`). El nombre del acta es del dueño.
  * @param {string} [opts.proxyUrl]    default wss://proxy.dotrino.com.
  * @param {string} [opts.dir]         dir del enlace (default dataDir()).
  * @param {object} [opts.link]        enlace ya cargado (override de dir).
@@ -329,7 +330,9 @@ export async function startRemoteAgent (opts = {}) {
     else if (payload.type === DATA) handleData(from, payload)
     // Sonda de presencia (liveness): el cliente hace ping y respondemos pong con el
     // mismo nonce → así la app sabe que el agente está online (sin abrir sesión).
-    else if (payload.type === PING) send(from, { type: PONG, n: payload.n })
+    // El pong dice además QUÉ agente es (`kind`, el label con que arrancó): el nombre que
+    // tiene en el acta lo pone el dueño al emparejar y no sirve para saber qué atiende.
+    else if (payload.type === PING) send(from, { type: PONG, n: payload.n, kind: opts.label || null })
     else if (payload.type === VMSG.REVOKED) handleRevoked(payload).catch(() => {})
   })
 

package/src/discover.js

@@ -21,6 +21,8 @@
  * después son sus miembros.
  */
 
+import { PING, PONG } from '../protocol.js'
+
 /**
  * @param {object} id   instancia de Identity (del vault) ya conectada.
  * @param {string} [label]  filtrar por servicio/label exacto (p. ej. `'content'`,
@@ -44,4 +46,37 @@ export async function listAgentsByLabel (id, label) {
     .map((m) => ({ sub: m.pub, label: m.label || m.cn || '', cn: m.cn || null }))
 }
 
-export default { listAgentsByLabel }
+/**
+ * QUÉ AGENTE ES CADA UNO, preguntándoselo. Manda un `ra.ping` a cada pubkey por el
+ * transporte que se le pase y devuelve los que contestan, con el `kind` que declara el
+ * agente al arrancar (`startRemoteAgent({ label })`).
+ *
+ * Existe porque buscar por el label del ACTA no sirve: ese nombre lo pone el dueño al
+ * emparejar («TerminalLocal», «el PC de la oficina»), así que una app que buscaba
+ * `terminal-agent` no encontraba nada. Lo que un agente atiende lo sabe el agente.
+ *
+ * Un agente apagado no contesta y no sale: no se puede saber qué es sin preguntarle.
+ *
+ * @param {{ on:Function, sendByPubkey:Function }} client  un WebSocketProxyClient conectado.
+ * @param {string[]} subs  pubkeys a preguntar (p. ej. las de `listAgentsByLabel(id)`).
+ * @param {{ timeoutMs?: number }} [opts]
+ * @returns {Promise<Map<string, { kind: string|null }>>} sub → lo que contestó.
+ */
+export function probeAgents (client, subs, { timeoutMs = 3000 } = {}) {
+  return new Promise((resolve) => {
+    const found = new Map()
+    if (!client || !subs?.length) return resolve(found)
+    const bySub = new Map()
+    const off = client.on('message', (_from, p) => {
+      if (p?.type === PONG && bySub.has(p.n)) found.set(bySub.get(p.n), { kind: p.kind ?? null })
+    })
+    for (const sub of subs) {
+      const n = [...crypto.getRandomValues(new Uint8Array(8))].map((x) => x.toString(16).padStart(2, '0')).join('')
+      bySub.set(n, sub)
+      try { client.sendByPubkey(sub, { type: PING, n }) } catch (_) {}
+    }
+    setTimeout(() => { try { off() } catch (_) {} resolve(found) }, timeoutMs)
+  })
+}
+
+export default { listAgentsByLabel, probeAgents }

package/src/instances.js

@@ -0,0 +1,82 @@
+/**
+ * instances.js — dónde vive el enlace de cada agente de esta máquina. EL ESTÁNDAR del
+ * ecosistema para todo agente de remote-agent (terminal, ia, los que vengan).
+ *
+ * Igual que `dotrino-env` (`~/.dotrino/service/<bóveda>/<cajón>`): cada agente tiene su
+ * TIPO y su NOMBRE, y su propio enlace en `~/.dotrino/agent/<tipo>/<nombre>/`. Así se
+ * pueden correr dos del mismo tipo a la vez (uno por proyecto) y cada uno es un aparato
+ * aparte del acta.
+ *
+ * Antes cada agente elegía su carpeta (y `ia` usaba la genérica de este paquete), con UN
+ * enlace: lanzarlo dos veces arrancaba dos procesos con la MISMA llave, el proxio les
+ * repartía los mensajes a los dos y el que no tenía la sesión contestaba «sesión
+ * desconocida» en el chat.
+ *
+ * El nombre es una etiqueta tuya de esta máquina: no viaja, no entra en el acta. Sin
+ * `--name`, se BUSCA y solo se exige si hay empate — la misma regla que `dotrino-env`.
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+export const DEFAULT_NAME = 'default'
+export const isValidName = (n) => typeof n === 'string' && /^[a-z0-9-]{1,32}$/.test(n)
+
+/**
+ * Raíz de los agentes de un tipo: `~/.dotrino/agent/<kind>` (override de la raíz común con
+ * `DOTRINO_AGENT_HOME`, igual que `DOTRINO_ENV_HOME` en dotrino-env).
+ * @param {string} kind  el tipo de agente, el mismo `label` de `startRemoteAgent` (`ia-agent`).
+ */
+export function instancesRoot (kind) {
+  if (!isValidName(kind)) throw new Error(`invalid agent kind "${kind}"`)
+  const home = process.env.DOTRINO_AGENT_HOME || path.join(os.homedir(), '.dotrino', 'agent')
+  return path.join(home, kind)
+}
+
+/** Nombres de las instancias enlazadas (las que tienen `link.json`). */
+export function listInstances (kind) {
+  const root = instancesRoot(kind)
+  let names = []
+  try { names = fs.readdirSync(root) } catch (_) { return [] }
+  return names.filter((n) => isValidName(n) && fs.existsSync(path.join(root, n, 'link.json'))).sort()
+}
+
+/**
+ * La carpeta de la instancia a usar.
+ *   · con `name`: esa (valida el nombre);
+ *   · sin nombre y ninguna enlazada: `default`;
+ *   · sin nombre y UNA enlazada: esa;
+ *   · sin nombre y VARIAS: se para y se dice cuáles hay. Elegir por el usuario sería adivinar.
+ * @returns {{ name: string, dir: string }}
+ */
+export function resolveInstance (kind, name) {
+  if (name != null) {
+    if (!isValidName(name)) throw new Error(`invalid name "${name}" (use [a-z0-9-]{1,32}, e.g. "project-a")`)
+    return { name, dir: path.join(instancesRoot(kind), name) }
+  }
+  const found = listInstances(kind)
+  if (found.length > 1) throw new Error(`there is more than one agent on this machine (${found.join(', ')}): pick one with --name <name>`)
+  const n = found[0] || DEFAULT_NAME
+  return { name: n, dir: path.join(instancesRoot(kind), n) }
+}
+
+/**
+ * Candado de la instancia: dos procesos con el MISMO enlace son la misma llave y se
+ * estorban. Si ya corre uno vivo, se para y se dice. Devuelve `release()`.
+ */
+export function lockInstance (dir) {
+  const file = path.join(dir, 'agent.pid')
+  try {
+    const pid = Number(fs.readFileSync(file, 'utf8'))
+    if (pid && pid !== process.pid && isAlive(pid)) {
+      throw Object.assign(new Error(`this agent is already running (pid ${pid}). To run another one at the same time, give it its own --name`), { code: 'EALREADY' })
+    }
+  } catch (e) { if (e.code === 'EALREADY') throw e }
+  fs.mkdirSync(dir, { recursive: true })
+  fs.writeFileSync(file, String(process.pid), { mode: 0o600 })
+  return () => { try { if (Number(fs.readFileSync(file, 'utf8')) === process.pid) fs.rmSync(file) } catch (_) {} }
+}
+
+function isAlive (pid) {
+  try { process.kill(pid, 0); return true } catch (e) { return e.code === 'EPERM' }
+}