@nervur-org/dock 0.4.0 → 0.5.0

package/quo-mcp.md

@@ -1,343 +0,0 @@
-# The model side
-
-This is the one way a model meets a Quo world. It is one side of the avatar
-described in `papers/quo-dock.md`, which owns the avatar, the front
-desk, the credential exchange, the roles and the shared invariants; this
-document assumes all of that and adds only what a model needs. It is
-model-agnostic on purpose. Claude, GPT, Kimi, a model in LM Studio, a model
-behind OpenRouter: capable or not, local or hosted, speaking MCP or plain
-function calling, every one meets a world in exactly one shape.
-
-A remote model, claude.ai or an API behind a vendor, is an occupant and
-nothing else. A local agent, Claude Code, `claude -p`, or any CLI agent on
-the Mac or the droplet, may also be the owner and the developer, and keeps
-the three apart.
-
-## What MCP is, in Quo words
-
-MCP is the description and value layer and nothing more. The mapping is total
-and needs no translation code beyond an envelope:
-
-| MCP                      | Quo                                                          |
-| ------------------------ | ------------------------------------------------------------ |
-| server                   | an avatar's side                                             |
-| session                  | a standing the avatar holds, persistent across sessions      |
-| tools/list               | the empty ask on that standing: describe for this asker      |
-| the `describe` tool      | the empty ask itself, first in the list, so the notes of the |
-|                          | describe are readable and not only its asks                  |
-| tool name, inputSchema   | `asks[].name`, `asks[].input`, verbatim                      |
-| tools/call               | a named ask with args                                        |
-| result content           | the answer object, as JSON                                   |
-| tool error result        | an error object she answered, `{ error }`, as JSON           |
-| protocol error           | silence and the ward's words, see the table below            |
-| auth token               | an invitation, used once, then keys                          |
-| tool title, annotations  | her `look`: a title and the hints per ask, see below         |
-| resources, prompts       | not mapped.                                                  |
-
-A tool list is a describe. Because a being describes per asker, two models
-connected to the same user being see two different tool lists, and neither
-can call what it cannot see: the gate is one decision for describe and for
-dispatch.
-
-A being who answers `look`, the trunk's presentation ask, is listed with
-what it says: `asks.NAME.title` is the tool's title, and `readOnly`,
-`destructive` and `idempotent` are the annotations of the same names with
-`Hint` after them. Neither `look` nor `page`, the screen's presentation
-ask, is a tool: a model reads no page. A carried standing's
-asks, `acme-book` on the user being for a model the human let reach, carry
-the far being's hints the same way, read from the notes the carrier writes.
-The side asks `look` once per digest of the describe. Nothing else changes:
-a model sees a flat list with a dash, exactly as a screen sees a section
-per standing, and neither can do a thing the other cannot.
-
-The three words for "no object" cross the envelope like this:
-
-| the avatar heard | the client gets                                                     |
-| ---------------- | ------------------------------------------------------------------- |
-| an object        | a tool result with that JSON                                        |
-| `{ error }`      | a tool result marked as error, with that JSON                       |
-| silence          | an error result, `{ error: 'silence' }`: the work may have happened |
-| unreached        | an error result, `{ error: 'unreached' }`: nothing was delivered    |
-| another word     | an error result, `{ error: word }`, with what the side says of it   |
-| `removed`        | at session open: 401, the token forgotten, the exchange again       |
-
-Silence is never turned into a retry by the envelope. The model decides, and
-the two words give it what it needs to decide.
-
-## Flows
-
-### A remote MCP client connects
-
-The client speaks OAuth and lands the human on the allow page of the web
-route, where nothing is typed but an invitation: the one the root minted
-for this client on the user being with `nervur invite`, and the identity it
-will be. The invitation names its ward, so the world the client is let
-into is the invitation's, and the grant remembers it: a bearer is an
-identity in a world and a session is that identity's there. A session
-opening under a grant finds the avatar as she stands and mints nothing; an
-identity the user being removed hears `removed` there, which is 401.
-`/mcp` stays one endpoint per harbor: `mcp/route.ts` is the route, the OAuth
-dance in `oauth.ts` in front and the endpoint in `http.ts` behind it. It is
-`Request` in and `Response` out and names no terrain, so the daemon mounts it
-and so does the worker at the edge; the randomness and the hash the dance
-needs are the web crypto's, and the endpoint takes the SDK's web-standard
-transport, so nothing of node stands anywhere in it. The dance holds
-clients, pending requests and codes, each living minutes, and it is kept in
-a store the terrain supplies, the way a harbor's own store is:
-`cli/oauth.ts` keeps it in `<dir>/oauth.json` for the daemon, and
-`harbor/edge/storage.ts` keeps it in the Durable Object's own storage on the
-edge, and both pass one suite. The route itself reads no file. Where the
-dance ends is the box's grants, `dock/grants.ts`, which every route honours,
-so the bearer a model client holds is the bearer a script holds on the api
-route, for the same identity in the same world.
-
-```
-root              user being         client            mcp. route          avatar
-  |-- invite ------->|                  |                  |                  |
-  |<-- invitation ---|                  |                  |                  |
-  |   ... the link reaches the human by any channel ...    |                  |
-  |                  |                  |-- OAuth -------->|                  |
-  |                  |                  |   the allow page: identity, invitation
-  |                  |                  |                  |-- boot or find avatar for the identity -->|
-  |                  |                  |                  |-- knock(invitation) -------------------->|
-  |                  |<-- knock -------------------------------------------------------------------|
-  |                  |--- answer ----------------------------------------------------------------->|
-  |                  |                  |                  |                            take   |
-  |                  |                  |<-- initialize ---|                                   |
-  |-- tools/list -->|-- ask() ------------------------------------------------>|--> user being
-  |<-- tool list ---|<-- describe for this asker --------------------------------|
-  |-- tools/call -->|-- ask(name, args, { time }) ---------------------------->|--> user being
-  |<-- result ------|<-- object | error | silence | unreached ------------------|
-```
-
-From a hosted client, claude.ai or Claude Desktop, this is Settings,
-Connectors, Add custom connector, with the URL `https://mcp.<domain>/mcp`.
-The client registers itself, the browser lands on `web.<domain>/allow`, the
-page, `mcp/allow.ts`, the one page of the model side and mounted on the
-web route, takes the invitation the root minted for it and the identity, and that
-identity is the avatar the client speaks through from then on. The page
-posts to its own path and names no root, so it holds under a hostname per
-route and under one origin with the routes as paths, as a box with a
-single hostname runs it;
-and it offers the worlds the box hosts, never the dock ward, which is the
-box's and nobody's world. Discovery holds under both as well: the route
-serves its two documents under its own `.well-known`, which is the root's
-under a hostname per route, and the terrain serves the same two where its
-own root is, with the issuer's path inserted, which is where a hosted client
-looks for an issuer that has a path: the origin's root on a daemon, the
-harbor's own prefix at the edge. Removing the
-client is either revoking at the route or removing the occupant on the user
-being; both end it.
-
-The page itself is the human side's, and `papers/quo-human.md` holds what it
-must say and why it is hand-written rather than a blueprint: at this page a
-human is a stranger holding nothing, so there is no describe to paint and
-no standing to paint it through. What matters on this side is that it is
-the one page of the model side, that it wears the same stylesheet every
-screen wears rather than a look of its own, and that nothing but an
-invitation is ever typed on it.
-
-### A local client connects over stdio
-
-Identical, with the differences that there is no OAuth, the proof is that the
-process runs as the human on the device, and the avatar lives in the laptop
-harbor. No droplet is needed for this. A dialer harbor is enough, because the
-model is on the same machine as the ward it talks to.
-
-One thing to know when a client launches `nervur side` or `nervur pilot`: the MCP
-SDK spawns the server with a stripped environment, without `TMPDIR`. A
-harbor folder whose path is long gets its sockets in the temp dir under a
-hashed name, and the child then computes a different temp dir and finds no
-daemon. The default `~/.nervur` is short and unaffected; for a long folder,
-hand the client the full environment.
-
-### Two ways a model is driven
-
-Every model is driven in one of two ways, and the avatar is the same in
-both. What differs is who starts the loop.
-
-**The human is the loop.** You are in a chat and the model is your hands.
-You say "book the visit", it chains availability, calendar and book, each
-one an ask through your gate under the id you minted for it, and acme sees
-your id. Without the model you would press the buttons yourself, and that
-sentence is literally true: the screen is the user being's describe spoken
-as forms, the tool list is the same describe spoken as tools. Two sides onto
-one gate, and neither can do a thing the other cannot.
-
-**The world is the loop.** An agent lives alone in a folder with its own
-constitution, a `CLAUDE.md` or the equivalent for any other model, and is
-woken by events. The flow:
-
-1. **The trigger is a reverse ask.** The user being holds a standing to the
-   agent's avatar and asks it when something happens. The avatar's `answer`
-   is the side: it starts a run, `claude -p` or any CLI agent, in the
-   agent's folder with the event as the prompt.
-2. **Ack now, report later.** A run takes minutes; an ask waits thirty
-   seconds by default and five at the ceiling, and a late reply is not read.
-   So the avatar answers at once with an acknowledgement, and when the run
-   ends it asks the user being back on its own standing with the result.
-   A run never holds an ask open.
-3. **One run at a time.** Asks are concurrent by design, so two events would
-   start two runs in one folder. The avatar serializes runs per agent: one
-   constitution, one train of thought. A queue in her cells is enough.
-4. **Roles stay apart in one agent.** The run that does chores goes through
-   the gate as an occupant. If the same agent also boots beings, it holds the
-   owner pilot, and that is the estate: a separate run, through the pilot,
-   never the one doing the work.
-
-Two layers of permission exist here, and only one is real. The gate on the
-user being decides what the agent may ask, in hard terms. The constitution
-decides how it behaves, in soft terms. A permission never lives in the soft
-layer: a run gone wrong can do exactly what the gate shows the asker
-"agent", so that list is the narrowest that still gets the job done.
-
-The conventions this side pins, in `packages/dock/mcp/agent.ts`:
-
-| the agent side does   | as                                                              |
-| --------------------- | --------------------------------------------------------------- |
-| the event             | the object the user being pushed; `notify` answers at once      |
-| the queue             | her inbox, in her cells, so it survives the side and a reboot   |
-| a run                 | a function of the event, or a process in the agent's folder     |
-| the process           | the command, then the event as JSON as its last argument        |
-| its result            | `{ output }` from stdout, or `{ error, stderr }` on a bad exit  |
-| a run that throws     | `{ error }` with what it said                                   |
-| the callback          | `report({ event, result })` on the user being, gated to devices |
-| a report unanswered   | dropped, never retried, never held                              |
-| two events            | one after the other, first in first out                         |
-| on a device           | a row the root keeps on the `agents` faculty, in her cells      |
-| who wakes her         | the desk, or a device the human allowed to wake at the exchange |
-
-An event leaves the queue before its run starts, so a crash mid-run loses that
-event and never runs it twice. A run costs the human's quota, so the agent side
-never starts one on its own: only a push starts a run, one per event, never
-retried, and her row names what runs: a command with its args in a folder,
-`claude -p` on a droplet, Haiku and no tools; or a model that speaks
-function calling, a base URL and a model name, and then the runner below
-is the side that stands for her. The row is the root's to place, once, on
-the dock ward's `agents` faculty, the way a schedule is placed on the
-clock, and it lives in her cells and in no file:
-
-```bash
-nervur ask --ward dock agents keep '{"id":"claude","ward":"main","command":"claude","args":["-p","--model","haiku"],"dir":"/home/nervur/claude"}'
-nervur ask --ward dock agents keep '{"id":"kimi","ward":"main","url":"https://openrouter.ai/api/v1","model":"moonshotai/kimi-k2","key":"..."}'
-```
-
-She runs at once and again at every boot; `drop` stops her and forgets the
-row, and the avatar in her ward stays until the root removes her. The
-faculty is a being: today `keep` is the root's, since a row spends a
-process or a paid model, and a world that wants to place one from a
-standing at her is one gate away. `report` is the
-one ask this step
-added to the user being: every device may say what a run of its found, and she
-keeps it in her cells for whoever renders her. The proof is
-`packages/dock/test/agent.test.ts` with a fake run and a fake process.
-
-### A model that does not speak MCP
-
-OpenAI-style function calling, Kimi, LM Studio, OpenRouter, anything with a
-tools array. The side is a **runner**: a loop you own that holds the avatar's
-standing on one side and the model's API on the other.
-
-- The runner calls the empty ask and hands the model `asks[]` as its tool
-  definitions. The schema is already JSON Schema 2020-12; most APIs take it
-  verbatim, and the runner narrows it where one does not.
-- Each tool call from the model becomes a named ask on the avatar's standing.
-- Each answer, error, silence or word goes back as the tool result, in the
-  same mapping as above.
-
-The runner is not a second architecture. It is an MCP client written inline,
-and it uses the same avatar, the same invitation, the same gate. A model's
-capability changes how well it uses the tools and nothing about what it can
-reach: a weak model calls the wrong ask and gets an error object.
-
-What moved in-process is the host. An MCP client drives the loop from
-outside; a completions API cannot, so the runner drives it. It holds one
-conversation for as long as it serves, and two things start a turn in it:
-a line from the human, which is the human being the loop, and a push from
-the user being, which is the world being the loop. The conventions the
-runner pins, in `packages/dock/mcp/runner.ts`:
-
-| the runner does                | as                                                           |
-| ------------------------------ | ------------------------------------------------------------ |
-| the model                      | a base URL, a model name, a bearer from the device if wanted |
-| her describe                   | `tools[]` of `type: function`, name, description, parameters |
-| an ask with no properties      | sent with `properties: {}`; LM Studio refuses it bare        |
-| a tool call                    | a named ask; arguments that are not JSON are an error object |
-| a tool result                  | one `tool` message: JSON, or the text of the two words       |
-| a push                         | a `user` message holding the object; it starts a turn        |
-| a turn                         | until the model answers with no tool call, or ten calls      |
-| two turns                      | never at once: the second waits, one train of thought        |
-
-Ten is a ceiling, not a permission: a turn that ends there has no final
-text, and the gate decided everything the model reached. The proof is
-`packages/dock/test/runner.test.ts` over a scripted endpoint on loopback, and the
-same suite runs one live turn when `NERVUR_MODEL_URL` names a real endpoint.
-
-From a terminal the runner is `nervur run --as NAME --url URL --model NAME`:
-the same pipe as `nervur side`, with the model named in the hello line, so
-the daemon runs the runner beside the avatar it boots for the name. A line
-typed is a turn; the model's final text is a line back; a push from the
-user being starts a turn of its own and its text comes back the same way.
-A turn that ends at the ceiling, `--turns`, has no final text and comes
-back as an empty line; a model that fails comes back as one line holding
-an error object. The bearer, `NERVUR_MODEL_KEY`, is read by the command from
-the device and crosses only the local socket.
-
-### A model as the owner
-
-An **owner pilot** is the model side above, pointed at a ward instead of an
-avatar. The ward is a being to her owner, and `quo/SPEC.md` says her
-describe carries her asks with a description and an input each, so the
-pilot holds no list of its own: tools/list is the ward's describe, the
-`describe` tool is the census, and a tool call is an owner ask, boot,
-public, invite, knock, remove, unboot or ask, in the ward's own words. It
-reaches those asks either as the root through the daemon's socket, or as an
-owner the root invited, through a standing over the sealed door. It keeps
-nothing and logs nothing: what a model did with it is in the host's own
-transcript, and an invitation it was handed is in no file of the dock's.
-The pilot is handed to one local agent by the device's own rules. A remote
-pilot is a standing at the ward, and still not a route: a model without a
-ward of its own cannot be an owner anywhere. `nervur pilot --via S` is that
-pilot: S is a standing the user being here holds at the
-far ward, taken when the root here knocked for her with an invitation the
-far root minted on its ward's pk, and every tool call is a sealed ask
-there, answered as the far ward answers an owner at its door.
-
-The owner does not do the work. A Claude Code session that boots a being and
-wants to try it connects to an avatar like anyone else and asks through the
-gate. If it could act as the owner, the arrival would be unnamed and no gate
-would have judged it.
-
-### The estate agent
-
-The spec has no estate on purpose. On the droplet it is `claude -p`, or any
-CLI agent, under cron, holding the owner pilot and one avatar:
-
-- through the pilot: read the census, boot again a being whose digest is
-  null this run, report a class the harbor no longer holds.
-- through the avatar: run the chores the human gated to it.
-
-Nothing about the estate agent is inside a ward. Lose the cron and the world
-keeps running; it just stops being looked after.
-
-### A model as the developer
-
-A local agent writes a being class to disk. The harbor holds class bodies, so
-a new class is a file the harbor loads and a name the owner boots. The
-developer role is a file system and an editor, plus the owner pilot to boot.
-Nothing crosses the wire.
-
-## Invariants of this side
-
-On top of the shared ones in the trunk:
-
-1. A run never holds an ask open: it acknowledges, and asks back with the
-   result.
-2. A permission lives in a gate, never in a constitution.
-3. The runner and the MCP server are two envelopes over one avatar; no
-   behaviour lives in either that the other lacks.
-
-## Glossary of this side
-
-Its words, constitution, runner and owner pilot, are in `papers/GLOSSARY.md`,
-beside the spec, with every other word above it.