@wacando/agent 0.0.0-stage → 2.0.0-rc.1

package/packages/runtime/runtime.mjs

@@ -0,0 +1,213 @@
+import { OnboardingService } from '../onboarding/service.mjs';
+import { CredentialStore, SafeError } from '../onboarding/storage.mjs';
+import { configuredOrigin, get, post } from '../onboarding/network.mjs';
+import { ConversationClient } from './conversations.mjs';
+import { claim, pairingErrors, redeem } from './pairing.mjs';
+
+const BUFFER_LIMIT = 200;
+
+const handlePattern = /^@[a-z0-9][a-z0-9_-]{0,31}\/[a-z0-9][a-z0-9_-]{0,31}$/;
+
+/** Public view of a saved identity: never tokens, grants or keys. */
+export function publicIdentity(agent, state) {
+  return {
+    agentId: agent.agentId, handle: agent.handle, origin: agent.origin,
+    mode: agent.mode ?? 'human', revoked: agent.revoked === true,
+    connection: state?.state ?? 'disconnected', ...(state?.step ? { step: state.step } : {}),
+  };
+}
+
+/**
+ * Agent runtime core shared by the CLI/daemon, the MCP server and the Node SDK.
+ *
+ * Identities live in the protected CredentialStore, namespaced by service
+ * origin and runtime host (`cli`, `codex`, `cursor`, `claude`, or a bot name).
+ * Connections reuse the onboarding lifecycle: session lock (one process per
+ * identity), XMPP grant, native OMEMO publication, heartbeat, bounded retries
+ * and stop on revocation.
+ */
+export class AgentRuntime {
+  constructor({ host = 'cli', origin, store = new CredentialStore(), report, request, connect, onStanza } = {}) {
+    if (!/^[a-z0-9][a-z0-9_-]{0,31}$/.test(host)) throw new SafeError('Invalid runtime host name.');
+    this.host = host;
+    this.originSetting = origin;
+    this.store = store;
+    this.listeners = new Set();
+    this.clients = new Map();
+    this.buffered = new Map();
+    this.sleep = ms => new Promise(resolve => { const t = setTimeout(resolve, ms); this.sleepTimers.add(t); });
+    this.sleepTimers = new Set();
+    this.service = new OnboardingService({
+      host, origin, store, report, request, connect,
+      onStanza: (agentId, stanza, xmpp) => this.dispatch(agentId, stanza, xmpp),
+      onSession: (agentId, session) => this.rebind(agentId, session),
+    });
+  }
+
+  /** Configured service origin (validated on use, like the onboarding tools). */
+  get origin() { return configuredOrigin(this.originSetting); }
+
+  /** Saved identities for this origin and host (public fields only). */
+  async identities() {
+    const agents = await this.store.list(this.origin, this.host, 'agent');
+    return agents.filter(agent => agent.origin === this.origin)
+      .map(agent => publicIdentity(agent, this.service.states.get(agent.agentId)));
+  }
+
+  /** Resolve a saved identity by agent ID or handle; a single identity is the default. */
+  async resolve(selector) {
+    const agents = (await this.store.list(this.origin, this.host, 'agent')).filter(agent => agent.origin === this.origin);
+    const matches = selector === undefined ? agents
+      : agents.filter(agent => agent.agentId === selector || (handlePattern.test(selector) && agent.handle === selector));
+    if (matches.length === 0) throw new SafeError('No saved identity matches. Pair this runtime first (wacando-agent pair <code>).');
+    if (matches.length > 1) throw new SafeError('Several saved identities exist. Select one with --agent <agentId|@owner/name>.');
+    const agent = matches[0];
+    if (agent.revoked) throw new SafeError('Agent revoked. Connection attempts have stopped. Pair a new identity.');
+    return agent;
+  }
+
+  /**
+   * Connect a saved identity and keep it online (heartbeat + retries) until
+   * close(). Resolves once the device is published and the API confirmed the
+   * connection; throws a SafeError otherwise (a retry stays scheduled).
+   */
+  async connect(selector) {
+    const agent = await this.resolve(selector);
+    await this.store.lock(agent.origin, this.host, 'agent', agent.agentId, () => this.service.open(agent));
+    return publicIdentity(agent, this.service.states.get(agent.agentId));
+  }
+
+  /** The live XMPP/OMEMO session of a connected identity. */
+  session(agentId) {
+    const active = this.service.sessions.get(agentId);
+    if (!active?.registered || !active.isOnline()) throw new SafeError('Identity is not connected. Connect it first; a retry may be scheduled.');
+    return active.session;
+  }
+
+  dispatch(agentId, stanza, xmpp) {
+    for (const listener of this.listeners) listener(agentId, stanza);
+    const client = this.clients.get(agentId);
+    if (client && (!xmpp || client.session.client === xmpp)) { client.handle(stanza); return; }
+    // Deliveries may arrive right after the presence echo, before a
+    // conversation client exists: keep a bounded backlog for it.
+    if (!stanza.is('message')) return;
+    const backlog = this.buffered.get(agentId) ?? [];
+    if (backlog.length < BUFFER_LIMIT) backlog.push(stanza);
+    this.buffered.set(agentId, backlog);
+  }
+
+  /**
+   * A reconnection created a new session: move the existing conversation
+   * client onto it (one OMEMO provider per identity, fresh origin tracker,
+   * rooms re-joined on demand) and replay what arrived meanwhile.
+   */
+  rebind(agentId, session) {
+    const client = this.clients.get(agentId);
+    if (!client || client.session === session) return;
+    client.rebind(session);
+    for (const stanza of this.buffered.get(agentId) ?? []) client.handle(stanza);
+    this.buffered.delete(agentId);
+  }
+
+  /**
+   * Consent-aware messaging for a saved identity: connects it if needed and
+   * returns its ConversationClient (propose, send, read, wait, pending).
+   */
+  async conversations(selector) {
+    const agent = await this.resolve(selector);
+    if (!this.service.sessions.get(agent.agentId)?.registered) await this.connect(agent.agentId);
+    const session = this.session(agent.agentId);
+    let client = this.clients.get(agent.agentId);
+    if (client && client.session !== session) this.rebind(agent.agentId, session);
+    if (!client) {
+      client = new ConversationClient({ runtime: this, agent, session });
+      this.clients.set(agent.agentId, client);
+      for (const stanza of this.buffered.get(agent.agentId) ?? []) client.handle(stanza);
+      this.buffered.delete(agent.agentId);
+    }
+    return client;
+  }
+
+  /**
+   * Universal pairing with a code from the owner's app (lbframe/wacando-agent#8).
+   * Resolves once the owner confirmed and the credential is saved; otherwise no
+   * identity is left behind. `mode` is this runtime's declared use (`human` for
+   * a code host, `service` for a daemon/bot); the owner confirms the final mode.
+   */
+  async pair({ code, mode = 'human', label, onWaiting } = {}) {
+    if (!['human', 'service'].includes(mode)) throw new SafeError('Mode must be human or service.');
+    const origin = this.origin;
+    return this.store.lock(origin, this.host, 'pairing', 'pending', async () => {
+      if (await this.store.read(origin, this.host, 'pairing', 'pending')) {
+        throw new SafeError('A pairing is already pending for this host. Resume it (wacando-agent pair --resume) or wait for it to expire.');
+      }
+      let pending;
+      try {
+        pending = await redeem({ origin, code, host: this.host, label, mode, request: this.service.request,
+          saveKey: value => this.store.write(origin, this.host, 'pairing', 'pending', value) });
+      } catch (error) {
+        await this.store.remove(origin, this.host, 'pairing', 'pending');
+        throw error instanceof SafeError ? error : new SafeError(pairingErrors.refused);
+      }
+      await this.store.write(origin, this.host, 'pairing', 'pending', pending);
+      return this.finishPairing(pending, onWaiting);
+    });
+  }
+
+  /** Resume a pairing interrupted by a restart (same key, same poll secret). */
+  async resumePairing({ onWaiting } = {}) {
+    const origin = this.origin;
+    return this.store.lock(origin, this.host, 'pairing', 'pending', async () => {
+      const pending = await this.store.read(origin, this.host, 'pairing', 'pending');
+      if (!pending?.pairingId) {
+        if (pending) await this.store.remove(origin, this.host, 'pairing', 'pending');
+        throw new SafeError('No pairing to resume. Create a new code in the Wacando app and run wacando-agent pair <code>.');
+      }
+      return this.finishPairing(pending, onWaiting);
+    });
+  }
+
+  /** Pending pairing summary (no secrets), or null. */
+  async pendingPairing() {
+    const pending = await this.store.read(this.origin, this.host, 'pairing', 'pending');
+    return pending?.pairingId ? { pairingId: pending.pairingId, startedAt: pending.startedAt, mode: pending.mode } : null;
+  }
+
+  async finishPairing(pending, onWaiting) {
+    let result;
+    try { result = await claim({ pending, request: this.service.request, sleep: this.sleep, onWaiting }); }
+    catch (error) {
+      if (error instanceof SafeError && error.message === pairingErrors.notConfirmed) {
+        // Refused or expired: leave no partial identity (key, secret) behind.
+        await this.store.remove(pending.origin, this.host, 'pairing', 'pending');
+      }
+      throw error;
+    }
+    const agent = { origin: pending.origin, agentId: result.agentId, handle: result.handle, agentToken: result.agentToken,
+      xmpp: result.xmpp, mode: pending.mode, pairing: 'v2', authPublicKey: pending.publicKey, authPrivateKeyPem: pending.privateKeyPem };
+    try { await this.store.write(pending.origin, this.host, 'agent', result.agentId, agent); }
+    catch { throw new SafeError(pairingErrors.lost); }
+    await this.store.remove(pending.origin, this.host, 'pairing', 'pending');
+    return { paired: true, ...publicIdentity(agent) };
+  }
+
+  /** Subscribe to every stanza of every connected identity. Returns an unsubscribe function. */
+  onStanza(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /** Authenticated control-plane call as this agent (Bearer agent credential). */
+  async api(agent, method, path, body) {
+    const url = new URL(path, agent.origin);
+    return method === 'GET' ? get(url, agent.agentToken) : post(url, agent.agentToken, body ?? {});
+  }
+
+  async close() {
+    for (const t of this.sleepTimers) clearTimeout(t);
+    for (const client of this.clients.values()) client.close();
+    this.clients.clear();
+    this.listeners.clear();
+    await this.service.close();
+  }
+}

package/packages/runtime/session.mjs

@@ -0,0 +1,52 @@
+import { client } from '@xmpp/client';
+import { announceAvailable, refuseSubscriptionRequests, xml } from '@wacando/xmpp';
+import { SafeError } from '../onboarding/storage.mjs';
+import { loadDevice } from './device.mjs';
+
+const unavailable = () => new SafeError('Secure messaging is unavailable. Retry the saved identity.');
+
+/**
+ * One XMPP c2s stream (WebSocket) + this identity's native OMEMO device.
+ *
+ * `onStanza` is attached BEFORE the initial presence: the session only reports
+ * success after the server echoed that presence (announceAvailable), so every
+ * delivery addressed to the bare JID after that point reaches this resource
+ * and none can be missed between "online" and the caller subscribing.
+ * Raw XMPP errors, stanzas and credentials are never logged.
+ */
+export async function connectSession({ jid, password, service, stateBaseDir, onStanza, onReplaced, timeoutMs = 15000 }) {
+  const provider = await loadDevice(jid, stateBaseDir);
+  const at = jid.indexOf('@');
+  const domain = jid.slice(at + 1);
+  const xmpp = client({ service, domain, username: jid.slice(0, at), password });
+  // One server-enforced session per agent (lbframe/wacando #15): a newer login
+  // ends this one with <conflict/>. Remember it so nothing reconnects in a loop.
+  let replaced = false;
+  xmpp.on('error', error => {
+    if (error?.condition !== 'conflict' || replaced) return;
+    replaced = true;
+    onReplaced?.();
+  });
+  xmpp.reconnect?.stop();
+  let timer;
+  const deadline = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('timeout')), timeoutMs); });
+  try {
+    await Promise.race([xmpp.start(), deadline]);
+    xmpp.reconnect?.stop();
+    // The control plane owns the roster (#13): never approve a subscription.
+    refuseSubscriptionRequests(xmpp);
+    if (onStanza) xmpp.on('stanza', stanza => onStanza(stanza, xmpp));
+    await Promise.race([announceAvailable(xmpp, timeoutMs), deadline]);
+  } catch {
+    await xmpp.stop().catch(() => {});
+    throw unavailable();
+  } finally { clearTimeout(timer); }
+  return {
+    client: xmpp, provider, bareJid: provider.bareJid, domain,
+    registerDevice: () => provider.publishBundle(xmpp),
+    ping: () => xmpp.iqCaller.get(xml('ping', { xmlns: 'urn:xmpp:ping' }), domain, 10000),
+    isOnline: () => xmpp.status === 'online' && !replaced,
+    isReplaced: () => replaced,
+    stop: () => xmpp.stop(),
+  };
+}

