@kanf/wema-kake 0.0.0-stage → 0.1.0

package/dist/lib/shared/op-summary.d.ts

@@ -0,0 +1,30 @@
+/** 保存する符号 */
+export declare const systemSummary: {
+    /** ページを、付箋を置いた状態で作った（最初のページ） */
+    pageCreated: () => string;
+    /** 子ページ `page` を削除したので、その付箋を消した */
+    childRemoved: (page: string) => string;
+    /** 操作 `seq` を取り消した（要約を付けずに取り消したとき） */
+    revert: (seq: number) => string;
+    /** ページ `page` から移した（写した）付箋を置いた */
+    notesReceived: (page: string) => string;
+    /** 子ページ `page` の色に、その付箋の色を合わせた */
+    childRecolored: (page: string) => string;
+};
+export type SystemSummary = {
+    kind: 'pageCreated';
+} | {
+    kind: 'childRemoved';
+    page: string;
+} | {
+    kind: 'revert';
+    seq: number;
+} | {
+    kind: 'notesReceived';
+    page: string;
+} | {
+    kind: 'childRecolored';
+    page: string;
+};
+/** 要約が、サーバーの付けた符号なら、その中身を返す。符号でなければ（知らない符号も）null */
+export declare function parseSystemSummary(summary: string): SystemSummary | null;

package/dist/lib/shared/op-summary.js

@@ -0,0 +1,37 @@
+// サーバーが付ける、操作の要約（ops.summary）。文言ではなく符号で保存し、画面が、今の言語の文言に
+// して出す（docs/plan.md のフェーズ 9）。LLM が MCP で付けた要約は、書かれた文のまま保存する。
+//
+// 符号を足す前に保存された要約（日本語の文）は、そのまま残っている。画面は、符号でない要約を、
+// そのまま出す。
+const PREFIX = 'system:';
+/** 保存する符号 */
+export const systemSummary = {
+    /** ページを、付箋を置いた状態で作った（最初のページ） */
+    pageCreated: () => `${PREFIX}page-created`,
+    /** 子ページ `page` を削除したので、その付箋を消した */
+    childRemoved: (page) => `${PREFIX}child-removed:${page}`,
+    /** 操作 `seq` を取り消した（要約を付けずに取り消したとき） */
+    revert: (seq) => `${PREFIX}revert:${seq}`,
+    /** ページ `page` から移した（写した）付箋を置いた */
+    notesReceived: (page) => `${PREFIX}notes-received:${page}`,
+    /** 子ページ `page` の色に、その付箋の色を合わせた */
+    childRecolored: (page) => `${PREFIX}child-recolored:${page}`,
+};
+/** 要約が、サーバーの付けた符号なら、その中身を返す。符号でなければ（知らない符号も）null */
+export function parseSystemSummary(summary) {
+    if (!summary.startsWith(PREFIX))
+        return null;
+    const [kind, ...rest] = summary.slice(PREFIX.length).split(':');
+    const value = rest.join(':');
+    if (kind === 'page-created' && value === '')
+        return { kind: 'pageCreated' };
+    if (kind === 'child-removed' && value !== '')
+        return { kind: 'childRemoved', page: value };
+    if (kind === 'revert' && /^\d+$/.test(value))
+        return { kind: 'revert', seq: Number(value) };
+    if (kind === 'notes-received' && value !== '')
+        return { kind: 'notesReceived', page: value };
+    if (kind === 'child-recolored' && value !== '')
+        return { kind: 'childRecolored', page: value };
+    return null;
+}

package/dist/lib/shared/protocol.d.ts

