duet-mcp 0.6.1

package/lib/edit.js

@@ -0,0 +1,63 @@
+/** 下書きと観測時の呼び口を一緒に保持する。行の外に置けば移動しても残る。 */
+export class EditSession {
+    base = null;
+    inflight = null;
+    listeners = new Set();
+    state = { active: false, value: undefined, pending: false, result: null, error: null };
+    getSnapshot = () => this.state;
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    };
+    update(state) {
+        this.state = state;
+        for (const listener of this.listeners)
+            listener();
+    }
+    editable() { if (this.inflight)
+        throw new Error("送信中は編集を変更できない。"); }
+    begin = (base, value) => {
+        if (this.state.active)
+            throw new Error("既に編集中。見直す場合は restart を使うこと。");
+        this.restart(base, value);
+    };
+    restart = (base, value) => {
+        this.editable();
+        this.base = base;
+        this.update({ active: true, value, pending: false, result: null, error: null });
+    };
+    setValue = (value) => {
+        this.editable();
+        if (!this.base)
+            throw new Error("編集を begin していない。");
+        this.update({ ...this.state, value });
+    };
+    cancel = () => {
+        this.editable();
+        this.base = null;
+        this.update({ active: false, value: undefined, pending: false, result: null, error: null });
+    };
+    run = (name, args) => {
+        if (this.inflight)
+            return this.inflight;
+        const base = this.base;
+        if (!base)
+            throw new Error("編集を begin していない。");
+        // microtask で開始し、同期の二重呼び出しでも同じ Promise を返す。
+        const promise = Promise.resolve().then(() => base.run(name, args)).then((result) => {
+            if ("ok" in result) {
+                this.base = null;
+                this.update({ active: false, value: undefined, pending: false, result, error: null });
+            }
+            else
+                this.update({ ...this.state, pending: false, result, error: null });
+            return result;
+        }, (err) => {
+            this.update({ ...this.state, pending: false, error: err instanceof Error ? err.message : String(err) });
+            throw err;
+        }).finally(() => { this.inflight = null; });
+        this.inflight = promise;
+        this.update({ ...this.state, pending: true, error: null });
+        return promise;
+    };
+}

package/lib/http.d.ts

@@ -0,0 +1,9 @@
+import { Hono } from "hono";
+import type { DocStore } from "./doc.js";
+import type { AppDef } from "./types.js";
+/**
+ * DocStore に触れる唯一の実装。
+ * ブラウザも、daemon 自身の MCP 層も、別プロセスの MCP 層も、全部ここを通る。
+ * 経路が 1 本なので「daemon かどうかで挙動が変わらない」を維持する必要が無い。
+ */
+export declare function createHttpApp<Doc>(app: AppDef<Doc>, getStore: () => DocStore<Doc>): Hono;

package/lib/http.js

