ai-ax 0.4.2 → 0.5.0

package/README.md

@@ -1,221 +1,155 @@
-# aiax
+# ai-ax
 
 AI Agent Experience (AI/AX) library for Hono + Cloudflare.
 
-人間のための UI/UX と、LLM のための AI/AX を、1 つの操作面として実装するための library。
-AI を特別扱いして専用画面を作るのではなく、AI を読者の一人として扱う。
-画面を見る人間と、木構造を観測する LLM は、同じ状態を読み、同じ操作 (act) で書く。
-aiax はそのために必要な server 側の接続部 — 認証、認可、realtime 同期、MCP、LLM 中継 — を Hono middleware として提供する。
-
-## 0. 思想
-
-web は人間が操作する前提で UI/UX を積み上げてきた。
-そこへ LLM の操作経路を後付けすると、認証認可と操作面が人間用と AI 用の二重になり、どちらかが必ず壊れる。
-aiax は操作の最小単位 action を 1 度だけ宣言させ、UI の click と MCP tool 呼び出しを同じ action に合流させる。
-状態は yjs の単一の木であり、人間には画面として、LLM には get_tree の観測結果として、同じ木が見える。
-
-```mermaid
-flowchart TB
-    UI[UI/UX<br>人間の click] -->|同じ act| ACT[action 宣言<br>1 機能 1 file]
-    AX[AI/AX<br>LLM の tool 呼び出し] -->|同じ act| ACT
-    ACT <-->|読み書き| TREE[yjs Y.Map 'tree'<br>全状態 = 単一の木]
-    TREE -->|画面として| UI
-    TREE -->|get_tree として| AX
-```
+ai-ax builds the human experience (UI/UX) and the AI agent experience (AI/AX) of a web app as one surface. An operation is declared exactly once, and that one declaration is a click handler for the person watching the screen and an MCP tool for the LLM at the same time, backed by one realtime state that both of them read and write.
 
-## 1. 全体構成
+Three ideas carry the library — **one action**, **one tree**, **one road** — and each of them is a mechanism you can point at, not a slogan: one action is a single tool registry that serves the UI, the MCP server and the cross-side transport; one tree is a single yjs map that is rendered as the screen, dumped as the agent's observation and encoded as the persistence snapshot; one road is a single `ai` object that every runtime adapter receives.
 
-前提は Hono + Cloudflare Workers。realtime 同期は partyserver (Durable Objects)、認証は Auth.js、LLM は Claude API の MCP connector。
+## Why
 
-```mermaid
-flowchart TB
-    B[Browser<br>React UI] -->|session<br>cookie| W[Hono Worker<br>aiax middleware]
-    C[Claude API] -->|grant<br>jwt| W
-    W -->|/api/llm| C
-    B <-->|websocket<br />sync| DO[Durable Object<br>y-partyserver]
-    W --> D1[(D1<br>Auth.js tables)]
-    W -->|認可済み room 名<br>x-user-sub header| DO
-```
+The AI agent has become one more user of the web site. The web, however, was built on the assumption that a human is the one operating it, so when an agent path is bolted onto an app as a second route beside the browser, everything doubles: two operation surfaces, two auth stacks, two sets of bugs, roughly twice the code to manage. The two copies inevitably drift apart, and the drift is usually discovered weeks later in a log.
 
-worker には 4 つの middleware を並べるだけでよい。
+ai-ax removes the second copy instead of maintaining it. The person and the agent read the same state and call the same operations, so the declaration of an operation _is_ its MCP tool, and the implementation lives in exactly one place. Every operation is synchronized in realtime through partyserver, whether it arrived from a browser click or from an MCP request, so the agent's moves appear on the human's screen as they happen.
 
-```ts
-const ax = createAiax({ name: 'demo', own: ownSelf(), database: (e) => e.my_d1_aiax, system: PROMPT })
-const app = new Hono().use('*', ax.auth()).use('/parties/*', ax.party()).all('/api/mcp', ax.mcp()).post('/api/llm', ax.llm())
-```
+Authentication is the one place where the two users genuinely differ, because an MCP request from the Claude API cannot carry the browser's session. ai-ax closes that gap with a signed token: when the user sends a prompt, the Hono side mints a token and hands it to the Claude API, the token comes back on every MCP request, and the MCP server verifies the signature before executing anything.
 
-## 2. 認証と認可
+## What
 
-credential は 2 種類だけ。どちらも AUTH_SECRET で署名された jwt であり、平文の user id が network を渡ることはない。
+The assumed stack is Hono on Cloudflare Workers. Realtime sync is partyserver — the successor of partykit, which was deprecated after becoming a Cloudflare product — running yjs docs on Durable Objects deployed straight to Cloudflare. Authentication is Auth.js, and the LLM is the Claude API with its MCP connector. Hono itself is confined to the `ai-ax/hono` entry, so every other entry stays framework free.
 
-| 経路                       | credential                     | 発行                              | 検証                            |
-| -------------------------- | ------------------------------ | --------------------------------- | ------------------------------- |
-| Browser → Worker           | session cookie (Auth.js jwt)   | /api/auth (Google OAuth)          | userSub()                       |
-| Claude → Worker (/api/mcp) | grant jwt ({ sub, path }, 12h) | llm middleware が認可後に mint    | readGrant()                     |
-| Worker → Durable Object    | DO 名 + x-user-sub header      | worker が認可済みの値で必ず上書き | DO へは worker binding 経由のみ |
+The whole library is one loop: the browser and the agent join the same room, and every operation — clicked or tool-called — lands on the same doc and syncs back to both.
 
