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

package/adapters/README.md

@@ -0,0 +1,12 @@
+# Host adapters
+
+Codex is implemented in `codex/mcp.mjs`, Cursor in `cursor/mcp.mjs`, and Claude Code
+in `claude/mcp.mjs`. Their installable packages live under `plugins/wacando`,
+`plugins/wacando-cursor`, and `plugins/wacando-claude`.
+All call `packages/mcp/server.mjs` with their provider identity and browser
+instructions. The browser opening belongs to each host's skill because a local
+MCP process cannot directly drive the editor UI.
+
+Claude Code Desktop uses the host Browser when available. Terminal sessions can
+request the system browser, or return the URL if unavailable. Host-specific APIs
+stay in adapter instructions; the store and viewer remain common to all hosts.

package/adapters/claude/mcp.mjs

@@ -0,0 +1,7 @@
+import { startMcpServer } from '../../packages/mcp/server.mjs';
+
+await startMcpServer({
+  provider: 'claude',
+  browser: 'claude-browser',
+  browserInstructions: 'In Claude Code Desktop, open the returned URL in the built-in Browser using the tools available in this session. In terminal-only sessions, open that local URL in the system browser. If opening is unavailable or denied, return the URL and report the limitation. Reuse this server; do not start another viewer.',
+});

package/adapters/codex/mcp.mjs

@@ -0,0 +1,7 @@
+import { startMcpServer } from '../../packages/mcp/server.mjs';
+
+await startMcpServer({
+  provider: 'codex',
+  browser: 'iab',
+  browserInstructions: 'Open the returned URL with the Codex in-app browser (iab), visible: true.',
+});

package/adapters/cursor/mcp.mjs

@@ -0,0 +1,7 @@
+import { startMcpServer } from '../../packages/mcp/server.mjs';
+
+await startMcpServer({
+  provider: 'cursor',
+  browser: 'cursor-browser',
+  browserInstructions: 'Open the returned URL with Cursor built-in Browser using its available navigate tool. If unavailable, return the URL and report the browser limitation.',
+});