@@ -0,0 +1,151 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Hono } from "hono";
+import { BlobStore } from "./blob.js";
+import { rootFor, dataDirFor } from "./paths.js";
+import { takeShot } from "./shot.js";
+import { baseUrlFor, MAX_WAIT_MS, MIN_WAIT_MS, portFor, WAIT_MS } from "./wire.js";
+const MIME = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".map": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+    ".gif": "image/gif",
+    ".ico": "image/x-icon",
+    ".woff2": "font/woff2",
+    ".woff": "font/woff",
+    ".ttf": "font/ttf",
+    ".wasm": "application/wasm",
+};
+function serveFile(root, filePath) {
+    const rel = path.relative(root, filePath);
+    if (rel.startsWith("..") || path.isAbsolute(rel))
+        return null;
+    if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile())
+        return null;
+    const type = MIME[path.extname(filePath)] ?? "application/octet-stream";
+    return new Response(new Uint8Array(fs.readFileSync(filePath)), {
+        headers: { "content-type": type },
+    });
+}
+const num = (v) => {
+    if (v === undefined || v === "")
+        return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : undefined;
+};
+const list = (v) => v === undefined || v === "" ? undefined : v.split(",").filter(Boolean);
+// 下限を切らないと、timeoutMs: 0 が「即 timedOut で返り続ける」空回りになる。
+const clampTimeout = (v) => Math.min(Math.max(v ?? WAIT_MS, MIN_WAIT_MS), MAX_WAIT_MS);
+/**
+ * 呼び出し元の名前。ヘッダが無ければブラウザなので "human"。
+ * MCP プロセスは env の DUET_ACTOR を送ってくる。
+ */
+const actorOf = (c) => c.req.header("x-duet-actor") || "human";
+/**
+ * DocStore に触れる唯一の実装。
+ * ブラウザも、daemon 自身の MCP 層も、別プロセスの MCP 層も、全部ここを通る。
+ * 経路が 1 本なので「daemon かどうかで挙動が変わらない」を維持する必要が無い。
+ */
+export function createHttpApp(app, getStore) {
+    const http = new Hono();
+    // verify と実リクエストの間に別アプリへ入れ替わっても操作を渡さない。
+    http.use("/api/*", async (c, next) => {
+        const expected = c.req.header("x-duet-app-id");
+        if (expected !== undefined && expected !== app.id)
+            return c.json({ error: "接続先は別の duet アプリ。" }, 409);
+        await next();
+    });
+    const blobs = new BlobStore(app.id, dataDirFor(app));
+    /** DocStore は最初のリクエストまで作られない（生成の遅延は boot.ts 側にある）。 */
+    const store = getStore;
+    // ---- 正体確認と居場所 ----
+    // ポートは app.id から導出されるので、人にも LLM にも見えない。
+    // 「どこで開いているか」を答えられる口を基盤が既定で持つ。
+    http.get("/api/hello", (c) => c.json({
+        id: app.id,
+        version: app.version,
+        port: portFor(app.id),
+        url: baseUrlFor(app.id),
+    }));
+    // ---- ドキュメント取得 / 待機 ----
+    // since を付けると変化があるまで返さない（ロングポーリング）。
+    // ブラウザの購読も MCP の await_change もこれ 1 本。
+    http.get("/api/doc", async (c) => {
+        const since = c.req.query("since");
+        return c.json(await store().wait(since, list(c.req.query("until")), clampTimeout(num(c.req.query("timeout"))), actorOf(c), c.req.raw.signal));
+    });
+    // snapshot と操作結果を DocStore が同時に確定する。
+    http.post("/api/op/:name", async (c) => {
+        const name = c.req.param("name");
+        if (!app.ops.some((o) => o.name === name))
+            return c.json({ error: `unknown op: ${name}` }, 404);
+        const args = await c.req.json().catch(() => ({}));
+        return c.json(store().run(name, args, actorOf(c)));
+    });
+    // ---- 活動の申告 ----
+    // 「今この人が触っている」だけを記録する。revision も doc も動かさない。
+    // 打鍵ごとに来るので、応答に doc を載せない（載せると 1 打鍵ごとに全状態が往復する）。
+    http.post("/api/touch", (c) => {
+        store().touch(actorOf(c));
+        return c.json({ ok: true });
+    });
+    // ---- スクリーンショット（GUI をそのまま撮る）----
+    http.post("/api/shot", async (c) => {
+        const body = (await c.req.json().catch(() => ({})));
+        try {
+            return c.json({ data: await takeShot(app, store().revision, body.path || "/") });
+        }
+        catch (err) {
+            return c.json({ error: err instanceof Error ? err.message : String(err) }, 400);
+        }
+    });
+    // ---- blob（画像などの実体）----
+    http.post("/api/blob", async (c) => {
+        const mime = c.req.header("content-type") ?? "application/octet-stream";
+        const bytes = new Uint8Array(await c.req.arrayBuffer());
+        if (bytes.byteLength === 0)
+            return c.json({ error: "empty body" }, 400);
+        return c.json(blobs.put(bytes, mime));
+    });
+    http.get("/api/blob", (c) => c.json(blobs.list()));
+    http.get("/blob/:id", (c) => {
+        const found = blobs.get(c.req.param("id"));
+        if (!found)
+            return c.text("not found", 404);
+        return new Response(new Uint8Array(found.bytes), {
+            headers: {
+                "content-type": found.mime,
+                "cache-control": "public, max-age=31536000, immutable",
+            },
+        });
+    });
+    // ---- GUI（vite ビルド成果物）。実ファイルが無ければ index.html を返す ----
+    // /api の打ち間違いが GUI の HTML で返ると原因が分からなくなるので、先に落とす。
+    http.all("/api/*", (c) => c.json({ error: `unknown endpoint: ${c.req.path}` }, 404));
+    const webDist = path.resolve(rootFor(app), app.webDist);
+    http.get("/*", (c) => {
+        let rel;
+        try {
+            rel = decodeURIComponent(new URL(c.req.url).pathname).replace(/^\/+/, "");
+        }
+        catch {
+            return c.text("bad path", 400);
+        }
+        const asFile = serveFile(webDist, path.resolve(webDist, rel));
+        if (asFile)
+            return asFile;
+        const index = serveFile(webDist, path.join(webDist, "index.html"));
+        if (index)
+            return index;
+        return c.text(`${app.webDist} not built. run: npm run build:web`, 404);
+    });
+    return http;
+}

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+/** 操作定義と共有型。Node.js の実行処理は duet-mcp/server から読み込む。 */
+export { defineApp, opFactory } from "./op.js";
+export type { AppDef, Op, Ctx, Actor, Json, Revision, Snapshot, RunResult } from "./types.js";

