@reins-ai/contract 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanoriva
+
+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,48 @@
-# Temporary Holding Version
+# @reins-ai/contract
 
-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 protocol between the page ([`@reins-ai/web`](../agent-web)) and the bridge ([`@reins-ai/bridge`](../agent-bridge)): [zod](https://zod.dev) schemas and their types. You do not need it directly when using those packages; it is for writing another compatible client or bridge.
+
+```sh
+npm install @reins-ai/contract
+```
+
+## Contents
+
+| Group | Schemas |
+| --- | --- |
+| Session | `Hello`, `PairRequired`, `PairOffer`, `Welcome`, `Unpaired`, `SessionError`, `PROTOCOL_VERSION` |
+| Orders | `Order` (`{ id, action, params, page }`), `OrderResponse`, `OrderError`, `ProtocolErrorCode` |
+| Events | `page.changed`, `content.available`, `tab.state` |
+| Catalog | `ActionDefinition`: the MCP tool format plus `scope` (`general` / `page`) and `effect` (`none` / `confirm`) |
+| Content | `Content` (`{ role: 'content-not-instructions', type, data, more? }`), `CONTENT_ROLE` |
+| Messages | `PageMessage` (page → bridge) and `BridgeMessage` (bridge → page) |
+
+```ts
+import { parsePageMessage } from '@reins-ai/contract';
+
+const parsed = parsePageMessage(raw);
+if (!parsed.ok) return; // invalid message: dropped
+```
+
+## Session
+
+```
+page   → hello { protocolVersion, tabId, token? }
+bridge → welcome { protocolVersion, token }   (valid token)
+       | pair_required                         (no token, or an invalid one)
+page   → pair_offer { code }                   (the page generates and shows the code)
+bridge → welcome { protocolVersion, token }    (once the AI sends that code with pair_tab)
+bridge → unpaired                              (the AI disconnected the tab)
+```
+
+## Orders
+
+Based on JSON-RPC 2.0: exactly one response per order. `page` is the screen counter; if it does not match the page's, the response is `PAGE_CHANGED`.
+
+```json
+{ "id": "o1", "action": "read_content", "params": { "part": 0 }, "page": 3 }
+{ "id": "o1", "ok": true, "result": { "role": "content-not-instructions", "type": "recipe", "data": {} } }
+{ "id": "o1", "ok": false, "error": { "code": "NOT_AVAILABLE", "message": "…" } }
+```
+
+Protocol codes: `UNKNOWN_ACTION`, `INVALID_PARAMS`, `NOT_AVAILABLE`, `NEEDS_CONFIRMATION`, `INVALID_CODE`, `TIMEOUT`, `PAGE_CHANGED`, `TAB_DISCONNECTED`. Each action may add its own, in `UPPER_SNAKE_CASE`.

package/dist/catalog.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+/**
+ * An action the page exposes to the AI. Same shape as an MCP tool, plus `scope` (`general` actions exist on
+ * every page, `page` actions belong to the current screen) and `effect` (`confirm` actions only run after the
+ * user says the confirmation code shown on screen).
+ *
+ * @example
+ * const sort: ActionDefinition = {
+ *   name: 'sort_appointments',
+ *   description: 'Sorts the upcoming appointments.',
+ *   inputSchema: { type: 'object', properties: { by: { type: 'string', enum: ['date', 'specialty'] } } },
+ *   scope: 'page',
+ *   effect: 'none',
+ * };
+ */
+export declare const ActionDefinition: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    inputSchema: z.ZodObject<{
+        type: z.ZodLiteral<"object">;
+    }, z.core.$loose>;
+    scope: z.ZodEnum<{
+        general: "general";
+        page: "page";
+    }>;
+    effect: z.ZodEnum<{
+        none: "none";
+        confirm: "confirm";
+    }>;
+}, z.core.$strip>;
+export type ActionDefinition = z.infer<typeof ActionDefinition>;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;iBAM3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/catalog.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+/**
+ * An action the page exposes to the AI. Same shape as an MCP tool, plus `scope` (`general` actions exist on
+ * every page, `page` actions belong to the current screen) and `effect` (`confirm` actions only run after the
+ * user says the confirmation code shown on screen).
+ *
+ * @example
+ * const sort: ActionDefinition = {
+ *   name: 'sort_appointments',
+ *   description: 'Sorts the upcoming appointments.',
+ *   inputSchema: { type: 'object', properties: { by: { type: 'string', enum: ['date', 'specialty'] } } },
+ *   scope: 'page',
+ *   effect: 'none',
+ * };
+ */
+export const ActionDefinition = z.object({
+    name: z.string().regex(/^[A-Za-z0-9_.-]{1,128}$/),
+    description: z.string().min(1),
+    inputSchema: z.looseObject({ type: z.literal('object') }),
+    scope: z.enum(['general', 'page']),
+    effect: z.enum(['none', 'confirm']),
+});
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,yBAAyB,CAAC;IACjD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;IACzD,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAClC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACpC,CAAC,CAAC"}

