@loicngr/kobo 2.1.23 → 2.1.24

package/AGENTS.md

@@ -243,7 +243,23 @@ Claude SDK `task_*` messages cover agents **and** background jobs. Preserve `tas
 
 ### External MCP dialogue and update checks
 
-Workspace-bound stdio, global stdio and HTTP expose shared `create_workspace` / `diagnose_workspace_pr` definitions in `src/shared/workspace-creation-tools.ts`. Stdio forwards them to the backend. `workspace-creation-mcp-service.ts` validates inputs and dispatches through the existing workspace and PR routes in process; preserve UI validation, checkout fingerprints, lifecycle guards and rollback. Inputs use snake_case except the existing camelCase PR checkout decisions. Attachments are inline base64, bounded to the shared 10-file/50 MiB decoded limit before checkout mutations. Keep SDK HTTP/stdio limits aligned with the shared creation envelope budget. Only creation envelopes get the larger base64 HTTP body budget; ordinary MCP requests remain 1 MiB. After a known PR creation failure, rollback only a checkout proven newly created, unchanged, clean (including ignored files) and unowned, under the Git repository lock; retain other checkouts and expose recovery details. Do not retry uncertain creation automatically or treat `creation_id` as an idempotency key. Restricted review/handoff launches cannot create workspaces or invoke lifecycle mutations. Shared lifecycle tools (`workspace-lifecycle-tools.ts` / `workspace-lifecycle-mcp-service.ts`) also expose archive, purge, delete, unarchive and restore through the same transports. Reject reserved/bulk/path-like IDs, require explicit purge/delete flags, and preserve warnings. Single-workspace DELETE accepts optional `confirmationBranch`, rechecked under its lifecycle guard before stopping processes; MCP always supplies it. Branch rename/resync share this guard so the confirmed branch and checkout path cannot change during teardown. Recovery uses `restore-worktree` before unarchive and never starts an agent.
+Workspace-bound stdio, global stdio and HTTP expose shared `create_workspace` / `diagnose_workspace_pr` definitions in `src/shared/workspace-creation-tools.ts`. Stdio forwards them to the backend. `workspace-creation-mcp-service.ts` validates inputs and dispatches through the existing workspace and PR routes in process; preserve UI validation, checkout fingerprints, lifecycle guards and rollback. Inputs use snake_case except the existing camelCase PR checkout decisions. Attachments are inline base64, bounded to the shared 10-file/50 MiB decoded limit before checkout mutations. Keep SDK HTTP/stdio limits aligned with the shared creation envelope budget. Creation and send_workspace_message envelopes with attachments get the larger base64 HTTP body budget; ordinary MCP requests remain 1 MiB. After a known PR creation failure, rollback only a checkout proven newly created, unchanged, clean (including ignored files) and unowned, under the Git repository lock; retain other checkouts and expose recovery details. Do not retry uncertain creation automatically or treat `creation_id` as an idempotency key. Restricted review/handoff launches cannot create workspaces or invoke lifecycle mutations. Shared lifecycle tools (`workspace-lifecycle-tools.ts` / `workspace-lifecycle-mcp-service.ts`) also expose archive, purge, delete, unarchive and restore through the same transports. Reject reserved/bulk/path-like IDs, require explicit purge/delete flags, and preserve warnings. Single-workspace DELETE accepts optional `confirmationBranch`, rechecked under its lifecycle guard before stopping processes; MCP always supplies it. Branch rename/resync share this guard so the confirmed branch and checkout path cannot change during teardown. Recovery uses `restore-worktree` before unarchive and never starts an agent.
+
+MCP creation and single-workspace messages share `shared/mcp-attachments.ts`
+validation and inline `{name, mime_type, data_base64}` schemas. Validate before
+writing, reserve keyed-message identity before uploading, and fingerprint the
+original content/session plus attachment names, types and bytes (preserving old
+text-only fingerprints). Delivery saves files under the target worktree using
+the existing attachment service, then passes references to the engine and chat.
+Clean up definitively rejected files; retain them if dispatch is uncertain.
+Never expose raw server filesystem paths as attachment inputs. Group messages
+remain text-only.
+
+The global JSON setting `forceImmediateMessages` (v67, default false) bypasses
+client chat queueing for new messages using confirmed immediate delivery. It
+also bypasses the auto-loop next-iteration UI path; normal backend immediate
+message delivery pauses a ready loop. Do not flush existing queues on toggle,
+remove compaction/permission/handoff guards, or queue rejected forced sends.
 
 `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.
 
