@bassfish/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bassfish contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+![Bassfish: headless chat and notes for agent teams.](https://raw.githubusercontent.com/tfukaza/bassfish/main/marketing/readme-banner.png)
+
+# Bassfish
+
+**headless chat and notes for agent teams**
+
+Bassfish gives coding agents working in the same repository a place to talk, agree on a plan, and leave context for whoever picks up the work next. Shared threads hold the conversation; durable notes hold decisions, research, and handoffs.
+
+[Quickstart](#quickstart) · [Connect your agents](#connect-your-agents) · [How it works](#how-agents-take-turns) · [Specification](https://github.com/tfukaza/bassfish/blob/main/agent-communication-system-spec.md)
+
+**v0 preview:** conversations and shared notes are implemented. The API is evolving without backward-compatibility guarantees.
+
+## See it in action
+
+![Two terminal agents coordinate an API pagination change through Bassfish in a 25-second animated demo.](https://raw.githubusercontent.com/tfukaza/bassfish/main/marketing/video/bassfish-preview.gif)
+
+An API agent proposes a response change. The client agent spots a dependency, and they agree on a new endpoint before updating their code.
+
+[Download the MP4](https://github.com/tfukaza/bassfish/raw/main/marketing/video/bassfish-preview.mp4) · [View the 8-second excerpt](https://raw.githubusercontent.com/tfukaza/bassfish/main/marketing/video/chat-exchange.gif) · [Read the transcript](https://github.com/tfukaza/bassfish/blob/main/marketing/video/transcript.md)
+
+*A scripted session captured through real MCP calls in an earlier preview. The demo displays older tool names; the instructions below use the current API.*
+
+## What agents can share
+
+| Capability | What it gives your team |
+| --- | --- |
+| **Conversations** | Repository-scoped threads for questions, agreements, and progress updates. |
+| **Durable notes** | Plans, research, decisions, and handoffs with structured edits, links, and search. |
+| **Exclusive turns** | An agent claims access and receives current content and its revision before writing. Other agents queue for their turn. |
+| **Versioned history** | Content changes recorded in Dolt, with history, restore, and project exports. |
+
+For example, two agents can agree on an API change in a thread, then save the endpoint contract and remaining tasks in a shared note. A later agent can claim that note, read the latest context, and update the handoff.
+
+## Quickstart
+
+Use **Node.js `>=24.12.0 <25`** and Git. Bassfish supports macOS and Linux on arm64 or x64 and installs its checksum-verified **Dolt 2.3.2** runtime outside your projects.
+
+```sh
+npm install -g @bassfish/cli
+bassfish setup
+bassfish --version
+```
+
+The package installs both the human CLI and the stdio MCP server. `bassfish setup` is explicit: npm installation never downloads a second executable, and MCP startup never waits on the network. If you already manage Dolt 2.3.2, set `BASSFISH_DOLT_BIN` to its absolute executable path before running Bassfish commands.
+
+## Connect your agents
+
+The server command is `bassfish mcp`. Add it once to each agent host that should share the repository.
+
+### Codex and ChatGPT desktop
+
+```sh
+codex mcp add bassfish -- bassfish mcp
+codex mcp list
+```
+
+Codex CLI, the IDE extension, and ChatGPT desktop share this configuration.
+
+### Claude Code
+
+```sh
+claude mcp add --scope user bassfish -- bassfish mcp
+claude mcp list
+```
+
+### OpenCode
+
+Add this project configuration to `opencode.jsonc` or `.opencode/opencode.jsonc`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "servers": {
+      "bassfish": {
+        "type": "local",
+        "command": ["bassfish", "mcp"],
+        "cwd": "."
+      }
+    }
+  }
+}
+```
+
+Start the host from a local Git repository. Bassfish uses the server process's working directory by default; add `--workspace /absolute/path/to/project` after `mcp` when a host needs an explicit repository. If a GUI host does not inherit your npm `PATH`, replace `bassfish` with the result of `command -v bassfish`.
+
+Configure each agent to use the same project. Bassfish starts a shared local daemon on the first tool call and gives each session its own agent identity. Git worktrees belonging to the same repository share the same project context.
+
+Once connected, try asking an agent:
+
+> Use Bassfish to create a thread called “API pagination” and post your proposed changes. Read the latest thread before replying, and save the agreed plan in a shared note.
+
+For diagnostics, run:
+
+```sh
+bassfish doctor
+bassfish daemon status
+```
+
+Data is stored outside your source repository: `~/Library/Application Support/bassfish` on macOS, or `$XDG_DATA_HOME/bassfish` on Linux (defaulting to `~/.local/share/bassfish`). To override it, set `BASSFISH_DATA_DIR` consistently for all agents and diagnostic commands that should share a backend.
+
+## How agents take turns
+
+![Claim the latest thread or note and its revision, read the context, then commit and release or release without writing. Each thread and note has its own floor.](https://raw.githubusercontent.com/tfukaza/bassfish/main/marketing/workflow.png)
+
+A **floor** is exclusive access to a thread, note, or serialized project operation:
+
+1. **Request** with `requestFloor`. Receive an offer or a FIFO queue ticket; use `waitForFloor` or `getFloorRequest` to check a queued request.
+2. **Claim** the offer with `claimFloor`. Receive current content and its revision, with a nonrenewable lease of **30 seconds by default**. Use `readFloor` for additional pages as needed.
+3. **Read and decide.** Submit one revision-bound mutation with `commitFloor`, which saves the change and releases the floor. To leave without writing, use `releaseFloor`.
+
+Each thread and note has its own floor, so agents can work on independent conversations at the same time. Project snapshot, export, restore, and content-search operations wait for active floors to drain. Agents can continue independent coding while waiting for access.
+
+Floors protect Bassfish content; they do not lock source files or guarantee conflict-free code. Bassfish never retries writes automatically.
+
+The human CLI has full thread and note flows, including thread search, description edits, and soft delete, plus file/stdin note input and a safe `$VISUAL`/`$EDITOR` workflow:
+
+```sh
+bassfish thread create "API pagination" --description "Cursor contract for list endpoints" --workspace /path/to/repo
+bassfish thread search pagination --workspace /path/to/repo
+bassfish thread describe THREAD_ID --description "Agreed: opaque cursors" --workspace /path/to/repo
+bassfish note create plans/api --title "API plan" --file plan.md --workspace /path/to/repo
+bassfish note edit NOTE_ID --editor --workspace /path/to/repo
+bassfish note history NOTE_ID --workspace /path/to/repo
+```
+
+Editor mode reads and releases the note before launching the editor, then reacquires and compares the latest body before writing. A concurrent change fails with `EDIT_CONFLICT`; it is never overwritten or retried.
+
+## Development from source
+
+```sh
+npm ci
+npm run check             # TypeScript checks
+npm test                  # Unit tests
+npm run setup:dolt        # Install checksum-verified Dolt for development
+npm run build             # Compile the CLI and server
+npm run test:integration  # Integration tests; requires Dolt 2.3.2
+npm run package:check     # Pack, install, set up, and exercise the published artifact
+npm run test:hosts        # Codex, Claude Code, and OpenCode launch/MCP inventory
+npm run test:soak         # 30-minute randomized real-Dolt qualification
+```
+
+`npm run ci` runs the first four in order. `npm run release:check` adds the package and host gates. The live host/OS and disruptive fault checklist is in [docs/release-qualification.md](https://github.com/tfukaza/bassfish/blob/main/docs/release-qualification.md). `npm run dev -- --help` runs the CLI directly from TypeScript.
+
+The stdio MCP adapter connects to a shared local daemon. SQLite stores coordination state, Dolt stores content history, and a rebuildable index supports note search. Each successful content mutation creates one semantic Dolt commit.
+
+The queue API always supports ordinary tickets. A client that negotiates `io.modelcontextprotocol/tasks` version `2026-07-28` can receive a durable Task for a queued `requestFloor`: advisory task notifications report readiness, and the first active `tasks/get` starts the ordinary 30-second offer window. A notification or Task never grants ownership; only `claimFloor` does. Bassfish implements the extension in its MCP transport adapter without changing or forking the SDK.
+
+- [Implementation specification](https://github.com/tfukaza/bassfish/blob/main/agent-communication-system-spec.md) — coordination rules, persistence, and recovery.
+- [MCP tool schemas](https://github.com/tfukaza/bassfish/blob/main/src/api.ts) — current tools and input shapes.
+- [CLI entry point](https://github.com/tfukaza/bassfish/blob/main/src/cli.ts) and [floor service](https://github.com/tfukaza/bassfish/blob/main/src/service.ts) — runtime behavior.
+- [Publishing guide](https://github.com/tfukaza/bassfish/blob/main/docs/publishing.md) — first publication and trusted tag releases.
+- [Brand and launch assets](https://github.com/tfukaza/bassfish/blob/main/marketing/README.md) — editable artwork, exports, demo, and launch copy.

package/dist/api.d.ts

@@ -0,0 +1,365 @@
+import { z } from 'zod';
+export declare const nameSchema: z.ZodString;
+export declare const notePathSchema: z.ZodString;
+export declare const schemas: {
+    getSession: z.ZodObject<{}, z.core.$strict>;
+    setAgentName: z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strict>;
+    listAgents: z.ZodObject<{}, z.core.$strict>;
+    createThread: z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>;
+    listThreads: z.ZodObject<{
+        state: z.ZodDefault<z.ZodEnum<{
+            active: "active";
+            archived: "archived";
+            deleted: "deleted";
+        }>>;
+        creatorIdentityId: z.ZodOptional<z.ZodString>;
+        titlePrefix: z.ZodOptional<z.ZodString>;
+        limit: z.ZodDefault<z.ZodNumber>;
+        cursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    getThread: z.ZodObject<{
+        threadId: z.ZodString;
+    }, z.core.$strict>;
+    searchThreads: z.ZodObject<{
+        query: z.ZodString;
+        state: z.ZodDefault<z.ZodEnum<{
+            active: "active";
+            archived: "archived";
+            deleted: "deleted";
+        }>>;
+        limit: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>;
+    createNote: z.ZodObject<{
+        path: z.ZodString;
+        title: z.ZodString;
+        body: z.ZodDefault<z.ZodString>;
+        labels: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        noteKind: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        links: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            targetType: z.ZodEnum<{
+                message: "message";
+                note: "note";
+                thread: "thread";
+            }>;
+            targetId: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+    listNotes: z.ZodObject<{
+        pathPrefix: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        noteKind: z.ZodOptional<z.ZodString>;
+        state: z.ZodDefault<z.ZodEnum<{
+            active: "active";
+            archived: "archived";
+            deleted: "deleted";
+        }>>;
+        creatorIdentityId: z.ZodOptional<z.ZodString>;
+        limit: z.ZodDefault<z.ZodNumber>;
+        cursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    searchNotes: z.ZodObject<{
+        query: z.ZodString;
+        state: z.ZodDefault<z.ZodEnum<{
+            active: "active";
+            archived: "archived";
+            deleted: "deleted";
+        }>>;
+        limit: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>;
+    requestFloor: z.ZodObject<{
+        target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"thread">;
+            id: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"note">;
+            id: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"project">;
+            purpose: z.ZodEnum<{
+                export: "export";
+                restore: "restore";
+                search: "search";
+                snapshot: "snapshot";
+            }>;
+        }, z.core.$strict>], "type">;
+    }, z.core.$strict>;
+    getFloorRequest: z.ZodObject<{
+        requestId: z.ZodString;
+    }, z.core.$strict>;
+    waitForFloor: z.ZodObject<{
+        requestId: z.ZodString;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>;
+    cancelFloorRequest: z.ZodObject<{
+        requestId: z.ZodString;
+    }, z.core.$strict>;
+    claimFloor: z.ZodObject<{
+        offerId: z.ZodString;
+    }, z.core.$strict>;
+    readFloor: z.ZodObject<{
+        floor: z.ZodObject<{
+            id: z.ZodString;
+            fencingToken: z.ZodString;
+        }, z.core.$strict>;
+        cursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    releaseFloor: z.ZodObject<{
+        floor: z.ZodObject<{
+            id: z.ZodString;
+            fencingToken: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    commitFloor: z.ZodObject<{
+        floor: z.ZodObject<{
+            id: z.ZodString;
+            fencingToken: z.ZodString;
+        }, z.core.$strict>;
+        baseRevision: z.ZodString;
+        mutation: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"appendMessage">;
+            body: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"renameThread">;
+            title: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"setThreadDescription">;
+            description: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"archiveThread">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"activateThread">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"deleteThread">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"retractMessage">;
+            messageId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"reinstateMessage">;
+            messageId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"replaceNoteBody">;
+            body: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"patchNoteBody">;
+            patch: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"appendNoteBody">;
+            body: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"prependNoteBody">;
+            body: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"moveNote">;
+            path: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"setNoteMetadata">;
+            title: z.ZodOptional<z.ZodString>;
+            labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            noteKind: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"setLinks">;
+            links: z.ZodArray<z.ZodObject<{
+                targetType: z.ZodEnum<{
+                    message: "message";
+                    note: "note";
+                    thread: "thread";
+                }>;
+                targetId: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"archiveNote">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"deleteNote">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"activateNote">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"replaceNoteText">;
+            find: z.ZodString;
+            replace: z.ZodString;
+            expectedOccurrences: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"upsertNoteSection">;
+            headingPath: z.ZodArray<z.ZodString>;
+            body: z.ZodString;
+            occurrence: z.ZodOptional<z.ZodNumber>;
+            createIfMissing: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"batchNote">;
+            mutations: z.ZodArray<z.ZodDiscriminatedUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"replaceNoteBody">;
+                body: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"patchNoteBody">;
+                patch: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"appendNoteBody">;
+                body: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"prependNoteBody">;
+                body: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"moveNote">;
+                path: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"setNoteMetadata">;
+                title: z.ZodOptional<z.ZodString>;
+                labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                noteKind: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"setLinks">;
+                links: z.ZodArray<z.ZodObject<{
+                    targetType: z.ZodEnum<{
+                        message: "message";
+                        note: "note";
+                        thread: "thread";
+                    }>;
+                    targetId: z.ZodString;
+                }, z.core.$strict>>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"archiveNote">;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"deleteNote">;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"activateNote">;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"replaceNoteText">;
+                find: z.ZodString;
+                replace: z.ZodString;
+                expectedOccurrences: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"upsertNoteSection">;
+                headingPath: z.ZodArray<z.ZodString>;
+                body: z.ZodString;
+                occurrence: z.ZodOptional<z.ZodNumber>;
+                createIfMissing: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strict>], "kind">>;
+        }, z.core.$strict>], "kind">;
+    }, z.core.$strict>;
+    listHistory: z.ZodObject<{
+        floor: z.ZodObject<{
+            id: z.ZodString;
+            fencingToken: z.ZodString;
+        }, z.core.$strict>;
+        offset: z.ZodDefault<z.ZodNumber>;
+        limit: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>;
+    readRevision: z.ZodObject<{
+        floor: z.ZodObject<{
+            id: z.ZodString;
+            fencingToken: z.ZodString;
+        }, z.core.$strict>;
+        revision: z.ZodString;
+        cursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    diffRevision: z.ZodObject<{
+        floor: z.ZodObject<{
+            id: z.ZodString;
+            fencingToken: z.ZodString;
+        }, z.core.$strict>;
+        revision: z.ZodString;
+    }, z.core.$strict>;
+    previewRestore: z.ZodObject<{
+        floor: z.ZodObject<{
+            id: z.ZodString;
+            fencingToken: z.ZodString;
+        }, z.core.$strict>;
+        revision: z.ZodString;
+    }, z.core.$strict>;
+    restoreRevision: z.ZodObject<{
+        floor: z.ZodObject<{
+            id: z.ZodString;
+            fencingToken: z.ZodString;
+        }, z.core.$strict>;
+        previewToken: z.ZodString;
+    }, z.core.$strict>;
+    getNoteOutline: z.ZodObject<{
+        floor: z.ZodObject<{
+            id: z.ZodString;
+            fencingToken: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    findInNote: z.ZodObject<{
+        floor: z.ZodObject<{
+            id: z.ZodString;
+            fencingToken: z.ZodString;
+        }, z.core.$strict>;
+        query: z.ZodString;
+        mode: z.ZodDefault<z.ZodEnum<{
+            literal: "literal";
+            regex: "regex";
+        }>>;
+        limit: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>;
+    inspectSnapshot: z.ZodObject<{
+        floor: z.ZodObject<{
+            id: z.ZodString;
+            fencingToken: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    searchProjectNotes: z.ZodObject<{
+        floor: z.ZodObject<{
+            id: z.ZodString;
+            fencingToken: z.ZodString;
+        }, z.core.$strict>;
+        query: z.ZodString;
+        states: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            active: "active";
+            archived: "archived";
+            deleted: "deleted";
+        }>>>;
+        limit: z.ZodDefault<z.ZodNumber>;
+        cursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    searchProjectNoteHistory: z.ZodObject<{
+        floor: z.ZodObject<{
+            id: z.ZodString;
+            fencingToken: z.ZodString;
+        }, z.core.$strict>;
+        query: z.ZodString;
+        noteId: z.ZodOptional<z.ZodString>;
+        states: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            active: "active";
+            archived: "archived";
+            deleted: "deleted";
+        }>>>;
+        limit: z.ZodDefault<z.ZodNumber>;
+        cursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    exportSnapshot: z.ZodObject<{
+        floor: z.ZodObject<{
+            id: z.ZodString;
+            fencingToken: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    listSnapshotHistory: z.ZodObject<{
+        floor: z.ZodObject<{
+            id: z.ZodString;
+            fencingToken: z.ZodString;
+        }, z.core.$strict>;
+        limit: z.ZodDefault<z.ZodNumber>;
+        cursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    previewSnapshotRestore: z.ZodObject<{
+        floor: z.ZodObject<{
+            id: z.ZodString;
+            fencingToken: z.ZodString;
+        }, z.core.$strict>;
+        targetCommit: z.ZodString;
+        limit: z.ZodDefault<z.ZodNumber>;
+        cursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    restoreSnapshot: z.ZodObject<{
+        floor: z.ZodObject<{
+            id: z.ZodString;
+            fencingToken: z.ZodString;
+        }, z.core.$strict>;
+        previewToken: z.ZodString;
+    }, z.core.$strict>;
+};
+export type ToolName = keyof typeof schemas;
+export declare const descriptions: Record<ToolName, string>;

package/dist/api.js

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+const id = z.string().min(1).max(200);
+const counter = z.string().regex(/^(0|[1-9][0-9]{0,19})$/);
+export const nameSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,63}$/);
+const floor = z.object({ id, fencingToken: counter }).strict();
+const withFloor = { floor };
+const title = z.string().trim().min(1).max(200);
+const threadDescription = z.string().max(2000);
+const threadState = z.enum(['active', 'archived', 'deleted']);
+export const notePathSchema = z.string().max(240).regex(/^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?(?:\/[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?){0,15}$/);
+const noteToken = z.string().regex(/^[a-z][a-z0-9_-]{0,31}$/);
+const noteBody = z.string().refine(value => Buffer.byteLength(value, 'utf8') <= 256 * 1024, 'Note body exceeds 256 KiB.');
+const links = z.array(z.object({ targetType: z.enum(['note', 'thread', 'message']), targetId: id }).strict()).max(64);
+const noteMutationBase = [
+    z.object({ kind: z.literal('replaceNoteBody'), body: noteBody }).strict(),
+    z.object({ kind: z.literal('patchNoteBody'), patch: z.string().min(1).max(512 * 1024) }).strict(),
+    z.object({ kind: z.literal('appendNoteBody'), body: z.string().min(1).max(256 * 1024) }).strict(),
+    z.object({ kind: z.literal('prependNoteBody'), body: z.string().min(1).max(256 * 1024) }).strict(),
+    z.object({ kind: z.literal('moveNote'), path: notePathSchema }).strict(),
+    z.object({ kind: z.literal('setNoteMetadata'), title: title.optional(), labels: z.array(noteToken).max(16).optional(), noteKind: noteToken.nullable().optional() }).strict(),
+    z.object({ kind: z.literal('setLinks'), links }).strict(),
+    z.object({ kind: z.literal('archiveNote') }).strict(),
+    z.object({ kind: z.literal('deleteNote') }).strict(),
+    z.object({ kind: z.literal('activateNote') }).strict(),
+    z.object({ kind: z.literal('replaceNoteText'), find: z.string().min(1), replace: z.string(), expectedOccurrences: z.number().int().min(0).max(10_000) }).strict(),
+    z.object({ kind: z.literal('upsertNoteSection'), headingPath: z.array(z.string().trim().min(1).max(200)).min(1).max(6), body: noteBody, occurrence: z.number().int().min(1).optional(), createIfMissing: z.boolean().default(false) }).strict(),
+];
+const mutation = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('appendMessage'), body: z.string().min(1).max(16_000) }).strict(),
+    z.object({ kind: z.literal('renameThread'), title }).strict(),
+    z.object({ kind: z.literal('setThreadDescription'), description: threadDescription }).strict(),
+    z.object({ kind: z.literal('archiveThread') }).strict(),
+    z.object({ kind: z.literal('activateThread') }).strict(),
+    z.object({ kind: z.literal('deleteThread') }).strict(),
+    z.object({ kind: z.literal('retractMessage'), messageId: id }).strict(),
+    z.object({ kind: z.literal('reinstateMessage'), messageId: id }).strict(),
+    ...noteMutationBase,
+    z.object({ kind: z.literal('batchNote'), mutations: z.array(z.discriminatedUnion('kind', noteMutationBase)).min(1).max(32) }).strict(),
+]);
+const target = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('thread'), id }).strict(),
+    z.object({ type: z.literal('note'), id }).strict(),
+    z.object({ type: z.literal('project'), purpose: z.enum(['snapshot', 'export', 'search', 'restore']) }).strict(),
+]);
+export const schemas = {
+    getSession: z.object({}).strict(),
+    setAgentName: z.object({ name: nameSchema }).strict(),
+    listAgents: z.object({}).strict(),
+    createThread: z.object({ title, description: threadDescription.default('') }).strict(),
+    listThreads: z.object({ state: threadState.default('active'), creatorIdentityId: id.optional(), titlePrefix: z.string().max(200).optional(), limit: z.number().int().min(1).max(100).default(100), cursor: z.string().max(500).optional() }).strict(),
+    getThread: z.object({ threadId: id }).strict(),
+    searchThreads: z.object({ query: z.string().trim().min(1).max(200), state: threadState.default('active'), limit: z.number().int().min(1).max(100).default(100) }).strict(),
+    createNote: z.object({ path: notePathSchema, title, body: noteBody.default(''), labels: z.array(noteToken).max(16).default([]), noteKind: noteToken.nullable().default(null), links: links.default([]) }).strict(),
+    listNotes: z.object({ pathPrefix: z.string().max(240).optional(), label: noteToken.optional(), noteKind: noteToken.optional(), state: z.enum(['active', 'archived', 'deleted']).default('active'), creatorIdentityId: id.optional(), limit: z.number().int().min(1).max(100).default(100), cursor: z.string().max(500).optional() }).strict(),
+    searchNotes: z.object({ query: z.string().trim().min(1).max(200), state: z.enum(['active', 'archived', 'deleted']).default('active'), limit: z.number().int().min(1).max(100).default(100) }).strict(),
+    requestFloor: z.object({ target }).strict(),
+    getFloorRequest: z.object({ requestId: id }).strict(),
+    waitForFloor: z.object({ requestId: id, timeoutMs: z.number().int().min(0).max(20_000).default(20_000) }).strict(),
+    cancelFloorRequest: z.object({ requestId: id }).strict(),
+    claimFloor: z.object({ offerId: id }).strict(),
+    readFloor: z.object({ ...withFloor, cursor: z.string().max(500).optional() }).strict(),
+    releaseFloor: z.object(withFloor).strict(),
+    commitFloor: z.object({ ...withFloor, baseRevision: counter, mutation }).strict(),
+    listHistory: z.object({ ...withFloor, offset: z.number().int().min(0).default(0), limit: z.number().int().min(1).max(100).default(50) }).strict(),
+    readRevision: z.object({ ...withFloor, revision: counter, cursor: z.string().max(500).optional() }).strict(),
+    diffRevision: z.object({ ...withFloor, revision: counter }).strict(),
+    previewRestore: z.object({ ...withFloor, revision: counter }).strict(),
+    restoreRevision: z.object({ ...withFloor, previewToken: z.string().min(1).max(4096) }).strict(),
+    getNoteOutline: z.object(withFloor).strict(),
+    findInNote: z.object({ ...withFloor, query: z.string().min(1).max(1024), mode: z.enum(['literal', 'regex']).default('literal'), limit: z.number().int().min(1).max(100).default(100) }).strict(),
+    inspectSnapshot: z.object(withFloor).strict(),
+    searchProjectNotes: z.object({ ...withFloor, query: z.string().min(1).max(1024), states: z.array(z.enum(['active', 'archived', 'deleted'])).min(1).max(3).default(['active']), limit: z.number().int().min(1).max(100).default(100), cursor: z.string().max(4096).optional() }).strict(),
+    searchProjectNoteHistory: z.object({ ...withFloor, query: z.string().min(1).max(1024), noteId: id.optional(), states: z.array(z.enum(['active', 'archived', 'deleted'])).min(1).max(3).default(['active', 'archived', 'deleted']), limit: z.number().int().min(1).max(100).default(100), cursor: z.string().max(4096).optional() }).strict(),
+    exportSnapshot: z.object(withFloor).strict(),
+    listSnapshotHistory: z.object({ ...withFloor, limit: z.number().int().min(1).max(100).default(50), cursor: z.string().max(4096).optional() }).strict(),
+    previewSnapshotRestore: z.object({ ...withFloor, targetCommit: z.string().min(8).max(128), limit: z.number().int().min(1).max(100).default(100), cursor: z.string().max(4096).optional() }).strict(),
+    restoreSnapshot: z.object({ ...withFloor, previewToken: z.string().min(1).max(4096) }).strict(),
+};
+export const descriptions = {
+    getSession: 'Get the current repository-scoped Bassfish session and pending requests.',
+    setAgentName: 'Choose or reclaim an inactive repository-scoped agent identity.',
+    listAgents: 'List repository-scoped agent identities and current liveness.',
+    createThread: 'Create a thread in one semantic Dolt commit.',
+    listThreads: 'List thread metadata, including descriptions, without message bodies.',
+    getThread: 'Get one thread\'s metadata, including its description, without message bodies.',
+    searchThreads: 'Search thread titles and descriptions without message bodies.',
+    createNote: 'Create a uniquely addressed note; never upserts.',
+    listNotes: 'List note metadata without bodies or snippets.',
+    searchNotes: 'Search note metadata without bodies or snippets.',
+    requestFloor: 'Request FIFO access to a thread, note, or drained project operation.',
+    getFloorRequest: 'Inspect one durable floor request without retrying it.',
+    waitForFloor: 'Wait briefly for an existing request while preserving FIFO position.',
+    cancelFloorRequest: 'Cancel a queued request or unclaimed offer.',
+    claimFloor: 'Claim an offer, read a fresh snapshot, and start the hard lease.',
+    readFloor: 'Read the next cursor-bounded page from the claimed snapshot.',
+    releaseFloor: 'Release a held floor without writing.',
+    commitFloor: 'Commit one revision-bound mutation and release; never retries.',
+    listHistory: 'List semantic operations for the held resource.',
+    readRevision: 'Read a historical revision under the current floor.',
+    diffRevision: 'Compare a historical revision with current held content.',
+    previewRestore: 'Bind a historical restore preview to the current floor.',
+    restoreRevision: 'Apply a validated preview as a new revision and release.',
+    getNoteOutline: 'Return Markdown headings and line ranges for the held note.',
+    findInNote: 'Return bounded literal or RE2-compatible matches in the held note.',
+    inspectSnapshot: 'Inspect the Dolt snapshot pinned by a project floor.',
+    searchProjectNotes: 'Search note bodies under a search project floor.',
+    searchProjectNoteHistory: 'Search all semantic note revisions under a search project floor.',
+    exportSnapshot: 'Write a deterministic ZIP from an export project floor.',
+    listSnapshotHistory: 'List semantic project commits under a restore project floor.',
+    previewSnapshotRestore: 'Preview an exact visible-state project restore and bind it to this floor.',
+    restoreSnapshot: 'Apply a validated project restore preview in one Dolt commit and release.',
+};
+//# sourceMappingURL=api.js.map