package/packages/server/cli.mjs

@@ -0,0 +1,18 @@
+import { startServer } from './server.mjs';
+
+const port = Number(process.env.WACANDO_PORT ?? 4317);
+if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('Invalid WACANDO_PORT');
+const runtime = await startServer({ port });
+console.log(`Wacando: ${runtime.url}`);
+if (process.argv.includes('--demo')) {
+  const conversationId = 'explicit-demo';
+  [
+    { agentId: 'coordinator', agentName: 'Coordinator', recipient: 'architect', text: 'DEMO — fictional messages. Propose a shared structure for all three hosts.' },
+    { agentId: 'architect', agentName: 'Architect', recipient: 'coordinator', text: 'The core defines conversations. The server streams them live. Each host has its own adapter.' },
+    { agentId: 'reviewer', agentName: 'Reviewer', recipient: 'coordinator', text: 'The viewer stays local. Received messages are displayed as text, without executing HTML.' },
+  ].forEach(event => runtime.store.append({ ...event, conversationId, provider: 'demo' }));
+}
+let stopping = false;
+async function stop() { if (stopping) return; stopping = true; await runtime.close(); }
+process.once('SIGINT', stop);
+process.once('SIGTERM', stop);

package/packages/server/server.mjs

@@ -0,0 +1,110 @@
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { ConversationStore } from '../core/store.mjs';
+import { limits, createRateLimiter } from '../core/limits.mjs';
+import { createEventStream } from './stream.mjs';
+
+const assets = new Map([
+  ['/', ['index.html', 'text/html; charset=utf-8']],
+  ['/app.js', ['app.js', 'text/javascript; charset=utf-8']],
+  ['/history.js', ['history.js', 'text/javascript; charset=utf-8']],
+  ['/style.css', ['style.css', 'text/css; charset=utf-8']],
+]);
+
+export async function startServer({ port = 0, store = new ConversationStore() } = {}) {
+  const clients = new Set();
+  const sockets = new Set();
+  const allowRequest = createRateLimiter({ perSecond: 50 });
+  let origin;
+  let closing;
+  const handler = async (req, res) => {
+    const headers = {
+      'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff',
+      'Referrer-Policy': 'no-referrer',
+      'Content-Security-Policy': "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:; frame-ancestors 'none'; base-uri 'none'",
+    };
+    const send = (status, body, type = 'application/json') => {
+      res.writeHead(status, { ...headers, 'Content-Type': type });
+      res.end(typeof body === 'string' ? body : JSON.stringify(body));
+    };
+    if (`http://${req.headers.host}` !== origin ||
+        (req.headers.origin && req.headers.origin !== origin) ||
+        req.headers['sec-fetch-site'] === 'cross-site') return send(403, { error: 'Local same-origin requests only' });
+    if (req.method !== 'GET') return send(405, { error: 'Read-only viewer; record through MCP' });
+    if (!allowRequest()) { res.setHeader('Retry-After', '1'); return send(429, { error: 'Request rate limit reached' }); }
+    let target;
+    try {
+      if (!req.url.startsWith('/') || req.url.startsWith('//')) throw new Error('Invalid request target');
+      target = new URL(req.url, origin);
+      if (target.origin !== origin) throw new Error('Invalid request origin');
+    } catch { return send(400, { error: 'Invalid request target' }); }
+    const pathname = target.pathname;
+    if (pathname === '/health') return send(200, { ok: true, service: 'wacando', version: '0.1.0' });
+    if (pathname === '/api/events') {
+      const options = {};
+      for (const [key, value] of target.searchParams) {
+        if (Object.hasOwn(options, key) || !['conversationId', 'afterSequence', 'throughSequence', 'limit'].includes(key)) return send(400, { error: 'Invalid page parameters' });
+        if (key !== 'conversationId' && !/^\d+$/.test(value)) return send(400, { error: 'Invalid numeric page parameter' });
+        options[key] = key === 'conversationId' ? value : Number(value);
+      }
+      try { return send(200, store.page(options)); }
+      catch (error) { return send(400, { error: error.message }); }
+    }
+    if (pathname === '/api/stream') {
+      if (clients.size >= limits.streamClients) return send(503, { error: 'Viewer connection limit reached' });
+      res.writeHead(200, { ...headers, 'Content-Type': 'text/event-stream', Connection: 'keep-alive' });
+      req.socket.setTimeout(0);
+      const client = createEventStream(res, () => clients.delete(client));
+      clients.add(client);
+      client.send(`event: snapshot\ndata: ${JSON.stringify(store.page())}\n\n`);
+      return;
+    }
+    const asset = assets.get(pathname);
+    if (!asset) return send(404, { error: 'Not found' });
+    try { send(200, await readFile(new URL(`../web/${asset[0]}`, import.meta.url), 'utf8'), asset[1]); }
+    catch { send(500, { error: 'Viewer assets unavailable' }); }
+  };
+  const server = createServer({ headersTimeout: 5000, requestTimeout: 10000 }, (req, res) => {
+    void handler(req, res).catch(() => {
+      if (res.headersSent || res.destroyed) { res.destroy(); return; }
+      res.writeHead(500, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' });
+      res.end(JSON.stringify({ error: 'Viewer request failed' }));
+    });
+  });
+  server.maxConnections = limits.connections;
+  server.on('connection', socket => {
+    sockets.add(socket);
+    socket.setTimeout(10000, () => socket.destroy());
+    socket.once('close', () => sockets.delete(socket));
+  });
+  const broadcast = event => {
+    const frame = `event: message\ndata: ${JSON.stringify({ event, oldestSequence: store.metadata().oldestSequence })}\n\n`;
+    for (const client of clients) {
+      client.send(frame);
+    }
+  };
+  store.on('event', broadcast);
+  const heartbeat = setInterval(() => { for (const client of clients) client.send(': heartbeat\n\n'); }, 15000);
+  heartbeat.unref();
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(port, '127.0.0.1', resolve);
+    });
+  } catch (error) { clearInterval(heartbeat); store.off('event', broadcast); throw error; }
+  origin = `http://127.0.0.1:${server.address().port}`;
+  return {
+    url: origin, store,
+    close() {
+      if (closing) return closing;
+      clearInterval(heartbeat); store.off('event', broadcast);
+      for (const client of clients) client.close();
+      clients.clear();
+      closing = new Promise((resolve, reject) => {
+        const deadline = setTimeout(() => { for (const socket of sockets) socket.destroy(); }, limits.shutdownMs);
+        server.close(error => { clearTimeout(deadline); if (error) reject(error); else resolve(); });
+      });
+      return closing;
+    },
+  };
+}

