# Changelog of the APC standard

This file records the contract that an app and an agent share in Agent Pointed Context: the view an app reports, the pin (focus) a person drops on a target, presence, the format of the focus, `wait_for_focus`, the tools an app and a hub expose, the drag payload and pairing. It does not record the software (Pulse, the dock, Signals, the extension, the desktop apps); that is [`CHANGELOG.md`](https://github.com/tineira/agent-pointed-context/blob/main/CHANGELOG.md) at the root.

The standard has its own semver, `APC_STANDARD_VERSION` in `@tineira/apc-protocol`, separate from the software release. It has been frozen since 1.0.0: from here a minor only adds, while a major may break inside the deprecation window. The version of the paper (V1, the apc.tineira.com demo) is not a 1.x of this standard. Every change to the contract adds an entry here and bumps the constant: a new minor for additions or a deprecation, or a new major for breaking changes. A patch never changes the contract; it fixes the packages or the wording.

## 1.1.1 (2026-11-16)

**M12 names the apps it binds.** At an app implementing Dock or still serving any Dock grant, every non-Dock grant, including a Direct grant, refuses an `initialize` carrying either binding key before any other answer, including while M8 omits `dock` from `apc.json` and during a hub's 60-second cache window. Only an app that does not implement Dock and holds no Dock grant owes no M12 refusal; it MAY refuse anyway. The spec and its restatements now carry this scope explicitly; this is a wording clarification with no contract, runtime or conformance changes.

## 1.1.0 (2026-11-16)

**The connection half is deprecated; nothing in the contract changes.** "What 1.1 deprecates" on the spec page carries the marking and is the authority on its extent: the Dock profile with the app's duties M1 to M13 and the hub's duties toward apps H1 to H10; four clauses of `apc.json` (`dock_connect`, a hub's `dock: { pair, confirm }`, leaving `dock` out of an `mcp.endpoints` entry on an exact path, and the answer owed a dock agent dropped on a Direct-only app); in the hub's trust model, the warning, the limits and the blocklist and the kill switch, each entire, with the one sentence that an unverified app **MUST** use HTTPS on a domain name and that its redirects are not followed, and the `app_not_allowed` and `https_required` codes answering it; and four error tables with the paragraph fixing `/apc/reader/status` at HTTP 200 `denied`. Out of *a hub, to an agent*, whose heading leaves it outside the 1.0 freeze but for H4 and H5, the two rows serving those duties are marked with them: the relayed `pairing` and `idle`, and `pairing_ended`. The list is a first instalment, not a complete inventory: a later minor marks what is still unplaced, and a marked definition is removed only once every clause depending on it has been marked and seen out a window of its own. Nothing is removed before it is marked. Until then every marked rule is unchanged and still binding: a party that conforms to 1.0.0 conforms to 1.1 without changing anything, no rule is relaxed, no pairing ends, and the conformance suite keeps exactly the checks it had for every deprecated rule, with the same limits of reach it already had. An app that wants to claim 1.1 changes only `standard`.

**What is deliberately not marked.** Untrusted marking stays, entire, and with it the sentences that define a verified and an unverified app and fix an app's identity as its domain: the rule is written in those words, and marking it while deleting its vocabulary would leave it pointing at nothing. `apc_link`, the browser extension and the sentences inside the core and the app-to-agent error codes that speak of a Dock grant (`pairing`, `idle`, `pairing_mismatch`) are left unmarked because whether each belongs to pointing or to connecting is still open; a later minor marks whichever of them moves, with a window of its own. Two things sit outside the frozen contract, so changing them needs no contractual deprecation: the hub's tools at the end of the Dock profile, and the rest of the table of what a hub answers an agent — its `app_unreachable` row, which serves untrusted marking and stays with it, and its reference rows. The profile word `"dock"` is not deprecated; only its definition moves.

**Why.** This standard is about pointing an agent at what a person is looking at. How an agent reaches an app, and how that connection is secured, is a separate problem with its own product and its own release line, and it had grown into the larger part of a document that is not about it. It moves unchanged to a Dock protocol published in its own right. `DESIGN.md` § 29 records the decision and what it costs.

## 1.0.0 (2026-11-15)

**The pairing contract is frozen.** 1.0 is 0.13 frozen under the new number, with no change to the contract itself. It freezes the core, Direct and Dock pairing (M1 to M13, H1 to H10), `apc_link`, `apc.json`, trust marking and unknown-field reading; the hub's agent tools and presentation remain outside the freeze. An app on 0.13 claims 1.0 by changing only `standard`, once it has dropped the 0.12 fallback this release ends. Future changes follow the spec's versioning and compatibility policy; the Dock first-pairing conformance floor remains 0.13.

**TIN-924's two fixes ship inside 1.0.0, without a 0.13.1.** `requestConnect` recognizes only the exact legacy JSON 404 (JSON media type, no BOM or duplicate keys), and conformance ties the owner's pairing code to the wire through transmitted-code freshness, re-consent, waiting-card and leak checks. The reference apps and Orders remove the one-release app-side rollback fallback and refuse a missing `/apc/connect`; the server package retains `legacyAbsent` for third-party apps talking to older hubs.

## 0.13.0 (draft, 2026-11-14)

**The conformance stand-in checks H9 tickets.** Its default `/apc/pair` refuses drop tickets as HTTP 400 `ticket_not_for_pairing` and connect tickets for another agent or origin as HTTP 400 `ticket_origin_mismatch`, leaving them unspent. Connect input validation and its post-manifest ticket recheck, pairing code and URL check order, and simulated Connect faults that preserve drop tickets have regression coverage. Pairing codes are required unless `pairingCode: "when_sent"` is explicit. M9 carries the raw hub through the 0.13 Connect server route and checks all three canonical hub URLs; Pulse and Signals' double-Allow tests use Connect. Tests needing a pre-0.13 hub explicitly select `legacy: "0.12"`, whose Connect response is exactly HTTP 404 `{"error":"not_found"}`. The stand-in deliberately accepts uncovered same-origin MCP URLs for M12's app-side isolation probe; it does not implement the full reference hub's trust policy or limits. This corrects the implementation within the unpublished 0.13.0 release; the contract and version stay unchanged.

**Origin-bound first pairing.** Drop tickets request Connect; only an owner-approved connect ticket bound to an app origin and agent can start `/apc/pair` (H9, H10). Apps declare fragment-free `dock_connect` and consume `#apc_connect` on their own session page (M13). `/apc/connect` adds bounded 120-second requests and the reader claim/check flow; `/apc/reader` is a hard-cut stub. New refusals are HTTP 400 `ticket_not_for_pairing`, `ticket_origin_mismatch`, `too_many_requests`. Existing pairings keep confirming and relaying; new first pairings need 0.13. 1.0 freezes 0.13. The temporary 0.12 fallback in `requestConnect` (`packages/server/src/hub-client.ts`) applies only on an HTTP 404 whose JSON body is an object with `error: "not_found"` (such as the 0.12 hub's `{"error":"not_found"}`), returning `hub_refused` otherwise.

- **Conformance coverage (`@tineira/apc-conformance`)**: hub conformance switches `pairingTicket` to `/apc/connect` + owner approve and adds **H9** (`ticket_not_for_pairing` and `ticket_origin_mismatch`, leaving mismatched/drop tickets unspent) and **H10** (connect tickets minted once per owner-authenticated approve and never exposed unauthenticated or in hub state/broadcasts). H10 requires `connectApproveEndpoint` and an authenticated `ownerFetch` probe: hostile `Origin` and `Sec-Fetch-Site` are tested independently with a valid owner session, followed by a same-origin approval as a positive control. Every string in the unauthenticated Connect response, including nested fields and decoded `#apc_connect` tickets, must fail `/apc/pair` before approval; fixture mutants verify CSRF guard removal and independently minted pre-approval leaks fail H10. App conformance adds HTTP and in-process **M13** checks (`dock_connect` valid, HTTPS, same origin, fragment-free, GET 200 without redirect, `Referrer-Policy: no-referrer`, and first drop calling `/apc/connect` instead of `/apc/pair`, while labelling the client-side `<head>` fragment script as reference behaviour); versioning advances `LAST_PRE_1_MINOR = 13` with a 0.13 floor for the Dock first-pairing checks so 0.10–0.12 apps keep passing existing checks with a pre-0.13 note.

## 0.12.0 (draft, 2026-11-14)

### The binding: a Dock grant goes live only for its own pairing (TIN-910)

Before, the hub's `initialize` named no pairing, so a hub could be handed, through `/apc/pair`, an MCP URL that the app had not given to that pairing (a Direct grant, another pairing's Dock grant, a copied URL), and the app served it. In the spec's [binding](https://apc.tineira.com/docs/spec#the-binding) and the Dock profile's M10 to M12 and H8 (`packages/protocol/src/core.ts`, `packages/protocol/src/dock.ts`).

- **H8. The hub names the pairing on every `initialize`**: `params._meta["apc.tineira.com/pairing_id"]` (`APC_PAIRING_ID_META`), the `pairing_id` it answered on `/apc/pair`, and `params._meta["apc.tineira.com/agent"]` (`APC_AGENT_META`), the pairing's agent handle, to every app. `/apc/pair`'s acknowledgement declares `binding: "pairing_id"` (`PAIRING_BINDING`). A `pairing_id` is 22 to 64 of `A–Z a–z 0–9 _ -` (`PAIRING_ID_RE`), holds at least 128 random bits, is unique across the hub, never changes while its pairing exists, and authorizes nothing at the hub. Neither value is a secret.
- **M10. The app records the binding.** Whether a grant is a Dock grant comes from the app's own record, never from its URL or the request. With the move out of in flight it stores the hub's origin, the agent, the `pairing_id` and whether `binding` was declared (`DockBinding`); they never change. An acknowledgement with any other `binding`, or a declared one with an id out of form, is a refusal (`declaredBinding`): an unknown scheme never downgrades an app silently.
- **M11. An `initialize` on a Dock grant that does not hold its binding gets HTTP 404**, the state unchanged (`bindingVerdict`, `dockGrantAnswer(state, call, { binding })`): a `pairing_id` or agent that is present and not exactly what the app stored (a value of another type or form included), or, on a declared grant in handoff, no `pairing_id`. A missing value is otherwise served, so a grant from before 0.12, a hub before 0.12 and a hub rolled back keep working. An app that allows more than one hub SHOULD also refuse a missing `pairing_id` on a declared grant in every state. Every `initialize` in a request counts (a batch, no `id`).
- **M12. On a grant that is not a Dock grant, an `initialize` carrying either key gets HTTP 404**, before any other answer (revoked included), and the grant is unchanged (`hasBindingKey`).
- **An app MUST ignore fields it does not know in a hub's answer** to `/apc/pair` or `/apc/confirm`; none changes what it stored for a grant, whose binding comes only from its own acknowledgement (the spec, "Every drop: `POST {hub}/apc/confirm`").
- The 404s SHOULD carry `{ "error": "pairing_mismatch" }` (`PAIRING_MISMATCH_ERROR`). Readers: `readBindingKey` (absent, invalid, valid), `hasBindingKey`, `rpcMessages`, `isInitializeMessage`.
- **Compatibility.** A hub before 0.12 sends neither key and declares no binding: a 0.12 app serves it as before. An app before 0.12 ignores both: a 0.12 hub pairs it as before, unchecked. **An app that validates `params._meta` strictly must accept the two new keys**, or the 0.12 hub's `initialize` fails and the pairing ends. Apps on 0.10 and 0.11 keep pairing with the reference hub, unchecked, for at least 6 months from this release, until 2027-05-14 (longer than the 3 months proposed for 1.0, by decision): the hub only counts the standard each app claims, and refuses nothing on it; ending the window takes a later release.
- **What it does not cover.** A drop's ticket can still be relayed through a real account on the app: someone with an account there takes the drop through the app's own consent and shows its code elsewhere. The binding passes then, since the app itself made the call. Closing that is planned before 1.0.

### The conformance suite checks what the 1.0 review found unchecked (TIN-912)

The rules an app implements do not change; the suite now fails an app that breaks some of them, where before it passed it. An app that met them passes as before.

- **A revoked grant answers revoked to every request, checked as such.** Besides `initialize`, `tools/list`, `tools/call`, GET and DELETE, the suite sends a revoked grant `ping`, `resources/list`, `prompts/list`, a notification and a body that does not parse, in process and over HTTP (`--revoked`), and each must get the `RevokedAnswer` with the binding's status; `revoked_by` must be the app's host (the host of the grant's MCP URL, with its port when it has one) and `message` a non-empty string: an app that leaves `message` out now fails (`checkRevokedBody`, `REVOKED_PROBES`).
- **No `then` on any `wait_for_focus` result with no focus.** The timeout, the wait a newer one took over, the refused wait and a cancelled wait that still answers are checked, each after a recent pin was read with the page open, so a `then` that should not ride would.
- **Nothing but grants under `P/{secret}`.** An app whose `mcp.endpoints` has a `{secret}` entry must not serve a child there that names no grant: a JSON-RPC POST and a GET get a 4xx, never a 2xx, a redirect or a 5xx (404 expected; another 4xx passes with a note) (in process, and `apc-json-secret-children` over HTTP, which needs no grant).
- **The Dock consent's nonce.** Through `dock.lifecycle.owner`: an Allow with the nonce left out, a forged one or another agent's sends the hub no `/apc/pair`; the right one does, once (`consent: an Allow pairs only with its own consent's nonce, once`). Without `dock.lifecycle` it passes with a note.
- **The revoked tool error may carry `structuredContent`.** The suite required it absent, which the spec never said and which runs against the `pairing` and `idle` errors carrying both. It now requires the `RevokedAnswer` and nothing else: in the text, and, when there, the same in `structuredContent`.
- **The command line says what it covered.** Under the pass and fail counts, `N of M checks ran (H of the T reachable over HTTP); K skipped, because:` with each reason and its count, and a warning that the run is not a conformance pass when more than half of the checks reachable over HTTP were skipped (the in-process ones never count, so a run with `--grant` and `--revoked` gets none); `coverage` in the report (`ran`, `total`, `skipped`, `skipped_why`, `in_process`, `http_ran`, `http_total`, `mostly_skipped`; `coverageOf`, `coverageLines`).
- **The timing bounds are named.** "Soon after" a pin, a revoke or a takeover is 8.7 s and "on time" is at most 4 s past `timeout_s`, as before; the conformance page says so, since the spec gives no number.

### The spec made coherent, the 1.0 scope and the compatibility policy (TIN-913)

Most of this is wording: the spec says what the reference already did. The bullets marked **changes the contract** are the ones an implementation may have to act on. In the spec, its [versioning and compatibility](https://apc.tineira.com/docs/spec#versioning-and-compatibility) and DESIGN.md section 27.

- **What 1.0 freezes.** The pairing contract between an app, an agent and a hub. The hub's tools for agents (its `get_current_view` with `views[]`, its `wait_for_focus`, `list_app_tools` and `call_app_tool`, the untrusted envelope, `page_reading` and `page_text`) are not normative until a later minor version, and the spec now says so. The spec no longer calls `@tineira/apc-protocol` the reference for everything: the page is the standard, and the package and the suite implement parts of it.
- **The force words are defined for every party.** MUST, SHOULD and MAY as in RFC 2119 and 8174, binding the party a sentence names (an app, its page, an agent, a hub, a dock's page); a hub's MUSTs bind although no suite checks a hub in 1.0.
- **Every reader ignores what it does not know**, stated once: a key in `apc.json`, a target, the view or focus, a presence event, a tool result or error, a hub's answer; a word of `profiles`; a presence `kind`; an error code (read as a refusal). Dropping an `mcp.endpoints` entry whole still wins: ignoring never widens.
- **Versioning and compatibility**, replacing "versioning and deprecation". From 1.0 a minor version only adds what readers ignore; deprecation is normative (one minor and 3 months at least); a hub or agent never refuses an app for an older minor of its major and reads a newer minor by the rules it knows; apps on 0.10 and 0.11 keep working with a 1.x hub for 6 months after 1.0; the previous major is kept 12 months; from 1.0 the suite passes a newer minor with a note. `standardSupport` in `@tineira/apc-conformance` already applies the from-1.0 rule to a 1.x suite; at 0.x a newer minor still fails (`packages/conformance/src/shared.ts`).
- **One table of error codes**, with who answers each and where, including the `apc_json_*` refusals and the hub's own codes, the reference ones marked as such.
- **Changes the contract: a target with no `id` and `params: {}` is refused.** It named nothing, and the spec already required an `id` or params; `parseTarget` and `parseFocusAttrs` took it (`packages/protocol/src/target.ts`).
- **The ceiling a page counts on.** A page the app ships learns the app's ceiling from its own code (`ceilingS`, `waitOpenLimitMs(ceilingS)`); a page that does not know it counts on `WAIT_CEILING_DEFAULT_S` (50 s), so an app whose wait events a page it did not write reads SHOULD keep its ceiling at 50 s or less.
- **Changes the contract: `T_ack` MUST be longer than the app's own deadline for the hub call (M3).** It was a rationale; an app with a shorter `T_ack` ended pairings whose acknowledgement came in time.
- **Changes the contract: an out-of-range `timeout_s` MUST be refused as invalid arguments**, never clamped or replaced by the default (what `@tineira/apc-server` already did, through its input schema). The conformance suite checks it for apps that claim 0.12 (`timeout_s` 0 and 1.5).
- **Changes the contract: a hub MUST mark everything an unverified app gives**, and not count its `then` or `page_open`; 1.0 freezes the marking, not the envelope's or the labels' shape.
- **What a minor version may not add:** a key inside an `mcp.endpoints` entry, or a new path form (older readers drop the entry), except beside an entry they understand; and a narrowing an older party cannot see it must take, unless that party declares it (as `binding`), or it is a major version.
- **`focusAttrs` writes no empty `data-focus-params`**, which no reader takes since this version.
- **`wait_for_focus` has one loop.** The reference description offered agents "running unattended" a loop on `page_open`, which the rule that no `then` rides on a result with no focus forbids; the sentence is gone (`packages/server/src/tools.ts`). There is no other loop: an agent waits only while `then` says so.
- **Clarified, as the reference does it:** `PresenceEvent.count` (how many distinct targets the call touched, at least the length of `targets`); a read of a target with an `id` names it in `targets`, a computation names nothing there; a re-drop on a pinned and read target is a new pin, unread; "trimmed per grant"; "at once" in a wait means within one poll; `then` is absent from a wait with no focus whatever ended it; `attention` rides only on results that serve app data (never in handoff or dormant); the revoked answer covers `ping`, any method, a notification and a body that does not parse, with a non-empty `message`, and a revoked tool error carries it in `content[0].text` (and MAY in `structuredContent`); an unknown bearer token is a plain 401 with `WWW-Authenticate: Bearer error="invalid_token"`; a bearer grant's id is random and stable, never derived from the token; a child of `P/{secret}` that names no grant answers 404; the server MUST make a grant only for its own consent's nonce, for that dock and agent, once; an app's MCP endpoint speaks Streamable HTTP and its `initialize` names `protocolVersion`, `serverInfo.name` and the `tools` capability; `mcp.path` starts and ends with `/`; the dock (not the payload) is what must keep secrets out of the drag; M6 lists four endpoints; the table's notifications are "served (202)", not "as 0.8".
- **`APC_DEFAULT_MCP_PATH`'s comment** no longer describes pairing a verified app without its file, a 0.5 rule that H7 replaced in 0.10 (`packages/protocol/src/manifest.ts`).

### Presentation moved to a non-normative UX guide (TIN-915)

The presentation rules of the spec, which were SHOULDs from 0.11 and prose beside them, move to [the UX guide](https://apc.tineira.com/docs/ux), non-normative: the conformance suite checks nothing in it, and `@tineira/apc-web` is its reference implementation. A rule that interoperability or security depends on stays in the spec. No wire format, tool, constant or check changes (`apps/dock/src/docs/pages/spec.md`, `apps/dock/src/docs/pages/ux.md`, `packages/protocol/src/core.ts`, comments only).

- **Now guidance, no longer SHOULDs.** That an app that shows a pet shows the APC pet; the header (up to 3 pets, "+N", the popover); the pin badge and its stacking; the motion rules; the colour scheme and `tint`; the phone layout of the pets (44 px targets); the logo cascade; the 8 pet states and their drivers. An app that did not follow them needed a reason before; it needs none now.
- **Now guidance, no longer described by the spec.** The consent's example sentence, the handoff card (the code large with a copy button, the time left), the countdown's rendering and words, `directOnlyNote` and `couldNotCheckNote`, the unverified warning's placement and weight, the extension's outline as an interaction.
- **Mobile loses its layout details, not its capability.** Still required: all agents shown in the page, the bar never collapsed or hidden, a finger can pin (tap the mark, then the target) and unpin, and Revoke by touch. The suite's `page.mobile` is unchanged and checks the first three (`agentBar`, `pinByTouch`, `unpinByTouch`), not Revoke by touch. Reachability while scrolling, finger-sized targets and the look of "tap to pin" are guidance; that an armed agent shows it and can be cancelled is a SHOULD.
- **Changed strength, stays in the spec.** Four rules that were SHOULDs and prose are now written with force words (**MUST**, **MUST NOT**, and **SHOULD NOT** for states, which stays advisory because apps in production still infer waiting), since something relies on each: marks carry `data-apc-mark` and `data-grant` (the extension finds an APC app by them); a page **SHOULD NOT** show a state the app's data does not give, nor guess one from timing, and **SHOULD** show `waiting` only from the wait signal (a page that infers waiting from grant use, a call heard lately or a `wait_for_focus` call, shows "waiting" when no wait runs and **SHOULD** move to wait events); a badge never suggests verification and no vendor's mascot is drawn; the agent bar offers Revoke for every agent. And the Direct profile's "the bar shows Direct agents in full, always" is now a **MUST NOT**: the bar is never collapsed or hidden while it shows a Direct agent, on any viewport.
- **Added.** Two **SHOULD**s: the consent names the hub's host from the drop, and where an app shows the pairing code it tells the person to type it only in their own dock and to Cancel if the dock does not ask. The dock's showing the app's host on every request, which the spec had as prose, is a **MUST**.
- **Unchanged.** The unverified-app warning: the domain first, **Not verified**, the app's own name as its own word, the risk and **Deny** as the default. The code only on the owner's page, the stored expiry hiding it, no dock grant shown as waiting, the extension's reading rules.

## 0.11.2 (draft, 2026-11-14)

A package patch: `@tineira/apc-web` and the wording only; the contract an app implements is the same as in 0.11.0 and 0.11.1 (TIN-903).

- **The pin badge's × never covers the mark on touch.** Under `APC_MOBILE_MEDIA` the × sat on the mark's corner with a 44 px hit area, so a tap meant to arm or drag the mark unpinned. It now sits beside the mark (24 px, its hit area stopping at the mark's edge), and the step between stacked badges on touch is `PIN_STACK_STEP_TOUCH` (72 px; `pinStackStep(touch)`, `pinBadgeX`). Desktop pointers are unchanged. The spec's wording of the pin badge says so (`packages/web/src/pin-badge.ts`, the spec).
- **`<apc-pets>`: a pin row can have no route, and the app can add its own links.** `pin.href: null` shows the pin as text, not as a button that goes nowhere; `links` puts the app's own links (for example "Manage agents") at the popover's foot (`apc-link` event, cancelable) (`packages/web/src/header-pets.ts`).
- **The armed mark wears `data-armed` and `aria-pressed` itself**, for pets, pin badges and the agent bar's marks, from `enablePinning`; an app needs no code of its own (`packages/web/src/armed.ts`, `packages/web/src/pinning.ts`). A pin badge's mark is now a `button` (it was an `img`), so `aria-pressed` is valid on it.
- **0.11.2 includes the `<apc-handoff>` card from PR 178** (`@tineira/apc-web`: `<apc-handoff>`, `handoffView`, `HandoffStrings`). It is in the package since the 0.11.1 tag was cut before it merged; the contract (pairing in § 4) does not change.

## 0.11.1 (draft, 2026-11-13)

A patch: the wording of M2 and the packages; the contract an app implements is the same (TIN-880).

- **M2 no longer names `redirect: "error"`, which Cloudflare Workers does not implement.** Workers throws a `TypeError` on it before anything is sent, so an app on Workers that followed the letter of M2 could never reach its hub. The rule is the same: never follow a redirect. Call the hub with `redirect: "manual"` (or `"error"` where the runtime has it), and refuse any 3xx, an `opaqueredirect` or `response.redirected` (`packages/protocol/src/dock.ts`, the spec).
- **`pairWithHub` and `confirmWithHub` call the hub with `redirect: "manual"`.** From 0.9.0 to 0.11.0 they asked for `"error"`, so on Workers every Dock pairing and confirm failed as `hub_unreachable` before it was sent. In Node and browsers they worked. A redirect is still refused, now as `hub_refused` on every runtime (Node used to report it as `hub_unreachable`) (`packages/server/src/hub-client.ts`).

## 0.11.0 (draft, 2026-11-13)

Wave 2 of the APC 1.0 track (TIN-880): the agent in the page (TIN-878), a presence kind for waits (TIN-886) and several MCP endpoints in `apc.json` (TIN-888). Each has its own subsection below.

### The agent in the page (TIN-878)

- **How an app shows each connected agent in its page is part of the standard, as SHOULDs.** An app may keep its own mark; an app that shows a pet SHOULD show the APC pet: in the header up to 3 pets, then a "+N" (or list) button that opens a popover, a pin badge with × on the pinned element (the app places several side by side), the pets and badges being marks, and a pet only a mark (a tap arms it, it never opens the popover) (`data-apc-mark`, `data-grant`). On a phone the pets stay in the header and every tap target is at least 44 px. Logos are brands only, never a vendor's mascot.
- **The 8 states and what drives each in an app** (`petState`, `PetInput`, `PET_STATES` in `@tineira/apc-web`): dragging, pairing, offline (no client, or revoked), pinned (an unread pin), calling (a call in flight or just heard), read (shown for `READ_HOLD_MS`), waiting (an open `wait_for_focus`, only from the page-readable wait signal, never inferred from timing), idle. Every input is optional and defaults to "not happening".
- **Motion**: one `requestAnimationFrame` loop per window, stopped while the page is hidden, slower once every pet is calm, a still pose with `prefers-reduced-motion`.
- **Colour scheme (SHOULD follow the page)**: the light pet on light pages, the inverse pet on dark ones (a near-white body, a dark outline and eyes, a thin outline on the badge's disc); the state marks do not change. `scheme: "light" | "dark" | "auto"` (`resolvePetScheme`, `petPalette`), and `tint` or `--apc-pet-body` / `--apc-pet-line` for a strict palette.
- In the spec's "The agent in the page" and the integrate guide.

### Wait events on the presence channel (TIN-886)

Before, a page could not tell whether its agent was listening, so apps guessed from recent calls (75 s, 5 minutes) and showed "waiting" with no wait running. In `packages/protocol/src/presence.ts`, the spec's [presence](https://apc.tineira.com/docs/spec#presence) and DESIGN.md section 24.

- **A presence kind `"wait"`**: `PresenceWaitEvent`, `{ v: 1, grant_id, at, kind: "wait", state: "open" | "closed" }`, ids only, no targets, on the existing presence stream with its read and write rules. `PresenceMessage` is either kind; `parsePresenceWaitEvent` and `isPresenceWaitEvent` require those five keys, strictly, and drop any other (an app sends exactly the five; the conformance suite checks that). `PresenceEvent` is unchanged.
- **Optional, with an atomic place.** An app **may** send wait events, and only if it claims and releases its place for a wait atomically; an app that cannot **must not**. A page that gets none shows no "waiting". An app that sends any **must** follow every rule below.
- **When.** An app that sends them **must** send `open` when a `wait_for_focus` claims the grant's place, and `closed` when it gives it up: on return, timeout, cancel, or the grant revoked or deleted. A refused wait (within the gap, or on a revoked grant) sends nothing. **Only an app whose place for a wait tells takeovers and releases atomically sends wait events**; one that checks and then releases in two steps sends none. A takeover sends the old wait's `closed`, then the new wait's `open`, both at the claim, and the old wait sends nothing later.
- **Expiry.** A page **must** treat an `open` as closed once it is older, on the page's clock from arrival, than the app's ceiling (`WAIT_CEILING_DEFAULT_S`, 50 s, unless the app sets its own) plus `WAIT_EVENT_MARGIN_S` (10 s; `waitOpenLimitMs`), so a lost `closed` cannot leave it "waiting" for ever. An app **should** tell a page that connects mid-wait. An `open` for a wait already open keeps the page's first arrival.
- **Dock grants.** A page **must not** show a dock grant as waiting: its agent waits on the hub, and the app sees only the hub's relays.
- `@tineira/apc-server`: `presenceWaitEvent`; `AtomicWaitSlot` (`atomic: true`, a claim that reports `tookOver`, a release that reports whether the token held the place) and `isAtomicWaitSlot`; `announceWaits(slot, grantId, publish)` sends the events from an `AtomicWaitSlot` and returns any other slot as it is, sending nothing; a release that throws still sends `closed`. `registerApcTools` takes `waitPresence: { grantId, publish }`. `MemoryWaitSlots.for` is atomic and keeps the closed of a grant forgotten mid-wait, and `MemoryWaitSlots` has `held(grantId)`. The default ceiling is `WAIT_CEILING_DEFAULT_S`.
- `@tineira/apc-web`: `foldWaitEvent` (a repeated `open` keeps the first arrival), `waitOpen` (what a pet's `waiting` input takes), `nextWaitExpiry`, `dropExpiredWaits` and `agentWaitOpen` (an agent shown as one, its Direct grants only: the pet's `waiting` in the Orders example); `flashTargets` takes any `PresenceMessage` and ignores wait events.
- `@tineira/apc-conformance`: `takePresence()` returns `PresenceMessage[]`. Five checks, on the Direct profile of an app that claims 0.11.0 and sends wait events. Any wait event the page gets anywhere in the run, on any agent and in any check, counts; one short wait on the first check's agent gives the app its chance. An app that has sent none passes them with the note "not checked: the app sends no wait events", and a last check fails the run if a wait event comes after they passed that way. They are: a wait sends `open`, then `closed`; a takeover sends `open, closed, open, closed`; a cancelled wait sends `closed`; a wait cut by a revoke sends `closed`, and a wait on the revoked grant nothing; a refused wait sends nothing.

An app before 0.11 sends no wait events, and its pages are not affected by them. An app may claim 0.11.0 without sending them (a store whose wait rows are not atomic, say); the conformance suite then passes the wait-event checks with a note, and holds an app that sends any wait event to every rule.

### `mcp.endpoints`: several MCP endpoints on one origin (TIN-888)

- **`apc.json` may list an origin's APC endpoints exactly**: `mcp.endpoints: [{ path, profiles }]`, at most 16 (`APC_MCP_ENDPOINTS_MAX`). A path is exact. `{secret}` as its last segment stands for one grant's secret, 16 to 128 of `A-Z a-z 0-9 _ -` (`APC_SECRET_RE`). When the list is there, only it covers an MCP URL for a 0.11 reader, never `mcp.path`. `mcp.path` stays valid and optional beside it, and every usable entry must lie inside it.
- **The match is by string.** The URL has no `?`, `#` or `%`, and equals its parsed `href`. An exact entry covers only a URL its grants share (`shared`). A `{secret}` entry covers one segment that fits the secret, unless the path is named by any entry (exact wins, compared without ASCII case). The top level and the entry must both list the profile. A hub pairing a Dock app checks `dock`.
- **Forward compatible without widening.** An entry with another key or another path form (a trailing `/`, `//`, another `{…}`) is dropped whole. Unknown profile words, and `dock` on an exact path, are left out. Malformed input (`%`, `?`, `#`, `\`, a dot segment, a duplicate, wrong types) makes the file invalid. A file with no usable entry parses and covers nothing.
- **API.** `declaresMcpUrl(manifest, url, options)` now **requires** `options.profile` (`"direct"` or `"dock"`). Under `mcp.path` alone it plays no part, and the 0.10 rule is unchanged. Without it, a file with endpoints covers nothing, and so does a manifest that skipped the parser and has an `endpoints` key that is not a list (never a fall back to `mcp.path`). A caller of 0.10 that checked a Dock grant passes `{ profile: "dock" }`; one that checked a shared Direct URL passes `{ profile: "direct", shared: true }`. New: `mcpUrlCoverage` (covered, and by what, or why not), `endpointRule`, `usableEndpoints` and `describeMcpCoverage`. `ApcManifest["mcp"]` is now `{ path?: string; endpoints?: ApcMcpEndpointEntry[] }`: `mcp.path` may be absent.
- **The spec states the parse and the match as MUSTs, with test vectors** (`packages/protocol/test/mcp-endpoint-vectors.json`, the same rows).

## 0.10.0 (draft, 2026-11-13)

The Dock profile as built (TIN-882): a dock grant has states, each state answers in a fixed way, and the hub and the app have MUSTs around the hub call. Before, the profile said how a pairing starts and not what a grant answers between the Allow and the hub's first `initialize`: one app served data in that window, two had no gate at all. In `packages/protocol/src/dock.ts` and `core.ts`, the spec's Dock profile and DESIGN.md section 22. The binding stays the secret MCP URL; other bindings are left open for future versions.

### Grant states

- **A dock grant is `in_flight`, `handoff`, `live`, `dormant`, `ended` or `revoked`, in that order of precedence from the last** (`DockGrantState`, `DOCK_GRANT_STATES`: revoked > ended > in_flight > handoff > dormant > live; `dockGrantStateOf`). In flight runs from the Allow to the hub's acknowledgement; handoff from the acknowledgement to the first committed `initialize`; live from then on; dormant (SHOULD) after `T_idle` with no wake action; ended after `T_ack` (at most 30 s, `T_ACK_MAX_MS`) still in flight, after `T_connect` (at most 10 minutes, `T_CONNECT_MAX_MS`) in handoff, on a give-back, or after long dormancy; revoked on the owner's Revoke or on Cancel.
- **Each state answers in a fixed way** (`dockGrantAnswer`, MUST wherever the state is implemented; `dockGrantCallOf` classifies a JSON-RPC message, a message with no `id` or any `notifications/*` method being a notification). In flight and ended answer HTTP 404 to every request, whatever its method, a `GET` or a body that does not parse included; revoked answers `RevokedAnswer` as in 0.8; live serves. Handoff serves `initialize` (which commits the connection), `ping` and `tools/list`; a `tools/call` is the tool error `{ error: "pairing", message }`, another method JSON-RPC -32000 with that as `data`, a notification 202. Dormant serves `initialize` (without waking), `ping` and `tools/list`; the core tools answer their idle shapes; another tool is the tool error `{ error: "idle", message }`, another method -32000. No answer in handoff or dormant carries `attention`, `then`, an `apc_link` offer or a presence event.
- **The idle shapes** (MUST for an app that sleeps): `get_current_view` answers `{ view: null, focus: null, idle: true, note }` (`idleCurrentView`), `wait_for_focus` `{ focus: null, timed_out: false, page_open: false, idle: true, note }` (`idleWaitForFocus`). They are the types `IdleCurrentView` and `IdleWaitForFocus`: `CurrentViewResult` becomes `CurrentViewAnswer | IdleCurrentView` and `WaitForFocusResult` gains `IdleWaitForFocus`, so an idle answer can carry no data and no timeout. An answer without `idle` (a 0.9 app) reads as before. `isIdleAnswer`, `isPairingAnswer`.
- **Tool errors** (`DockGrantErrorAnswer`) are carried in both `structuredContent` and `content[0].text` (JSON), with `isError: true`.
- **Transitions.** `initialize` fails closed: no result unless the move out of handoff committed (on a persistence failure, JSON-RPC -32603 or HTTP 500), and the commit is conditional on the grant being neither revoked nor ended in the same atomic step. The acknowledgement's move from in flight to handoff is conditional the same way. A served call is a `tools/call` that returned app data while live. Wake actions are the owner's authenticated page heartbeat (at least every `T_idle / 2` while the page is open) or a confirmed drop; agent traffic never wakes or extends a grant. Cancel revokes, only in handoff before any served call, atomically.
- **Recommended times**: `T_idle` 30 minutes (`T_IDLE_RECOMMENDED_MS`), long dormancy 30 days (`LONG_DORMANCY_RECOMMENDED_MS`).

### The hub (H1 to H7)

- **H1.** The hub sends `initialize` on a grant only after the dock owner approved with the code, and nothing before; while approving, the dock takes no code. **H2.** `/apc/confirm` expires overdue requests before it answers. **H3.** One pending request per (agent, app origin): `/apc/pair` replaces an unapproved one (never an approving or paired one), outside the cap, giving its URL back afterwards when it differs, the new one's wrong-code count at 0. **H4.** `pairing` and `idle` are relayed as tool errors (in the envelope for an unverified app), `idle: true` per app in `views[]`, an idle answer never ends the hub's wait or reads as page closed, and an all-idle wait answers the idle shape. **H5.** A 404 from a pairing introduced or in handoff is `pairing_ended` (`PAIRING_ENDED_ERROR`), with an `ended` tombstone. **H6.** The instructions and guide say what `idle` and `pairing` mean. **H7.** The `apc.json` copy for a pairing decision is at most 60 s old (`APC_JSON_PAIRING_MAX_AGE_S`), and an unreachable one refuses the pairing (`apc_json_unreachable`).

### The app (M1 to M9)

- **M1** a constant allowlist of hub origins, parsed with `new URL`, on the drop and the Allow (`hub_not_allowed`); **M2** no redirects; **M3** one deadline of at most 10 s for headers and body (`HUB_CALL_DEADLINE_MS`); **M4** at most 8 KiB read (`HUB_ANSWER_MAX_BYTES`), with a strict `content-length` rule; **M5** no lock held across the hub call, one drop, Allow or confirm at a time per (user, hub, agent); **M6** the owner-session endpoints are `POST` `application/json`, refuse a foreign `Origin` or a cross-site `Sec-Fetch-Site`, and take a request with neither on the session alone; **M7** `/apc/revoke` answers the same 200 to anything and ends a matching grant in any state but revoked or ended; **M8** `apc.json` lists `dock` only while the app can pair, cached 60 s at most; **M9** hub requests go to the parsed origin.

### One pending pairing

Before the acknowledgement a new drop replaces the pending consent (the stale Allow is `consent_expired`); a second Allow is `pairing_in_progress`. After it and before `initialize`, a drop asks `/apc/confirm`: `pending` with the app's own expiry ahead shows the same code and the time left; `not_paired` or a passed expiry ends the grant and starts a fresh consent; `paired` keeps the grant in handoff until `initialize`. The page treats its stored expiry as the truth.

### Packages

`@tineira/apc-protocol`: `dock.ts` (the states, the answer table, the tool errors, the idle shapes, the time limits, `PAIRING_ENDED_ERROR`, `DockDropError`, and the H and M rules in prose). The drag payload moves here from `@tineira/apc-web`, unchanged, so an app's server can check a drop with the page's grammar (`drag.ts`: `AgentDrag`, `APC_AGENT_TYPE`, `agentDragPayload`, `parseAgentDrag`, `parseAgentDragPayload`, and the grammar as `AGENT_HANDLE_RE` and `DRAG_TICKET_RE`); `@tineira/apc-web` re-exports it. `HubCallError` gains `hub_not_allowed` (a hub that is not a bare origin: nothing is sent).

`@tineira/apc-server` (TIN-883):

- **`pairWithHub` and `confirmWithHub` follow M2, M3, M4 and M9**: the call goes to the hub's parsed origin (`hubCallOrigin`; anything but a bare `https:` origin, or `http:` on a loopback host, is `hub_not_allowed`, nothing sent); a 3xx, `opaqueredirect` or `redirected` answer is `hub_refused`; one deadline of at most 10 s covers the headers and the whole body (`hub_unreachable`); a `content-length` that is not digits or is over 8 KiB is refused before reading, and the decoded body is read as a stream and cut at 8 KiB (`hub_refused`), with an absent `content-length` taken and never compared.
- **`toolError` sets `structuredContent`** with the same `{ error, message }` as its text. MCP SDK clients validate `structuredContent` against a tool's `outputSchema` even on `isError`, so a tool that declares one must admit `{ error, message }` (for a JSON Schema, `{ type: "object", anyOf: [own, errorShape] }`), and a core tool's must admit its idle shape, or the client rejects the error.
- **`parseDockDrop(body, { hubs, localDevHubs })`** (M1): the hub parsed with `new URL`, `https:` (or a listed loopback origin), no userinfo, path, query or fragment, written as its own origin, and exactly equal to one on the allowlist; the agent and ticket in the drag grammar. It answers `{ ok, hub, agent, ticket }` or `hub_not_allowed` / `invalid_drop`; call it on the drop and again on the Allow.
- **`handleDockGiveBack(request, { origin, endGrantBySecretHash })`** (M7): `POST /apc/revoke` answers the same 200 to any input, reads at most 4 KiB within 5 s, and hands the app the `secretHash` of the URL's secret to end that grant unless it is revoked or ended; it never logs the URL.
- **`dockGrantGate(state, message, { host })`** and **`dockGrantToolResult(state, tool)`**: the answer table as a gate for an app's MCP handler, with the exact HTTP 404, 202, `RevokedAnswer`, JSON-RPC -32000, `pairing` / `idle` tool error or idle shape; a request method without an id is another method, never served by a grant that is not live. Such an answer is returned as is, before the app's wrapper (no activity stamp, presence, `attention`, `then` or `apc_link`): the app's obligation, documented.
- **The derived-secret recipe** (optional): `deriveDockSecret(key, appTag, grantId, salt)` (a `grantId` of 1 to 80 of `[A-Za-z0-9_.:-]`), `dockSecretHash(secret)` and `newDockSalt()`, Web Crypto only.
- **`apcJsonResponse` caches `max-age=60`** (was 300; M8, H7).

The reference hub and apps, and the conformance checks, follow in their own changes.

An app that implements 0.9 keeps working with a 0.10 hub: its answers carry no `idle`, and read as they did. To claim 0.10.0 it implements the states it uses as the table says, and M1 to M9.

## 0.9.0 (draft, 2026-11-12)

The pairing code: on the Dock profile the app's consent shows a code, and the dock's Allow requires it (TIN-859). A drag can be put on any page, and anyone who runs a dock can mint tickets for their own agent; before, they could lure an app's owner into a drop and an Allow and get their own agent paired with the owner's data. In `packages/protocol/src/core.ts`, `packages/server/src/consent.ts`, `packages/server/src/hub-client.ts`, `packages/conformance` and DESIGN.md section 12.

### Pairing

- **The app shows a pairing code with its consent, and sends it to the hub.** Six characters of Crockford base32 (`PAIRING_CODE_LENGTH`, `PAIRING_CODE_ALPHABET`, 30 bits), new for every consent, shown as `K7M-4P2` (`formatPairingCode`) with the warning to type it only in the person's own dock. After the Allow the app sends it raw in `pairing_code` of `POST {hub}/apc/pair` (`DockPairRequest`). An app that implements 0.9 **must** send it. The code never goes over MCP, in a URL, to `/apc/confirm` or anywhere but the app owner's page and that one request.
- **The hub keeps it and answers `pairing_code: "required"`** (`PAIRING_CODE_ACK`, `DockPairAnswer`), never shows it (not in the dock's state, a broadcast or any answer), and checks the body before it spends the ticket: a `pairing_code` that is present but not a code (`null`, `""`, a number) is `invalid_pairing_code`. Only an absent key is a pairing without a code; a hub may refuse those (`pairing_code_required`).
- **The dock owner's Allow needs the code.** The hub compares it in constant time (`pairingCodesMatch`) with what the app sent; a missing or malformed code is refused without counting; a wrong one counts, `wrong_pairing_code` with `attempts_left`, and the fifth (`PAIRING_CODE_MAX_ATTEMPTS`) removes the request and gives the grant back (`pairing_code_refused`). A request with a code that nobody approves goes after `PAIRING_CODE_TTL_MS` (120 s), its grant given back; one without keeps the old ten minutes. Deny and unpair need no code. Typing is forgiving: case, spaces and dashes are ignored, O reads as 0 and I or L as 1 (`normalizePairingCode`).
- **The app keeps a grant only on the acknowledgement**: a non-redirected HTTP 200 with `ok: true`, `pairing_code: "required"` and a string `pairing_id`. A hub's own refusal is HTTP 400 with `ok: false` and its error. Anything else (another status, a redirect, a missing acknowledgement, no answer) and the app deletes the grant before it answers its page (`hub_refused`, `hub_unreachable`, `hub_ignores_pairing_code`, `HubCallError`). `/apc/confirm` is believed the same way: 200, `ok: true`, `status` `"pending"` or `"paired"`.
- **A drag's ticket lives 240 s** (`TICKET_TTL_MS`; it was 60 s), longer than the app's two-minute consent, so the person has the time to read the card.
- **What the app shows after the Allow** (reference behaviour, not a MUST): the code again, the time left, and Cancel, until the hub connects (its first `initialize` on the grant) or the grant goes; if the person's own dock never asks for that code, the agent was someone else's.

### Packages

- `@tineira/apc-server`: `DockConsent.ask` returns `{ nonce, pairing_code }`, and `take` is replaced by `takeConsent`, which returns `{ ok: true, pairing_code }` or `{ ok: false }` (no boolean to test by mistake): every caller has to show the code and send it. New: `newPairingCode`, and `pairWithHub` / `confirmWithHub` (`redirect: "error"`, a 10 s limit, the rules above).
- `@tineira/apc-conformance`: `standInHub`, a hub to pair with in process, faithful on tickets, the code, wrong codes, expiry, the give-back and the acknowledgement, with broken modes (`no_ack`, `redirect`, `error_500`). An adapter on the Dock profile gives `dock: { hub, drop }`, required of an app that claims 0.9.0 or later (as `page.mobile` since 0.6). New checks: the consent shows a well-formed code and the app sends that code; every consent shows a new code; a hub that does not acknowledge, redirects or says yes with a 500 holds no grant; five wrong codes or the code's expiry give the grant back; the right code pairs.

An app that implements 0.8 keeps pairing with a hub in its default mode (`when_sent`), without a code, until the operator requires one; to claim 0.9.0 it shows and sends the code and fails closed on the hub's answer.

## 0.8.0 (draft, 2026-11-12)

The core tools made robust, from a second implementation in use, and the Direct profile freed from how the agent authenticates (TIN-839, TIN-667). In `packages/protocol/src/core.ts`, `manifest.ts`, `packages/server/src/tools.ts`, `waits.ts`, `packages/conformance` and DESIGN.md section 21.

### The loop

- **`then` only after a recent pin.** A result carries `then` only while a page of the person's is open (and shared) **and** the grant was pinned within the app's window, read or unread (`THEN_PIN_WINDOW_MIN`, 30 minutes unless the app sets its own; `thenApplies` in `@tineira/apc-server`). An open page with no recent pin gives no `then`, so an agent no longer waits after every answer. Before, an open page was enough.
- **Wait in the background.** The instructions (`APC_INSTRUCTIONS`), the `guide` prompt, the `then` note and `wait_for_focus`'s description tell the agent to run the wait in the background if its client can (a background subagent, say), and otherwise to keep it short and never chain waits (`WAIT_IN_BACKGROUND`). The default timeout stays the app's: 25 to 45 s suits a conversation.
- **One wait per grant.** At most one wait of a grant delivers. A new wait takes over: the one it replaces ends at its next check with `focus: null, timed_out: false` and a note, delivers nothing and marks nothing seen. A new wait within `WAIT_CLAIM_GAP_S` (2 s) of one still running is refused instead, with `focus: null, timed_out: false, retry_after_s` (new in `WaitNoFocus`) and a note, so two waits fired together do not take over from each other in a loop. A wait whose request the client cancels stops and frees its place at once: MCP's `notifications/cancelled`, which reaches a stateless server in a POST of its own (`InflightCalls` keeps the calls in flight per grant to find the one it names), and an HTTP abort where the host reports one.
- **Seen once delivered.** Checking for a pin, or polling for one, never marks it seen: only returning it does. An app marks a pin seen only once the result that carries it is final (in a wait, after it gave its place up and checked once more that its request was not cancelled), and marks that exact pin by its `pinned_at`, never a newer one dropped meanwhile. The result goes out whether or not the mark succeeds. So a pin may be delivered twice, and is never lost to a wait that was taken over or cancelled, or to a newer pin. MCP has no acknowledgement: a result lost after the app sent it, with no abort the app could see, cannot be told apart, and that pin is marked seen. Before, the reference marked the pin seen inside the tool, before the result left, so a wait the client had given up on, or a newer pin dropped between the read and the mark, could be lost.
- **Unavailable has its own shape, and trim never fails the read.** A core tool the app cannot answer just now still answers in its own shape with a `note` (new, optional, in `CurrentViewResult`): `{ view: null, focus: null, note }`, or `{ focus: null, timed_out: false, page_open: false, note }`; never a tool error or an `{ ok, reason }` of the app's own. A check on one item of the answer that cannot run hides that item and the rest answers; it never fails the read open, and a defect in one check never fails it whole (guidance, not wire format).

### The Direct profile, whatever the auth

- **What a grant must be** (`GrantRequirement`, `GRANT_REQUIREMENTS`): a stable id per agent connection (pins, views, presence and `apc_link` are keyed by it); revocable from the app alone, checked on every request and before and after each tool, and revoking ends what could bring it back without the person (with OAuth, its refresh tokens and authorization); revoked told apart from expired or unknown; trimmed per grant, so pointing grants no access. Any binding that meets them will do. The secret URL (`newDirectGrant`, `directMcpUrl`) stays the reference apps' binding; OAuth 2.1 (one MCP URL shared by every grant, the bearer token naming the grant) is another.
- **The revoked answer's status is the binding's.** Every binding answers a revoked grant with the `RevokedAnswer` body. The status is 403 with a secret URL (`REVOKED_HTTP_STATUS`, unchanged) and 401 with `WWW-Authenticate: Bearer error="invalid_token"` with a bearer token (`REVOKED_HTTP_STATUS_BEARER`). An unknown or expired grant answers without a `RevokedAnswer`.
- **`apc.json`.** A Direct app whose grants share one URL may serve it at `mcp.path` itself or at `mcp.path` without its last `/`; one origin may serve several such endpoints under the path, one per role (`declaresMcpUrl(manifest, url, { shared: true })`; a hub pairing a Dock app still requires one URL per grant). `direct.auth` (a short word such as `"url"` or `"oauth"`) and `direct.resource_metadata` (with OAuth, the protected-resource metadata URL on the origin) may say how agents authenticate, as information only: a reader never requires them.
- **Hosts with no long-lived process.** An app on stateless functions bounds `wait_for_focus` by its function's time limit (its own ceiling for `timeout_s`), tells a closed page from a heartbeat, and checks the grant before and after each tool call.

### Conformance

- A connection may carry headers: `AgentConnection.headers` (`{ authorization: "Bearer …" }`), and the CLI takes `--bearer-env <VAR>` and `--revoked-bearer-env <VAR>`, the name of an environment variable that holds the token (never the token itself on the command line; it is never printed). With a bearer token the revoked checks expect 401, the grant's URL may be `mcp.path` itself, and the unknown-grant 404 check is skipped.
- New checks of an app that claims 0.8.0 or later: an open page with no pin gives no `then`; a newer wait takes over and the older one delivers nothing; a second wait right after the first is refused with `retry_after_s` and the first still delivers; a wait cancelled by `notifications/cancelled`, and one cancelled by an HTTP abort, marks nothing seen and frees its place. Of an app that claims less, those checks pass with a note that they did not apply. The `then` check pins the agent first.

An app that implements 0.7 keeps working with agents and docks unchanged; to claim 0.8.0 it adds the `then` window, one wait per grant, and seen once delivered. `@tineira/apc-server`'s `ApcToolContext` now requires `waitSlot` (`MemoryWaitSlots.for(grantId)` for an app whose waits run in one process), takes `signal` (the request's, with `InflightCalls`' for MCP's cancel), and calls `markSeen(pinnedAt)` with the pin it delivered.

## 0.7.1 (draft, 2026-11-04)

No change to the contract: an app or a hub that implements 0.7.0 implements 0.7.1, and `standard` in `apc.json` may say either. This is the first release of `@tineira/apc-protocol`, `@tineira/apc-server`, `@tineira/apc-web` and `@tineira/apc-conformance` published by `.github/workflows/publish.yml` (npm trusted publishing) rather than from a maintainer's machine.

- **The package names in the doc comments are the published ones.** `core.ts` and `manifest.ts` (and so the `.d.ts` files in `dist/`) named `@apc/server`, `@apc/web` and `@apc/conformance`, from before the rename; they now say `@tineira/apc-server`, `@tineira/apc-web` and `@tineira/apc-conformance`.
- **The conformance checks take a newer patch of their own standard.** An app whose `apc.json` says a newer patch of the minor `@tineira/apc-conformance` knows (0.7.2 against 0.7.1) passes the standard check with a note, since a patch never changes the contract; a newer minor still fails until the checks are updated. Before, an app that moved to 0.7.1 failed against the 0.7.0 checks. The in-process suite keeps the note too: after `run()`, the check's `note` says it, and `runConformance` puts it on the result. (`standardSupport` in `packages/conformance/src/shared.ts`, `packages/conformance/src/index.ts`)
- The four packages and `APC_STANDARD_VERSION` are 0.7.1; nothing else in what the packages ship changed.

## 0.7.0 (draft, 2026-11-04)

Consent in the app, checked by the app's server, and revoke told by the grant itself (TIN-606). In `packages/protocol/src/core.ts`, `packages/server/src/consent.ts` and DESIGN.md section 14.

- **Consent in the app is the app's server's to check (the Dock profile).** An app makes a grant for a dock agent it holds no grant for only on a request that proves the person allowed it on the app's page just now, whatever the page last loaded: a page that missed a revoke, or a pairing the dock forgot, must not pair without asking. The reference apps send every dock drop to their server; for an agent with no grant it answers `consent_required` (`CONSENT_REQUIRED`) with a nonce, the page shows its consent with it, and the Allow sends it back. `DockConsent` in `@apc/server` gives and takes the nonce: 128 random bits, once, for the same dock and agent, within `DOCK_CONSENT_TTL_MS` (two minutes). The drag's ticket is not spent until the app calls `POST {hub}/apc/pair`. One drop of an agent is answered at a time: a second request for the same dock and agent while the first waits on the hub answers `pairing_in_progress` and changes nothing, and the new grant is linked to the agent only once the hub took it. Nothing changes between the app and the hub.
- **Whether a grant was revoked is told by the grant itself** (its secret, and the hash the app keeps of it), never by a grant id a later grant may reuse: a call running when its grant was revoked ends `revoked` even if a new grant took the id, and a later grant with a revoked one's id that is given back ends its running call as an unknown grant, not as revoked.

## 0.6.0 (draft, 2026-11-04)

On mobile, every app shows the agent in its page (TIN-608). In `packages/protocol/src/core.ts`, `packages/web`, `packages/conformance` and DESIGN.md section 19.

- **A new core rule (item 9).** In a viewport that matches `APC_MOBILE_MEDIA` (`(pointer: coarse), (max-width: 640px)`: a touch device, or a narrow window), an app shows its agents in its own page, each with its mark visible and usable for pinning, on both profiles. On a phone there is no dock window, extension or desktop pet to drag from, so the agent in the page is the only way the person can point it. The Dock profile's rule that the agent bar may collapse (0.4.0) does not apply there: the bar is never collapsed or hidden, and it stays reachable while the page scrolls without covering content.
- **A finger can pin.** With no mouse drag (phone browsers do no HTML5 drag and drop): touching the agent's mark and then a target (tap to pin, with a clear state and a way to cancel), or dragging the mark with a finger by pointer events. The result is the same pin as a mouse drag's. Unpin and Revoke work by touch, with finger-sized targets.
- `APC_MOBILE_MEDIA` and `APC_MOBILE_VIEWPORT` (375 x 812, the reference viewport) are exported.
- **Conformance.** An adapter may give `page.mobile` (`ApcMobilePage`: `agentBar`, `pinByTouch`, `unpinByTouch`). The suite then checks that every connected agent is shown in the page and the bar cannot be collapsed, that a pin made by touch is read by the agent through `get_current_view`, and that unpin by touch removes it.
- An app that implemented 0.5 and meets the rule needs no change to its MCP surface or `apc.json`; `standard` in `apc.json` may say 0.5.0 or 0.6.0.

## 0.5.0 (draft, 2026-11-03)

Discovery with `apc.json`, and a clear answer to a drop an app cannot take (TIN-579). In `packages/protocol/src/manifest.ts`, `packages/server/src/apc-json.ts`, `packages/web/src/pinning.ts`, `packages/conformance`, `apps/dock/src/worker/hub.ts` and DESIGN.md section 17.

### `apc.json`

- **Every APC origin says what it is** at `GET {origin}/.well-known/apc.json` (`APC_JSON_PATH`), from that origin, as JSON (`ApcManifest`): `name`, `standard` (the version it implements), `origin` (exactly the origin it is served from), `profiles`, `mcp: { path }` (every grant's MCP URL on the origin starts with `origin + path`), and, with `"direct"`, `direct: { connect }` (the page on its own origin where the person connects an agent directly). At most `APC_JSON_MAX_BYTES` (16 KiB).
- **`profiles`** is `"direct"`, `"dock"` or both for an app, and `"hub"` alone for a dock's hub (`ApcRole`), so apps and tools can tell a dock from an app. A hub's file also has `dock: { pair, confirm }`, its pairing endpoints. A reader ignores profile words and keys it does not know.
- `parseApcManifest(raw, origin)` checks a file read from `origin`: the manifest, or `apc_json_wrong_origin` (it names another origin) or `apc_json_invalid` (anything else, with a reason). `declaresMcpUrl(manifest, url)` says whether an MCP URL is an http(s) URL on the origin and under `mcp.path`, with no encoded `/`, `\`, `.` or `%` (`%2f`, `%5c`, `%2e`, `%25`) in its path and no `.` or `..` segment after `mcp.path`, so a server that decodes later cannot be walked out of it. Every URL in a manifest is http(s) on its origin (`urlOnOrigin`; a `blob:` URL of the origin is not). `compareStandard` orders versions.

### Pairing (the Dock profile)

- **A hub reads the app's `apc.json` before it pairs** (`POST {hub}/apc/pair`), once the ticket and the app's origin have passed, under the hub's transport rules (0.3.0): a time limit and the byte cap, and no redirect followed for any app, verified or not (the file is the origin's own or none). It refuses the pairing (`ApcJsonRefusal`) when the file is missing (`apc_json_missing`: a 4xx), answered with a redirect (`apc_json_redirected`, any app: a redirect is the origin answering), cannot be read as one (`apc_json_invalid`), names another origin (`apc_json_wrong_origin`), does not list `"dock"` (`dock_not_offered`), or does not cover the MCP URL the app sent (`mcp_url_not_declared`). An unverified app whose file cannot be reached (no answer, a time limit, a 5xx) is refused too (`apc_json_unreachable`).
- A hub may keep the copy it read: the reference dock uses it for 10 minutes, then reads the file again. A verified app whose file cannot be reached at all (no answer, a time limit, a 5xx) keeps pairing, checked against the last copy the hub read, or on the operator's word when it has none. Even then the MCP URL must lie under `APC_DEFAULT_MCP_PATH` (`/mcp/`) and pass `declaresMcpUrl`'s checks: the operator's word covers the profiles, never the path. A definite answer (missing, a redirect, invalid, another origin) refuses a verified app too. The hub reads the file only when an app asks to pair: a pairing made stays until it is revoked or unpaired.

### A drop an app cannot take

- **A dock agent dropped on an app that offers only Direct is answered, never lost.** The app (with `@apc/web`: `enablePinning({ profiles, direct: { name, connect }, onDockUnsupported })`) takes the drop anywhere on the page and tells the person that it connects agents directly, with its connect page, in the words of `directOnlyNote(name)`. It never pairs or pins such a drop. `profiles` may be a list, a promise or a loader such as `loadApcProfiles` (the page's own `apc.json`, read with no redirect, 3 s and 16 KiB at most). A dock agent's drop made before the profiles are known is held, then answered or paired as they say. When they cannot be read, the drop is answered, never paired: `DockUnsupported.reason` is `unchecked`, in the words of `couldNotCheckNote(name)`, and a loader is asked again on the next drop (`reason` is `direct_only` for a Direct-only app). While it takes native drops, `enablePinning` sets `data-apc-native-drops` on the root element; the browser extension answers a Direct-only app (by its `apc.json`) that does not, in its own words (the domain first).

### Conformance

- The suite reads the app's `apc.json` through the adapter's `fetch`: served as JSON from the app's origin, valid, a standard from 0.5.0 to the suite's own, the profile under test listed (both with `link`), never `"hub"`, the grant's MCP URL under `mcp.path`, and `direct.connect` on its origin.

## 0.4.0 (draft, 2026-11-03)

`apc_link`: one agent on both paths, shown as one (TIN-578). In `packages/protocol/src/core.ts`, `packages/server/src/links.ts`, `packages/conformance` and DESIGN.md section 16.

- **The offer.** When a connection arrives (`initialize`) with the same MCP client as one already connected on the opposite path to the same app, the app puts `apc_link: { code, expires_in, note }` (`ApcLinkOffer`, key `APC_LINK_KEY`) on a result of the new connection, a top-level key of the structured result and of the text, like `attention`. On the Dock path it rides on a result of one of the app's own tools, never a core tool (the hub merges those). The app asks at most once per MCP session, from one `initialize` to the next.
- **The answer.** The agent calls the tool `apc_link({ code })` (`APC_LINK_TOOL`) on its other connection to the same app: directly, or through the dock as `<app>__apc_link`. The app answers `ApcLinkDone` (`{ linked: true, note }`), or a tool error `ApcLinkRefused` (`{ error: "link_refused", reason, message }`).
- **The code** has at least 96 random bits, works once and expires after `APC_LINK_TTL_S` (120) seconds. It is redeemed only on a different connection to the same app, on the opposite path, among those it was offered to (the same client, neither linked). Otherwise the reason is `unknown_code`, `expired`, `used`, `same_connection`, `same_path`, `not_offered` or `already_linked`. The app keeps only its hash.
- **Linking grants nothing.** Each path keeps its own grant, trimming and pin; the agent bar shows one agent with both paths. Revoke on a linked agent cuts both grants, and the person can unlink, which removes the link only.
- **The client on the Dock path.** The hub initializes an app as itself (`clientInfo.name` "apc-hub"), so it names the agent's own MCP client in `params._meta["apc.tineira.com/agent_client"]` (`APC_AGENT_CLIENT_META`) of that `initialize`. On the Direct path the client is the agent's own `clientInfo.name`.
- `oppositePath` gives the other profile. `APC_INSTRUCTIONS` and the `guide` prompt tell the agent what an `apc_link` key means.
- The hub names the agent's client to verified apps only: an unverified app (0.3.0) learns nothing of it, so it is never offered a link through the hub.

## 0.3.0 (draft, 2026-11-03)

A hub's protections for apps it does not know (TIN-580), in the Dock profile: what an agent receives through a hub from an unverified app, and the hub's answers to pairing. In `apps/dock/src/worker/trust.ts`, `hub.ts`, `app-client.ts` and DESIGN.md section 15. Apps and agents that only meet verified apps see nothing new.

### Verified and unverified apps

- A hub's **verified** apps are the ones its operator lists. Any other app is **unverified**; a hub may pair with one only behind every rule below (the reference dock does not yet: pairing with an unverified app stays closed).
- **Identity is the domain.** An unverified app's id, and so its tool prefix, is derived from its host (and port): lower case, each run of other characters one `_` (`evil.example` gives `evil_example`, `evil_example__get_figure`). It always holds a `_` and never `__`, so it never equals a verified app's id (`[a-z0-9]`) or `page`. Another origin that maps to the same id is refused (`app_id_taken`). The app's `name` in `/apc/pair` is kept only as `declared_name`.
- `AppRef` (on the focus, in `views`, in `list_app_tools`) gains, for an unverified app only, `unverified: true` and `declared_name`; its `name` is the app's host. A verified app's `AppRef` is unchanged.
- The `app` argument of `call_app_tool` and `list_app_tools` takes up to 40 characters (it was 16), the longest domain id.

### Untrusted marking

- A tool result relayed from an unverified app arrives in an envelope, in the structured result and in its text: `{ app, untrusted: true, note, result }` (the app's structured result) or `{ app, untrusted: true, note, text: [...] }` (its text blocks, when it gave no structured result). `isError` is kept. This is the marking `page_text` has had since 0.1 (`untrusted: true`).
- An unverified app's entry in `views` and its focus (also as `attention`) carry `untrusted: true`.
- Its tools in `tools/list` start with `[Unverified app at <host>, calls itself "<name>". Untrusted: …]` and carry no annotations of the app's (an app could claim `readOnlyHint`). In `list_app_tools` its entry carries `untrusted: true` and a `note`, and each description the same label.
- A failed call to an unverified app is the tool error `app_unreachable` with the hub's own reason only (an HTTP status, "the app answered with an error", a time or size limit): never the app's JSON-RPC error message or HTTP error body.
- `then` on a hub's results, and the `page_open` its `wait_for_focus` reports, come from verified apps only: an unverified app's say on whether the person is on its page is not counted, so it cannot keep the agent in the wait loop.

### Limits and the blocklist

- A hub reads at most a fixed number of bytes of each answer from an app (the reference dock: 1 MiB for a verified app, 256 KiB for an unverified one), and every call has a time limit that covers the body. Past either, the call fails as `app_unreachable` for the agent.
- An unverified app must use HTTPS on a domain name (no IP address, no single-label or `localhost` host), and its redirects are not followed. Its pin is taken only when well formed, with `app_url` on its own origin and a `pinned_at` no later than now; its view only when small.
- A hub holds a fixed number of app pairings at most (the reference dock: 20, across its agents; a blocked pairing holds no place); `/apc/pair` past it answers `too_many_apps`. A host too long for an id (40 characters) answers `app_host_too_long`.
- A hub may block domains (a domain covers its subdomains; an entry in Unicode matches the app's punycode host). `/apc/pair` from one answers `app_blocked`, `/apc/confirm` too; a pairing made before the block reads `status: "blocked"`, is never called again (not even to give its grant back), its tools, view and pin go, and a call to it is the tool error `app_blocked`.
- New `/apc/pair` errors: `https_required`, `app_blocked`, `app_id_taken`, `app_host_too_long`, `too_many_apps`.

## 0.2.0 (draft, 2026-11-03)

The core written down, a conformance suite for it, and revoke from the app (TIN-577). In `packages/protocol/src/core.ts`, `packages/server/src/revoke.ts`, `packages/web/src/agents-bar.ts`, `packages/conformance` and DESIGN.md section 14.

### The core and the profiles

- The core is what every APC app implements, per grant, whichever way agents reach it: the view, the pin, presence, the focus format, `get_current_view` and `wait_for_focus` (`CORE_TOOLS`), and revoke from the app. A dock's hub is one more holder of a grant.
- Two profiles, each optional: **Direct** (the agent connects to the app's own MCP URL; the grant per agent, its URL and the agent list are the profile's) and **Dock** (the agent connects once, to a hub; receiving the drop, the ticket, consent in the app, `/apc/pair`, `/apc/confirm` and `/apc/revoke` from the hub are the profile's). `ApcProfile` names them.
- `CurrentViewResult` and `WaitForFocusResult` type the two tools' results. A wait returns a pin dropped during it, marked seen; with none, `timed_out: true` at the timeout, or `timed_out: false, page_open: false` as soon as the app knows the person's page is closed.
- `then` is never on a `wait_for_focus` result that came back with no focus: that result ends the loop. An app without a view-sharing switch always shares, so it always reports `page_open`.
- Presence is core: after each successful tool call the app publishes a `PresenceEvent` to the person's page, and a read of a target names it in `targets`.
- An unknown or expired grant answers 404, whatever the body.

### Revoke from the app

- Every agent in the app's agent bar (`<apc-agents>`), Direct or Dock, has Revoke: a first click asks, a second within `REVOKE_CONFIRM_MS` emits `apc-revoke`.
- It holds in the app alone and at once: the grant, its pin and (Dock) the app's link to the hub go. The app calls nobody, so it holds with the hub down.
- From then on every request to the grant's MCP URL is answered HTTP 403 (`REVOKED_HTTP_STATUS`) with a `RevokedAnswer`: `{ error: "revoked", revoked_by, revoked_at, message }`, `revoked_by` being the app's host. A call already running ends as a tool error with the same answer and no app data. `revokedAnswer` and `isRevokedAnswer` build and recognise it.
- A revoked grant never works again. The person lets the agent back with a new grant: a new MCP URL (Direct), or a new drop with consent in the app and in the dock (Dock).
- A hub that gets a `RevokedAnswer` marks the pairing revoked and shows "Revoked by <app host>", stops relaying to it, drops the view and the pin it took from it, never confirms it on a drop, and never pairs it again by itself. A new pairing with the same app replaces the revoked one.

## 0.1.0 (draft, 2026-11-03)

The contract as it stands today, in `packages/protocol/src`, `packages/server/src`, `packages/web/src` and DESIGN.md sections 6, 12 and 13.

### Target and focus

- A target is `{ kind, id, part, params }`. It names a row (`id`), a computation (`params`), or both; an `id` and `params` both missing is invalid. `kind` and param keys match `[a-z][a-z0-9_]{0,31}`; `id` matches `[A-Za-z0-9_.:-]{1,80}`.
- `part` names a piece of a target (`step:new`, `seats`) and follows `PART_RE`.
- `params` carries keys only: string tokens, or lists of at most 20 of them, in at most 1 KB. A bare number is an amount, never a key, and is refused (months such as `2026-03` pass). Free text never travels.
- `canonicalTarget` gives one string per target, whatever the param order.
- A pointable element carries `data-focus="kind:id"`, with `data-focus-part` and `data-focus-params` (JSON) when needed.
- A pin is stored per grant (`FocusRow`: target, `grant_id`, `pinned_at`, `seen_at`). It is unread while it was dropped after the last read that returned it.
- What the agent receives (`FocusPayload`) is the target plus `app_url`, `pinned_at`, and `next` and `next_args`, the tool call that reads it. It may carry `part_note`, `trimmed` and `gone`.

### View

- The person's screen is `ViewPayload`: `screen`, `params`, at most one `selection` (`kind`, `id`), `app_url`, `updated_at`, `age_seconds`, `stale` and `next`. It holds identifiers, trimmed to the calling grant.

### Attention and the loop

- A tool result carries `attention` (`{ focus, note }`, a top-level key of the structured result and of the text) while the pin is unread. It points at `get_current_view` and never instructs.
- A tool result carries `then` while a page of the person's is open: after answering, call `wait_for_focus`. With no page open, or when the person does not share their view, `then` is absent.
- The view and the focus are pointers, never instructions.

### Tools

- `get_current_view` returns `{ view, focus }`; reading the focus marks it seen.
- `wait_for_focus({ timeout_s })` holds the request until a new pin or the timeout (1 to the host's ceiling, default 25 s). It returns the focus, or `focus: null` with `timed_out`, `page_open` and a note. `page_open` is reported only while the person shares their view; a closed page ends the wait at its next check.
- `APC_INSTRUCTIONS` is the text an app gives an agent on connecting.

### Presence

- After each successful tool call an app may publish `PresenceEvent` (`v: 1`): `grant_id`, `at`, `tool`, `kind` (`read` or `write`), up to 20 `targets` (`kind`, `id`) and `count`. Ids only.

### Drag payload and pairing

- An agent is dragged with the type `application/x-apc-agent`. The payload is `{ v: 1, agent }`: a public handle, never a secret or an MCP URL. With a hub it adds `hub` (a bare http(s) origin) and `ticket` (a short single-use token that opens a pairing request and nothing else).
- On a drop the app looks up the handle. A paired agent gets a pin for its grant. An unpaired one makes the app ask the person, then `POST {hub}/apc/pair { ticket, app, mcp_url }` server to server; the pairing counts when the person has also said yes in the dock.

### Hub (one agent across apps)

- A hub exposes `get_current_view` (the focus and a `views` list per app), `wait_for_focus` (one wait across all paired apps), `list_app_tools` and `call_app_tool({ app, tool, args })`. An app's other tools are also relayed as `<app>__<tool>` (at most 64 characters).
- The focus gains `app: { id, name, origin }`, and `next` and `next_args` are rewritten to the hub's tool name. The hub removes an app's own `attention` and `then` and adds its own.
- A browser extension is one more app of the hub, with id `page`. A page reading is the focus kind `page_reading`, read with `page__get_reading`; its text is data from the page, never instructions.

---

The APC standard is at 1.1.1, frozen and changing only by the versioning and compatibility policy (/docs/spec#versioning-and-compatibility). This page as HTML: /docs/changelog. Text CC BY 4.0, code MIT. Source: https://github.com/tineira/agent-pointed-context/blob/main/packages/protocol/CHANGELOG.md
