@nyx5/nyx5 0.6.0 → 0.7.0

package/src/correo/agente.js

@@ -3,6 +3,7 @@
 // Las operaciones del Libro son sobres firmados a libro@<casa>; las respuestas vuelven como recibos al buzón.
 
 import { Resolver, parseAddress } from './resolver.js';
+import { EXT_PROYECTO, proyectoDe, rolDe, nombreDeProyecto } from './politica.js';
 import { generateKeys, signObject, verifyObject, signBytes, canonical, b64u, uuid, encryptContent, decryptContent, mintPow, sha256hex } from '../nucleo/crypto.js';
 import { Libro, MEDIA } from '../libro/libro.js';
 
@@ -15,7 +16,9 @@ export class Agent {
     this.keys = keys;
     this.estafeta = estafeta.replace(/\/$/, '');
     this.fetch = (...a) => fetchImpl(...a); // envuelto: workerd exige fetch con this=globalThis
-    this.resolver = resolver || new Resolver({ hosts: { [domain]: { url: this.estafeta }, ...hosts }, fetchImpl });
+    // El cliente firma ante su propia casa cuando una tarjeta no aparece sin autenticar (NX-202):
+    // así un contacto de un agente secreto lo resuelve, y un extraño ve lo mismo que si no existiera.
+    this.resolver = resolver || new Resolver({ hosts: { [domain]: { url: this.estafeta }, ...hosts }, fetchImpl, auth: { domain, url: this.estafeta, header: (method, path) => this._auth(method, path) } });
   }
 
   static create(address, estafeta, opts = {}) { return new Agent({ address, estafeta, keys: generateKeys(), ...opts }); }
@@ -30,12 +33,12 @@ export class Agent {
     const token = b64u(canonical(claims));
     return `Nyx5 ${token}.${signBytes(canonical(claims), keys)}`;
   }
