@anynotate/protocol 0.2.0 → 0.3.0

package/PROTOCOL.md

@@ -1,12 +1,12 @@
-# Anynotate protocol v1
+# Anynotate protocol v2
 
 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 } }`.
+`POST /health` (or `GET`) → `{ "ok": true, "bridgeVersion": "0.3.0", "protocol": { "version": 2, "min": 1 } }`.
 
-A client supports a range of protocol versions (the extension: `min 1, max 1`) and calls `compatibility(clientRange, response.protocol)`:
+A client supports a range of protocol versions (the extension: `min 2, max 2`) and calls `compatibility(clientRange, response.protocol)`:
 
 - `ok` — the ranges overlap; proceed.
 - `bridge-too-old` — ask the user to update the bridge; don't send.
@@ -66,12 +66,29 @@ Each bundle is written to `$ANYNOTATE_HOME/inbox/<id>/` (default `~/.anynotate`)
 
 `$ANYNOTATE_HOME/inbox/latest` points at the newest bundle.
 
+## Intents
+
+Each annotation may carry an `intent` telling the agent what the user wants. `INTENTS` lists the current ones; `README.md` puts a directive line under the note's heading instead of naming the intent:
+
+| `intent` | Directive in `README.md` |
+|---|---|
+| `explain` | `**Explain** this.` |
+| `change` | `**Change requested.**` |
+| `approve` | `**Approved** — no change needed.` |
+
+The v1 values `question`, `bug` and `note` are still accepted and appear in the heading as before, with no directive line. `change` was also a v1 value; it keeps its name and now gets the directive line. No `intent` means no directive either.
+
 ## 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.
 
+### Version history
+
+- **v1** — handshake, token-only access, native-host token delivery.
+- **v2** — intents `explain`, `change`, `approve` (legacy `question`, `bug`, `note` still accepted). `PROTOCOL_MIN` stays `1`: a v2 bridge accepts v1 clients.
+
 ## Threat model
 
 - **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.

package/dist/fixtures.d.ts

@@ -67,8 +67,10 @@ export declare const responseSchemas: {
                 }>;
                 comment: z.ZodString;
                 intent: z.ZodOptional<z.ZodEnum<{
-                    question: "question";
+                    explain: "explain";
                     change: "change";
+                    approve: "approve";
+                    question: "question";
                     bug: "bug";
                     note: "note";
                 }>>;

package/dist/fixtures.js

@@ -11,7 +11,7 @@ export const exampleBundleInput = {
     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",
+            id: "A1", kind: "text", comment: "is there a substitute for cream?", intent: "explain",
             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",
@@ -25,7 +25,7 @@ export const examplePage = "# Tomato soup\n\nstir in ⟦A1⟧200 ml cream before
 export const responseSchemas = {
     HealthResponse, SessionsResponse, SendResponse, BundleStatusResponse, OkResponse, ErrorResponse,
 };
-const health = { ok: true, bridgeVersion: "0.2.0", protocol: { version: 1, min: 1 } };
+const health = { ok: true, bridgeVersion: "0.3.0", protocol: { version: 2, 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 = [

package/dist/index.d.ts

@@ -2,6 +2,10 @@ import { z } from "zod";
 export declare const AGENT_NAME: RegExp;
 export declare const Agent: z.ZodString;
 export type Agent = z.infer<typeof Agent>;
+export declare const INTENTS: readonly ["explain", "change", "approve"];
+export declare const LEGACY_INTENTS: readonly ["question", "bug", "note"];
+/** The intent clients should send; parsed annotations may also hold a LEGACY_INTENTS value. */
+export type Intent = (typeof INTENTS)[number];
 export declare const Annotation: z.ZodObject<{
     id: z.ZodString;
     kind: z.ZodEnum<{
@@ -10,8 +14,10 @@ export declare const Annotation: z.ZodObject<{
     }>;
     comment: z.ZodString;
     intent: z.ZodOptional<z.ZodEnum<{
-        question: "question";
+        explain: "explain";
         change: "change";
+        approve: "approve";
+        question: "question";
         bug: "bug";
         note: "note";
     }>>;
@@ -80,8 +86,10 @@ export declare const BundleInput: z.ZodObject<{
         }>;
         comment: z.ZodString;
         intent: z.ZodOptional<z.ZodEnum<{
-            question: "question";
+            explain: "explain";
             change: "change";
+            approve: "approve";
+            question: "question";
             bug: "bug";
             note: "note";
         }>>;
@@ -145,8 +153,10 @@ export declare const Bundle: z.ZodObject<{
         }>;
         comment: z.ZodString;
         intent: z.ZodOptional<z.ZodEnum<{
-            question: "question";
+            explain: "explain";
             change: "change";
+            approve: "approve";
+            question: "question";
             bug: "bug";
             note: "note";
         }>>;
@@ -234,7 +244,7 @@ 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_VERSION = 2;
 export declare const PROTOCOL_MIN = 1;
 export declare const HealthResponse: z.ZodObject<{
     ok: z.ZodLiteral<true>;
@@ -301,8 +311,10 @@ export declare const BundleStatusResponse: z.ZodObject<{
             }>;
             comment: z.ZodString;
             intent: z.ZodOptional<z.ZodEnum<{
-                question: "question";
+                explain: "explain";
                 change: "change";
+                approve: "approve";
+                question: "question";
                 bug: "bug";
                 note: "note";
             }>>;

package/dist/index.js

@@ -1,13 +1,15 @@
 import { z } from "zod";
 export const AGENT_NAME = /^[a-z][a-z0-9_-]{0,31}$/;
 export const Agent = z.string().regex(AGENT_NAME);
+export const INTENTS = ["explain", "change", "approve"];
+export const LEGACY_INTENTS = ["question", "bug", "note"];
 const Box = z.object({ x: z.number(), y: z.number(), w: z.number(), h: z.number() });
 export const Annotation = z.object({
     id: z.string().regex(/^A\d+$/),
     // v1 kinds only; "region" | "draw" are reserved for later tools.
     kind: z.enum(["text", "element"]),
     comment: z.string(),
-    intent: z.enum(["question", "change", "bug", "note"]).optional(),
+    intent: z.enum([...INTENTS, ...LEGACY_INTENTS]).optional(),
     anchor: z.object({
         quote: z.object({ exact: z.string(), prefix: z.string(), suffix: z.string() }).optional(),
         position: z.object({ start: z.number().int(), end: z.number().int() }).optional(),
@@ -68,9 +70,9 @@ 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
+// Protocol v2. 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_VERSION = 2;
 export const PROTOCOL_MIN = 1;
 export const HealthResponse = z.object({
     ok: z.literal(true),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anynotate/protocol",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Wire types and zod schemas shared by Anynotate clients and the Anynotate bridge.",
   "license": "Apache-2.0",
   "author": "Kun Xu",

package/src/fixtures.ts

@@ -16,7 +16,7 @@ export const exampleBundleInput: BundleInput = {
   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",
+    id: "A1", kind: "text", comment: "is there a substitute for cream?", intent: "explain",
     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",
@@ -49,7 +49,7 @@ export type Exchange = {
   response: { schema: SchemaName; example: unknown };
 };
 
-const health = { ok: true, bridgeVersion: "0.2.0", protocol: { version: 1, min: 1 } };
+const health = { ok: true, bridgeVersion: "0.3.0", protocol: { version: 2, 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" } };
 

package/src/index.ts

@@ -4,6 +4,11 @@ export const AGENT_NAME = /^[a-z][a-z0-9_-]{0,31}$/;
 export const Agent = z.string().regex(AGENT_NAME);
 export type Agent = z.infer<typeof Agent>;
 
+export const INTENTS = ["explain", "change", "approve"] as const;
+export const LEGACY_INTENTS = ["question", "bug", "note"] as const;
+/** The intent clients should send; parsed annotations may also hold a LEGACY_INTENTS value. */
+export type Intent = (typeof INTENTS)[number];
+
 const Box = z.object({ x: z.number(), y: z.number(), w: z.number(), h: z.number() });
 
 export const Annotation = z.object({
@@ -11,7 +16,7 @@ export const Annotation = z.object({
   // v1 kinds only; "region" | "draw" are reserved for later tools.
   kind: z.enum(["text", "element"]),
   comment: z.string(),
-  intent: z.enum(["question", "change", "bug", "note"]).optional(),
+  intent: z.enum([...INTENTS, ...LEGACY_INTENTS]).optional(),
   anchor: z.object({
     quote: z.object({ exact: z.string(), prefix: z.string(), suffix: z.string() }).optional(),
     position: z.object({ start: z.number().int(), end: z.number().int() }).optional(),
@@ -87,9 +92,9 @@ export const Session = z.object({
 });
 export type Session = z.infer<typeof Session>;
 
-// Protocol v1. Additive changes (optional fields, new endpoints) keep the version; removals, renames and
+// Protocol v2. 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_VERSION = 2;
 export const PROTOCOL_MIN = 1;
 
 export const HealthResponse = z.object({