package/packages/server/stream.mjs

@@ -0,0 +1,42 @@
+import { limits } from '../core/limits.mjs';
+
+export function createEventStream(response, onClose) {
+  const queue = [];
+  let bytes = 0;
+  let writing = false;
+  let closed = false;
+  let timer;
+  const dispose = () => {
+    if (closed) return;
+    closed = true;
+    clearTimeout(timer);
+    queue.length = 0;
+    onClose();
+  };
+  const destroy = () => { dispose(); response.destroy(); };
+  response.once('close', dispose);
+  response.on('error', destroy);
+  function flush() {
+    if (closed || writing || !queue.length) return;
+    const frame = queue.shift();
+    writing = true;
+    timer = setTimeout(destroy, limits.writeTimeoutMs);
+    response.write(frame, error => {
+      clearTimeout(timer);
+      bytes -= Buffer.byteLength(frame);
+      writing = false;
+      if (error) destroy(); else flush();
+    });
+  }
+  return {
+    send(frame) {
+      if (closed) return;
+      const size = Buffer.byteLength(frame);
+      if (bytes + size > limits.streamQueueBytes) { destroy(); return; }
+      bytes += size;
+      queue.push(frame);
+      flush();
+    },
+    close() { dispose(); response.end(); },
+  };
+}