@@ -0,0 +1,74 @@
+import type { HistoryDelta, Snapshot } from './delta';
+/** 認証の期限が切れた接続を、サーバーが閉じるときのコード。クライアントは再読み込みして認証し直す */
+export declare const CLOSE_AUTH_EXPIRED = 4401;
+/**
+ * ページが削除されたときに、サーバーが接続を閉じるコード。クライアントは再接続しない
+ * （再接続すると、手元の未確定の操作でページが作り直されてしまう）
+ */
+export declare const CLOSE_PAGE_DELETED = 4410;
+/** 接続維持のためにクライアントが送る文字列と、サーバーの応答（JSON ではない） */
+export declare const PING = "ping";
+export declare const PONG = "pong";
+/** text の更新で、`before.text` がサーバーの現在値と違ったときの `reject` の `reason` */
+export declare const REASON_TEXT_CONFLICT = "text conflict";
+/** ブラウザ → サーバー */
+export type ClientMsg = 
+/**
+ * `epoch` は、前に受け取ったスナップショットの値（あれば）。サーバーの今の値と違えば、
+ * ページが削除されたか作り直されているので、サーバーは CLOSE_PAGE_DELETED で閉じる
+ */
+{
+    type: 'hello';
+    clientId: string;
+    lastSeq?: number;
+    epoch?: string;
+} | {
+    type: 'ops';
+    opId: string;
+    deltas: HistoryDelta[];
+};
+/** 確定した変更。送信元も含めた全員に配信する */
+export interface OpsMsg {
+    type: 'ops';
+    seq: number;
+    actor: string;
+    clientId: string;
+    opId: string;
+    /**
+     * 操作を記録した時刻（UNIX ミリ秒）。付箋ごとの付加情報（src/shared/note-info.ts）の更新に使う。
+     * 配信と、再接続のときの差分に付く。配信しなかった結果を送信元にだけ返すとき（再送への応答、
+     * デルタをすべて捨てた操作）には付かない
+     */
+    createdAt?: number;
+    /** サーバーが実際に適用したデルタ。送信元は自分の opId のものを適用しない */
+    deltas: HistoryDelta[];
+    summary?: string;
+    /**
+     * この操作が取り消しなら、取り消した対象の seq。取り消しは HTTP の API か MCP から行われ、
+     * 要求元のブラウザも手元には適用していない。自分の clientId の操作でも、これがあれば適用する
+     */
+    reverts?: number;
+    /** 送信元にだけ付く。サーバーが変えた分で、送信元はこれだけを適用する */
+    fixups?: HistoryDelta[];
+}
+/** サーバー → ブラウザ */
+export type ServerMsg = ({
+    type: 'snapshot';
+} & Snapshot) | OpsMsg
+/** 表示名か、ページの色が変わった。付箋の変更ではないので seq は進まない */
+ | {
+    type: 'meta';
+    title: string | null;
+    color: string | null;
+    epoch: string | null;
+}
+/**
+ * 操作を受け付けなかった。送信元は手元の変更を巻き戻し、`fixups`（サーバーの現在値に
+ * 合わせるためのデルタ。text が競合した付箋など）を適用する
+ */
+ | {
+    type: 'reject';
+    opId: string;
+    reason: string;
+    fixups?: HistoryDelta[];
+};

package/dist/lib/shared/protocol.js

@@ -0,0 +1,12 @@
+/** 認証の期限が切れた接続を、サーバーが閉じるときのコード。クライアントは再読み込みして認証し直す */
+export const CLOSE_AUTH_EXPIRED = 4401;
+/**
+ * ページが削除されたときに、サーバーが接続を閉じるコード。クライアントは再接続しない
+ * （再接続すると、手元の未確定の操作でページが作り直されてしまう）
+ */
+export const CLOSE_PAGE_DELETED = 4410;
+/** 接続維持のためにクライアントが送る文字列と、サーバーの応答（JSON ではない） */
+export const PING = 'ping';
+export const PONG = 'pong';
+/** text の更新で、`before.text` がサーバーの現在値と違ったときの `reject` の `reason` */
+export const REASON_TEXT_CONFLICT = 'text conflict';

package/dist/lib/shared/site.d.ts

