@tineira/apc-protocol 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -2,7 +2,41 @@
 
 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.
+The standard has its own semver, `APC_STANDARD_VERSION` in `@tineira/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: a new minor (or, from 1.0, a major) version. A patch (0.7.0 to 0.7.1) never changes the contract; it fixes the packages or the wording, so an app that implements 0.7.0 implements every 0.7.x.
+
+## 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)
 

package/README.md

@@ -8,7 +8,7 @@ The contract an app and an agent share in Agent Pointed Context: wire types, the
 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).
+Pre-releases go out on the `next` tag while the standard is 0.x; the package's version follows the standard's (0.8.x ships APC 0.8).
 
 ```ts
 import { APC_STANDARD_VERSION, focusAttrs, parseApcManifest } from "@tineira/apc-protocol";
@@ -32,11 +32,11 @@ What every APC app implements, whichever way agents reach it ([`src/core.ts`](sr
 | 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. |
+| `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 and the grant was pinned in the last 30 minutes (0.8), 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. One wait per grant: a newer one takes over (0.8). A pin is marked seen only once the result that carries it is final, by its `pinned_at` (0.8): delivered twice at worst, never lost. |
 | `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. |
+| Revoke from the app | Revoke on every agent in the agent bar. At once, in the app alone (it calls nobody): every request with the grant answers `RevokedAnswer` from then on (403 with a secret URL, 401 with a bearer token, 0.8), a call already running ends the same way (told by the grant itself, 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:
 

package/dist/core.d.ts

@@ -3,9 +3,12 @@
  *
  * 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.
+ * - **Direct**: the agent connects to the app's own MCP endpoint. The connection (a grant per agent,
+ *   how the agent authenticates, the agent list where the person makes and names them) is the
+ *   profile's, not the core's. Since APC 0.8 the standard does not fix how the agent authenticates:
+ *   any binding that meets `GrantRequirement` will do. The reference apps' binding is the secret URL
+ *   (one MCP URL per grant, `newDirectGrant` in `@tineira/apc-server`); OAuth (one MCP URL shared by
+ *   every grant, the bearer token naming the grant) is another.
  * - **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`)
@@ -13,7 +16,7 @@
  *   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
+ *   `DockConsent` in `@tineira/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.
@@ -26,7 +29,9 @@
  *    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.
+ *    hint `then` while a page of the person's is open and the grant was pinned lately (APC 0.8), at most
+ *    one delivering wait per grant (APC 0.8), and a pin marked seen only once the result that carries
+ *    it is final (APC 0.8): an app may deliver a pin twice, never lose one.
  * 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,
@@ -36,7 +41,7 @@
  * 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
+ * `@tineira/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";
@@ -48,21 +53,68 @@ 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).
+ * The loop hint. Since APC 0.8 it is present on a result only while both hold: a page of the person's
+ * is open (and they share their view), and the grant was pinned within the app's window
+ * (`THEN_PIN_WINDOW_MIN`, 30 minutes unless the app sets its own). An open page with no recent pin gives
+ * no `then`, so an agent does not wait after every answer. It is never on a `wait_for_focus` that came
+ * back with no focus (that one ends the loop).
+ *
+ * The agent is told (in the instructions, the guide, the note and the tool's description) 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.
  */
 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. */
+/** The default `then` window, in minutes: the grant's pin, read or unread, is at most this old. An app may set its own. */
+export declare const THEN_PIN_WINDOW_MIN = 30;
+/**
+ * `get_current_view`: the screen and, if the person pointed the agent, the focus. Returning the focus
+ * marks it seen, once the result is final (APC 0.8, `WaitForFocusResult`).
+ *
+ * **Unavailable (APC 0.8).** When the app cannot answer a core tool just now (its store is down, a check
+ * cannot run), the tool still answers in its own shape, with nothing in it and a `note` for the agent:
+ * `{ view: null, focus: null, note }` here, `{ focus: null, timed_out: false, page_open: false, note }`
+ * from `wait_for_focus`. Never a tool error or an `{ ok, reason }` of the app's own. A revoked grant is not
+ * unavailable: it answers `RevokedAnswer`.
+ *
+ * **Trim, never fail (APC 0.8).** A check on one item of the answer (a filter, the selection, the pin)
+ * that cannot run hides that item, and the rest still answers. It never fails the read open (the item
+ * shown unchecked), and a defect in one check (a missing column, a value it cannot parse) never fails
+ * the read whole. A failure that concerns the grant itself (its auth, an expired session) still fails it
+ * closed.
+ */
 export interface CurrentViewResult {
     view: ViewPayload | null;
     focus: FocusPayload | null;
+    /** Why the result is empty, when the app could not answer it just now (APC 0.8). */
+    note?: string;
 }
 /**
  * `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).
+ * view (an app without that switch always shares). The default timeout is the app's: 25 to 45 s suits
+ * a conversation (`WAIT_DEFAULT_S` in `@tineira/apc-server` is 25), bounded by what its host can hold.
+ *
+ * **One wait per grant (APC 0.8).** 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 never marks a pin seen. A new wait that starts within `WAIT_CLAIM_GAP_S` of one still running is
+ * refused instead, with `focus: null, timed_out: false, retry_after_s` and a note: two waits fired
+ * together would otherwise 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, to a stateless server, comes
+ * in a POST of its own: the app keeps the calls in flight per grant to find the one it names,
+ * `InflightCalls` in `@tineira/apc-server`), and an HTTP abort where the host reports one (on Cloudflare
+ * Workers, `request.signal` with the `enable_request_signal` flag, or a compatibility date from 2026-11-17).
+ *
+ * **Seen once delivered (APC 0.8).** 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 one last time that its request was not cancelled), and
+ * marks that exact pin (by its `pinned_at`), never a newer one dropped meanwhile. It returns the result
+ * 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 (the connection dropped with no abort the app could see) is not something an app can tell, and that
+ * pin is marked seen. A hub that relays a wait holds the pin it was handed: it keeps it unread until its
+ * own agent gets it.
  */
 export type WaitForFocusResult = WaitGotFocus | WaitNoFocus;
 export interface WaitGotFocus {
@@ -73,19 +125,56 @@ export interface WaitNoFocus {
     focus: null;
     timed_out: boolean;
     page_open?: boolean;
+    /** On a wait refused because another wait of the grant started just before it (APC 0.8): when to try again. */
+    retry_after_s?: number;
     note: string;
 }
+/** How soon after one wait of a grant another is refused rather than taking over, in seconds (APC 0.8). */
+export declare const WAIT_CLAIM_GAP_S = 2;
+/**
+ * What a Direct grant must be, whatever way the agent authenticates (APC 0.8). The standard does not fix
+ * the binding (a secret MCP URL, OAuth, an API key, mTLS); any binding that meets these will do:
+ *
+ * - `stable_id`: **a stable id per agent connection.** Pins, views, presence and `apc_link` are keyed by it.
+ * - `revocable_in_app`: **revocable from the app alone.** The app revokes it in its own store, calling
+ *   nobody, and checks it on every request, and before and after each tool call. Revoking ends everything
+ *   that could bring the grant back without the person: with OAuth, the refresh tokens and the
+ *   authorization behind it too, so a client that answers a 401 by refreshing or re-authorizing silently
+ *   gets nothing. The person lets the agent back with a new grant.
+ * - `revoked_told_apart`: **revoked is told apart from expired or unknown**, with a `RevokedAnswer` body,
+ *   so the agent tells the person and stops retrying, where an expired credential may just be renewed.
+ * - `trimmed_per_grant`: **pointing grants no access.** What a grant may read is trimmed per grant; a pin
+ *   never widens it.
+ *
+ * Two bindings are described:
+ *
+ * - **The secret URL** (the reference apps; `newDirectGrant` and `directMcpUrl` in `@tineira/apc-server`):
+ *   one MCP URL per grant, under `apc.json`'s `mcp.path`; whoever holds the URL holds the grant. Revoked is
+ *   HTTP 403 with `RevokedAnswer`; an unknown or expired grant is 404.
+ * - **OAuth 2.1**: one MCP URL shared by every grant, the bearer token naming the grant. Revoked is HTTP
+ *   401 with `WWW-Authenticate: Bearer error="invalid_token"` and the `RevokedAnswer` body, so the client
+ *   tells "taken back by the person" from "expired" and does not just authorize again.
+ *
+ * On a host with no long-lived process (stateless functions and a database), an app still bounds
+ * `wait_for_focus` by its function's time limit (its own ceiling for `timeout_s`), tells a closed page from
+ * a heartbeat the page sends, and checks the grant before and after each tool call.
+ */
+export type GrantRequirement = "stable_id" | "revocable_in_app" | "revoked_told_apart" | "trimmed_per_grant";
+export declare const GRANT_REQUIREMENTS: readonly GrantRequirement[];
 /**
  * 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).
+ * - From then on every request with the grant, whatever the method, is answered with a `RevokedAnswer`
+ *   body. The HTTP status is the binding's (APC 0.8, `GrantRequirement`): `REVOKED_HTTP_STATUS` (403)
+ *   with a secret URL, `REVOKED_HTTP_STATUS_BEARER` (401, with `WWW-Authenticate: Bearer
+ *   error="invalid_token"`) with OAuth. 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 is answered without
+ *   a `RevokedAnswer` (404 with a secret URL; a plain 401 with OAuth), so the holder can tell "taken back"
+ *   from "gone". Whether a grant was revoked is told by the grant itself (its secret or token), 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
@@ -93,7 +182,10 @@ export interface WaitNoFocus {
  *   again by itself.
  */
 export declare const REVOKED_ERROR = "revoked";
+/** The status of a revoked grant with the secret-URL binding. */
 export declare const REVOKED_HTTP_STATUS = 403;
+/** The status of a revoked grant with a bearer token (OAuth), with `WWW-Authenticate: Bearer error="invalid_token"` (APC 0.8). */
+export declare const REVOKED_HTTP_STATUS_BEARER = 401;
 export interface RevokedAnswer {
     error: typeof REVOKED_ERROR;
     /** The host of the app that revoked the grant, e.g. "pulse.example". */

package/dist/core.js

@@ -3,21 +3,36 @@ 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).
+ * The loop hint. Since APC 0.8 it is present on a result only while both hold: a page of the person's
+ * is open (and they share their view), and the grant was pinned within the app's window
+ * (`THEN_PIN_WINDOW_MIN`, 30 minutes unless the app sets its own). An open page with no recent pin gives
+ * no `then`, so an agent does not wait after every answer. It is never on a `wait_for_focus` that came
+ * back with no focus (that one ends the loop).
+ *
+ * The agent is told (in the instructions, the guide, the note and the tool's description) 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.
  */
 export const THEN_KEY = "then";
+/** The default `then` window, in minutes: the grant's pin, read or unread, is at most this old. An app may set its own. */
+export const THEN_PIN_WINDOW_MIN = 30;
+/** How soon after one wait of a grant another is refused rather than taking over, in seconds (APC 0.8). */
+export const WAIT_CLAIM_GAP_S = 2;
+export const GRANT_REQUIREMENTS = ["stable_id", "revocable_in_app", "revoked_told_apart", "trimmed_per_grant"];
 /**
  * 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).
+ * - From then on every request with the grant, whatever the method, is answered with a `RevokedAnswer`
+ *   body. The HTTP status is the binding's (APC 0.8, `GrantRequirement`): `REVOKED_HTTP_STATUS` (403)
+ *   with a secret URL, `REVOKED_HTTP_STATUS_BEARER` (401, with `WWW-Authenticate: Bearer
+ *   error="invalid_token"`) with OAuth. 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 is answered without
+ *   a `RevokedAnswer` (404 with a secret URL; a plain 401 with OAuth), so the holder can tell "taken back"
+ *   from "gone". Whether a grant was revoked is told by the grant itself (its secret or token), 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
@@ -25,7 +40,10 @@ export const THEN_KEY = "then";
  *   again by itself.
  */
 export const REVOKED_ERROR = "revoked";
+/** The status of a revoked grant with the secret-URL binding. */
 export const REVOKED_HTTP_STATUS = 403;
+/** The status of a revoked grant with a bearer token (OAuth), with `WWW-Authenticate: Bearer error="invalid_token"` (APC 0.8). */
+export const REVOKED_HTTP_STATUS_BEARER = 401;
 export function revokedAnswer(host, revokedAt) {
     return {
         error: REVOKED_ERROR,

package/dist/manifest.d.ts

@@ -15,9 +15,16 @@
  *   `"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.
+ *   its own `/.well-known/` (another tenant's, on a shared host) is never paired. Since APC 0.8 a Direct
+ *   app whose grants share one MCP URL (a bearer token names the grant, as with OAuth) may serve it at
+ *   `mcp.path` itself, or at `mcp.path` without its last `/` (`/api/mcp` for `"/api/mcp/"`); one origin
+ *   may serve several such endpoints under the path, one per role (`declaresMcpUrl` with `shared`).
  * - **`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.
+ * - **`direct.auth`** (APC 0.8, optional, information only): how a Direct agent authenticates, a short
+ *   word such as `"url"` (the secret URL) or `"oauth"`; with OAuth, `direct.resource_metadata` may give
+ *   the URL of its OAuth protected-resource metadata, on its origin. A reader never requires either: the
+ *   standard does not fix how agents authenticate (`GrantRequirement`).
  * - **`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
@@ -31,7 +38,7 @@ 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
+ * Where an app's MCP URLs live when it says nothing else: `@tineira/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/";
@@ -50,9 +57,15 @@ export interface ApcManifest {
     mcp: {
         path: string;
     };
-    /** With "direct": where the person connects an agent directly, on the same origin. */
+    /**
+     * With "direct": where the person connects an agent directly, on the same origin; and, as information
+     * only (APC 0.8), how agents authenticate (`auth`, e.g. "url" or "oauth") and, with OAuth, the URL of
+     * the protected-resource metadata (`resource_metadata`, on the same origin).
+     */
     direct?: {
         connect: string;
+        auth?: string;
+        resource_metadata?: string;
     };
     /** A hub's pairing endpoints, on its origin. */
     dock?: {
@@ -89,12 +102,18 @@ export declare function parseApcManifest(raw: unknown, origin: string): {
  * 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.
+ *
+ * With `shared` (APC 0.8: a Direct endpoint whose grants share one URL, the credential naming the grant),
+ * the URL may also be `mcp.path` itself or `mcp.path` without its last `/`. Without it, as a hub pairing a
+ * Dock app checks, the URL must lie strictly under `mcp.path`: one URL per grant.
  */
-export declare function declaresMcpUrl(manifest: Pick<ApcManifest, "origin" | "mcp">, mcpUrl: string): boolean;
+export declare function declaresMcpUrl(manifest: Pick<ApcManifest, "origin" | "mcp">, mcpUrl: string, options?: {
+    shared?: boolean;
+}): 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
+ * own words, on its own page (`@tineira/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;

package/dist/manifest.js

@@ -3,13 +3,14 @@ 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
+ * Where an app's MCP URLs live when it says nothing else: `@tineira/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 AUTH_RE = /^[a-z0-9][a-z0-9_-]{0,31}$/;
 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
@@ -80,6 +81,13 @@ export function parseApcManifest(raw, origin) {
         if (!connect)
             return bad("direct.connect is not a URL on its origin");
         manifest.direct = { connect };
+        // Information only (APC 0.8): kept when well formed, otherwise left out, never a reason to refuse.
+        const direct = raw.direct;
+        if (typeof direct.auth === "string" && AUTH_RE.test(direct.auth))
+            manifest.direct.auth = direct.auth;
+        const metadata = onOrigin(direct.resource_metadata, origin);
+        if (metadata)
+            manifest.direct.resource_metadata = metadata;
     }
     if (profiles.includes("hub")) {
         const dock = isObject(raw.dock) ? raw.dock : {};
@@ -97,8 +105,12 @@ export function parseApcManifest(raw, origin) {
  * 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.
+ *
+ * With `shared` (APC 0.8: a Direct endpoint whose grants share one URL, the credential naming the grant),
+ * the URL may also be `mcp.path` itself or `mcp.path` without its last `/`. Without it, as a hub pairing a
+ * Dock app checks, the URL must lie strictly under `mcp.path`: one URL per grant.
  */
-export function declaresMcpUrl(manifest, mcpUrl) {
+export function declaresMcpUrl(manifest, mcpUrl, options = {}) {
     let url;
     try {
         url = new URL(mcpUrl);
@@ -108,9 +120,12 @@ export function declaresMcpUrl(manifest, mcpUrl) {
     }
     if (!urlOnOrigin(url.href, manifest.origin))
         return false;
-    if (!url.pathname.startsWith(manifest.mcp.path) || url.pathname.length <= manifest.mcp.path.length)
+    const path = manifest.mcp.path;
+    if (options.shared && path !== "/" && (url.pathname === path || url.pathname === path.slice(0, -1)))
+        return !/%(2f|5c|2e|25)/i.test(mcpUrl.split(/[?#]/, 1)[0]);
+    if (!url.pathname.startsWith(path) || url.pathname.length <= path.length)
         return false;
-    const rest = url.pathname.slice(manifest.mcp.path.length);
+    const rest = url.pathname.slice(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;
@@ -119,7 +134,7 @@ export function declaresMcpUrl(manifest, mcpUrl) {
 /**
  * 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
+ * own words, on its own page (`@tineira/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) {

package/dist/version.d.ts

@@ -7,4 +7,4 @@
  * 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";
+export declare const APC_STANDARD_VERSION = "0.8.0";

package/dist/version.js

@@ -7,4 +7,4 @@
  * 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";
+export const APC_STANDARD_VERSION = "0.8.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tineira/apc-protocol",
-  "version": "0.7.0",
+  "version": "0.8.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",