@anynotate/protocol 0.1.0 → 0.2.0

package/PROTOCOL.md

@@ -1,30 +1,58 @@
-# Anynotate protocol (0.1.x)
+# Anynotate protocol v1
 
-The bridge is an HTTP server on `127.0.0.1`, port `47291` by default (`ANYNOTATE_PORT`). Clients send annotation **bundles**; the bridge stores each one as a folder and delivers it to an AI agent session.
+The bridge is an HTTP server on `127.0.0.1`, port `47291` by default (`ANYNOTATE_PORT`). Clients send annotation **bundles**; the bridge stores each one as a folder and delivers it to an AI agent session. Constants and schemas live in `@anynotate/protocol`; request/response examples for the extension-facing endpoints live in `@anynotate/protocol/fixtures` (`conformance`).
+
+## Handshake
+
+`POST /health` (or `GET`) → `{ "ok": true, "bridgeVersion": "0.2.0", "protocol": { "version": 1, "min": 1 } }`.
+
+A client supports a range of protocol versions (the extension: `min 1, max 1`) and calls `compatibility(clientRange, response.protocol)`:
+
+- `ok` — the ranges overlap; proceed.
+- `bridge-too-old` — ask the user to update the bridge; don't send.
+- `extension-too-old` — ask the user to update the client.
+
+A `/health` body without `protocol` comes from a pre-v1 bridge: treat it as `bridge-too-old`.
 
 ## Access
 
-- Browser callers are recognised by `Origin`. A request carrying an `Origin` that is not on the bridge's allow-list (`$ANYNOTATE_HOME/origins` plus `ANYNOTATE_ALLOWED_ORIGINS`) gets `403`. Allowed origins get CORS headers.
-- Every endpoint except `GET /health` and `OPTIONS` requires the header `X-Anynotate-Token: <token>`, where the token is the contents of `$ANYNOTATE_HOME/token` (`anynotate token`). A missing or wrong token gets `401`.
+Checked in this order:
+
+| Request | Result |
+|---|---|
+| `Host` is not `127.0.0.1:<port>` or `localhost:<port>` | `403 {"error":"bad host"}` |
+| `Origin` present and not on the allow-list | `403 {"error":"forbidden origin"}` (preflight too) |
+| `OPTIONS` | `204`, with CORS headers for an allowed origin |
+| `/health` | answered, no credentials needed |
+| `X-Anynotate-Token` equal to `$ANYNOTATE_HOME/token` | allowed |
+| anything else | `401 {"error":"bad token"}` |
+
+An `Origin` on the allow-list earns CORS headers only; **the token is still required**, because any local process can send any `Origin`.
+
+The allow-list is the valid `chrome-extension://` entries from `$ANYNOTATE_HOME/origins` and `ANYNOTATE_ALLOWED_ORIGINS`; `anynotate install` adds the Anynotate extension's id, and `anynotate origin add chrome-extension://<id>` adds a development build. Chrome attaches `Origin` to an extension's non-GET requests only, so **browser clients use the POST endpoints**; the GET variants remain for the CLI and scripts.
+
+### How the extension gets the token
+
+`anynotate install` registers a Chrome native messaging host named `dev.anynotate.host` (macOS: `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/dev.anynotate.host.json`) whose `allowed_origins` are the allow-listed extension ids. Chrome launches it only for those extensions, running `~/.anynotate/native-host` as the user. Chrome starts the helper without the user's environment, so `ANYNOTATE_HOME` does not apply: the helper always reads `~/.anynotate/token` and `~/.anynotate/origins`. Messages use Chrome's native messaging framing (a 4-byte little-endian length, then UTF-8 JSON): the request `{ "type": "token" }` is answered with `{ "ok": true, "token": "<64 hex>" }`, or `{ "ok": false, "error": "<reason>" }` if the calling origin is not allowed or the request is unknown. The extension then sends the token as `X-Anynotate-Token`; nobody copies it by hand.
 
 ## Endpoints
 
 | Method and path | Body | Response |
 |---|---|---|