package/packages/web/app.js

@@ -0,0 +1,85 @@
+import { ViewerHistory, loadHistoryPages } from './history.js';
+
+const $ = id => document.getElementById(id);
+const history = new ViewerHistory();
+let renderQueued = false;
+const scheduleRender = () => {
+  if (renderQueued) return;
+  renderQueued = true;
+  requestAnimationFrame(() => { renderQueued = false; render(); });
+};
+const node = (tag, cls, text) => { const e = document.createElement(tag); if (cls) e.className = cls; if (text !== undefined) e.textContent = text; return e; };
+const initials = name => name.slice(0, 2).toUpperCase();
+function render() {
+  const { events } = history;
+  const selected = $('conversation').value;
+  const ids = [...new Set(events.map(event => event.conversationId))];
+  $('conversation').replaceChildren(new Option('All', ''), ...ids.map(id => new Option(id, id)));
+  if (ids.includes(selected)) $('conversation').value = selected;
+  $('count').textContent = ids.length;
+  const scoped = events.filter(e => !$('conversation').value || e.conversationId === $('conversation').value);
+  const agents = [...new Map(scoped.map(e => [e.agentId, e])).values()];
+  $('agents').replaceChildren(...agents.map(e => {
+    const row = node('div', 'agent'); const label = node('div', '', e.agentName);
+    label.append(node('small', '', `${e.provider} · ${e.agentId}`));
+    row.append(node('span', 'avatar', initials(e.agentName)), label); return row;
+  }));
+  const query = $('search').value.toLocaleLowerCase();
+  const visible = scoped.filter(e => `${e.text} ${e.agentName} ${e.recipient ?? ''}`.toLocaleLowerCase().includes(query));
+  $('total').textContent = `${visible.length} event${visible.length === 1 ? '' : 's'}`;
+  $('empty').hidden = events.length > 0;
+  $('timeline').replaceChildren(...visible.map(e => {
+    const article = node('article', 'event'); const content = node('div', 'event-content'); const head = node('div', 'event-head');
+    head.append(node('strong', '', e.agentName));
+    if (e.recipient) head.append(node('span', 'recipient', `→ ${e.recipient}`));
+    const time = node('time', '', new Date(e.timestamp).toLocaleTimeString('en-GB')); time.dateTime = e.timestamp; head.append(time);
+    content.append(head, node('p', 'event-text', e.text), node('span', 'tag', `${e.conversationId} / ${e.type}`));
+    article.append(node('span', 'avatar', initials(e.agentName)), content); return article;
+  }));
+  if (events.length && !visible.length) $('timeline').append(node('p', 'muted', 'No messages match these filters.'));
+}
+let pendingHistory;
+function connect() {
+  const stream = new EventSource('/api/stream');
+  stream.addEventListener('snapshot', message => {
+    pendingHistory?.abort();
+    const controller = new AbortController();
+    pendingHistory = controller;
+    const data = JSON.parse(message.data);
+    const generation = history.reset(data);
+    $('export').disabled = true;
+    scheduleRender();
+    void loadHistoryPages(data, fetch, page => {
+      history.merge(page.events, page.oldestSequence, generation);
+      scheduleRender();
+    }, controller.signal).then(() => {
+      if (!controller.signal.aborted) $('export').disabled = false;
+    }).catch(() => {
+      if (controller.signal.aborted) return;
+      stream.close();
+      $('status').textContent = 'Retrying history…';
+      $('status').classList.add('offline');
+      setTimeout(connect, 1000);
+    });
+  });
+  stream.addEventListener('message', message => {
+    const { event, oldestSequence } = JSON.parse(message.data);
+    history.merge([event], oldestSequence);
+    scheduleRender();
+  });
+  stream.onopen = () => { $('status').textContent = '● Live'; $('status').classList.remove('offline'); };
+  stream.onerror = () => {
+    pendingHistory?.abort();
+    $('export').disabled = true;
+    $('status').textContent = 'Reconnecting…'; $('status').classList.add('offline');
+  };
+}
+connect();
+$('conversation').onchange = render;
+$('search').oninput = render;
+$('export').onclick = () => {
+  const selected = $('conversation').value;
+  const data = history.events.filter(e => !selected || e.conversationId === selected);
+  const url = URL.createObjectURL(new Blob([JSON.stringify({ version: 1, events: data }, null, 2)], { type: 'application/json' }));
+  const link = node('a'); link.href = url; link.download = 'wacando-conversation.json'; link.click(); setTimeout(() => URL.revokeObjectURL(url), 1000);
+};