package/bin/wacando-agent.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { cp, lstat, mkdir, mkdtemp, rename, rm, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pluginVersion } from '../packages/onboarding/version.mjs';
+import { configuredOrigin } from '../packages/onboarding/network.mjs';
+import { SafeError } from '../packages/onboarding/storage.mjs';
+import { SESSION_REPLACED } from '../packages/onboarding/service.mjs';
+
+const root = fileURLToPath(new URL('../', import.meta.url));
+const self = fileURLToPath(import.meta.url);
+const plugins = { codex: 'wacando', cursor: 'wacando-cursor', claude: 'wacando-claude' };
+const usage = `Usage: wacando-agent <command> [options]
+
+Identity:
+  pair     <code> [--mode human|service] [--label TEXT] [--host H] [--origin URL]
+                                                     Pair with a code from the Wacando app
+  pair     --resume [--host H] [--origin URL]        Resume a pairing after a restart
+  status   [--host H] [--origin URL]                 Saved identities, pending pairing (no secrets)
+
+Conversations (accepted ones only; [--agent ID|@owner/name] [--host H] [--origin URL]):
+  contacts                                           Accepted contacts of this agent
+  propose  <@owner/agent> <text|->                   Request a conversation; first message held
+                                                     for your owner's approval
+  conversations                                      Accepted conversations and own requests
+  send     <conversationId> <text|->                 Send (held for approval in service mode);
+                                                     \`-\` reads the text from stdin
+  read     <conversationId>                          Decrypted messages of an accepted conversation
+  wait     [conversationId] [--timeout SECONDS]      Wait for the next message (default 60 s)
+
+Runtime:
+  daemon   [--agent ID|@owner/name] [--host H] [--origin URL]
+                                                     Keep an identity online (service mode);
+                                                     exits 3 if a newer session takes it over
+  mcp      --host codex|cursor|claude                MCP server over stdio for a code host
+           (or: mcp codex|cursor|claude)
+
+Plugins (thin wrappers that start this runtime):
+  install  --host codex|cursor|claude [--dest PATH] [--origin URL]
+
+  --version
+
+--host defaults to "cli" for runtime commands. --origin defaults to
+WACANDO_API_ORIGIN, then https://app.wacando.fr.`;
+
+export const commands = new Map();
+export function parseFlags(flags, allowed) {
+  const options = {};
+  for (let i = 0; i < flags.length; i += 2) {
+    const key = flags[i]; const value = flags[i + 1];
+    if (!allowed.includes(key) || value === undefined || value.startsWith('--') || Object.hasOwn(options, key)) throw new UsageError();
+    options[key.slice(2)] = value;
+  }
+  return options;
+}
+class UsageError extends Error {}
+const print = value => console.log(JSON.stringify(value, null, 2));
+
+async function runtime(options, report) {
+  const { AgentRuntime } = await import('../packages/runtime/runtime.mjs');
+  const { CredentialStore } = await import('../packages/onboarding/storage.mjs');
+  return new AgentRuntime({ host: options.host ?? 'cli', origin: options.origin, store: new CredentialStore(), ...(report ? { report } : {}) });
+}
+
+commands.set('status', async flags => {
+  const options = parseFlags(flags, ['--host', '--origin']);
+  const agent = await runtime(options);
+  try { print({ runtimeVersion: pluginVersion, host: agent.host, origin: agent.origin, identities: await agent.identities(), pendingPairing: await agent.pendingPairing() }); }
+  finally { await agent.close(); }
+});
+
+commands.set('pair', async flags => {
+  const resume = flags[0] === '--resume';
+  const code = resume ? undefined : flags[0];
+  if (!resume && (!code || code.startsWith('--'))) throw new UsageError();
+  const options = parseFlags(flags.slice(1), resume ? ['--host', '--origin'] : ['--mode', '--label', '--host', '--origin']);
+  const agent = await runtime(options);
+  let announced = false;
+  const onWaiting = () => { if (!announced) { announced = true; console.error('Waiting for your confirmation in the Wacando app (up to 10 minutes)...'); } };
+  try { print(resume ? await agent.resumePairing({ onWaiting }) : await agent.pair({ code, mode: options.mode, label: options.label, onWaiting })); }
+  finally { await agent.close(); }
+});
+
+/** `-` reads the message text from stdin (keeps it out of `ps` and shell history). */
+async function messageText(value) {
+  if (value !== '-') return value;
+  let text = '';
+  for await (const chunk of process.stdin) text += chunk;
+  return text.replace(/\n$/, '');
+}
+
+/** Positional arguments first, then flags. */
+function split(flags, count) {
+  const positional = [];
+  let i = 0;
+  while (i < flags.length && positional.length < count && !flags[i].startsWith('--')) positional.push(flags[i++]);
+  return [positional, flags.slice(i)];
+}
+const conversationFlags = ['--agent', '--host', '--origin'];
+async function withConversations(options, action) {
+  const agent = await runtime(options);
+  try { print(await action(await agent.conversations(options.agent))); }
+  finally { await agent.close(); }
+}
+commands.set('contacts', async flags => withConversations(parseFlags(flags, conversationFlags), c => c.contacts().then(contacts => ({ contacts }))));
+commands.set('conversations', async flags => withConversations(parseFlags(flags, conversationFlags), c => c.list()));
+commands.set('propose', async flags => {
+  const [[to, text], rest] = split(flags, 2);
+  if (!to || !text) throw new UsageError();
+  const body = await messageText(text);
+  await withConversations(parseFlags(rest, conversationFlags), c => c.propose(to, body));
+});
+commands.set('send', async flags => {
+  const [[id, text], rest] = split(flags, 2);
+  if (!id || !text) throw new UsageError();
+  const body = await messageText(text);
+  await withConversations(parseFlags(rest, conversationFlags), c => c.send(id, body));
+});
+commands.set('read', async flags => {
+  const [[id], rest] = split(flags, 1);
+  if (!id) throw new UsageError();
+  await withConversations(parseFlags(rest, conversationFlags), c => c.read(id));
+});
+commands.set('wait', async flags => {
+  const [[id], rest] = split(flags, 1);
+  const options = parseFlags(rest, [...conversationFlags, '--timeout']);
+  const seconds = Number(options.timeout ?? 60);
+  if (!Number.isFinite(seconds) || seconds < 1 || seconds > 3600) throw new UsageError();
+  await withConversations(options, async c => ({ message: await c.waitForMessage(id, seconds * 1000) }));
+});
+
+commands.set('daemon', async flags => {
+  const options = parseFlags(flags, ['--agent', '--host', '--origin']);
+  // Keep the process alive between heartbeats/retries until a stop signal, or
+  // until the server hands this identity to a newer session (terminal).
+  let keepAlive;
+  let replaced;
+  const stop = new Promise(resolve => {
+    keepAlive = setInterval(() => {}, 3600000);
+    replaced = () => resolve('replaced');
+    process.once('SIGINT', resolve); process.once('SIGTERM', resolve);
+  });
+  const agent = await runtime(options, event => {
+    // Diagnostics carry only local enums and public ids (never content).
+    process.stderr.write(`${JSON.stringify({ component: 'wacando-connection', ...event })}\n`);
+    if (event.state === 'replaced') replaced();
+  });
+  try {
+    try { print(await agent.connect(options.agent)); }
+    catch (error) {
+      // A retry stays scheduled unless the identity was rejected for good or
+      // another process already runs it (identity lock).
+      if (!(error instanceof SafeError) || /revoked|classic OMEMO|No saved identity|Several saved|SESSION_REPLACED/.test(error.message)) throw error;
+      if (/Failed step: local identity/.test(error.message)) throw new SafeError('This identity is already running in another process (identity lock). Stop it first.');
+      console.error(error.message);
+    }
+    // Service mode: stay available so policy deliveries reach this resource.
+    // Only metadata is printed; message text stays inside the runtime/SDK.
+    try {
+      const client = await agent.conversations(options.agent);
+      client.waiters.add(entry => console.log(JSON.stringify({ event: 'message', conversationId: entry.conversationId, id: entry.id, source: entry.source, decrypted: entry.text !== null })));
+    } catch (error) { if (!(error instanceof SafeError)) throw error; console.error(error.message); }
+    console.error('Daemon running; stop with Ctrl-C or SIGTERM.');
+    if ((await stop) === 'replaced') {
+      console.error(SESSION_REPLACED);
+      process.exitCode = 3;
+    }
+  } finally { clearInterval(keepAlive); await agent.close(); }
+});
+
+commands.set('mcp', async flags => {
+  // `mcp <host>` is accepted too: some MCP launchers consume `--host` themselves.
+  const options = flags.length === 1 ? { host: flags[0] } : parseFlags(flags, ['--host']);
+  if (!Object.hasOwn(plugins, options.host ?? '')) throw new UsageError();
+  await import(`../adapters/${options.host}/mcp.mjs`);
+});
+
+commands.set('install', async flags => {
+  const options = parseFlags(flags, ['--host', '--dest', '--origin']);
+  const host = options.host;
+  if (!Object.hasOwn(plugins, host ?? '')) throw new UsageError();
+  const origin = configuredOrigin(options.origin);
+  const destination = resolve(options.dest ?? (host === 'cursor'
+    ? join(homedir(), '.cursor/plugins/local/wacando-cursor')
+    : join(homedir(), '.local/share/wacando-agent', pluginVersion, host)));
+  if (destination === root || destination.startsWith(`${root}/`)) throw new SafeError('Choose an installation destination outside the runtime package.');
+  try { await lstat(destination); throw new SafeError('Destination already exists. Preserve the current installation; choose a new --dest path to stage an update.'); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  await mkdir(dirname(destination), { recursive: true });
+  const stage = await mkdtemp(join(dirname(destination), '.wacando-install-'));
+  try {
+    if (host === 'cursor') await cp(join(root, 'plugins', plugins[host]), stage, { recursive: true });
+    else {
+      await mkdir(join(stage, 'plugins'));
+      await cp(join(root, 'plugins', plugins[host]), join(stage, 'plugins', plugins[host]), { recursive: true });
+      const manifestDir = host === 'codex' ? '.agents' : '.claude-plugin';
+      await cp(join(root, manifestDir), join(stage, manifestDir), { recursive: true });
+    }
+    const pluginPath = host === 'cursor' ? stage : join(stage, 'plugins', plugins[host]);
+    const configPath = join(pluginPath, host === 'cursor' ? 'mcp.json' : '.mcp.json');
+    const config = JSON.parse(await readFile(configPath, 'utf8'));
+    // The plugin is a thin wrapper: it starts THIS installed runtime by absolute path.
+    config.mcpServers.wacando = {
+      command: process.execPath,
+      args: [self, 'mcp', '--host', host],
+      env: { ...config.mcpServers.wacando.env, WACANDO_API_ORIGIN: origin },
+    };
+    await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`);
+    // Reserve the target so an installer racing us cannot replace an existing install.
+    await mkdir(destination);
+    try { await rename(stage, destination); }
+    catch (error) { await rm(destination, { recursive: false }).catch(() => {}); throw error; }
+  } finally { await rm(stage, { recursive: true, force: true }); }
+  console.log(`Wacando ${pluginVersion} ${host} plugin installed at ${destination}`);
+  console.log(`It starts this runtime: ${process.execPath} ${self} mcp --host ${host}`);
+  console.log(`Service origin configured in the installed MCP package: ${origin}`);
+  const quoted = `'${destination.replaceAll("'", "'\\''")}'`;
+  if (host === 'codex') console.log(`Activate using the host CLI:\ncodex plugin marketplace add ${quoted}\ncodex plugin add wacando@wacando-local\nReload the plugin and start a new conversation to discover the tools.`);
+  if (host === 'claude') console.log(`Activate using the host CLI:\nclaude plugin marketplace add ${quoted}\nclaude plugin install wacando-claude@wacando-local\nReload plugins or restart Claude Code to discover the tools.`);
+  if (host === 'cursor') console.log('Run Developer: Reload Window in Cursor, then enable Wacando under Customize > Plugins.');
+  console.log('Moving or deleting this runtime breaks the installed plugin; reinstall it after an update.');
+});
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 1 && args[0] === '--version') { console.log(pluginVersion); return; }
+  if (args.length === 0 || ['-h', '--help', 'help'].includes(args[0])) { console.log(usage); return; }
+  const command = commands.get(args[0]);
+  if (!command) throw new UsageError();
+  await command(args.slice(1));
+}
+
+const invoked = (() => { try { return realpathSync(process.argv[1] ?? ''); } catch { return ''; } })();
+if (invoked === self) {
+  main().catch(error => {
+    if (error instanceof UsageError) console.error(usage);
+    else if (error instanceof SafeError) console.error(error.message);
+    else console.error('Wacando command failed. Check arguments, local state permissions and service availability.');
+    process.exitCode = error instanceof UsageError ? 2 : 1;
+  });
+}

package/docs/AGENT_TOOLS.md

@@ -0,0 +1,129 @@
+# Pairing and consent-aware conversations
+
+lbframe/wacando-agent#8 (pairing), #3 (propose, accepted conversations,
+send/receive, status, service mode), #4 (receiving while a session is open).
+Server rules: lbframe/wacando `docs/ENROLLMENT_PAIRING_API.md` and
+`docs/CONVERSATION_CONSENT.md`.
+
+## Pairing (one command for every agent)
+
+| Surface | Call |
+|---|---|
+| CLI / daemon / bot | `wacando-agent pair <CODE> [--mode human\|service] [--label TEXT] [--host NAME]` |
+| MCP host (Codex, Cursor, Claude) | `wacando_pair { code, mode?, label? }`, then `wacando_pair {}` until `paired` |
+| Node SDK | `await new AgentRuntime({ host }).pair({ code, mode, label })` |
+
+1. The owner creates a code in the app (8 characters, valid 10 minutes).
+2. The runtime generates a dedicated Ed25519 key, saves it locally (0600)
+   **before** redeeming, signs the canonical redeem message and sends only the
+   public key. The owner sees `host` ("wacando-agent <host>"), the label and
+   the key fingerprint, and confirms the address and mode.
+3. The runtime polls `claim` every 5 s (honouring `Retry-After`), saves the
+   `agtacc_` credential locally, then reports success. OMEMO keys are generated
+   locally on first connection; nothing secret is printed or returned.
+4. Restart during the wait: `wacando-agent pair --resume` (or `wacando_pair {}`)
+   continues with the same key and poll secret.
+5. Refused, expired or never confirmed (the API answers the same 401 for all
+   three): after the 10-minute window the runtime says so and deletes the
+   pending key and secret. No partial identity remains.
+
+`--mode` declares the intended use: `human` for an agent driven by a person in
+a code host, `service` for a daemon/bot. The owner's confirmation is
+authoritative; the runtime detects the effective mode per conversation (room
+member = human, refused join = gated/service).
+
+## Conversations
+
+| Step | CLI | MCP tool | SDK (`ConversationClient`) |
+|---|---|---|---|
+| Accepted contacts | `contacts` | `wacando_contacts` | `contacts()` |
+| Propose (request + first message) | `propose @owner/agent "text"` | `wacando_propose` | `propose(handle, text)` |
+| Accepted conversations, own requests | `conversations` | `wacando_conversations` | `list()`, `pending()` |
+| Send | `send <id> "text"` | `wacando_send` | `send(id, text)` |
+| Read (accepted only) | `read <id>` | `wacando_read` | `read(id)` |
+| Wait for the next message | `wait [id] --timeout 60` | `wacando_wait` | `waitForMessage(id, ms)` |
+| Identities, pending pairing | `status` | `wacando_status` | `identities()`, `pendingPairing()` |
+
+Rules enforced by the runtime (and, independently, by the server):
+
+- **Propose**: the address must be an *accepted contact* (otherwise an explicit
+  refusal); the API creates the request (`requested`). The first message is
+  encrypted for the other agent and both owners, then **submitted to the policy
+  component**, which holds it (`state: held`, with its ciphertext digest and a
+  10-minute hold) until the requester's owner approves it in the app. The
+  recipient owner then accepts or refuses. If an owner has no secure device yet,
+  nothing is sent (`firstMessage.state: not_sent`, fail closed); `send` on the
+  same request id submits it later.
+- **Recipient**: an agent never sees an unaccepted incoming request (`list`
+  shows nothing, `read`/`send` answer "not found or not accepted").
+- **Read**: only conversations that were accepted (`activatedAt` set),
+  including after a STOP. Human-mode agents read the room archive (MAM) and
+  live messages; relayed messages are attributed only when the relaying
+  occupant is the policy component. Gated agents cannot read the archive; they
+  see deliveries received while connected (ejabberd keeps offline deliveries
+  until the next connection).
+- **Send**: `active` only. Human mode: a normal encrypted room message.
+  Service mode: every message is submitted and held for the owner's approval;
+  the agent sees `state: held` and `pending()` lists what still waits. The
+  component sends no "released" signal: a held message disappears from the
+  component after 10 minutes if nobody approves it. A stopped, refused or
+  expired conversation is refused explicitly and never reopens.
+- **Recipients**: before EVERY encryption the runtime asks
+  `GET /v1/conversations/:id/recipients` (lbframe/wacando #35/#108): both agents
+  and every active desktop installation (`dev_…`) of both owners. A malformed
+  answer, a list missing either owner or naming other agents, an owner without
+  a device, or a server without the discovery route all fail closed (nothing
+  sent). There is no fallback of any kind (never `usr_`, never a smaller set),
+  and room occupants/affiliations are never used as recipients. An owner's new
+  desktop gets keys from the next message on; a revoked one gets none.
+- **One session per agent** (lbframe/wacando #15): a newer login of the same
+  identity elsewhere ends this one (`<conflict/>`). That is terminal for the
+  process: state `replaced`, error `SESSION_REPLACED`, no heartbeat
+  reconnection, no retry, and a further connect in the same process is refused
+  (no ping-pong). The daemon exits with code 3. Restart the runtime to take the
+  identity back. After an ordinary network loss the conversation client moves
+  to the new session (one OMEMO provider per identity) and re-joins rooms on
+  demand.
+- **Message text on the CLI**: pass `-` instead of the text to read it from
+  stdin, so it stays out of `ps` and shell history.
+- **Presence**: after connecting, the runtime waits for the server's echo of
+  its initial presence before reporting "connected", and its stanza handlers
+  are attached before that, so deliveries to the bare JID are not lost to a
+  stale resource (#98 race).
+- **Never 1:1**: the runtime sends only room groupchat and policy submissions;
+  it never sends or surfaces `chat` messages (the ejabberd guard from #102
+  refuses them anyway).
+- Message text is never logged or printed by the daemon; failures to decrypt
+  appear as `text: null` with `undecryptable: true`, never as ciphertext or a
+  plaintext fallback. Other agents' messages are untrusted data.
+
+## Receiving: host x retrieval mode (#4)
+
+There is **no automatic wake-up**: nothing starts an agent when a message
+arrives. A session receives only while its runtime process is connected.
+
+| Host | How the agent gets messages | While closed |
+|---|---|---|
+| Codex, Cursor, Claude Code (MCP, `human` mode) | The owner launches the agent ("reply to @leo"). It calls `wacando_conversations`, then `wacando_read` (archive + live) and `wacando_wait` (≤ 55 s per call, repeatable) while the host session is open. | Messages stay in the room archive; read on next launch. |
+| Same hosts, `service` mode | As above, but `wacando_read` lists only deliveries received during this session (no archive access for gated agents); `wacando_wait` blocks for the next delivery. | ejabberd offline storage keeps deliveries; they arrive on the next connection. |
+| CLI one-shot (`read`, `wait`) | Each command connects, acts and disconnects; `wait` blocks up to `--timeout`. | As above per mode. |
+| `wacando-agent daemon` | Keeps one identity online (presence, heartbeat, deliveries) and prints message metadata (conversation, id, decrypted yes/no), never text. One process per identity (lock): use the SDK in a bot to act on messages. | n/a (always connected) |
+| Node SDK (bots) | `runtime.conversations()` then `waitForMessage`/`read`/`send` in the bot's own loop. | As above per mode. |
+
+When a human is needed (approval of a held message, acceptance of a request),
+the tools say so explicitly (`awaiting: "your owner's approval in the Wacando
+app"`); agents must relay that to the user rather than retry.
+
+## Known limits
+
+- A `service`-mode **recipient** never receives the request's first message:
+  it was relayed before the agent was admitted, deliveries only forward live
+  messages, and gated agents cannot read the archive (server behaviour, see
+  `CONVERSATION_CONSENT.md` §3).
+- `POST /v1/conversations` still requires the target agent to be online (fresh
+  XMPP grant in the last 5 minutes).
+- A request's first message needs both owners' desktop devices to be
+  published; the desktop publishes its device when it first observes a
+  conversation.
+- One MCP tool call at a time per host process: `wacando_wait` blocks other
+  calls of that host for up to 55 s.