-| `GET /health` | — | `{ "ok": true }` |
-| `GET /sessions` | — | `Session[]`: live push sessions, herdr panes (`method: "herdr"`), then sessions seen by the prompt hook (`method: "next-prompt"`) |
-| `POST /bundles` | `multipart/form-data`: field `bundle` = JSON `BundleInput`; file fields named `page.md`, `screenshot.png`, optional `snapshot.html`, `crops/A<n>.png` | `201 { id, status: Status }` |
-| `GET /bundles/<id>` | — | `{ bundle: Bundle, status: Status }` or `404` |
-| `POST /bundles/<id>/ack` | `{ "summary"?: string }` | `{ "ok": true }`, or `404` if unknown or busy |
-| `POST /register` | `{ id, agent, cwd, title? }` | `{ "ok": true }`, registers a push adapter |
-| `POST /heartbeat` | `{ id }` | `{ "ok": true }`, or `404` if not registered |
-| `GET /adapter/<id>/events` | — | Server-sent events: `event: deliver` / `data: { "bundleId": … }`, plus a comment ping every 15 s |
+| `GET` / `POST /health` | — | `HealthResponse` |
+| `GET` / `POST /sessions` | — | `Session[]`: live push sessions, herdr panes (`method: "herdr"`), then sessions seen by the prompt hook outside herdr (`method: "next-prompt"`) |
+| `POST /bundles` | `multipart/form-data`: field `bundle` = JSON `BundleInput`; files `page.md`, `screenshot.png`, optional `snapshot.html`, `crops/A<n>.png` | `201 SendResponse` (`{ id, status }`); `400 ErrorResponse` for an invalid bundle or file name |
+| `POST /bundles/<id>/status`, `GET /bundles/<id>` | — | `BundleStatusResponse` (`{ bundle, status }`; `status` is `null` if the status file is missing or unreadable); `404` if unknown |
+| `POST /bundles/<id>/ack` | `AckRequest` (`{ "summary"?: string }`) | `OkResponse`; `404` if unknown or busy |
+| `POST /register` | `{ id, agent, cwd, title? }` | `OkResponse`; registers a push adapter (`400` for an invalid agent name) |
+| `POST /heartbeat` | `{ id }` | `OkResponse`, or `404 {"ok":false}` if not registered |
+| `GET /adapter/<id>/events` | — | Server-sent events: a `: connected` comment, then `event: deliver` / `data: { "bundleId": … }`, plus a comment ping every 15 s; `404 {"error":"not registered"}` if not registered |
 
-Request bodies are capped at 50 MB. Upload file names outside the list above are rejected.
+Every error body is `ErrorResponse` (`{ "error": string }`), except `/heartbeat`'s `404 {"ok":false}` and a body over the 50 MB cap, which the server refuses before the bridge handles the request.
 
 ## Bundle folder
 
-Each bundle is written to `$ANYNOTATE_HOME/inbox/<id>/` (default `~/.anynotate`), and older bundles are moved to `$ANYNOTATE_HOME/archive/`. Ids match `BUNDLE_ID`, e.g. `2026-09-28T101502-example-com`.
+Each bundle is written to `$ANYNOTATE_HOME/inbox/<id>/` (default `~/.anynotate`); older bundles move to `$ANYNOTATE_HOME/archive/`. Ids match `BUNDLE_ID`, e.g. `2026-09-24T153200-tomato-soup-recipes`.
 
 | File | Contents |
 |---|---|
@@ -38,6 +66,19 @@ Each bundle is written to `$ANYNOTATE_HOME/inbox/<id>/` (default `~/.anynotate`)
 
 `$ANYNOTATE_HOME/inbox/latest` points at the newest bundle.
 
-## Versioning
+## Evolution
+
+- Additive changes — optional fields, new endpoints — keep `PROTOCOL_VERSION`. Both sides ignore fields they don't know.
+- Removing, renaming or changing the meaning of anything bumps `PROTOCOL_VERSION`; the bridge keeps accepting the previous version (`PROTOCOL_MIN`) for at least one release.
+- The bundle format has its own `v` (currently `1`); the agent-facing `README.md` stays human-readable.
+
+## Threat model
 
