@muretai/agent-entry 1.9.0 → 1.11.0

package/README.md

@@ -1,10 +1,61 @@
 # Agent Entry
 
-**`llms.txt` describes your site to an AI agent. An Agent Entry *recognises* one.**
+[![npm](https://img.shields.io/npm/v/@muretai/agent-entry.svg?label=npm)](https://www.npmjs.com/package/@muretai/agent-entry)
+[![LICENSE](https://img.shields.io/badge/LICENSE-MIT-blue.svg)](LICENSE)
 
-It verifies who is knocking, opens an account for them, and answers — in the same HTTP
-response. No signup form, because the visitor's key already is the account. When that
-person replaces their phone, your site still knows it is them.
+**Agents already visit your site. Give them a way to become a customer.**
+
+## Contents
+
+- [What this is](#what-this-is)
+- [What you get](#what-you-get)
+- [Who is knocking](#who-is-knocking)
+- [Put it on a site](#put-it-on-a-site)
+- [On serverless](#on-serverless)
+- [On WordPress](#on-wordpress)
+- [Pairs with WebMCP](#pairs-with-webmcp-the-tab-conversation-becomes-a-customer)
+- [In production](#in-production)
+- [This package](#this-package)
+
+## What this is
+
+They read your pages and leave. No signup, no cookie, nothing in your analytics.
+Agent Entry is a single module you put on the origin. It publishes an
+[Agent Card](https://a2a-protocol.org/latest/specification/)
+at `/.well-known/agent-card.json` — who you are, what you answer, how to knock —
+and then answers one signed POST: verify the visitor, open an account from their
+key, reply signed, same HTTP response.
+
+No form. The key *is* the account. Come back next month from another device and
+it is still them.
+
+Any A2A client works: their agent, `curl`, not a particular router or ours.
+
+Keep WebMCP. A person already in the tab keeps the page. This file sits beside
+it and replaces none of it: an Agent Card and a door, so an agent who arrives
+alone can become a customer — one signed POST, a signed reply.
+
+`llms.txt` is a brochure — prose, not a contract. MCP is a tool server for an
+app that holds a token. A different purpose.
+
+The agent reads the card **before** it knocks (AE-8). The act is then one
+**POST** `message/send` — already formed correctly — and a signed reply comes
+back on that same request (AE-20).
+
+A **handoff** is how a tool on the page, or a tool server, can send the visitor
+*here*: the result names this entry's DID, and the next act is a signed knock at
+this origin. This file does not follow a handoff and does not parse
+`_meta.handoff`. It is where one lands. The `to` in that envelope must be the
+DID printed at startup — the same seed as the card. A visitor (or any router
+they run) is who honours the pointer.
+
+| | |
+|---|---|
+| **Who installs this** | Website owners who want agents as *customers* — a returning identity — not only as crawlers. |
+| **Not for** | People writing the visiting agent. This package does not find doors, MCP servers, or WebMCP tools; it *is* a door. |
+| **The problem** | A GET-only document cannot recognise anyone. A signup form does not work for an agent. The first signed POST has to *be* the account. |
+
+![A person in the tab keeps WebMCP. An agent alone can become a customer at the door beside it.](diagrams/become.png)
 
 One file. Zero dependencies. No database. Node 20+.
 
@@ -38,9 +89,26 @@ That is the whole integration. `responder` is called with a verified envelope an
 what to say back; everything else — signatures, replay, rate limiting, the account
 ledger — is handled for you.
 
+### Not an HTTP 402 challenge
+
+[x402](https://x402.org/) v2 over HTTP teaches by **error**. The client asks for the
+resource; the server answers `402 Payment Required` with a `PAYMENT-REQUIRED` header; the
+client **retries** the same resource with `PAYMENT-SIGNATURE`. The error is how the
+client learns what to do next.
+
+Agent Entry does the reverse. The Agent Card states the terms **before** anyone knocks
+(AE-8). An HTTP-402-style challenge structurally cannot do that. The first POST is already
+formed correctly and is answered `200` with a signed reply (AE-20). This package does not
+speak x402 and does not return HTTP 402. A protocol refusal here is HTTP `200` plus a
+JSON-RPC error (AE-19). If someone POSTs with no signature at all, `-32001` still carries
+`data.accepts` — the same scheme object as the card — so they can succeed on the next POST
+(AE-24). That is a fallback, not the design.
+
+![x402: request, HTTP 402, retry with payment. Agent Entry: GET the card as 200, then POST already correct, answered 200.](diagrams/x402.svg)
+
 ---
 
-## What you actually get
+## What you get
 
 **A caller you can trust.** Every message arrives with an Ed25519 signature over six
 frozen fields. The sender's DID *is* their public key (`did:key`), so verification needs
@@ -69,7 +137,7 @@ resolves it and files them under `owner_did`, so a replaced phone is not a new c
 Your entry does not need to poll or be told: a node that carries the account learns it on
 its own, and refuses that key.
 
-## Say what your door answers
+### Say what your door answers
 
 A visiting agent reads your card **before** it knocks. Left alone, that card says something
 answers here and nothing about what it answers, so the visitor has to guess and learns your
@@ -84,7 +152,7 @@ createAgentEntry({
     description: 'Ask what a shoot costs, what the studio does, and how to book. '
       + 'The answer comes back in the same HTTP response, signed by this domain.',
     tags: ['studio', 'booking', 'signed', 'inline-reply'],
-    examples: ['Do you shoot weddings?', 'What does a half-day cost?', 'How do I book?'],
+    examples: ['Do you shoot weddings?', 'How much is a half-day?', 'Book Saturday 14:00'],
   }],
 });
 ```
@@ -99,12 +167,21 @@ visitor you will get, so drive your examples through your own responder in your
 **Declare only what the responder does:** a skill that mentions booking, on an entry that
 answers questions and hands off nothing, is a signed claim you cannot keep.
 
+Turning logged knocks into that menu is an offline owner loop, not part of the
+runtime — see [`spec/skill-distill.md`](spec/skill-distill.md). On this machine
+only: `npm run distill` measures whether a proposed menu would have made the
+next first knock useful. `observer: fileSink()` (from
+`scripts/distill/record.mjs`) appends POST outcomes to `var/traces.jsonl`.
+Nothing is uploaded, and the Distiller is never imported by
+`muretai-agent-entry.mjs`.
+
 ### The rest of the settings
 
 | option | default | what it does |
 |---|---|---|
 | `skills` | `[]` | the menu above — what a visitor learns before knocking |
 | `openDoor` | `true` | publishes `agentEntry.open_door`: the field that tells a visiting agent it may message you with no introduction. The same fact is emitted under the older `muretai.open_door` spelling beside it — read either, write the neutral one |
+| `prefer` | unset | your own order of the ways into your site, published verbatim as `agentEntry.prefer` (spec AE-30): an array of `"page"`, `"card"`, `"mcp"` or `{kind, when}` with `when` one of `person`, `alone`, `key`, `no-key`, `token`, `browser` — e.g. `[{kind:'page', when:'no-key'}, 'card']` says "read on the page if you hold no key; otherwise the door". A visiting agent reads it against what it has on hand. An invalid list refuses to start rather than publish an order you did not write; unset publishes no key at all |
 | `anonymousLane` | `false` | also answer **unsigned** inquiries. They create no account row, and the lane is capped entry-wide — an unauthenticated caller must never become an unmetered signing oracle |
 | `anonRatePerMin` | `30` | anonymous replies per minute, entry-wide |
 | `signedRatePerMin` | `60` | signed replies per minute **per account**, ON by default. Attribution is not scarcity: a `did:key` costs nothing to mint, so being in your ledger was never a bound |
@@ -121,12 +198,12 @@ answers questions and hands off nothing, is a signed claim you cannot keep.
 `seedHex` and `baseUrl` are the two an entry refuses to start without: the seed **is** the
 address, and the url it publishes must equal the origin the visitor dialled.
 
-## Who is knocking — observation, never identity
+## Who is knocking
 
-The person who found you often never opens a browser: they hand your link to their
-agent, and the agent fetches your card and knocks. That traffic is invisible to every
-page-view metric you have — the only place it can be seen is the door itself. So the
-door counts it:
+Observation, never identity. The person who found you often never opens a browser:
+they hand your link to their agent, and the agent fetches your card and knocks.
+That traffic is invisible to every page-view metric you have — the only place it
+can be seen is the door itself. So the door counts it:
 
 ```js
 entry.stats()
@@ -198,7 +275,9 @@ signature over the transport proves who fetched — not who wrote the text, and
 captured header set is replayable until it expires (minutes), which is why `wba_did`
 is identification, never authorship.
 
-## Install
+## Put it on a site
+
+### Install
 
 ```bash
 npm i @muretai/agent-entry
@@ -218,7 +297,7 @@ upgrade — the ledger is your customer list, and more features stand on keeping
 an analytics tool covers statistics without one. Both are described under
 [Before you put it in production](#before-you-put-it-in-production).
 
-## Put one on a site you already have
+### Put one on a site you already have
 
 A visiting agent knows only your **domain**, so the three paths it walks are fixed — it
 cannot be told to look elsewhere:
@@ -351,8 +430,9 @@ has already changed the bytes the signature covers, and the only diagnostic anyo
 
 ### 3. A reverse proxy — for a site that is not Node at all
 
-WordPress, Rails, a static build. Run the entry as one small process and route three
-locations to it:
+Rails, a static build, anything that is not WordPress and not a function. Run the
+entry as one small process and route three locations to it. WordPress has its own
+plugin — [On WordPress](#on-wordpress).
 
 ```nginx
 location = /.well-known/agent-card.json     { proxy_pass http://127.0.0.1:8788; }
@@ -363,16 +443,35 @@ location = / {
 }
 ```
 
-### Serverless
+### On serverless
+
+The round-trip shape fits a single function: one signed POST in, one signed reply out.
+What does not fit is the state. A function instance keeps nothing between requests, so
+the replay set, the device→owner pins and the ledger have to live in a store the
+platform keeps, not in memory.
+
+This package still runs in process. For Cloudflare Workers, Vercel and Netlify, use
+the deploy templates — this door plus one store adapter per platform:
+
+[github.com/muretai/agent-entry-serverless](https://github.com/muretai/agent-entry-serverless)
+
+They vendor a library build that includes the `store` seam those adapters need. Do not
+replace that file with an older published copy of this package: versions without the
+seam accept the option and silently ignore it, which puts the three stateful rules
+back into per-instance memory — the failures those templates exist to prevent.
+
+Until you are on one of those templates, use one of the long-lived shapes above.
+
+### On WordPress
 
-The round-trip shape fits a single function well, and `handleRequestAsync` is exactly the
-handler signature those platforms want. Two things must be settled first, because a
-serverless instance keeps nothing between requests: the seed has to come from a secret
-environment variable, and the ledger, the device→owner pins and the replay guard have to
-live in your own store rather than in memory. A `store` hook for that is the next release;
-until then, use one of the three long-lived shapes above.
+If the site is WordPress, do not proxy this Node file in front of it. The plugin is a
+third implementation of the same contract — it publishes the card, answers the signed
+POST, and with WooCommerce lets an agent ask about the catalogue. `GET /` stays your
+site.
 
-## Run the example
+[github.com/muretai/agent-entry-wordpress](https://github.com/muretai/agent-entry-wordpress)
+
+### Run the example
 
 ```bash
 node examples/server.mjs        # prints its DID and card URL
@@ -381,9 +480,10 @@ node examples/server.mjs        # prints its DID and card URL
 Environment: `AGENT_ENTRY_SEED_HEX` (generated and printed if absent — **persist it, it is
 your site's identity**), `AGENT_ENTRY_PORT` (8788), `AGENT_ENTRY_BASE_URL`,
 `AGENT_ENTRY_NAME`, `AGENT_ENTRY_ANON` (`1` also accepts unsigned inquiries, which create
-no account).
+no account), `AGENT_ENTRY_PREFER` (your order of the ways in, as one JSON array — see
+`prefer` above; an invalid list refuses to start).
 
-## What `baseUrl` may be
+### What `baseUrl` may be
 
 `baseUrl` must be the URL visitors actually dial: it is what your signed card claims, and
 a card naming a different origin proves nothing about yours.
@@ -420,7 +520,7 @@ Two rules worth knowing before you pick a URL:
   parser punycodes a host and Python's does not, so the two implementations would otherwise
   sign different bytes for the same site.
 
-## One host, many agents
+### One host, many agents
 
 A domain can hold a **fleet** — a front desk, support, sales — each its own agent, its own
 key, its own address, each contactable directly. Give each one a `baseUrl` that carries its
@@ -472,7 +572,7 @@ const fwd = (entry) => async (req, res) => {
 };
 ```
 
-## Which domains this entry speaks for
+### Which domains this entry speaks for
 
 An entry can name the domains it belongs to:
 
@@ -503,6 +603,11 @@ Set it from the environment with `AGENT_ENTRY_DOMAINS=studio.example,support.stu
 
 ## Pairs with WebMCP: the tab conversation becomes a customer
 
+WebMCP is not MCP. MCP is a tool *server* over HTTP (a token, a session). WebMCP is tools
+*in the page*, running as whoever is in that browser tab. This package implements neither.
+A site may run WebMCP, an MCP server, and an Agent Entry at once; a headless agent should
+use the last two, not scrape the first.
+
 If your page already exposes [WebMCP](https://github.com/MiguelsPizza/WebMCP) tools, you have
 one door open: an agent **inside a visitor's browser** can call `check_stock` or `inquire`
 while that person is on the page. That is useful and it is also temporary — close the tab and
@@ -515,10 +620,11 @@ An Agent Entry is the second door, and it is the one that keeps something:
 | **WebMCP tools** | a person's agent, in a tab, right now | an answer in the moment |
 | **Agent Entry** | an agent alone, from anywhere, at any hour | a customer you still recognise next month |
 
-**They connect.** When a WebMCP tool call reaches the point of actually wanting something —
-a booking, a quote, a follow-up — the tool returns a small envelope naming your site's DID,
-and the visitor's agent then sends a **signed message to your own origin**, where your Agent
-Entry receives it:
+**They connect by a handoff.** When a WebMCP (or MCP) tool call reaches the point of
+actually wanting something — a booking, a quote, a follow-up — the tool returns a small
+envelope naming your site's DID. The visitor's agent then sends a **signed message to your
+own origin**, where your Agent Entry receives it. That envelope is a handoff: this package
+is the landing, not the follower.
 
 ```js
 navigator.modelContext.registerTool({
@@ -547,7 +653,9 @@ account layer resolves the owner behind both keys.
 A search engine makes your site **findable**. An Agent Entry makes it **answerable** — and
 makes the visitor someone you can recognise the next time.
 
-## Before you put it in production
+## In production
+
+### Before you put it in production
 
 **Nothing here is needed to start** — an entry runs, and every exchange stays correct,
 on its in-process state alone; some installers have read this section as a prerequisite,
@@ -598,7 +706,7 @@ What the entry now handles for you at the HTTP layer, so you do not have to:
   which says a server must accept the absolute form: this endpoint answers exactly the
   address its card names, and the refusal says so.
 
-## Counting visits without handing over your customer list
+### Counting visits without handing over your customer list
 
 You will want to know how many agents knocked, how many came back, and what they asked. All
 three are answerable — and how you answer them decides whether you are counting your visitors
@@ -683,7 +791,9 @@ disclosure that arrives after the visit is not a disclosure, it is a receipt.
 And if you decide to send raw DIDs anyway, that is your call to make — but say so on the card,
 in the same breath, in plain words.
 
-## Two implementations, pinned to each other
+## This package
+
+### Two implementations, pinned to each other
 
 This module is not alone. A Python reference implements the same contract, and the two are
 held to **identical verdicts** by an acceptance suite: it runs the same attack battery
@@ -725,9 +835,12 @@ for byte. No network, no checkout of ours, nothing to ask us for:
 npm test
 ```
 
-Write a third implementation and point it at the same vectors.
+Write another implementation and point it at the same vectors.
+[Agent Entry for WordPress](https://github.com/muretai/agent-entry-wordpress)
+is one that already does — a PHP door, not this file wrapped, held to the same
+golden bytes.
 
-## Contributing
+### Contributing
 
 This repo is a **published mirror**, rendered out of a private working repository — not the
 place the next change is written. A pull request opened here will not merge: the next release
@@ -738,7 +851,7 @@ That is not a closed door. **Open an issue** — a bug, a wire-vector disagreeme
 docs are wrong, a design question — and it gets read and, where it's right, becomes the next
 release here. That path works; a PR against these files does not.
 
-## What this is part of
+### What this is part of
 
 [Muretai](https://muretai.com) is a network where AI agents that belong to *different
 people* can find and talk to each other — with identity, introductions and trust, rather
@@ -748,7 +861,19 @@ that has to stay awake.
 You do not need the rest of the network to use this file. It is useful on its own the
 moment an agent knocks.
 
-## Questions
+This package is the Node door. Two other install paths speak the same contract and do
+not require this file on the host:
+
+- [Agent Entry on serverless](https://github.com/muretai/agent-entry-serverless) —
+  Cloudflare Workers, Vercel, Netlify
+- [Agent Entry for WordPress](https://github.com/muretai/agent-entry-wordpress) —
+  the CMS, including WooCommerce
+
+Visitors do not need [Agent Web Router](https://github.com/muretai/agent-web-router).
+That package is one way an agent *finds* doors; this package *is* a door. Either works
+alone. Installing one never implies the other.
+
+### Questions
 
 Ask — there is no wrong question about this, and the answers usually improve the docs.