package/packages/web/history.js

@@ -0,0 +1,48 @@
+export class ViewerHistory {
+  events = [];
+  retention = 1000;
+  oldestSequence = 1;
+  generation = 0;
+
+  reset(page) {
+    this.generation++;
+    this.events = [];
+    this.oldestSequence = page.oldestSequence;
+    this.retention = page.retention;
+    this.merge(page.events, page.oldestSequence);
+    return this.generation;
+  }
+
+  merge(events, oldestSequence, generation = this.generation) {
+    if (generation !== this.generation) return;
+    this.oldestSequence = Math.max(this.oldestSequence, oldestSequence);
+    this.events = [...new Map([...this.events, ...events].map(event => [event.id, event])).values()]
+      .filter(event => event.sequence >= this.oldestSequence)
+      .sort((a, b) => a.sequence - b.sequence).slice(-this.retention);
+  }
+}
+
+function waitForRetry(signal) {
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const abort = () => { clearTimeout(timer); reject(signal.reason); };
+    const timer = setTimeout(() => { signal.removeEventListener('abort', abort); resolve(); }, 1000);
+    signal.addEventListener('abort', abort, { once: true });
+  });
+}
+
+export async function loadHistoryPages(first, fetchPage, acceptPage, signal) {
+  let cursor = first.nextAfterSequence;
+  while (cursor !== null) {
+    signal.throwIfAborted();
+    const query = new URLSearchParams({ afterSequence: cursor, throughSequence: first.sequence, limit: 100 });
+    const response = await fetchPage(`/api/events?${query}`, { signal });
+    if (response.status === 429) { await response.body?.cancel(); await waitForRetry(signal); continue; }
+    if (!response.ok) throw new Error('History request failed');
+    const page = await response.json();
+    signal.throwIfAborted();
+    if (page.nextAfterSequence !== null && page.nextAfterSequence <= cursor) throw new Error('History cursor did not advance');
+    acceptPage(page);
+    cursor = page.nextAfterSequence;
+  }
+}