@@ -0,0 +1,16 @@
+import { type Lang } from './i18n';
+export interface SiteConfig {
+    /** 画面に出すサイトの名前（一覧の見出しと、タブの表示名） */
+    siteName: string;
+    /** Cookie もブラウザの言語も、対応する言語に当たらないときの言語 */
+    defaultLang: Lang;
+}
+/** 設定を省いたときの値 */
+export declare const DEFAULT_SITE: SiteConfig;
+/** index.html の `<head>` に入れる `<meta>` の名前。`content` は SiteConfig の JSON */
+export declare const SITE_META_NAME = "wema-kake-site";
+/**
+ * `<meta>` の `content` を読む。読めない値や欠けた項目は、既定の値にする（Worker を通らずに
+ * 配られた index.html でも、画面が動くようにする）
+ */
+export declare function parseSiteConfig(content: string | null | undefined): SiteConfig;

package/dist/lib/shared/site.js

@@ -0,0 +1,28 @@
+// サイトの設定のうち、画面が使うもの。Worker が index.html に埋め込み、画面が読み込み時に読む。
+//
+// 画面の言語は、スクリプトを読み込んだときに同期で決める（src/web/i18n/index.ts）。API で
+// 問い合わせる形だと、その応答を待つまで文言を決められないので、HTML に入れて渡す。
+import { DEFAULT_LANG, isLang } from './i18n';
+/** 設定を省いたときの値 */
+export const DEFAULT_SITE = { siteName: 'wema-kake', defaultLang: DEFAULT_LANG };
+/** index.html の `<head>` に入れる `<meta>` の名前。`content` は SiteConfig の JSON */
+export const SITE_META_NAME = 'wema-kake-site';
+/**
+ * `<meta>` の `content` を読む。読めない値や欠けた項目は、既定の値にする（Worker を通らずに
+ * 配られた index.html でも、画面が動くようにする）
+ */
+export function parseSiteConfig(content) {
+    let value = {};
+    try {
+        const parsed = JSON.parse(content ?? '');
+        if (parsed && typeof parsed === 'object')
+            value = parsed;
+    }
+    catch {
+        // 下で既定の値にする
+    }
+    return {
+        siteName: typeof value.siteName === 'string' && value.siteName !== '' ? value.siteName : DEFAULT_SITE.siteName,
+        defaultLang: typeof value.defaultLang === 'string' && isLang(value.defaultLang) ? value.defaultLang : DEFAULT_SITE.defaultLang,
+    };
+}

package/dist/lib/shared/slug.d.ts

@@ -0,0 +1,4 @@
+/** スラッグの形（正規表現の中身）。小文字の英数字とハイフンで、64 文字まで */
+export declare const SLUG_PATTERN = "[a-z0-9][a-z0-9-]{0,63}";
+export declare const SLUG_RE: RegExp;
+export declare function isValidSlug(slug: string): boolean;

package/dist/lib/shared/slug.js

@@ -0,0 +1,6 @@
+/** スラッグの形（正規表現の中身）。小文字の英数字とハイフンで、64 文字まで */
+export const SLUG_PATTERN = '[a-z0-9][a-z0-9-]{0,63}';
+export const SLUG_RE = new RegExp(`^${SLUG_PATTERN}$`);
+export function isValidSlug(slug) {
+    return SLUG_RE.test(slug);
+}

