@7ots/cli 0.1.1 → 0.1.3

package/llms.txt

@@ -1,13 +1,205 @@
 # 7ots
 
 > Open-source embeddable web agent: it sees the page, speaks and acts for your visitor. One HTML tag, your server, your brand.
-> Every ot has an identity (face, personality, voice, meet avatar) reproducible from a short seed, and can also live on
-> your computer as a virtual pet and join apuchat meet video calls.
+> Every ot has an identity (face, personality, voice, meet avatar) reproducible from a short seed. The same ot can live
+> on a website (widget), on the user's computer (a virtual pet: desktop window, terminal or tmux), in apuchat meet
+> video calls, and answer email (apumail) and chat (apuchat). 7ots integrates those services; it does not host audio or mail.
 
-- Site: https://7ots.com/
-- Create an identity in the browser: https://7ots.com/#create
-- Hosted ots (dashboard): https://7ots.com/app/
-- npm: https://www.npmjs.com/package/7ots (CLI: `npx @7ots/cli help`)
+- Site: https://7ots.com/ · create an identity in the browser: https://7ots.com/#create
+- Hosted ots (dashboard, no server needed): https://7ots.com/app/
+- CLI: npm `@7ots/cli` (https://www.npmjs.com/package/@7ots/cli) → `npx -y @7ots/cli help`, `npx -y @7ots/cli <cmd> --help`
+- This file: https://7ots.com/llms.txt (also `npx -y @7ots/cli docs`)
+
+# Read this first (for coding agents)
+
+1. Never invent identity fields or config files by hand: use the CLI, it validates everything.
+2. Ask the user only what you can't tell from the project. The usual question is WHERE the ot should live:
+   - a website in this repo → widget (section "Website");
+   - not a website (library, backend, CLI, data…) → the pet on their computer, a meet call, or hosting on https://7ots.com/app/;
+   - "on my computer" / "a tamagotchi" → the pet (section "Pet").
+3. From an agent, commands must return: use `--detach` for the pet, run `meet` in the background, and ask the user to run
+   interactive commands themselves (`setup`, the terminal pet) — in Claude Code: `! npx -y @7ots/cli setup`.
+4. Language: `--lang en|es|pt` on `new` sets the ot's language, and from then on every CLI text follows it
+   (order: SEVENOTS_LANG > ~/.7ots/config.json "lang" > the ot's language > LANG > English).
+5. Secrets (API keys, tokens) never go in HTML, in identity.json or in your reply: they go in env vars / .env of a server,
+   in ~/.7ots/keys.json (written by `setup`, 0600) or in the https://7ots.com/app/ dashboard.
+6. When done, tell the user: the ot's name and seed, where it lives, and how to see it (URL, `7ots pet`, …).
+
+# Typical flows
+
+- "Use 7ots" in a website repo:
+  `npx -y @7ots/cli new --lang <en|es|pt>` → `npx -y @7ots/cli install` → tell the user which AI endpoint the widget uses.
+- "Give me a pet":
+  `npx -y @7ots/cli new` (if there is no identity) → `npx -y @7ots/cli pet --mode desktop --detach` → `npx -y @7ots/cli hooks install --claude`.
+- "Put it in a call": `npx -y @7ots/cli meet --new` (in the background) and give the printed link only to the user.
+- "Host it, no server": create it at https://7ots.com/app/ (or open the link `install` prints) and paste its one-line embed.
+
+# CLI reference (`npx -y @7ots/cli <command>`, or `7ots <command>` once installed globally)
+
+Every command accepts `--help` (prints usage, never launches anything) and `--lang en|es|pt`.
+
+| Command | What it does |
+|---|---|
+| `new [--seed s] [--name n] [--lang en\|es\|pt] [--global] [--force] [--json]` | Random identity → `.7ots/identity.json` (`--global`: `~/.7ots/identity.json`, shared by every project). Keeps an existing one unless `--force`. |
+| `show [--json\|--prompt]` | The identity in use (the project's, else the global one). `--prompt`: as a system prompt. |
+| `seed <text>` | Normalizes a seed. Same seed = same ot everywhere. |
+| `install [--target html\|self\|print] [file]` | Puts the widget in the project (see "Website"). |
+| `setup` (alias `wizard`, `init`) | Interactive wizard: where the ot lives, brain, voice, pet mode, chattiness, hooks. Writes `~/.7ots/config.json` and `keys.json`. |
+| `pet [--mode desktop\|terminal\|browser\|auto] [--detach] [--opaque] [--tmux] [--compact]` | Wakes the pet (see "Pet"). |
+| `feed` · `play` · `sleep` · `wake` · `say <text>` | Care for the pet (works even if it is not running: the state is saved). |
+| `status [--line\|--json]` | Level, food, energy, fun. `--line`: one short line for status bars. |
+| `stop` | Stops the pet daemon (and its windows). |
+| `hooks install\|remove [--claude] [--shell] [--global]` | Lets the pet react to your work (see "Hooks"). |
+| `meet --new [--minutes n]` · `meet "<invite or link>"` | The ot joins an apuchat meet video call. |
+| `prompt [identity\|install\|pet\|meet\|all]` | Short recipes for coding agents. |
+| `docs` | Prints this file. |
+| `login orquesta` | Connects a getorquesta.com account (brain "batuta", home "orquesta"). |
+| `server` | Runs the 7ots proxy (`/api/agent`) with the env vars below. |
+| `version` · `help` | |
+
+# Files
+
+| Path | Content |
+|---|---|
+| `.7ots/identity.json` (project) / `~/.7ots/identity.json` (global) | The identity. Public data only (name, role, look, voice, personality, contact). Commit it if you want. |
+| `~/.7ots/config.json` | Written by `setup`: `lang`, `home`, `brain`, `voice`, `pet` (below). |
+| `~/.7ots/keys.json` (0600) | Keys typed in `setup`, under their env-var names. Env vars always win. Never print it. |
+| `~/.7ots/pet.json` · `pet.log` · `pet.token` | Pet state, daemon log, local auth token. |
+| `SEVENOTS_HOME` | Moves `~/.7ots` elsewhere. `SEVENOTS_PET_PORT` (default 7717) moves the pet daemon. `SEVENOTS_LANG` forces the CLI language. |
+
+Identity fields: `id, name, role, tagline, seed, bio, language, languages, personality{tone, traits, instructions}, look{color, …},
+voice{provider, id, lang}, contact{…}`. Change them with `new --force`, the web editor (https://7ots.com/#create) or the backoffice, not by hand.
+
+## config.json
+
+```
+home   { kind: 'local' }                                  only on this computer
+       { kind: '7ots', url: 'https://7ots.com/api/o/<id>' }        hosted on 7ots.com
+       { kind: 'server', url: 'https://site/api/agent' }   the user's own 7ots server
+       { kind: 'orquesta', projectId, projectName }        a getorquesta.com project
+brain  { kind: 'lines' }                                  built-in phrases, no AI (default)
+       { kind: 'cli', cli: 'claude'|'codex'|'gemini'|'ollama'|'custom', model?, command? }   the user's own AI CLI
+       { kind: 'api', provider: 'anthropic'|'openai', model?, baseUrl? }                    a key in keys.json/env
+       { kind: '7ots' }                                   the home's /chat (7ots.com or own server)
+       { kind: 'batuta', model? }                         Orquesta's Batuta
+voice  { kind: 'none'|'browser'|'apuchat'|'elevenlabs'|'grok'|'fish'|'openai', voiceId? }
+pet    { mode: 'ask'|'desktop'|'terminal'|'browser', annoy: 0..3, opaque?: true }
+       annoy: 0 silent · 1 rarely · 2 normal · 3 chatty (+ terminal bell)
+```
+Keys by name: ANTHROPIC_API_KEY, OPENAI_API_KEY, ORQUESTA_TOKEN, APUCHAT_VOICE_TOKEN, ELEVENLABS_API_KEY, XAI_API_KEY, FISH_API_KEY.
+
+# Pet
+
+- `desktop`: a small always-on-top window that walks along the bottom of the screen (Electron via npx, ~100 MB the first time).
+  Find it bottom-right; menu on right click or the tray icon (Show / Hide / Feed / Play / Sleep / Quit). Hide keeps it alive.
+- `terminal`: drawn in the current terminal, keys f feed · p play · s sleep/wake · q quit. Needs its own terminal: ask the user.
+- `browser`: a tab at http://127.0.0.1:7717/pet.
+- `auto`: desktop if there is a screen, else terminal.
+- `--detach`: return immediately (always from agents). The daemon keeps running until `7ots stop`.
+- tmux: `7ots pet --tmux` opens the terminal pet in a side pane (`--compact` for a narrow one); for the status bar add
+  `set -g status-right "#(7ots status --line)"` to ~/.tmux.conf.
+- Needs: food, energy and fun decay with time (time away counts at most 8 h); it gains XP and levels from passing
+  commands and finished agent turns.
+
+Troubleshooting:
+- A grey/black box behind the pet (Linux without a compositor, some GPUs): `7ots pet --opaque` (or `"pet": {"opaque": true}` in config.json).
+- Can't see it: look at the tray icon, or `7ots stop && 7ots pet --mode desktop` (it comes back bottom-right).
+- Electron can't start (no display, headless, WSL): it falls back to the browser tab; or use `--mode terminal`.
+- Port busy: `SEVENOTS_PET_PORT=7720`.
+
+# Hooks
+
+- `hooks install --claude`: Claude Code hooks in `.claude/settings.local.json` of this project (`--global`: ~/.claude/settings.json).
+  The pet hears tool calls, errors and finished turns (`7ots event --from claude`, reads the hook JSON on stdin; never fails).
+- `hooks install --shell`: bash/zsh hook in ~/.bashrc / ~/.zshrc: the pet hears commands and exit codes (secrets are redacted).
+- `hooks remove` undoes both. Without a running pet the events still change its state silently.
+
+# Website (widget)
+
+`npx -y @7ots/cli install` detects the project:
+- plain HTML (index.html in ., public/, src/, static/, www/, site/) → inserts the widget before </body> between
+  `<!-- 7ots -->` markers (idempotent: re-running replaces the block);
+- a framework (Next, Nuxt, Astro, SvelteKit, Remix, Gatsby, Vite, Django, Rails, Laravel, Hugo, Jekyll…) → prints the snippet and
+  which file to paste it in (root layout/template, before </body>);
+- not a website → says so and suggests the pet, meet or hosting;
+- `--target print` only prints the snippet; `--target self` prepares the identity for the user's own server.
+
+Snippet for an ot hosted on 7ots.com (simplest; allowed domains are set in the dashboard):
+```html
+<script src="https://7ots.com/api/o/<id>/embed.js" defer></script>
+```
+Snippet with your own proxy:
+```html
+<script src="https://cdn.jsdelivr.net/npm/@7ots/cli/dist/7ots.iife.js" defer></script>
+<script>
+  addEventListener('DOMContentLoaded', () => SevenOts.init({ endpoint: '/api/agent', identity: true }));
+</script>
+```
+Declarative: `<ots-agent endpoint="/api/agent" site-key="pk_x" name="Ana"></ots-agent>`. ES module: `import { init } from '@7ots/cli'`.
+
+`SevenOts.init(options)`:
+| Option | Meaning |
+|---|---|
+| `endpoint` | Proxy URL (`/api/agent`, `https://7ots.com/api/o/<id>`, …). Required. |
+| `siteKey` | Public site id the proxy may require (`SITE_KEYS`). |
+| `identity` | `true` (ask the endpoint), a URL, or an inline identity object (public fields only). |
+| `agent` | `{ name, role, siteName, language, instructions, expressive }`. |
+| `avatar` | `{ url, body: 'F'\|'M', mood, cameraView }` (3D, needs an importmap for three) or `false`; default is the 2D character. |
+| `voice` | `{ tts: 'proxy'\|'browser'\|false, stt: true, lang }` or `false`. |
+| `auth` | `{ token }`, `{ getToken, getUser }` or `{ credentials: 'include' }`; `exposeClaims`. |
+| `mcp` | `[{ url, name, requiresAuth, filter, confirm }]` MCP servers (Streamable HTTP). |
+| `actions` | Custom tools `[{ name, description, parameters, handler, confirm }]`. |
+| `templates` | `{ name: (data, { escape }) => html }` for show_modal / open_sidebar. |
+| `navigation` | `{ allowedOrigins, router }` (`router` for SPAs). |
+| `proactive` | `{ level: 'quiet'\|'normal'\|'bold', greetDelayMs, dwellMs, idleMs, cooldownMs, maxPerSession, … }` or `false`. |
+| `context` | `{ privateSelectors, ignoreSelectors, extra: () => ({...}) }` — what it may read on the page. |
+| `contact` | `{ apuchat: true, apumail: true \| { categories } }` or `false` — hand off to a human. |
+| `builtins` | `{ exclude: ['click', …], confirmClicks: 'submit'\|'all'\|'none' }`. |
+| `pointer` | `{ speed, visible }` or `false` — the virtual mouse/keyboard. |
+| `pageTools` | `true` (default): forms/buttons with `data-ots-tool` become tools. |
+| `mode` / `companion` | `'panel'` (default) or `'companion'` (the avatar walks the page); `{ size, idleHomeMs, follow, wanderMs, watchCursor }`. |
+| `theme` | `{ primary, radius, position: 'right'\|'left', font }`. |
+
+HTML tools without JS: `<form data-ots-tool="invite_member" data-ots-description="…" data-ots-confirm="Invite {email}?" data-ots-auth>`
+(named fields become parameters). Runtime API: `agent.ask(text)`, `say`, `notify`, `registerAction`, `registerMcp`,
+`setAuthToken`, `setIdentity`, `setProactivity`, `open/close/reset/destroy`, `on(event, fn)`.
+
+# Own server (`npx -y @7ots/cli server`, or `node server/server.mjs` from the repo)
+
+Reads env vars / `.env`. Keys live only here. Admin UI at /backoffice/ (localhost only unless ADMIN_PASSWORD).
+- Core: PORT (8787), ALLOWED_ORIGINS (comma list), SITE_KEYS, RATE_LIMIT_PER_MIN (40), TRUST_PROXY, SERVER_INSTRUCTIONS, LOCALE (es|en|pt), LOG_LEVEL.
+- LLM: LLM_PROVIDER (anthropic | openai | mock), ANTHROPIC_API_KEY, OPENAI_API_KEY, LLM_MODEL, LLM_BASE_URL (OpenAI-compatible:
+  DeepSeek, Groq, Ollama, OpenRouter…), LLM_EFFORT (low…max), LLM_MAX_TOKENS, LLM_FALLBACKS (on|off).
+- Voice (TTS): TTS_PROVIDER (apuchat | elevenlabs | grok | fish | openai | none = browser voice; empty = first with a key);
+  APUCHAT_VOICE_URL, APUCHAT_VOICE_TOKEN, APUCHAT_VOICE_ID, APUCHAT_VOICE_PROVIDER; ELEVENLABS_API_KEY, ELEVENLABS_VOICE_ID,
+  ELEVENLABS_MODEL; XAI_API_KEY, XAI_TTS_VOICE; FISH_API_KEY, FISH_VOICE_ID, FISH_MODEL; OPENAI_TTS_MODEL, OPENAI_TTS_VOICE.
+- Email tickets (apumail): APUMAIL_API, APUMAIL_INBOX, APUMAIL_INBOX_TOKEN, APUMAIL_TO.
+- Human handoff (apuchat): APUCHAT_HUB, APUCHAT_NOTIFIER_IDENTITY_KEY, APUCHAT_OPERATOR_HANDLE, APUCHAT_TRANSCRIBE.
+- Backoffice: ADMIN_PASSWORD, CONFIG_FILE, SECRETS_FILE, IDENTITY_FILE (default data/identity.json).
+- The agent outside the web: AGENT_NAME, AGENT_ROLE, AGENT_SITE_URL, AGENT_INSTRUCTIONS, AGENT_LANG; own mailbox APUMAIL_AGENT_INBOX,
+  APUMAIL_AGENT_TOKEN, APUMAIL_AGENT_WEBHOOK_SECRET, APUMAIL_AGENT_DAILY; own apuchat/meet identity APUCHAT_AGENT_IDENTITY_KEY,
+  APUCHAT_AGENT_AVATAR, APUCHAT_AGENT_SCENE, APUCHAT_AGENT_ALLOW, AGENT_MAX_CALLS, AGENT_CALL_MAX_MINUTES, AGENT_CALL_MAX_TURNS.
+- Demo: DEMO, SERVE_STATIC, DEMO_JWT_SECRET.
+- Platform (multi-tenant, what https://7ots.com runs): PLATFORM=true, PLATFORM_URL, PLATFORM_DB, PLATFORM_SECRET, PLATFORM_MAX_OTS,
+  PLATFORM_OTS_RATE_PER_MIN, PLATFORM_OTS_DAILY_LIMIT, PLATFORM_NEW_ACCOUNTS_PER_IP_DAY, PLATFORM_MAX_INFLIGHT,
+  PLATFORM_LLM_PROVIDER/API_KEY/BASE_URL/MODEL, PLATFORM_FREE_MESSAGES, PLATFORM_APUCHAT_VOICE_TOKEN, PLATFORM_FREE_TTS,
+  PLATFORM_MAIL_INBOX/TOKEN, NOTLOGIN_URL/CLIENT_ID/CLIENT_SECRET, PLATFORM_APUCHAT_IDENTITIES_PER_DAY (free apuchat
+  identities per account and day, default 5), ORQUESTA_URL (default https://getorquesta.com).
+Endpoints: POST /api/agent/chat, POST /api/agent/tts, GET /api/agent/identity, /api/agent/contact/*, /llms.txt.
+
+# Hosted on https://7ots.com (no server)
+
+- Sign in at https://7ots.com/app/, create an ot (`7ots install` also prints a link that opens this same identity there), set the allowed domains, copy the embed.
+- Each ot's public API: `https://7ots.com/api/o/<id>/` — embed.js, config, identity, identity.vcf, chat, tts, contact/apumail, contact/apuchat.
+  Point the CLI at it with `setup` → home "7ots" (brain "7ots" then uses its /chat).
+- Brain: the account's free monthly quota on the platform's AI, or the user's own key (BYOK) set in the ot's settings.
+  Same for voice. Keys are encrypted and never shown again. Per-ot daily and per-minute limits apply.
+- Settings per ot in /backoffice/?ots=<id>: instructions, LLM/voice keys, apumail/apuchat channels.
+- apuchat tab of an ot: a free @handle (expires after 24h without activity, e.g. while the ot is paused), made permanent
+  by paying once by card on apuchat; connect your apuchat account to keep paid identities under it, or paste an identity key you own.
+- Orquesta tab of an ot: connect Orquesta (OAuth or an oak_ key), pick a project, enable tasks. Then the ot can start Orquesta
+  tasks (run_task, task_status) only for its owner in the dashboard ("Ask your ot to do something") and for apuchat DMs /
+  apumail emails from senders on the ot's allowlist — never from the public chat (/api/o/<id>/chat). Daily cap per ot (default 20).
 
 # Recipes for coding agents
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7ots/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "7ots.com — open-source embeddable web agent: it sees the page, speaks and acts for your visitor. Web Component + self-hosted Node proxy, Claude/OpenAI, 2D/3D avatar with voice, i18n, backoffice — plus a CLI with reproducible identities, a desktop pet and apuchat meet.",
   "homepage": "https://7ots.com",
   "repository": {

package/server/channels/apuchat.mjs

@@ -55,9 +55,10 @@ export function apuchatConfigured(cfg = apuchatConfigFromEnv()) {
 }
 
 /**
- * @param {{ agent: ReturnType<import('./agent.mjs').createServerAgent>, persona: Function, log: Function, config?: object }} deps
+ * @param {{ agent: ReturnType<import('./agent.mjs').createServerAgent>, persona: Function, log: Function, config?: object, tools?: Function }} deps
+ *   tools: extra tools for a DM, decided by sender ({ channel:'dm', from } → { tools, run } | null)
  */
-export function createApuchatChannel({ agent, persona, log, config = apuchatConfigFromEnv() }) {
+export function createApuchatChannel({ agent, persona, log, config = apuchatConfigFromEnv(), tools: extraTools = null }) {
   const cfg = { ...apuchatConfigFromEnv({}), ...config };
   const key = cfg.identityKey;
   const hub = String(cfg.hub).replace(/\/$/, '');
@@ -169,11 +170,13 @@ export function createApuchatChannel({ agent, persona, log, config = apuchatConf
     }
     if (backlog && age > BACKLOG_MAX_AGE_MS) return;
     if (!allowed(from)) return;
+    const extra = extraTools?.({ channel: 'dm', from }) || null;
     const reply = await agent.respond(`dm:${from}`, 'dm', text, {
-      tools: [ringTool],
+      tools: [ringTool, ...(extra?.tools || [])],
       run: async (name, args) => {
-        if (name !== 'llamar_por_apuchat') throw new Error(`Herramienta desconocida: ${name}`);
-        return ring(from, args.motivo);
+        if (name === 'llamar_por_apuchat') return ring(from, args.motivo);
+        if (extra?.tools.some((x) => x.name === name)) return extra.run(name, args);
+        throw new Error(`Herramienta desconocida: ${name}`);
       },
     });
     if (reply) await dm(from, reply);

package/server/channels/apumail.mjs

@@ -43,9 +43,10 @@ export function apumailConfigured(cfg = apumailConfigFromEnv()) {
 }
 
 /**
- * @param {{ agent: ReturnType<import('./agent.mjs').createServerAgent>, log: Function, config?: object }} deps
+ * @param {{ agent: ReturnType<import('./agent.mjs').createServerAgent>, log: Function, config?: object, tools?: Function }} deps
+ *   tools: extra tools for a mail, decided by sender ({ channel:'email', from, verified } → { tools, run } | null)
  */
-export function createApumailChannel({ agent, log, config = apumailConfigFromEnv() }) {
+export function createApumailChannel({ agent, log, config = apumailConfigFromEnv(), tools = null }) {
   const cfg = { ...apumailConfigFromEnv({}), ...config };
   const inbox = String(cfg.inbox || '').toLowerCase();
   const token = cfg.token;
@@ -87,7 +88,8 @@ export function createApumailChannel({ agent, log, config = apumailConfigFromEnv
     }
     const subject = String(mail.subject || '').slice(0, 200);
     const body = (mail.text || stripHtml(mail.html) || '').split('\n').filter((l) => !l.startsWith('>')).join('\n').trim().slice(0, 6000);
-    const reply = await agent.respond(`mail:${from}`, 'email', `Asunto: ${subject || '(sin asunto)'}\n\n${body || '(vacío)'}`);
+    const extra = tools?.({ channel: 'email', from, verified: senderVerified(mail) }) || null;
+    const reply = await agent.respond(`mail:${from}`, 'email', `Asunto: ${subject || '(sin asunto)'}\n\n${body || '(vacío)'}`, extra || {});
     if (!reply) return;
     const res = await fetch(`${base}/send`, {
       method: 'POST',
@@ -175,6 +177,14 @@ export function emailOf(from) {
   return (s.match(/<([^>]+)>/)?.[1] || s).trim().toLowerCase();
 }
 
+/**
+ * Did apumail verify the sender (DMARC pass for the From domain)? Only a structured verdict from
+ * apumail counts; headers inside the mail can be written by whoever sent it.
+ */
+export function senderVerified(mail) {
+  return mail?.auth?.dmarc === 'pass';
+}
+
 /** Correos que nunca se contestan: propios, automáticos, rebotes, listas. */
 export function skipReason(mail, from, inbox) {
   if (!/^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/.test(from)) return 'remitente inválido';

package/server/channels/index.mjs

@@ -18,14 +18,16 @@ import { apuchatConfigFromEnv, apuchatConfigured, createApuchatChannel } from '.
  * @param {() => string} [deps.instructions] instrucciones fijas del servidor (defecto: SERVER_INSTRUCTIONS)
  * @param {{ apumail?: object|false, apuchat?: object|false }} [deps.config]  por defecto, el entorno
  * @param {Function} [deps.log]
+ * @param {(ctx: { channel: 'dm'|'email', from: string, verified?: boolean }) => ({ tools: object[], run: Function }|null)} [deps.tools]
+ *   extra server tools for one conversation (DMs and mails, never voice calls), decided per sender
  */
-export function startAgentChannels({ llm, brain, identity = getIdentity, instructions, config = {}, log = (...a) => console.log('[7ots]', ...a) }) {
+export function startAgentChannels({ llm, brain, identity = getIdentity, instructions, config = {}, log = (...a) => console.log('[7ots]', ...a), tools = null }) {
   const agent = createServerAgent({ llm, brain, identity, instructions });
   const persona = () => personaOf(identity);
   const mailCfg = config.apumail === false ? null : { ...apumailConfigFromEnv(), ...(config.apumail || {}) };
   const chatCfg = config.apuchat === false ? null : { ...apuchatConfigFromEnv(), ...(config.apuchat || {}) };
-  const apumail = mailCfg && apumailConfigured(mailCfg) ? createApumailChannel({ agent, log, config: mailCfg }) : null;
-  const apuchat = chatCfg && apuchatConfigured(chatCfg) ? createApuchatChannel({ agent, persona, log, config: chatCfg }) : null;
+  const apumail = mailCfg && apumailConfigured(mailCfg) ? createApumailChannel({ agent, log, config: mailCfg, tools }) : null;
+  const apuchat = chatCfg && apuchatConfigured(chatCfg) ? createApuchatChannel({ agent, persona, log, config: chatCfg, tools }) : null;
   apumail?.start();
   apuchat?.start();
 

package/server/platform/apuchat.mjs

@@ -0,0 +1,266 @@
+/**
+ * apuchat for the platform: an apuchat identity (@callsign) for each ot, made from the dashboard.
+ *
+ * Every 7ots account can hold two apuchat accounts (sealed in `integrations`, kind 'apuchat'):
+ *   managed  an anonymous apuchat account the platform creates on first use (no sign-up): it owns the
+ *            identities made for the user's ots. Its session lasts 90 days; when it is refused, the
+ *            recovery token gets a new one (and if even that fails, a new anonymous account is made).
+ *   linked   the user's own apuchat account, connected with apuchat's /link flow (app "7ots"): new
+ *            identities go there and the ot's identity can be claimed into it.
+ *
+ * Hub contract (APUCHAT_HUB, read once at boot; server to server only):
+ *   POST /api/account                        → { account_id, recovery_token, session_token }
+ *   POST /api/account/recover {recovery_token} → { session_token }
+ *   POST /api/account/identities              Bearer session|apt_ → { callsign, identity_key, free_identity, … }
+ *   DELETE /api/account/identities/:callsign
+ *   GET  /api/identities/mint/quote?callsign= Bearer → { valid, taken, reason, tier, tier_label, price_usd, … }
+ *   POST /api/identities/mint/checkout { callsign, return_url } → { checkout_id, url, price_usd, tier }
+ *   GET  /api/identities/mint/checkout/:id    → { status, callsign, upgraded, identity_key? }
+ *   POST /api/v1/link/exchange { code, app }  → { account_id, identities, app_token (apt_, shown once), scopes, notice }
+ *   POST /api/account/identities/claim { identity_key }  Bearer apt_ → { ok, callsign, moved, paid }
+ *                                             (409 *_not_transferable when it is paid/verified elsewhere)
+ * apt_ errors: 401 invalid_app_token (the link is forgotten) · 403 insufficient_scope. Paying needs
+ * Stripe on apuchat: 503 not_configured until then (we point to minting with USDC on apuchat instead).
+ * return_url must be on 7ots.com (or localhost:8787 in development); apuchat appends ?apuchat_checkout=<id>&status=….
+ *   GET  /api/dm/wait?timeout=1               X-Identity-Key → { callsign, … }  (checks a pasted key)
+ *
+ * Free identities expire after 24 h without DM activity; the ot's channel long-polls /api/dm/wait,
+ * which counts as activity, so they live while the ot is on.
+ */
+
+import { i18nError } from '../i18n.mjs';
+import { getIntegration, setIntegration } from './store.mjs';
+
+const penv = process.env;
+const HUB = (penv.APUCHAT_HUB || 'https://apuchat.com').replace(/\/+$/, '');
+const SESSION_REFRESH_MS = 80 * 24 * 3600_000; // sessions last 90 days: renew a bit before
+export const CALLSIGN_RE = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+const IDENTITIES_PER_DAY = () => Number(penv.PLATFORM_APUCHAT_IDENTITIES_PER_DAY || 5);
+
+export const apuchatHub = () => HUB;
+
+async function hub(method, path, { bearer, identityKey, body, timeoutMs = 15000 } = {}) {
+  let res;
+  try {
+    res = await fetch(HUB + path, {
+      method,
+      headers: {
+        Accept: 'application/json',
+        ...(body ? { 'Content-Type': 'application/json' } : {}),
+        ...(bearer ? { Authorization: `Bearer ${bearer}` } : {}),
+        ...(identityKey ? { 'X-Identity-Key': identityKey } : {}),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+      redirect: 'manual',
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch {
+    throw i18nError(424, 'platform.apuchat.unreachable');
+  }
+  let data = null;
+  try {
+    data = await res.json();
+  } catch {}
+  return { ok: res.ok, status: res.status, data: data || {} };
+}
+
+/** Upstream error → our error (the hub's own text is never shown; its code helps a few cases). */
+function hubError(r) {
+  const code = String(r.data.code || r.data.error || '');
+  if (r.status === 503 && /not_configured/.test(code)) return i18nError(501, 'platform.apuchat.paymentsOff', { url: `${HUB}/account/mint` });
+  if (r.status === 429) return i18nError(429, 'platform.apuchat.hubBusy');
+  if (r.status === 403 && /insufficient_scope/.test(code)) return i18nError(403, 'platform.apuchat.insufficientScope');
+  if (r.status === 409 && /not_transferable/.test(code)) return i18nError(409, 'platform.apuchat.notTransferable');
+  if (r.status === 409) return i18nError(409, 'platform.apuchat.taken');
+  return i18nError(424, 'platform.apuchat.failed', { status: r.status });
+}
+
+// ───────────────────────────── account state ─────────────────────────────
+
+const state = (accountId) => getIntegration(accountId, 'apuchat') || {};
+const saveState = (accountId, s) => setIntegration(accountId, 'apuchat', s.managed || s.linked || s.checkouts?.length ? s : null);
+const locks = new Map(); // accountId → Promise (one session refresh / account creation at a time)
+
+function locked(accountId, fn) {
+  const prev = locks.get(accountId) || Promise.resolve();
+  const run = prev.catch(() => {}).then(fn);
+  const tail = run.catch(() => {});
+  locks.set(accountId, tail);
+  tail.then(() => locks.get(accountId) === tail && locks.delete(accountId));
+  return run;
+}
+
+/** Public view for the dashboard (never tokens). */
+export function apuchatAccountView(accountId) {
+  const s = state(accountId);
+  return { managed: !!s.managed, linked: s.linked ? { accountId: s.linked.account_id || '', canClaim: can(s.linked, 'identities:write') } : null };
+}
+
+/** Whether the app token of the link was granted a scope (older links without a scope list: assume yes). */
+const can = (linked, scope) => !!linked?.app_token && (!Array.isArray(linked.scopes) || linked.scopes.includes(scope));
+
+async function createManaged(accountId) {
+  const r = await hub('POST', '/api/account', { body: {} });
+  if (!r.ok || !r.data.session_token || !r.data.recovery_token) throw hubError(r);
+  const s = state(accountId);
+  s.managed = { account_id: r.data.account_id, recovery_token: r.data.recovery_token, session_token: r.data.session_token, at: Date.now() };
+  saveState(accountId, s);
+  return s.managed.session_token;
+}
+
+/** Gets a fresh session with the recovery token; if apuchat no longer knows it, starts a new anonymous account. */
+async function recoverManaged(accountId) {
+  const s = state(accountId);
+  if (!s.managed?.recovery_token) return createManaged(accountId);
+  const r = await hub('POST', '/api/account/recover', { body: { recovery_token: s.managed.recovery_token } });
+  if (r.ok && r.data.session_token) {
+    s.managed = { ...s.managed, session_token: r.data.session_token, at: Date.now() };
+    saveState(accountId, s);
+    return s.managed.session_token;
+  }
+  if (r.status === 401 || r.status === 403 || r.status === 404) {
+    console.warn('[7ots] apuchat: recovery refused, new anonymous account for', accountId);
+    return createManaged(accountId);
+  }
+  throw hubError(r);
+}
+
+/** Session of the managed account (made on first use, renewed when old). */
+function managedSession(accountId, { create = true } = {}) {
+  return locked(accountId, async () => {
+    const m = state(accountId).managed;
+    if (!m) {
+      if (!create) return null;
+      return createManaged(accountId);
+    }
+    if (Date.now() - (m.at || 0) > SESSION_REFRESH_MS) return recoverManaged(accountId);
+    return m.session_token;
+  });
+}
+
+/**
+ * A call as one of the account's apuchat accounts. 'managed' renews its session once on 401;
+ * 'linked' uses the app token (a 401 means the user revoked it: the link is forgotten).
+ */
+async function as(accountId, owner, method, path, o = {}) {
+  if (owner === 'linked') {
+    const l = state(accountId).linked;
+    if (!l?.app_token) throw i18nError(409, 'platform.apuchat.notLinked');
+    const r = await hub(method, path, { ...o, bearer: l.app_token });
+    if (r.status === 401) {
+      const s = state(accountId);
+      delete s.linked;
+      saveState(accountId, s);
+      throw i18nError(409, 'platform.apuchat.linkExpired');
+    }
+    return r;
+  }
+  let token = await managedSession(accountId);
+  let r = await hub(method, path, { ...o, bearer: token });
+  if (r.status === 401) {
+    token = await locked(accountId, () => recoverManaged(accountId));
+    r = await hub(method, path, { ...o, bearer: token });
+  }
+  return r;
+}
+
+/** Which apuchat account new identities go to: the user's own when linked with a token, else the managed one. */
+export const defaultOwner = (accountId, scope = 'identities:write') => (can(state(accountId).linked, scope) ? 'linked' : 'managed');
+
+// ───────────────────────────── identities ─────────────────────────────
+
+const madeToday = new Map(); // accountId → timestamps (free identities made in the last day)
+
+/** A new free identity. Limited per account and day (each one is a handle taken on apuchat). */
+export async function createFreeIdentity(accountId) {
+  const now = Date.now();
+  const recent = (madeToday.get(accountId) || []).filter((t) => now - t < 86400_000);
+  if (recent.length >= IDENTITIES_PER_DAY()) throw i18nError(429, 'platform.apuchat.tooManyIdentities', { max: IDENTITIES_PER_DAY() });
+  const owner = defaultOwner(accountId);
+  const r = await as(accountId, owner, 'POST', '/api/account/identities', { body: {} });
+  if (!r.ok || !r.data.identity_key || !r.data.callsign) throw hubError(r);
+  recent.push(now);
+  madeToday.set(accountId, recent);
+  if (madeToday.size > 5000) madeToday.clear();
+  return { callsign: String(r.data.callsign).toLowerCase(), identityKey: r.data.identity_key, free: r.data.free_identity !== false, owner };
+}
+
+/** Deletes an identity on apuchat (only the free ones the platform made; best effort). */
+export async function deleteIdentity(accountId, owner, callsign) {
+  if (!CALLSIGN_RE.test(callsign || '') || (owner !== 'managed' && owner !== 'linked')) return false;
+  const r = await as(accountId, owner, 'DELETE', `/api/account/identities/${encodeURIComponent(callsign)}`).catch(() => null);
+  return !!r?.ok;
+}
+
+/** The @callsign of an identity key, or null if apuchat does not accept it. */
+export async function callsignOf(identityKey) {
+  const r = await hub('GET', '/api/dm/wait?timeout=1', { identityKey, timeoutMs: 20000 });
+  if (r.status === 401 || r.status === 403 || r.status === 404) return null;
+  if (!r.ok) throw hubError(r);
+  return r.data.callsign ? String(r.data.callsign).toLowerCase() : null;
+}
+
+// ───────────────────────────── permanent handle (paid) ─────────────────────────────
+
+export async function quote(accountId, owner, callsign) {
+  const r = await as(accountId, owner, 'GET', `/api/identities/mint/quote?callsign=${encodeURIComponent(callsign)}`);
+  if (!r.ok) throw hubError(r);
+  const q = r.data;
+  return { callsign, valid: !!q.valid, taken: !!q.taken, reason: q.reason || null, tier: q.tier || null, tierLabel: q.tier_label || null, priceUsd: q.price_usd ?? null };
+}
+
+/** Starts a card checkout; the checkout is remembered so only this ot can read its result. */
+export async function checkout(accountId, owner, { otsId, callsign, returnUrl }) {
+  const r = await as(accountId, owner, 'POST', '/api/identities/mint/checkout', { body: { callsign, return_url: returnUrl } });
+  if (!r.ok || !r.data.checkout_id || !r.data.url) throw hubError(r);
+  const s = state(accountId);
+  s.checkouts = [{ id: String(r.data.checkout_id), otsId, callsign, owner, at: Date.now() }, ...(s.checkouts || []).filter((c) => Date.now() - c.at < 7 * 86400_000)].slice(0, 20);
+  saveState(accountId, s);
+  return { checkoutId: String(r.data.checkout_id), url: String(r.data.url), priceUsd: r.data.price_usd ?? null, tier: r.data.tier || null };
+}
+
+export const pendingCheckouts = (accountId, otsId) => (state(accountId).checkouts || []).filter((c) => c.otsId === otsId).map(({ id, callsign, at }) => ({ id, callsign, at }));
+
+/** Status of a checkout started for this ot (null if it isn't one of its own). Fulfilled/failed ones are forgotten. */
+export async function checkoutStatus(accountId, otsId, id) {
+  const c = (state(accountId).checkouts || []).find((x) => x.id === String(id) && x.otsId === otsId);
+  if (!c) return null;
+  const r = await as(accountId, c.owner, 'GET', `/api/identities/mint/checkout/${encodeURIComponent(c.id)}`);
+  if (!r.ok) throw hubError(r);
+  const status = ['pending', 'fulfilled', 'failed'].includes(r.data.status) ? r.data.status : 'pending';
+  if (status !== 'pending') {
+    const s = state(accountId);
+    s.checkouts = (s.checkouts || []).filter((x) => x.id !== c.id);
+    saveState(accountId, s);
+  }
+  return { status, callsign: String(r.data.callsign || c.callsign).toLowerCase(), upgraded: !!r.data.upgraded, identityKey: r.data.identity_key || null, owner: c.owner };
+}
+
+// ───────────────────────────── linking the user's apuchat account ─────────────────────────────
+
+/** Where to send the browser to link (apuchat appends `code`; it doesn't echo `state`, so it rides in the return URL). */
+export const linkUrl = (returnUrl) => `${HUB}/link?${new URLSearchParams({ app: '7ots', return: returnUrl })}`;
+
+export async function exchangeLink(accountId, code) {
+  const r = await hub('POST', '/api/v1/link/exchange', { body: { code, app: '7ots' } });
+  if (!r.ok || !r.data.account_id) throw hubError(r);
+  const s = state(accountId);
+  const scopes = Array.isArray(r.data.scopes) ? r.data.scopes.map(String) : typeof r.data.scopes === 'string' ? r.data.scopes.split(/[\s,]+/).filter(Boolean) : null;
+  // The app token is shown once: it lives only sealed in the database and is never logged.
+  s.linked = { account_id: String(r.data.account_id), app_token: r.data.app_token || '', scopes, at: Date.now() };
+  saveState(accountId, s);
+  return { accountId: s.linked.account_id, canClaim: can(s.linked, 'identities:write') };
+}
+
+export function unlink(accountId) {
+  const s = state(accountId);
+  delete s.linked;
+  saveState(accountId, s);
+}
+
+/** Moves an identity (by its key) into the linked account. */
+export async function claimIdentity(accountId, identityKey) {
+  const r = await as(accountId, 'linked', 'POST', '/api/account/identities/claim', { body: { identity_key: identityKey } });
+  if (!r.ok) throw hubError(r);
+  return { callsign: r.data.callsign ? String(r.data.callsign).toLowerCase() : null, moved: r.data.moved !== false, paid: !!r.data.paid };
+}