@tineira/apc-protocol 0.0.0-stage → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,150 @@
+# 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`](../../CHANGELOG.md) at the root.
+
+The standard has its own semver, `APC_STANDARD_VERSION` in `@apc/protocol`, separate from the software release. It stays 0.x while the standard is a draft and becomes 1.0.0 when it is published. 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.
+
+## 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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tineira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# @tineira/apc-protocol
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The contract an app and an agent share in Agent Pointed Context: wire types, the target grammar, the version of the standard (`APC_STANDARD_VERSION`) and the core. Its changes are in [CHANGELOG.md](CHANGELOG.md). No dependencies, no Node imports: it runs in the browser, on Workers and on Node. Docs: https://apc.tineira.com/docs
+
+## Install
+
+```sh
+npm i @tineira/apc-protocol@next
+```
+
+Pre-releases go out on the `next` tag while the standard is 0.x; the package's version follows the standard's (0.7.x ships APC 0.7).
+
+```ts
+import { APC_STANDARD_VERSION, focusAttrs, parseApcManifest } from "@tineira/apc-protocol";
+
+// Mark something in your page that the person can point an agent at:
+const attrs = focusAttrs({ kind: "customer", id: "cus_0042" }); // { "data-focus": "customer:cus_0042" }
+
+// Read an app's apc.json, checked against the origin it came from:
+const res = await fetch("https://pulse.apc.tineira.com/.well-known/apc.json", { redirect: "manual" });
+const parsed = parseApcManifest(await res.json(), "https://pulse.apc.tineira.com");
+if (parsed.ok) console.log(parsed.manifest.profiles, parsed.manifest.standard, APC_STANDARD_VERSION);
+```
+
+## The core
+
+What every APC app implements, whichever way agents reach it ([`src/core.ts`](src/core.ts)). It holds per grant: a dock's hub is one more holder of a grant.
+
+| Part | What the app does |
+|---|---|
+| The view | Reports the person's screen as identifiers (`ViewPayload`), trimmed to each grant. |
+| The pin | Keeps one pin per grant, dropped by the person on a target (`FocusTarget`), and gives it as `FocusPayload` with `next` and `next_args`, the call that reads it. While it is unread, every tool result carries `attention`. |
+| Presence | After each successful tool call, publishes a `PresenceEvent` (ids only) to the person's page; a read of a target names it. |
+| The focus format | `FocusPayload`, from the grammar in [`src/target.ts`](src/target.ts): kinds, ids, parts and key-only params. |
+| `get_current_view`, `wait_for_focus` | The two core tools (`CORE_TOOLS`), with `then` on results while a page of the person's is open, never on a wait that came back empty. A wait returns a pin dropped during it, times out cleanly, and ends as soon as the app knows the page is closed. |
+| `apc.json` | Serves `/.well-known/apc.json` from its own origin: what it is and which profiles it offers (below). |
+| `apc_link` | Only with both profiles: the same agent on both paths shown as one, with a one-time code; it grants nothing (below). |
+| Mobile (0.6) | On a phone or any touch viewport (`APC_MOBILE_MEDIA`) shows its agents in its own page, on both profiles (below). |
+| Revoke from the app | Revoke on every agent in the agent bar. At once, in the app alone (it calls nobody): the grant's MCP URL answers 403 with `RevokedAnswer` from then on, a call already running ends the same way (told by the grant's secret, never an id a later grant may reuse, 0.7), and the grant never works again. |
+
+What belongs to a profile, not to the core:
+
+- **Direct** (the agent connects to the app's own MCP URL): a grant per agent, its secret URL, the list where the person makes and names agents.
+- **Dock** (the agent connects once, to a hub): the drop (`application/x-apc-agent`, the handle and the ticket), consent in the app (checked by the app's server, never its page alone: 0.7, `DockConsent` in `@tineira/apc-server`), `POST {hub}/apc/pair` (the hub reads the app's `apc.json` first), `POST {hub}/apc/confirm` on every drop, and `POST {app}/apc/revoke`, the hub giving a grant back.
+
+Whatever it offers, an app publishes `apc.json` (below).
+
+An app offers one profile or both. Pulse (`apps/demo`) and Signals (`apps/signals`) offer both, declared in `APC_PROFILES` in their `wrangler.jsonc`; the Direct profile's parts are packaged in `@tineira/apc-server` (`direct.ts`) and `@tineira/apc-web` (`<apc-direct-agents>`).
+
+### Mobile (0.6)
+
+On a phone there is no dock window, browser extension or desktop pet to drag an agent from, so the agent in the app's own page is the only way the person can point it. In a viewport that matches `APC_MOBILE_MEDIA` (`(pointer: coarse), (max-width: 640px)`), on both profiles, an app ([`src/core.ts`](src/core.ts)):
+
+- **shows its agents in the page**, each with its mark visible and usable for pinning. The Dock profile's rule that the agent bar may collapse does not apply there, and the bar is never collapsed or hidden; it stays reachable while the page scrolls without covering content the person needs;
+- **lets a finger 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 pin is the same `FocusTarget` as a mouse drag's. Unpin and Revoke work by touch, with finger-sized targets.
+
+`@tineira/apc-web` does both (`<apc-agents>`, `enablePinning`). `APC_MOBILE_VIEWPORT` (375 x 812) is the reference viewport; `@tineira/apc-conformance` checks it through the adapter's `page.mobile`.
+
+### `apc_link` (0.4)
+
+An app that offers both profiles shows the same agent on both paths as one ([`src/core.ts`](src/core.ts)). When a connection arrives with the same MCP client as one already connected on the opposite path, the app puts `apc_link: { code, expires_in, note }` on a result of the new connection (on the Dock path, of one of its own tools), at most once per MCP session. The agent sends it back with the tool `apc_link({ code })` on its other connection (through a dock, `<app>__apc_link`). The code works once, for 120 s, only on a different connection on the opposite path that it was offered to; otherwise `link_refused` with a reason. Linking grants nothing: each path keeps its grant, the bar shows one agent, Revoke cuts both, and the person can unlink. On the Dock path the hub names the agent's own client in `_meta["apc.tineira.com/agent_client"]` of its `initialize`.
+
+### `apc.json` (0.5)
+
+Every APC origin says what it is at `GET {origin}/.well-known/apc.json` ([`src/manifest.ts`](src/manifest.ts)): its `name`, the `standard` it implements, its `origin` (exactly the one it is served from), its `profiles` (`"direct"`, `"dock"` or both; `"hub"` alone for a dock), `mcp.path` (where its MCP URLs live) and, with Direct, `direct.connect` (its page where the person connects an agent directly). `@tineira/apc-server` builds an app's (`apcManifest`, `apcJsonResponse`). A hub reads it before it pairs and refuses an app whose file is missing, invalid, names another origin, lists no `"dock"` or does not cover the MCP URL; a dock agent dropped on a Direct-only app is answered with how to connect directly (`directOnlyNote`), in the page and in the browser extension.
+
+To check an app against the core, run [`@tineira/apc-conformance`](../conformance) on its MCP endpoint (see the root README), or `npx @tineira/apc-conformance@next <app-origin>` against a live app.

package/dist/core.d.ts

@@ -0,0 +1,187 @@
+/**
+ * The core of APC: what every APC app implements, whichever way agents reach it.
+ *
+ * An app offers one profile or both:
+ *
+ * - **Direct**: the agent connects to the app's own MCP URL, one per agent. The connection (a grant
+ *   per agent, its secret MCP URL, the agent list where the person makes and names them) is the
+ *   profile's, not the core's.
+ * - **Dock**: the agent connects once, to a hub (the dock), which reaches the app with a grant the
+ *   app gave it. Receiving the drop (`application/x-apc-agent`, the handle and the ticket), consent
+ *   in the app, pairing (`POST {hub}/apc/pair`), the check on every drop (`POST {hub}/apc/confirm`)
+ *   and the hub giving a grant back (`POST {app}/apc/revoke`) are the profile's, not the core's.
+ *   Consent in the app is the app's server's to check (APC 0.7), never the page's alone: the server makes
+ *   a grant for a dock agent it holds none for only on a request that proves the person allowed it on the
+ *   app's page just now (the reference apps: a single-use nonce the page shows its consent with,
+ *   `DockConsent` in @apc/server), whatever the page last loaded. A page that missed a revoke must not
+ *   pair without asking.
+ *
+ * The core is the same on both, and per grant: the hub is one more holder of a grant.
+ *
+ * 1. **The view**: what the person sees, as identifiers (`ViewPayload`), trimmed to the grant.
+ * 2. **The pin**: the person drops the agent's mark on a target (`FocusTarget`); the app keeps one
+ *    pin per grant (`FocusRow`) and gives it as `FocusPayload`, with `next` and `next_args`, the
+ *    call that reads it. While the pin is unread, every tool result carries `attention`.
+ * 3. **Presence**: after each successful tool call the app publishes a `PresenceEvent` (ids only) to
+ *    the person's page; a read of a target names it in `targets`.
+ * 4. **The focus format**: `FocusPayload`, from the grammar in `target.ts`.
+ * 5. **`get_current_view` and `wait_for_focus`**, the two core tools (`CORE_TOOLS`), with the loop
+ *    hint `then` while a page of the person's is open.
+ * 6. **Revoke from the app**: the person can cut any agent from the app itself, at once, without the
+ *    hub (`RevokedAnswer`).
+ * 7. **`apc_link`** (an app that offers both profiles): the same agent on both paths shown as one,
+ *    with a one-time code; it grants nothing (`ApcLinkOffer`).
+ * 8. **`apc.json`** (APC 0.5): what the app is, at `GET {origin}/.well-known/apc.json`: its name, the
+ *    standard, its origin, its profiles, where its MCP URLs live, its connect page (`manifest.ts`).
+ * 9. **Mobile** (APC 0.6): on a phone or any touch viewport (`APC_MOBILE_MEDIA`) the app shows its agents
+ *    in its own page, on both profiles (below).
+ *
+ * `@apc/conformance` checks an app against this core, given its MCP endpoint and a small adapter for
+ * what happens in the page.
+ */
+import type { FocusPayload, ViewPayload } from "./types.js";
+/** How an agent reaches an app. An app offers one or both; the core is the same on each. */
+export type ApcProfile = "direct" | "dock";
+/** The two tools every APC app exposes, on every grant. */
+export declare const CORE_TOOLS: readonly ["get_current_view", "wait_for_focus"];
+export type CoreTool = (typeof CORE_TOOLS)[number];
+/** The key an unread pin puts on every tool result (structured and in the text): `{ focus, note }`. */
+export declare const ATTENTION_KEY = "attention";
+/**
+ * The loop hint: present on a result while a page of the person's is open and they share their view,
+ * except on a `wait_for_focus` that came back with no focus (that one ends the loop).
+ */
+export declare const THEN_KEY = "then";
+/** `get_current_view`: the screen and, if the person pointed the agent, the focus. Reading the focus marks it seen. */
+export interface CurrentViewResult {
+    view: ViewPayload | null;
+    focus: FocusPayload | null;
+}
+/**
+ * `wait_for_focus({ timeout_s })`: holds the call until the person pins the agent or `timeout_s`
+ * passes (1 to the app's ceiling). A pin dropped during the wait is returned, marked seen. With no
+ * pin: `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. `page_open` is left out while the person does not share their
+ * view (an app without that switch always shares).
+ */
+export type WaitForFocusResult = WaitGotFocus | WaitNoFocus;
+export interface WaitGotFocus {
+    focus: FocusPayload;
+    timed_out: false;
+}
+export interface WaitNoFocus {
+    focus: null;
+    timed_out: boolean;
+    page_open?: boolean;
+    note: string;
+}
+/**
+ * Revoke from the app. Every agent in the app's agent bar, Direct or Dock, has Revoke, and it holds
+ * in the app alone:
+ *
+ * - It takes effect at once: the grant, its pin and (Dock) the app's link to the hub go. The app
+ *   calls nobody, so it works with the hub down.
+ * - From then on every request to the grant's MCP URL, whatever the method, is answered with HTTP
+ *   `REVOKED_HTTP_STATUS` (403) and a `RevokedAnswer` body. A call already running when the grant is
+ *   revoked ends as a tool error whose `error` is `"revoked"`, with no app data. An unknown or
+ *   expired grant stays 404, so the holder can tell "taken back" from "gone". Whether a grant was
+ *   revoked is told by the grant itself (its secret), never by an id a later grant may reuse (0.7).
+ * - A revoked grant never works again. To let the agent back, the person makes 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 that pairing revoked ("Revoked by <app host>"), stops
+ *   relaying to it, drops what it kept from it (its view and the pin it took), and never pairs it
+ *   again by itself.
+ */
+export declare const REVOKED_ERROR = "revoked";
+export declare const REVOKED_HTTP_STATUS = 403;
+export interface RevokedAnswer {
+    error: typeof REVOKED_ERROR;
+    /** The host of the app that revoked the grant, e.g. "pulse.example". */
+    revoked_by: string;
+    revoked_at: string;
+    message: string;
+}
+export declare function revokedAnswer(host: string, revokedAt: string): RevokedAnswer;
+export declare function isRevokedAnswer(body: unknown): body is RevokedAnswer;
+/**
+ * Mobile (APC 0.6). On a phone there is no dock window, browser extension or desktop pet to drag an
+ * agent from, so the agent in the app's own page is the only way the person can point it (give it
+ * focus). So, in a viewport that matches `APC_MOBILE_MEDIA`, on both profiles:
+ *
+ * - **The agents are shown in the page**, all of them, each with its mark visible and usable for
+ *   pinning. This holds whatever the app's profiles, and whatever the agent bar does elsewhere: the
+ *   Dock profile's rule that the bar may collapse to a small indicator does not apply, and the bar is
+ *   never hidden or collapsed. It stays reachable while the page scrolls, without covering content
+ *   the person needs.
+ * - **The person can pin with a finger, with no mouse drag.** Browsers on phones do not do HTML5
+ *   drag and drop, so the app takes a touch alternative: touching the agent's mark and then a target
+ *   ("tap to pin": a clear state, a way to cancel), or dragging the mark with a finger with pointer
+ *   events. The result is the same pin (`FocusTarget`) as a mouse drag. Removing the pin (unpin) and
+ *   Revoke work by touch too, with targets large enough for a finger.
+ *
+ * `APC_MOBILE_VIEWPORT` is the reference viewport the conformance suite and the apps are checked at.
+ */
+export declare const APC_MOBILE_MEDIA = "(pointer: coarse), (max-width: 640px)";
+export declare const APC_MOBILE_VIEWPORT: {
+    readonly width: 375;
+    readonly height: 812;
+};
+/** The other path: Direct for Dock and Dock for Direct. */
+export declare function oppositePath(path: ApcProfile): ApcProfile;
+/**
+ * `apc_link` (APC 0.4): the same agent, connected to one app both ways (its own MCP URL, Direct, and
+ * through a dock's hub, Dock), shown as one agent in the app's agent bar.
+ *
+ * - **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`) on a result of that 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,
+ *   not a core tool (the hub merges those into its own results). The app asks at most once per MCP
+ *   session (from one `initialize` to the next): an agent that does not answer, or answers late, is not
+ *   asked again in that session, and stays two entries.
+ * - **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 links the
+ *   two grants and answers `ApcLinkDone`, or refuses with a tool error, `ApcLinkRefused`.
+ * - **The code** is random (at least 96 bits), works once, expires after `expires_in` seconds
+ *   (`APC_LINK_TTL_S`), and is redeemed only by a different connection to the same app, on the opposite
+ *   path, among those the app offered it to (the same MCP client, not already linked). Anything else is
+ *   refused with a reason (`ApcLinkRefusal`). The app keeps only a hash of it.
+ * - **Linking grants nothing.** Each path keeps its own grant, trimming and pin; the link changes only
+ *   what the agent bar shows: one agent with both paths. Revoke on a linked agent cuts both grants. The
+ *   person can unlink from the bar, which removes the link and nothing else.
+ * - **Which client it is.** On the Direct path, `clientInfo.name` of the agent's own `initialize`. On
+ *   the Dock path the hub initializes the app as itself, so it names the agent's own MCP client in
+ *   `params._meta[APC_AGENT_CLIENT_META]` of that `initialize`.
+ */
+export declare const APC_LINK_TOOL = "apc_link";
+/** The key an offer puts on a result. */
+export declare const APC_LINK_KEY = "apc_link";
+/** How long a link code lives, in seconds. */
+export declare const APC_LINK_TTL_S = 120;
+/** On the Dock path: the `_meta` key of the hub's `initialize` that names the agent's own MCP client. */
+export declare const APC_AGENT_CLIENT_META = "apc.tineira.com/agent_client";
+export interface ApcLinkOffer {
+    /** One-time; sent back with `apc_link({ code })` on the other connection. */
+    code: string;
+    /** Seconds left: `APC_LINK_TTL_S` when offered. */
+    expires_in: number;
+    /** What to do with it, for the agent. */
+    note: string;
+}
+export interface ApcLinkDone {
+    linked: true;
+    note: string;
+}
+export declare const LINK_REFUSED_ERROR = "link_refused";
+/**
+ * Why a code was refused: `unknown_code` (no such code in this app), `expired`, `used` (it already
+ * linked), `same_connection` (sent back on the connection that got it), `same_path` (on another
+ * connection of the same path), `not_offered` (on a connection it was not offered to: another client,
+ * or one not connected when it was offered), `already_linked` (one of the two is linked already).
+ */
+export type ApcLinkRefusal = "unknown_code" | "expired" | "used" | "same_connection" | "same_path" | "not_offered" | "already_linked";
+export interface ApcLinkRefused {
+    error: typeof LINK_REFUSED_ERROR;
+    reason: ApcLinkRefusal;
+    message: string;
+}

package/dist/core.js

@@ -0,0 +1,97 @@
+/** The two tools every APC app exposes, on every grant. */
+export const CORE_TOOLS = ["get_current_view", "wait_for_focus"];
+/** The key an unread pin puts on every tool result (structured and in the text): `{ focus, note }`. */
+export const ATTENTION_KEY = "attention";
+/**
+ * The loop hint: present on a result while a page of the person's is open and they share their view,
+ * except on a `wait_for_focus` that came back with no focus (that one ends the loop).
+ */
+export const THEN_KEY = "then";
+/**
+ * Revoke from the app. Every agent in the app's agent bar, Direct or Dock, has Revoke, and it holds
+ * in the app alone:
+ *
+ * - It takes effect at once: the grant, its pin and (Dock) the app's link to the hub go. The app
+ *   calls nobody, so it works with the hub down.
+ * - From then on every request to the grant's MCP URL, whatever the method, is answered with HTTP
+ *   `REVOKED_HTTP_STATUS` (403) and a `RevokedAnswer` body. A call already running when the grant is
+ *   revoked ends as a tool error whose `error` is `"revoked"`, with no app data. An unknown or
+ *   expired grant stays 404, so the holder can tell "taken back" from "gone". Whether a grant was
+ *   revoked is told by the grant itself (its secret), never by an id a later grant may reuse (0.7).
+ * - A revoked grant never works again. To let the agent back, the person makes 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 that pairing revoked ("Revoked by <app host>"), stops
+ *   relaying to it, drops what it kept from it (its view and the pin it took), and never pairs it
+ *   again by itself.
+ */
+export const REVOKED_ERROR = "revoked";
+export const REVOKED_HTTP_STATUS = 403;
+export function revokedAnswer(host, revokedAt) {
+    return {
+        error: REVOKED_ERROR,
+        revoked_by: host,
+        revoked_at: revokedAt,
+        message: `The person revoked this agent's access in the app at ${host}. It does not come back: to reconnect, the person makes a new grant there.`,
+    };
+}
+export function isRevokedAnswer(body) {
+    const b = body;
+    return !!b && typeof b === "object" && b.error === REVOKED_ERROR && typeof b.revoked_by === "string";
+}
+/**
+ * Mobile (APC 0.6). On a phone there is no dock window, browser extension or desktop pet to drag an
+ * agent from, so the agent in the app's own page is the only way the person can point it (give it
+ * focus). So, in a viewport that matches `APC_MOBILE_MEDIA`, on both profiles:
+ *
+ * - **The agents are shown in the page**, all of them, each with its mark visible and usable for
+ *   pinning. This holds whatever the app's profiles, and whatever the agent bar does elsewhere: the
+ *   Dock profile's rule that the bar may collapse to a small indicator does not apply, and the bar is
+ *   never hidden or collapsed. It stays reachable while the page scrolls, without covering content
+ *   the person needs.
+ * - **The person can pin with a finger, with no mouse drag.** Browsers on phones do not do HTML5
+ *   drag and drop, so the app takes a touch alternative: touching the agent's mark and then a target
+ *   ("tap to pin": a clear state, a way to cancel), or dragging the mark with a finger with pointer
+ *   events. The result is the same pin (`FocusTarget`) as a mouse drag. Removing the pin (unpin) and
+ *   Revoke work by touch too, with targets large enough for a finger.
+ *
+ * `APC_MOBILE_VIEWPORT` is the reference viewport the conformance suite and the apps are checked at.
+ */
+export const APC_MOBILE_MEDIA = "(pointer: coarse), (max-width: 640px)";
+export const APC_MOBILE_VIEWPORT = { width: 375, height: 812 };
+/** The other path: Direct for Dock and Dock for Direct. */
+export function oppositePath(path) {
+    return path === "direct" ? "dock" : "direct";
+}
+/**
+ * `apc_link` (APC 0.4): the same agent, connected to one app both ways (its own MCP URL, Direct, and
+ * through a dock's hub, Dock), shown as one agent in the app's agent bar.
+ *
+ * - **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`) on a result of that 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,
+ *   not a core tool (the hub merges those into its own results). The app asks at most once per MCP
+ *   session (from one `initialize` to the next): an agent that does not answer, or answers late, is not
+ *   asked again in that session, and stays two entries.
+ * - **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 links the
+ *   two grants and answers `ApcLinkDone`, or refuses with a tool error, `ApcLinkRefused`.
+ * - **The code** is random (at least 96 bits), works once, expires after `expires_in` seconds
+ *   (`APC_LINK_TTL_S`), and is redeemed only by a different connection to the same app, on the opposite
+ *   path, among those the app offered it to (the same MCP client, not already linked). Anything else is
+ *   refused with a reason (`ApcLinkRefusal`). The app keeps only a hash of it.
+ * - **Linking grants nothing.** Each path keeps its own grant, trimming and pin; the link changes only
+ *   what the agent bar shows: one agent with both paths. Revoke on a linked agent cuts both grants. The
+ *   person can unlink from the bar, which removes the link and nothing else.
+ * - **Which client it is.** On the Direct path, `clientInfo.name` of the agent's own `initialize`. On
+ *   the Dock path the hub initializes the app as itself, so it names the agent's own MCP client in
+ *   `params._meta[APC_AGENT_CLIENT_META]` of that `initialize`.
+ */
+export const APC_LINK_TOOL = "apc_link";
+/** The key an offer puts on a result. */
+export const APC_LINK_KEY = "apc_link";
+/** How long a link code lives, in seconds. */
+export const APC_LINK_TTL_S = 120;
+/** On the Dock path: the `_meta` key of the hub's `initialize` that names the agent's own MCP client. */
+export const APC_AGENT_CLIENT_META = "apc.tineira.com/agent_client";
+export const LINK_REFUSED_ERROR = "link_refused";

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type * from "./types.js";
+export * from "./target.js";
+export * from "./version.js";
+export * from "./core.js";
+export * from "./manifest.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./target.js";
+export * from "./version.js";
+export * from "./core.js";
+export * from "./manifest.js";

package/dist/manifest.d.ts

@@ -0,0 +1,105 @@
+/**
+ * `apc.json` (APC 0.5): what an origin says about itself. Every APC app, and every hub, serves it at
+ * `GET {origin}/.well-known/apc.json` (`APC_JSON_PATH`), from its own origin:
+ *
+ * ```json
+ * { "name": "Signals", "standard": "0.5.0", "origin": "https://signals.example",
+ *   "profiles": ["direct", "dock"], "mcp": { "path": "/mcp/" },
+ *   "direct": { "connect": "https://signals.example/?connect" } }
+ * ```
+ *
+ * - **`name`**: what the app (or hub) calls itself.
+ * - **`standard`**: the version of the APC standard it implements (`APC_STANDARD_VERSION`).
+ * - **`origin`**: the origin it is served from, exactly. A file that names another origin is refused.
+ * - **`profiles`**: how agents reach it. An app lists `"direct"`, `"dock"` or both; a hub lists
+ *   `"hub"` alone, so apps and tools can tell a dock from an app. Words a reader does not know are ignored.
+ * - **`mcp.path`**: where its MCP URLs live. Every grant's MCP URL on this origin starts with
+ *   `origin + mcp.path`. A hub pairs only an MCP URL under it, so a path the domain did not declare in
+ *   its own `/.well-known/` (another tenant's, on a shared host) is never paired.
+ * - **`direct.connect`** (with `"direct"`): the page, on the same origin, where the person connects an
+ *   agent directly: what a person is shown when they drop a dock agent on a Direct-only app.
+ * - **`dock`** (a hub): where it takes pairings, `pair` and `confirm`, as absolute URLs on its origin.
+ *
+ * A hub reads an app's `apc.json` when the app asks to pair (`POST {hub}/apc/pair`) and refuses the
+ * pairing when it is missing (`apc_json_missing`), answered with a redirect (`apc_json_redirected`), cannot be read as one (`apc_json_invalid`), names
+ * another origin (`apc_json_wrong_origin`), does not list the Dock profile (`dock_not_offered`), or
+ * does not cover the MCP URL the app sent (`mcp_url_not_declared`); see `ApcJsonRefusal`.
+ */
+import type { ApcProfile } from "./core.js";
+/** Where an origin serves its `apc.json`. */
+export declare const APC_JSON_PATH = "/.well-known/apc.json";
+/** The most bytes a reader takes of an `apc.json`. */
+export declare const APC_JSON_MAX_BYTES = 16384;
+/**
+ * Where an app's MCP URLs live when it says nothing else: `@apc/server`'s default `mcp.path`, and the
+ * path a hub holds a verified app to when it pairs it without a file (its file out of reach, no copy).
+ */
+export declare const APC_DEFAULT_MCP_PATH = "/mcp/";
+/** A word of `profiles`: an app's profiles, or `"hub"` for a dock's hub. */
+export type ApcRole = ApcProfile | "hub";
+export declare const APC_ROLES: readonly ApcRole[];
+export interface ApcManifest {
+    name: string;
+    /** The version of the APC standard it implements, e.g. "0.5.0". */
+    standard: string;
+    /** The origin it is served from. */
+    origin: string;
+    /** "direct", "dock" or both for an app; "hub" alone for a hub. */
+    profiles: ApcRole[];
+    /** Every grant's MCP URL on this origin starts with origin + path. */
+    mcp: {
+        path: string;
+    };
+    /** With "direct": where the person connects an agent directly, on the same origin. */
+    direct?: {
+        connect: string;
+    };
+    /** A hub's pairing endpoints, on its origin. */
+    dock?: {
+        pair: string;
+        confirm: string;
+    };
+}
+/** Why a hub refuses a pairing over the app's `apc.json` (APC 0.5). */
+export type ApcJsonRefusal = "apc_json_missing" | "apc_json_redirected" | "apc_json_unreachable" | "apc_json_invalid" | "apc_json_wrong_origin" | "dock_not_offered" | "mcp_url_not_declared";
+/**
+ * An absolute http(s) URL on `origin`, with no credentials, as its href; null otherwise. The scheme is
+ * checked as well as the origin: `blob:https://app.example/…` has that origin too, and is no page of it.
+ */
+export declare function urlOnOrigin(value: unknown, origin: string): string | null;
+/** Compares two versions of the standard: negative, zero or positive. */
+export declare function compareStandard(a: string, b: string): number;
+/**
+ * An `apc.json` as read from `origin`, checked: the manifest, or why it is not one. `wrong_origin` when
+ * it names another origin than the one it was read from; `invalid` for anything else that is wrong
+ * (a missing or malformed field, no profile this reader knows, a hub listing an app's profile too, a
+ * Direct app with no connect page, a URL off its origin).
+ */
+export declare function parseApcManifest(raw: unknown, origin: string): {
+    ok: true;
+    manifest: ApcManifest;
+} | {
+    ok: false;
+    error: "apc_json_invalid" | "apc_json_wrong_origin";
+    detail: string;
+};
+/**
+ * Whether an MCP URL lies under what the manifest declares: an http(s) URL on its origin, with no
+ * credentials, under `mcp.path`. The URL parser removes literal `.` and `..` segments, but not encoded
+ * ones, which a server may decode afterwards: so the rest of the path after `mcp.path` may hold no
+ * encoded slash, backslash or dot (`%2f`, `%5c`, `%2e`), no encoded percent (`%25`, a second round of
+ * encoding), and no backslash.
+ */
+export declare function declaresMcpUrl(manifest: Pick<ApcManifest, "origin" | "mcp">, mcpUrl: string): boolean;
+/**
+ * What an app tells a person who drops an agent from their dock on it when it connects agents only
+ * directly (its `apc.json` lists no `"dock"`): the drop is answered, never lost. These are the app's
+ * own words, on its own page (`@apc/web`); the browser extension, which speaks for itself, puts the
+ * domain first and the name only as what the page says it is.
+ */
+export declare function directOnlyNote(name: string): string;
+/**
+ * What an app tells a person who drops a dock agent on it when its page could not read its own
+ * `apc.json`: it cannot tell whether it takes dock agents, so it pairs nothing and says so.
+ */
+export declare function couldNotCheckNote(name: string): string;

package/dist/manifest.js

@@ -0,0 +1,134 @@
+/** Where an origin serves its `apc.json`. */
+export const APC_JSON_PATH = "/.well-known/apc.json";
+/** The most bytes a reader takes of an `apc.json`. */
+export const APC_JSON_MAX_BYTES = 16_384;
+/**
+ * Where an app's MCP URLs live when it says nothing else: `@apc/server`'s default `mcp.path`, and the
+ * path a hub holds a verified app to when it pairs it without a file (its file out of reach, no copy).
+ */
+export const APC_DEFAULT_MCP_PATH = "/mcp/";
+export const APC_ROLES = ["direct", "dock", "hub"];
+const VERSION_RE = /^(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,4})\.(0|[1-9]\d{0,5})$/;
+const PATH_RE = /^\/([A-Za-z0-9._~!$&'()*+,;=:@-]+\/)*$/;
+const isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+/**
+ * An absolute http(s) URL on `origin`, with no credentials, as its href; null otherwise. The scheme is
+ * checked as well as the origin: `blob:https://app.example/…` has that origin too, and is no page of it.
+ */
+export function urlOnOrigin(value, origin) {
+    if (typeof value !== "string" || value.length > 2048)
+        return null;
+    try {
+        const url = new URL(value);
+        return (url.protocol === "https:" || url.protocol === "http:") && url.origin === origin && !url.username && !url.password ? url.href : null;
+    }
+    catch {
+        return null;
+    }
+}
+const onOrigin = urlOnOrigin;
+/** Compares two versions of the standard: negative, zero or positive. */
+export function compareStandard(a, b) {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    for (let i = 0; i < 3; i++)
+        if ((pa[i] ?? 0) !== (pb[i] ?? 0))
+            return (pa[i] ?? 0) - (pb[i] ?? 0);
+    return 0;
+}
+/**
+ * An `apc.json` as read from `origin`, checked: the manifest, or why it is not one. `wrong_origin` when
+ * it names another origin than the one it was read from; `invalid` for anything else that is wrong
+ * (a missing or malformed field, no profile this reader knows, a hub listing an app's profile too, a
+ * Direct app with no connect page, a URL off its origin).
+ */
+export function parseApcManifest(raw, origin) {
+    const bad = (detail) => ({ ok: false, error: "apc_json_invalid", detail });
+    if (!isObject(raw))
+        return bad("not a JSON object");
+    const name = typeof raw.name === "string" ? raw.name.replace(/[\p{Cc}\p{Cf}]/gu, "").trim() : "";
+    if (!name || name.length > 60)
+        return bad("name is not a short string");
+    if (typeof raw.standard !== "string" || !VERSION_RE.test(raw.standard))
+        return bad("standard is not a version like 0.5.0");
+    if (typeof raw.origin !== "string")
+        return bad("origin is missing");
+    let declared;
+    try {
+        declared = new URL(raw.origin).origin;
+    }
+    catch {
+        return bad("origin is not an origin");
+    }
+    if (declared !== raw.origin)
+        return bad("origin is not an origin (scheme, host and port, no path or trailing slash)");
+    if (declared !== origin)
+        return { ok: false, error: "apc_json_wrong_origin", detail: `it names ${declared}, it was read from ${origin}` };
+    if (!Array.isArray(raw.profiles) || raw.profiles.length > 8)
+        return bad("profiles is not a short list");
+    const profiles = APC_ROLES.filter((r) => raw.profiles.includes(r));
+    if (!profiles.length)
+        return bad("profiles lists none of direct, dock, hub");
+    if (profiles.includes("hub") && profiles.length > 1)
+        return bad("a hub lists only hub");
+    const mcp = raw.mcp;
+    if (!isObject(mcp) || typeof mcp.path !== "string" || mcp.path.length > 200 || !PATH_RE.test(mcp.path) || mcp.path.split("/").some((s) => s === "." || s === ".."))
+        return bad("mcp.path is not a path that starts and ends with /");
+    const manifest = { name, standard: raw.standard, origin, profiles, mcp: { path: mcp.path } };
+    if (profiles.includes("direct")) {
+        const connect = isObject(raw.direct) ? onOrigin(raw.direct.connect, origin) : null;
+        if (!connect)
+            return bad("direct.connect is not a URL on its origin");
+        manifest.direct = { connect };
+    }
+    if (profiles.includes("hub")) {
+        const dock = isObject(raw.dock) ? raw.dock : {};
+        const pair = onOrigin(dock.pair, origin);
+        const confirm = onOrigin(dock.confirm, origin);
+        if (!pair || !confirm)
+            return bad("dock.pair and dock.confirm are not URLs on its origin");
+        manifest.dock = { pair, confirm };
+    }
+    return { ok: true, manifest };
+}
+/**
+ * Whether an MCP URL lies under what the manifest declares: an http(s) URL on its origin, with no
+ * credentials, under `mcp.path`. The URL parser removes literal `.` and `..` segments, but not encoded
+ * ones, which a server may decode afterwards: so the rest of the path after `mcp.path` may hold no
+ * encoded slash, backslash or dot (`%2f`, `%5c`, `%2e`), no encoded percent (`%25`, a second round of
+ * encoding), and no backslash.
+ */
+export function declaresMcpUrl(manifest, mcpUrl) {
+    let url;
+    try {
+        url = new URL(mcpUrl);
+    }
+    catch {
+        return false;
+    }
+    if (!urlOnOrigin(url.href, manifest.origin))
+        return false;
+    if (!url.pathname.startsWith(manifest.mcp.path) || url.pathname.length <= manifest.mcp.path.length)
+        return false;
+    const rest = url.pathname.slice(manifest.mcp.path.length);
+    // Checked on the URL as sent too: the parser turns some encoded dots into segments it then removes.
+    const sent = mcpUrl.split(/[?#]/, 1)[0];
+    const encoded = /%(2f|5c|2e|25)/i;
+    return !encoded.test(rest) && !encoded.test(sent) && !rest.includes("\\") && !rest.split("/").some((s) => s === "." || s === "..");
+}
+/**
+ * What an app tells a person who drops an agent from their dock on it when it connects agents only
+ * directly (its `apc.json` lists no `"dock"`): the drop is answered, never lost. These are the app's
+ * own words, on its own page (`@apc/web`); the browser extension, which speaks for itself, puts the
+ * domain first and the name only as what the page says it is.
+ */
+export function directOnlyNote(name) {
+    return `${name} connects agents directly, not through a dock. Connect your agent to ${name} on its own URL, then drag its mark from the agent bar there.`;
+}
+/**
+ * What an app tells a person who drops a dock agent on it when its page could not read its own
+ * `apc.json`: it cannot tell whether it takes dock agents, so it pairs nothing and says so.
+ */
+export function couldNotCheckNote(name) {
+    return `${name} could not check how it connects agents just now, so your agent was not paired. Drop it again in a moment, or connect your agent to ${name} directly on its own URL.`;
+}

package/dist/target.d.ts

@@ -0,0 +1,28 @@
+import type { FocusParams, FocusTarget, KeyValue } from "./types.js";
+/** The part grammar of the specification (the PFA 0114 check). */
+export declare const PART_RE: RegExp;
+export declare const PARAMS_MAX_BYTES = 1024;
+/** Keys only: string tokens or short lists of them; no numbers, no free text, at most 1 KB. */
+export declare function parseParams(raw: unknown): FocusParams | null;
+/** A valid target, or null. A target names a row (id) or a computation (params), or both. */
+export declare function parseTarget(raw: {
+    kind?: unknown;
+    id?: unknown;
+    part?: unknown;
+    params?: unknown;
+}): FocusTarget | null;
+/** One canonical string per target: param order does not matter. */
+export declare function canonicalTarget(target: FocusTarget): string;
+/** The three DOM attributes a pointable element carries. */
+export interface FocusAttrs {
+    "data-focus": string;
+    "data-focus-part"?: string;
+    "data-focus-params"?: string;
+}
+export declare function focusAttrs(target: {
+    kind: string;
+    id?: string | null;
+    part?: string | null;
+    params?: Record<string, KeyValue> | null;
+}): FocusAttrs;
+export declare function parseFocusAttrs(focus: string | null, part: string | null, params: string | null): FocusTarget | null;

package/dist/target.js

@@ -0,0 +1,88 @@
+/** The part grammar of the specification (the PFA 0114 check). */
+export const PART_RE = /^[a-z][a-z0-9_]{0,31}(:[A-Za-z0-9_.|:-]{1,80})?$/;
+const KIND_RE = /^[a-z][a-z0-9_]{0,31}$/;
+const ID_RE = /^[A-Za-z0-9_.:-]{1,80}$/;
+const PARAM_KEY_RE = /^[a-z][a-z0-9_]{0,31}$/;
+const TOKEN_RE = /^[A-Za-z0-9_.:|-]{1,80}$/;
+/** A bare number is an amount, never a key. Months ("2026-03") and ids pass. */
+const NUMBER_RE = /^[-+]?\d+(\.\d+)?$/;
+export const PARAMS_MAX_BYTES = 1024;
+function isToken(value) {
+    return typeof value === "string" && TOKEN_RE.test(value) && !NUMBER_RE.test(value);
+}
+/** Keys only: string tokens or short lists of them; no numbers, no free text, at most 1 KB. */
+export function parseParams(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    if (typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!PARAM_KEY_RE.test(key))
+            return null;
+        if (Array.isArray(value)) {
+            if (value.length === 0 || value.length > 20 || !value.every(isToken))
+                return null;
+            out[key] = [...value];
+        }
+        else if (isToken(value)) {
+            out[key] = value;
+        }
+        else {
+            return null;
+        }
+    }
+    if (new TextEncoder().encode(JSON.stringify(out)).length > PARAMS_MAX_BYTES)
+        return null;
+    return out;
+}
+/** A valid target, or null. A target names a row (id) or a computation (params), or both. */
+export function parseTarget(raw) {
+    const kind = raw.kind;
+    if (typeof kind !== "string" || !KIND_RE.test(kind))
+        return null;
+    const id = raw.id === null || raw.id === undefined || raw.id === "" ? null : raw.id;
+    if (id !== null && (typeof id !== "string" || !ID_RE.test(id)))
+        return null;
+    const part = raw.part === null || raw.part === undefined || raw.part === "" ? null : raw.part;
+    if (part !== null && (typeof part !== "string" || !PART_RE.test(part)))
+        return null;
+    const params = parseParams(raw.params);
+    if (raw.params !== null && raw.params !== undefined && params === null)
+        return null;
+    if (id === null && params === null)
+        return null;
+    return { kind, id: id, part: part, params };
+}
+/** One canonical string per target: param order does not matter. */
+export function canonicalTarget(target) {
+    const params = target.params
+        ? Object.fromEntries(Object.entries(target.params).sort(([a], [b]) => a.localeCompare(b)))
+        : null;
+    return JSON.stringify([target.kind, target.id, target.part, params]);
+}
+export function focusAttrs(target) {
+    const attrs = { "data-focus": `${target.kind}:${target.id ?? ""}` };
+    if (target.part)
+        attrs["data-focus-part"] = target.part;
+    if (target.params)
+        attrs["data-focus-params"] = JSON.stringify(target.params);
+    return attrs;
+}
+export function parseFocusAttrs(focus, part, params) {
+    if (!focus)
+        return null;
+    const colon = focus.indexOf(":");
+    if (colon < 1)
+        return null;
+    let parsedParams = null;
+    if (params) {
+        try {
+            parsedParams = JSON.parse(params);
+        }
+        catch {
+            return null;
+        }
+    }
+    return parseTarget({ kind: focus.slice(0, colon), id: focus.slice(colon + 1), part, params: parsedParams });
+}

package/dist/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Wire types of the three APC channels, as in the companion specification
+ * (04-payload-specification.md, https://doi.org/10.5281/zenodo.23383101).
+ * Only identifiers and keys travel: never text, amounts or pixels.
+ */
+/** A key-only value: an id, a month, an enum word, or a list of those. */
+export type KeyValue = string | string[];
+export type FocusParams = Record<string, KeyValue>;
+/** What the person pointed at: a row, a part of a row, or a part of a computed figure. */
+export interface FocusTarget {
+    kind: string;
+    /** The row id; null for a figure, which is named by its params. */
+    id: string | null;
+    part: string | null;
+    params: FocusParams | null;
+}
+/** The stored pin, one per grant. */
+export interface FocusRow extends FocusTarget {
+    grant_id: string;
+    pinned_at: string;
+    seen_at: string | null;
+}
+/** What the agent receives: the target plus the tool and arguments that read it. */
+export interface FocusPayload extends FocusTarget {
+    app_url: string;
+    pinned_at: string;
+    next: string;
+    next_args: Record<string, unknown>;
+    part_note?: string;
+    trimmed?: {
+        hidden_entities: number;
+    } | null;
+    gone?: boolean;
+}
+/** Carried on every tool result while the pin is unread. */
+export interface Attention {
+    focus: FocusPayload;
+    note: string;
+}
+/** The person's screen as identifiers, trimmed to the calling grant. */
+export interface ViewPayload {
+    screen: string;
+    params: FocusParams;
+    selection: {
+        kind: string;
+        id: string;
+    } | null;
+    app_url: string;
+    updated_at: string;
+    age_seconds: number;
+    stale: boolean;
+    next: string | null;
+}
+/** One message on the presence channel, after each successful tool call. */
+export interface PresenceEvent {
+    v: 1;
+    grant_id: string;
+    at: string;
+    tool: string;
+    kind: "read" | "write";
+    targets: Array<{
+        kind: string;
+        id: string;
+    }>;
+    count: number;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Wire types of the three APC channels, as in the companion specification
+ * (04-payload-specification.md, https://doi.org/10.5281/zenodo.23383101).
+ * Only identifiers and keys travel: never text, amounts or pixels.
+ */
+export {};

package/dist/version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The version of the APC standard: the contract an app and an agent share
+ * (view, pin, presence, the focus format, `wait_for_focus`, the tools, the
+ * drag payload, pairing). It is semver and separate from the software release
+ * (the repo's tags v0.1.0 and v0.2.0): the software can ship a dozen times
+ * without the contract changing. It stays 0.x while the standard is a draft
+ * and becomes 1.0.0 when the standard is published. Every change to the
+ * contract adds an entry to `packages/protocol/CHANGELOG.md` and bumps this.
+ */
+export declare const APC_STANDARD_VERSION = "0.7.0";

package/dist/version.js

@@ -0,0 +1,10 @@
+/**
+ * The version of the APC standard: the contract an app and an agent share
+ * (view, pin, presence, the focus format, `wait_for_focus`, the tools, the
+ * drag payload, pairing). It is semver and separate from the software release
+ * (the repo's tags v0.1.0 and v0.2.0): the software can ship a dozen times
+ * without the contract changing. It stays 0.x while the standard is a draft
+ * and becomes 1.0.0 when the standard is published. Every change to the
+ * contract adds an entry to `packages/protocol/CHANGELOG.md` and bumps this.
+ */
+export const APC_STANDARD_VERSION = "0.7.0";

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@tineira/apc-protocol",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.0",
+  "description": "Agent Pointed Context (APC): the contract an app and an AI agent share. Wire types, the target grammar, the core, apc.json and the version of the standard.",
+  "keywords": [
+    "apc",
+    "agent-pointed-context",
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "protocol"
+  ],
+  "homepage": "https://apc.tineira.com/docs",
+  "bugs": {
+    "url": "https://github.com/tineira/agent-pointed-context/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tineira/agent-pointed-context",
+    "directory": "packages/protocol"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {},
+  "types": "./dist/index.d.ts"
 }