package/dist/lib/shared/tools.d.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import { type OpSummary, type RevertOutcome } from './api';
+import type { HistoryDelta, WemaEdge, WemaNote } from './delta';
+/** ツールが入力や状態の問題で実行できなかった。メッセージは LLM に返す */
+export declare class ToolError extends Error {
+}
+export interface PageInfo {
+    name: string;
+    title: string | null;
+    note_count: number;
+    updated_at: number;
+    /** 親ページのスラッグ。ルートのページ（どのページの子でもない）なら null */
+    parent: string | null;
+}
+type AuthoredNote = WemaNote & {
+    createdBy: string | null;
+};
+export interface BoardState {
+    title: string | null;
+    notes: AuthoredNote[];
+    edges: WemaEdge[];
+}
+export type ApplyOutcome = 
+/** `seq` は記録した操作の番号。何も変わらなかった（値が同じ、対象がもうない）なら null */
+{
+    ok: true;
+    seq: number | null;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface BoardAccess {
+    listPages(options: {
+        updatedAfter?: number;
+        limit?: number;
+    }): Promise<PageInfo[]>;
+    searchPages(query: string): Promise<{
+        name: string;
+        title: string | null;
+        parent: string | null;
+        snippet?: string;
+    }[]>;
+    /** ページがまだ作られていなければ null */
+    readBoard(page: string): Promise<BoardState | null>;
+    /** 付箋の text（HTML）をプレーンテキストにする */
+    plainText(html: string): Promise<string>;
+    /**
+     * デルタを 1 つの操作として適用する。`summary` は履歴に出る説明。
+     * ページがなければ適用せず、`ok: false` を返すこと（ツールはページを作らない）
+     */
+    apply(page: string, deltas: HistoryDelta[], summary: string): Promise<ApplyOutcome>;
+    /** 自分（この agent）の最近の操作 */
+    ownOps(page: string): Promise<OpSummary[]>;
+    /** 自分の操作を取り消す */
+    revert(page: string, seq: number, summary: string): Promise<RevertOutcome>;
+}
+/** ツール 1 つ。`input` は入力のスキーマ、`run` は BoardAccess を使った実装 */
+export interface Tool<S extends z.ZodType = z.ZodType> {
+    name: string;
+    description: string;
+    input: S;
+    /** ボードを変更しないか */
+    readOnly: boolean;
+    run(access: BoardAccess, input: z.infer<S>): Promise<unknown>;
+}
+export declare const TOOLS: Tool[];
+export {};

package/dist/lib/shared/tools.js

@@ -0,0 +1,353 @@
+// LLM に公開するツールの定義と実装。
+//
+// 実装は BoardAccess（ボードを読む、デルタを適用する、取り消す）越しに書いてある。リモート MCP では
+// サーバー版（ページの DO と D1 を呼ぶ）を渡す。WebMCP を足すときは、ブラウザ版（wema の API を呼ぶ）を
+// 渡せば、同じツールがそのまま使える。
+import { computeAutoLayout } from '@kanf/wema';
+import { z } from 'zod';
+import { MAX_LIST_LIMIT, MAX_QUERY_LENGTH } from './api';
+import { childPageOf } from './hierarchy';
+import { textToHtml } from './note-text';
+import { SLUG_RE } from './slug';
+/** ツールが入力や状態の問題で実行できなかった。メッセージは LLM に返す */
+export class ToolError extends Error {
+}
+const NOTE_WIDTH = 200;
+const NOTE_HEIGHT = 150;
+const NOTE_COLOR = '#FFF9C4';
+const GAP = 40;
+const MAX_ITEMS = 200;
+const page = z
+    .string()
+    .regex(SLUG_RE)
+    .describe('ページのスラッグ（list_pages の name）');
+const reason = z
+    .string()
+    .max(200)
+    .optional()
+    .describe('この操作の説明。操作の履歴に表示され、人が取り消すかどうかの判断に使う');
+const noteText = z
+    .string()
+    .max(20_000)
+    .describe('付箋の本文（プレーンテキスト）。改行できる。"- " で始まる行は箇条書き、"- [ ] " / "- [x] " で始まる行はチェックリストになる。[[スラッグ]] と書くと、そのページへのリンクになる（read_board の本文にも、ページへのリンクは同じ書式で出る）。外部のページへは、URL（http:// か https://）をそのまま書くと、その URL を文字にしたリンクになる。リンクの文字は変えられないので、何のリンクかは URL の前後に文で書く。URL の直後の句読点（. , ; : ! ?）は、URL に含めない。HTML と Markdown のリンク（[文字](URL)）は書けない');
+const color = z
+    .string()
+    .regex(/^#[0-9a-fA-F]{6}$/)
+    .describe('付箋の色（#RRGGBB）。分類に使う');
+/** 付箋の幅と高さ */
+const noteSize = z.number().min(40).max(2000);
+const overlaps = (a, b) => a.x < b.x + b.width + GAP / 2 &&
+    b.x < a.x + a.width + GAP / 2 &&
+    a.y < b.y + b.height + GAP / 2 &&
+    b.y < a.y + a.height + GAP / 2;
+/** 本文の量から、付箋の高さを見積もる（サーバーでは実際の描画の大きさを測れない） */
+function estimateHeight(text, width) {
+    // 1 行に入る文字数は、幅に比例する（幅 200 で、全角 13 文字ほど）
+    const perLine = Math.max(1, Math.floor((13 * width) / NOTE_WIDTH));
+    const lines = text.split('\n').reduce((sum, line) => sum + Math.max(1, Math.ceil(line.length / perLine)), 0);
+    return Math.min(Math.max(NOTE_HEIGHT, 40 + lines * 22), 500);
+}
+/** 置き場所を決める。`near` があればその右、なければ既存の付箋の下。重なる間は下へずらす */
+function placeNote(size, near, taken) {
+    const rect = near
+        ? { ...size, x: near.x + near.width + GAP, y: near.y }
+        : { ...size, x: GAP, y: taken.reduce((bottom, r) => Math.max(bottom, r.y + r.height), 0) + GAP };
+    // 重なった付箋の下まで、一度にずらす
+    for (let hit = taken.find((r) => overlaps(rect, r)); hit; hit = taken.find((r) => overlaps(rect, r))) {
+        rect.y = hit.y + hit.height + GAP;
+    }
+    return rect;
+}
+async function existingBoard(access, slug) {
+    const board = await access.readBoard(slug);
+    // ページの作成はツールでは行わない（人が画面から作る）
+    if (!board)
+        throw new ToolError(`page not found: ${slug}`);
+    return { ...board, notesById: new Map(board.notes.map((n) => [n.id, n])) };
+}
+async function applyOrThrow(access, slug, deltas, summary) {
+    if (deltas.length === 0)
+        throw new ToolError('nothing to change');
+    const result = await access.apply(slug, deltas, summary);
+    if (!result.ok)
+        throw new ToolError(result.reason);
+    // 操作として記録されていないので、返せる番号がない（別の操作の番号を返すと、取り消しで事故になる）
+    if (result.seq === null) {
+        throw new ToolError('nothing changed: the board already has these values, or the targets no longer exist');
+    }
+    return result.seq;
+}
+/** 同じ id を 2 回指定していたら断る（2 件目が、1 件目の結果と食い違って拒否されるため） */
+function assertUnique(ids) {
+    const seen = new Set();
+    for (const id of ids) {
+        if (seen.has(id))
+            throw new ToolError(`duplicate id: ${id}`);
+        seen.add(id);
+    }
+}
+const summaryOf = (tool, why) => (why ? `${tool}: ${why}` : tool);
+function findNote(board, id) {
+    const note = board.notesById.get(id);
+    if (!note)
+        throw new ToolError(`note not found: ${id}`);
+    return note;
+}
+const tool = (definition) => definition;
+const ARROW = { fromAnchor: 'auto', toAnchor: 'auto', style: 'arrow' };
+export const TOOLS = [
+    tool({
+        name: 'list_pages',
+        description: 'ページの一覧（名前、表示名、付箋の数、更新日時、親ページ）を、更新の新しい順に返す。updated_at は ISO 8601（UTC）の日時。ページは階層になっていて、parent は親ページの名前（ルートのページなら null）。',
+        readOnly: true,
+        input: z.object({
+            updated_after: z
+                .union([z.iso.datetime({ offset: true }), z.iso.date()])
+                .optional()
+                .describe('この日時より後に更新されたページだけを返す。ISO 8601 の日時（updated_at と同じ書式）か、日付だけ（その日の UTC の 0 時）'),
+            limit: z.number().int().min(1).max(MAX_LIST_LIMIT).optional(),
+        }),
+        async run(access, input) {
+            const updatedAfter = input.updated_after === undefined ? undefined : Date.parse(input.updated_after);
+            const pages = await access.listPages({ updatedAfter, limit: input.limit });
+            // 日時は、数値（UNIX ミリ秒）のままだと読み違えやすいので、文字列にして返す
+            return pages.map((p) => ({ ...p, updated_at: new Date(p.updated_at).toISOString() }));
+        },
+    }),
+    tool({
+        name: 'search_pages',
+        description: 'ページを全文検索する（表示名と付箋の本文）。parent は親ページの名前（ルートのページなら null）。',
+        readOnly: true,
+        input: z.object({ query: z.string().min(1).max(MAX_QUERY_LENGTH) }),
+        run: (access, input) => access.searchPages(input.query),
+    }),
+    tool({
+        name: 'read_board',
+        description: '1 ページの付箋（id、本文、座標、大きさ、色、作成者）と接続線（id、from、to、label）を返す。座標は左上が原点で、単位はピクセル。child_page のある付箋は、子ページを表す付箋で、値は子ページの名前（中身は、その名前で read_board を呼ぶと読める）。',
+        readOnly: true,
+        input: z.object({ page }),
+        async run(access, input) {
+            const board = await existingBoard(access, input.page);
+            return {
+                title: board.title,
+                notes: await Promise.all(board.notes.map(async (n) => ({
+                    id: n.id,
+                    text: await access.plainText(n.text),
+                    x: n.x,
+                    y: n.y,
+                    width: n.width,
+                    height: n.height,
+                    color: n.color,
+                    created_by: n.createdBy,
+                    // 子ページの付箋だけに付ける
+                    child_page: childPageOf(n),
+                }))),
+                edges: board.edges.map((e) => ({ id: e.id, from: e.from, to: e.to, label: e.label })),
+            };
+        },
+    }),
+    tool({
+        name: 'add_notes',
+        description: `付箋を追加する。位置を省略すると、near で指定した付箋の右（なければ既存の付箋の下）に、重ならないように置く。大きさを省略すると、幅は ${NOTE_WIDTH}、高さは本文の量に合わせて自動で決まる（長い本文でも、ふつうは指定しなくてよい）。connect_from を指定すると、その付箋から新しい付箋へ接続線を引く。`,
+        readOnly: false,
+        input: z.object({
+            page,
+            notes: z
+                .array(z.object({
+                text: noteText,
+                x: z.number().optional(),
+                y: z.number().optional(),
+                color: color.optional(),
+                width: noteSize.optional().describe(`付箋の幅。省略すると ${NOTE_WIDTH}`),
+                height: noteSize
+                    .optional()
+                    .describe('付箋の高さ。省略すると、本文の量と幅に合わせて自動で決まる'),
+                near: z.string().optional().describe('この id の付箋の近くに置く'),
+                connect_from: z.string().optional().describe('この id の付箋から、新しい付箋へ接続線を引く'),
+            }))
+                .min(1)
+                .max(MAX_ITEMS),
+            reason,
+        }),
+        async run(access, input) {
+            const board = await existingBoard(access, input.page);
+            const taken = [...board.notes];
+            const deltas = [];
+            const ids = [];
+            for (const spec of input.notes) {
+                const anchor = spec.near ?? spec.connect_from;
+                const near = anchor === undefined ? undefined : findNote(board, anchor);
+                const noteWidth = spec.width ?? NOTE_WIDTH;
+                const size = { width: noteWidth, height: spec.height ?? estimateHeight(spec.text, noteWidth) };
+                if ((spec.x === undefined) !== (spec.y === undefined)) {
+                    throw new ToolError('x and y must be given together (or both omitted for automatic placement)');
+                }
+                const rect = spec.x !== undefined && spec.y !== undefined
+                    ? { ...size, x: spec.x, y: spec.y }
+                    : placeNote(size, near, taken);
+                taken.push(rect);
+                const id = crypto.randomUUID();
+                ids.push(id);
+                deltas.push({
+                    type: 'note:create',
+                    note: { id, ...rect, text: textToHtml(spec.text), color: spec.color ?? NOTE_COLOR, zIndex: 1 },
+                });
+                if (spec.connect_from !== undefined) {
+                    findNote(board, spec.connect_from);
+                    deltas.push({
+                        type: 'edge:create',
+                        edge: { id: crypto.randomUUID(), from: spec.connect_from, to: id, ...ARROW },
+                    });
+                }
+            }
+            const seq = await applyOrThrow(access, input.page, deltas, summaryOf('add_notes', input.reason));
+            return { operation: seq, note_ids: ids };
+        },
+    }),
+    tool({
+        name: 'update_notes',
+        description: '付箋の本文、色、位置、大きさを変更する。指定した項目だけが変わる。',
+        readOnly: false,
+        input: z.object({
+            page,
+            notes: z
+                .array(z.object({
+                id: z.string(),
+                text: noteText.optional(),
+                color: color.optional(),
+                x: z.number().optional(),
+                y: z.number().optional(),
+                width: noteSize.optional(),
+                height: noteSize.optional(),
+            }))
+                .min(1)
+                .max(MAX_ITEMS),
+            reason,
+        }),
+        async run(access, input) {
+            const board = await existingBoard(access, input.page);
+            assertUnique(input.notes.map((n) => n.id));
+            const deltas = input.notes.map(({ id, text, ...rest }) => {
+                const note = findNote(board, id);
+                const after = { ...rest };
+                // text の更新には、読んだ時点の text を添える（その後に誰かが編集していたら拒否される）
+                const before = {};
+                if (text !== undefined) {
+                    before.text = note.text;
+                    after.text = textToHtml(text);
+                }
+                return { type: 'note:update', noteId: id, before, after };
+            });
+            const seq = await applyOrThrow(access, input.page, deltas, summaryOf('update_notes', input.reason));
+            return { operation: seq };
+        },
+    }),
+    tool({
+        name: 'delete_notes',
+        description: '付箋を削除する。その付箋につながる接続線も削除される。',
+        readOnly: false,
+        input: z.object({ page, note_ids: z.array(z.string()).min(1).max(MAX_ITEMS), reason }),
+        async run(access, input) {
+            const board = await existingBoard(access, input.page);
+            assertUnique(input.note_ids);
+            const deltas = input.note_ids.map((id) => ({ type: 'note:delete', note: findNote(board, id) }));
+            const seq = await applyOrThrow(access, input.page, deltas, summaryOf('delete_notes', input.reason));
+            return { operation: seq };
+        },
+    }),
+    tool({
+        name: 'connect_notes',
+        description: '付箋同士を接続線（矢印）でつなぐ。ラベルを付けられる。',
+        readOnly: false,
+        input: z.object({
+            page,
+            connections: z
+                .array(z.object({ from: z.string(), to: z.string(), label: z.string().max(200).optional() }))
+                .min(1)
+                .max(MAX_ITEMS),
+            reason,
+        }),
+        async run(access, input) {
+            const board = await existingBoard(access, input.page);
+            const ids = [];
+            const deltas = input.connections.map(({ from, to, label }) => {
+                findNote(board, from);
+                findNote(board, to);
+                const id = crypto.randomUUID();
+                ids.push(id);
+                const edge = { id, from, to, ...ARROW };
+                if (label)
+                    edge.label = label;
+                return { type: 'edge:create', edge };
+            });
+            const seq = await applyOrThrow(access, input.page, deltas, summaryOf('connect_notes', input.reason));
+            return { operation: seq, edge_ids: ids };
+        },
+    }),
+    tool({
+        name: 'disconnect_notes',
+        description: '接続線を削除する。',
+        readOnly: false,
+        input: z.object({ page, edge_ids: z.array(z.string()).min(1).max(MAX_ITEMS), reason }),
+        async run(access, input) {
+            const board = await existingBoard(access, input.page);
+            const deltas = input.edge_ids.map((id) => {
+                const edge = board.edges.find((e) => e.id === id);
+                if (!edge)
+                    throw new ToolError(`edge not found: ${id}`);
+                return { type: 'edge:delete', edge };
+            });
+            const seq = await applyOrThrow(access, input.page, deltas, summaryOf('disconnect_notes', input.reason));
+            return { operation: seq };
+        },
+    }),
+    tool({
+        name: 'auto_layout',
+        description: '接続線のつながりに基づいて、付箋を階層に並べ直す。note_ids を省略すると、ページの全付箋が対象になる。1 回で動かせる付箋は 2000 枚まで（超える場合は note_ids で対象を絞る）。',
+        readOnly: false,
+        input: z.object({ page, note_ids: z.array(z.string()).max(2000).optional(), reason }),
+        async run(access, input) {
+            const board = await existingBoard(access, input.page);
+            input.note_ids?.forEach((id) => findNote(board, id));
+            const positions = computeAutoLayout(board.notes, board.edges, { noteIds: input.note_ids });
+            const deltas = [];
+            for (const { id, x, y } of positions) {
+                const note = findNote(board, id);
+                if (note.x === x && note.y === y)
+                    continue;
+                deltas.push({ type: 'note:update', noteId: id, before: { x: note.x, y: note.y }, after: { x, y } });
+            }
+            const seq = await applyOrThrow(access, input.page, deltas, summaryOf('auto_layout', input.reason));
+            return { operation: seq, moved: deltas.length };
+        },
+    }),
+    tool({
+        name: 'revert_operation',
+        description: '自分が行った操作を取り消す。operation を省略すると、まだ取り消していない直前の操作が対象になる。その後に人が変更した付箋は戻さず、skipped で返す。何も戻せなかった場合（applied が 0）は、それより前の自分の操作の番号を earlier_operations で返すので、必要なら operation に指定して呼び直す。',
+        readOnly: false,
+        input: z.object({
+            page,
+            operation: z.number().int().optional().describe('取り消す操作の番号（各ツールが返す operation）'),
+            reason,
+        }),
+        async run(access, input) {
+            // ページの存在は確かめない（ページがなければ、操作の一覧が空で、取り消しも断られる）
+            let seq = input.operation;
+            let earlier = [];
+            if (seq === undefined) {
+                // 取り消しそのもの（reverts がある）と、取り消し済みのものは対象にしない
+                const candidates = (await access.ownOps(input.page))
+                    .filter((op) => op.revertedBy === null && op.reverts === null)
+                    .map((op) => op.seq);
+                if (candidates.length === 0)
+                    throw new ToolError('no operation to revert');
+                [seq, ...earlier] = candidates;
+            }
+            const outcome = await access.revert(input.page, seq, summaryOf('revert_operation', input.reason));
+            const result = { reverted: seq, operation: outcome.seq, applied: outcome.applied, skipped: outcome.skipped };
+            // 何も戻せなかった操作は取り消し済みにならず、省略時にまた選ばれる。それより前の操作を
+            // 取り消したいときに番号を指定できるよう、候補を返す
+            return outcome.applied === 0 && earlier.length > 0 ? { ...result, earlier_operations: earlier } : result;
+        },
+    }),
+];