@loicngr/kobo 1.11.39 → 1.11.41

package/AGENTS.md

@@ -4,9 +4,9 @@ Guidance for AI coding agents (Claude Code, Cursor, etc.) working on this reposi
 
 ## What this project is
 
-**Kōbō** (工房, Japanese for "workshop") orchestrates multiple Claude Code agents across isolated git worktrees. Each "workspace" is a self-contained mission with its own worktree, branch, Claude session, optional dev server, optional Notion source-of-truth, and a dedicated MCP tools server. A Vue 3 UI lets the human track progress, read live agent output, and manage the lifecycle.
+**Kōbō** (工房, Japanese for "workshop") orchestrates Claude Code and OpenAI Codex agents across isolated git worktrees. Each "workspace" is a self-contained mission with its own worktree, branch, agent sessions, optional dev server, optional Notion/Sentry context, and a dedicated MCP tools server. A Vue 3 UI lets the human track progress, read live agent output, review Git changes, and manage the lifecycle. A workspace can switch engines through a handoff to a fresh session while preserving its worktree and history.
 
-Single-user dev tool, local by default. The server binds `127.0.0.1` unless the opt-in "network access" setting is enabled, which binds all interfaces and gates non-loopback HTTP/WS requests behind a shared token (localhost always exempt). No multi-tenant concerns.
+Single-user dev tool, local by default. The server binds `127.0.0.1` unless the opt-in "network access" setting is enabled, which binds all interfaces and gates non-loopback API/WS requests behind a shared token. Behind-a-reverse-proxy mode also requires the token for loopback API/WS requests; `/api/health` stays exempt. Host/Origin checks apply separately. No multi-tenant concerns.
 
 ## Tech stack
 