@@ -654,6 +670,14 @@ reuse outside PR import still forces setup off. Worktree ownership is unchanged.
 
 Each event maps to one effective-settings key (`sessionEndedScript` / `prMergedScript` / `autoLoopDisabledScript`, settings migration v55), cascading project-over-global with empty meaning inherit. Execution reuses `runScript` with `eventPrefix: 'hook:<event>'`; `runScript` gained an `extraEnv` option, merged **under** the identity variables so a hook payload can never claim a different `WORKSPACE_ID`. `runLifecycleHook` never rejects and returns `null` when there is nothing to run (no script, unknown workspace, worktree gone). The pr-watcher awaits the `pr-merged` hook before auto-purge so a deploy script does not lose its worktree mid-run. See [CONFIGURATION.md → Lifecycle hooks](CONFIGURATION.md#lifecycle-hooks).
 
+The shared `utils/script-runner.ts` supplies `INSTANCE` and `PROJECT_NAME` to
+setup, cleanup, archive and every lifecycle hook, including shutdown. Resolve
+these at execution time through `utils/dev-server-instance.ts`, shared with the
+dev-server service. Never inherit ambient Docker identity or invent a Compose
+project name: `PROJECT_NAME` is empty when no matching instance metadata exists.
+`ScriptVariablesHelp.vue` documents common and event-specific variables in both
+global and project settings; keep this help and CONFIGURATION.md in sync.
+
 ### Engine comparison
 
 Successful paired creation opens the existing `split` route with `left` and `right` workspace ids in creation order. A single successful creation keeps the normal workspace route, including when the second creation fails.

package/CHANGELOG.md

@@ -4,6 +4,10 @@ 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.
 
+## 2.1.24
+
+- feat: add MCP attachments and immediate chat delivery
+
 ## 2.1.23
 
 - feat: configure shutdown hooks and improve agent guidance

package/CONFIGURATION.md

@@ -397,14 +397,43 @@ silently.
 
 ### Hook environment variables
 
-Every hook gets the standard set: `WORKSPACE_ID`, `WORKSPACE_NAME`,
-`BRANCH_NAME`, `SOURCE_BRANCH`, `PROJECT_PATH`, plus `KOBO_HOOK_EVENT` naming
-the event. On top of that:
+Settings → Scripts and each project's script fields include expandable
+**Available variables** help. Setup, cleanup, archive and lifecycle scripts all
+run in the workspace worktree (`PWD`) and receive:
+
+| Variable | Value |
+|---|---|
+| `WORKSPACE_ID`, `WORKSPACE_NAME` | Workspace identifier and display name |
+| `BRANCH_NAME`, `SOURCE_BRANCH` | Working branch and source branch |
+| `PROJECT_PATH` | Main repository path, not the worktree |
+| `INSTANCE` | Matching Docker instance name, or the lowercased branch with `/` and `_` replaced by `-` |
+| `PROJECT_NAME` | Exact Compose project name from the matching `PROJECT_PATH/.container/instances/*.env` file; empty without a known matching instance |
+
+Docker identity is resolved at each script execution using the same instance
+metadata as the dev-server panel. It never inherits a Docker project from the
+server's environment or guesses one from a folder name. In particular, setup
+before the first dev-server launch usually has an empty `PROJECT_NAME`.
+Keep the metadata file if later archive/PR hooks need that identity. These
+variables are specific to the shared workspace script runner; dev start/stop
+and change-source-branch commands have their own contracts documented below.
+
+Quote variables and guard destructive Docker commands against a missing project:
+
+```bash
+# Archive or PR merged — stop this stack, preserving volumes and images.
+docker compose -p "${PROJECT_NAME:?Missing Docker project}" down --remove-orphans
+```
+
+Add `--volumes --rmi local` only to also remove its Compose-managed volumes and
+images without custom tags. This does not remove every image on the Docker host.
+
+Lifecycle hooks also receive `KOBO_HOOK_EVENT` naming the event. On top of that:
 
 | Hook | Extra variables |
 |---|---|
 | Session ended | `KOBO_SESSION_ID`, `KOBO_SESSION_END_REASON` (`completed` / `error` / `killed` / `watchdog`), `KOBO_SESSION_EXIT_CODE` (empty when the engine reports none), `KOBO_SESSION_STOP_CAUSE` (`user`, `replacement`, `setup`, `archive`, or `shutdown`; empty for a natural end; superseded sessions and delete/purge stops skip the hook), `KOBO_AUTOLOOP_ACTIVE` (`1` when auto-loop is enabled, so a test run may overlap with the next agent's edits) |
 | PR merged | `KOBO_PR_NUMBER`, `KOBO_PR_URL` |
+| Kōbō shutdown | `KOBO_SHUTDOWN_SIGNAL` |
 | Auto-loop stopped | `KOBO_AUTOLOOP_REASON` (`completed` / `user-action`; blocked missions retain their intent and do not fire this hook), `KOBO_TASKS_PENDING` |
 
 Only `KOBO_`-prefixed variables are passed through from the event; a hook
@@ -851,6 +880,13 @@ The setting lives in `settings.json` under `global` and has no UI control yet:
 
 An external MCP client can connect to `http://127.0.0.1:3000/api/mcp` using Streamable HTTP (use your backend's configured port). It can create workspaces with the same options as the form, diagnose and check out existing PRs, discover workspaces, read their conversations, send messages and answer pending questions. Workspace-bound stdio, global stdio and HTTP share the creation contract, including brainstorm settings, final auto-loop review, workflow policy, imports, existing worktrees, comparison grouping and inline attachments. All three transports also expose archive, disk-space purge, permanent deletion with explicit branch confirmation, unarchive and recovery of purged worktrees. See the [creation and PR guide](src/mcp-server/README.md#create_workspace) for fields, explicit checkout decisions and timeout/retry behavior.
 
+Both `create_workspace` and `send_workspace_message` accept inline `attachments`
+with `{name, mime_type, data_base64}`: 10 files, 50 MiB decoded total, same formats
+as the interface. Messages may contain only attachments. Kōbō saves them in the
+destination worktree and sends file/image references to the agent and chat.
+Keyed retries include attachment identity and never upload or send twice. See
+[Sending files and images](src/mcp-server/README.md#sending-files-and-images).
+
 Remote HTTP clients follow the [network access](#network-access) settings and supply the Kōbō token as `Authorization: Bearer <token>` or `X-Kobo-Token`. The endpoint uses the same Host/Origin and reverse-proxy policy as the rest of the backend. No network setting is changed automatically.
 
 See [Connect an external LLM](src/mcp-server/README.md#connect-an-external-llm) for connection examples, tool arguments, cursor polling and authentication details.
@@ -1425,6 +1461,23 @@ Kōbō talks to the embedded [`@anthropic-ai/claude-agent-sdk`](https://github.c
 
 The model selector is populated from [`src/shared/models.ts`](./src/shared/models.ts), also used by backend validation. This checkout includes Fable 5.1, Mythos 5, Opus 5, Opus 4.8, Sonnet 5 and older variants. Pick the default in **Settings → Agents**. Catalogue entries describe what Kōbō offers; provider access still depends on your account. `auto` leaves model selection to the runtime.
 
+#### Immediate chat messages
+
+**Settings → Agents → Force immediate message delivery** controls
+`forceImmediateMessages`, **false by default**, including existing installations.
+When enabled, new chat messages reach a busy Claude/Codex agent directly, like
+**Ctrl+Enter**, instead of waiting in Kōbō's message queue. Messages sent during
+an auto-loop go through immediate delivery and pause the active, ready loop.
+Previously queued instructions stay queued; changing the setting never sends
+old drafts automatically. The setting affects subsequent sends without restarting
+the server or agent.
+
+Compaction, pending questions/permissions, archive and session handoff guards
+still apply. Failed or rejected sends restore the draft; they do not silently
+queue it. MCP messages already use direct delivery and do not depend on this
+interface setting. Explicit next-iteration scheduling remains available through
+its dedicated auto-loop API.
+
 #### Session watchdogs
 
 **Settings → Agents → Enable agent inactivity watchdogs**, at the top of the tab,

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

@@ -3,9 +3,10 @@ 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 { MAX_MCP_ATTACHMENT_REQUEST_BYTES } from '../shared/mcp-attachments.js';
 import { EXTERNAL_MEMORY_TOOL_DEFINITIONS, isMemoryToolName, MEMORY_TOOL_DEFINITIONS } from '../shared/memory-tools.js';
 import { INTERNAL_PROGRESS_BAR_TOOLS, isProgressBarTool, PROGRESS_BAR_TOOLS } from '../shared/progress-bar-tools.js';
-import { isWorkspaceCreationTool, MAX_MCP_CREATION_REQUEST_BYTES, WORKSPACE_CREATION_TOOLS, } from '../shared/workspace-creation-tools.js';
+import { isWorkspaceCreationTool, WORKSPACE_CREATION_TOOLS } from '../shared/workspace-creation-tools.js';
 import { WORKSPACE_DIALOGUE_TOOLS } from '../shared/workspace-dialogue-tools.js';
 import { isWorkspaceGroupMessageTool, WORKSPACE_GROUP_MESSAGE_TOOLS } from '../shared/workspace-group-message-tools.js';
 import { isWorkspaceLifecycleTool, WORKSPACE_LIFECYCLE_TOOLS } from '../shared/workspace-lifecycle-tools.js';
@@ -1023,7 +1024,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 const transport = new StdioServerTransport(process.stdin, process.stdout, {
     // Include the JSON-lines delimiter in addition to the HTTP envelope budget.
-    maxBufferSize: MAX_MCP_CREATION_REQUEST_BYTES + 1,
+    maxBufferSize: MAX_MCP_ATTACHMENT_REQUEST_BYTES + 1,
 });
 server.connect(transport).catch((err) => {
     console.error('[kobo-tasks-server] Fatal:', err);

package/dist/server/routes/mcp.js

@@ -3,9 +3,10 @@ import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { Hono } from 'hono';
 import { bodyLimit } from 'hono/body-limit';
+import { MAX_MCP_ATTACHMENT_REQUEST_BYTES } from '../../shared/mcp-attachments.js';
 import { EXTERNAL_MEMORY_TOOL_DEFINITIONS, isMemoryToolName } from '../../shared/memory-tools.js';
 import { isProgressBarTool, PROGRESS_BAR_TOOLS } from '../../shared/progress-bar-tools.js';
-import { isWorkspaceCreationTool, MAX_MCP_CREATION_REQUEST_BYTES, WORKSPACE_CREATION_TOOLS, } from '../../shared/workspace-creation-tools.js';
+import { isWorkspaceCreationTool, WORKSPACE_CREATION_TOOLS } from '../../shared/workspace-creation-tools.js';
 import { EXTERNAL_MCP_TOOLS } from '../../shared/workspace-dialogue-tools.js';
 import { isWorkspaceGroupMessageTool, WORKSPACE_GROUP_MESSAGE_TOOLS, } from '../../shared/workspace-group-message-tools.js';
 import { isWorkspaceLifecycleTool, WORKSPACE_LIFECYCLE_TOOLS } from '../../shared/workspace-lifecycle-tools.js';
@@ -19,22 +20,27 @@ import { executeWorkspaceGroupMessageTool, WorkspaceGroupMessageMcpError, } from
 import { executeWorkspaceLifecycleTool, WorkspaceLifecycleMcpError, } from '../services/workspace-lifecycle-mcp-service.js';
 import { prepareMemoryToolEnvelope } from '../utils/memory-token-budget.js';
 const app = new Hono();
-// Only creation envelopes may carry the larger, base64 attachment payload.
+// Only creation and message envelopes may carry the larger, base64 attachment payload.
 // Other tools retain their existing 1 MiB limit, including malformed envelopes.
-app.use('*', bodyLimit({ maxSize: MAX_MCP_CREATION_REQUEST_BYTES }));
+app.use('*', bodyLimit({ maxSize: MAX_MCP_ATTACHMENT_REQUEST_BYTES }));
 app.use('*', async (c, next) => {
     if (c.req.raw.body) {
         const body = await c.req.raw.clone().arrayBuffer();
         if (body.byteLength > 1024 * 1024) {
-            let creation = false;
+            let attachmentTool = false;
             try {
                 const envelope = JSON.parse(new TextDecoder().decode(body));
-                creation = envelope?.method === 'tools/call' && envelope?.params?.name === 'create_workspace';
+                attachmentTool =
+                    envelope?.method === 'tools/call' &&
+                        (envelope?.params?.name === 'create_workspace' ||
+                            (envelope?.params?.name === 'send_workspace_message' &&
+                                Array.isArray(envelope?.params?.arguments?.attachments) &&
+                                envelope.params.arguments.attachments.length > 0));
             }
             catch {
                 /* Preserve the normal body-size rejection for malformed input. */
             }
-            if (!creation)
+            if (!attachmentTool)
                 return c.json({ error: 'MCP request is too large' }, 413);
         }
     }
@@ -64,7 +70,7 @@ app.all('/', async (c) => {
     const transport = new WebStandardStreamableHTTPServerTransport({
         sessionIdGenerator: undefined,
         enableJsonResponse: true,
-        maxRequestBodySize: MAX_MCP_CREATION_REQUEST_BYTES,
+        maxRequestBodySize: MAX_MCP_ATTACHMENT_REQUEST_BYTES,
     });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: [

package/dist/server/services/dev-server-service.js

@@ -1,10 +1,11 @@
 import { execFile, spawn } from 'node:child_process';
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { resolveInstance, sanitizeBranchName } from '../utils/dev-server-instance.js';
 import { assertWorkspaceLifecycleAvailable } from '../utils/workspace-lifecycle-guard.js';
 import { getProjectSettings } from './settings-service.js';
 import { emitEphemeral } from './websocket-service.js';
 import { getWorkspace, listWorkspaces, updateDevServerStatus } from './workspace-service.js';
+export { parseEnvFile, resolveInstance, sanitizeBranchName } from '../utils/dev-server-instance.js';
 // ── Helpers ───────────────────────────────────────────────────────────────────
 /** Build a clean env for child processes, stripping Kobo-specific variables. */
 function cleanEnv() {
@@ -37,63 +38,6 @@ export function _resetTrackedProcessesForTests() {
     generations.clear();
     shuttingDown = false;
 }
-// ── Pure helpers ───────────────────────────────────────────────────────────────
-/**
- * Sanitize a branch name for use as a Docker instance name.
- * Replace `/` and `_` with `-`, lowercase.
- */
-export function sanitizeBranchName(branch) {
-    return branch.toLowerCase().replace(/[/_]/g, '-');
-}
-/**
- * Parse a `.env` file content into key=value pairs.
- * Skips empty lines and comments (#). Handles quotes.
- */
-export function parseEnvFile(content) {
-    const result = {};
-    for (const line of content.split('\n')) {
-        const trimmed = line.trim();
-        if (!trimmed || trimmed.startsWith('#'))
-            continue;
-        const eqIndex = trimmed.indexOf('=');
-        if (eqIndex === -1)
-            continue;
-        const key = trimmed.slice(0, eqIndex).trim();
-        let value = trimmed.slice(eqIndex + 1).trim();
-        // Strip surrounding quotes
-        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-            value = value.slice(1, -1);
-        }
-        result[key] = value;
-    }
-    return result;
-}
-/**
- * Resolve the dev-server instance config for a given project + branch.
- * Looks in `<projectPath>/.container/instances/` for `.env` files.
- */
-export function resolveInstance(projectPath, workingBranch) {
-    const instancesDir = path.join(projectPath, '.container', 'instances');
-    if (!existsSync(instancesDir))
-        return null;
-    const sanitized = sanitizeBranchName(workingBranch);
-    const files = readdirSync(instancesDir).filter((f) => f.endsWith('.env'));
-    for (const file of files) {
-        const content = readFileSync(path.join(instancesDir, file), 'utf-8');
-        const parsed = parseEnvFile(content);
-        if (parsed.INSTANCE_NAME &&
-            parsed.INSTANCE_NAME.toLowerCase() === sanitized &&
-            parsed.PROJECT_NAME &&
-            /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(parsed.PROJECT_NAME)) {
-            return {
-                instanceName: parsed.INSTANCE_NAME,
-                projectName: parsed.PROJECT_NAME,
-                httpPort: parsed.HTTP_PORT ?? '',
-            };
-        }
-    }
-    return null;
-}
 // ── Docker helpers ─────────────────────────────────────────────────────────────
 /**
  * List all running Docker container names.

package/dist/server/services/lifecycle-hook-service.js

@@ -3,7 +3,6 @@ import { getDb } from '../db/index.js';
 import { slugifyProjectName } from '../utils/project-slug.js';
 import { runScript } from '../utils/script-runner.js';
 import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
-import { resolveInstance, sanitizeBranchName } from './dev-server-service.js';
 import { getEffectiveSettings, getGlobalSettings, getProjectSettings } from './settings-service.js';
 import { listWorkspaces } from './workspace-service.js';
 export const SHUTDOWN_SCRIPT_TIMEOUT_MS = 60_000;
@@ -55,7 +54,6 @@ export async function runLifecycleHook(event, workspaceId, extraEnv) {
             }
             return null;
         }
-        const instance = event === 'kobo-shutdown' ? resolveInstance(row.project_path, row.working_branch) : null;
         return await runScript({
             workspaceId,
             worktreePath,
@@ -70,12 +68,6 @@ export async function runLifecycleHook(event, workspaceId, extraEnv) {
                 branchName: row.working_branch,
                 sourceBranch: row.source_branch,
                 projectPath: row.project_path,
-                ...(event === 'kobo-shutdown'
-                    ? {
-                        projectName: instance?.projectName ?? '',
-                        instanceName: instance?.instanceName ?? sanitizeBranchName(row.working_branch),
-                    }
-                    : {}),
             },
             extraEnv: { ...extraEnv, KOBO_HOOK_EVENT: event },
         });

package/dist/server/services/mcp-message-delivery-service.js

@@ -4,7 +4,7 @@ import { broadcastPersistedEvent, persistWorkspaceEvent } from './websocket-serv
 import { deliverWorkspaceMessage } from './workspace-message-service.js';
 export async function deliverKeyedMcpMessage(workspaceId, key, message) {
     const db = getDb();
-    const request = reserveMessageRequest(db, workspaceId, key, message.content, message.sessionId);
+    const request = reserveMessageRequest(db, workspaceId, key, message.content, message.sessionId, message.attachments);
     if (!request.fresh)
         return request.result;
     let dispatched = false;

package/dist/server/services/mcp-message-request-service.js

@@ -1,9 +1,15 @@
 import { createHash } from 'node:crypto';
 import { nanoid } from 'nanoid';
-export function reserveMessageRequest(db, workspaceId, key, content, sessionId) {
-    const fingerprint = createHash('sha256')
-        .update(JSON.stringify([content, sessionId ?? null]))
-        .digest('hex');
+export function reserveMessageRequest(db, workspaceId, key, content, sessionId, attachments) {
+    // Keep text-only fingerprints compatible with receipts issued before attachment support.
+    const identity = [content, sessionId ?? null];
+    if (attachments?.length)
+        identity.push(attachments.map((file) => [
+            file.name,
+            file.mime_type,
+            createHash('sha256').update(file.data_base64).digest('hex'),
+        ]));
+    const fingerprint = createHash('sha256').update(JSON.stringify(identity)).digest('hex');
     return db
         .transaction(() => {
         const requestId = `mcp-${nanoid()}`;
@@ -23,7 +29,7 @@ export function reserveMessageRequest(db, workspaceId, key, content, sessionId)
                 accepted: false,
                 requestId: row.request_id,
                 code: 'idempotency_conflict',
-                message: 'This key was already used for different content or a different session',
+                message: 'This key was already used for different content, session or attachments',
             };
         else if (row.result_json) {
             result = JSON.parse(row.result_json);

package/dist/server/services/settings-service.js

@@ -1010,6 +1010,14 @@ const settingsMigrations = [
             }
         },
     },
+    {
+        version: 67,
+        name: 'opt-in-immediate-chat-messages',
+        migrate: ({ global }) => {
+            if (typeof global.forceImmediateMessages !== 'boolean')
+                global.forceImmediateMessages = false;
+        },
+    },
 ];
 /** Current settings schema version — always equals the highest migration version. */
 export const SETTINGS_SCHEMA_VERSION = settingsMigrations.length > 0 ? settingsMigrations[settingsMigrations.length - 1].version : 0;
@@ -1067,6 +1075,7 @@ function defaultSettings() {
             autoPurgeOnPrMerged: false,
             autoLoopMaxRetries: 5,
             agentWatchdogEnabled: false,
+            forceImmediateMessages: false,
             showProgressBars: true,
             stopDevServersOnShutdown: true,
             awaitingUserReminderMinutes: 0,
@@ -1218,6 +1227,8 @@ export function runSettingsMigrations(raw) {
     current.global.workflowPolicy = resolveWorkflowPolicy(current.global.workflowPolicy);
     if (!isMemoryMode(current.global.memoryMode))
         current.global.memoryMode = 'hybrid';
+    if (typeof current.global.forceImmediateMessages !== 'boolean')
+        current.global.forceImmediateMessages = false;
     if (typeof current.global.showProgressBars !== 'boolean')
         current.global.showProgressBars = true;
     if (typeof current.global.stopDevServersOnShutdown !== 'boolean')
@@ -1588,6 +1599,9 @@ export function updateGlobalSettings(input) {
     if ('stopDevServersOnShutdown' in data && typeof data.stopDevServersOnShutdown !== 'boolean') {
         delete data.stopDevServersOnShutdown;
     }
+    if ('forceImmediateMessages' in data && typeof data.forceImmediateMessages !== 'boolean') {
+        delete data.forceImmediateMessages;
+    }
     if ('showProgressBars' in data && typeof data.showProgressBars !== 'boolean') {
         delete data.showProgressBars;
     }
@@ -1659,6 +1673,7 @@ export function updateGlobalSettings(input) {
         'autoPurgeOnPrMerged',
         'autoLoopMaxRetries',
         'agentWatchdogEnabled',
+        'forceImmediateMessages',
         'showProgressBars',
         'stopDevServersOnShutdown',
         'awaitingUserReminderMinutes',

package/dist/server/services/workspace-dialogue-service.js

@@ -85,6 +85,7 @@ export async function executeWorkspaceDialogueTool(name, input, source = createM
     if (name === 'send_workspace_message' && args.idempotency_key)
         return deliverKeyedMcpMessage(workspaceId, args.idempotency_key, {
             content: args.content,
+            ...(args.attachments ? { attachments: args.attachments } : {}),
             sessionId: args.session_id,
             source,
         });
@@ -93,6 +94,7 @@ export async function executeWorkspaceDialogueTool(name, input, source = createM
             accepted: true,
             ...(await deliverWorkspaceMessage(workspaceId, {
                 content: args.content,
+                ...(args.attachments ? { attachments: args.attachments } : {}),
                 sessionId: args.session_id,
                 clientMessageId: `mcp-${nanoid()}`,
                 source,

package/dist/server/services/workspace-message-service.js

@@ -1,5 +1,7 @@
-import { assertWorkspaceLifecycleAvailable } from '../utils/workspace-lifecycle-guard.js';
+import { validateMcpAttachments } from '../../shared/mcp-attachments.js';
+import { assertWorkspaceLifecycleAvailable, withWorkspaceLifecycleGuard } from '../utils/workspace-lifecycle-guard.js';
 import { isAgentUnavailableError, isShuttingDown, sendMessage, startAgent } from './agent/orchestrator.js';
+import { attachmentReference, removeAttachments, saveAttachments } from './attachment-service.js';
 import { hasLoopMessage } from './auto-loop-message-service.js';
 import * as autoLoop from './auto-loop-service.js';
 import { createChatReceipt } from './chat-receipt-service.js';
@@ -7,10 +9,28 @@ import { emitEphemeral } from './websocket-service.js';
 import { getActiveSession, getWorkspace, updateWorkspaceStatus } from './workspace-service.js';
 /** Shared delivery for WebSocket chat and external MCP clients. */
 export async function deliverWorkspaceMessage(workspaceId, message, hooks) {
+    // Keep the caller's original content unchanged for durable idempotency fingerprints.
+    message = { ...message };
     const receipt = createChatReceipt(workspaceId, message, hooks?.persist);
+    let saved = [];
+    let attachmentWorktree;
+    let dispatched = false;
+    const beforeDispatch = () => {
+        if (saved.length) {
+            assertWorkspaceLifecycleAvailable(workspaceId);
+            const current = getWorkspace(workspaceId);
+            if (!current || current.archivedAt || current.worktreePurgedAt || current.worktreePath !== attachmentWorktree)
+                throw new Error('Workspace changed before attachment delivery');
+            if (current.status === 'compacting' || current.status === 'awaiting-user' || isShuttingDown())
+                throw new Error('Workspace is not ready to receive a message');
+        }
+        hooks?.beforeDispatch?.();
+        dispatched = true;
+    };
     let reason;
     try {
-        if (!message.content.trim())
+        const attachments = validateMcpAttachments(message.attachments);
+        if (!message.content.trim() && !attachments.length)
             throw new Error('Message content must not be empty');
         if (isShuttingDown())
             throw new Error('Kōbō is shutting down');
@@ -21,6 +41,8 @@ export async function deliverWorkspaceMessage(workspaceId, message, hooks) {
         if (workspace.archivedAt || workspace.worktreePurgedAt)
             throw new Error('Restore the workspace before sending a message');
         if (message.delivery === 'next_iteration') {
+            if (attachments.length)
+                throw new Error('Attachments require immediate delivery');
             if (!message.clientMessageId)
                 throw new Error('clientMessageId is required for queued delivery');
             const acceptedBefore = hasLoopMessage(workspaceId, message.clientMessageId);
@@ -45,11 +67,28 @@ export async function deliverWorkspaceMessage(workspaceId, message, hooks) {
             reason = 'awaiting-user';
             throw new Error('Answer the pending question or permission request before sending a chat message');
         }
+        if (attachments.length) {
+            attachmentWorktree = workspace.worktreePath;
+            await withWorkspaceLifecycleGuard(workspaceId, async () => {
+                const files = attachments.map((file) => new File([Buffer.from(file.data_base64, 'base64')], file.name, { type: file.mime_type }));
+                saved = await saveAttachments(workspace.worktreePath, files);
+            });
+            assertWorkspaceLifecycleAvailable(workspaceId);
+            const current = getWorkspace(workspaceId);
+            if (!current || current.archivedAt || current.worktreePurgedAt || current.worktreePath !== attachmentWorktree)
+                throw new Error('Workspace changed while saving attachments');
+            if (current.status === 'compacting' || current.status === 'awaiting-user' || isShuttingDown())
+                throw new Error('Workspace is not ready to receive a message');
+            message.content = [message.content.trim(), ...saved.map(attachmentReference)].filter(Boolean).join('\n\n');
+            // Binary data never belongs in the chat receipt or agent prompt.
+            delete message.attachments;
+        }
+        const trackDispatch = !!hooks?.beforeDispatch || saved.length > 0;
         const loop = autoLoop.getStatus(workspaceId);
         let sessionId = message.sessionId ?? getActiveSession(workspaceId)?.id;
         try {
-            if (hooks?.beforeDispatch)
-                await sendMessage(workspaceId, message.content, message.sessionId, hooks.beforeDispatch);
+            if (trackDispatch)
+                await sendMessage(workspaceId, message.content, message.sessionId, beforeDispatch);
             else
                 await sendMessage(workspaceId, message.content, message.sessionId);
         }
@@ -61,7 +100,7 @@ export async function deliverWorkspaceMessage(workspaceId, message, hooks) {
             const current = getWorkspace(workspaceId);
             if (!current || current.archivedAt || current.worktreePurgedAt)
                 throw new Error('Workspace is unavailable');
-            const started = startAgent(workspaceId, current.worktreePath, message.content, current.model, true, message.agentPermissionModeOverride ?? current.agentPermissionMode, message.sessionId, current.reasoningEffort, ...(hooks?.beforeDispatch ? [hooks.beforeDispatch] : []));
+            const started = startAgent(workspaceId, current.worktreePath, message.content, current.model, true, message.agentPermissionModeOverride ?? current.agentPermissionMode, message.sessionId, current.reasoningEffort, ...(trackDispatch ? [beforeDispatch] : []));
             updateWorkspaceStatus(workspaceId, 'executing');
             sessionId = message.sessionId ?? started.agentSessionId;
         }
@@ -71,6 +110,23 @@ export async function deliverWorkspaceMessage(workspaceId, message, hooks) {
         return { sessionId };
     }
     catch (error) {
+        // Once dispatch may have happened, keep files available to the agent even if
+        // acknowledgement failed. Only remove files from a definitively rejected send.
+        if (saved.length && attachmentWorktree && !dispatched) {
+            const worktree = attachmentWorktree;
+            try {
+                await withWorkspaceLifecycleGuard(workspaceId, async () => {
+                    const current = getWorkspace(workspaceId);
+                    if (!current || current.worktreePurgedAt || current.worktreePath !== worktree)
+                        return;
+                    for (const warning of await removeAttachments(worktree, saved))
+                        console.warn(`[message-attachments] ${warning}`);
+                });
+            }
+            catch {
+                // A competing lifecycle operation owns the checkout now; do not touch it.
+            }
+        }
         receipt.reject(error instanceof Error ? error.message : String(error), reason);
         throw error;
     }

package/dist/server/utils/dev-server-instance.js

@@ -0,0 +1,58 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Sanitize a branch name for use as a Docker instance name.
+ * Replace `/` and `_` with `-`, lowercase.
+ */
+export function sanitizeBranchName(branch) {
+    return branch.toLowerCase().replace(/[/_]/g, '-');
+}
+/**
+ * Parse a `.env` file content into key=value pairs.
+ * Skips empty lines and comments (#). Handles quotes.
+ */
+export function parseEnvFile(content) {
+    const result = {};
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const eqIndex = trimmed.indexOf('=');
+        if (eqIndex === -1)
+            continue;
+        const key = trimmed.slice(0, eqIndex).trim();
+        let value = trimmed.slice(eqIndex + 1).trim();
+        // Strip surrounding quotes
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        result[key] = value;
+    }
+    return result;
+}
+/**
+ * Resolve the dev-server instance config for a given project + branch.
+ * Looks in `<projectPath>/.container/instances/` for `.env` files.
+ */
+export function resolveInstance(projectPath, workingBranch) {
+    const instancesDir = path.join(projectPath, '.container', 'instances');
+    if (!existsSync(instancesDir))
+        return null;
+    const sanitized = sanitizeBranchName(workingBranch);
+    const files = readdirSync(instancesDir).filter((f) => f.endsWith('.env'));
+    for (const file of files) {
+        const content = readFileSync(path.join(instancesDir, file), 'utf-8');
+        const parsed = parseEnvFile(content);
+        if (parsed.INSTANCE_NAME &&
+            parsed.INSTANCE_NAME.toLowerCase() === sanitized &&
+            parsed.PROJECT_NAME &&
+            /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(parsed.PROJECT_NAME)) {
+            return {
+                instanceName: parsed.INSTANCE_NAME,
+                projectName: parsed.PROJECT_NAME,
+                httpPort: parsed.HTTP_PORT ?? '',
+            };
+        }
+    }
+    return null;
+}

package/dist/server/utils/script-runner.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import * as wsService from '../services/websocket-service.js';
+import { resolveInstance, sanitizeBranchName } from './dev-server-instance.js';
 import { getIndexLockPath } from './git-ops.js';
 import { ensureDirectoryInside } from './safe-path.js';
 /** Default wall-clock budget for a user script before it is force-killed. */
@@ -39,6 +40,8 @@ export function runScript(opts) {
         scriptDirectory = fs.mkdtempSync(path.join(storage, '.script-'));
         scriptPath = path.join(scriptDirectory, path.basename(tmpFileName));
         fs.writeFileSync(scriptPath, script, { mode: 0o700, flag: 'wx' });
+        // Resolve only from this workspace's persisted instance, never the host's env.
+        const instance = env?.projectPath && env.branchName ? resolveInstance(env.projectPath, env.branchName) : null;
         const proc = spawn('bash', [scriptPath], {
             cwd: worktreePath,
             env: {
@@ -49,8 +52,8 @@ export function runScript(opts) {
                 BRANCH_NAME: env?.branchName ?? '',
                 SOURCE_BRANCH: env?.sourceBranch ?? '',
                 PROJECT_PATH: env?.projectPath ?? '',
-                ...(env?.projectName !== undefined ? { PROJECT_NAME: env.projectName } : {}),
-                ...(env?.instanceName !== undefined ? { INSTANCE: env.instanceName } : {}),
+                PROJECT_NAME: instance?.projectName ?? '',
+                INSTANCE: instance?.instanceName ?? sanitizeBranchName(env?.branchName ?? ''),
             },
             stdio: ['ignore', 'pipe', 'pipe'],
             // Detached so this is the leader of its own process group: a script