-認可は own resolver という 1 つの関数に集約される。
+![diagram](https://r.tsei.jp/ai-ax/diagram.svg)
 
-```ts
-type Own = (env: any, sub: string, path: string) => Promise<string> | string
-```
+### One action
 
-「誰 (sub) が、何 (path) に対して、どの部屋 (room) を得るか」を返す。空文字は拒否。
-所有の定義は service ごとに異なるため、resolver の実装は自由に差し替えられる。
+`x(params, config)` builds the `ai` object. The first argument declares typed state keys with their initial values (write `x<Keys>()` when a key should start undefined), and the second argument is the service config.
 
+<!-- prettier-ignore -->
 ```ts
-ownSite((env) => env.my_r2_xxx)
-// R2 head(`${sub}/${path}`) の customMetadata.site が room。file を所有していれば editor の部屋が開く
-
-ownSelf()
-// room = sub。認証した本人の部屋だけが開く。start page や個人 app 向け
-
-const ownGroup: Own = async (env, sub, path) => {
-        const [row] = await drizzle(env.my_d1).select().from(members).where(...)
-        return row ? row.roomId : ''
-}
-// D1 の所属 table を引く resolver も同じ型で書ける
+// actions.ts
+import { x } from 'ai-ax'
+import { z } from 'zod'
+
+export default x(
+        { count: 0 },
+        { name: 'counter', tree: 'count is the current value. Observe before acting', own: ({ sub }) => sub },
+)
+        .describe('A counting app.', (a) =>
+                a
+                        .action('increment', 'Add 1 to the current value', () => ++ai.count)
+                        .action('overwrite', 'Overwrite the current value', { count: z.number() }, ({ count }) => (ai.count = count)),
+        )
+        .client('notify', 'Show an alert in the browser', { text: z.string() }, ({ text }) => alert(text))
+        .server('heavy', 'Run heavy work on the server', { src: z.string() }, () => import('./heavy'))
 ```
 
-## 3. 認可の流れ
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant Browser
-    participant Worker
-    participant Resolver as own resolver
-    participant ClaudeAPI
-    participant MCP as Worker /api/mcp
-    participant DO as Durable Object
-
-    Browser->>Worker: POST /api/llm { path, prompt } (session cookie)
-    Worker->>Resolver: own(env, sub, path)
-    alt room = '' (所有なし)
-        Worker-->>Browser: 401 / 403
-    else room あり
-        Worker->>ClaudeAPI: messages + mcp_servers<br>(authorization_token = grant jwt { sub, path })
-        ClaudeAPI->>MCP: MCP request (Authorization: Bearer grant)
-        MCP->>MCP: readGrant (復号失敗 / 期限切れ → 401)
-        MCP->>Resolver: own(env, sub, path)
-        alt room = ''
-            MCP-->>ClaudeAPI: 403
-        else room あり
-            MCP->>DO: getServerByName(binding, room) へ action 転送
-            DO-->>Browser: 実行結果を websocket で realtime 同期
-            DO-->>MCP: action の戻り値
-            MCP-->>ClaudeAPI: MCP response
-            ClaudeAPI-->>Worker: stream 応答
-            Worker-->>Browser: text stream 中継
-        end
-    end
-```
+Each definition takes the tool name first, and after that the description, the zod schema and the implementation in any order — each part is recognized by its type, so an inline handler reads hono-like as `(name, schema, fn)` while a dynamic import reads `(name, () => import('./x'), description, schema)` with the schema at the end where the whole list scans best. The implementation is either an inline function or a dynamic import whose default export receives `(input, ai)`, so heavy or browser-incompatible code stays out of the other side's bundle. `.action` runs on whichever side called it, `.client` only in the browser, `.server` only in the Durable Object; when the other side calls it, the request travels over the shared doc and the result travels back, so a tool call from the LLM can open a dialog in the connected browser and return what the user did. `.describe(text, fn)` blocks nest, and their texts concatenate hierarchically into the MCP tool description. `get_tree` is built in — every service exposes the same observation tool, and `config.tree` replaces its description.
+
+The declared names and schemas flow into the type of `ai`: `ai.overwrite({ count: 3 })` typechecks, `ai.overwrite(true)` and `ai.missing()` do not.
 
-grant jwt は llm middleware が turn ごとに mint し、Claude API がそのまま /api/mcp へ運ぶ。
-LLM は token の中身を選べず、書き換えれば署名が壊れる。
-つまり LLM が操作できる部屋は「その瞬間に認可された 1 部屋」だけに封じられる。
+### One tree
 
-## 4. room の決定規則
+All shared state lives in a single yjs map. State declared in the first argument is read and written through plain properties — `ai.count = 3` above syncs to every connected browser and to the agent's next `get_tree` — and `ai.data()` exposes the underlying `Y.Map` for apps that key their state by screen paths. `ai.rows(prefix)`, `ai.scan(prefix)` and `ai.wipe(prefix)` query and clear repeated entries, `ai.tx(fn, origin?)` groups writes into one transaction, and `ai.history(options?)` is the undo manager over the same map.
 
-room 名は client にも LLM にも決めさせない。必ず own resolver の結果を使う。
+The tree is also the persistence unit. `config.load` restores a snapshot when the doc first wakes, `config.save` persists one on the update debounce, on a durable alarm and on every disconnect — which is what survives Durable Object hibernation — and `snapshot(doc, keys?)` encodes the whole doc or only the named maps. A `lobby` room skips persistence entirely, so an anonymous top page stays playable without touching storage. State that should stay out of the shared tree and out of snapshots deliberately steps off the road: the `ai-ax/react` entry ships a small atom store (`atom`, `setAtom`, `useAtomValue`) for browser-local values like an IME buffer or an open popup.
 
-- browser は 'my-room' という alias で接続してよい。party middleware が own の結果へ書き換えて DO へ渡す
-- room 名を URL に持つ設計 (editor 型) では、URL の room と own の結果の一致を検査し、不一致は 403
-- websocket・MCP どちらの経路でも x-user-sub / x-user-path header は worker が認可済みの値で上書きするため、外部から偽装できない
-- lobby は唯一の例外。匿名で触れる demo 部屋を 1 つだけ開けられる。設定しなければ全経路で認証必須
+```ts
+x(
+        {},
+        {
+                name: 'notes',
+                lobby: 'notes',
+                own: async ({ env, sub, path }) => (await env.my_bucket.head(`${sub}/${path}`))?.customMetadata?.site ?? '',
+                load: async ({ env, sub, path }) => (await env.my_bucket.get(`${sub}/${path}`))?.arrayBuffer(),
+                save: ({ env, sub, path, room }, buf) => env.my_bucket.put(`${sub}/${path}`, buf, { customMetadata: { site: room } }),
+        },
+)
+```
 
-## 5. action
+### One road
 
-action は「UI handler が呼ぶ関数」と「MCP tool」の両方になる操作の最小単位。
+The app touches the library through the one `ai` object, and each runtime has exactly one adapter that receives it.
 
+<!-- prettier-ignore -->
 ```ts
-export const placeMark = action<{ cell: number }, string>(() => import('./actions/place-mark'), 'both', {
-        name: 'place_mark',
-        description: '空いているマスに現在の手番の印を置く',
-        input: { cell: z.number().describe('マス番号 0-8') },
-})
+// index.ts (worker + Durable Object)
+import { Hono } from 'hono'
+import { hono } from 'ai-ax/hono'
+import { PROMPT } from './prompt'
+import ai from './actions'
+
+export default new Hono().use('*', hono(ai, { system: PROMPT }))
+export { Server as PartyServer } from 'ai-ax/server'
+```
+
+```tsx
+// client.tsx (browser)
+import { useClient } from 'ai-ax/react'
+import ai from './actions'
+
+const App = () => {
+        const { count } = useClient(ai)
+        return <button onClick={() => ai.increment()}>{count}</button>
+}
 ```
 
-- 宣言から MCP tool (name / description / zod inputSchema) が自動生成される
-- 第 1 引数は `() => import('./actions/xxx')` の dynamic import でも、実装関数そのものでもよい (bundle を分けたい service は前者、1 file で書きたい app は後者)
-- side は 3 値。both = yjs を書くだけ (どちら側でも実行可)、client = browser API が要る (server から呼ばれると yjs 上の act-req / act-res で接続中 browser へ委譲)、server = DO 専用
-- 人間の click も LLM の tool 呼び出しも同じ action 関数に到達するため、実装した全機能を LLM が操作・観測できる
-
-## 6. LLM 中継
-
-/api/llm は「認可 → grant mint → Claude API 呼び出し → text stream 中継」を行う。
-
-- mcp_servers に自 host の /api/mcp と grant jwt を設定して Claude API を呼ぶ
-- stop_reason が pause_turn の間は messages を積み直して継続する (MCP tool 呼び出しを跨ぐ)
-- tool 呼び出しは `[tool] name`、終端に `[usage] input/output tokens` を stream へ流す
-
-## 7. API
-
-### createAiax(config)
-
-| key       | 型                  | 既定値                                  | 説明                                                           |
-| --------- | ------------------- | --------------------------------------- | -------------------------------------------------------------- |
-| name      | string              | 必須                                    | service id。MCP server 名になる                                |
-| own       | Own                 | 必須                                    | 認可 resolver。(env, sub, path) → room。'' で拒否              |
-| database  | (env) => D1Database | なし                                    | Auth.js の DrizzleAdapter に渡す D1。省略時は adapter なし jwt |
-| lobby     | string              | なし                                    | 匿名で開放する demo room。省略時は全経路で認証必須             |
-| alias     | string              | 'my-room'                               | 「自分の部屋」を指す接続 room 名。own の結果へ書き換えられる   |
-| system    | string              | ''                                      | LLM の system prompt                                           |
-| model     | string              | 'claude-sonnet-5'                       | Claude API の model id                                         |
-| claude    | string              | 'https://api.anthropic.com/v1/messages' | Claude API の URL (AI Gateway 経由に差し替え可)                |
-| maxTokens | number              | 32000                                   | 1 応答の max_tokens                                            |
-| maxTurns  | number              | 10                                      | pause_turn 継続の上限回数                                      |
-| binding   | string              | 'v1'                                    | Durable Object binding 名                                      |
-| endpoint  | string              | '/api/mcp'                              | MCP endpoint の path                                           |
-| version   | string              | '1.0.0'                                 | MCP server の version 表記                                     |
-| salt      | string              | 'authjs.mcp-token'                      | grant jwt の salt (service ごとの分離)                         |
-| maxAge    | number              | 43200 (12h)                             | grant jwt の有効秒数                                           |
-| cookie    | { apex, services }  | なし                                    | subdomain 間で session cookie を共有する service 群            |
-| providers | any[]               | Google                                  | Auth.js providers の差し替え                                   |
-
-戻り値は `{ auth, party, mcp, llm }` の 4 middleware factory。
-x-user-sub / x-user-path の header 名と anthropic-version は library 内部の protocol 定数であり、config では変えられない (両端が同時に変わる必要があるため)。
-
-### 個別 export
-
-| export                                                     | file      | 説明                                                               |
-| ---------------------------------------------------------- | --------- | ------------------------------------------------------------------ |
-| action / actions / init / serve / grantOf / side           | act.ts    | action system。宣言と登録簿、act-req/act-res の配線、DO 側の受け口 |
-| auth / userSub / signGrant / readGrant / ownSite / ownSelf | auth.ts   | 認証と認可の素材。Auth.js 設定、grant jwt、own preset              |
-| party                                                      | party.ts  | websocket 経路の認可と room 書き換え・DO 転送                      |
-| mcp                                                        | mcp.ts    | grant 検証・認可・action の MCP tool 化・DO への action 転送       |
-| llm                                                        | llm.ts    | Claude API 中継 stream (認可 → mint → converse)                    |
-| callClaude / relay / converse                              | claude.ts | Claude API 呼び出しと stream の逐次処理・turn 継続                 |
-
-## 8. 適用パターン
-
-[Hono and React realtime app](https://zenn.dev/jp/articles) の template がそのまま前提環境になる。
-記事の authMiddleware / myMiddleware を ax.auth() / ax.party() に差し替え、/api/mcp と /api/llm の 2 行を足すと、realtime app が AI/AX 対応になる。
-
-| 型          | own             | lobby | room              | 例                   |
-| ----------- | --------------- | ----- | ----------------- | -------------------- |
-| 個人 app 型 | ownSelf()       | なし  | sub (本人の部屋)  | projects/demo        |
-| editor 型   | ownSite(bucket) | 任意  | file の site id   | editor services      |
-| group 型    | 自作 (D1 join)  | 任意  | 所属 group の部屋 | 将来の collaboration |
-
-## 9. これから — 初期化動線の吸収
-
-Y.Doc の初期化は「browser で作る (公開閲覧の hydrate)」「DO で作る (draft の復元・demo の投入)」「空から作る (seed)」の 3 経路が排他で並び、ここが service 実装の最も複雑な場所になっている。
-aiax は現時点で境界の契約 (認証認可・room 決定・action 転送) だけを持ち、初期化は service 側に残している。
-次の段階で、実行場所 (client / worker / DO) と経路 (view / edit / lobby) の場合分けを宣言で表現する boot / persist API をこの library へ吸収する。
-
-## 10. 攻撃面と防御
-
-| 攻撃                                           | 防御                                                                     |
-| ---------------------------------------------- | ------------------------------------------------------------------------ |
-| MCP client が room 名を引数で自由指定する      | tool 引数に room を持たせない。room は grant の sub/path から own が決定 |
-| 他人の path で grant を得る                    | mint 前に own で所有を検査。mcp 側でも同じ own で再検査する二重化        |
-| 期限切れ / 改竄された grant                    | AUTH_SECRET + salt 付き jwt。復号できなければ sub が空になり 401         |
-| x-user-sub header の偽装                       | worker が認可済みの値で必ず上書きしてから DO へ渡す                      |
-| DO への直接アクセス                            | DO は worker binding 経由でのみ到達可能。公開 URL を持たない             |
-| 破壊的 action (公開データの書き換え)           | action 実行の直前に own で再認可する実装を service 側で足せる            |
-| 認可の掏り替え (client が接続後に path を変更) | grant は { sub, path } 固定。別 path は別 grant の再発行が要る           |
-
-## License
-
-MIT
+`hono(ai, extra?)` routes `/parties/*` to websocket sync, the MCP endpoint, the LLM relay and the Auth.js session, and lets everything else fall through to the app's own routes; `extra` merges server-only config such as the system prompt or an Auth.js `adapter`, so they never enter the browser bundle. `Server` is the Durable Object: it records the owning user across hibernation, serializes action execution, and drives the `load` / `save` hooks. `useClient(ai)` connects once and re-renders on every tree change (`Client` is the component form, `client(ai)` the non-React form), and `hydrate(ai, entries)` fills a local doc from a published JSON snapshot without waking a Durable Object at all.
+
+Runtime-only values — Cloudflare bindings, the authorized user, the room — travel the same road instead of module globals: the server injects them with `ai.use({ ... })`, and every implementation receives `ai` as its second argument. `.abstract(name)` declares a function that actions may call before anyone has implemented it, and `.override(name, (input, next, ai) => ...)` supplies or wraps implementations onion-style, where `next(input)` runs whatever was underneath. Overrides intercept tools too, which is how a browser rewrites the variables the Claude API sends before an action runs.
+
+`createStream()` from `ai-ax/client` is the browser side of the relay's wire format: `POST` to the relay streams plain text in which a `[tool]` line marks each MCP call and a trailing `[usage]` line closes the turn, and `parse` / `send` / prior-`messages` replay are the pieces an app needs to render and continue conversations without touching the format itself.
+
+### One resolver
+
+Authorization concentrates into the single `own` function: given `{ env, sub, path }` it answers which room this user may enter, and an empty string denies. Only two kinds of credentials exist, both jwt signed with `AUTH_SECRET` — a plain user id never crosses the network.
+
+| path                    | credential                   | issued by                                    | verified by                                 |
+| ----------------------- | ---------------------------- | -------------------------------------------- | ------------------------------------------- |
+| Browser → Worker        | session cookie (Auth.js jwt) | `/api/auth` (Google OAuth by default)        | the Auth.js session                         |
+| Claude → Worker MCP     | grant jwt `{ sub, path }`    | the LLM relay, minted per prompt             | signature check before every tool execution |
+| Worker → Durable Object | room name + user headers     | the worker overwrites with authorized values | the DO is reachable only through the worker |
+
+Browsers always connect to the alias room `my-room`, and the worker rewrites it to the room `own` returned, so no client ever picks a real room name. The grant jwt is minted when the user sends a prompt and is carried by the Claude API back on every MCP request; the LLM cannot choose the token's contents, and rewriting it breaks the signature, so at any moment the agent is sealed inside the one room that was just authorized, for at most `maxAge` seconds.
+
+## How
+
+| entry          | main exports                                             | where it runs           |
+| -------------- | -------------------------------------------------------- | ----------------------- |
+| `ai-ax`        | `x`                                                      | everywhere (isomorphic) |
+| `ai-ax/hono`   | `hono`                                                   | worker                  |
+| `ai-ax/server` | `Server`, `snapshot`                                     | Durable Object          |
+| `ai-ax/client` | `client`, `hydrate`, `createStream`, `ALIAS`             | browser                 |
+| `ai-ax/react`  | `useClient`, `Client`, `atom`, `setAtom`, `useAtomValue` | browser (React)         |
+| `ai-ax/const`  | protocol constants (paths, header names)                 | both                    |
+
+The worker expects a Durable Object binding named `v1` pointing at the exported `Server` class, and the environment needs `AUTH_SECRET`, the OAuth client credentials and `ANTHROPIC_API_KEY`. Config keys of `x(params, config)` and `hono(ai, extra)`:
+
+| key       | type                       | default                                   | meaning                                               |
+| --------- | -------------------------- | ----------------------------------------- | ----------------------------------------------------- |
+| name      | `string`                   | `'x'`                                     | service id, becomes the MCP server name               |
+| tree      | `string`                   | generic text                              | description of the built-in `get_tree` tool           |
+| own       | `(at: Peer) => string`     | deny all                                  | authorization resolver, `''` denies                   |
+| adapter   | `(env) => Adapter`         | none                                      | Auth.js adapter factory, jwt-only when omitted        |
+| lobby     | `string`                   | none                                      | one anonymous room without persistence                |
+| load      | `(at: Saved) => buf`       | none                                      | snapshot restore on first doc load                    |
+| save      | `(at: Saved, buf) => void` | none                                      | snapshot persist on debounce / alarm / disconnect     |
+| keys      | `string[]`                 | whole doc                                 | map names included in the snapshot                    |
+| alias     | `string`                   | `'my-room'`                               | connection name meaning "my room", rewritten by `own` |
+| system    | `string`                   | `''`                                      | system prompt for the LLM                             |
+| model     | `string`                   | `'claude-sonnet-5'`                       | Claude API model id                                   |
+| claude    | `string`                   | `'https://api.anthropic.com/v1/messages'` | Claude API URL, replaceable with an AI Gateway        |
+| maxTokens | `number`                   | `32000`                                   | max_tokens per response                               |
+| maxTurns  | `number`                   | `10`                                      | upper bound of pause_turn continuations               |
+| binding   | `string`                   | `'v1'`                                    | Durable Object binding name                           |
+| host      | `string`                   | request host                              | public host the Claude API reaches the MCP through    |
+| endpoint  | `string`                   | `'/api/mcp'`                              | MCP endpoint path                                     |
+| relay     | `string`                   | `'/api/llm'`                              | LLM relay path                                        |
+| version   | `string`                   | `'1.0.0'`                                 | MCP server version string                             |
+| salt      | `string`                   | `'authjs.mcp-token'`                      | grant jwt salt, separates services                    |
+| maxAge    | `number`                   | `43200` (12h)                             | grant jwt lifetime in seconds                         |
+| cookie    | `{ apex, services }`       | none                                      | services sharing a session cookie across subdomains   |
+| providers | `any[]`                    | Google                                    | Auth.js providers                                     |
+
+The `x-user-sub` / `x-user-path` header names and the anthropic-version are internal protocol constants and intentionally not configurable, because both ends of each protocol must change together.

package/dist/client.d.ts

@@ -1,49 +1,2 @@
-import { ActMeta, ActionDef, Side } from "./types.js";
-import { Call, action, actions, bind, data, init, side } from "./action.js";
-import { ALIAS, BINDING } from "./const.js";
-import * as Y from "yjs";
-//#region src/browser/stream.d.ts
-interface StreamTool {
-  server: string;
-  name: string;
-}
-interface StreamItem {
-  text: string;
-  tools: StreamTool[];
-  error?: boolean;
-}
-interface StreamSend {
-  prompt: string;
-  path?: string;
-  model?: string;
-  messages?: any[];
-  headers?: Record<string, string>;
-}
-interface StreamUpdate {
-  items: StreamItem[];
-  delta: string;
-  raw: string;
-}
-declare const createStream: (endpoint?: string) => {
-  parse: (raw: string) => StreamItem[];
-  send: (input: StreamSend, update?: (u: StreamUpdate) => void) => Promise<StreamItem[]>;
-};
-//#endregion
-//#region src/client.d.ts
-interface Route {
-  room?: string;
-  path?: string;
-  host?: string;
-  party?: string;
-  doc?: Y.Doc;
-}
-interface Link {
-  doc: Y.Doc;
-  call: Call;
-  synced: (fn: () => void) => void;
-  leave: () => void;
-}
-declare const onLeave: (fn: () => void) => undefined;
-declare const connect: (route?: Route) => Link;
-//#endregion
-export { ALIAS, type ActMeta, type ActionDef, BINDING, Link, Route, type Side, type StreamItem, type StreamSend, type StreamTool, type StreamUpdate, action, actions, bind, connect, createStream, data, init, onLeave, side };
+import { a as StreamItem, c as StreamUpdate, i as hydrate, l as createStream, n as Route, o as StreamSend, r as client, s as StreamTool, t as Link } from "./client-BN8W_6y5.js";
+export { Link, Route, type StreamItem, type StreamSend, type StreamTool, type StreamUpdate, client, createStream, hydrate };

package/dist/client.js

@@ -1,2 +1,2 @@
-import{ALIAS as e,BINDING as t,LLM_PATH as n}from"./const.js";import{action as r,actions as i,bind as a,data as o,init as s,side as c}from"./action.js";import l from"y-partyserver/provider";import*as u from"yjs";const d=/^\[tool\] (?:(\S+) )?(\S+)$/,f=(e=n)=>{let t=e=>{let t=[{text:``,tools:[]}],n=!1;for(let r of e.split(`
-`)){if(r.startsWith(`[usage]`))continue;let e=d.exec(r),i=t[t.length-1];if(e){i.tools.push({server:e[1]??``,name:e[2]}),n=!0;continue}if(!(n&&r.trim()===``)){if(n){t.push({text:r,tools:[]}),n=!1;continue}i.text=i.text===``?r:`${i.text}\n${r}`}}return t.map(e=>({...e,text:e.text.trim()})).filter(e=>e.text!==``||e.tools.length>0)};return{parse:t,send:async(n,r)=>{let{headers:i={},...a}=n,o=await fetch(e,{method:`POST`,headers:{"content-type":`application/json`,...i},body:JSON.stringify(a)});if(!o.ok){let e=(await o.text()).replace(/\n/g,` `),t=[{text:e,tools:[],error:!0}];return r?.({items:t,delta:e,raw:e}),t}let s=o.body.getReader(),c=new TextDecoder,l=``;for(;;){let{done:e,value:n}=await s.read();if(e)break;let i=c.decode(n,{stream:!0});l+=i,r?.({items:t(l),delta:i,raw:l})}return t(l)}}};let p=null,m=new Set;const h=e=>void m.add(e),g=(e={})=>{p?.leave();let{room:t=``,path:n=``,host:r=location.host,party:i=`v1`,doc:a}=e,o=t?new l(r,t,a,{party:i,params:{path:n}}):null,c=o?.doc??a??new u.Doc;return p={doc:c,call:s(c),synced(e){if(!o||o.synced)return void e();o.once(`synced`,()=>e())},leave(){m.forEach(e=>e()),m=new Set,o?.destroy()}}};export{e as ALIAS,t as BINDING,r as action,i as actions,a as bind,g as connect,f as createStream,o as data,s as init,h as onLeave,c as side};
+import{init as e}from"./index.js";import{ALIAS as t,LLM_PATH as n}from"./const.js";import*as r from"yjs";import i from"y-partyserver/provider";const a=/^\[tool\] (?:(\S+) )?(\S+)$/,o=(e=n)=>{let t=e=>{let t=[{text:``,tools:[]}],n=!1;for(let r of e.split(`
+`)){if(r.startsWith(`[usage]`))continue;let e=a.exec(r),i=t[t.length-1];if(e){i.tools.push({server:e[1]??``,name:e[2]}),n=!0;continue}if(!(n&&r.trim()===``)){if(n){t.push({text:r,tools:[]}),n=!1;continue}i.text=i.text===``?r:`${i.text}\n${r}`}}return t.map(e=>({...e,text:e.text.trim()})).filter(e=>e.text!==``||e.tools.length>0)};return{parse:t,send:async(n,r)=>{let{headers:i={},...a}=n,o=await fetch(e,{method:`POST`,headers:{"content-type":`application/json`,...i},body:JSON.stringify(a)});if(!o.ok){let e=(await o.text()).replace(/\n/g,` `),t=[{text:e,tools:[],error:!0}];return r?.({items:t,delta:e,raw:e}),t}let s=o.body.getReader(),c=new TextDecoder,l=``;for(;;){let{done:e,value:n}=await s.read();if(e)break;let i=c.decode(n,{stream:!0});l+=i,r?.({items:t(l),delta:i,raw:l})}return t(l)}}};let s=null,c=new Set;const l=(t={})=>{s?.leave();let{room:n=``,path:a=``,host:o=location.host,party:l=`v1`,doc:u}=t,d=n?new i(o,n,u,{party:l,params:{path:a}}):null,f=d?.doc??u??new r.Doc;return s={doc:f,call:e(f),synced(e){if(!d||d.synced)return void e();d.once(`synced`,()=>e())},leave(){c.forEach(e=>e()),c=new Set,d?.destroy()}}},u=new WeakSet,d=(e,n={})=>{if(u.has(e))return e;u.add(e);let r=l({room:t,...n});return e.use({link:r}),e},f=(e,t,n=(e,t)=>t)=>{if(u.has(e))return e;u.add(e);let r=l({});return r.doc.transact(()=>Object.entries(t).forEach(([e,t])=>r.doc.getMap(`tree`).set(e,n(e,t)))),e.use({link:r}),e};export{d as client,o as createStream,f as hydrate};

package/dist/hono.d.ts

@@ -0,0 +1,5 @@
+import { n as Ai, r as Config } from "./types-CQLXtCsz.js";
+//#region src/hono.d.ts
+declare const hono: (ai: Ai<any>, extra?: Partial<Config>) => import("hono").MiddlewareHandler<any, string, {}, Response>;
+//#endregion
+export { hono };

package/dist/hono.js

@@ -0,0 +1,2 @@
+import{actions as e}from"./index.js";import{PATH_HEADER as t,SUB_HEADER as n}from"./const.js";import{createMiddleware as r}from"hono/factory";import i from"@auth/core/providers/google";import{decode as a,encode as o}from"@auth/core/jwt";import{getAuthUser as s,initAuthConfig as c}from"@hono/auth-js";import{env as l}from"hono/adapter";import{streamText as u}from"hono/streaming";import{StreamableHTTPTransport as d}from"@hono/mcp";import{McpServer as f}from"@modelcontextprotocol/sdk/server/mcp.js";import{getServerByName as p,routePartykitRequest as m}from"partyserver";const h=`authjs.mcp-token`,g=e=>c(t=>{let n=new URL(t.req.url).host,r=!!e.cookie&&e.cookie.services.some(t=>n===`${t}.${e.cookie.apex}`),a={sessionToken:{options:{domain:`.${e.cookie?.apex}`}}},o=e.providers??[i({clientId:t.env.GOOGLE_CLIENT_ID,clientSecret:t.env.GOOGLE_CLIENT_SECRET})];return{...e.adapter?{adapter:e.adapter(t.env)}:{},providers:o,secret:t.env.AUTH_SECRET,session:{strategy:`jwt`},...r?{cookies:a}:{}}}),_=async e=>(await s(e))?.token?.sub??``,v=(e,t,n,r)=>o({token:{sub:t,path:n},secret:l(e).AUTH_SECRET,salt:r?.salt??h,maxAge:r?.maxAge??43200}),y=async(e,t)=>{let n=(e.req.header(`Authorization`)??``).replace(/^Bearer\s+/i,``);if(!n)return null;let r=await a({token:n,secret:l(e).AUTH_SECRET,salt:t?.salt??h}).catch(()=>null);return{sub:r?.sub??``,path:r?.path??``}},b=e=>e.startsWith(`data:`)?JSON.parse(e.slice(5)):null,x=(e,t,n)=>fetch(e.api,{method:`POST`,headers:{"x-api-key":e.key,"anthropic-version":`2023-06-01`,"anthropic-beta":`mcp-client-2025-11-20`,"content-type":`application/json`},body:JSON.stringify({model:e.model,max_tokens:e.maxTokens,stream:!0,cache_control:{type:`ephemeral`},system:e.system,mcp_servers:[{type:`url`,url:e.url,name:e.name,...t?{authorization_token:t}:{}}],tools:[{type:`mcp_toolset`,mcp_server_name:e.name}],messages:n})}),S=async(e,t)=>{let n=[],r=null,i=0,a=0,o=0,s=``,c=e.body.getReader(),l=new TextDecoder,u=``;for(;;){let{done:e,value:d}=await c.read();if(e)break;u+=l.decode(d,{stream:!0});let f=u.split(`
+`);u=f.pop()??``;for(let e of f){let c=b(e);if(c){if(c.type===`message_start`){let e=c.message?.usage??{};i+=(e.input_tokens??0)+(e.cache_creation_input_tokens??0)+(e.cache_read_input_tokens??0),a+=e.cache_read_input_tokens??0}c.type===`message_delta`&&(o=c.usage?.output_tokens??o,s=c.delta?.stop_reason??s),c.type===`content_block_start`&&(r={...c.content_block},n.push(r),r.type===`mcp_tool_use`&&await t(`\n[tool] ${r.server_name} ${r.name}\n`)),c.type===`content_block_delta`&&c.delta?.type===`text_delta`&&(r.text=(r.text??``)+c.delta.text,await t(c.delta.text)),c.type===`content_block_delta`&&c.delta?.type===`input_json_delta`&&(r.partial=(r.partial??``)+c.delta.partial_json),c.type===`content_block_delta`&&c.delta?.type===`thinking_delta`&&(r.thinking=(r.thinking??``)+c.delta.thinking),c.type===`content_block_delta`&&c.delta?.type===`signature_delta`&&(r.signature=(r.signature??``)+c.delta.signature),c.type===`content_block_stop`&&r?.partial!==void 0&&(r.input=r.partial?JSON.parse(r.partial):{},delete r.partial)}}}return{blocks:n,input:i,cached:a,output:o,stop:s}},C=async(e,t,n,r,i,a=10)=>{let o=r,s=0,c=0,l=0,u=``;for(let r=0;r<a;r++){let r=await S(o,i);if(s+=r.input,c+=r.cached,l+=r.output,u=r.stop||u,u!==`pause_turn`)break;if(n.push({role:`assistant`,content:r.blocks.filter(e=>e.type!==`thinking`||e.thinking||e.signature)}),o=await x(e,await t(),n),!o.ok){await i(`\n[error] ${(await o.text()).replace(/\n/g,` `)}\n`);break}}await i(`\n[usage] input ${s} (cache ${c}) / output ${l} tokens (${u})\n`)},w=e=>r(async t=>{let n=await _(t),{path:r=``,prompt:i,model:a=``,messages:o=[]}=await t.req.json(),s=!!e.lobby&&!r;if(!s&&!n)return t.text(`Unauthorized`,401);if(!s&&!await(e.own??(()=>``))({env:l(t),sub:n,path:r}))return t.text(`Forbidden`,403);let c=e.host??t.req.header(`x-original-host`)??t.req.header(`x-forwarded-host`)??new URL(t.req.url).host,d={key:l(t).ANTHROPIC_API_KEY,api:e.claude??`https://api.anthropic.com/v1/messages`,name:e.name??`aiax`,url:`https://${c}${e.endpoint??`/api/mcp`}`,model:a||e.model||`claude-sonnet-5`,system:e.system??``,maxTokens:e.maxTokens??32e3},f=()=>s?Promise.resolve(``):v(t,n,r,e),p=[...o,{role:`user`,content:i}],m=await x(d,await f(),p);return m.ok?u(t,t=>C(d,f,p,m,e=>t.write(e),e.maxTurns??10)):t.text(await m.text(),500)}),T=async(e,r,i,a,o)=>{let s=await p(e,r),c={[n]:i.sub,[t]:encodeURIComponent(i.path)};return(await s.fetch(`https://internal/act`,{method:`POST`,headers:c,body:JSON.stringify({name:a,input:o})})).json()},E=t=>r(async n=>{let r=await y(n,t),i=r?.sub??``,a=r?.path??``,o=t.lobby??``;if(r||!o){if(!i)return n.text(`Unauthorized`,401);if(o=await(t.own??(()=>``))({env:l(n),sub:i,path:a}),!o)return n.text(`Forbidden`,403)}let s=new f({name:t.name??`aiax`,version:t.version??`1.0.0`}),c=new d;return e.forEach((e,r)=>s.registerTool(r,{description:e.description,inputSchema:{...e.input}},async e=>{let s=await T(l(n)[t.binding??`v1`],o,{sub:i,path:a},r,e);return{content:[{type:`text`,text:JSON.stringify(s)}]}})),await s.connect(c),c.handleRequest(n)}),D=async(e,r,i,a)=>{let o=new Headers(e.req.raw.headers);o.set(n,i),o.set(t,encodeURIComponent(a));let s=new URL(e.req.url),c=s.pathname.split(`/`);c[3]=encodeURIComponent(r),s.pathname=c.join(`/`);let u=new Request(s,new Request(e.req.raw,{headers:o}));return await m(u,l(e))??e.text(`Not Found`,404)},O=e=>r(async t=>{let n=decodeURIComponent(t.req.path.split(`/`)[3]??``),r=t.req.query(`path`)??``,i=await _(t);if(e.lobby&&n===e.lobby)return D(t,n,i,r);if(!i)return t.text(`Unauthorized`,401);let a=await(e.own??(()=>``))({env:l(t),sub:i,path:r});return!a||n!==a&&n!==(e.alias??`my-room`)?t.text(`Forbidden`,403):D(t,a,i,r)}),k=(e,t={})=>{let n=Object.assign(e.config,t),i={auth:g(n),party:O(n),mcp:E(n),llm:w(n)};return r(async(e,t)=>{let r=()=>e.req.path.startsWith(`/parties/`)?i.party(e,t):e.req.path===(n.endpoint??`/api/mcp`)?i.mcp(e,t):e.req.path===(n.relay??`/api/llm`)&&e.req.method===`POST`?i.llm(e,t):t(),a;if(await i.auth(e,async()=>void(a=await r())),a)return a})};export{k as hono};

package/dist/index.d.ts

@@ -1,16 +1,3 @@
-import { Config, Own } from "./types.js";
-//#region src/worker/auth.d.ts
-declare const ownSite: (bucket: (env: any) => any, meta?: string) => Own;
-declare const ownSelf: () => Own;
-//#endregion
-//#region src/index.d.ts
-declare const createAiax: (config: Config) => {
-  config: Config;
-  all: () => import("hono").MiddlewareHandler<any, string, {}, Response>;
-  auth: () => import("hono").MiddlewareHandler;
-  party: () => import("hono").MiddlewareHandler<any, string, {}, any>;
-  mcp: () => import("hono").MiddlewareHandler<any, string, {}, Response>;
-  llm: () => import("hono").MiddlewareHandler<any, string, {}, Response>;
-};
-//#endregion
-export { createAiax, ownSelf, ownSite };
+import { a as Define, c as Peer, i as Cookie, l as Saved, n as Ai, o as Grant, r as Config, s as Own, t as ActionDef, u as Side } from "./types-CQLXtCsz.js";
+import { a as current, c as isBound, i as call, l as side, n as actions, o as data, r as bind, s as init, t as Call, u as x } from "./index-DNUoYl4_.js";
+export { type ActionDef, type Ai, Call, type Config, type Cookie, type Define, type Grant, type Own, type Peer, type Saved, type Side, actions, bind, call, current, data, init, isBound, side, x };

package/dist/index.js

@@ -1,2 +1 @@
-import{PATH_HEADER as e,SUB_HEADER as t}from"./const.js";import{actions as n}from"./action.js";import{createMiddleware as r}from"hono/factory";import i from"@auth/core/providers/google";import{decode as a,encode as o}from"@auth/core/jwt";import{DrizzleAdapter as s}from"@auth/drizzle-adapter";import{getAuthUser as c,initAuthConfig as l}from"@hono/auth-js";import{drizzle as u}from"drizzle-orm/d1";import{env as d}from"hono/adapter";import{streamText as f}from"hono/streaming";import{StreamableHTTPTransport as p}from"@hono/mcp";import{McpServer as m}from"@modelcontextprotocol/sdk/server/mcp.js";import{getServerByName as h,routePartykitRequest as g}from"partyserver";const _=`authjs.mcp-token`,v=e=>l(t=>{let n=new URL(t.req.url).host,r=!!e.cookie&&e.cookie.services.some(t=>n===`${t}.${e.cookie.apex}`),a={sessionToken:{options:{domain:`.${e.cookie?.apex}`}}},o=e.providers??[i({clientId:t.env.GOOGLE_CLIENT_ID,clientSecret:t.env.GOOGLE_CLIENT_SECRET})];return{...e.database?{adapter:s(u(e.database(t.env)))}:{},providers:o,secret:t.env.AUTH_SECRET,session:{strategy:`jwt`},...r?{cookies:a}:{}}}),y=async e=>(await c(e))?.token?.sub??``,b=(e,t,n,r)=>o({token:{sub:t,path:n},secret:d(e).AUTH_SECRET,salt:r?.salt??_,maxAge:r?.maxAge??43200}),x=async(e,t)=>{let n=(e.req.header(`Authorization`)??``).replace(/^Bearer\s+/i,``);if(!n)return null;let r=await a({token:n,secret:d(e).AUTH_SECRET,salt:t?.salt??_}).catch(()=>null);return{sub:r?.sub??``,path:r?.path??``}},S=(e,t=`site`)=>async(n,r,i)=>!r||!i?``:(await e(n).head(`${r}/${i}`))?.customMetadata?.[t]??``,C=()=>(e,t)=>t,w=e=>e.startsWith(`data:`)?JSON.parse(e.slice(5)):null,T=(e,t,n)=>fetch(e.api,{method:`POST`,headers:{"x-api-key":e.key,"anthropic-version":`2023-06-01`,"anthropic-beta":`mcp-client-2025-11-20`,"content-type":`application/json`},body:JSON.stringify({model:e.model,max_tokens:e.maxTokens,stream:!0,cache_control:{type:`ephemeral`},system:e.system,mcp_servers:[{type:`url`,url:e.url,name:e.name,...t?{authorization_token:t}:{}}],tools:[{type:`mcp_toolset`,mcp_server_name:e.name}],messages:n})}),E=async(e,t)=>{let n=[],r=null,i=0,a=0,o=0,s=``,c=e.body.getReader(),l=new TextDecoder,u=``;for(;;){let{done:e,value:d}=await c.read();if(e)break;u+=l.decode(d,{stream:!0});let f=u.split(`
-`);u=f.pop()??``;for(let e of f){let c=w(e);if(c){if(c.type===`message_start`){let e=c.message?.usage??{};i+=(e.input_tokens??0)+(e.cache_creation_input_tokens??0)+(e.cache_read_input_tokens??0),a+=e.cache_read_input_tokens??0}c.type===`message_delta`&&(o=c.usage?.output_tokens??o,s=c.delta?.stop_reason??s),c.type===`content_block_start`&&(r={...c.content_block},n.push(r),r.type===`mcp_tool_use`&&await t(`\n[tool] ${r.server_name} ${r.name}\n`)),c.type===`content_block_delta`&&c.delta?.type===`text_delta`&&(r.text=(r.text??``)+c.delta.text,await t(c.delta.text)),c.type===`content_block_delta`&&c.delta?.type===`input_json_delta`&&(r.partial=(r.partial??``)+c.delta.partial_json),c.type===`content_block_delta`&&c.delta?.type===`thinking_delta`&&(r.thinking=(r.thinking??``)+c.delta.thinking),c.type===`content_block_delta`&&c.delta?.type===`signature_delta`&&(r.signature=(r.signature??``)+c.delta.signature),c.type===`content_block_stop`&&r?.partial!==void 0&&(r.input=r.partial?JSON.parse(r.partial):{},delete r.partial)}}}return{blocks:n,input:i,cached:a,output:o,stop:s}},D=async(e,t,n,r,i,a=10)=>{let o=r,s=0,c=0,l=0,u=``;for(let r=0;r<a;r++){let r=await E(o,i);if(s+=r.input,c+=r.cached,l+=r.output,u=r.stop||u,u!==`pause_turn`)break;if(n.push({role:`assistant`,content:r.blocks.filter(e=>e.type!==`thinking`||e.thinking||e.signature)}),o=await T(e,await t(),n),!o.ok){await i(`\n[error] ${(await o.text()).replace(/\n/g,` `)}\n`);break}}await i(`\n[usage] input ${s} (cache ${c}) / output ${l} tokens (${u})\n`)},O=e=>r(async t=>{let n=await y(t),{path:r=``,prompt:i,model:a=``,messages:o=[]}=await t.req.json(),s=!!e.lobby&&!r;if(!s&&!n)return t.text(`Unauthorized`,401);if(!s&&!await e.own(d(t),n,r))return t.text(`Forbidden`,403);let c=t.req.header(`x-original-host`)??t.req.header(`x-forwarded-host`)??new URL(t.req.url).host,l={key:d(t).ANTHROPIC_API_KEY,api:e.claude??`https://api.anthropic.com/v1/messages`,name:e.name,url:`https://${c}${e.endpoint??`/api/mcp`}`,model:a||e.model||`claude-sonnet-5`,system:e.system??``,maxTokens:e.maxTokens??32e3},u=()=>s?Promise.resolve(``):b(t,n,r,e),p=[...o,{role:`user`,content:i}],m=await T(l,await u(),p);return m.ok?f(t,t=>D(l,u,p,m,e=>t.write(e),e.maxTurns??10)):t.text(await m.text(),500)}),k=async(n,r,i,a,o)=>{let s=await h(n,r),c={[t]:i.sub,[e]:encodeURIComponent(i.path)};return(await s.fetch(`https://internal/act`,{method:`POST`,headers:c,body:JSON.stringify({name:a,input:o})})).json()},A=e=>r(async t=>{let r=await x(t,e),i=r?.sub??``,a=r?.path??``,o=e.lobby??``;if(r||!o){if(!i)return t.text(`Unauthorized`,401);if(o=await e.own(d(t),i,a),!o)return t.text(`Forbidden`,403)}let s=new m({name:e.name,version:e.version??`1.0.0`}),c=new p;return n.forEach((n,r)=>s.registerTool(r,{description:n.description,inputSchema:{...n.input}},async n=>{let s=await k(d(t)[e.binding??`v1`],o,{sub:i,path:a},r,n);return{content:[{type:`text`,text:JSON.stringify(s)}]}})),await s.connect(c),c.handleRequest(t)}),j=async(n,r,i,a)=>{let o=new Headers(n.req.raw.headers);o.set(t,i),o.set(e,encodeURIComponent(a));let s=new URL(n.req.url),c=s.pathname.split(`/`);c[3]=encodeURIComponent(r),s.pathname=c.join(`/`);let l=new Request(s,new Request(n.req.raw,{headers:o}));return await g(l,d(n))??n.text(`Not Found`,404)},M=e=>r(async t=>{let n=decodeURIComponent(t.req.path.split(`/`)[3]??``),r=t.req.query(`path`)??``,i=await y(t);if(e.lobby&&n===e.lobby)return j(t,n,i,r);if(!i)return t.text(`Unauthorized`,401);let a=await e.own(d(t),i,r);return!a||n!==a&&n!==(e.alias??`my-room`)?t.text(`Forbidden`,403):j(t,a,i,r)}),N=e=>{let t={auth:v(e),party:M(e),mcp:A(e),llm:O(e)},n=r(async(n,r)=>{let i=()=>n.req.path.startsWith(`/parties/`)?t.party(n,r):n.req.path===(e.endpoint??`/api/mcp`)?t.mcp(n,r):n.req.path===`/api/llm`&&n.req.method===`POST`?t.llm(n,r):r(),a;if(await t.auth(n,async()=>void(a=await i())),a)return a});return{config:e,all:()=>n,auth:()=>t.auth,party:()=>t.party,mcp:()=>t.mcp,llm:()=>t.llm}};export{N as createAiax,C as ownSelf,S as ownSite};
+import*as e from"yjs";const t=new Map,n=typeof window>`u`?`server`:`client`;let r,i;const a=e=>i=e,o=()=>!!i,s=(e=`tree`)=>i.getMap(e),c=(e,t)=>r(e,t),l=(e,i=e=>e())=>{a(e);let o=e.getMap(`act-req`),s=e.getMap(`act-res`),c=new Map,l=async r=>{let c=o.get(r),l=t.get(c?.name);!l||l.side!==n||(o.delete(r),s.set(r,{value:await i(()=>(a(e),l.run(c.input)))}))},u=e=>{let t=c.get(e);!t||!s.has(e)||(c.delete(e),t(s.get(e).value),s.delete(e))};return o.observe(e=>e.keysChanged.forEach(l)),s.observe(e=>e.keysChanged.forEach(u)),r=(r,i)=>{let s=t.get(r);return s.side===n||s.side===`both`?(a(e),s.run(i)):new Promise(e=>{let t=crypto.randomUUID();c.set(t,e),o.set(t,{name:r,input:i})})},r},u={ai:null},d=()=>u.ai,f=new WeakMap,p=t=>{let n=s();return f.has(n)||f.set(n,new e.UndoManager(n,t)),f.get(n)},m=e=>!!e&&typeof e.parse==`function`,h=e=>m(e)?{value:e}:e,g=(e,t)=>m(e)&&t&&typeof t==`object`&&`value`in t?t.value:t;function _(e={},r={}){let i={},a=new Map,l=new Set,d=[],f=(e,t)=>n=>{let r=a.get(e);return r?r(n,t,y):t(n)},m=e=>(n,...r)=>{let i=r.find(e=>typeof e==`string`)??``,a=r.find(e=>typeof e==`function`),o=r.find(e=>e&&typeof e==`object`),s=async e=>{let t=g(o,e),n=await a(t,y);return typeof n==`function`?n(t,y):n&&n.default?n.default(t,y):n},c=[...d,i].filter(Boolean).join(` `);return t.set(n,{name:n,description:c,side:e,input:h(o),run:f(n,s)}),y},_=e=>()=>Promise.reject(Error(`not implemented: ${e}`)),v={config:r,context:i,side:n,action:m(`both`),client:m(`client`),server:m(`server`),describe(e,t){return t?(d=[...d,e],t(y),d=d.slice(0,-1),y):y},abstract:e=>(l.add(e),y),override:(e,t)=>(a.set(e,t),y),use:e=>(Object.assign(i,e),y),data:e=>s(e),rows(e){let t=[];return s().forEach((n,r)=>r.startsWith(e)&&!r.slice(e.length).includes(`/`)&&t.push(n)),t.sort((e,t)=>(e?.pos??0)-(t?.pos??0))},scan(e){let t=[];return s().forEach((n,r)=>r.startsWith(e)&&t.push(n)),t},wipe(e){let t=[];s().forEach((n,r)=>r.startsWith(e)&&t.push(r)),t.forEach(e=>s().delete(e))},tx:(e,t)=>s().doc.transact(e,t),history:e=>p(e),call:(e,t)=>c(e,t)};t.set(`get_tree`,{name:`get_tree`,description:r.tree??`共有 tree の全 key/value を dump して画面の現在状態を観測する。操作前の観測用`,side:`both`,run:f(`get_tree`,async()=>{let e={};return s().forEach((t,n)=>e[n]=t),e})});let y=new Proxy(v,{get(n,r){if(typeof r!=`string`||r in n)return n[r];if(t.has(r))return e=>c(r,e);if(l.has(r))return f(r,_(r));if(r in i)return i[r];if(r!==`then`&&r!==`toJSON`)return o()?s().get(r)??e[r]:e[r]},set(t,n,r){return typeof n!=`string`||n in t?(t[n]=r,!0):n in i?(i[n]=r,!0):o()?(s().set(n,r),!0):(e[n]=r,!0)}});return u.ai=y,y}export{t as actions,a as bind,c as call,d as current,s as data,l as init,o as isBound,n as side,_ as x};

package/dist/react.d.ts

@@ -0,0 +1,23 @@
+import { n as Route } from "./client-BN8W_6y5.js";
+import { ReactNode } from "react";
+//#region src/react.d.ts
+declare const atom: <T>(initial: T) => {
+  value: T;
+  listeners: Set<(v: T) => void>;
+};
+type Atom<T> = ReturnType<typeof atom<T>>;
+declare const setAtom: <T>(a: Atom<T>, v: T | ((p: T) => T)) => void;
+declare const useAtomValue: <T>(a: Atom<T>) => T;
+declare const useAtom: <T>(a: Atom<T>) => [T, (v: T) => void];
+declare const AtomValue: <T>({ atom, children }: {
+  atom: Atom<T>;
+  children: (v: T) => ReactNode;
+}) => ReactNode;
+declare const useClient: <T extends object>(ai: T, route?: Route) => T;
+declare const Client: <T extends object>({ ai, route, children }: {
+  ai: T;
+  route?: Route;
+  children: (ai: T) => ReactNode;
+}) => ReactNode;
+//#endregion
+export { Atom, AtomValue, Client, atom, setAtom, useAtom, useAtomValue, useClient };

package/dist/react.js

@@ -0,0 +1 @@
+import{useCallback as e,useEffect as t,useState as n}from"react";const r=e=>({value:e,listeners:new Set}),i=(e,t)=>{typeof t==`function`&&(t=t(e.value)),e.value=t,e.listeners.forEach(e=>e(t))},a=e=>{let[r,i]=n(()=>e.value);return t(()=>{let t=e=>i(e);return e.listeners.add(t),r!==e.value&&i(e.value),()=>void e.listeners.delete(t)},[e]),r},o=t=>[a(t),e(e=>i(t,e),[t])],s=({atom:e,children:t})=>t(a(e)),c=(e,r)=>{let[,i]=n(0),a=e.link;return t(()=>{let t=()=>i(e=>e+1);if(!a)return void import(`./client.js`).then(({client:n})=>(n(e,r),t()));let n=a.doc.getMap(`tree`);return n.observe(t),()=>n.unobserve(t)},[a]),e},l=({ai:e,route:t,children:n})=>n(c(e,t));export{s as AtomValue,l as Client,r as atom,i as setAtom,o as useAtom,a as useAtomValue,c as useClient};

package/dist/server.d.ts

@@ -1,14 +1,46 @@
-import { Grant } from "./types.js";
-import { Call } from "./action.js";
-import { BINDING } from "./const.js";
+import { o as Grant, r as Config } from "./types-CQLXtCsz.js";
+import { t as Call } from "./index-DNUoYl4_.js";
+import * as Y from "yjs";
 import { YServer } from "y-partyserver";
 //#region src/server.d.ts
-declare class AiaxServer extends YServer {
+declare const snapshot: (doc: Y.Doc, keys?: string[]) => Uint8Array;
+declare class Server extends YServer {
+  static options: {
+    hibernate: boolean;
+  };
+  static callbackOptions: {
+    debounceWait: number;
+    debounceMaxWait: number;
+  };
+  env: any;
+  ctx: any;
+  ai: any;
+  sub: string;
+  path: string;
+  grant: Grant | null;
+  queue: Promise<any>;
+  hook: (run: () => Promise<any>) => Promise<any>;
   wrap: (run: () => Promise<any>) => Promise<any>;
   call: Call;
+  conf(): Config;
+  isLobby(): boolean;
+  saved(grant: Grant): {
+    env: any;
+    sub: string;
+    path: string;
+    room: string;
+  };
   grantOf(request: Request): Grant;
-  onAct(_grant: Grant, _request: Request): Promise<void>;
+  owner(): Promise<Grant>;
+  remember(sub: string, path: string): Promise<void>;
+  onAct(grant: Grant, _request?: Request): Promise<void>;
+  onStart(): Promise<void>;
+  onConnect(conn: any, ctx: any): Promise<void>;
+  onLoad(): Promise<void>;
+  onSave(): Promise<void>;
+  onAlarm(): Promise<void>;
+  onClose(conn: any, code: number, reason: string, wasClean: boolean): Promise<void>;
   onRequest(request: Request): Promise<Response>;
 }
 //#endregion
-export { AiaxServer, BINDING, type Grant };
+export { Server, snapshot };

package/dist/server.js

@@ -1 +1 @@
-import{BINDING as e}from"./const.js";import{actions as t,bind as n,init as r}from"./action.js";import{YServer as i}from"y-partyserver";var a=class extends i{wrap=e=>e();call=r(this.document,e=>this.wrap(e));grantOf(e){return{sub:e.headers.get(`x-user-sub`)??``,path:decodeURIComponent(e.headers.get(`x-user-path`)??``)}}async onAct(e,t){}async onRequest(e){if(n(this.document),e.method!==`POST`)return new Response(`Not Found`,{status:404});let{name:r,input:i}=await e.json();return t.get(r)?.side===`client`?Response.json({ok:!0,result:await this.call(r,i)}):(await this.onAct(this.grantOf(e),e),Response.json({ok:!0,result:await this.wrap(()=>this.call(r,i))}))}};export{a as AiaxServer,e as BINDING};
+import{actions as e,bind as t,current as n,init as r}from"./index.js";import"./const.js";import*as i from"yjs";import{YServer as a}from"y-partyserver";const o=(e,t)=>{if(!t)return i.encodeStateAsUpdate(e);let n=new i.Doc;return n.transact(()=>{t.forEach(t=>{let r=e.getMap(t),a=n.getMap(t);r.forEach((e,t)=>a.set(t,e instanceof i.AbstractType?e.clone():e))})}),i.encodeStateAsUpdate(n)};var s=class extends a{static options={hibernate:!0};static callbackOptions={debounceWait:6e4,debounceMaxWait:6e4};ai=n();sub=``;path=``;grant=null;queue=Promise.resolve();hook=e=>e();wrap=e=>{let t=this.grant;this.grant=null;let n=async()=>(this.ai.use({env:this.env,room:this.name,...t??await this.owner()}),this.hook(e));return this.queue=this.queue.then(n,n),this.queue};call=r(this.document,e=>this.wrap(e));conf(){return this.ai?.config??{}}isLobby(){let e=this.conf().lobby;return!!e&&this.name===e}saved(e){return{env:this.env,sub:e.sub,path:e.path,room:this.name}}grantOf(e){return{sub:e.headers.get(`x-user-sub`)??``,path:decodeURIComponent(e.headers.get(`x-user-path`)??``)}}async owner(){for(let e of this.getConnections()){let t=e.state;if(t?.sub)return t}return this.sub?{sub:this.sub,path:this.path}:await this.ctx.storage.get(`owner`)??{sub:``,path:``}}async remember(e,t){this.sub=e||this.sub,this.path=t||this.path,e&&await this.ctx.storage.put(`owner`,{sub:e,path:t})}async onAct(e,t){this.grant=e,await this.remember(e.sub,e.path)}async onStart(){await super.onStart(),this.conf().save&&this.document.on(`update`,()=>{this.isLobby()||this.ctx.storage.setAlarm(Date.now()+7e4)})}async onConnect(e,t){let{sub:n,path:r}=this.grantOf(t.request);return e.setState({sub:n,path:r}),await this.remember(n,r),super.onConnect(e,t)}async onLoad(){let e=this.conf().load;if(!e||this.isLobby())return;let t=await e(this.saved(await this.owner()));t&&t.byteLength&&i.applyUpdate(this.document,new Uint8Array(t),`load`)}async onSave(){let e=this.conf().save;if(!e||this.isLobby())return;let t=await this.owner();t.sub&&await e(this.saved(t),o(this.document,this.conf().keys))}async onAlarm(){await this.onSave()}async onClose(e,t,n,r){await super.onClose(e,t,n,r),await this.onSave()}async onRequest(n){if(t(this.document),n.method!==`POST`)return new Response(`Not Found`,{status:404});let{name:r,input:i}=await n.json();return e.get(r)?.side===`client`?Response.json({ok:!0,result:await this.call(r,i)}):(await this.onAct(this.grantOf(n),n),Response.json({ok:!0,result:await this.wrap(()=>this.call(r,i))}))}};export{s as Server,o as snapshot};

package/dist/types.d.ts

@@ -1,42 +1,2 @@
-import { ZodRawShape } from "zod";
-//#region src/types.d.ts
-type Side = 'server' | 'client' | 'both';
-interface ActMeta {
-  name: string;
-  description: string;
-  input?: ZodRawShape;
-}
-interface ActionDef extends ActMeta {
-  side: Side;
-  run: (input: any) => Promise<any>;
-}
-interface Grant {
-  sub: string;
-  path: string;
-}
-type Own = (env: any, sub: string, path: string) => Promise<string> | string;
-interface Cookie {
-  apex: string;
-  services: string[];
-}
-interface Config {
-  name: string;
-  own: Own;
-  database?: (env: any) => any;
-  lobby?: string;
-  alias?: string;
-  system?: string;
-  model?: string;
-  claude?: string;
-  maxTokens?: number;
-  maxTurns?: number;
-  binding?: string;
-  endpoint?: string;
-  version?: string;
-  salt?: string;
-  maxAge?: number;
-  cookie?: Cookie;
-  providers?: any[];
-}
-//#endregion
-export { ActMeta, ActionDef, Config, Cookie, Grant, Own, Side };
+import { a as Define, c as Peer, i as Cookie, l as Saved, n as Ai, o as Grant, r as Config, s as Own, t as ActionDef, u as Side } from "./types-CQLXtCsz.js";
+export { ActionDef, Ai, Config, Cookie, Define, Grant, Own, Peer, Saved, Side };

package/package.json

@@ -1,7 +1,7 @@
 {
         "name": "ai-ax",
         "author": "tseijp",
-        "version": "0.4.2",
+        "version": "0.5.0",
         "license": "MIT",
         "description": "AI Agent Experience (AI/AX) library for Hono + Cloudflare. One act surface for both human UI/UX and LLM MCP tools, with authentication, authorization, realtime sync and Claude API relay.",
         "keywords": [
@@ -30,10 +30,6 @@
                         "types": "./dist/index.d.ts",
                         "default": "./dist/index.js"
                 },
-                "./action": {
-                        "types": "./dist/action.d.ts",
-                        "default": "./dist/action.js"
-                },
                 "./client": {
                         "types": "./dist/client.d.ts",
                         "default": "./dist/client.js"
@@ -42,10 +38,22 @@
                         "types": "./dist/const.d.ts",
                         "default": "./dist/const.js"
                 },
+                "./hono": {
+                        "types": "./dist/hono.d.ts",
+                        "default": "./dist/hono.js"
+                },
+                "./react": {
+                        "types": "./dist/react.d.ts",
+                        "default": "./dist/react.js"
+                },
                 "./server": {
                         "types": "./dist/server.d.ts",
                         "default": "./dist/server.js"
                 },
+                "./types": {
+                        "types": "./dist/types.d.ts",
+                        "default": "./dist/types.js"
+                },
                 "./src": {
                         "types": "./src/index.ts",
                         "default": "./src/index.ts"
@@ -57,42 +65,52 @@
         },
         "files": [
                 "dist",
+                "mermaid",
                 "README.md"
         ],
         "scripts": {
-                "build": "tsdown --config ../../tsdown.config.ts"
+                "build": "tsdown --config ../../tsdown.config.ts && rm -f dist/*-*.d.ts",
+                "mmd": "for f in concept stack grant; do mmdc -i media/$f.mmd -o media/$f.svg; done"
         },
         "devDependencies": {
                 "@auth/core": "0.34.3",
-                "@auth/drizzle-adapter": "1.11.2",
                 "@hono/auth-js": "1.1.1",
                 "@hono/mcp": "0.3.1",
                 "@modelcontextprotocol/sdk": "1.29.0",
-                "drizzle-orm": "0.45.2",
+                "@types/react": "^19.2.17",
                 "hono": "4.12.30",
                 "partyserver": "0.5.8",
+                "react": "^19.2.7",
                 "y-partyserver": "2.2.0",
                 "yjs": "13.6.31",
                 "zod": "4.4.3"
         },
         "peerDependencies": {
                 "@auth/core": ">=0.34.0",
-                "@auth/drizzle-adapter": ">=1.0.0",
                 "@hono/auth-js": ">=1.0.0",
                 "@hono/mcp": ">=0.3.0",
                 "@modelcontextprotocol/sdk": ">=1.0.0",
-                "drizzle-orm": ">=0.40.0",
                 "hono": ">=4.0.0",
                 "partyserver": ">=0.5.0",
+                "react": ">=18.0.0",
                 "y-partyserver": ">=2.0.0",
                 "yjs": ">=13.0.0",
                 "zod": ">=3.25.0"
         },
         "peerDependenciesMeta": {
-                "@auth/drizzle-adapter": {
+                "@hono/auth-js": {
+                        "optional": true
+                },
+                "@hono/mcp": {
+                        "optional": true
+                },
+                "@modelcontextprotocol/sdk": {
+                        "optional": true
+                },
+                "hono": {
                         "optional": true
                 },
-                "drizzle-orm": {
+                "react": {
                         "optional": true
                 }
         }

package/dist/action.d.ts

@@ -1,13 +0,0 @@
-import { ActMeta, ActionDef, Side } from "./types.js";
-import * as Y from "yjs";
-//#region src/action.d.ts
-type Action<I, R> = (input: I) => R | Promise<R>;
-type Call = (name: string, input: any) => Promise<any>;
-declare const actions: Map<string, ActionDef>;
-declare const side: Side;
-declare const bind: (doc: Y.Doc) => Y.Doc;
-declare const data: <T = any>(name?: string) => Y.Map<T>;
-declare function action<I extends object, R>(load: Action<I, R> | ((input?: I) => any), at: Side, meta: ActMeta): (input: I) => Promise<R>;
-declare const init: (doc: Y.Doc, wrap?: (run: () => Promise<any>) => Promise<any>) => Call;
-//#endregion
-export { Call, action, actions, bind, data, init, side };

package/dist/action.js

@@ -1 +0,0 @@
-const e=new Map,t=typeof window>`u`?`server`:`client`;let n,r;const i=e=>r=e,a=(e=`tree`)=>r.getMap(e);function o(t,r,i){let a=async e=>{let n=await t(e);return typeof n==`function`?n(e):n?.default?n.default(e):n};return e.set(i.name,{...i,side:r,run:a}),e=>n(i.name,e)}const s=(r,a=e=>e())=>{i(r);let o=r.getMap(`act-req`),s=r.getMap(`act-res`),c=new Map,l=async n=>{let c=o.get(n),l=e.get(c?.name);!l||l.side!==t||(o.delete(n),s.set(n,{value:await a(()=>(i(r),l.run(c.input)))}))},u=e=>{let t=c.get(e);!t||!s.has(e)||(c.delete(e),t(s.get(e).value),s.delete(e))};return o.observe(e=>e.keysChanged.forEach(l)),s.observe(e=>e.keysChanged.forEach(u)),n=(n,a)=>{let s=e.get(n);return s.side===t||s.side===`both`?(i(r),s.run(a)):new Promise(e=>{let t=crypto.randomUUID();c.set(t,e),o.set(t,{name:n,input:a})})},n};export{o as action,e as actions,i as bind,a as data,s as init,t as side};