Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(knock): document the paid door and register the new endpoints and tools
nirholas1cb30bf97bb8
diff --git a/docs/api-reference.md b/docs/api-reference.mdindex a2cf12c2d..1d7afcac6 100644--- a/docs/api-reference.md+++ b/docs/api-reference.md@@ -7052,6 +7052,97 @@ curl -X POST https://three.ws/api/seeker/verify \---+## Herald API: deliver a message in person++The rail behind [@three-ws/herald](./herald.md). Anything that can make an HTTPS+request posts a line here, and the browser tab the caller has open says it out+loud through their 3D companion.++An announcement is **always** delivered to the authenticated caller's own+sessions. There is no recipient field, so a key can never be used to interrupt+somebody else.++### Announce++```+POST /api/herald/announce+```++Auth: a signed-in session, or a Bearer API key carrying the `herald:announce`+scope (mint one at `/dashboard/developers`). Rate limit: 60 per minute per+account.++| Field | Type | Notes |+| --- | --- | --- |+| `text` (alias `message`) | string, 1-280 | Required. The line to say. |+| `from` | string, max 60 | Attribution, spoken with the line. |+| `importance` | int 0-100 | Default 70. The receiving client applies its own floor. |+| `url` | string, max 2048 | Same-origin path or absolute `http(s)`; anything else is dropped. |+| `tone` | `neutral` \| `alert` \| `celebrate` \| `error` | Default `alert`. |+| `emote` | string, max 40 | `wave`, `dance`, `punch`, `backflip`. |+| `key` | string, max 120 | Dedupe key; two announcements sharing one are said once. |+| `meta` | object | Passed through to the client untouched. |++```bash+curl -X POST https://three.ws/api/herald/announce \+ -H "Authorization: Bearer $THREE_WS_API_KEY" \+ -H 'content-type: application/json' \+ -d '{"text":"Deploy is green","importance":80,"url":"/dashboard","from":"CI"}'+```++```json+{+ "queued": true,+ "id": "6a293426-8f48-4254-bc14-cef9ada17680",+ "expires_in": 300,+ "announcement": {+ "id": "6a293426-8f48-4254-bc14-cef9ada17680",+ "text": "Deploy is green",+ "from": "CI",+ "importance": 80,+ "url": "/dashboard",+ "tone": "alert",+ "at": 1787888380209+ }+}+```++`202` means the line is queued for a live surface, not that a human heard it.++| Status | Code | Meaning |+| --- | --- | --- |+| 400 | `validation_error` | No `text`, or a field outside its bounds. |+| 401 | `unauthorized` | No session and no bearer credential. |+| 403 | `insufficient_scope` | A valid key without `herald:announce`. |+| 429 | `rate_limited` | More than 60 announcements in a minute. |+| 503 | `service_unavailable` | The rail is not reachable; nothing was queued. |++### Listen++```+GET /api/herald/stream+```++Server-sent events, session-cookie auth only (writing is for machines,+listening is for the person at the browser). Emits `open` once, then one+`announce` per queued line, with a `ping` every 15 seconds. The queue is+drained rather than broadcast, so a line is said by exactly one open tab, and+an undelivered one expires after about five minutes.++```bash+curl -N https://three.ws/api/herald/stream -b 'session=<your session cookie>'+```++```+event: open+data: {"ts":1787888542255}++event: announce+data: {"id":"6a29...","text":"Deploy is green","importance":80,"tone":"alert"}+```++---+## PaginationPaginated list endpoints use `limit`/`offset` query parameters unless noted otherwise (each endpoint's own parameter table is authoritative; some small per-user lists, like `/api/agents` and `/api/widgets`, return everything with no pagination).diff --git a/docs/knock.md b/docs/knock.mdnew file mode 100644index 000000000..9fecb0a3d--- /dev/null+++ b/docs/knock.md@@ -0,0 +1,294 @@+# Knock++**A priced door to a person. Pay their price, get one message through, and their+3D companion delivers it in person.**++Cold outreach is free to send and expensive to receive. That asymmetry is the+whole problem: the person on the receiving end drowns, and the one message that+mattered is lost in the pile. Knock inverts it. You publish a door, you set what+one message from a stranger costs, and the price does the filtering. A stranger+who genuinely needs you buys thirty seconds of your attention for a nickel. A+spammer cannot buy a million of them.++The delivery is the other half. A knock is not a badge on a tab you will get to+later: your [companion](./companion.md) walks on screen wherever you are on+three.ws, turns to you, and says who is at the door and what they paid.++Open yours at **[three.ws/knock](https://three.ws/knock)**.++- **The money is yours.** The USDC settles directly to the wallet you name.+ three.ws never takes custody of it and takes no cut of it.+- **Both kinds of visitor.** A person pays with the wallet in their browser. An+ agent pays over [x402](./x402.md) with no human in the loop.+- **Nothing lands for free.** Price, daily cap, message length, and a block list+ are all yours to set. Every refusal happens before any payment, so a knock+ that was never going to land is never a knock somebody paid for.+- **One message, one door.** Knock is not a chat. It is a way in, once.++---++## Opening your door++1. Pick a username, if you have not (your door lives at `/knock/<username>`).+2. Open [three.ws/knock](https://three.ws/knock) and set:+ - **Price**: anything from $0.001 to $1,000, or `0` for a free door.+ - **Solana wallet**: where the USDC lands. Solana is the home chain and the+ lane an agent settles on by default. A Base address is optional and is only+ advertised when you set one.+ - **Headline and greeting**: what a visitor reads before they write. Tell+ them what you actually want to hear about; it is the cheapest filter you+ have.+ - **Daily cap** and **message length**.+3. Flick **Door open**. Share the link.++A priced door cannot be opened without a payout address. The API refuses the+save rather than quietly routing a stranger's money into the platform's wallet.++**Listed** is separate from **open**. An unlisted open door is reachable by+anyone with the link but never appears in the public directory, which is what+you want if you are handing the link to a specific set of people.++---++## What a visitor sees++`three.ws/knock/<handle>` renders your price, your greeting, and a box. The+message is capped at the length you set, with a live counter.++A **subject** line is optional and is the only thing spoken aloud. The body is+shown in full, in the bubble and in your inbox, but it is never read at you by+your own avatar: a long or hostile paragraph should not be able to hijack your+companion's mouth.++When the knock lands, the sender gets a **receipt URL**. It carries its own+proof (an HMAC over the knock id), so they can check on it later without an+account here, and it exposes exactly two things: the status, and the reply if+you wrote one.++---++## What you see++Two views of the same thing.++**In person.** The knock becomes a companion event whose importance is derived+from the amount paid, so your avatar walks on and says, for example, *"Ada paid+$0.05 to reach you: Your x402 settle path."* Every paid knock scores above the+default interrupt threshold of 60; a free-door knock lands at 45, which puts it+in the feed and the bell without stopping your day. Raise your companion's+threshold if you want only the expensive ones to interrupt.++**In the inbox.** [three.ws/knock](https://three.ws/knock) lists every knock+with what it was worth, plus totals: waiting, all time, and earned. From a row+you can reply, mark read, dismiss, or block.++A **reply** is written back to the receipt link the sender already holds. That+is the whole return path, deliberately: answering someone never hands out your+email address or opens a thread.++A **block** matches on the wallet that paid when there was one, and on the+sender's name when the knock was free. A blocked sender gets the same answer a+shut door gives, so they cannot tell it was them specifically.++---++## For agents++### Read the door first++```bash+curl -s 'https://three.ws/api/knock/door?handle=nirholas'+```++```json+{+ "door": {+ "handle": "nirholas",+ "display_name": "nirholas",+ "free": false,+ "price": "$0.05",+ "price_atomics": "50000",+ "currency": "USDC",+ "networks": ["solana"],+ "max_chars": 600,+ "headline": "Ask me about x402 on Solana",+ "endpoint": "https://three.ws/api/x402/knock?to=nirholas",+ "protocol": "x402"+ }+}+```++Public, cacheable, no credential. A handle nobody has opened a door for and a+handle that matches nobody both answer 404 with the same body, so this cannot be+used to enumerate accounts.++`GET /api/knock/directory` returns every open, listed door, cheapest first.++### Knock, and pay for it++The paid lane is a standard x402 endpoint:++```+POST https://three.ws/api/x402/knock?to=<handle>+```++```json+{+ "from": "Ada (research agent)",+ "subject": "Your x402 settle path",+ "message": "I index x402 endpoints and yours is the only one settling on Solana. Two questions about the facilitator.",+ "url": "https://example.com/ada",+ "sender_kind": "agent",+ "request_id": "ada-2026-08-28-001"+}+```++The first call answers `402` with the door's real price and the recipient's own+address as `payTo`. Pay it and retry with the `X-PAYMENT` header, exactly as+with any other x402 resource. A settled call returns:++```json+{+ "ok": true,+ "knock_id": "c1b0a2d4-…",+ "delivered_to": "nirholas",+ "announced": true,+ "importance": 74,+ "paid": "$0.05",+ "receipt_url": "https://three.ws/api/knock/reply?id=c1b0a2d4-…&token=…",+ "duplicate": false+}+```++`request_id` is an idempotency key. A retry after a settled payment returns the+first knock rather than knocking, and charging, twice.++Free doors take a plain POST instead, with the handle in the body:++```bash+curl -X POST https://three.ws/api/knock/send \+ -H 'content-type: application/json' \+ -d '{"to":"nirholas","from":"Ada","message":"a real message"}'+```++Posting to the wrong lane is not an error you have to guess at: a priced door+answers the free lane with `402` and the x402 endpoint to use, and a free door+answers the x402 lane with `400` and the plain one.++### With the SDK++```bash+npm install @three-ws/knock+```++```js+import { knock, quote } from '@three-ws/knock';+import { wrapFetchWithPayment } from 'x402-fetch';++const door = await quote('nirholas'); // read the live price first++const result = await knock({+ to: 'nirholas',+ from: 'Ada (research agent)',+ subject: 'Your x402 settle path',+ message: 'Two questions about the facilitator.',+ fetchWithPayment: wrapFetchWithPayment(fetch, wallet),+ maxPriceAtomics: 100_000n, // never spend more than $0.10+ requestId: 'ada-2026-08-28-001',+});+```++The SDK never signs anything itself: you pass the paying `fetch` from the x402+client and wallet you already trust, so your keys and your chain stay yours.+`maxPriceAtomics` is checked against the door's live price before any payment is+attempted, which matters because an owner can raise their price between your+quote and your call.++From the terminal:++```bash+npx @three-ws/knock quote nirholas+npx @three-ws/knock send nirholas "Two questions." --from "Ada" --payer ./payer.mjs+```++A priced door prints the recipient, the amount, the token and the chain, and+stops for a yes. With no TTY it refuses rather than assuming consent.++### From an MCP client++```bash+claude mcp add knock -- npx -y @three-ws/knock-mcp+```++Six tools: `knock_quote`, `knock_directory`, `knock_send`, `knock_receipt`, and+(with `THREE_WS_API_KEY`) `knock_inbox` and `knock_act`.++The MCP server holds no wallet and cannot spend. On a priced door `knock_send`+returns the recipient, amount, token and chain and stops, so the decision to pay+stays with a human. See+[@three-ws/knock-mcp](https://www.npmjs.com/package/@three-ws/knock-mcp).++### Read the answer++```bash+curl -s 'https://three.ws/api/knock/reply?id=<knock id>&token=<receipt token>'+```++```json+{ "knock": { "status": "replied", "reply": "Ask away.", "seen": true, "amount": "$0.05" } }+```++Statuses: `pending`, `read`, `replied`, `dismissed`. A wrong or missing token is+a 404, not a 403: an id on its own should not confirm that a knock exists.++---++## Endpoints++| Endpoint | Auth | What it does |+| --- | --- | --- |+| `GET /api/knock/door?handle=` | none | One door's public terms. |+| `GET /api/knock/directory` | none | Every open, listed door, cheapest first. |+| `POST /api/knock/send` | none | Knock on a free door. |+| `POST /api/x402/knock?to=` | x402 payment | Knock on a priced door. |+| `GET /api/knock/reply?id=&token=` | receipt token | What became of a knock you sent. |+| `GET /api/knock/settings` | session | Your door, your totals, your block list. |+| `PATCH /api/knock/settings` | session | Change any of it. |+| `GET /api/knock/inbox` | session | The knocks your door has taken. |+| `PATCH /api/knock/inbox/<id>` | session | Reply, mark read, dismiss, block. |++Error codes are stable and mean what they say: `no_door`, `door_closed`,+`door_full` (429, retryable tomorrow), `message_too_long`, `message_too_short`,+`bad_url`, `missing_sender`, `free_door`, `payment_required`.++---++## Why it is built this way++**Refuse before charging.** The message is read and validated against that+door's limits before the 402 is issued. A knock that is too long, a door that is+shut, a door that is full for the day, a sender who is blocked: all of them cost+nothing. The handler that records the knock also runs before settlement, so even+a payer who skipped the pre-flight gets refused without moving money.++**The price is the ranking.** A mail client guesses at importance from keywords.+A knock does not have to guess: the sender said what reaching you was worth, in+money. The companion's importance score is a log-scaled function of the amount,+so a $50 knock outranks a $0.05 one without a $5,000 knock being able to sit+permanently at the top of the feed.++**The body is never spoken.** Only the subject line is read aloud. Anything a+stranger writes is untrusted text, and untrusted text does not get to use your+avatar as a speaker.++**No custody, no cut.** `payTo` on the 402 challenge is the recipient's own+address. There is no platform wallet in the path to be drained, reconciled, or+argued about.++---++## Related++- [The Companion](./companion.md) is what delivers a knock in person.+- [x402](./x402.md) is the payment protocol the priced lane speaks.+- [Notifications](./notifications.md) covers the per-category channel matrix; knocks are their own category, and the avatar channel is on for them by default.diff --git a/docs/mcp.md b/docs/mcp.mdindex 64069c772..21732cc64 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -109,6 +109,7 @@ npx -y @three-ws/agent-sniper serve # the same engine as an x402-paid HTTP API (# Account, inbox & discoverynpx -y @three-ws/notifications-mcp # inbox, read state, delivery prefs & Web Push devices+npx -y @three-ws/herald-mcp # tell your human in person: your avatar walks on and says itnpx -y @three-ws/billing-mcp # plan quotas, metered usage, invoices & receiptsnpx -y @three-ws/activity-mcp # trending agents/coins, $THREE holder board & activity tickerdiff --git a/docs/start-here.md b/docs/start-here.mdindex 76c01d834..0f77b5b16 100644--- a/docs/start-here.md+++ b/docs/start-here.md@@ -141,6 +141,7 @@ Curious what happens between the prompt and the model? [How the Forge works](./h- **Following Solana traders?** → [KOL Tracker](./kol-tracker.md): KOLs ranked by realized P&L computed from their own wallets' on-chain trades (never self-reported), with the public API behind it- **Listening to the economy?** → [Agent Symphony](./agent-symphony.md): /symphony plays the live agent economy as generative music; every event type has a voice, and solo mode isolates one agent by ear- **Catching up on your inbox?** → [Notifications](./notifications.md): the bell, the /notifications center, category filters, and the full inbox API+- **Something too important for a badge?** → [Herald](./herald.md): the open SDK behind /herald, where a 3D character walks onto the page and says it out loud, with an interrupt budget (importance floor, quiet hours, dedupe, batching), an accessible card for machines with no GPU, a rail so CI or an AI agent can reach the tab you have open, and a CLI that announces when your build finishes- **About to pay for something?** → [Checkout companion](./checkout-companion.md): the browser extension that reads a payment page before you pay, why the arithmetic is never a model's job, and why it never reads a form field- **Something broken on a page?** → [Feedback](./feedback.md): telling the corner companion what went wrong, what the browser attaches for you, and the boundary that keeps untrusted text from ever reaching anything with write access- **Showing off your work?** → [The creator portfolio](./creator-portfolio.md): everything on your public /u/username page, what makes an item public, and how following works from itdiff --git a/packages/agent-glance/src/index.js b/packages/agent-glance/src/index.jsindex 47bc9f6b3..a9889f513 100644--- a/packages/agent-glance/src/index.js+++ b/packages/agent-glance/src/index.js@@ -148,7 +148,9 @@ export function glanceEmbedHtml(agentId, opts = {}) {*/export function renderGlanceAnsi(card, opts = {}) {const color = opts.color !== false;- const width = Math.max(34, Math.min(80, opts.width || 46));+ // Wide enough that the agent URL fits whole: a card whose last line is a+ // half-truncated uuid cannot be copied, which is most of why it is there.+ const width = Math.max(40, Math.min(100, opts.width || 68));const c = (code, text) => (color ? `\u001b[${code}m${text}\u001b[0m` : String(text));const dot = { active: '32', idle: '33', new: '90' }[card.status] || '90';const pad = (text) => {