package/lib/index.js

@@ -0,0 +1,2 @@
+/** 操作定義と共有型。Node.js の実行処理は duet-mcp/server から読み込む。 */
+export { defineApp, opFactory } from "./op.js";

package/lib/mcp.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AppDef } from "./types.js";
+/** daemon の HTTP を叩く。daemon 自身も自分を叩く。 */
+export type Call = <T>(pathname: string, init?: RequestInit) => Promise<T>;
+export declare function registerTools<Doc>(server: McpServer, app: AppDef<Doc>, call: Call): void;

package/lib/mcp.js

@@ -0,0 +1,109 @@
+import { dataDirFor } from "./paths.js";
+import { z } from "zod";
+import { BlobStore } from "./blob.js";
+import { inputShape } from "./op.js";
+import { MAX_WAIT_MS, WAIT_MS } from "./wire.js";
+const json = (value) => ({
+    content: [{ type: "text", text: JSON.stringify(value) }],
+});
+/**
+ * conflict を扱えないと詰まるので、それを説明文で担保する。
+ * 競合後に最新 doc で意図を見直すことを伝える。
+ *
+ * op ごとに付くので短く保つこと。activity の説明は await_change 側に 1 度だけ置く。
+ */
+const CONFLICT_NOTE = " baseRevision は意図を決めるために観測した revision（文字列）をそのまま渡す。" +
+    "版が変わっていたら handler を実行せず conflict と最新 doc を返す。" +
+    "最新 doc を見て意図を見直すこと。同じ引数を新しい版で自動再送しない。" +
+    "通信エラーは適用結果が不明な場合がある。まず await_change で現在の状態を確認する。";
+/** 基盤が生やすツール。op がこの名前を使うと登録が衝突する。 */
+const RESERVED = ["gui_url", "await_change", "render_screenshot", "read_blob"];
+export function registerTools(server, app, call) {
+    const blobs = new BlobStore(app.id, dataDirFor(app));
+    const clash = app.ops.filter((o) => RESERVED.includes(o.name)).map((o) => o.name);
+    if (clash.length > 0) {
+        throw new Error(`op の名前が基盤のツールと衝突している: ${clash.join(", ")}`);
+    }
+    const post = (pathname, body) => call(pathname, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    // ---- アプリが定義した op をそのままツールにする ----
+    for (const op of app.ops) {
+        server.registerTool(op.name, {
+            title: op.name,
+            description: op.description + CONFLICT_NOTE,
+            inputSchema: inputShape(op),
+        }, async (args) => json(await post(`/api/op/${encodeURIComponent(op.name)}`, args)));
+    }
+    // ---- どこで開いているか ----
+    // ポートは app.id から導出されるので、人は自力で知りようがない。
+    // 「ブラウザで開きたい」と言われたら、これを呼んで URL を伝えること。
+    server.registerTool("gui_url", {
+        title: "gui_url",
+        description: "人が操作する GUI の URL を返す。ポートは app.id から導出されるので、" +
+            "人に「どこで開いているか」を聞かれたらこれで答えること。",
+        inputSchema: {},
+    }, async () => json(await call("/api/hello")));
+    // ---- 人間の操作を待つ ----
+    server.registerTool("await_change", {
+        title: "await_change",
+        description: "省略すると現在の doc と revision を即時取得する。sinceRevision は観測した文字列をそのまま渡す。" +
+            "その版以後のコミットを待ち、既に変更があれば即返す。until は待つ op 名を絞る。" +
+            "全応答に doc が載る。truncated は差分を説明できないという意味。doc を確認すること。" +
+            "再起動や履歴の保持範囲外でも最新 doc を即返す。timedOut の場合も doc と revision を組で読む。" +
+            "changes は対象 op の変更説明で、連続した同じ参加者の同じ op は count にまとまる。" +
+            "activity は最終活動からの経過ミリ秒で、編集完了や優先権は保証しない。activity 自体では起床しない。",
+        inputSchema: {
+            sinceRevision: z
+                .string()
+                .optional()
+                .describe("直前に観測した revision。省略すると待たずに今の doc を返す。"),
+            until: z.array(z.string()).optional().describe("待つ op 名。省略すると任意の変更。"),
+            timeoutMs: z.number().optional().describe(`既定 ${WAIT_MS}、上限 ${MAX_WAIT_MS}。`),
+        },
+    }, async ({ sinceRevision, until, timeoutMs }) => {
+        // sinceRevision は任意。省略すると http.ts の「待たずに今の doc を返す」経路に落ちる。
+        // 初回にはまだ観測識別子を持っていない。
+        const q = new URLSearchParams();
+        if (sinceRevision !== undefined)
+            q.set("since", String(sinceRevision));
+        if (until?.length)
+            q.set("until", until.join(","));
+        if (timeoutMs !== undefined)
+            q.set("timeout", String(Math.min(timeoutMs, MAX_WAIT_MS)));
+        return json(await call(`/api/doc?${q}`));
+    });
+    // ---- 描画結果を見る。人が見ている GUI をそのまま撮る ----
+    server.registerTool("render_screenshot", {
+        title: "render_screenshot",
+        description: "同じ文書を GUI の別セッションで描画した PNG を返す。人間の下書きやスクロール位置は共有しない。" +
+            "path を渡すとその画面へ移動してから撮る（GUI が解釈する URL をそのまま書く）。",
+        inputSchema: {
+            path: z.string().optional().describe('既定 "/"。例: "/board/2?debug=1"'),
+        },
+    }, async ({ path }) => {
+        const r = await post("/api/shot", { path });
+        const { data } = r;
+        return { content: [{ type: "image", data, mimeType: "image/png" }] };
+    });
+    // ---- blob（画像などの実体）。不変なので daemon を通さない ----
+    server.registerTool("read_blob", {
+        title: "read_blob",
+        description: "blob を読む。画像なら画像として返す。id は doc から得る。",
+        inputSchema: { id: z.string() },
+    }, async ({ id }) => {
+        const found = blobs.get(id);
+        if (!found)
+            return json({ error: `blob not found: ${id}` });
+        if (found.mime.startsWith("image/")) {
+            return {
+                content: [
+                    { type: "image", data: found.bytes.toString("base64"), mimeType: found.mime },
+                ],
+            };
+        }
+        return json({ id, mime: found.mime, text: found.bytes.toString("utf8") });
+    });
+}

package/lib/op.d.ts

@@ -0,0 +1,10 @@
+import type { AppDef, Op, ZodRawShape } from "./types.js";
+/**
+ * Doc を固定した op 定義ヘルパ。
+ * `const op = opFactory<MyDoc>()` としてから op({...}) と書くと、
+ * handler の ctx.doc と args に型が付く。
+ */
+export declare function opFactory<Doc>(): <Shape extends ZodRawShape>(op: Op<Doc, Shape>) => Op<Doc, Shape>;
+export declare function defineApp<Doc>(app: AppDef<Doc>): AppDef<Doc>;
+/** 両方の入口に同じ観測識別子を要求する。 */
+export declare function inputShape<Doc>(op: Op<Doc>): ZodRawShape;

package/lib/op.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+/**
+ * Doc を固定した op 定義ヘルパ。
+ * `const op = opFactory<MyDoc>()` としてから op({...}) と書くと、
+ * handler の ctx.doc と args に型が付く。
+ */
+export function opFactory() {
+    return (op) => op;
+}
+export function defineApp(app) {
+    return app;
+}
+/** 両方の入口に同じ観測識別子を要求する。 */
+export function inputShape(op) {
+    return {
+        ...op.input,
+        baseRevision: z.string().min(1).describe("意図を決めるために観測した revision をそのまま渡す。数値の旧形式は使えない。版が変われば実行前に conflict。"),
+    };
+}

package/lib/paths.d.ts

@@ -0,0 +1,4 @@
+import type { AppDef } from "./types.js";
+/** パッケージの設置場所ではなく、アプリが指定したルートを使う。 */
+export declare function rootFor(app: Pick<AppDef<unknown>, "rootDir">): string;
+export declare const dataDirFor: (app: Pick<AppDef<unknown>, "rootDir">) => string;

package/lib/paths.js

@@ -0,0 +1,9 @@
+import path from "node:path";
+/** パッケージの設置場所ではなく、アプリが指定したルートを使う。 */
+export function rootFor(app) {
+    if (app.rootDir !== undefined && !path.isAbsolute(app.rootDir)) {
+        throw new Error("rootDir は絶対パスで指定してください。");
+    }
+    return app.rootDir ?? process.cwd();
+}
+export const dataDirFor = (app) => path.join(rootFor(app), "data");

package/lib/protocol.d.ts

@@ -0,0 +1,36 @@
+import type { Json } from "./diff.js";
+/** 不透明な観測識別子。受け取った値をそのまま返す。 */
+export type Revision = string;
+export type Snapshot<Doc> = {
+    revision: Revision;
+    actor: string;
+    doc: Readonly<Doc>;
+    activity: Record<string, number>;
+};
+export type Change = {
+    revision: Revision;
+    op: string;
+    actor: string;
+    count: number;
+    touched: string[];
+};
+export type Diff = {
+    changes: Change[];
+    truncated: boolean;
+};
+export type RunResult<Doc> = Snapshot<Doc> & ({
+    ok: true;
+    result?: Json;
+} | {
+    rejected: string;
+} | ({
+    conflict: true;
+} & Diff));
+export type WaitResult<Doc> = Snapshot<Doc> & Diff & {
+    timedOut: boolean;
+};
+/** 基盤内部だけで使う。アプリは revision を解析しない。 */
+export declare function parseRevision(value: unknown): {
+    epoch: string;
+    seq: number;
+} | null;

package/lib/protocol.js

@@ -0,0 +1,10 @@
+/** 基盤内部だけで使う。アプリは revision を解析しない。 */
+export function parseRevision(value) {
+    if (typeof value !== "string")
+        return null;
+    const match = /^([^:]+):(0|[1-9]\d*)$/.exec(value);
+    if (!match)
+        return null;
+    const seq = Number(match[2]);
+    return Number.isSafeInteger(seq) ? { epoch: match[1], seq } : null;
+}

package/lib/server.d.ts

@@ -0,0 +1 @@
+export { runApp } from "./boot.js";

package/lib/server.js

@@ -0,0 +1 @@
+export { runApp } from "./boot.js";

package/lib/shot.d.ts

@@ -0,0 +1,8 @@
+import { type Revision } from "./protocol.js";
+import type { AppDef } from "./types.js";
+/**
+ * 同じ daemon の要求時点以降の DOM 反映を待つ。
+ * 非同期画像などのアプリ固有の描画完了は、この属性だけでは判定できない。
+ * 基盤と GUI の間の contract はこの属性 1 つだけ。
+ */
+export declare function takeShot<Doc>(app: AppDef<Doc>, revision: Revision, at?: string): Promise<string>;

package/lib/shot.js

@@ -0,0 +1,85 @@
+import { chromium } from "playwright";
+import { parseRevision } from "./protocol.js";
+import { baseUrlFor } from "./wire.js";
+const READY_TIMEOUT_MS = 10_000;
+const DEFAULT_VIEWPORT = { width: 1024, height: 768 };
+/**
+ * 撮影先。既定は daemon 自身（= 人が見ているのと同じ vite ビルド成果物）。
+ *
+ * 開発時だけ差し替える。`dev:web` 中は人間が :5173 の最新を見ているのに、
+ * daemon は古い（あるいは未ビルドの）dist を配るので、既定のままだと
+ * ビルド成果物の食い違いを避けるため、開発中はここを :5173 に向ける。
+ *
+ *   DUET_SHOT_ORIGIN=http://127.0.0.1:5173
+ *
+ * vite の dev server は /api と /blob を daemon にプロキシするので、
+ * data-duet-revision の契約はそのまま成立する。
+ */
+const shotOrigin = (id) => process.env.DUET_SHOT_ORIGIN?.replace(/\/+$/, "") ?? baseUrlFor(id);
+const holder = globalThis;
+/**
+ * 同じ GUI を別セッションで描く。人間の下書きやスクロール位置は共有しない。
+ *
+ * ページは開いたままにする。GUI は useDoc でロングポーリングしているので、
+ * 常に最新を映している。撮影ごとの navigate も再読み込みも要らない。
+ */
+async function getPage(app, at) {
+    const url = `${shotOrigin(app.id)}${at}`;
+    const live = holder.__duetShot;
+    if (live && live.browser.isConnected() && !live.page.isClosed()) {
+        if (live.at !== at) {
+            await live.page.goto(url);
+            live.at = at;
+        }
+        return live.page;
+    }
+    // 死んだ browser を掴んだままにすると、以後の撮影が永久に失敗する。
+    holder.__duetShot = undefined;
+    const reusable = live?.browser.isConnected() === true ? live.browser : null;
+    if (reusable)
+        await live.page.close().catch(() => { });
+    const browser = reusable ?? (await chromium.launch({ headless: true }));
+    const v = app.shot?.viewport;
+    const page = await browser.newPage({
+        viewport: v ? { width: Math.ceil(v.w), height: Math.ceil(v.h) } : DEFAULT_VIEWPORT,
+    });
+    await page.goto(url);
+    holder.__duetShot = { browser, page, at };
+    return page;
+}
+/**
+ * 同じ daemon の要求時点以降の DOM 反映を待つ。
+ * 非同期画像などのアプリ固有の描画完了は、この属性だけでは判定できない。
+ * 基盤と GUI の間の contract はこの属性 1 つだけ。
+ */
+export function takeShot(app, revision, at = "/") {
+    // 参加者は複数居てよい設計なので、render_screenshot が同時に来ることはある。
+    // 並べないと、片方が撮っている間にもう片方が goto して別の画面が写る。
+    const prev = holder.__duetShotQueue ?? Promise.resolve();
+    const next = prev.then(() => capture(app, revision, at));
+    holder.__duetShotQueue = next.then(() => undefined, () => undefined);
+    return next;
+}
+async function capture(app, revision, at) {
+    const page = await getPage(app, at);
+    const want = parseRevision(revision);
+    if (!want)
+        throw new Error("invalid revision");
+    await page.waitForFunction((target) => {
+        const raw = document.documentElement.dataset.duetRevision;
+        const parts = raw?.split(":");
+        return parts?.[0] === target.epoch && Number(parts[1]) >= target.seq;
+    }, want, { timeout: READY_TIMEOUT_MS });
+    await page.evaluate(() => document.fonts.ready.then(() => true));
+    const epoch = await page.evaluate(() => document.documentElement.dataset.duetRevision?.split(":")[0]);
+    if (epoch !== want.epoch)
+        throw new Error("撮影中に daemon が交代した。最新状態を取得して撮り直すこと。");
+    const selector = app.shot?.selector;
+    const buf = selector
+        ? await page.locator(selector).screenshot({ type: "png" })
+        : await page.screenshot({ type: "png" });
+    const after = await page.evaluate(() => document.documentElement.dataset.duetRevision?.split(":")[0]);
+    if (after !== want.epoch)
+        throw new Error("撮影中に daemon が交代した。最新状態を取得して撮り直すこと。");
+    return buf.toString("base64");
+}

package/lib/transport.d.ts

@@ -0,0 +1,7 @@
+/** 読み取りの再接続と、結果不明の書き込みを区別する。 */
+export declare class Reached extends Error {
+}
+export declare class OutcomeUnknown extends Error {
+    constructor();
+}
+export declare function requestWithRecovery<T>(request: () => Promise<T>, recover: () => Promise<void>, method?: string): Promise<T>;

package/lib/transport.js

@@ -0,0 +1,22 @@
+/** 読み取りの再接続と、結果不明の書き込みを区別する。 */
+export class Reached extends Error {
+}
+export class OutcomeUnknown extends Error {
+    constructor() { super("操作の適用結果が不明。自動再送していない。最新の doc を取得して確認すること。"); }
+}
+export async function requestWithRecovery(request, recover, method = "GET") {
+    try {
+        return await request();
+    }
+    catch (err) {
+        if (err instanceof Reached)
+            throw err;
+        if (method.toUpperCase() !== "GET") {
+            // 所有者の回復は試すが、元の操作を再実行しない。
+            await recover().catch(() => { });
+            throw new OutcomeUnknown();
+        }
+        await recover();
+        return request();
+    }
+}

package/lib/types.d.ts

@@ -0,0 +1,66 @@
+import type { z } from "zod";
+import type { Json } from "./diff.js";
+export type { Revision, Snapshot, RunResult } from "./protocol.js";
+export type { Json } from "./diff.js";
+export type ZodRawShape = z.ZodRawShape;
+/**
+ * 誰が操作したか。ただの文字列。
+ * ブラウザからは "human"、MCP からは env の DUET_ACTOR（既定 "llm"）。
+ * MCP 設定に DUET_ACTOR=gpt と書けば別参加者になる。
+ *
+ * 「面」でも「役割」でもない。席の割り当てはアプリの doc に書くこと。
+ */
+export type Actor = string;
+/**
+ * op のハンドラが受け取るもの。これで全部。
+ *
+ * doc はそのまま書き換えてよい。これは複製なので、reject や例外で抜けた場合は
+ * 途中まで書いた変更ごと捨てられる。commit / 永続化 / revision 採番は基盤が行う。
+ */
+export type Ctx<Doc> = {
+    doc: Doc;
+    actor: Actor;
+    /**
+     * この操作は適用しない、と宣言して中断する。revision は進まない。
+     * 非合法な入力、状態的に許されない要求、手番違反はすべてこれ（例外ではなく正常な結果）。
+     * `return reject(...)` の形で呼ぶこと。
+     */
+    reject: (reason: string) => never;
+};
+/**
+ * 操作の唯一の定義。ここから MCP ツールと HTTP ルートの両方が生える。
+ *
+ * handler をメソッド構文で宣言しているのは、具体的な Shape を持つ Op を
+ * Op<Doc, ZodRawShape>[] に代入できるようにするため（双変性）。
+ */
+export type Op<Doc, Shape extends ZodRawShape = ZodRawShape> = {
+    name: string;
+    description: string;
+    /** baseRevision は基盤が必須項目として足す。 */
+    input: Shape;
+    /** 同期で doc と結果だけを計算する。外部副作用・Promise は扱わない。 */
+    handler(ctx: Ctx<Doc>, args: z.infer<z.ZodObject<Shape>>): Json | void;
+};
+export type AppDef<Doc> = {
+    /** ポートとデータファイル名の元になる。プロセス間の正体確認にも使う。 */
+    id: string;
+    version: string;
+    initialDoc: () => Doc;
+    ops: Op<Doc>[];
+    /** アプリのルートの絶対パス。省略時は起動時の作業ディレクトリ。保存先はこの下の data/。 */
+    rootDir?: string;
+    /** GUI の出力先。rootDir からの相対パス、または絶対パス。 */
+    webDist: string;
+    /**
+     * スクリーンショットの撮り方。省略するとビューポート全体を等倍で撮る。
+     * 絵は GUI をそのまま撮るので、LLM 用に別途描画するものは無い。
+     */
+    shot?: {
+        /** 撮る要素の CSS セレクタ。省略するとページ全体。 */
+        selector?: string;
+        viewport?: {
+            w: number;
+            h: number;
+        };
+    };
+};

package/lib/types.js

@@ -0,0 +1 @@
+export {};