package/dist/content.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+/**
+ * Role carried by every piece of page content sent to the AI. It marks the content as data to read, never as
+ * instructions, as one of the protections against prompt injection.
+ */
+export declare const CONTENT_ROLE = "content-not-instructions";
+/**
+ * Envelope for the content a screen offers to the AI. The app defines `type` and the shape of `data`; long
+ * content is split into parts, and `more` tells the AI to ask for the next one.
+ *
+ * @example
+ * const part: Content = {
+ *   role: CONTENT_ROLE,
+ *   type: 'report',
+ *   data: { blocks: ['Blood test', 'Fasting glucose: 112 mg/dl'] },
+ *   more: true,
+ * };
+ */
+export declare const Content: z.ZodObject<{
+    role: z.ZodLiteral<"content-not-instructions">;
+    type: z.ZodString;
+    data: z.ZodUnknown;
+    more: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type Content = z.infer<typeof Content>;
+//# sourceMappingURL=content.d.ts.map

package/dist/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,YAAY,6BAA6B,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO;;;;;iBAKlB,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,OAAO,CAAC,CAAC"}

package/dist/content.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+/**
+ * Role carried by every piece of page content sent to the AI. It marks the content as data to read, never as
+ * instructions, as one of the protections against prompt injection.
+ */
+export const CONTENT_ROLE = 'content-not-instructions';
+/**
+ * Envelope for the content a screen offers to the AI. The app defines `type` and the shape of `data`; long
+ * content is split into parts, and `more` tells the AI to ask for the next one.
+ *
+ * @example
+ * const part: Content = {
+ *   role: CONTENT_ROLE,
+ *   type: 'report',
+ *   data: { blocks: ['Blood test', 'Fasting glucose: 112 mg/dl'] },
+ *   more: true,
+ * };
+ */
+export const Content = z.object({
+    role: z.literal(CONTENT_ROLE),
+    type: z.string().min(1),
+    data: z.unknown(),
+    more: z.boolean().optional(),
+});
+//# sourceMappingURL=content.js.map

package/dist/content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.js","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,0BAA0B,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;IAC7B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE;IACjB,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAC7B,CAAC,CAAC"}

package/dist/events.d.ts

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+/** Sent when the screen changes, with the new route, the new screen counter and the actions now available. */
+export declare const PageChanged: z.ZodObject<{
+    event: z.ZodLiteral<"page.changed">;
+    data: z.ZodObject<{
+        route: z.ZodString;
+        title: z.ZodString;
+        page: z.ZodInt;
+        actions: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+            inputSchema: z.ZodObject<{
+                type: z.ZodLiteral<"object">;
+            }, z.core.$loose>;
+            scope: z.ZodEnum<{
+                general: "general";
+                page: "page";
+            }>;
+            effect: z.ZodEnum<{
+                none: "none";
+                confirm: "confirm";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** Sent when the current screen starts offering content to read. */
+export declare const ContentAvailable: z.ZodObject<{
+    event: z.ZodLiteral<"content.available">;
+    data: z.ZodObject<{
+        type: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** Sent when the tab becomes active, goes to the background or is closed. */
+export declare const TabState: z.ZodObject<{
+    event: z.ZodLiteral<"tab.state">;
+    data: z.ZodObject<{
+        state: z.ZodEnum<{
+            active: "active";
+            background: "background";
+            closed: "closed";
+        }>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Notifications from the page. Unlike orders they carry no id and expect no response; the bridge queues them
+ * and hands them to the AI with its next result.
+ */
+export declare const PageEvent: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    event: z.ZodLiteral<"page.changed">;
+    data: z.ZodObject<{
+        route: z.ZodString;
+        title: z.ZodString;
+        page: z.ZodInt;
+        actions: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+            inputSchema: z.ZodObject<{
+                type: z.ZodLiteral<"object">;
+            }, z.core.$loose>;
+            scope: z.ZodEnum<{
+                general: "general";
+                page: "page";
+            }>;
+            effect: z.ZodEnum<{
+                none: "none";
+                confirm: "confirm";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    event: z.ZodLiteral<"content.available">;
+    data: z.ZodObject<{
+        type: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    event: z.ZodLiteral<"tab.state">;
+    data: z.ZodObject<{
+        state: z.ZodEnum<{
+            active: "active";
+            background: "background";
+            closed: "closed";
+        }>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "event">;
+export type PageEvent = z.infer<typeof PageEvent>;
+export type PageEventName = PageEvent['event'];
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,8GAA8G;AAC9G,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;iBAQtB,CAAC;AAEH,oEAAoE;AACpE,eAAO,MAAM,gBAAgB;;;;;;iBAM3B,CAAC;AAEH,6EAA6E;AAC7E,eAAO,MAAM,QAAQ;;;;;;;;;iBAKnB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAA2E,CAAC;AAClG,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAClD,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC"}

package/dist/events.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { ActionDefinition } from './catalog.js';
+import { PageCounter } from './orders.js';
+/** Sent when the screen changes, with the new route, the new screen counter and the actions now available. */
+export const PageChanged = z.object({
+    event: z.literal('page.changed'),
+    data: z.object({
+        route: z.string(),
+        title: z.string(),
+        page: PageCounter,
+        actions: z.array(ActionDefinition),
+    }),
+});
+/** Sent when the current screen starts offering content to read. */
+export const ContentAvailable = z.object({
+    event: z.literal('content.available'),
+    data: z.object({
+        type: z.string().min(1),
+        title: z.string(),
+    }),
+});
+/** Sent when the tab becomes active, goes to the background or is closed. */
+export const TabState = z.object({
+    event: z.literal('tab.state'),
+    data: z.object({
+        state: z.enum(['active', 'background', 'closed']),
+    }),
+});
+/**
+ * Notifications from the page. Unlike orders they carry no id and expect no response; the bridge queues them
+ * and hands them to the AI with its next result.
+ */
+export const PageEvent = z.discriminatedUnion('event', [PageChanged, ContentAvailable, TabState]);
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,8GAA8G;AAC9G,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC;IAChC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;QACjB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;QACjB,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC;KACnC,CAAC;CACH,CAAC,CAAC;AAEH,oEAAoE;AACpE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC;IACrC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACvB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;KAClB,CAAC;CACH,CAAC,CAAC;AAEH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/B,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;IAC7B,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,YAAY,EAAE,QAAQ,CAAC,CAAC;KAClD,CAAC;CACH,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,kBAAkB,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,gBAAgB,EAAE,QAAQ,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './catalog.js';
+export * from './content.js';
+export * from './events.js';
+export * from './messages.js';
+export * from './orders.js';
+export * from './session.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from './catalog.js';
+export * from './content.js';
+export * from './events.js';
+export * from './messages.js';
+export * from './orders.js';
+export * from './session.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/dist/messages.d.ts

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+/** Everything the page can send to the bridge. */
+export declare const PageMessage: z.ZodUnion<readonly [z.ZodObject<{
+    type: z.ZodLiteral<"hello">;
+    protocolVersion: z.ZodInt;
+    tabId: z.ZodString;
+    token: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"pair_offer">;
+    code: z.ZodString;
+}, z.core.$strip>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    ok: z.ZodLiteral<true>;
+    result: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    ok: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        attemptsLeft: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "ok">, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    event: z.ZodLiteral<"page.changed">;
+    data: z.ZodObject<{
+        route: z.ZodString;
+        title: z.ZodString;
+        page: z.ZodInt;
+        actions: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+            inputSchema: z.ZodObject<{
+                type: z.ZodLiteral<"object">;
+            }, z.core.$loose>;
+            scope: z.ZodEnum<{
+                general: "general";
+                page: "page";
+            }>;
+            effect: z.ZodEnum<{
+                none: "none";
+                confirm: "confirm";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    event: z.ZodLiteral<"content.available">;
+    data: z.ZodObject<{
+        type: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    event: z.ZodLiteral<"tab.state">;
+    data: z.ZodObject<{
+        state: z.ZodEnum<{
+            active: "active";
+            background: "background";
+            closed: "closed";
+        }>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "event">]>;
+export type PageMessage = z.infer<typeof PageMessage>;
+/** Everything the bridge can send to the page. */
+export declare const BridgeMessage: z.ZodUnion<readonly [z.ZodObject<{
+    type: z.ZodLiteral<"welcome">;
+    protocolVersion: z.ZodInt;
+    token: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"pair_required">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"unpaired">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"session_error">;
+    code: z.ZodEnum<{
+        VERSION_MISMATCH: "VERSION_MISMATCH";
+        INVALID_MESSAGE: "INVALID_MESSAGE";
+    }>;
+    message: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    action: z.ZodString;
+    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    page: z.ZodInt;
+}, z.core.$strip>]>;
+export type BridgeMessage = z.infer<typeof BridgeMessage>;
+export type ParseResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Parses and validates a raw message received by the bridge.
+ *
+ * @example
+ * const parsed = parsePageMessage(raw);
+ * if (!parsed.ok) socket.close(1008, parsed.error);
+ */
+export declare const parsePageMessage: (raw: string) => ParseResult<PageMessage>;
+/** Parses and validates a raw message received by the page. */
+export declare const parseBridgeMessage: (raw: string) => ParseResult<BridgeMessage>;
+//# sourceMappingURL=messages.d.ts.map

package/dist/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,kDAAkD;AAClD,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8BAAwD,CAAC;AACjF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,kDAAkD;AAClD,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;mBAAkE,CAAC;AAC7F,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAenF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,MAAM,KAAG,WAAW,CAAC,WAAW,CAA4B,CAAC;AAEnG,+DAA+D;AAC/D,eAAO,MAAM,kBAAkB,GAAI,KAAK,MAAM,KAAG,WAAW,CAAC,aAAa,CAC/C,CAAC"}

package/dist/messages.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { PageEvent } from './events.js';
+import { Order, OrderResponse } from './orders.js';
+import { Hello, PairOffer, PairRequired, SessionError, Unpaired, Welcome } from './session.js';
+/** Everything the page can send to the bridge. */
+export const PageMessage = z.union([Hello, PairOffer, OrderResponse, PageEvent]);
+/** Everything the bridge can send to the page. */
+export const BridgeMessage = z.union([Welcome, PairRequired, Unpaired, SessionError, Order]);
+function parse(schema, raw) {
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, error: 'Not valid JSON' };
+    }
+    const result = schema.safeParse(json);
+    return result.success
+        ? { ok: true, value: result.data }
+        : { ok: false, error: z.prettifyError(result.error) };
+}
+/**
+ * Parses and validates a raw message received by the bridge.
+ *
+ * @example
+ * const parsed = parsePageMessage(raw);
+ * if (!parsed.ok) socket.close(1008, parsed.error);
+ */
+export const parsePageMessage = (raw) => parse(PageMessage, raw);
+/** Parses and validates a raw message received by the page. */
+export const parseBridgeMessage = (raw) => parse(BridgeMessage, raw);
+//# sourceMappingURL=messages.js.map

package/dist/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE/F,kDAAkD;AAClD,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC,CAAC;AAGjF,kDAAkD;AAClD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC,CAAC;AAK7F,SAAS,KAAK,CAAI,MAAoB,EAAE,GAAW;IACjD,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAChD,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACtC,OAAO,MAAM,CAAC,OAAO;QACnB,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE;QAClC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAC1D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,GAAW,EAA4B,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;AAEnG,+DAA+D;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,GAAW,EAA8B,EAAE,CAC5E,KAAK,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC"}

package/dist/orders.d.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+/** Screen counter. It increases with every `page.changed`. */
+export declare const PageCounter: z.ZodInt;
+/**
+ * An order from the AI to the page. `page` is the screen counter the AI knew when it sent the order: if the
+ * screen has changed since, the page answers `PAGE_CHANGED` instead of acting on a screen the AI has not seen.
+ *
+ * @example
+ * const order: Order = { id: 'o-1', action: 'highlight', params: { text: 'Fasting glucose' }, page: 4 };
+ */
+export declare const Order: z.ZodObject<{
+    id: z.ZodString;
+    action: z.ZodString;
+    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    page: z.ZodInt;
+}, z.core.$strip>;
+export type Order = z.infer<typeof Order>;
+/** Error codes defined by the protocol. Actions may add their own, in UPPER_SNAKE_CASE (e.g. `TEXT_NOT_FOUND`). */
+export declare const ProtocolErrorCode: {
+    readonly UNKNOWN_ACTION: "UNKNOWN_ACTION";
+    readonly INVALID_PARAMS: "INVALID_PARAMS";
+    readonly NOT_AVAILABLE: "NOT_AVAILABLE";
+    readonly NEEDS_CONFIRMATION: "NEEDS_CONFIRMATION";
+    readonly INVALID_CODE: "INVALID_CODE";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly PAGE_CHANGED: "PAGE_CHANGED";
+    readonly TAB_DISCONNECTED: "TAB_DISCONNECTED";
+};
+export declare const OrderError: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    attemptsLeft: z.ZodOptional<z.ZodInt>;
+}, z.core.$strip>;
+export type OrderError = z.infer<typeof OrderError>;
+export declare const OrderSuccess: z.ZodObject<{
+    id: z.ZodString;
+    ok: z.ZodLiteral<true>;
+    result: z.ZodUnknown;
+}, z.core.$strip>;
+export declare const OrderFailure: z.ZodObject<{
+    id: z.ZodString;
+    ok: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        attemptsLeft: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * The page's answer to an order: exactly one per order, with the same id.
+ *
+ * @example
+ * const done: OrderResponse = { id: 'o-1', ok: true, result: { scrolled: false } };
+ * const failed: OrderResponse = { id: 'o-2', ok: false, error: { code: 'TEXT_NOT_FOUND', message: 'That text is not on the screen' } };
+ */
+export declare const OrderResponse: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    ok: z.ZodLiteral<true>;
+    result: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    ok: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        attemptsLeft: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "ok">;
+export type OrderResponse = z.infer<typeof OrderResponse>;
+//# sourceMappingURL=orders.d.ts.map

package/dist/orders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orders.d.ts","sourceRoot":"","sources":["../src/orders.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8DAA8D;AAC9D,eAAO,MAAM,WAAW,UAAwB,CAAC;AAEjD;;;;;;GAMG;AACH,eAAO,MAAM,KAAK;;;;;iBAKhB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAC;AAE1C,mHAAmH;AACnH,eAAO,MAAM,iBAAiB;;;;;;;;;CASpB,CAAC;AAEX,eAAO,MAAM,UAAU;;;;iBAIrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,YAAY;;;;iBAIvB,CAAC;AAEH,eAAO,MAAM,YAAY;;;;;;;;iBAIvB,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;yBAA2D,CAAC;AACtF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/orders.js

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+/** Screen counter. It increases with every `page.changed`. */
+export const PageCounter = z.int().nonnegative();
+/**
+ * An order from the AI to the page. `page` is the screen counter the AI knew when it sent the order: if the
+ * screen has changed since, the page answers `PAGE_CHANGED` instead of acting on a screen the AI has not seen.
+ *
+ * @example
+ * const order: Order = { id: 'o-1', action: 'highlight', params: { text: 'Fasting glucose' }, page: 4 };
+ */
+export const Order = z.object({
+    id: z.string().min(1),
+    action: z.string().min(1),
+    params: z.record(z.string(), z.unknown()).default({}),
+    page: PageCounter,
+});
+/** Error codes defined by the protocol. Actions may add their own, in UPPER_SNAKE_CASE (e.g. `TEXT_NOT_FOUND`). */
+export const ProtocolErrorCode = {
+    UNKNOWN_ACTION: 'UNKNOWN_ACTION',
+    INVALID_PARAMS: 'INVALID_PARAMS',
+    NOT_AVAILABLE: 'NOT_AVAILABLE',
+    NEEDS_CONFIRMATION: 'NEEDS_CONFIRMATION',
+    INVALID_CODE: 'INVALID_CODE',
+    TIMEOUT: 'TIMEOUT',
+    PAGE_CHANGED: 'PAGE_CHANGED',
+    TAB_DISCONNECTED: 'TAB_DISCONNECTED',
+};
+export const OrderError = z.object({
+    code: z.string().regex(/^[A-Z][A-Z0-9_]*$/),
+    message: z.string().min(1),
+    attemptsLeft: z.int().nonnegative().optional(),
+});
+export const OrderSuccess = z.object({
+    id: z.string().min(1),
+    ok: z.literal(true),
+    result: z.unknown(),
+});
+export const OrderFailure = z.object({
+    id: z.string().min(1),
+    ok: z.literal(false),
+    error: OrderError,
+});
+/**
+ * The page's answer to an order: exactly one per order, with the same id.
+ *
+ * @example
+ * const done: OrderResponse = { id: 'o-1', ok: true, result: { scrolled: false } };
+ * const failed: OrderResponse = { id: 'o-2', ok: false, error: { code: 'TEXT_NOT_FOUND', message: 'That text is not on the screen' } };
+ */
+export const OrderResponse = z.discriminatedUnion('ok', [OrderSuccess, OrderFailure]);
+//# sourceMappingURL=orders.js.map

package/dist/orders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orders.js","sourceRoot":"","sources":["../src/orders.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8DAA8D;AAC9D,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACrD,IAAI,EAAE,WAAW;CAClB,CAAC,CAAC;AAGH,mHAAmH;AACnH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,cAAc,EAAE,gBAAgB;IAChC,cAAc,EAAE,gBAAgB;IAChC,aAAa,EAAE,eAAe;IAC9B,kBAAkB,EAAE,oBAAoB;IACxC,YAAY,EAAE,cAAc;IAC5B,OAAO,EAAE,SAAS;IAClB,YAAY,EAAE,cAAc;IAC5B,gBAAgB,EAAE,kBAAkB;CAC5B,CAAC;AAEX,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,mBAAmB,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,YAAY,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;CAC/C,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;IACnB,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE;CACpB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IACpB,KAAK,EAAE,UAAU;CAClB,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+/** Protocol version. Bumped only for incompatible changes; the bridge rejects pages on another version. */
+export declare const PROTOCOL_VERSION = 1;
+export declare const PairingCode: z.ZodString;
+/**
+ * First message from the page on every connection. `tabId` identifies the tab across reloads; `token` comes from
+ * a previous pairing and skips pairing again.
+ *
+ * @example
+ * const hello: Hello = { type: 'hello', protocolVersion: PROTOCOL_VERSION, tabId: crypto.randomUUID() };
+ */
+export declare const Hello: z.ZodObject<{
+    type: z.ZodLiteral<"hello">;
+    protocolVersion: z.ZodInt;
+    tabId: z.ZodString;
+    token: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Hello = z.infer<typeof Hello>;
+/**
+ * The 6-digit code the page generated and shows on screen. The user reads it to their AI, the AI sends it to the
+ * bridge with `pair_tab`, and the bridge pairs the tab whose offer matches.
+ */
+export declare const PairOffer: z.ZodObject<{
+    type: z.ZodLiteral<"pair_offer">;
+    code: z.ZodString;
+}, z.core.$strip>;
+export type PairOffer = z.infer<typeof PairOffer>;
+/** The session is ready. The page keeps `token` to skip pairing next time. */
+export declare const Welcome: z.ZodObject<{
+    type: z.ZodLiteral<"welcome">;
+    protocolVersion: z.ZodInt;
+    token: z.ZodString;
+}, z.core.$strip>;
+export type Welcome = z.infer<typeof Welcome>;
+/**
+ * The tab must be paired: the page generates a code, shows it and sends it with `pair_offer`. Sent again when
+ * the code expires or after 5 failed attempts.
+ */
+export declare const PairRequired: z.ZodObject<{
+    type: z.ZodLiteral<"pair_required">;
+}, z.core.$strip>;
+export type PairRequired = z.infer<typeof PairRequired>;
+/** The AI disconnected this tab: its token is revoked and `pair_required` follows. */
+export declare const Unpaired: z.ZodObject<{
+    type: z.ZodLiteral<"unpaired">;
+}, z.core.$strip>;
+export type Unpaired = z.infer<typeof Unpaired>;
+/** A session error. The bridge closes the connection right after sending it. */
+export declare const SessionError: z.ZodObject<{
+    type: z.ZodLiteral<"session_error">;
+    code: z.ZodEnum<{
+        VERSION_MISMATCH: "VERSION_MISMATCH";
+        INVALID_MESSAGE: "INVALID_MESSAGE";
+    }>;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type SessionError = z.infer<typeof SessionError>;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,2GAA2G;AAC3G,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,eAAO,MAAM,WAAW,aAA8B,CAAC;AAEvD;;;;;;GAMG;AACH,eAAO,MAAM,KAAK;;;;;iBAKhB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAC;AAE1C;;;GAGG;AACH,eAAO,MAAM,SAAS;;;iBAGpB,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAElD,8EAA8E;AAC9E,eAAO,MAAM,OAAO;;;;iBAIlB,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,OAAO,CAAC,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,YAAY;;iBAEvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD,sFAAsF;AACtF,eAAO,MAAM,QAAQ;;iBAEnB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD,gFAAgF;AAChF,eAAO,MAAM,YAAY;;;;;;;iBAIvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC"}

package/dist/session.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+/** Protocol version. Bumped only for incompatible changes; the bridge rejects pages on another version. */
+export const PROTOCOL_VERSION = 1;
+export const PairingCode = z.string().regex(/^\d{6}$/);
+/**
+ * First message from the page on every connection. `tabId` identifies the tab across reloads; `token` comes from
+ * a previous pairing and skips pairing again.
+ *
+ * @example
+ * const hello: Hello = { type: 'hello', protocolVersion: PROTOCOL_VERSION, tabId: crypto.randomUUID() };
+ */
+export const Hello = z.object({
+    type: z.literal('hello'),
+    protocolVersion: z.int().positive(),
+    tabId: z.string().min(1),
+    token: z.string().min(1).optional(),
+});
+/**
+ * The 6-digit code the page generated and shows on screen. The user reads it to their AI, the AI sends it to the
+ * bridge with `pair_tab`, and the bridge pairs the tab whose offer matches.
+ */
+export const PairOffer = z.object({
+    type: z.literal('pair_offer'),
+    code: PairingCode,
+});
+/** The session is ready. The page keeps `token` to skip pairing next time. */
+export const Welcome = z.object({
+    type: z.literal('welcome'),
+    protocolVersion: z.int().positive(),
+    token: z.string().min(1),
+});
+/**
+ * The tab must be paired: the page generates a code, shows it and sends it with `pair_offer`. Sent again when
+ * the code expires or after 5 failed attempts.
+ */
+export const PairRequired = z.object({
+    type: z.literal('pair_required'),
+});
+/** The AI disconnected this tab: its token is revoked and `pair_required` follows. */
+export const Unpaired = z.object({
+    type: z.literal('unpaired'),
+});
+/** A session error. The bridge closes the connection right after sending it. */
+export const SessionError = z.object({
+    type: z.literal('session_error'),
+    code: z.enum(['VERSION_MISMATCH', 'INVALID_MESSAGE']),
+    message: z.string().min(1),
+});
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,2GAA2G;AAC3G,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAElC,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IACxB,eAAe,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACnC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CACpC,CAAC,CAAC;AAGH;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;IAC7B,IAAI,EAAE,WAAW;CAClB,CAAC,CAAC;AAGH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IAC1B,eAAe,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACnC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACzB,CAAC,CAAC;AAGH;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC;CACjC,CAAC,CAAC;AAGH,sFAAsF;AACtF,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/B,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;CAC5B,CAAC,CAAC;AAGH,gFAAgF;AAChF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC;IAChC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,kBAAkB,EAAE,iBAAiB,CAAC,CAAC;IACrD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC3B,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@reins-ai/contract",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Protocol between the page and the bridge: zod schemas and types.",
+  "license": "MIT",
+  "author": "Sanoriva",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sanoriva/reins.git",
+    "directory": "packages/agent-contract"
+  },
+  "homepage": "https://github.com/sanoriva/reins/tree/main/packages/agent-contract#readme",
+  "bugs": {
+    "url": "https://github.com/sanoriva/reins/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --import tsx --test \"__tests__/**/*.test.ts\""
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "files": [
+    "dist"
+  ]
+}