-Bundles carry `v: 1`. Consumers must ignore fields they don't know.
+- **Web pages** can reach `127.0.0.1` from the user's browser. They are refused by `Origin` (including preflights), and DNS-rebinding pages by `Host`; a web request without an `Origin` (such as an `<img>` GET) fails the token check.
+- **Other users, and sandboxed processes that cannot read `$ANYNOTATE_HOME/token`,** can reach the loopback port and can forge any `Origin`, but the token is required on every route except `/health`, and `$ANYNOTATE_HOME` and its contents are owner-only. They are refused.
+- **Processes running as the user** can read the token file or run the native host themselves; the bridge does not defend against code already running as the user.
+- **Bundle handling**: file names are allow-listed, ids are validated, bodies are capped at 50 MB, and the bridge loads no remote code.
+- **The token** is compared in constant time. The extension receives it only from the native host, which Chrome starts only for allow-listed extension ids.
+- **Extension ids** are what the native host trusts. An extension the user side-loads in developer mode with a copied public key gets the same id and is treated as Anynotate.
+- **A compromised extension renderer** can change the stored bridge URL, but the extension only ever sends the token to `127.0.0.1`.
+- **While the bridge is not running**, another local user could listen on its port and receive the extension's token. Keep the bridge running (launchd restarts it), and treat the token as exposed if that may have happened: delete `~/.anynotate/token` and restart the bridge to rotate it.

package/README.md