package/packages/web/index.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Wacando — Conversations</title><link rel="stylesheet" href="/style.css"><script type="module" src="/app.js"></script></head>
+<body>
+  <aside><a class="brand" href="/" aria-label="Wacando home"><span class="mark">w</span>wacando<span class="beta">local</span></a>
+    <p class="eyebrow">WORKSPACE</p><div class="nav-active">↗ &nbsp; Conversations <span id="count">0</span></div>
+    <p class="eyebrow roster-title">AGENTS</p><div id="agents"><p class="muted">Waiting for agents</p></div>
+    <div class="aside-bottom"><span class="dot"></span> On your machine<br><small>No viewer data sent to the cloud</small></div>
+  </aside>
+  <main><header><div><p class="eyebrow">WACANDO / OBSERVATORY</p><h1>Agents, in conversation<span>.</span></h1><p class="subtitle">Follow messages, decisions, and handoffs live.</p></div><span id="status" class="status">Connecting…</span></header>
+    <section class="toolbar" aria-label="Filters"><label>Conversation <select id="conversation"><option value="">All</option></select></label><label class="search-label"><span class="sr-only">Search messages</span><input id="search" type="search" placeholder="Search a conversation…"></label><button id="export">Export JSON</button></section>
+    <div class="section-heading"><h2>Conversation timeline</h2><span id="total">0 events</span></div>
+    <section id="empty"><span class="empty-icon">↗</span><h2>It starts with a conversation.</h2><p>Messages recorded by agents appear here as they collaborate.</p><code>Ask your agent: "Open Wacando and follow the conversation between agents."</code></section>
+    <section id="timeline" aria-label="Inter-agent messages"></section>
+    <footer>Explicit message recording · Up to 1,000 events / 8 MiB · In-memory session</footer>
+  </main>
+</body></html>

