@glyphteck/veyl 0.2.0 → 0.3.0

package/docs/agents.md

@@ -0,0 +1,235 @@
+# Agent Guide
+
+Read this file first when operating Veyl from an agent, worker, terminal daemon, or script.
+
+## Shape
+
+- Package: `@glyphteck/veyl`.
+- Runtime: Bun.
+- Core interface: JavaScript API from `import { open } from '@glyphteck/veyl'`.
+- Human shell interface: `veyl ...`.
+- MCP interface: `veyl mcp serve`, a local stdio server started by the MCP host.
+- CLI paths, CLI help, MCP schemas, MCP dispatch, and the exported command inventory come from `src/commands.js`.
+- Hosted remote MCP: none. Veyl does not run an MCP endpoint on Vercel.
+- Best default for agents: use the JS API for long-running sessions. Use CLI for one-off shell commands. Use MCP only when the agent host already speaks MCP tools.
+
+Headless is a client, not a backend bypass. Auth, vault decrypt, wallet signing, and chat encryption happen locally. Machine-created accounts are public `bot` profiles. Passkey-created CLI accounts are normal human accounts.
+
+## Install
+
+```bash
+bun add @glyphteck/veyl
+```
+
+One-off:
+
+```bash
+bunx @glyphteck/veyl help
+```
+
+## Local State
+
+Profiles live in `~/.veyl`, or `VEYL_HOME`.
+
+Important env:
+
+```bash
+VEYL_HOME=/secure/veyl-home
+VEYL_PROFILE=runner
+VEYL_NETWORK=REGTEST
+VEYL_VAULT_SECRET=...
+VEYL_WEB_URL=https://veyl.glyphteck.com
+```
+
+Use `REGTEST` for dev/smoke accounts and `MAINNET` for real funds.
+
+## Create Account
+
+Machine account:
+
+```js
+import { open } from '@glyphteck/veyl';
+
+const veyl = await open({ profile: 'runner', network: 'REGTEST' });
+await veyl.account.create({ username: 'runner', saveCredential: true });
+await veyl.vault.create({ saveSecret: true });
+```
+
+Passkey account from CLI:
+
+```bash
+veyl --network REGTEST create --passkey @runner
+veyl --network REGTEST vault create
+```
+
+The passkey flow opens a browser URL. After WebAuthn succeeds, the CLI stores a local machine credential for later CLI sessions.
+
+## Start Session
+
+```js
+const veyl = await open({ profile: 'runner', network: 'REGTEST' });
+await veyl.account.login();
+await veyl.vault.unlock();
+```
+
+Most chat and money methods auto-unlock if a vault secret is saved or available in `VEYL_VAULT_SECRET`, but long-running agents should login and unlock once.
+
+Lock when done:
+
+```js
+await veyl.vault.lock();
+```
+
+## Message Loop
+
+```js
+await veyl.listen({
+  agent: true,
+  interval: 3000,
+  replay: false,
+  onEvent: async (event) => {
+    if (event.type !== 'message') return;
+    if (event.message.type === 'txt') {
+      await veyl.chat.reply(event, `received: ${event.message.text}`);
+      await veyl.chat.reactTo(event, '+1');
+    }
+    if (event.message.type === 'req') {
+      await veyl.money.pay(event.message.requestId);
+    }
+  },
+});
+```
+
+`agent: true` means compact incoming-only message events. It avoids rereading chats after every event.
+
+Compact ready event:
+
+```js
+{ type: 'ready', ts, account: { uid, username, network, auth, bot, unlocked } }
+```
+
+Compact message event:
+
+```js
+{
+  type: 'message',
+  ts,
+  peer: '@alice',
+  replyTo: { peer: '@alice', messageId: 'abc123' },
+  reactTo: { peer: '@alice', messageId: 'abc123' },
+  chat: { id, peer, username, peerChatPK, peerUid, unseen, ts },
+  message: {
+    id, cid, chatId, from, type, ts, peerChatPK,
+    text, amountSats, paid, requestId, replyId
+  }
+}
+```
+
+Transaction event:
+
+```js
+{ type: 'transaction', ts, transaction }
+```
+
+Error event:
+
+```js
+{ type: 'error', ts, peer, message }
+```
+
+## Chat Methods
+
+Peers may be `@username`, chat public keys, wallet public keys, or a listen event target.
+
+```js
+await veyl.chat.list({ count: 20 });
+await veyl.chat.read('@alice', { count: 30, markRead: true });
+await veyl.chat.send('@alice', 'hello');
+await veyl.chat.reply(event, 'reply text');
+await veyl.chat.reply({ peer: '@alice', messageId: 'abc123' }, 'reply text');
+await veyl.chat.reactTo(event, '+1');
+await veyl.chat.react('@alice', 'abc123', '+1');
+await veyl.chat.unreact('@alice', 'abc123');
+await veyl.chat.save('@alice', 'abc123');
+await veyl.chat.unsave('@alice', 'abc123');
+await veyl.chat.delete('@alice', 'abc123');
+await veyl.chat.deleteChat('@alice', { cleanup: true });
+await veyl.chat.retention('@alice', 'seen'); // or '24h'
+```
+
+Use `reply(event, ...)` and `reactTo(event, ...)` inside listeners. They use the event's embedded peer/message target and avoid another lookup.
+
+## Money Methods
+
+Amounts are sats.
+
+```js
+await veyl.money.balance();
+await veyl.money.receive();
+await veyl.money.claim({ count: 100 });
+await veyl.money.transactions({ count: 50, offset: 0 });
+
+await veyl.money.send('@alice', 1000);
+const req = await veyl.money.request('@alice', 1000);
+await veyl.money.pay(req.message.requestId);
+
+await veyl.money.invoice(1000, { memo: 'coffee' });
+await veyl.money.payInvoice(invoice, { type: 'lightning', maxFeeSats: 20 });
+await veyl.money.lightningQuote(invoice, { amountSats: 1000 });
+await veyl.money.lightningPay(invoice, { amountSats: 1000, maxFeeSats: 20 });
+await veyl.money.lightningReceive(id);
+await veyl.money.lightningSend(id);
+
+await veyl.money.withdrawQuote(address, 10000);
+await veyl.money.withdrawPrepare(address, 10000, { speed: 'MEDIUM' });
+await veyl.money.withdraw(address, 10000, { speed: 'MEDIUM' });
+```
+
+## CLI Cheat Sheet
+
+```bash
+veyl create @runner
+veyl create --passkey @runner
+veyl login [@runner]
+veyl vault create
+veyl unlock
+veyl balance
+veyl receive
+veyl claim
+veyl say @alice "hello"
+veyl reply @alice <message-id> "got it"
+veyl react @alice <message-id> +1
+veyl send @alice 1000
+veyl request @alice 1000
+veyl pay <request-id>
+veyl transactions
+veyl listen --agent
+veyl mcp serve
+```
+
+CLI results are JSON. `veyl listen` emits newline-delimited JSON events.
+
+## MCP
+
+Run locally:
+
+```bash
+veyl mcp serve
+```
+
+The MCP host starts that command, sends JSON-RPC over stdin, and reads JSON-RPC over stdout. Users host it themselves by running the package on their own machine or worker. Veyl does not expose a remote MCP URL.
+
+Use MCP when the agent host prefers tools. Use the JS API when you control the runtime loop.
+
+## Docs
+
+- Full JS API: `docs/api.md`
+- CLI: `docs/cli.md`
+- MCP: `docs/mcp.md`
+
+## Limits
+
+- `listen` is polling-based. There is no backend wake-ping contract yet.
+- Headless sends text chat and payment requests. Media summaries may appear in reads, but public media upload helpers are not exposed yet.
+- Machine-created headless accounts are intentionally separate from passkey-created human accounts.
+- Passkey create/login needs a browser-capable environment.