@@ -12,6 +12,8 @@ import { BundleInput, type Session } from "@anynotate/protocol";
 const parsed = BundleInput.safeParse(payload);
 ```
 
+Request/response examples for the extension-facing endpoints: `import { conformance } from "@anynotate/protocol/fixtures"`.
+
 Versions below 1.0 may change the wire format between minor releases.
 
 ## License

package/dist/fixtures.d.ts

@@ -0,0 +1,164 @@
+import type { z } from "zod";
+import { type BundleInput } from "./index.js";
+export declare const FIXTURE_EXTENSION_ORIGIN = "chrome-extension://abcdefghijklmnopabcdefghijklmnop";
+export declare const EXAMPLE_BUNDLE_ID = "2026-09-24T153200-tomato-soup-recipes";
+export declare const exampleBundleInput: BundleInput;
+export declare const examplePage = "# Tomato soup\n\nstir in \u27E6A1\u27E7200 ml cream before serving\n";
+export declare const responseSchemas: {
+    HealthResponse: z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+        bridgeVersion: z.ZodString;
+        protocol: z.ZodObject<{
+            version: z.ZodNumber;
+            min: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    SessionsResponse: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        agent: z.ZodString;
+        cwd: z.ZodString;
+        title: z.ZodString;
+        method: z.ZodEnum<{
+            push: "push";
+            herdr: "herdr";
+            "next-prompt": "next-prompt";
+        }>;
+        pane: z.ZodOptional<z.ZodString>;
+        sessionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    SendResponse: z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodObject<{
+            state: z.ZodEnum<{
+                queued: "queued";
+                delivered: "delivered";
+                acked: "acked";
+            }>;
+            at: z.ZodString;
+            via: z.ZodOptional<z.ZodEnum<{
+                push: "push";
+                herdr: "herdr";
+                hook: "hook";
+                pull: "pull";
+            }>>;
+            session: z.ZodOptional<z.ZodString>;
+            summary: z.ZodOptional<z.ZodString>;
+            note: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    BundleStatusResponse: z.ZodObject<{
+        bundle: z.ZodObject<{
+            v: z.ZodLiteral<1>;
+            url: z.ZodString;
+            title: z.ZodString;
+            sentAt: z.ZodISODateTime;
+            target: z.ZodObject<{
+                agent: z.ZodString;
+                sessionId: z.ZodOptional<z.ZodString>;
+                cwd: z.ZodOptional<z.ZodString>;
+                pane: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            overall: z.ZodOptional<z.ZodString>;
+            annotations: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                kind: z.ZodEnum<{
+                    text: "text";
+                    element: "element";
+                }>;
+                comment: z.ZodString;
+                intent: z.ZodOptional<z.ZodEnum<{
+                    question: "question";
+                    change: "change";
+                    bug: "bug";
+                    note: "note";
+                }>>;
+                anchor: z.ZodObject<{
+                    quote: z.ZodOptional<z.ZodObject<{
+                        exact: z.ZodString;
+                        prefix: z.ZodString;
+                        suffix: z.ZodString;
+                    }, z.core.$strip>>;
+                    position: z.ZodOptional<z.ZodObject<{
+                        start: z.ZodNumber;
+                        end: z.ZodNumber;
+                    }, z.core.$strip>>;
+                    css: z.ZodString;
+                    path: z.ZodArray<z.ZodString>;
+                    near: z.ZodString;
+                    hosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                }, z.core.$strip>;
+                element: z.ZodOptional<z.ZodObject<{
+                    tag: z.ZodString;
+                    role: z.ZodOptional<z.ZodString>;
+                    name: z.ZodOptional<z.ZodString>;
+                    text: z.ZodString;
+                    html: z.ZodString;
+                    attrs: z.ZodRecord<z.ZodString, z.ZodString>;
+                }, z.core.$strip>>;
+                box: z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                    w: z.ZodNumber;
+                    h: z.ZodNumber;
+                }, z.core.$strip>;
+                viewport: z.ZodObject<{
+                    w: z.ZodNumber;
+                    h: z.ZodNumber;
+                    dpr: z.ZodNumber;
+                    scrollY: z.ZodNumber;
+                }, z.core.$strip>;
+                crop: z.ZodString;
+            }, z.core.$strip>>;
+            id: z.ZodString;
+            files: z.ZodObject<{
+                page: z.ZodString;
+                screenshot: z.ZodString;
+                snapshot: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+        status: z.ZodNullable<z.ZodObject<{
+            state: z.ZodEnum<{
+                queued: "queued";
+                delivered: "delivered";
+                acked: "acked";
+            }>;
+            at: z.ZodString;
+            via: z.ZodOptional<z.ZodEnum<{
+                push: "push";
+                herdr: "herdr";
+                hook: "hook";
+                pull: "pull";
+            }>>;
+            session: z.ZodOptional<z.ZodString>;
+            summary: z.ZodOptional<z.ZodString>;
+            note: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    OkResponse: z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+    }, z.core.$strip>;
+    ErrorResponse: z.ZodObject<{
+        error: z.ZodString;
+    }, z.core.$strip>;
+};
+export type SchemaName = keyof typeof responseSchemas;
+export type Exchange = {
+    name: string;
+    request: {
+        method: "GET" | "POST";
+        path: string;
+        auth: "extension" | "extension-no-token" | "token" | "none" | "foreign-origin";
+        host?: string;
+        json?: unknown;
+        bundle?: {
+            input: BundleInput;
+            files: Record<string, string>;
+        };
+    };
+    status: number;
+    response: {
+        schema: SchemaName;
+        example: unknown;
+    };
+};
+export declare const conformance: Exchange[];

package/dist/fixtures.js

@@ -0,0 +1,45 @@
+import { BundleStatusResponse, ErrorResponse, HealthResponse, OkResponse, SendResponse, SessionsResponse, } from "./index.js";
+// Shared request/response examples. The bridge's tests replay every exchange against a live bridge; client
+// tests check that they make the extension exchanges with exactly this method and path and can parse the examples.
+export const FIXTURE_EXTENSION_ORIGIN = "chrome-extension://abcdefghijklmnopabcdefghijklmnop";
+export const EXAMPLE_BUNDLE_ID = "2026-09-24T153200-tomato-soup-recipes";
+export const exampleBundleInput = {
+    v: 1,
+    url: "https://recipes.example.com/tomato-soup",
+    title: "Tomato soup – Recipes",
+    sentAt: "2026-09-24T15:32:00.000Z",
+    target: { agent: "claude", sessionId: "s-1", cwd: "/tmp/repo" },
+    overall: "can we make this vegan?",
+    annotations: [{
+            id: "A1", kind: "text", comment: "is there a substitute for cream?", intent: "question",
+            anchor: {
+                quote: { exact: "200 ml cream", prefix: "stir in ", suffix: " before serving" },
+                css: "section#ingredients > li:nth-child(3)", path: ["main", "section#ingredients", "ul"], near: "Ingredients",
+            },
+            box: { x: 10, y: 20, w: 100, h: 18 },
+            viewport: { w: 1280, h: 800, dpr: 2, scrollY: 0 },
+            crop: "crops/A1.png",
+        }],
+};
+export const examplePage = "# Tomato soup\n\nstir in ⟦A1⟧200 ml cream before serving\n";
+export const responseSchemas = {
+    HealthResponse, SessionsResponse, SendResponse, BundleStatusResponse, OkResponse, ErrorResponse,
+};
+const health = { ok: true, bridgeVersion: "0.2.0", protocol: { version: 1, min: 1 } };
+const queued = { state: "queued", at: "2026-09-24T15:32:01.000Z" };
+const exampleBundle = { ...exampleBundleInput, id: EXAMPLE_BUNDLE_ID, files: { page: "page.md", screenshot: "screenshot.png" } };
+export const conformance = [
+    { name: "health-extension", request: { method: "POST", path: "/health", auth: "extension" }, status: 200, response: { schema: "HealthResponse", example: health } },
+    { name: "health-probe", request: { method: "GET", path: "/health", auth: "none" }, status: 200, response: { schema: "HealthResponse", example: health } },
+    { name: "sessions-extension", request: { method: "POST", path: "/sessions", auth: "extension" }, status: 200, response: { schema: "SessionsResponse", example: [{ id: "w1:p2", agent: "claude", cwd: "/home/me/project", title: "shell", method: "herdr", pane: "w1:p2" }] } },
+    { name: "sessions-token", request: { method: "GET", path: "/sessions", auth: "token" }, status: 200, response: { schema: "SessionsResponse", example: [] } },
+    { name: "sessions-extension-no-token", request: { method: "POST", path: "/sessions", auth: "extension-no-token" }, status: 401, response: { schema: "ErrorResponse", example: { error: "bad token" } } },
+    { name: "sessions-unauthenticated", request: { method: "POST", path: "/sessions", auth: "none" }, status: 401, response: { schema: "ErrorResponse", example: { error: "bad token" } } },
+    { name: "sessions-foreign-origin", request: { method: "POST", path: "/sessions", auth: "foreign-origin" }, status: 403, response: { schema: "ErrorResponse", example: { error: "forbidden origin" } } },
+    { name: "health-wrong-host", request: { method: "GET", path: "/health", auth: "none", host: "evil.example" }, status: 403, response: { schema: "ErrorResponse", example: { error: "bad host" } } },
+    { name: "send-bundle", request: { method: "POST", path: "/bundles", auth: "extension", bundle: { input: exampleBundleInput, files: { "page.md": examplePage } } }, status: 201, response: { schema: "SendResponse", example: { id: EXAMPLE_BUNDLE_ID, status: queued } } },
+    { name: "bundle-status-extension", request: { method: "POST", path: "/bundles/:id/status", auth: "extension" }, status: 200, response: { schema: "BundleStatusResponse", example: { bundle: exampleBundle, status: queued } } },
+    { name: "bundle-status-token", request: { method: "GET", path: "/bundles/:id", auth: "token" }, status: 200, response: { schema: "BundleStatusResponse", example: { bundle: exampleBundle, status: queued } } },
+    { name: "ack", request: { method: "POST", path: "/bundles/:id/ack", auth: "token", json: { summary: "suggested oat cream" } }, status: 200, response: { schema: "OkResponse", example: { ok: true } } },
+    { name: "bundle-status-unknown", request: { method: "POST", path: "/bundles/2026-01-01T000000-missing/status", auth: "extension" }, status: 404, response: { schema: "ErrorResponse", example: { error: "not found" } } },
+];

package/dist/index.d.ts

@@ -234,3 +234,158 @@ export declare const Session: z.ZodObject<{
     sessionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type Session = z.infer<typeof Session>;
+export declare const PROTOCOL_VERSION = 1;
+export declare const PROTOCOL_MIN = 1;
+export declare const HealthResponse: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    bridgeVersion: z.ZodString;
+    protocol: z.ZodObject<{
+        version: z.ZodNumber;
+        min: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type HealthResponse = z.infer<typeof HealthResponse>;
+export declare const SessionsResponse: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    agent: z.ZodString;
+    cwd: z.ZodString;
+    title: z.ZodString;
+    method: z.ZodEnum<{
+        push: "push";
+        herdr: "herdr";
+        "next-prompt": "next-prompt";
+    }>;
+    pane: z.ZodOptional<z.ZodString>;
+    sessionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>>;
+export type SessionsResponse = z.infer<typeof SessionsResponse>;
+export declare const SendResponse: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodObject<{
+        state: z.ZodEnum<{
+            queued: "queued";
+            delivered: "delivered";
+            acked: "acked";
+        }>;
+        at: z.ZodString;
+        via: z.ZodOptional<z.ZodEnum<{
+            push: "push";
+            herdr: "herdr";
+            hook: "hook";
+            pull: "pull";
+        }>>;
+        session: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type SendResponse = z.infer<typeof SendResponse>;
+export declare const BundleStatusResponse: z.ZodObject<{
+    bundle: z.ZodObject<{
+        v: z.ZodLiteral<1>;
+        url: z.ZodString;
+        title: z.ZodString;
+        sentAt: z.ZodISODateTime;
+        target: z.ZodObject<{
+            agent: z.ZodString;
+            sessionId: z.ZodOptional<z.ZodString>;
+            cwd: z.ZodOptional<z.ZodString>;
+            pane: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        overall: z.ZodOptional<z.ZodString>;
+        annotations: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<{
+                text: "text";
+                element: "element";
+            }>;
+            comment: z.ZodString;
+            intent: z.ZodOptional<z.ZodEnum<{
+                question: "question";
+                change: "change";
+                bug: "bug";
+                note: "note";
+            }>>;
+            anchor: z.ZodObject<{
+                quote: z.ZodOptional<z.ZodObject<{
+                    exact: z.ZodString;
+                    prefix: z.ZodString;
+                    suffix: z.ZodString;
+                }, z.core.$strip>>;
+                position: z.ZodOptional<z.ZodObject<{
+                    start: z.ZodNumber;
+                    end: z.ZodNumber;
+                }, z.core.$strip>>;
+                css: z.ZodString;
+                path: z.ZodArray<z.ZodString>;
+                near: z.ZodString;
+                hosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>;
+            element: z.ZodOptional<z.ZodObject<{
+                tag: z.ZodString;
+                role: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+                text: z.ZodString;
+                html: z.ZodString;
+                attrs: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, z.core.$strip>>;
+            box: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                w: z.ZodNumber;
+                h: z.ZodNumber;
+            }, z.core.$strip>;
+            viewport: z.ZodObject<{
+                w: z.ZodNumber;
+                h: z.ZodNumber;
+                dpr: z.ZodNumber;
+                scrollY: z.ZodNumber;
+            }, z.core.$strip>;
+            crop: z.ZodString;
+        }, z.core.$strip>>;
+        id: z.ZodString;
+        files: z.ZodObject<{
+            page: z.ZodString;
+            screenshot: z.ZodString;
+            snapshot: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    status: z.ZodNullable<z.ZodObject<{
+        state: z.ZodEnum<{
+            queued: "queued";
+            delivered: "delivered";
+            acked: "acked";
+        }>;
+        at: z.ZodString;
+        via: z.ZodOptional<z.ZodEnum<{
+            push: "push";
+            herdr: "herdr";
+            hook: "hook";
+            pull: "pull";
+        }>>;
+        session: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type BundleStatusResponse = z.infer<typeof BundleStatusResponse>;
+export declare const AckRequest: z.ZodObject<{
+    summary: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AckRequest = z.infer<typeof AckRequest>;
+export declare const OkResponse: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export type OkResponse = z.infer<typeof OkResponse>;
+export declare const ErrorResponse: z.ZodObject<{
+    error: z.ZodString;
+}, z.core.$strip>;
+export type ErrorResponse = z.infer<typeof ErrorResponse>;
+export type Compatibility = "ok" | "bridge-too-old" | "extension-too-old";
+export declare function compatibility(client: {
+    min: number;
+    max: number;
+}, bridge: {
+    version: number;
+    min: number;
+}): Compatibility;

package/dist/index.js

@@ -68,3 +68,26 @@ export const Session = z.object({
     pane: z.string().optional(),
     sessionIds: z.array(z.string()).optional(),
 });
+// Protocol v1. Additive changes (optional fields, new endpoints) keep the version; removals, renames and
+// semantic changes bump PROTOCOL_VERSION, and the bridge keeps accepting the previous version for a release.
+export const PROTOCOL_VERSION = 1;
+export const PROTOCOL_MIN = 1;
+export const HealthResponse = z.object({
+    ok: z.literal(true),
+    bridgeVersion: z.string(),
+    protocol: z.object({ version: z.number().int().positive(), min: z.number().int().positive() }),
+});
+export const SessionsResponse = z.array(Session);
+export const SendResponse = z.object({ id: z.string().regex(BUNDLE_ID), status: Status });
+export const BundleStatusResponse = z.object({ bundle: Bundle, status: Status.nullable() });
+export const AckRequest = z.object({ summary: z.string().optional() });
+export const OkResponse = z.object({ ok: z.literal(true) });
+export const ErrorResponse = z.object({ error: z.string() });
+// A client supports protocol versions [min, max]; a bridge speaks `version` and still accepts down to `min`.
+export function compatibility(client, bridge) {
+    if (bridge.version < client.min)
+        return "bridge-too-old";
+    if (client.max < bridge.min)
+        return "extension-too-old";
+    return "ok";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anynotate/protocol",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Wire types and zod schemas shared by Anynotate clients and the Anynotate bridge.",
   "license": "Apache-2.0",
   "author": "Kun Xu",
@@ -16,6 +16,12 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./fixtures": {
+      "bun": "./src/fixtures.ts",
+      "types": "./dist/fixtures.d.ts",
+      "import": "./dist/fixtures.js",
+      "default": "./dist/fixtures.js"
     }
   },
   "files": ["dist", "src", "PROTOCOL.md", "README.md", "LICENSE"],

package/src/fixtures.ts

@@ -0,0 +1,70 @@
+import type { z } from "zod";
+import {
+  BundleStatusResponse, type BundleInput, ErrorResponse, HealthResponse, OkResponse, SendResponse, SessionsResponse,
+} from "./index.js";
+
+// Shared request/response examples. The bridge's tests replay every exchange against a live bridge; client
+// tests check that they make the extension exchanges with exactly this method and path and can parse the examples.
+export const FIXTURE_EXTENSION_ORIGIN = "chrome-extension://abcdefghijklmnopabcdefghijklmnop";
+export const EXAMPLE_BUNDLE_ID = "2026-09-24T153200-tomato-soup-recipes";
+
+export const exampleBundleInput: BundleInput = {
+  v: 1,
+  url: "https://recipes.example.com/tomato-soup",
+  title: "Tomato soup – Recipes",
+  sentAt: "2026-09-24T15:32:00.000Z",
+  target: { agent: "claude", sessionId: "s-1", cwd: "/tmp/repo" },
+  overall: "can we make this vegan?",
+  annotations: [{
+    id: "A1", kind: "text", comment: "is there a substitute for cream?", intent: "question",
+    anchor: {
+      quote: { exact: "200 ml cream", prefix: "stir in ", suffix: " before serving" },
+      css: "section#ingredients > li:nth-child(3)", path: ["main", "section#ingredients", "ul"], near: "Ingredients",
+    },
+    box: { x: 10, y: 20, w: 100, h: 18 },
+    viewport: { w: 1280, h: 800, dpr: 2, scrollY: 0 },
+    crop: "crops/A1.png",
+  }],
+};
+export const examplePage = "# Tomato soup\n\nstir in ⟦A1⟧200 ml cream before serving\n";
+
+export const responseSchemas = {
+  HealthResponse, SessionsResponse, SendResponse, BundleStatusResponse, OkResponse, ErrorResponse,
+} satisfies Record<string, z.ZodType>;
+export type SchemaName = keyof typeof responseSchemas;
+
+export type Exchange = {
+  name: string;
+  request: {
+    method: "GET" | "POST";
+    path: string;
+    // extension = allowed Origin and token; extension-no-token = allowed Origin only; token = X-Anynotate-Token, no Origin;
+    // foreign-origin = a web page.
+    auth: "extension" | "extension-no-token" | "token" | "none" | "foreign-origin";
+    host?: string;
+    json?: unknown;
+    bundle?: { input: BundleInput; files: Record<string, string> };
+  };
+  status: number;
+  response: { schema: SchemaName; example: unknown };
+};
+
+const health = { ok: true, bridgeVersion: "0.2.0", protocol: { version: 1, min: 1 } };
+const queued = { state: "queued", at: "2026-09-24T15:32:01.000Z" };
+const exampleBundle = { ...exampleBundleInput, id: EXAMPLE_BUNDLE_ID, files: { page: "page.md", screenshot: "screenshot.png" } };
+
+export const conformance: Exchange[] = [
+  { name: "health-extension", request: { method: "POST", path: "/health", auth: "extension" }, status: 200, response: { schema: "HealthResponse", example: health } },
+  { name: "health-probe", request: { method: "GET", path: "/health", auth: "none" }, status: 200, response: { schema: "HealthResponse", example: health } },
+  { name: "sessions-extension", request: { method: "POST", path: "/sessions", auth: "extension" }, status: 200, response: { schema: "SessionsResponse", example: [{ id: "w1:p2", agent: "claude", cwd: "/home/me/project", title: "shell", method: "herdr", pane: "w1:p2" }] } },
+  { name: "sessions-token", request: { method: "GET", path: "/sessions", auth: "token" }, status: 200, response: { schema: "SessionsResponse", example: [] } },
+  { name: "sessions-extension-no-token", request: { method: "POST", path: "/sessions", auth: "extension-no-token" }, status: 401, response: { schema: "ErrorResponse", example: { error: "bad token" } } },
+  { name: "sessions-unauthenticated", request: { method: "POST", path: "/sessions", auth: "none" }, status: 401, response: { schema: "ErrorResponse", example: { error: "bad token" } } },
+  { name: "sessions-foreign-origin", request: { method: "POST", path: "/sessions", auth: "foreign-origin" }, status: 403, response: { schema: "ErrorResponse", example: { error: "forbidden origin" } } },
+  { name: "health-wrong-host", request: { method: "GET", path: "/health", auth: "none", host: "evil.example" }, status: 403, response: { schema: "ErrorResponse", example: { error: "bad host" } } },
+  { name: "send-bundle", request: { method: "POST", path: "/bundles", auth: "extension", bundle: { input: exampleBundleInput, files: { "page.md": examplePage } } }, status: 201, response: { schema: "SendResponse", example: { id: EXAMPLE_BUNDLE_ID, status: queued } } },
+  { name: "bundle-status-extension", request: { method: "POST", path: "/bundles/:id/status", auth: "extension" }, status: 200, response: { schema: "BundleStatusResponse", example: { bundle: exampleBundle, status: queued } } },
+  { name: "bundle-status-token", request: { method: "GET", path: "/bundles/:id", auth: "token" }, status: 200, response: { schema: "BundleStatusResponse", example: { bundle: exampleBundle, status: queued } } },
+  { name: "ack", request: { method: "POST", path: "/bundles/:id/ack", auth: "token", json: { summary: "suggested oat cream" } }, status: 200, response: { schema: "OkResponse", example: { ok: true } } },
+  { name: "bundle-status-unknown", request: { method: "POST", path: "/bundles/2026-01-01T000000-missing/status", auth: "extension" }, status: 404, response: { schema: "ErrorResponse", example: { error: "not found" } } },
+];

package/src/index.ts

@@ -86,3 +86,42 @@ export const Session = z.object({
   sessionIds: z.array(z.string()).optional(),
 });
 export type Session = z.infer<typeof Session>;
+
+// Protocol v1. Additive changes (optional fields, new endpoints) keep the version; removals, renames and
+// semantic changes bump PROTOCOL_VERSION, and the bridge keeps accepting the previous version for a release.
+export const PROTOCOL_VERSION = 1;
+export const PROTOCOL_MIN = 1;
+
+export const HealthResponse = z.object({
+  ok: z.literal(true),
+  bridgeVersion: z.string(),
+  protocol: z.object({ version: z.number().int().positive(), min: z.number().int().positive() }),
+});
+export type HealthResponse = z.infer<typeof HealthResponse>;
+
+export const SessionsResponse = z.array(Session);
+export type SessionsResponse = z.infer<typeof SessionsResponse>;
+
+export const SendResponse = z.object({ id: z.string().regex(BUNDLE_ID), status: Status });
+export type SendResponse = z.infer<typeof SendResponse>;
+
+export const BundleStatusResponse = z.object({ bundle: Bundle, status: Status.nullable() });
+export type BundleStatusResponse = z.infer<typeof BundleStatusResponse>;
+
+export const AckRequest = z.object({ summary: z.string().optional() });
+export type AckRequest = z.infer<typeof AckRequest>;
+
+export const OkResponse = z.object({ ok: z.literal(true) });
+export type OkResponse = z.infer<typeof OkResponse>;
+
+export const ErrorResponse = z.object({ error: z.string() });
+export type ErrorResponse = z.infer<typeof ErrorResponse>;
+
+export type Compatibility = "ok" | "bridge-too-old" | "extension-too-old";
+
+// A client supports protocol versions [min, max]; a bridge speaks `version` and still accepts down to `min`.
+export function compatibility(client: { min: number; max: number }, bridge: { version: number; min: number }): Compatibility {
+  if (bridge.version < client.min) return "bridge-too-old";
+  if (client.max < bridge.min) return "extension-too-old";
+  return "ok";
+}