@@ -16,9 +16,9 @@ Single-user dev tool, local by default. The server binds `127.0.0.1` unless the
 
 **Database**: a single SQLite file under the **Kōbō home directory** (`~/.config/kobo/kobo.db` by default, overridable via `KOBO_HOME`). Fresh-install schema lives in `src/server/db/schema.ts` (`initSchema`); incremental migrations live in `src/server/db/migrations.ts`. **The project is in production**, so every schema change MUST ship as a migration that preserves data, never as a breaking change to `initSchema` alone. See [Database migrations](#database-migrations) below.
 
-**Kōbō home directory**: `KOBO_HOME` env var overrides everything. Otherwise `$XDG_CONFIG_HOME/kobo/`, else `~/.config/kobo/`. Contains `kobo.db`, `settings.json`, `skills.json`, `templates.json`. **Development uses `./data/`** via the `KOBO_HOME=./data` prefix in the `dev` npm script, so local dev never touches your real `~/.config/kobo/` and can run in parallel with a production-installed Kōbō (`npx @loicngr/kobo`). See `src/server/utils/paths.ts`.
+**Kōbō home directory**: `KOBO_HOME` env var overrides everything. Otherwise `$XDG_CONFIG_HOME/kobo/`, else `~/.config/kobo/`. Contains `kobo.db`, `settings.json`, `skills.json`, `templates.json`, and `workspace-templates.json`. **Development uses `./data/`** via the `KOBO_HOME=./data` prefix in the `dev` npm script, so local dev never touches your real `~/.config/kobo/` and can run in parallel with a production-installed Kōbō (`npx @loicngr/kobo`). See `src/server/utils/paths.ts`.
 
-**Tests**: Vitest covers backend services/routes and frontend stores/pure utilities. Vue components are not unit-tested; type-checking and manual smoke tests cover their behavior. Run `npm test` and `(cd src/client && npm test)` for the complete suites.
+**Tests**: Vitest covers backend services/routes and frontend stores, utilities, composables, and selected Vue components. The client suite uses Vue Test Utils and `happy-dom`; type-checking and manual smoke tests complement it. `npm test` runs the backend suite only; `npm run test:all` runs both suites. The three dependency trees (root, client, PWA) have separate lockfiles.
 
 ## Commands
 
@@ -36,8 +36,12 @@ npm run dev:all                     # both concurrently
 # Check & test
 npm run lint                        # biome check (linting + formatting)
 npx tsc --noEmit                    # type check backend (the project's primary quality gate)
-npm test                            # run full vitest suite (backend + client tests)
-(cd src/client && npm test)         # client tests only (stores, utils)
+npm run typecheck:tests             # type check backend test fixtures and tests
+(cd src/client && npm run type-check) # vue-tsc: client + Vue components
+npm test                            # backend vitest suite
+(cd src/client && npm test)         # client stores, utilities, composables and components
+npm run test:all                    # backend + client suites
+make ci                            # install, audit, lint, type checks, build, both suites
 npm run test:watch                  # vitest in watch mode
 
 # Build & run
@@ -56,15 +60,15 @@ src/
 │   ├── db/
 │   │   ├── index.ts                # singleton getDb / closeDb
 │   │   ├── schema.ts               # initSchema — CREATE TABLE IF NOT EXISTS …
-│   │   └── migrations.ts           # incremental migrations, bumped per feature
+│   │   └── migrations.ts           # append-only migration registry + transactional runner
 │   ├── services/                   # business logic — pure functions over db + external processes
 │   │   ├── workspace-service.ts    # workspaces + tasks + agent_sessions CRUD
 │   │   ├── agent/                  # agent engine abstraction (replaces former agent-manager.ts)
 │   │   │   ├── orchestrator.ts     # per-workspace engine map, retry/quota handling, watchdog, public API
 │   │   │   ├── session-controller.ts # lifecycle wrapper around an AgentEngine instance
-│   │   │   ├── event-router.ts     # maps engine AgentEvent stream to WS emit + DB side-effects
+│   │   │   ├── event-router.ts     # persists/broadcasts normalized AgentEvent via WebSocket
 │   │   │   └── engines/{claude-code,codex}/ # per-engine adapters implementing the AgentEngine contract
-│   │   ├── forge/                  # ForgeProvider abstraction — github / gitlab / none, with registry + auto-resolve
+│   │   ├── forge/                  # github / gitlab / bitbucket-community / none, registry + auto-resolve
 │   │   ├── change-source-branch-service.ts # re-target a workspace onto a new source branch (built-in cherry-pick or custom bash)
 │   │   ├── git-stats-service.ts    # pure compute of commit/ahead-behind/diff stats + forge availability for a workspace
 │   │   ├── settings-defaults.ts    # DEFAULT_* constants for opt-in settings (e.g. change-source-branch script)
@@ -83,7 +87,8 @@ src/
 │   │   ├── workspaces.ts           # /api/workspaces/* — the main surface
 │   │   ├── templates.ts            # /api/templates — prompt templates CRUD
 │   │   ├── workspace-templates.ts  # /api/workspace-templates - saved create-form presets
-│   │   ├── plans.ts                # /api/workspaces/:id/plans — plan file browser (read-only)
+│   │   ├── documents.ts            # workspace plans, specs and thoughts browser (read-only)
+│   │   ├── mcp.ts                  # /api/mcp — external discovery and conversation tools
 │   │   ├── dev-server.ts, git.ts, notion.ts, settings.ts
 │   ├── utils/
 │   │   ├── git-ops.ts              # pushBranch, pullBranch, getCommitsBetween, delete{Local,Remote}Branch…
@@ -91,7 +96,7 @@ src/
 ├── client/                         # Vue 3 + Quasar PWA
 │   └── src/
 │       ├── stores/                 # pinia: workspace, websocket, settings, dev-server, templates
-│       ├── components/             # WorkspaceList, NotionPanel, AcceptancePanel, ChatInput, GitPanel, PlansPanel, WorkspaceAttentionLabels, HelpMenu…
+│       ├── components/             # WorkspaceList, AcceptancePanel, ChatInput, GitPanel, DocumentsPanel, WorkspaceAttentionLabels, HelpMenu…
 │       ├── utils/                  # expand-template, formatters, workspace-attention (CI failure / changes-requested derivation)…
 │       ├── tours/                  # declarative onboarding tours, one file per zone + registry
 │       ├── pages/                  # WorkspacePage, CreatePage, SettingsPage
@@ -99,7 +104,8 @@ src/
 ├── mcp-server/                     # standalone MCP server spawned per workspace
 │   ├── kobo-tasks-server.ts        # entrypoint, registers tools
 │   └── kobo-tasks-handlers.ts      # pure handlers (list_tasks, mark_task_done)
-└── __tests__/                      # vitest, one file per service/route
+├── shared/                         # model catalogues, prompts, dialogue contracts, shared utilities
+└── __tests__/                      # backend Vitest suites; client tests live under client/src/__tests__/
 ```
 
 ## Data model (SQLite)
@@ -110,7 +116,14 @@ src/
 | `tasks` | workspace sub-items: title, status, `is_acceptance_criterion`, sort_order; CASCADE DELETE on workspace |
 | `agent_sessions` | agent-engine sessions: pid where applicable, engine session id, status, timestamps, model, and name |
 | `ws_events` | persisted WebSocket events for replay on reconnect: type, payload, session_id, created_at |
-| `pending_wakeups` | one-row-per-workspace scheduler for the `ScheduleWakeup` tool: target_at (ISO UTC), prompt, reason; CASCADE DELETE on workspace |
+| `pending_wakeups` | one-row-per-workspace scheduler for the `schedule_wakeup` MCP tool: target_at (ISO UTC), prompt, reason; CASCADE DELETE on workspace |
+| `pending_quota_backoffs` | persisted quota retries and their attempt counts |
+| `pending_crons` | recurring workspace schedules and their next run |
+| `session_event_metrics` / `usage_snapshots` | session event counters and provider usage snapshots |
+| `workspace_activity` | significant lifecycle/PR events for the absence digest |
+| `search_*` | derived logical-message search index and indexing progress; see `search-schema.ts` |
+| `mcp_message_requests` | durable external-message idempotency ledger; independent of event retention |
+| `schema_migrations` | applied migration versions, names and timestamps |
 | `workspace_chat_history` | chat-input history per workspace: message text + `created_at`, ordered by autoincrement id, capped at 200 entries by the service; CASCADE DELETE on workspace |
 | `workspace_permission_rules` | remembered per-workspace tool approvals, scoped to an exact operation or every invocation of a tool; CASCADE DELETE on workspace |
 
@@ -132,8 +145,8 @@ src/
 
 ### The two files and their roles
 
-- **`src/server/db/schema.ts`**: `initSchema(db)` is the source of truth for **fresh installs only**. It creates every table at its current shape. New installations (empty `data/` directory) run `initSchema` once and land at the latest `SCHEMA_VERSION`.
-- **`src/server/db/migrations.ts`**: `runMigrations(db)` reads the current `version` from the `schema_version` table and sequentially applies every pending migration block up to `SCHEMA_VERSION`. Existing databases upgrade through this path.
+- **`src/server/db/schema.ts`**: `initSchema(db)` creates the current application schema for **fresh installs only**, including the search and MCP-message schemas through their helpers.
+- **`src/server/db/migrations.ts`**: the ordered `migrations` registry contains `{ version, name, migrate(db) }` entries. `SCHEMA_VERSION` is derived from its last entry. `runMigrations(db)` records applied entries in `schema_migrations(version, name, applied_at)` and applies each pending entry in its own transaction. A fresh installation runs `initSchema` and records all entries as applied in one transaction. Legacy `schema_version` databases are converted to the history table automatically.
 
 Both files must be kept in sync: after adding a migration, update `initSchema` so fresh installs get the same final shape without replaying migrations.
 
@@ -141,10 +154,10 @@ Both files must be kept in sync: after adding a migration, update `initSchema` s
 
 Every feature that touches the schema:
 
-1. Bump `SCHEMA_VERSION` in `migrations.ts` (e.g. `1` → `2`)
-2. Add a new guarded block at the bottom of `runMigrations` that applies only if `currentVersion < newVersion`, using `db.exec` (better-sqlite3) to run raw SQL like `ALTER TABLE workspaces ADD COLUMN new_field TEXT`
+1. Append an entry to `migrations` with the next version and a descriptive name. `SCHEMA_VERSION` updates automatically; do not replace its derived expression with a literal.
+2. Implement the entry's `migrate(db)` using raw SQL, such as `ALTER TABLE workspaces ADD COLUMN new_field TEXT`. The runner owns the transaction and skips versions already recorded.
 3. Update `initSchema` in `schema.ts` so the fresh-install shape matches (e.g. add the new column to the `CREATE TABLE` statement)
-4. At the end of `runMigrations`, bump the row in `schema_version` to the new `SCHEMA_VERSION` (the existing code already does this)
+4. Let the runner record the new entry in `schema_migrations`; do not manually update a legacy `schema_version` row.
 5. Add a test in `src/__tests__/migrations.test.ts` that verifies:
    - A database at the previous version can be upgraded without data loss
    - The new version matches `SCHEMA_VERSION`
@@ -157,18 +170,31 @@ Every feature that touches the schema:
 - **Always idempotent where possible.** Use `IF NOT EXISTS`, check for column existence before altering, etc. Prefer migrations that can be safely re-run.
 - **`ALTER TABLE ADD COLUMN` is safe in SQLite** (even on large tables). For more invasive changes (rename, drop, change type), use the [12-step SQLite pattern](https://sqlite.org/lang_altertable.html#otheralter) within a transaction.
 
-- **Run migrations on every backend start.** `runMigrations(db)` is called from `getDb()` via `src/server/db/index.ts`.
+- **Run migrations on every backend start.** `src/server/index.ts` opens the connection with `getDb()`, checks for pending migrations, attempts a pre-migration backup, then calls `runMigrations(db)`. `getDb()` only opens/configures SQLite; it does not initialize or migrate the schema. Tests creating their own database must initialize it explicitly.
+- **Settings migrations are separate.** The JSON settings migration versions in `settings-service.ts` are independent of SQLite's `SCHEMA_VERSION`.
 - **Test upgrades, not just fresh installs.** The `migrations.test.ts` suite must exercise "old DB → new DB" paths.
 
 ## WebSocket protocol
 
+### External MCP dialogue and update checks
+
+`POST /api/mcp` exposes stateless Streamable HTTP discovery/dialogue tools, behind the existing Host/Origin and network-token gates. The global stdio server forwards dialogue calls through this backend so agent runtime ownership remains centralized. `workspace-message-service.ts` shares delivery with WebSocket chat.
+
+Optional `send_workspace_message.idempotency_key` uses `mcp_message_requests` (migration v43). Reserve before dispatch, preserve fingerprints and terminal outcomes, and never automatically resend an unfinished request after restart. The user event and accepted receipt commit in one SQLite transaction; broadcast follows commit. Dispatch may precede persistence, so interrupted requests are explicitly `delivery_unknown`, not an exactly-once execution promise. The backend alone calls `reconcileMessageRequests` on startup. History retention does not delete the ledger; workspace deletion cascades it.
+
+MCP messages and question answers include optional `source: { kind: 'mcp', clientName, transport }`; keep it across live, sync, history and conversation grouping paths without changing legacy `sender` behavior. Client names are display labels, not authorization identities. Unicode HTTP labels use URI encoding with `X-Kobo-Client-Name-Encoding: uri`; stdio forwards the initialization name or `KOBO_MCP_CLIENT_NAME` override.
+
+`update-check-service.ts` owns the single immediate/every-20-minute npm release check. It is explicitly started/stopped by the backend, coalesces route/poller calls, and broadcasts ephemeral global `kobo:update-checked` events. The client update store also refreshes at reconnect. Do not reintroduce a per-tab registry poll or automatically install updates.
+
+The explicit `npm run test:mcp:live` / `make test-mcp-live` command requires `KOBO_LIVE_ENGINE` and `KOBO_LIVE_MODEL`, uses real credentials and disposable data, and must stay outside `make ci`. Normal CI uses deterministic transport/service tests.
+
 Clients subscribe to individual workspace ids. The server sends `WsEvent` objects:
 
 ```ts
 { id, workspaceId, type, payload, sessionId?, createdAt }
 ```
 
-Common types: `agent:output`, `agent:status`, `agent:error`, `user:message`, `task:updated`, `devserver:status`, `workspace:archived`, `workspace:unarchived`, `sync:response`.
+Agent engines emit a normalized `AgentEvent` union, carried by `agent:event`. Common outer types include `user:message`, `task:updated`, `devserver:status`, `workspace:status`, `workspace:archived`, `workspace:unarchived`, and `sync:response`. Legacy `agent:output` rows remain supported through content migration. Keep the backend union in `services/agent/engines/types.ts` and its client mirror in `client/src/types/agent-event.ts` synchronized.
 
 Two emit flavors in `websocket-service.ts`:
 - `emit(workspaceId, type, payload)` persists to `ws_events` for later replay via `sync:request` on reconnect
@@ -178,7 +204,7 @@ Two emit flavors in `websocket-service.ts`:
 
 ### Forge providers
 
-`src/server/services/forge/` implements a `ForgeProvider` interface with three concrete providers: `github` (wraps the `gh` CLI), `gitlab` (wraps the `glab` CLI), and `none` (a no-op that disables PR/MR features cleanly). The public surface is two functions: `getForgeProvider(name)` in `registry.ts` (returns the provider for a named forge) and `resolveForge(projectPath)` in `resolve.ts` (reads the per-project `forge` setting, then falls back to auto-detection from the `origin` remote URL: host contains `github.com` → GitHub, host contains `gitlab` → GitLab, otherwise `none`). The per-project `forge` setting (`'auto' | 'github' | 'gitlab' | 'none'`, default `'auto'`) is stored in `settings.json` and seeded by settings migration v32. PR routes (`open-pr`, `change-pr-base`) and the pr-watcher go through the resolved provider. **Kōbō ships no forge credentials**, so the user must install and authenticate `gh` or `glab` themselves; when the CLI is absent or unauthenticated, PR/MR actions are disabled with a tooltip rather than a raw error.
+`src/server/services/forge/` implements `ForgeProvider` for `github` (`gh`), `gitlab` (`glab`), `bitbucket-community` (`bkt`), and `none` (disables PR/MR features). `getForgeProvider(id)` resolves a provider; `resolveForge(projectPath)` first reads the explicit project setting, then classifies the `origin` URL by `github.com`, `gitlab`, or `bitbucket`, falling back to `none`. Successful remote reads are cached for five minutes. PR routes and the watcher use the resolved provider. **Kōbō ships no forge credentials**: users authenticate `gh`/`glab` themselves; Bitbucket uses the email and API token entered in Settings, passed to `bkt` and excluded from settings exports. Missing or unauthenticated CLIs disable PR/MR actions with an explanation.
 
 ### Notion (opt-in, user-provided credentials)
 
@@ -188,7 +214,7 @@ Two emit flavors in `websocket-service.ts`:
 2. `NOTION_TOKEN` env var
 3. `~/.claude.json` → `mcpServers.notion.env.NOTION_TOKEN` / `NOTION_API_TOKEN` (Claude Code's MCP config: the recommended path, the same token shared with Claude Code)
 
-The MCP command and args can be overridden via `NOTION_MCP_COMMAND` (default `npx`) and `NOTION_MCP_ARGS` (default `-y @notionhq/notion-mcp-server`) for pinning a specific version or using a fork.
+The selected Claude config entry defaults to the enabled key named exactly `notion`; `global.notionMcpKey` selects another exact key. Its command/args are reused unless `NOTION_MCP_COMMAND` / `NOTION_MCP_ARGS` override them; otherwise the fallback is `npx -y @notionhq/notion-mcp-server`. Existing `OPENAPI_MCP_HEADERS` are preserved; when absent, the resolved token is used to construct them.
 
 When adding features touching `notion-service.ts`, remember: **no token = no feature**. The rest of Kōbō must keep working if the Notion token is absent; only the explicit Notion import endpoints should fail with a clear error. Do not throw at server startup.
 
@@ -198,7 +224,7 @@ See the "Notion integration" section of the README for the end-user setup guide.
 
 Two engines live under `src/server/services/agent/engines/`, both implementing the `AgentEngine` contract in `types.ts`:
 
-**Claude Code** (`claude-code/`): uses `@anthropic-ai/claude-agent-sdk` (in-process async iterator). Spawns no subprocess. Auth via `~/.claude.json` or `ANTHROPIC_API_KEY` env var. The engine arms a **15 s result-drain watchdog** when the SDK emits its `result` message: if the async iterator does not close cleanly within the window, `session:ended` is force-emitted so the orchestrator and auto-loop never hang on a stuck generator. The watchdog is idempotent via a `sessionEndedEmitted` guard and the timer is cleared in `finally`.
+**Claude Code** (`claude-code/`): consumes the `@anthropic-ai/claude-agent-sdk` async iterator. The SDK manages the Claude runtime; Kōbō does not launch a separate `claude` CLI command. Authentication reuses the user's Claude login or `ANTHROPIC_API_KEY`. The engine arms a **15 s result-drain watchdog** when the SDK emits its `result` message: if the async iterator does not close cleanly within the window, `session:ended` is force-emitted so the orchestrator and auto-loop never hang on a stuck generator. The watchdog is idempotent via a `sessionEndedEmitted` guard and the timer is cleared in `finally`.
 
 **OpenAI Codex** (`codex/`): uses the **`codex app-server` JSON-RPC protocol** (line-delimited JSON over stdio with a long-lived `codex` subprocess). The engine layers are:
 - `jsonrpc/transport.ts` + `jsonrpc/peer.ts`: generic JSON-RPC 2.0 stdio peer (request correlation, notifications, server-initiated requests)
@@ -220,17 +246,60 @@ Background: the engine was migrated from `@openai/codex-sdk` (one-shot `codex ex
 - **Permission mode vs collaboration mode are independent.** Sandbox + approvalPolicy control *what the agent may do at OS level* (read-only / workspace-write, never / on-request / unless-trusted). `collaborationMode` is a separate session-level flag that gates internal Codex behaviour (notably interactive Q&A). Kōbō hides both behind a single "permission mode" selector and maps them together.
 - **Sub-agents map to `collabAgentToolCall`.** Codex's analogue of Claude's Task tool is `collabAgentToolCall` (`spawnAgent` / `sendInput` / `resumeAgent` / `wait` / `closeAgent`). The mapper emits **both** a `tool:call` named `Task` (chat card) and a `subagent:progress` event (right-hand panel) per call, the same dual-emission Claude does. See `event-mapper.ts` `handleItemStarted` / `handleItemCompleted` for the `collabAgentToolCall` branch.
 - **`fileChange` items carry a unified-diff blob.** The protocol shape is `{ path, kind: PatchChangeKind, diff: string }` per change; `kind` is a discriminated union, not a string. The mapper flattens the first change into a Claude-style Edit input (`{ file_path, diff, change_kind, move_path? }`) so the existing `ToolCallItem` renderer picks it up. The client parses the unified diff into `DiffLine[]` via `parseUnifiedDiff` in `inline-diff.ts`.
-- **Streaming bursts trip auto-scroll.** Codex emits one `message:text` event per token-delta (50-200 per message), versus Claude which emits ~1 per content block. The naive `eventCount` watcher in `ActivityFeed.vue` triggered an animated `scrollToBottom(180)` per event, causing stacked animations and visible jank. The fix coalesces requests through `requestAnimationFrame` and only animates the *first* scroll after a quiet period; subsequent scrolls during a burst snap instantly.
+- **Streaming bursts trip auto-scroll.** Both engines can emit token deltas; Claude enables SDK partial messages as well. The naive `eventCount` watcher in `ActivityFeed.vue` triggered an animated `scrollToBottom(180)` per event, causing stacked animations and visible jank. Scroll requests are coalesced through `requestAnimationFrame`; preserve burst handling when changing the feed.
 - **`MCP tools` need `default_tools_approval_mode: 'auto'` in `config.mcp_servers`.** Without it Codex flags every MCP tool call as needing user approval ("user cancelled MCP tool call"). Kōbō trusts every tool it spawns, so the options-builder pre-approves the namespace.
 
 ## Workspace operations
 
+### Attachments during creation
+
+`CreationAttachments.vue` keeps `File[]` in the create form, with image-only
+object-URL previews revoked on removal/unmount. The workspace store sends
+existing JSON requests unchanged when there are no files; attachments use
+multipart fields `workspace` (one JSON string) and repeated `attachments`.
+The legacy `images` field is accepted too; both fields share validation limits.
+`attachment-service.ts` validates before workspace/git side effects,
+then saves after the worktree exists and before setup/agent launch. Images use
+`image-service.ts`; documents use generated filenames in `.ai/attachments/`,
+exclusive writes and the existing directory-containment helper. File ownership
+is recorded immediately after exclusive open so partial writes are cleaned on
+failure. Creation excludes `.ai/attachments/` from Git; document uploads also
+ensure that exclusion for existing workspaces. Never use an
+uploaded filename as a storage path. The initial prompt stores image references
+and document names/paths for normal starts and setup retries. Documents are
+copied byte-for-byte, with no PDF extraction or OCR.
+Limits and supported formats live in `src/shared/attachments.ts`:
+10 files, 50 MiB each, 50 MiB total; the creation route limits the body to 51 MiB.
+Document validation uses supported filename extensions because browser MIME
+labels can be empty or generic. A failed creation cleans its own uploaded files
+from reused worktrees, preserving existing files; setup failures retain the
+workspace, files and initial prompt. Comparison requests copy the same browser
+files independently. Attachments are not persisted in form presets.
+See [creation attachments](CONFIGURATION.md#attachments-in-the-creation-description).
+
+### Chat attachments
+
+`POST /api/workspaces/:id/attachments` in `routes/images.ts` accepts one multipart
+`attachment`, validates it with the shared `attachments.ts` policy and returns
+`uid`, `kind`, `path`, `originalName`, and `reference`. It uses the same storage as
+creation and a lifecycle guard against concurrent purge/delete. Document deletion
+accepts only the generated filename at `DELETE /:id/attachments/:filename`; images
+retain their existing retrieval/deletion endpoints. The legacy image upload also
+uses the 50 MiB limit.
+
+`use-chat-attachments.ts` owns pending upload state, draft-level limits and serial
+uploads. `ChatInput.vue` transfers file ownership when sending/queuing, restores
+badges on failed sends, and discards unsent files on workspace/session changes.
+Late upload receipts are cleaned up using the captured original workspace id.
+Never delete handed-off files when clearing a draft or changing conversations.
+See [chat attachments](CONFIGURATION.md#attachments-in-workspace-chat).
+
 ### Change source branch
 
 `change-source-branch-service.ts` re-targets a workspace onto a new source branch. The default path is a cherry-pick of the branch-proper commits (commits in the working branch but in **neither** the old nor the new base), inspired by the sekur `deploy-preprod-rebase.yml` workflow. The route is `POST /api/workspaces/:id/change-source-branch` and returns a discriminated status: `done | aligned | conflict | too-many | dirty`.
 
 - **Built-in cherry-pick**: `fetchAllBranches` → `listProperCommits` → `stashPush` (if dirty + aligned) → backup branch (`kobo-backup/<branch>-<unix-ts>`) → `reset --hard origin/<new>` → cherry-pick replay → optional force-push prompt → forge PR-base update via `provider.changePrBase`. Conflicts leave the worktree in a cherry-pick state for the user/agent to resolve via `POST /:id/git/resolve-with-agent`. `GitConflictError` carries an `operation: 'rebase' | 'merge' | 'cherry-pick'` discriminator.
-- **Custom bash override**: if `effective.changeSourceBranchScript` is non-empty (per-project override or global default), the script **replaces** the built-in flow. Spawned with `bash -c`, cwd = worktree, 5 min timeout, stderr captured (last 8 KB). Exit 0 → Kōbō updates the source-branch metadata; any non-zero exit → the stderr tail is propagated as a clean error. The user-facing menu item only shows when the resolved script is non-empty; empty means the feature is disabled (opt-in).
+- **Custom bash override**: if `effective.changeSourceBranchScript` is non-empty (per-project override or global default), the script **replaces** the built-in flow. Spawned with `bash -c`, cwd = worktree, 5 min timeout, stderr captured (last 8 KB). Exit 0 → Kōbō updates the source-branch metadata; any non-zero exit → the stderr tail is propagated as a clean error. The user-facing menu item only shows when the resolved script is non-empty; clearing the effective script hides the action; the global default is the bundled Kōbō script.
 - **Custom-script env vars**: `KOBO_NEW_BASE`, `KOBO_OLD_BASE`, `KOBO_WORKING_BRANCH`, `KOBO_WORKTREE_PATH`, `KOBO_PROJECT_PATH`, `KOBO_PROJECT_NAME`, `KOBO_WORKSPACE_ID`, `KOBO_WORKSPACE_NAME`, `KOBO_FORGE`, `KOBO_PR_NUMBER` (empty when no PR/MR is open). The default script lives in `settings-defaults.ts` and is seeded into `global.changeSourceBranchScript` by settings migration v33; the client reads it through `GET /api/settings/defaults` for the "Reset to Kōbō default" button. See [CONFIGURATION.md → Custom change-source-branch script](CONFIGURATION.md#custom-change-source-branch-script).
 
 ### Lifecycle hooks
@@ -263,9 +332,9 @@ One task, two engines, two sibling worktrees. `POST /api/workspaces` accepts a `
 
 `src/server/services/worktree-purge-service.ts` removes a workspace's worktree from disk while preserving the chat history and PR metadata. Triggered manually via `POST /api/workspaces/:id/purge-worktree` from the workspace context menu, or automatically by the pr-watcher when a PR transitions to MERGED **and** `global.autoPurgeOnPrMerged` is enabled (Settings → Worktrees toggle, settings migration v36).
 
-Sequence: `captureRestoreData` (best-effort forge lookup for PR number / URL / merge SHA) → stop agent + dev server + terminal → `archiveWorkspace` → `removeWorktree` → `markWorktreePurged(restoreData)` → emit `workspace:worktree-purged`. Permission errors on removal (EACCES / EPERM, typically Docker-owned files in `node_modules` / `vendor`) are detected via regex on the error message and the warning toast carries a copy-pasteable `sudo rm -rf` + `git worktree prune` recovery command plus prevention tips (Docker `USER` directive, `setfacl` default ACL). See [CONFIGURATION.md → Auto-purge worktree on PR merged](CONFIGURATION.md#auto-purge-worktree-on-pr-merged).
+Sequence: `captureRestoreData` (best-effort forge lookup for PR number / URL / merge SHA) → stop agent + dev server + terminal → `archiveWorkspace` → `removeWorktree` → `markWorktreePurged(restoreData)` → emit `workspace:worktree-purged`. Permission errors on removal (EACCES / EPERM, typically Docker-owned files in `node_modules` / `vendor`) trigger an attempt to reclaim ownership through a temporary Docker container and retry removal. If recovery fails, the UI offers manual cleanup guidance and prevention tips (Docker `USER`, default ACLs). Agent and dev-server shutdown must be confirmed before removal; shutdown failures leave the worktree in place. See [CONFIGURATION.md → Auto-purge worktree on PR merged](CONFIGURATION.md#auto-purge-worktree-on-pr-merged).
 
-**Auto-restore on manual recreation.** When the user manually recreates the worktree folder (`gh pr checkout <pr-number>` or `git worktree add <path> <branch>`), the pr-watcher detects the folder reappearing on its next 30 s tick via `autoRestoreManuallyRecreatedWorktrees()`: it iterates archived workspaces with `worktreePurgedAt`, checks `fs.existsSync(worktreePath)`, and on a hit calls `restoreWorktreeFromDisk(id)` which clears `worktree_purged_at` + `worktree_purge_restore_data` + `archived_at` in one transaction, then emits `workspace:worktree-restored`. The client websocket store reuses the same handler as `workspace:archived`/`unarchived` to refresh both the active and archived workspace lists. No UI action needed.
+**Auto-restore on manual recreation.** When the user manually recreates the worktree folder (`gh pr checkout <pr-number>` or `git worktree add <path> <branch>`), the pr-watcher detects the folder reappearing on its next 30 s tick via `autoRestoreManuallyRecreatedWorktrees()`: it iterates archived workspaces with `worktreePurgedAt`, validates the exact worktree root, repository and working branch via `isMatchingWorkspaceWorktree`, and on a match calls `restoreWorktreeFromDisk(id)` which clears `worktree_purged_at` + `worktree_purge_restore_data` + `archived_at` in one transaction, then emits `workspace:worktree-restored`. The client websocket store reuses the same handler as `workspace:archived`/`unarchived` to refresh both the active and archived workspace lists. No UI action needed.
 
 **Restore**: `POST /api/workspaces/:id/restore-worktree` calls `worktree-restore-service.ts` to recreate the exact checkout and only then clear purge/archive metadata via `restoreWorktreeFromDisk`. Source order: surviving local branch → optional `headCommitSha` in the existing restore JSON → exact branch fetched from `origin`. No SQL migration is needed for the optional JSON key; older records remain supported. No reset, overwrite, agent/dev-server start or setup script. `workspace-lifecycle-guard.ts` excludes overlapping restore/purge/delete operations, while the existing common-Git-directory lock serializes Git mutations. The watcher shares `isMatchingWorkspaceWorktree` validation and invalidates in-flight PR checks on restoration; delayed auto-purges carry their expected archive timestamp to avoid purging a workspace restored in the meantime. The context menu and purged banner expose the action; HTTP and the existing `workspace:worktree-restored` event reconcile client lists. Discarded uncommitted/ignored files and dependencies are not recoverable.
 
@@ -295,7 +364,7 @@ The right panel of `DiffViewer.vue` is editable when the workspace agent is stop
 
 **Route layer** is thin: always wrap the handler body in `try / catch` and return `c.json({ error: message }, status)`. Match the existing shape in `src/server/routes/workspaces.ts`.
 
-**Swallowed failures** are acceptable (and required) for best-effort side effects like `agentManager.stopAgent` and `devServerService.stopDevServer` during delete/archive. Log with `console.error` and continue. Never let these break the happy path.
+**Best-effort failures** may be logged and swallowed for non-critical side effects such as lifecycle-hook reporting. Process shutdown is a precondition for destructive operations: use `stopAgentAndWait` with `assertAgentStopped`, propagate dev-server shutdown failures, and retain the worktree when shutdown is unconfirmed. See [Audit remediation contracts](#audit-remediation-contracts-september-2026).
 
 **Route ordering matters** in Hono. Static paths (`GET /archived`) MUST be declared **before** dynamic segments (`GET /:id`) or the dynamic segment captures them. There's a regression test locking this invariant in `src/__tests__/routes-workspaces.test.ts`.
 
@@ -305,7 +374,7 @@ The right panel of `DiffViewer.vue` is editable when the workspace agent is stop
 
 ## Internationalization (i18n)
 
-The frontend uses `vue-i18n` v10 with 5 supported locales: English (`en`), French (`fr`), German (`de`), Spanish (`es`), Italian (`it`). Translation files live in `src/client/src/i18n/`.
+The frontend uses `vue-i18n` with 5 supported locales: English (`en`), French (`fr`), German (`de`), Spanish (`es`), Italian (`it`). Translation files live in `src/client/src/i18n/`; the dependency version is declared in `src/client/package.json`.
 
 **Mandatory rules for all frontend code:**
 
@@ -318,9 +387,9 @@ The frontend uses `vue-i18n` v10 with 5 supported locales: English (`en`), Frenc
 
 ## Testing discipline
 
-- **TDD for backend**: write the failing test, confirm it fails for the right reason, implement minimally, confirm it passes, commit. One commit per logical unit. See existing tests in `src/__tests__/workspace-service.test.ts` for the setup pattern (fresh in-memory DB per test via `resetDb()`).
+- **TDD for backend**: write the failing test, confirm it fails for the right reason, implement minimally, confirm it passes, commit. One commit per logical unit. See `src/__tests__/workspace-service.test.ts` for the setup pattern: `resetDb()` creates a fresh database in a temporary directory, initializes its schema, and closes/removes it after each test.
 - **Route tests** use `vi.mock()` on service modules before imports (see `src/__tests__/routes-workspaces.test.ts`). Keep mocks complete; missing exports cause obscure failures.
-- **Frontend tests** cover Pinia stores (`workspace-store`, `settings-store`, `templates-store`) and pure utility modules (`expand-template`). Run with `cd src/client && npm test`. Vue components are **not** tested: type-check via `npx tsc --noEmit` + manual smoke testing covers UI behavior.
+- **Frontend tests** cover Pinia stores, pure utilities, composables, and selected Vue components (for example `ActivityFeed`, `TurnCard`, and `WorkspaceCard`). Run with `cd src/client && npm test`; use Vue Test Utils and the existing `happy-dom` setup for component regressions. Run `cd src/client && npm run type-check` for Vue/TypeScript checking, and use manual smoke tests for browser behavior that the DOM test environment cannot exercise.
 - **`beforeEach(() => vi.clearAllMocks())`** is the convention for all route test files.
 
 ## Git workflow
@@ -385,7 +454,7 @@ deviate from the documented system without explicit user approval.
 - Don't add confirmation dialogs for reversible actions (archive, unarchive). Only destructive actions (delete) get a dialog.
 - Don't introduce ORMs, query builders, or schema validation libraries; the project is small enough for raw prepared statements and hand-written mappers.
 - Don't break the single-source-of-truth of `CLAUDE.md` → `AGENTS.md` symlink. Edit `AGENTS.md`; `CLAUDE.md` follows automatically.
-- Don't skip `try/catch` swallowing on best-effort cleanup (agent stop, dev-server stop, worktree removal). These must never break the primary operation.
+- Don't swallow failed or timed-out shutdowns before deleting, purging, or replacing a worktree. Only non-critical best-effort side effects may fail without blocking the primary operation.
 - Don't hardcode user-visible text in the frontend. Every string must go through `$t()` / `t()` with keys in all 5 locale files. See [Internationalization (i18n)](#internationalization-i18n).
 - Don't hardcode hex colors, spacing literals, or font names in components. Use the CSS variables from `src/client/src/css/design-tokens.scss` and the patterns in `DESIGN.md`. See [Design System](#design-system).
 

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to Kōbō are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/). Each release is an `## <version>`
 section — the in-app "What's new" dialog reads this file.
 
+## 1.11.41
+
+- feat(attachments): support documents in workspace creation and chat
+
+## 1.11.40
+
+- feat(workspaces): add external MCP access and harden workspace flows
+
 ## 1.11.39
 
 - fix(deps): require Claude SDK with Fable 5.1 support

package/README.md

@@ -38,14 +38,16 @@ Default port is `3000`; if it's taken, `SERVER_PORT` (checked first) or `PORT` p
 SERVER_PORT=9997 PORT=9998 npx @loicngr/kobo@latest
 ```
 
-Kōbō's production build is an installable PWA — use your browser's **Install app** action. Want to run from source or contribute instead? See [`CONTRIBUTING.md`](./CONTRIBUTING.md). Prefer Docker? Jump to [Docker deployment](#docker-deployment).
+Kōbō's production build is an installable PWA — use your browser's **Install app** action. Want to run from source or contribute instead? See [`CONTRIBUTING.md`](./CONTRIBUTING.md). Prefer Docker? Jump to [Docker deployment](#docker).
 
 ![Diff viewer with side-by-side changes](docs/assets/images/diff-viewer.png)
 
 ## Everything else Kōbō does
 
+- **Attachments from the first prompt**: paste, drop or attach screenshots, Markdown, text files or PDFs to the creation description or workspace chat. Kōbō copies them into the worktree for the agent. See [creation attachments](./CONFIGURATION.md#attachments-in-the-creation-description) and [chat attachments](./CONFIGURATION.md#attachments-in-workspace-chat).
+
 - **Command palette & search**: `/` autocompletes skills and commands, `@` fuzzy-completes worktree file paths, `Ctrl+F` searches readable messages, `Ctrl+K` opens a command palette. The global search page deep-links to the same spot.
-- **Full MCP toolset (`kobo-tasks`)**: task/acceptance-criteria CRUD, dev server control, a unified `get_ticket` (Notion or Sentry), cross-workspace conversation search, per-session usage, and a `.ai/thoughts` decision log — see [`AGENTS.md`](./AGENTS.md) for the full tool list.
+- **MCP toolset (`kobo-tasks`)**: task/acceptance-criteria CRUD, dev server control, a unified `get_ticket` (Notion or Sentry), cross-workspace conversation search, per-session usage, and a `.ai/thoughts` decision log — see the [MCP guide](./src/mcp-server/README.md#tools). External MCP clients can also discover workspaces, read conversations, send messages, and answer questions through HTTP or global stdio.
 
   ![Sub-agents panel showing parallel tool calls](docs/assets/images/sub-agents-panel.png)
 - **Multi-forge Git panel**: GitHub (`gh`), GitLab (`glab`), or Bitbucket Community (`bkt`), auto-detected from the remote — `Open PR`, `Merge ready PR`, `Change PR base`, `Change source branch`, all from the UI.
@@ -56,7 +58,7 @@ Kōbō's production build is an installable PWA — use your browser's **Install
   ![Agent asking a clarifying question, awaiting the user's answer](docs/assets/images/agent-question.png)
 - **Quota-aware**: 5-hour / 7-day Claude usage and Codex rate-limit buckets live in the footer; sessions auto-resume after a reset.
 - **Disk-space purge**: reclaim a merged workspace's `node_modules`/`vendor` weight without losing its chat history — see [`CONFIGURATION.md`](./CONFIGURATION.md#auto-purge-worktree-on-pr-merged).
-- **Lifecycle scripts**: shell scripts run automatically on setup, cleanup, and archive, with output streamed into the chat.
+- **Lifecycle scripts**: shell scripts run on setup, cleanup, archive, session end, PR merge, or auto-loop stop, with output streamed into the chat.
 - **Observability**: a per-session timeline (duration, tools, tokens, errors) and a downloadable redacted diagnostic JSON.
 - **Optional integrations**: Notion (import missions) and Sentry (fix from issue URL), each independently toggled with a **Test connection** action; local voice transcription via `whisper.cpp`.
 
@@ -105,7 +107,7 @@ src/
 ├── client/         # Vue 3 + Quasar PWA
 ├── mcp-server/     # kobo-tasks MCP server, spawned per workspace
 ├── shared/         # types shared backend ↔ frontend
-└── __tests__/      # Vitest suite, backend + client, thousands of tests
+└── __tests__/      # backend Vitest suite; client tests live in client/src/__tests__/
 ```
 
 [`AGENTS.md`](./AGENTS.md) covers the data model, WebSocket protocol, engine contracts, MCP tool surface, migration discipline, i18n rules, and contribution guidelines.

package/dist/mcp-server/kobo-tasks-handlers.js

@@ -4,7 +4,7 @@ import { nanoid } from 'nanoid';
 import * as cronService from '../server/services/cron-service.js';
 import * as settingsService from '../server/services/settings-service.js';
 import { slugifyProjectName } from '../server/utils/project-slug.js';
-import { resolveExistingPathInside } from '../server/utils/safe-path.js';
+import { ensureDirectoryInside, resolveExistingPathInside } from '../server/utils/safe-path.js';
 import { resolveWorkspaceWorktreePath } from '../server/utils/worktree-paths.js';
 import { MASKED_SECRET, SECRET_GLOBAL_KEYS } from '../shared/consts.js';
 /** Allowed task status values. */
@@ -404,7 +404,7 @@ export function readDocumentHandler(worktreePath, relPath) {
 }
 /**
  * Append a thought / decision / note to
- * `.ai/thoughts/logs/<YYYY-MM-DD>-<slug>.md`. Creates the directory if missing.
+ * `.ai/thoughts/logs/<YYYY-MM-DD>-<slug>-<timestamp>-<id>.md`. Creates the directory if missing.
  * Returns the path (worktree-relative) of the file actually written — useful
  * for the agent to reference it in chat.
  *
@@ -419,8 +419,7 @@ export function logThoughtHandler(worktreePath, data) {
     const content = data.content?.trim();
     if (!content)
         throw new Error('content is required');
-    const thoughtsDir = path.join(worktreePath, '.ai', 'thoughts', 'logs');
-    fs.mkdirSync(thoughtsDir, { recursive: true });
+    const thoughtsDir = ensureDirectoryInside(worktreePath, path.join('.ai', 'thoughts', 'logs'));
     const date = new Date().toISOString().slice(0, 10);
     const slug = title
         .toLowerCase()
@@ -430,12 +429,20 @@ export function logThoughtHandler(worktreePath, data) {
         .replace(/^-+|-+$/g, '')
         .slice(0, 60) || 'note';
     const tagSuffix = data.tag ? `-${data.tag.replace(/[^a-z0-9]+/gi, '-').toLowerCase()}` : '';
-    const filename = `${date}-${slug}${tagSuffix}.md`;
-    const abs = path.join(thoughtsDir, filename);
-    const relPath = `.ai/thoughts/logs/${filename}`;
     const header = `# ${title}\n\n_${new Date().toISOString()}_${data.tag ? ` · tag: \`${data.tag}\`` : ''}\n\n`;
-    fs.writeFileSync(abs, header + content + (content.endsWith('\n') ? '' : '\n'), 'utf-8');
-    return { path: relPath };
+    for (let attempt = 0; attempt < 5; attempt++) {
+        const filename = `${date}-${slug}${tagSuffix}-${Date.now()}-${nanoid(10)}.md`;
+        const abs = path.join(thoughtsDir, filename);
+        try {
+            fs.writeFileSync(abs, header + content + (content.endsWith('\n') ? '' : '\n'), { encoding: 'utf-8', flag: 'wx' });
+            return { path: `.ai/thoughts/logs/${filename}` };
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+        }
+    }
+    throw new Error('Could not allocate a unique thought filename');
 }
 /**
  * Aggregate `usage` events from `ws_events` to report how many tokens and

package/dist/mcp-server/kobo-tasks-server.js

@@ -3,7 +3,9 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { getDb } from '../server/db/index.js';
+import { WORKSPACE_DIALOGUE_TOOLS } from '../shared/workspace-dialogue-tools.js';
 import { createTaskHandler, cronListHandler, deleteTaskHandler, getDevServerStatusHandler, getSessionUsageHandler, getSettingsHandler, getTicketSourcesHandler, getWorkspaceInfoHandler, listDocumentsHandler, listTasksHandler, listWorkspaceImagesHandler, listWorkspacesHandler, logThoughtHandler, markAutoLoopReadyHandler, markTaskDoneHandler, readDocumentHandler, readWorkspaceEventsCsvHandler, setWorkspaceAgentDescriptionHandler, updateTaskHandler, } from './kobo-tasks-handlers.js';
+import { callWorkspaceDialogueTool } from './workspace-dialogue-client.js';
 const workspaceId = process.env.KOBO_WORKSPACE_ID;
 const dbPath = process.env.KOBO_DB_PATH;
 const settingsPath = process.env.KOBO_SETTINGS_PATH;
@@ -94,9 +96,12 @@ async function notifyAgentDescriptionUpdated() {
 /** Generic HTTP request to the Kobo backend, returning parsed JSON or null. */
 async function backendRequest(method, pathname, body) {
     const url = `${backendUrl}${pathname}`;
-    const init = { method };
+    const headers = process.env.KOBO_NETWORK_TOKEN
+        ? { 'X-Kobo-Token': process.env.KOBO_NETWORK_TOKEN }
+        : {};
+    const init = { method, headers };
     if (body !== undefined) {
-        init.headers = { 'Content-Type': 'application/json' };
+        headers['Content-Type'] = 'application/json';
         init.body = JSON.stringify(body);
     }
     const res = await fetch(url, init);
@@ -475,6 +480,7 @@ const WORKSPACE_SCOPED_TOOLS = [
     },
 ];
 const GLOBAL_TOOLS = [
+    ...WORKSPACE_DIALOGUE_TOOLS,
     {
         name: 'list_workspaces',
         description: 'List Kōbō workspaces with their id, title, status, and creation date. Works even when the Kōbō backend server is not running (reads the database directly). Use this to discover existing workspaces before creating one or targeting one with archive_workspace/stop_workspace.',
@@ -594,6 +600,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return fail(`Tool '${name}' requires a workspace-bound MCP session (KOBO_WORKSPACE_ID not set).`);
     }
     try {
+        if (WORKSPACE_DIALOGUE_TOOLS.some((tool) => tool.name === name)) {
+            if (workspaceId && a.workspace_id === workspaceId && name === 'send_workspace_message')
+                return fail('Use the normal conversation to communicate in your own workspace.');
+            return await callWorkspaceDialogueTool(backendUrl, name, a, process.env.KOBO_NETWORK_TOKEN, process.env.KOBO_MCP_CLIENT_NAME ?? server.getClientVersion()?.name);
+        }
         if (name === 'list_tasks') {
             return ok(listTasksHandler(db, workspaceId));
         }

package/dist/mcp-server/workspace-dialogue-client.js

@@ -0,0 +1,28 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { validateDialogueArguments } from '../shared/workspace-dialogue-tools.js';
+import { normalizeClientName } from '../shared/workspace-message-types.js';
+/** Stateless HTTP bridge: external stdio clients never own agent runtime state. */
+export async function callWorkspaceDialogueTool(backendUrl, name, args, token, clientName) {
+    const arguments_ = validateDialogueArguments(name, args);
+    const client = new Client({ name: 'kobo-stdio-bridge', version: '1.0.0' });
+    const signal = AbortSignal.timeout(30_000);
+    const transport = new StreamableHTTPClientTransport(new URL(`${backendUrl.replace(/\/$/, '')}/api/mcp`), {
+        requestInit: {
+            signal,
+            headers: {
+                ...(token ? { 'X-Kobo-Token': token } : {}),
+                'X-Kobo-Client-Name': encodeURIComponent(normalizeClientName(clientName)),
+                'X-Kobo-Client-Name-Encoding': 'uri',
+                'X-Kobo-Client-Transport': 'stdio',
+            },
+        },
+    });
+    try {
+        await client.connect(transport, { signal });
+        return await client.callTool({ name, arguments: arguments_ }, undefined, { signal });
+    }
+    finally {
+        await client.close();
+    }
+}

package/dist/server/db/mcp-message-schema.js

@@ -0,0 +1,16 @@
+/** v43 schema shared by fresh installs and the append-only migration. */
+export function initMcpMessageSchema(db) {
+    db.exec(`CREATE TABLE IF NOT EXISTS mcp_message_requests (
+    workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+    idempotency_key TEXT NOT NULL,
+    request_id TEXT NOT NULL UNIQUE,
+    fingerprint TEXT NOT NULL,
+    state TEXT NOT NULL CHECK (state IN ('reserved','dispatching','accepted','rejected','unknown')),
+    result_json TEXT,
+    event_id TEXT,
+    session_id TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    PRIMARY KEY (workspace_id, idempotency_key)
+  )`);
+}

package/dist/server/db/migrations.js

@@ -1,4 +1,6 @@
+import { initMcpMessageSchema } from './mcp-message-schema.js';
 import { initSchema } from './schema.js';
+import { initSearchSchema } from './search-schema.js';
 /** Ordered registry of all schema migrations. Append new entries at the end. */
 export const migrations = [
     {
@@ -740,6 +742,8 @@ export const migrations = [
     CREATE INDEX IF NOT EXISTS idx_workspace_activity_created ON workspace_activity(created_at);`);
         },
     },
+    { version: 42, name: 'index-logical-search-messages', migrate: initSearchSchema },
+    { version: 43, name: 'durable-mcp-message-requests', migrate: initMcpMessageSchema },
 ];
 /** Current schema version — always equals the highest migration version. */
 export const SCHEMA_VERSION = migrations.length > 0 ? migrations[migrations.length - 1].version : 1;

package/dist/server/db/schema.js

@@ -1,3 +1,5 @@
+import { initMcpMessageSchema } from './mcp-message-schema.js';
+import { initSearchSchema } from './search-schema.js';
 /** Create all tables and indexes for a fresh install. Not used for upgrades -- see migrations.ts. */
 export function initSchema(db) {
     db.exec(`
@@ -221,4 +223,6 @@ export function initSchema(db) {
     CREATE INDEX IF NOT EXISTS idx_session_event_metrics_session
       ON session_event_metrics(session_id);
   `);
+    initSearchSchema(db);
+    initMcpMessageSchema(db);
 }