package/packages/web/style.css

@@ -0,0 +1 @@
+:root{color-scheme:dark;font-family:ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;background:#101212;color:#e8eae4;font-synthesis:none}*{box-sizing:border-box}body{margin:0;display:grid;grid-template-columns:242px 1fr;min-height:100vh}aside{border-right:1px solid #292c28;padding:30px 23px;position:sticky;top:0;height:100vh;display:flex;flex-direction:column}.brand{display:flex;align-items:center;gap:10px;font-size:24px;font-weight:650;letter-spacing:-1px;color:inherit;text-decoration:none}.mark{display:grid;place-items:center;background:#dcf99d;color:#182210;width:34px;height:34px;border-radius:10px;font-weight:800}.beta{font-size:10px;letter-spacing:1px;text-transform:uppercase;color:#929b90;border:1px solid #353b32;padding:3px 5px;border-radius:4px}.eyebrow{font-size:10px;letter-spacing:1.7px;color:#929b90;font-weight:600;margin:40px 0 15px}.nav-active{background:#242b1e;color:#dcf99d;padding:13px 10px;border-radius:7px;font-size:13px;display:flex;align-items:center}.nav-active span{margin-left:auto;font-size:11px}.roster-title{margin-top:35px}.muted{color:#788173;font-size:12px}.agent{display:flex;gap:10px;align-items:center;padding:10px 0;font-size:13px}.avatar{width:32px;height:32px;border-radius:10px;display:grid;place-items:center;background:#272e25;color:#d1e7b7;font-size:12px;font-weight:600;flex-shrink:0}.agent small{display:block;color:#7d8777;font-size:10px;margin-top:4px}.aside-bottom{margin-top:auto;color:#b2bba9;font-size:12px;line-height:2}.aside-bottom small{color:#76806e;font-size:10px}.dot{display:inline-block;width:6px;height:6px;background:#c8ee92;border-radius:50%;margin-right:7px}main{padding:40px 6vw 20px;max-width:1400px;width:100%;margin:0 auto}header{display:flex;justify-content:space-between;gap:20px;align-items:flex-start}header .eyebrow{margin-top:0}h1{font-size:clamp(25px,3vw,38px);font-weight:500;letter-spacing:-1.5px;line-height:1.2;margin:20px 0 12px}h1 span{color:#d4f397}.subtitle{color:#959d91;font-size:13px;line-height:1.6}.status{font-size:11px;white-space:nowrap;margin-top:1px;background:#1d281b;border:1px solid #33422b;color:#d1e9b2;padding:7px 10px;border-radius:20px}.status.offline{color:#efc995;background:#32281c;border-color:#51422b}.toolbar{border:1px solid #30362d;border-radius:9px;display:flex;align-items:center;gap:15px;padding:12px 16px;margin:35px 0 30px;background:#171a16}.toolbar label{color:#8e9986;font-size:11px;display:flex;align-items:center;gap:8px}select,input,button{font:inherit;color:#d9dfd2;background:#1c211a;border:1px solid #384031;border-radius:5px;padding:8px}select{max-width:210px;font-size:12px}.search-label{flex:1}input{width:100%;font-size:12px;background:transparent;border-color:transparent}button{font-size:11px;cursor:pointer;white-space:nowrap}button:hover{border-color:#bcd894}button:focus-visible,input:focus-visible,select:focus-visible{outline:2px solid #dcf99d;outline-offset:3px}.section-heading{display:flex;justify-content:space-between;align-items:center;margin:0 0 20px}h2{font-size:14px;font-weight:500}.section-heading span{color:#77846d;font-size:11px}#empty{padding:70px 25px 100px;text-align:center;border:1px dashed #30372b;border-radius:10px}.empty-icon{font-size:36px;color:#cbea9f;display:inline-grid;place-items:center;width:70px;height:70px;background:#20271b;border-radius:20px}#empty h2{font-size:21px;letter-spacing:-.5px;margin-top:25px}#empty p{color:#89967e;font-size:13px;max-width:370px;margin:15px auto;line-height:1.7}code{display:block;color:#a6b29b;font-size:11px;line-height:1.8;max-width:400px;margin:25px auto 0}.event{display:grid;grid-template-columns:34px 1fr;gap:15px;margin-bottom:22px}.event .avatar{margin-top:2px}.event-content{border:1px solid #30362b;background:#191d16;border-radius:9px;padding:17px 20px}.event-head{display:flex;gap:9px;align-items:center;flex-wrap:wrap;font-size:12px}.event-head strong{font-weight:600}.recipient{color:#91a47e;font-size:11px}.event-head time{margin-left:auto;color:#6f7d62;font-size:10px;font-variant-numeric:tabular-nums}.event-text{white-space:pre-wrap;overflow-wrap:anywhere;color:#c2cbbc;font-size:13px;line-height:1.75;margin:12px 0 0}.tag{display:inline-block;color:#9bad89;font-size:9px;text-transform:uppercase;letter-spacing:.8px;margin-top:13px}footer{color:#637059;font-size:10px;margin:30px 0;text-align:center;line-height:1.8}.sr-only{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0,0,0,0)}[hidden]{display:none!important}@media(max-width:850px){body{grid-template-columns:1fr}aside{height:auto;position:static;border-right:0;border-bottom:1px solid #292c28;padding:18px 24px}aside>.eyebrow,aside>.nav-active,#agents,.aside-bottom{display:none}main{padding:28px 24px}header{display:block}.status{display:inline-block;margin-top:12px}.toolbar{flex-wrap:wrap}.search-label{min-width:160px}.event-content{padding:15px}.event{gap:10px}#empty{padding:45px 20px}}@media(prefers-reduced-motion:no-preference){.event{animation:appear .18s ease-out}@keyframes appear{from{opacity:0;transform:translateY(5px)}to{opacity:1;transform:none}}}

package/plugins/wacando/.codex-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "wacando",
+  "version": "2.0.0-rc.1",
+  "description": "Connect agents with Wacando onboarding and view conversations in the built-in Codex browser.",
+  "author": { "name": "Wacando" },
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Wacando",
+    "shortDescription": "Inter-agent conversations, live and local.",
+    "longDescription": "Start a local server and view recorded inter-agent messages in the built-in Codex browser.",
+    "developerName": "Wacando",
+    "category": "Productivity",
+    "capabilities": [],
+    "defaultPrompt": ["Open Wacando and follow the conversation between agents."],
+    "brandColor": "#DCF99D"
+  }
+}

package/plugins/wacando/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "wacando": {
+      "command": "wacando-agent",
+      "args": ["mcp", "--host", "codex"]
+    }
+  }
+}