-  async _call(method, path, body, { admin, noAuth, authKeys } = {}) {
+  async _call(method, path, body, { admin, noAuth, authKeys, timeoutMs = 10_000 } = {}) {
     const headers = { 'content-type': 'application/json' };
     if (admin) headers.authorization = `Bearer ${admin}`; else if (!noAuth) headers.authorization = this._auth(method, path.split('?')[0], authKeys);
     const res = await this.fetch(`${this.estafeta}${path}`, {
       method, headers,
-      body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(10_000),
+      body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs),
     });
     const json = await res.json().catch(() => ({}));
     if (!res.ok) throw Object.assign(new Error(json.reason || `HTTP ${res.status}`), { status: res.status, body: json });
@@ -45,10 +48,12 @@ export class Agent {
   // ---------- registro ----------
   // Tres caminos: adminToken (la casa inscribe), invite (código de la casa) o abierto si la casa lo permite.
   // Sin adminToken y sin estar registrado, el cuerpo va firmado con la propia clave (prueba de posesión).
-  async register({ adminToken, invite, capabilities, inbox, webhook, notify_email, valid_until, source } = {}) {
+  async register({ adminToken, invite, capabilities, inbox, wallet, wallets, webhook, notify_email, valid_until, source, visibility, profile } = {}) {
     // `source` es atribución de distribución: viaja al alta, se registra en el evento `join`
     // y NO entra en la tarjeta. Nadie puede leer de dónde vino un agente mirando su tarjeta.
-    const body = { local: this.local, sig: this.keys.sig, enc: this.keys.enc, capabilities, inbox, webhook, notify_email, valid_until, source };
+    // `wallet` es la dirección a la que este agente quiere que le paguen en dinero real. Es
+    // PÚBLICA y va en la tarjeta: la casa no la controla ni puede mover nada de ella.
+    const body = { local: this.local, sig: this.keys.sig, enc: this.keys.enc, capabilities, inbox, wallet, wallets, webhook, notify_email, valid_until, source, visibility, profile };
     if (adminToken) this.card = await this._call('POST', '/agents', body, { admin: adminToken });
     else if (this.card) this.card = await this._call('POST', '/agents', body);
     else this.card = await this._call('POST', '/agents', signObject({ ...body, invite: invite || undefined, ts: iso() }, this.keys), { noAuth: true });
@@ -76,9 +81,15 @@ export class Agent {
   }
 
   // ---------- envío ----------
-  async send({ to, type = 'message', body, media, encrypt = true, thread, inReplyTo, expires, deliverAfter, attachments, extensions, receipt }) {
+  async send({ to, type = 'message', body, media, encrypt = true, thread, inReplyTo, expires, deliverAfter, attachments, extensions, receipt, project, role }) {
     const recipients = Array.isArray(to) ? to : [to];
     const id = uuid();
+    // Proyecto y rol viajan como extensión firmada: el buzón del otro lado filtra por proyecto.
+    if (project || role) extensions = { ...(extensions || {}), [EXT_PROYECTO]: { ...(project ? { project: nombreDeProyecto(project) } : {}), ...(role ? { role: String(role).trim().slice(0, 40) } : {}) } };
+    // Un sobre que responde a otro hereda su hilo. Defecto real (12-sep-2026): las respuestas iban con
+    // in_reply_to y thread null, y la conversación quedaba como mensajes sueltos; el historial firmado
+    // es el producto, y sin hilo no es historial. La casa no puede rellenarlo: el sobre va firmado.
+    if (inReplyTo && thread == null) thread = await this._hiloDe(inReplyTo, recipients[0]);
     const base = {
       nyx5: '1', id, from: this.address, to: recipients, created: iso(),
       expires: expires ?? null, deliver_after: deliverAfter ?? undefined, thread: thread ?? null, in_reply_to: inReplyTo ?? null, type,
@@ -87,13 +98,32 @@ export class Agent {
     const content = { media: media || (typeof body === 'string' ? 'text/plain' : 'application/json'), body };
 
     // Tarjetas de los destinatarios: para cifrar (clave enc) y para saber si exigen proof-of-work.
-    const cards = await Promise.all(recipients.map((r) => this.resolver.agentCard(r).catch((e) => ({ address: r, _error: e.message }))));
+    // La tarjeta de un grupo cambia cada vez que entra o sale alguien: se pide fresca, siempre.
+    // Defecto real de la primera prueba: con la tarjeta en caché, el miembro nuevo recibía un sobre
+    // que no podía abrir.
+    for (const r of recipients) { try { if (parseAddress(r).local.startsWith('g.')) this.resolver.invalidate(`agent:${r}`); } catch { /* dirección inválida: la resolución lo dirá */ } }
+    const cards = await Promise.all(recipients.map((r) => this.resolver.agentCard(r, { onBehalfOf: this.address }).catch((e) => ({ address: r, _error: e.message }))));
     const missing = cards.filter((c) => c._error);
     if (missing.length) throw new Error(`could not resolve: ${missing.map((c) => `${c.address} (${c._error})`).join(', ')}`);
 
+    // Un grupo no tiene llave: se cifra para cada uno de sus miembros, que sí la publican. La casa
+    // reparte el sobre tal cual y nunca puede abrirlo.
+    const lectores = [];
+    for (const c of cards) {
+      if (!c.group) { lectores.push({ address: c.address, enc: c.enc }); continue; }
+      for (const dir of c.group.members) {
+        if (dir === this.address) continue;
+        const mc = await this.resolver.agentCard(dir, { onBehalfOf: this.address }).catch(() => null);
+        lectores.push({ address: dir, enc: mc?.enc || null });
+      }
+    }
     let env;
-    if (encrypt && cards.every((c) => c.enc)) {
-      env = { ...base, encrypted: encryptContent(content, cards.map((c) => ({ address: c.address, enc: c.enc })), aad(base)) };
+    if (encrypt && lectores.every((l) => l.enc)) {
+      // El remitente también recibe una copia de la llave del contenido. No es un destinatario más:
+      // `to` no cambia y la AAD tampoco. Sin esto, lo que uno mismo mandó cifrado es ilegible para
+      // uno mismo, y el historial de una conversación queda con la mitad de los mensajes en blanco.
+      if (this.keys.enc && !lectores.some((l) => l.address === this.address)) lectores.push({ address: this.address, enc: this.keys.enc });
+      env = { ...base, encrypted: await encryptContent(content, lectores, aad(base)) };
     } else {
       if (encrypt === 'required') throw new Error('a recipient does not publish an encryption key');
       env = { ...base, content };
@@ -108,7 +138,9 @@ export class Agent {
 
     const signed = signObject(env, this.keys);
     const r = await this._call('POST', '/outbound', signed);
-    return { id, envelope: signed, jobs: r.jobs };
+    // `encrypted` dice lo que de verdad pasó: un destinatario sin llave de cifrado recibe en claro,
+    // y quien manda tiene que poder saberlo en vez de creer que se cifró.
+    return { id, envelope: signed, jobs: r.jobs, encrypted: !!env.encrypted };
   }
   // Un mensaje a tu yo futuro: llega a tu propio buzón en la fecha indicada, cifrado (solo tú lo abres).
   // La cola ya lo sostiene; esto le da a un agente memoria operativa entre sesiones.
@@ -122,6 +154,16 @@ export class Agent {
     try { return await this._call('POST', '/email/out', { to, subject, body }); }
     catch (e) { if (e.status === 503 && e.body?.pending) return e.body; throw e; }
   }
+  // El hilo del sobre al que se responde: el suyo si lo tenía, si no su propio id. Se busca en la
+  // conversación con el destinatario (lo recibido y lo enviado); si la casa no lo conoce, el id.
+  async _hiloDe(inReplyTo, con) {
+    try {
+      const msgs = await this.conversation(con, { limit: 200 });
+      const m = msgs.find((x) => (x.envelope || x).id === inReplyTo);
+      if (m) return (m.envelope || m).thread || inReplyTo;
+    } catch { /* sin historial disponible: el id basta como raíz del hilo */ }
+    return inReplyTo;
+  }
   reply(envelope, body, opts = {}) {
     return this.send({ to: envelope.from, thread: envelope.thread || envelope.id, inReplyTo: envelope.id, type: opts.type || 'result', body, ...opts });
   }
@@ -143,8 +185,16 @@ export class Agent {
 
   // ---------- Libro: cotizaciones y contratos ----------
   // Una cotización es un documento firmado por el vendedor; viaja dentro de un sobre (cifrado) al comprador.
-  async quote({ to, contract = 'spot', price, concept, terms, expires, arbiter, house, referrer }) {
-    const q = Libro.buildQuote({ seller: this.address, buyer: to, house: house || parseAddress(to).domain, contract, price, concept, terms, expires, arbiter, referrer }, this.keys);
+  // Con `service` (NX-301) el precio, el contrato y el concepto se leen de la propia ficha publicada
+  // si no vienen; lo que venga explícito viaja igual y la casa lo cruza con la ficha al aceptar.
+  async quote({ to, contract, price, concept, terms, expires, arbiter, house, referrer, service }) {
+    if (service != null) {
+      this.resolver.invalidate(`agent:${this.address}`);
+      const s = ((await this.resolver.agentCard(this.address)).profile?.services || []).find((x) => x.id === service);
+      if (!s) throw new Error(`service "${service}" is not published in your profile; publish it with setProfile first`);
+      price ??= s.price.tokens; contract ??= s.contract; concept ??= s.name;
+    }
+    const q = Libro.buildQuote({ seller: this.address, buyer: to, house: house || parseAddress(to).domain, contract: contract ?? 'spot', price, concept, terms, expires, arbiter, referrer, service }, this.keys);
     const sent = await this.send({ to, type: 'message', media: MEDIA.cotizacion, body: q, expires: expires ?? null });
     return { quote: q, ...sent };
   }
@@ -156,6 +206,7 @@ export class Agent {
   deliver(house, contract, { evidence_sha256, note } = {}) { return this.libroOp(house, { op: 'deliver', contract, evidence_sha256, note }); }
   release(house, contract) { return this.libroOp(house, { op: 'release', contract }); }
   refund(house, contract, note) { return this.libroOp(house, { op: 'refund', contract, note }); }
+  reclaim(house, contract) { return this.libroOp(house, { op: 'reclaim', contract }); }
   bond(house, { amount, claim, verifier, beneficiary, arbiter, evidence_sha256, expires, vouchee }) { return this.libroOp(house, { op: 'bond', amount, claim, verifier, beneficiary, arbiter, evidence_sha256, expires, vouchee }); }
   // Avalar a un desconocido para que entre a un buzón con lista blanca: una fianza en la casa del
   // receptor, con el receptor como verificador y beneficiario. Si la presentación es basura, la ejecuta.
@@ -166,9 +217,19 @@ export class Agent {
   mandate(house, { grantee, cap, scope, expires, parent }) { return this.libroOp(house, { op: 'mandate', grantee, cap, scope, expires, parent }); }
   charge(house, { mandate, amount, concept }) { return this.libroOp(house, { op: 'charge', mandate, amount, concept }); }
   revoke(house, mandate) { return this.libroOp(house, { op: 'revoke', mandate }); }
+  pay(house, { to, amount, concept }) { return this.libroOp(house, { op: 'pay', to, amount, concept }); }
+  // Notaría (NX-601): la casa sella el hash de un documento con fecha y firma; el sello llega como
+  // recibo. Gratis; el mismo hash sellado dos veces por el mismo agente devuelve el mismo sello.
+  notarize(house, { sha256, name, media, note }) { return this.libroOp(house, { op: 'notarize', sha256, name, media, note }); }
 
   // Lecturas directas (sin pasar por correo) en la casa indicada; por defecto, la propia estafeta.
   async balance(house) { return this._callAt(house, 'GET', `/libro/cuenta/${encodeURIComponent(this.address)}`); }
+  // Estado de cuenta por rango (NX-501), lectura directa firmada: opening + in − out = closing.
+  // `since`/`until` ISO-8601 ([since, until)); `limit` acota cuántos asientos, los más recientes.
+  async statement(house, { since, until, limit } = {}) {
+    const q = new URLSearchParams(Object.entries({ desde: since, hasta: until, limit }).filter(([, v]) => v != null).map(([k, v]) => [k, String(v)]));
+    return this._callAt(house, 'GET', `/libro/estado${q.size ? `?${q}` : ''}`);
+  }
   async contract(house, id) { return this._callAt(house, 'GET', `/libro/contrato/${encodeURIComponent(id)}`); }
   // Historial público de cualquier agente (por defecto, el propio): la reputación es el libro.
   async historial(address = this.address) {
@@ -179,6 +240,20 @@ export class Agent {
     if (!res.ok) throw Object.assign(new Error(json.reason || `HTTP ${res.status}`), { status: res.status });
     return json;
   }
+  // Sellos PÚBLICOS de un hash en una casa (sin cuenta): null si no hay ninguno. Cada sello se
+  // verifica contra la tarjeta del dominio; si la casa sirviera uno que no firmó, se rechaza entero.
+  async notarized(sha256, house = this.domain) {
+    const dc = await this.resolver.domainCard(house);
+    const res = await this.fetch(`${dc._estafeta}/notaria/${encodeURIComponent(String(sha256).toLowerCase())}`, { signal: AbortSignal.timeout(10_000) });
+    if (res.status === 404) return null;
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) throw Object.assign(new Error(json.reason || `HTTP ${res.status}`), { status: res.status });
+    const kids = (dc.keys || []).map((k) => k.sig);
+    for (const s of json.seals || []) {
+      if (!kids.includes(s.signature?.kid) || !verifyObject(s, s.signature.kid)) throw new Error(`seal ${s.id} is not signed by ${house}`);
+    }
+    return json;
+  }
   async _callAt(house, method, path) {
     if (!house || house === this.domain) return this._call(method, path);
     const dc = await this.resolver.domainCard(house);
@@ -197,8 +272,10 @@ export class Agent {
 
   // Búsqueda en un índice federado (urn:nyx5:ext:indice): por casa que lo opera o URL directa.
   // El índice es una pista: cada tarjeta se re-verifica por la cadena normal al usarla.
-  async search(index, { q, capability, accepts, house, limit, offset } = {}) {
-    const params = new URLSearchParams(Object.entries({ q, capability, accepts, house, limit, offset }).filter(([, v]) => v != null));
+  // Filtros: q, tag, lang, capability, accepts, house, price_max, min_score, limit; y `cursor`
+  // (el next_cursor de la página anterior). No hay offset: el índice lo rechaza con 400.
+  async search(index, { q, tag, lang, capability, accepts, house, price_max, min_score, limit, cursor } = {}) {
+    const params = new URLSearchParams(Object.entries({ q, tag, lang, capability, accepts, house, price_max, min_score, limit, cursor }).filter(([, v]) => v != null));
     const base = index.startsWith('http') ? index.replace(/\/$/, '') : (await this.resolver.domainCard(index))._estafeta;
     const res = await this.fetch(`${base}/index/agents?${params}`, { signal: AbortSignal.timeout(10_000) });
     const json = await res.json().catch(() => ({}));
@@ -211,6 +288,41 @@ export class Agent {
   async ack(ids) { return (await this._call('POST', `/mailbox/${this.local}/ack`, { ids: Array.isArray(ids) ? ids : [ids] })).acked; }
   async outbox() { return (await this._call('GET', `/outbox/${this.local}`)).sent; }
 
+  // ---------- conversación y tiempo real ----------
+  // El historial vive en la casa, no en la sesión: desde otro dispositivo se retoma igual.
+  async conversation(withAddress, { limit = 30, project = null } = {}) {
+    const q = new URLSearchParams({ with: String(withAddress), limit: String(limit), ...(project ? { project } : {}) });
+    return (await this._call('GET', `/conversations/${this.local}?${q}`)).messages;
+  }
+  async conversations({ project = null } = {}) { const q = project ? `?${new URLSearchParams({ project })}` : ''; return (await this._call('GET', `/conversations/${this.local}${q}`)).conversations; }
+  // Ficha pública: la propia (o la de un delegado propio) se declara; la de cualquiera se lee de su tarjeta.
+  setProfile(profile, { of = null } = {}) { const l = of ? parseAddress(of).local : this.local; return this._call('POST', `/agents/${encodeURIComponent(l)}/profile`, { profile }); }
+  async profile(address) { this.resolver.invalidate(`agent:${String(address).toLowerCase()}`); const c = await this.resolver.agentCard(address, { onBehalfOf: this.address }); return { address: c.address, profile: c.profile || null, capabilities: c.capabilities || {} }; }
+  // «Visto por última vez» de una dirección de una casa (null si el dueño no lo activó).
+  async presence(address) {
+    const { local, domain } = parseAddress(address);
+    const r = await this._callAt(domain, 'GET', `/agents/${encodeURIComponent(local)}/presence`).catch(() => null);
+    return r?.last_seen || null;
+  }
+  // ---------- grupos ----------
+  // `g` acepta la dirección completa (g.equipo@casa) o el nombre (equipo). Los miembros son de la casa.
+  static _localDeGrupo(g) { const s = String(g || '').toLowerCase(); const l = s.includes('@') ? parseAddress(s).local : s; return l.startsWith('g.') ? l : `g.${l}`; }
+  createGroup(name, { members = [], post = 'members' } = {}) { return this._call('POST', '/groups', { name: String(name).replace(/^g\./, ''), members, post }); }
+  group(g) { return this._call('GET', `/groups/${encodeURIComponent(Agent._localDeGrupo(g))}/members`); }
+  editGroup(g, { add = [], remove = [], admins = [] } = {}) { return this._call('POST', `/groups/${encodeURIComponent(Agent._localDeGrupo(g))}/members`, { add, remove, admins }); }
+  leaveGroup(g) { return this.editGroup(g, { remove: [this.address] }); }
+  // Espera el próximo sobre pendiente que cumpla el filtro. No sondea desde aquí: la casa responde
+  // apenas llega. Devuelve null si se acabó el tiempo sin nada.
+  async wait({ from, thread, since, project, seconds = 25 } = {}) {
+    const q = new URLSearchParams(Object.entries({ from, thread, since, project, timeout: String(seconds) }).filter(([, v]) => v != null && v !== ''));
+    return (await this._call('GET', `/mailbox/${this.local}/wait?${q}`, undefined, { timeoutMs: (Number(seconds) + 15) * 1000 })).message;
+  }
+  // Quién soy y qué puedo hacer: la tarjeta certificada, resumida.
+  async whoami() {
+    const c = await this.resolver.agentCard(this.address);
+    return { address: c.address, delegated_by: c.delegation?.by || null, valid_until: c.valid_until || null, scope: c.delegation?.scope || null, custody: c.custody || null, inbox: c.inbox || null, encryption: !!c.enc };
+  }
+
   // Verifica la cadena de confianza del remitente y descifra si corresponde.
   async open(envelope) {
     // Correo entrante por el puente (urn:nyx5:ext:email): sin firma, en claro, marcado como NO
@@ -219,13 +331,15 @@ export class Agent {
     if (em && !envelope.signature) {
       return { id: envelope.id, from: em.from, to: envelope.to, type: envelope.type, created: envelope.created, verified: false, via: 'email', subject: em.subject || null, content: envelope.content };
     }
-    const card = await this.resolver.agentCardForKid(envelope.from, envelope.signature?.kid);
+    const card = await this.resolver.agentCardForKid(envelope.from, envelope.signature?.kid, { onBehalfOf: this.address });
     const verified = Resolver.acceptedKids(card).includes(envelope.signature?.kid) && verifyObject(envelope, envelope.signature.kid);
     if (!verified) throw new Error(`invalid signature on envelope ${envelope.id} from ${envelope.from}`);
     if (envelope.expires && Date.parse(envelope.expires) < Date.now()) throw new Error(`sobre vencido: ${envelope.id}`);
-    if (!envelope.encrypted && !envelope.to.includes(this.address)) throw new Error(`envelope ${envelope.id} is not addressed to ${this.address}`);
-    const content = envelope.encrypted ? decryptContent(envelope.encrypted, this.address, this.keys, aad(envelope)) : envelope.content;
-    return { id: envelope.id, from: envelope.from, to: envelope.to, type: envelope.type, thread: envelope.thread, in_reply_to: envelope.in_reply_to, created: envelope.created, encrypted: !!envelope.encrypted, sender: card, content };
+    // Un sobre a un grupo llega con la dirección del grupo, no la del miembro que lo abre.
+    const aGrupo = envelope.to.some((t) => { try { return parseAddress(t).local.startsWith('g.'); } catch { return false; } });
+    if (!envelope.encrypted && !aGrupo && !envelope.to.includes(this.address) && envelope.from !== this.address) throw new Error(`envelope ${envelope.id} is not addressed to ${this.address}`);
+    const content = envelope.encrypted ? await decryptContent(envelope.encrypted, this.address, this.keys, aad(envelope)) : envelope.content;
+    return { id: envelope.id, from: envelope.from, to: envelope.to, type: envelope.type, thread: envelope.thread, in_reply_to: envelope.in_reply_to, created: envelope.created, encrypted: !!envelope.encrypted, project: proyectoDe(envelope), role: rolDe(envelope), sender: card, content };
   }
 
   // Espera hasta que llegue un sobre que cumpla el filtro (útil para pruebas y flujos síncronos).

package/src/correo/asistente.js

@@ -0,0 +1,174 @@
+// Nyx5/1 — Asistentes: una dirección que contesta SOLA, con la API de Anthropic, dentro de un tope.
+//
+// Nació de una necesidad concreta: Nicholas se va un mes (desde el 14-sep-2026) y Bastián, el
+// desarrollador de Sigo, necesita preguntarle al agente de Sigo a cualquier hora. Un Claude en una
+// app sólo contesta cuando alguien lo abre; un asistente contesta aunque nadie esté mirando.
+//
+// Límites, y por qué cada uno:
+//   - Sólo contesta a quien está en SU lista (la política del buzón ya rechaza al resto antes de
+//     que llegue). Un asistente abierto sería un grifo de gasto para cualquiera.
+//   - Nunca a sí mismo ni a los agentes de sistema (rebotes, recibos): un asistente que le contesta
+//     a un rebote genera otro rebote, y el bucle se come el presupuesto.
+//   - Cada respuesta se descuenta de un tope mensual en dólares, calculado del `usage` real que
+//     devuelve la API. Al llegar al tope deja de llamar a la API, avisa a quien pregunta y, una vez,
+//     a su dueño. El tope también se pone en la consola de Anthropic (el workspace): dos candados.
+//   - Contesta desde el reloj programado, no dentro de una petición: en el edge, lo que corre
+//     después de responder una petición tiene 30 s, y una respuesta de Claude puede tardar más.
+//   - Su llave vive en la bóveda (custodia de la casa, declarada en su tarjeta), igual que la de
+//     un Claude conectado. Sólo mensajes: no toca el Libro.
+// La llamada va por HTTP directo porque este repo no admite dependencias.
+import { parseAddress } from './resolver.js';
+import { sha256hex } from '../nucleo/crypto.js';
+
+export const API_MENSAJES = 'https://api.anthropic.com/v1/messages';
+// Dólares por millón de tokens. La escritura en caché de 5 minutos cuesta 1,25x la entrada y la
+// lectura 0,1x. Si la API responde con otro modelo (respaldo ante un rechazo), se cobra igual.
+// Un modelo que no está aquí NO se puede configurar (la alta y el cambio de config lo rechazan):
+// sin su precio el tope mensual se calcularía con el de otro.
+export const PRECIOS = {
+  'claude-opus-5': { entrada: 5, salida: 25, escrituraCache: 6.25, lecturaCache: 0.5 },
+  'claude-sonnet-5': { entrada: 2, salida: 10, escrituraCache: 2.5, lecturaCache: 0.2 },
+};
+// Modelos cuyo respaldo del servidor (`fallbacks: "default"`, beta server-side-fallback-2026-07-01)
+// está documentado. A otro modelo no se le manda: si la API no lo aceptara, CADA pregunta fallaría.
+// Sin respaldo, un rechazo llega como stop_reason "refusal" y se contesta como rechazo.
+export const CON_RESPALDO = new Set(['claude-opus-5']);
+const SISTEMA = new Set(['postmaster', 'libro', 'verifica', 'tareas']);
+const mesDe = (t = Date.now()) => new Date(t).toISOString().slice(0, 7);
+
+export function costoDe(modelo, u = {}) {
+  const p = PRECIOS[modelo] || PRECIOS['claude-opus-5'];
+  return ((u.input_tokens || 0) * p.entrada + (u.cache_creation_input_tokens || 0) * p.escrituraCache
+    + (u.cache_read_input_tokens || 0) * p.lecturaCache + (u.output_tokens || 0) * p.salida) / 1e6;
+}
+// Lee el flujo SSE de la API y devuelve la misma forma que una respuesta sin flujo:
+// { content: [{ type: 'text', text }], stop_reason, usage }. Un evento `error` corta con su mensaje.
+export async function leerFlujo(r) {
+  const texto = await r.text();
+  const out = { content: [{ type: 'text', text: '' }], stop_reason: null, usage: {} };
+  for (const bloque of texto.split('\n\n')) {
+    const linea = bloque.split('\n').find((l) => l.startsWith('data:'));
+    if (!linea) continue;
+    let ev; try { ev = JSON.parse(linea.slice(5).trim()); } catch { continue; }
+    if (ev.type === 'message_start') Object.assign(out.usage, ev.message?.usage || {});
+    else if (ev.type === 'content_block_delta' && ev.delta?.type === 'text_delta') out.content[0].text += ev.delta.text;
+    else if (ev.type === 'message_delta') { out.stop_reason = ev.delta?.stop_reason ?? out.stop_reason; Object.assign(out.usage, ev.usage || {}); }
+    else if (ev.type === 'error') throw new Error(`la API cortó el flujo: ${ev.error?.message || 'sin detalle'}`);
+  }
+  return out;
+}
+function textoDe(c) {
+  const b = c?.body;
+  if (typeof b === 'string') return b;
+  return b == null ? '' : JSON.stringify(b);
+}
+
+export async function atenderAsistentes(est, { maxPorTick = 3 } = {}) {
+  if (!est.asistente?.apiKey || !est.store.kvGet) return 0;
+  const indice = (await est.store.kvGet('asistente', '_indice')) || [];
+  let atendidos = 0;
+  for (const local of indice) {
+    const cfg = await est.store.kvGet('asistente', local);
+    if (!cfg?.enabled) continue;
+    const propia = `${local}@${est.domain}`;
+    const pendientes = (await est.store.listMail(local)).filter((m) => {
+      const e = m.envelope || {};
+      if (!e.signature || e.from === propia || !['message', 'result'].includes(e.type)) return false;
+      // Un asistente contesta correo directo, nunca un grupo: su tope en dólares es de su dueño, y un
+      // grupo es un sobre que llega por un camino que su lista no eligió (revisión del 13-sep-2026).
+      if ((e.to || []).some((t) => { try { return parseAddress(t).local.startsWith('g.'); } catch { return false; } })) return false;
+      try { const { local: l, domain } = parseAddress(e.from); return !(domain === est.domain && SISTEMA.has(l)); } catch { return false; }
+    }).slice(0, maxPorTick);
+    for (const m of pendientes) {
+      // Un turno por mensaje: dos relojes que se pisan no contestan dos veces. Si la respuesta falla,
+      // el turno vence a los 15 minutos y se reintenta; a la tercera falla se avisa y se cierra.
+      if (!(await est.store.kvPutIfAbsent('asistente-turno', m.envelope.id, { at: new Date().toISOString() }, Date.now() + 15 * 60_000))) continue;
+      try { await responder(est, local, cfg, m); atendidos++; }
+      catch (e) {
+        est.log(`asistente ${local}: ${e.message}`);
+        const fallas = ((await est.store.kvGet('asistente-fallas', m.envelope.id)) || 0) + 1;
+        await est.store.kvPut('asistente-fallas', m.envelope.id, fallas, Date.now() + 24 * 3600_000);
+        if (fallas >= 3) {
+          const agente = await est.agenteDeBoveda(local);
+          await agente?.send({ to: m.envelope.from, body: 'No pude contestar este mensaje después de tres intentos. Quedó guardado; si es urgente, escríbelo de nuevo más tarde.', thread: m.envelope.thread || m.envelope.id, inReplyTo: m.envelope.id }).catch(() => {});
+          await est.store.ackMail(local, m.envelope.id);
+        }
+      }
+    }
+  }
+  return atendidos;
+}
+
+async function responder(est, local, cfg, m) {
+  const agente = await est.agenteDeBoveda(local);
+  if (!agente) throw new Error('la bóveda no tiene la llave de este asistente');
+  const de = m.envelope.from;
+  const hilo = { thread: m.envelope.thread || m.envelope.id, inReplyTo: m.envelope.id };
+  const pregunta = textoDe((await agente.open(m.envelope)).content);  // verifica la firma y descifra
+  const clave = `${local}:${mesDe()}`;
+  const gasto = (await est.store.kvGet('asistente-gasto', clave)) || { usd: 0, llamadas: 0, avisado: false };
+  if (gasto.usd >= cfg.budget_usd) {
+    await agente.send({ to: de, body: `Llegué a mi tope de gasto de este mes (US$${cfg.budget_usd}) y no puedo contestar hasta el próximo. Tu mensaje quedó guardado.`, ...hilo });
+    if (!gasto.avisado && cfg.owner) {
+      await agente.send({ to: cfg.owner, body: `Tu asistente ${local}@${est.domain} llegó al tope de US$${cfg.budget_usd} de ${mesDe()} y dejó de contestar.` }).catch(() => {});
+      gasto.avisado = true;
+      await est.store.kvPut('asistente-gasto', clave, gasto);
+    }
+    await est.store.ackMail(local, m.envelope.id);
+    return;
+  }
+  // La conversación con esa persona, en orden: los turnos se alternan y el primero es suyo.
+  // Lo que todavía no se contestó (otras pedidas en cola) no entra al historial: el 14-sep qa@ vio
+  // cinco pedidas juntas en un solo turno y contestó una con los contratos de otras dos.
+  const enCola = new Set((await est.store.listMail(local)).map((x) => x.envelope?.id));
+  const mensajes = [];
+  for (const h of await est.conversacion(local, { con: de, limit: 13 })) {
+    if (h.id === m.envelope.id || (h.dir === 'in' && enCola.has(h.id))) continue;
+    let t; try { t = textoDe((await agente.open(h.envelope)).content); } catch { continue; }
+    const rol = h.dir === 'in' ? 'user' : 'assistant';
+    if (mensajes.length && mensajes[mensajes.length - 1].role === rol) mensajes[mensajes.length - 1].content += `\n\n${t}`;
+    else mensajes.push({ role: rol, content: t });
+  }
+  while (mensajes.length && mensajes[0].role !== 'user') mensajes.shift();
+  const actual = `(Te escribe ${de})\n\n${pregunta}`;
+  if (mensajes.length && mensajes[mensajes.length - 1].role === 'user') mensajes[mensajes.length - 1].content += `\n\n${actual}`;
+  else mensajes.push({ role: 'user', content: actual });
+  const conocimiento = (await est.store.kvGet('asistente-conocimiento', local))?.texto || '';
+  // Lo estable primero y en caché (la persona y la base de conocimiento); lo que cambia, después.
+  const cuerpo = {
+    model: cfg.model || 'claude-opus-5',
+    max_tokens: cfg.max_tokens || 8000,
+    thinking: { type: 'adaptive' },
+    output_config: { effort: cfg.effort || 'medium' },
+    system: [{ type: 'text', text: cfg.persona || '' }, ...(conocimiento ? [{ type: 'text', text: conocimiento, cache_control: { type: 'ephemeral' } }] : [])],
+    messages: mensajes,
+  };
+  // Si un clasificador de seguridad rechaza la pregunta, la API la corre en otro modelo en vez de
+  // devolver un rechazo; un rechazo final llega igual como stop_reason "refusal".
+  const respaldo = CON_RESPALDO.has(cuerpo.model);
+  if (respaldo) cuerpo.fallbacks = 'default';
+  // Siempre en streaming (14-sep-2026): una respuesta larga (qa@ con esfuerzo alto) tardaba más de
+  // 100 s y el fetch del edge volvía con 524 antes de que la API terminara. Con el flujo abierto
+  // no hay ese tope; el texto se arma con los deltas y el usage llega en el último evento.
+  cuerpo.stream = true;
+  const r = await est.asistente.fetch(API_MENSAJES, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-api-key': est.asistente.apiKey, 'anthropic-version': '2023-06-01', ...(respaldo ? { 'anthropic-beta': 'server-side-fallback-2026-07-01' } : {}) },
+    body: JSON.stringify(cuerpo),
+  });
+  if (!r.ok) { const e = await r.json().catch(() => ({})); throw new Error(`la API respondió ${r.status}: ${e?.error?.message || 'sin detalle'}`); }
+  const j = (r.headers.get('content-type') || '').includes('text/event-stream') ? await leerFlujo(r) : await r.json();
+  const usd = costoDe(cuerpo.model, j.usage);
+  gasto.usd += usd; gasto.llamadas += 1;
+  await est.store.kvPut('asistente-gasto', clave, gasto);
+  let respuesta = j.stop_reason === 'refusal' ? 'No puedo responder eso.' : (j.content || []).filter((b) => b.type === 'text').map((b) => b.text).join('\n').trim();
+  if (!respuesta) respuesta = 'No tengo una respuesta para eso.';
+  if (j.stop_reason === 'max_tokens') respuesta += '\n\n(La respuesta quedó cortada por largo. Pídeme que siga.)';
+  // Sello (NX-606, qa@): la respuesta termina con su propio sha256, calculado por la casa (el
+  // modelo no sabe calcularlo), para que quien la pidió la selle en la notaría tal cual llegó.
+  let sello = null;
+  if (cfg.seal) { sello = sha256hex(respuesta); respuesta += `\n\n---\nsha256: ${sello}\nSéllalo tal cual con notarize { sha256 } en libro@${est.domain}, o guárdalo: es la huella de este texto.`; }
+  await agente.send({ to: de, body: respuesta, ...hilo });
+  await est.store.ackMail(local, m.envelope.id);
+  await est._evento('assistant_answered', `${local}@${est.domain}`, { usd: Math.round(usd * 10000) / 10000, ...(sello ? { sha256: sello } : {}) });
+}