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): specify the door protocol other implementations have to match
nirholas8daffda9ea9d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 646e2d36f..4357ab6f7 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -33,6 +33,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Agent payments now stop themselves when the fee wallet runs dry**: The platform sponsors the network fee on every agent payment. When that wallet ran down to the point where it could not cover a single fee, the check meant to pause payments could not run, because it depended on a balance lookup and the network providers were rate-limited at the same moment. Payments kept being attempted for three hours and none of them could complete. The pause now reads its answer from the failure itself, which costs nothing and works exactly when the network is too busy to answer questions. The status page also names the real cause now, a wallet that needs funding, instead of pointing at the payment rail. `[fix, infra]`- **AI agents can now see the 3D models they make**: Until today every 3D generator on the internet, ours included, answered with a link to a file an AI agent cannot open. A person clicks it; an agent is blind to it, which is why an agent that makes a 3D model has never been able to tell a clean one from a melted one. That changes now: ask to look at any model and it comes back rendered from four angles as actual pictures the agent sees, with the geometry explained in plain language. An agent can finally check its own work, spot that the back of the model was never finished, and try again saying exactly what was wrong. It works over MCP, over a plain web request, and through a new open-source package called @three-ws/see, and it is free, including for agents that bought a model from us and want to confirm they got what they paid for. (`/docs/3d-vision`) `[feature, sdk]`- **Every release note now shows you the code that shipped it**: Until today this site kept two separate records of the same work: a changelog written for people, and a commit feed written by engineers, neither aware of the other. The new ship log joins them. Each release note now lists the commits that produced it, and says how confident it is in each match and why it made it, in plain words you can argue with. Commits nobody ever wrote up are grouped and shown too, so the work that shipped quietly is visible instead of lost. The announcements in the Telegram channel now carry a link to the exact code behind them, the raw commit feed reads in plain language instead of engineering shorthand, and it no longer posts merges or dependency bumps. The whole thing is a free, open-source package that works on anyone's repository. (`/ship`) `[feature, sdk, improvement]`+- **Herald: your terminal can now make a 3D character walk onto your screen and talk to you**: We took the part of three.ws where an avatar delivers a notification in person and turned it into something anyone can use, on any website. @three-ws/herald is an open library: one line of code and a 3D character walks into the corner of your page, looks at the person using it, and tells them, with a link to the thing it is about. It is not a toast library. It is an interrupt budget: an importance floor, quiet hours, a rate limit, dedupe, freshness, batch collapse, and a stable reason for every message it refuses to deliver, so you can always answer why you did not hear about something. No GPU, an iframe, or reduced motion falls back to an accessible card that screen readers announce the same moment everyone else hears it. There is also a rail: with an API key, anything that can make an HTTPS request reaches the browser tab you already have open. Run npx @three-ws/herald watch -- npm test and your avatar tells you when the build finishes, keeping the exit code. Wire the MCP server into Claude or Cursor and an agent that worked for twenty minutes can walk on and tell you it is done. An announcement always goes to your own sessions, so no key can interrupt anyone but its owner. Try the whole thing, rules engine included, at three.ws/herald. (`/herald`) `[feature, sdk]`- **Next on the roadmap: your agent on your home screen**: A fifth phase has been added to the public roadmap: native widgets. Right now three.ws is something you open. The plan is for the agent you own to sit on your home screen and your desktop, showing itself and one live number about it, refreshed by the system without you opening anything, with a tap that drops you back into the right screen. Android is first, because the Android app is already built and signed: three.ws ships as a real app for Solana Seeker, and as of today Google confirms the app's release key against the site, so a three.ws link opens inside the app instead of a browser tab. Windows 11 follows through the installed web app, which needs no separate store submission, then macOS and iOS through a shared widget extension. None of it is shipped yet. It is written down, scoped and public so you can hold us to it, and the phase is on the roadmap in the repo along with the work order behind it. `[docs]`- **Photo uploads, avatar saves, launches and team tasks fail fast instead of hanging**: A handful of steps still had no time limit on the outside service they called. When that service accepted the connection and then went quiet, the request sat there until the platform killed it, and you got a spinner that ended in nothing: a photo-to-avatar upload that never came back, a saved model that never finished downloading, a coin launch stuck fetching its own thumbnail, an ordinals order whose status never loaded, a team task where one hired agent held up the whole run. Each of those now has a deadline and a clear answer when it is missed, and the ones that are safe to repeat retry once first. Anything that spends money or starts a generation is never repeated: it is bounded and then reported, so no upload is billed twice and no hire is paid twice. Saving a model from a link is also checked more tightly now, against the address it actually connects to and with the size limit applied while it downloads. `[improvement, fix, infra]`- **Report a bug and it arrives as a test that fails until it is fixed**: When you tell the agent in the corner that something is broken, it now sends what you actually did: the steps you took, the page, and the error the browser saw. Those steps compile into a real test that fails while the bug is there and passes once it is gone, so the slowest part of fixing anything (working out how to make it happen again) is done before anyone starts. You can see every step that gets attached before you send, and nothing you typed into a field is ever recorded, only how much. The recorder is open source and works on any site: install @three-ws/witness. (`/docs/witness`) `[feature, sdk, improvement]`diff --git a/packages/portal/src/index.js b/packages/portal/src/index.jsnew file mode 100644index 000000000..76b597b5f--- /dev/null+++ b/packages/portal/src/index.js@@ -0,0 +1,149 @@+// @three-ws/portal — any website as a walkable 3D world.+//+// Three things live here, and they are deliberately separable:+//+// the layout a pure function from a page's structure to a world+// (./layout.js). No network, no DOM, no three.js. It runs+// identically in a browser, in Node, in a worker, and on+// three.ws itself, which is why a shared link always opens+// the same city the sharer walked.+// the client thin wrappers over the public Portal API, which does the+// fetching, the robots.txt check and the caching for you.+// the embed one call that puts a live, walkable world in your page.+//+// Nothing here needs a key, an account, or a wallet.+//+// import { fetchWorld, mountPortal } from '@three-ws/portal';+// const { world } = await fetchWorld('example.com');+// mountPortal(document.querySelector('#stage'), { url: 'example.com' });++export * from './layout.js';++/** The public Portal API. Point this at a self-hosted three.ws to use your own. */+export const PORTAL_API = 'https://three.ws/api/portal';+export const PORTAL_PAGE = 'https://three.ws/portal';++/** Everything the client throws, with the API's own machine-readable code. */+export class PortalError extends Error {+ constructor(code, message, status) {+ super(message);+ this.name = 'PortalError';+ this.code = code;+ this.status = status;+ }+}++function endpointFor(url, { endpoint = PORTAL_API, ...params } = {}) {+ const query = new URLSearchParams({ url: String(url || '') });+ for (const [k, v] of Object.entries(params)) {+ if (v !== undefined && v !== null && k !== 'fetch' && k !== 'signal') query.set(k, String(v));+ }+ return `${endpoint}?${query}`;+}++/**+ * Build (or read from cache) the world for a page.+ * @param {string} url any address: `example.com`, `https://example.com/docs`+ * @param {{ endpoint?: string, include?: 'world'|'outline'|'both', fetch?: typeof fetch, signal?: AbortSignal }} [opts]+ * @returns {Promise<{ world: object, outline?: object, cached: boolean, stale: boolean }>}+ */+export async function fetchWorld(url, opts = {}) {+ const impl = opts.fetch || globalThis.fetch;+ if (!impl) throw new PortalError('no_fetch', 'No fetch implementation available. Pass one as opts.fetch.', 0);+ const res = await impl(endpointFor(url, opts), {+ headers: { accept: 'application/json' },+ signal: opts.signal,+ });+ const body = await res.json().catch(() => null);+ if (!res.ok || !body?.world) {+ throw new PortalError(+ body?.error || `http_${res.status}`,+ body?.error_description || `Portal could not build a world from ${url}.`,+ res.status,+ );+ }+ return { world: body.world, outline: body.outline, cached: !!body.cached, stale: !!body.stale };+}++/**+ * The same world as a glTF binary, ready for Blender, Unity, AR, or any viewer.+ * @param {string} url+ * @param {{ endpoint?: string, fetch?: typeof fetch, signal?: AbortSignal }} [opts]+ * @returns {Promise<ArrayBuffer>}+ */+export async function fetchWorldGlb(url, opts = {}) {+ const impl = opts.fetch || globalThis.fetch;+ if (!impl) throw new PortalError('no_fetch', 'No fetch implementation available. Pass one as opts.fetch.', 0);+ const res = await impl(endpointFor(url, { ...opts, format: 'glb' }), { signal: opts.signal });+ if (!res.ok) {+ const body = await res.json().catch(() => null);+ throw new PortalError(body?.error || `http_${res.status}`, body?.error_description || 'Portal could not export that world.', res.status);+ }+ return res.arrayBuffer();+}++/** The iframe snippet that puts a walkable world on a page, as a string. */+export function embedSnippet(url, { height = 520, page = PORTAL_PAGE, title } = {}) {+ const src = `${page}?url=${encodeURIComponent(url)}&embed=1`;+ const label = title || `Walk ${url} in 3D`;+ return `<iframe src="${src}" width="100%" height="${height}" style="border:0;border-radius:14px" loading="lazy" title="${label}"></iframe>`;+}++/**+ * Mount a live, walkable world into an element.+ *+ * It embeds the hosted renderer rather than shipping a second copy of it: the+ * renderer is a WebGL app with an avatar, a clip library and a rig retargeter+ * behind it, and a stale duplicate of that inside an npm package would be worse+ * for everyone than an iframe that is always current.+ *+ * @param {Element} element where to mount+ * @param {{ url: string, height?: number|string, page?: string, title?: string }} opts+ * @returns {HTMLIFrameElement}+ */+export function mountPortal(element, { url, height = 520, page = PORTAL_PAGE, title } = {}) {+ if (!element || typeof element.append !== 'function') {+ throw new PortalError('bad_target', 'mountPortal needs an element to mount into.', 0);+ }+ if (!url) throw new PortalError('bad_url', 'mountPortal needs a url to explore.', 0);+ const doc = element.ownerDocument || globalThis.document;+ const frame = doc.createElement('iframe');+ frame.src = `${page}?url=${encodeURIComponent(url)}&embed=1`;+ frame.width = '100%';+ frame.height = String(height);+ frame.loading = 'lazy';+ frame.title = title || `Walk ${url} in 3D`;+ frame.style.border = '0';+ frame.style.borderRadius = '14px';+ frame.allow = 'fullscreen';+ element.append(frame);+ return frame;+}++/**+ * A compact, human-readable summary of a world: what the page turned into.+ * Used by the CLI and the MCP tool, and useful in any dashboard.+ * @param {object} world+ */+export function describeWorld(world) {+ const districts = world.buildings.map((b) => ({+ name: b.label,+ height: b.h,+ words: b.words,+ doors: world.doors.filter((d) => d.buildingId === b.id).length,+ }));+ return {+ host: world.meta.host,+ title: world.meta.title,+ sections: world.meta.sections,+ words: world.meta.words,+ doors: world.doors.length,+ internalDoors: world.doors.filter((d) => d.internal).length,+ billboards: world.props.filter((p) => p.kind === 'billboard').length,+ monoliths: world.props.filter((p) => p.kind === 'monolith').length,+ radius: world.ground.radius,+ palette: world.palette,+ tallest: districts.slice().sort((a, b) => b.height - a.height)[0] || null,+ districts,+ };+}diff --git a/public/changelog.json b/public/changelog.jsonindex a37eb2fab..22c13e16a 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-28T05:46:30.228Z",+ "generated_at": "2026-08-28T05:48:20.975Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -280,6 +280,17 @@"improvement"]},+ {+ "date": "2026-08-28",+ "type": "update",+ "title": "Herald: your terminal can now make a 3D character walk onto your screen and talk to you",+ "summary": "We took the part of three.ws where an avatar delivers a notification in person and turned it into something anyone can use, on any website. @three-ws/herald is an open library: one line of code and a 3D character walks into the corner of your page, looks at the person using it, and tells them, with a link to the thing it is about. It is not a toast library. It is an interrupt budget: an importance floor, quiet hours, a rate limit, dedupe, freshness, batch collapse, and a stable reason for every message it refuses to deliver, so you can always answer why you did not hear about something. No GPU, an iframe, or reduced motion falls back to an accessible card that screen readers announce the same moment everyone else hears it. There is also a rail: with an API key, anything that can make an HTTPS request reaches the browser tab you already have open. Run npx @three-ws/herald watch -- npm test and your avatar tells you when the build finishes, keeping the exit code. Wire the MCP server into Claude or Cursor and an agent that worked for twenty minutes can walk on and tell you it is done. An announcement always goes to your own sessions, so no key can interrupt anyone but its owner. Try the whole thing, rules engine included, at three.ws/herald.",+ "link": "/herald",+ "tags": [+ "feature",+ "sdk"+ ]+ },{"date": "2026-08-28","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex ed9af2336..beca943c8 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -222,6 +222,14 @@<category>feature</category><description>Until today this site kept two separate records of the same work: a changelog written for people, and a commit feed written by engineers, neither aware of the other. The new ship log joins them. Each release note now lists the commits that produced it, and says how confident it is in each match and why it made it, in plain words you can argue with. Commits nobody ever wrote up are grouped and shown too, so the work that shipped quietly is visible instead of lost. The announcements in the Telegram channel now carry a link to the exact code behind them, the raw commit feed reads in plain language instead of engineering shorthand, and it no longer posts merges or dependency bumps. The whole thing is a free, open-source package that works on anyone's repository.</description></item>+ <item>+ <title>Herald: your terminal can now make a 3D character walk onto your screen and talk to you</title>+ <link>https://three.ws/herald</link>+ <guid isPermaLink="false">2026-08-28:Herald: your terminal can now make a 3D character walk onto your screen and talk to you</guid>+ <pubDate>Fri, 28 Aug 2026 12:00:00 GMT</pubDate>+ <category>feature</category>+ <description>We took the part of three.ws where an avatar delivers a notification in person and turned it into something anyone can use, on any website. @three-ws/herald is an open library: one line of code and a 3D character walks into the corner of your page, looks at the person using it, and tells them, with a link to the thing it is about. It is not a toast library. It is an interrupt budget: an importance floor, quiet hours, a rate limit, dedupe, freshness, batch collapse, and a stable reason for every message it refuses to deliver, so you can always answer why you did not hear about something. No GPU, an iframe, or reduced motion falls back to an accessible card that screen readers announce the same moment everyone else hears it. There is also a rail: with an API key, anything that can make an HTTPS request reaches the browser tab you already have open. Run npx @three-ws/herald watch -- npm test and your avatar tells you when the build finishes, keeping the exit code. Wire the MCP server into Claude or Cursor and an agent that worked for twenty minutes can walk on and tell you it is done. An announcement always goes to your own sessions, so no key can interrupt anyone but its owner. Try the whole thing, rules engine included, at three.ws/herald.</description>+ </item><item><title>Next on the roadmap: your agent on your home screen</title><link>https://three.ws/changelog</link>diff --git a/public/features.json b/public/features.jsonindex 583494749..93d817be0 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-28T05:46:30.138Z",+ "generated_at": "2026-08-28T05:48:20.941Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",diff --git a/specs/KNOCK_PROTOCOL.md b/specs/KNOCK_PROTOCOL.mdnew file mode 100644index 000000000..b03ed6da1--- /dev/null+++ b/specs/KNOCK_PROTOCOL.md@@ -0,0 +1,301 @@+# KNOCK_PROTOCOL - v1++The wire contract for a priced door to a person: how a door advertises its+terms, how a knock is paid for and accepted, and how the sender reads the+answer.++Knock is deliberately small. It is one message in one direction, priced by the+recipient, settled to the recipient, and delivered in person by their+[companion](../docs/companion.md). Everything else (threads, contacts, presence)+is out of scope by design.++Reference implementation: `api/knock/**`, `api/x402/knock.js`, and the pure rule+module `api/_lib/knock/policy.js`. Client: `packages/knock-sdk`.++---++## 1. Terms++| Term | Meaning |+| --- | --- |+| **Door** | A recipient's published terms: price, chains, message limit, daily cap. |+| **Knock** | One accepted message through a door. |+| **Free door** | `price_atomics == "0"`. Takes an unpaid POST. |+| **Priced door** | `price_atomics > 0`. Takes an x402 payment. |+| **Receipt token** | An unguessable derived token that lets the sender read one knock's state. |++All amounts are **USDC atomic units**, decimal string, 6 decimals. `"50000"` is+$0.05. Strings, not numbers: a JSON number cannot carry these safely at the top+of the range.++---++## 2. Door document++`GET /api/knock/door?handle=<username>` returns the door as a stranger sees it.+Unauthenticated. Cacheable for 30s.++```json+{+ "door": {+ "handle": "nirholas",+ "display_name": "nirholas",+ "avatar_url": "https://…",+ "verified": null,+ "open": true,+ "free": false,+ "price_atomics": "50000",+ "price": "$0.05",+ "currency": "USDC",+ "networks": ["solana"],+ "headline": "Ask me about x402 on Solana",+ "greeting": "…",+ "max_chars": 600,+ "endpoint": "https://three.ws/api/x402/knock?to=nirholas",+ "protocol": "x402"+ }+}+```++| Field | Type | Notes |+| --- | --- | --- |+| `free` | boolean | Authoritative. Clients MUST branch on this, not on `price`. |+| `price_atomics` | string | Decimal atomic USDC. |+| `price` | string | Display only. Never parse it. |+| `networks` | string[] | Ordered by preference. Solana leads unless the owner set only Base. |+| `max_chars` | integer | The door's own limit, 40 to 2000. |+| `endpoint` | string | Absolute URL of the lane to use. |+| `protocol` | `"http"` \| `"x402"` | Which lane `endpoint` speaks. |++A payout address is **never** in this document.++**Non-enumeration.** A handle that matches no account and a handle whose owner+has not opened a door MUST both answer `404` with the same body.++`GET /api/knock/directory?limit=<1-100>` returns `{ doors: [...], count }`:+every door that is open **and** listed, ordered by `price_atomics` ascending.+Open and listed are independent: an unlisted open door is reachable by link and+absent from the directory.++---++## 3. Knock request++The same body on both lanes, except that the free lane carries `to`.++```json+{+ "from": "Ada (research agent)",+ "subject": "Your x402 settle path",+ "message": "…",+ "url": "https://example.com/ada",+ "sender_kind": "agent",+ "request_id": "ada-2026-08-28-001"+}+```++| Field | Required | Constraint |+| --- | --- | --- |+| `to` | free lane only | Handle. On the paid lane it is the `?to=` query parameter. |+| `from` | yes | 1 to 64 chars after trim. Shown and spoken. |+| `message` | yes | 8 to `max_chars` chars after trim. Shown in full, **never spoken**. |+| `subject` | no | Up to 120 chars. The only field read aloud. |+| `url` | no | `http(s)` only, up to 400 chars. Any other scheme is rejected. |+| `sender_kind` | no | `agent` \| `human` \| `unknown`. Self-declared, never trusted for access. |+| `request_id` | no | Up to 80 chars. Idempotency key, scoped to the recipient. |++`sender_kind` is displayed, not enforced. It exists so a recipient can see what+claims to be knocking, not to gate anything.++---++## 4. Lanes++### 4.1 Free lane++```+POST /api/knock/send+```++Unauthenticated. `201` on acceptance, `200` when `request_id` matched an earlier+knock.++A **priced** door MUST answer this lane with `402` and the x402 endpoint:++```json+{+ "error": "payment_required",+ "error_description": "nirholas charges $0.05 to be reached",+ "endpoint": "https://three.ws/api/x402/knock?to=nirholas",+ "price_atomics": "50000",+ "protocol": "x402"+}+```++### 4.2 Paid lane++```+POST /api/x402/knock?to=<handle>+```++A standard [x402](../docs/x402.md) resource. The `402` challenge MUST advertise:++- `amount` equal to that door's `price_atomics` at request time, and+- `payTo` equal to **the recipient's own address** for each advertised network.++A **free** door MUST answer this lane with `400 free_door` and the plain+endpoint, so a client that guessed wrong is redirected rather than refused.++### 4.3 Ordering guarantee++This is the load-bearing rule of the protocol.++> Every refusal that can be determined from the request and the door MUST be+> evaluated **before** the `402` challenge is issued, and MUST be re-evaluated+> **before** settlement.++Concretely: a shut door, a door at its daily cap, a blocked sender, a missing+`from`, and a message outside the length bounds are all refused with no payment+taken. Implementations that deliver-then-settle (as this one does) get the+second half for free: the handler that records the knock runs before settlement,+so a throw there refuses the knock without moving money.++A conforming client MAY therefore retry a `4xx` from this endpoint without+worrying that the previous attempt was charged.++---++## 5. Knock response++```json+{+ "ok": true,+ "knock_id": "c1b0a2d4-7e33-4f01-9a55-2b7c1d0e9f4a",+ "delivered_to": "nirholas",+ "announced": true,+ "importance": 74,+ "paid": "$0.05",+ "receipt_url": "https://three.ws/api/knock/reply?id=…&token=…",+ "duplicate": false+}+```++| Field | Notes |+| --- | --- |+| `announced` | The knock cleared the default interrupt threshold. Not a promise: the recipient may have raised their own bar. |+| `importance` | 0 to 100, see §7. |+| `duplicate` | `request_id` matched an earlier knock. Nothing new was delivered, and on the paid lane nothing new settles. |+| `receipt_url` | Absolute. The sender's only handle on this knock. |++---++## 6. Receipt++```+GET /api/knock/reply?id=<knock id>&token=<receipt token>+```++The token is derived, not stored:++```+token = base64url(HMAC-SHA256(server_secret, "knock-receipt-v1:" + knock_id))[0:32]+```++Constant-time compared. A wrong or absent token MUST answer `404`, not `403`: an+id alone must not confirm that a knock exists.++```json+{+ "knock": {+ "id": "c1b0a2d4-…",+ "subject": "Your x402 settle path",+ "status": "replied",+ "reply": "Ask away.",+ "replied_at": "2026-08-28T04:02:11.000Z",+ "seen": true,+ "amount": "$0.05",+ "created_at": "2026-08-28T03:41:02.000Z"+ }+}+```++`status` is one of `pending`, `read`, `replied`, `dismissed`. `reply` is+non-null **only** when `status == "replied"`.++The receipt MUST NOT expose anything about the recipient beyond the reply they+deliberately wrote. No name, no address, no wallet, no read timestamps beyond+the `seen` boolean.++---++## 7. Importance++A knock's importance is a pure function of the amount paid. There is no keyword+scoring: the sender already stated what reaching this person was worth, in+money.++```+importance(0) = 45+importance(a > 0) = clamp(round(80 + 6 * log10(a / 10^6)), 62, 99)+```++Properties a conforming implementation MUST preserve:++1. Every paid knock scores **above** 60, the default interrupt threshold. Paying+ to reach someone is the signal.+2. A free knock scores **below** 60. It enters the feed and the bell; it does not+ stop the recipient's day.+3. The function is monotonic in the amount and bounded at 99, so no single+ payment can permanently own the top of the feed.++---++## 8. Delivery++An accepted knock becomes a companion event with `source_kind = "knock"` and a+`spoken_line` of the form:++```+<from> paid <price> to reach you: <subject>.+<from> is at your door. (free door, or no subject)+```++The `message` body is **never** placed in `spoken_line`. Untrusted text does not+get to use the recipient's avatar as a speaker.++It also raises a `knock_received` notification, which rides the recipient's+normal per-category channel matrix (`knock` category: in-app, push, email and+avatar on by default, telegram off). Muting the category mutes the delivery;+nothing here bypasses it.++---++## 9. Error codes++Stable, machine-readable, returned as `{"error": <code>, "error_description": …}`.++| Code | Status | Meaning |+| --- | --- | --- |+| `no_door` | 404 | No open door for that handle, or no such account. |+| `door_closed` | 403 | Shut right now. Also what a blocked sender sees. |+| `door_full` | 429 | Daily cap spent. Retryable tomorrow. Nothing was charged. |+| `missing_sender` | 400 | No `from`. |+| `message_too_short` | 400 | Under 8 characters. |+| `message_too_long` | 400 | Over that door's `max_chars`. |+| `bad_url` | 400 | `url` was not a plain `http(s)` link under 400 chars. |+| `free_door` | 400 | Paid lane used on a free door. Carries the plain endpoint. |+| `payment_required` | 402 | Free lane used on a priced door. Carries the x402 endpoint. |++**Blocked senders and shut doors are indistinguishable by design.** A blocked+sender who could tell it was them would simply knock again under another name.++---++## 10. Privacy and custody invariants++1. **No custody.** `payTo` is the recipient's address. No platform wallet is in+ the settlement path. A priced door cannot be opened without a payout address.+2. **No enumeration.** Unknown handle and shut door are indistinguishable.+3. **No leakage through the receipt.** See §6.+4. **No spoken bodies.** See §8.+5. **No unpaid refusals turning into paid ones.** See §4.3.diff --git a/specs/README.md b/specs/README.mdindex 7c0da9f66..4d246aa2f 100644--- a/specs/README.md+++ b/specs/README.md@@ -25,6 +25,7 @@ The specifications that define the three.ws embodied-agent platform: on-chain id- [`SKILL_ROYALTY_SPLIT.md`](./SKILL_ROYALTY_SPLIT.md): Skill Royalty Split v1. How a paid skill call divides between the author and the platform, and how that division is recorded: exact integer arithmetic that conserves value and rounds toward the creator, who the author of record is, which wallet a payout resolves to, and the ledger invariants both earning lanes must hold. The contract the x402 rail, the accrual writer, the settle cron and the earnings surface all read from.+- [`KNOCK_PROTOCOL.md`](./KNOCK_PROTOCOL.md): Knock Protocol v1. A priced door to a person: how a door advertises its terms, how a knock is paid for on the free and x402 lanes, the ordering rule that guarantees a refused knock is never a paid one, the derived receipt token the sender reads the answer with, and the custody and non-enumeration invariants.- [`OPEN_INFERENCE_PROTOCOL.md`](./OPEN_INFERENCE_PROTOCOL.md): Open Inference Protocol (OIN) v0.1. The vendor-neutral wire protocol for agent inference: a job envelope, a signed capability advertisement, and an Ed25519-signed response anyone can verify against the node's published key, so inference decouples from any single provider. Reference verifier in `api/_lib/oin-verify.js`; reference node in `workers/stylize`.- [`inference-receipts.md`](./inference-receipts.md): Inference Receipt v1. The settlement half of the same story: what a paid inference call hands back as proof (job, model, input/output hashes, node and issuer signatures, the settlement transaction) and how to verify it offline.