npm - ai-ax - Versions diffs - 0.4.0 → 0.4.3 - Mend

ai-ax 0.4.0 → 0.4.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.ja.md ADDED Viewed

@@ -0,0 +1,147 @@
+# ai-ax
+AI Agent Experience (AI/AX) library for Hono + Cloudflare.
+ai-ax は、web アプリの「人間向けの体験 (UI/UX)」と「AI agent 向けの体験 (AI/AX)」を 1 つの操作面として実装するための library。操作は 1 度だけ宣言され、その宣言が人間には click handler、LLM には MCP tool として同時に機能する。両者は同じ realtime 状態を読み書きする。
+library 全体を支える考えは 3 つ。**one action**、**one tree**、**one resolver**。
+## Why
+web は「操作するのは人間」という前提で UI/UX を積み上げてきた。そこへ後から LLM の操作経路を足すと、操作面が 2 つ、認証認可が 2 系統、バグも 2 倍になる。2 つの実装は必ずずれていき、そのずれは数週間後の log でようやく見つかる。
+ai-ax は 2 つ目の実装を管理するのではなく、消す。AI agent をアプリのユーザーの一人として扱い、画面を見る人間と同じ状態を読ませ、同じ操作を呼ばせる。開発者が UI のボタンを click して debug すれば、その debug 済みコードがそのまま MCP 経由で agent が実行するコードになる。ずれていく「もう 1 つの実装」は存在しない。
+![one action, one tree](https://r.tsei.jp/ai-ax/concept.svg)
+**one action** — 操作の最小単位を 1 度だけ宣言し、UI と MCP の両方から同じ実装に到達させる。**one tree** — 全状態は単一の yjs の木であり、人間には描画された画面として、LLM には `get_tree` の観測結果として同じ木が見える。**one resolver** — 認可は「誰がどの部屋に入れるか」を決める 1 つの関数に集約され、人間も AI もすべての経路がそこを通る。
+## What
+前提となる構成は Hono + Cloudflare Workers。realtime 同期は partyserver (Durable Objects) + yjs、認証は Auth.js、LLM は Claude API の MCP connector。ai-ax はその接続部 — 認証、認可、realtime 同期、MCP server、LLM 中継 — を Hono middleware として提供する。
+![stack](https://r.tsei.jp/ai-ax/stack.svg)
+worker 側は合成 middleware を 1 つ置くだけでよく、Durable Object は re-export で済む。
+```ts
+import { Hono } from 'hono'
+import { createAiax, ownSelf } from 'ai-ax'
+import { PROMPT } from './prompt'
+import './actions'
+const ai = createAiax({ name: 'demo', own: ownSelf(), database: (e) => e.my_d1, system: PROMPT })
+const app = new Hono().use('*', ai.all())
+export default app
+export { AiaxServer } from 'ai-ax/server'
+```
+`ai.all()` は `/parties/*` を websocket 同期へ、`/api/mcp` を MCP server へ、`POST /api/llm` を Claude 中継へ振り分け、Auth.js の session も処理する。それ以外はすべて自作の route へ素通しする。export した `AiaxServer` は binding 名 `v1` の Durable Object として deploy する。
+### one action
+```ts
+import { action } from 'ai-ax/action'
+import { z } from 'zod'
+export const placeMark = action<{ cell: number }, string>(() => import('./actions/place-mark'), 'both', {
+        name: 'place_mark',
+        description: '空いているマスに現在の手番の印を置く',
+        input: { cell: z.number().describe('マス番号 0-8') },
+})
+```
+この 1 つの宣言から 2 つのものが生まれる。UI の event handler から呼べる async 関数と、LLM に公開される MCP tool (name / description / zod input schema)。第 1 引数は dynamic import でも実装関数そのものでもよく、bundle を分けたい service にも 1 file で書きたいアプリにも合う。
+`side` は「その実装がどこでなら動けるか」を表し、反対側から呼ばれたときは ai-ax が境界を越えて実行を届ける。
+| side     | 動作場所                          | 反対側から呼ばれたとき                             |
+| -------- | --------------------------------- | -------------------------------------------------- |
+| `both`   | browser と Durable Object の両方  | 呼んだ側でそのまま実行                             |
+| `client` | browser のみ (browser API が必要) | yjs 上の act-req / act-res で接続中 browser へ委譲 |
+| `server` | Durable Object のみ               | Durable Object へ転送                              |
+action の中では `data()` が共有の `Y.Map` (`tree`) を返す。ここへの書き込みは接続中の全 browser に realtime 同期され、LLM が観測するのも全く同じ木。だから agent の操作は人間の画面にその場で現れる。
+browser 側は 1 度接続すればすべてが動き出す。
+```ts
+import { ALIAS, connect } from 'ai-ax/client'
+const link = connect({ room: ALIAS })
+link.synced(() => boot())
+```
+client は常に別名 `my-room` で接続する。server が認可済みの room 名へ書き換えるため、client が実際の room 名を選ぶことはない。
+### one resolver
+credential は 2 種類だけ。どちらも `AUTH_SECRET` で署名された jwt であり、平文の user id が network を渡ることはない。
+| 経路                       | credential                   | 発行                              | 検証                                  |
+| -------------------------- | ---------------------------- | --------------------------------- | ------------------------------------- |
+| Browser → Worker           | session cookie (Auth.js jwt) | `/api/auth` (Google OAuth)        | `userSub()`                           |
+| Claude → Worker `/api/mcp` | grant jwt `{ sub, path }`    | llm middleware が認可後に発行     | `readGrant()`                         |
+| Worker → Durable Object    | room 名 + `x-user-sub`       | worker が認可済みの値で必ず上書き | DO へは worker binding 経由でのみ到達 |
+認可は 1 つの関数に集約される。
+```ts
+type Own = (env: any, sub: string, path: string) => Promise<string> | string
+```
+答えるのは「この user はこの path に対してどの部屋を得るか」だけで、空文字は拒否。`ownSelf()` は user 本人の id を返す (個人アプリ: 全員が自分だけの部屋を持つ)。`ownSite(bucket)` は R2 の file metadata を引く (editor アプリ: file を所有していればその部屋が開く)。D1 の所属 table を join する resolver も同じ型で書ける。
+grant jwt は llm middleware が turn ごとに発行し、Claude API がすべての MCP request に載せて `/api/mcp` へ運ぶ。MCP server は毎回署名を検証してから操作を実行する。LLM は token の中身を選べず、書き換えれば署名が壊れる。つまり agent はその瞬間に認可された 1 部屋の中に封じられる。
+![grant sequence](https://r.tsei.jp/ai-ax/grant.svg)
+### LLM 中継
+`POST /api/llm` に `{ path, prompt, model?, messages? }` を送ると、認可 → grant 発行 → MCP server 付きで Claude API 呼び出し → text stream 中継、が 1 本で流れる。`messages` は prompt の前に積む過去の会話。library は履歴を保存しない — 何をどこへどんな形で永続化するかはアプリの決めごとであり、ここに渡されたものをそのまま再生するだけ。
+stream は素の text で、`[tool] server name` の行が tool 呼び出しを、末尾の `[usage] ...` の行が turn の終わりを表す。この wire format の browser 側の相棒が `createStream()`。
+```ts
+import { createStream } from 'ai-ax/client'
+const stream = createStream()
+const items = await stream.send({ prompt, path, model, messages }, (u) => draw(u.items))
+```
+`parse` は raw text を `{ text, tools }` の item 列に分解して usage を隠し、`send` は POST しながら parse 済みの update を流す。対になる `pack` / `unpack` は完成した応答を保存可能な `{ reply, tools }` 形式と相互変換する。アプリは wire format そのものに触れずに、会話の描画・永続化・再生ができる。
+## How
+| entry          | 主な export                         | 動作場所                 |
+| -------------- | ----------------------------------- | ------------------------ |
+| `ai-ax`        | `createAiax`, `ownSelf`, `ownSite`  | worker (Hono middleware) |
+| `ai-ax/client` | `connect`, `createStream`, `ALIAS`  | browser                  |
+| `ai-ax/action` | `action`, `actions`, `data`, `side` | 共有の action 宣言       |
+| `ai-ax/server` | `AiaxServer`                        | Durable Object           |
+| `ai-ax/const`  | protocol 定数 (path と header 名)   | 両方                     |
+`createAiax(config)` は以下を受け取り `{ all, auth, party, mcp, llm }` を返す。`all()` が上で示した合成 middleware で、4 つの factory は個別にも使える。
+| key       | 型                    | 既定値                                    | 説明                                                        |
+| --------- | --------------------- | ----------------------------------------- | ----------------------------------------------------------- |
+| name      | `string`              | 必須                                      | service id。MCP server 名になる                             |
+| own       | `Own`                 | 必須                                      | 認可 resolver。`''` で拒否                                  |
+| database  | `(env) => D1Database` | なし                                      | Auth.js DrizzleAdapter に渡す D1。省略時は adapter なし jwt |
+| lobby     | `string`              | なし                                      | 匿名で開放する demo 部屋 1 つ。省略時は全経路で認証必須     |
+| alias     | `string`              | `'my-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 の差し替え                                |
+`x-user-sub` / `x-user-path` の header 名と anthropic-version は library 内部の protocol 定数であり、意図的に設定不可。protocol の両端は同時に変わる必要があるため。

package/README.md CHANGED Viewed

@@ -1,221 +1,147 @@
-# 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 lets you build the human experience (UI/UX) and the AI agent experience (AI/AX) of a web app as one surface. Every operation is declared exactly once, and that single declaration becomes a click handler for humans and an MCP tool for LLMs at the same time, backed by one realtime state that both sides read and write.
+Three ideas carry the whole library: **one action**, **one tree**, **one resolver**.
+## Why
+The web has been built on the assumption that a human is the one operating it. When an LLM path is bolted onto such an app afterwards, everything doubles: two operation surfaces, two auth stacks, two sets of bugs. The two copies inevitably drift apart, and the drift is usually discovered weeks later in a log.
+ai-ax removes the second copy instead of maintaining it. The AI agent is treated as one more user of the app: it reads the same state and calls the same operations as the person watching the screen. When a developer debugs a button by clicking it in the UI, that debugged code is literally what the agent runs through MCP. There is no second implementation left to drift.
+![one action, one tree](https://r.tsei.jp/ai-ax/concept.svg)
+**One action** — the smallest unit of operation is declared once and reached from both the UI and MCP. **One tree** — all state lives in a single yjs tree, which humans see as the rendered screen and the LLM observes as `get_tree`. **One resolver** — authorization is a single function that decides which room a user may enter; every path, human or AI, goes through it.
+## What
-## 1. 全体構成
+The assumed stack is Hono + Cloudflare Workers. Realtime sync is partyserver (Durable Objects) with yjs, authentication is Auth.js, and the LLM is the Claude API with its MCP connector. ai-ax ships the server-side plumbing between them — authentication, authorization, realtime sync, the MCP server, and the LLM relay — as Hono middleware.
-前提は Hono + Cloudflare Workers。realtime 同期は partyserver (Durable Objects)、認証は Auth.js、LLM は Claude API の MCP connector。
+![stack](https://r.tsei.jp/ai-ax/stack.svg)
-```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 worker needs one composite middleware, and the Durable Object is a re-export.
+```ts
+import { Hono } from 'hono'
+import { createAiax, ownSelf } from 'ai-ax'
+import { PROMPT } from './prompt'
+import './actions'
+const ai = createAiax({ name: 'demo', own: ownSelf(), database: (e) => e.my_d1, system: PROMPT })
+const app = new Hono().use('*', ai.all())
+export default app
+export { AiaxServer } from 'ai-ax/server'
 ```
-worker には 4 つの middleware を並べるだけでよい。
+`ai.all()` routes `/parties/*` to websocket sync, `/api/mcp` to the MCP server, `POST /api/llm` to the Claude relay, and handles Auth.js sessions; everything else falls through to your own routes. The exported `AiaxServer` class is deployed as a Durable Object under the binding name `v1`.
+### One action
 ```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())
+import { action } from 'ai-ax/action'
+import { z } from 'zod'
+export const placeMark = action<{ cell: number }, string>(() => import('./actions/place-mark'), 'both', {
+        name: 'place_mark',
+        description: 'Place the current player mark on an empty cell',
+        input: { cell: z.number().describe('cell index 0-8') },
+})
 ```
-## 2. 認証と認可
+This one declaration yields two things: an async function the UI calls from event handlers, and an MCP tool (name, description, zod input schema) exposed to the LLM. The first argument is either a dynamic import or the implementation function itself, so bundles can stay split or stay simple.
-credential は 2 種類だけ。どちらも AUTH_SECRET で署名された jwt であり、平文の user id が network を渡ることはない。
+`side` states where the implementation is able to run, and ai-ax forwards calls across the boundary when the other side needs it.
-| 経路                       | 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 経由のみ |
+| side     | runs on                          | when called from the other side                            |
+| -------- | -------------------------------- | ---------------------------------------------------------- |
+| `both`   | browser and Durable Object       | executed locally on whichever side called it               |
+| `client` | browser only (needs browser API) | delegated to the connected browser via yjs act-req/act-res |
+| `server` | Durable Object only              | forwarded to the Durable Object                            |
-認可は own resolver という 1 つの関数に集約される。
+Inside an action, `data()` returns the shared `Y.Map` named `tree`. Whatever is written there syncs to every connected browser in realtime and is exactly what the LLM observes, so the agent's moves appear on the human's screen as they happen.
+The browser side connects once and everything above starts working.
 ```ts
-type Own = (env: any, sub: string, path: string) => Promise<string> | string
+import { ALIAS, connect } from 'ai-ax/client'
+const link = connect({ room: ALIAS })
+link.synced(() => boot())
 ```
-「誰 (sub) が、何 (path) に対して、どの部屋 (room) を得るか」を返す。空文字は拒否。
-所有の定義は service ごとに異なるため、resolver の実装は自由に差し替えられる。
+Clients always connect to the alias room `my-room`. The server rewrites it to the authorized room, so no client ever picks a real room name.
-```ts
-ownSite((env) => env.my_r2_xxx)
-// R2 head(`${sub}/${path}`) の customMetadata.site が room。file を所有していれば editor の部屋が開く
+### One resolver
-ownSelf()
-// room = sub。認証した本人の部屋だけが開く。start page や個人 app 向け
+Only two kinds of credentials exist, and both are jwt signed with `AUTH_SECRET`; a plain user id never crosses the network.
-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 も同じ型で書ける
-```
+| path                       | credential                   | issued by                                  | verified by                             |
+| -------------------------- | ---------------------------- | ------------------------------------------ | --------------------------------------- |
+| Browser → Worker           | session cookie (Auth.js jwt) | `/api/auth` (Google OAuth)                 | `userSub()`                             |
+| Claude → Worker `/api/mcp` | grant jwt `{ sub, path }`    | llm middleware, minted after authorization | `readGrant()`                           |
+| Worker → Durable Object    | room name + `x-user-sub`     | worker overwrites with authorized values   | DO is reachable only via worker binding |
-## 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
+Authorization concentrates into a single function.
+```ts
+type Own = (env: any, sub: string, path: string) => Promise<string> | string
 ```
-grant jwt は llm middleware が turn ごとに mint し、Claude API がそのまま /api/mcp へ運ぶ。
-LLM は token の中身を選べず、書き換えれば署名が壊れる。
-つまり LLM が操作できる部屋は「その瞬間に認可された 1 部屋」だけに封じられる。
+It answers one question — which room does this user get for this path — and an empty string denies. `ownSelf()` returns the user's own id (personal apps: everyone gets exactly one private room). `ownSite(bucket)` reads the file's metadata from R2 (editor apps: owning the file opens its room). A resolver that joins a D1 membership table fits the same type.
-## 4. room の決定規則
+The grant jwt is minted per turn by the llm middleware and carried by the Claude API to `/api/mcp` 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.
-room 名は client にも LLM にも決めさせない。必ず own resolver の結果を使う。
+![grant sequence](https://r.tsei.jp/ai-ax/grant.svg)
-- 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 つだけ開けられる。設定しなければ全経路で認証必須
+### LLM relay
-## 5. action
+`POST /api/llm` with `{ path, prompt, model?, messages? }` authorizes the caller, mints a grant, calls the Claude API with the MCP server attached, and relays the response as a text stream. `messages` is prior conversation to prepend before the prompt. The library never stores history — what to persist, where, and in which shape is the application's decision, and whatever is passed here is simply replayed.
-action は「UI handler が呼ぶ関数」と「MCP tool」の両方になる操作の最小単位。
+The stream is plain text: a `[tool] server name` line marks a tool call and a trailing `[usage] ...` line closes the turn. `createStream()` returns the browser-side counterpart of this wire format.
 ```ts
-export const placeMark = action<{ cell: number }, string>(() => import('./actions/place-mark'), 'both', {
-        name: 'place_mark',
-        description: '空いているマスに現在の手番の印を置く',
-        input: { cell: z.number().describe('マス番号 0-8') },
-})
+import { createStream } from 'ai-ax/client'
+const stream = createStream()
+const items = await stream.send({ prompt, path, model, messages }, (u) => draw(u.items))
 ```
-- 宣言から 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
+`parse` splits raw text into items of `{ text, tools }` with usage hidden, `send` posts and streams with parsed updates, and the symmetric pair `pack` / `unpack` converts a finished reply into a storable `{ reply, tools }` form and back — the pieces an app needs to render, persist, and replay conversations without ever touching the wire format itself.
+## How
+| entry          | main exports                             | where it runs             |
+| -------------- | ---------------------------------------- | ------------------------- |
+| `ai-ax`        | `createAiax`, `ownSelf`, `ownSite`       | worker (Hono middleware)  |
+| `ai-ax/client` | `connect`, `createStream`, `ALIAS`       | browser                   |
+| `ai-ax/action` | `action`, `actions`, `data`, `side`      | shared action definitions |
+| `ai-ax/server` | `AiaxServer`                             | Durable Object            |
+| `ai-ax/const`  | protocol constants (paths, header names) | both                      |
+`createAiax(config)` accepts the following and returns `{ all, auth, party, mcp, llm }` — `all()` is the composite shown above, and the four factories are also usable individually.
+| key       | type                  | default                                   | meaning                                                      |
+| --------- | --------------------- | ----------------------------------------- | ------------------------------------------------------------ |
+| name      | `string`              | required                                  | service id, becomes the MCP server name                      |
+| own       | `Own`                 | required                                  | authorization resolver, `''` denies                          |
+| database  | `(env) => D1Database` | none                                      | D1 for the Auth.js DrizzleAdapter, jwt-only when omitted     |
+| lobby     | `string`              | none                                      | one anonymous demo room, all paths require auth when omitted |
+| 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                                  |
+| endpoint  | `string`              | `'/api/mcp'`                              | MCP endpoint 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/server.d.ts CHANGED Viewed

@@ -1,5 +1,6 @@
 import { Grant } from "./types.js";
 import { Call } from "./action.js";
+import { BINDING } from "./const.js";
 import { YServer } from "y-partyserver";
 //#region src/server.d.ts
 declare class AiaxServer extends YServer {
@@ -10,4 +11,4 @@ declare class AiaxServer extends YServer {
   onRequest(request: Request): Promise<Response>;
 }
 //#endregion
-export { AiaxServer, type Grant };
+export { AiaxServer, BINDING, type Grant };

package/dist/server.js CHANGED Viewed

	@@ -1 +1 @@
1	- import"./const.js";import{actions as e,bind as t,init as n}from"./action.js";import{YServer as r}from"y-partyserver";var i=class extends r{wrap=e=>e();call=n(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(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{i as AiaxServer};
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};

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
         "name": "ai-ax",
         "author": "tseijp",
-        "version": "0.4.0",
+        "version": "0.4.3",
         "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": [
@@ -34,14 +34,18 @@
                         "types": "./dist/action.d.ts",
                         "default": "./dist/action.js"
                 },
-                "./server": {
-                        "types": "./dist/server.d.ts",
-                        "default": "./dist/server.js"
-                },
                 "./client": {
                         "types": "./dist/client.d.ts",
                         "default": "./dist/client.js"
                 },
+                "./const": {
+                        "types": "./dist/const.d.ts",
+                        "default": "./dist/const.js"
+                },
+                "./server": {
+                        "types": "./dist/server.d.ts",
+                        "default": "./dist/server.js"
+                },
                 "./src": {
                         "types": "./src/index.ts",
                         "default": "./src/index.ts"
@@ -53,10 +57,12 @@
         },
         "files": [
                 "dist",
+                "mermaid",
                 "README.md"
         ],
         "scripts": {
-                "build": "tsdown --config ../../tsdown.config.ts"
+                "build": "tsdown --config ../../tsdown.config.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",