specrails-desktop 2.18.2 → 2.19.0

package/docs/running-pipelines.md

@@ -21,7 +21,7 @@ SpecsBoard (left)            Rails (right)
 
 A **rail** is an execution lane. Drag a spec card from the SpecsBoard onto a rail and press **▶ Play** to launch the pipeline. Rails let you organise and queue work into named lanes.
 
-Rails run on **Claude** by default. If your project has more than one provider installed, a per-rail engine selector lets you launch a rail on **Codex** or **Gemini** instead — see [Using Codex](codex.md) and [Using Gemini](gemini.md). Only the **Ultracode** loop is Claude-only; the standard Implement and Batch loops run on any installed provider.
+Rails run on **Claude** by default. If your project has more than one provider installed, a per-rail engine selector lets you launch a rail on **Codex** or **Gemini** instead — see [Using Codex](codex.md) and [Using Gemini](gemini.md). Only the **Freestyle** loop is Claude-only; the standard Implement and Batch loops run on any installed provider.
 
 > **One job at a time per project.** Each project has a single queue, so within a project only one rail job runs at a time; the rest queue behind it. Real parallelism is **across projects** — open two projects and their rails run independently. See [Running multiple rails](#running-multiple-rails).
 
@@ -31,7 +31,7 @@ Each rail has a header with:
 
 - **Status pill** — `idle`, `running`, or `failed`. (There's no separate "completed" state — a rail returns to `idle` when its job finishes cleanly.)
 - **Spec list** — the IDs of the specs assigned to this rail. Drag in more, drag out to detach. You can also use the **Move to rail** popover from a spec card; it shows a status dot per rail so you don't push work onto a busy lane.
-- **Loop picker** — the **Loop** this rail runs: a built-in (`Implement`, `Batch`, or `Ultracode`) or one of your published custom loops. See [Loops](#loops).
+- **Loop picker** — the **Loop** this rail runs: a built-in (`Implement`, `Batch`, or `Freestyle`) or one of your published custom loops. See [Loops](#loops).
 - **Profile picker** — which agent profile this rail uses. This only appears once the project has **at least one** profile (create them on the Agents page). When present, `No profile` runs the rail in legacy mode.
 - **Engine selector** — pick which installed provider (Claude, Codex, or Gemini) runs this rail. Only renders on projects with more than one provider installed.
 - **Play / Stop button** — start or cancel.
@@ -44,7 +44,7 @@ A rail runs a **Loop**, picked in the rail header and persisted per rail. The th
 |------|---------|--------------|
 | **Implement** | `/specrails:implement` | One job covering all the specs on the rail. Runs the full Architect → Developer → Reviewer → Ship pipeline. |
 | **Batch** | `/specrails:batch-implement` | One job that works through the rail's specs sequentially, in dependency-aware waves. |
-| **Ultracode** | (Ultracode) | Claude implements each spec autonomously, **bypassing** the OpenSpec pipeline. One independent job per spec. Claude only. |
+| **Freestyle** | (Freestyle) | Claude implements each spec autonomously, **bypassing** the OpenSpec pipeline. One independent job per spec. Claude only. |
 
 Beyond the built-ins, the **Loops** section (left sidebar, above the project list) is a global, n8n-style **visual builder** shared across all your projects. A loop is a graph of typed steps:
 
@@ -76,17 +76,17 @@ Each phase is a specialised agent invoked by the rail's engine (Claude, Codex, o
 
 In plain terms: the project's **agent profile** decides which AI agent handles each phase. The baseline trio (`sr-architect`, `sr-developer`, `sr-reviewer`) is always present; a profile's routing rules can add extra agents or swap which one runs a phase. The phase progress bar only renders when the command defines phases. For the full format, see [internals/profiles.md](internals/profiles.md).
 
-### Ultracode
+### Freestyle
 
-`Ultracode` is a Claude-only loop that skips the Architect → Developer → Reviewer → Ship pipeline entirely. Instead of orchestrating the agent chain, it hands Claude a configurable pre-prompt plus the full spec text and lets it work autonomously with its native tools.
+`Freestyle` (mode value `ultracode` on the API — its original name) is a Claude-only loop that skips the Architect → Developer → Reviewer → Ship pipeline entirely. Instead of orchestrating the agent chain, it hands Claude a configurable pre-prompt plus the full spec text and lets it work autonomously with its native tools.
 
-- **One job per spec.** If the rail has three specs, `Ultracode` launches three independent jobs.
+- **One job per spec.** If the rail has three specs, `Freestyle` launches three independent jobs.
 - **Variable cost.** Because the run is open-ended, pressing Play opens a confirmation dialog before anything spawns.
-- **Model picker.** A per-rail control lets you pick **Haiku / Sonnet / Opus** (default Sonnet) for the Ultracode run.
-- **Claude only.** The Ultracode loop and its model picker are offered only when the rail's engine is Claude. Codex and Gemini rails can't run Ultracode, and agent profiles don't apply to Ultracode rails.
-- **Interactive (optional).** An `Interactive` toggle next to the Ultracode launch turns the run into a back-and-forth session: you can chat with the running job, send follow-up prompts, and click **Finalize** when you're done. Without it, the job runs to completion on its own. (Available when the rail is idle; can be disabled server-side via `SPECRAILS_INTERACTIVE_JOBS=false`.)
+- **Model picker.** A per-rail control lets you pick **Haiku / Sonnet / Opus** (default Sonnet) for the Freestyle run.
+- **Claude only.** The Freestyle loop and its model picker are offered only when the rail's engine is Claude. Codex and Gemini rails can't run Freestyle, and agent profiles don't apply to Freestyle rails.
+- **Interactive (optional).** An `Interactive` toggle next to the Freestyle launch turns the run into a back-and-forth session: you can chat with the running job, send follow-up prompts, and click **Finalize** when you're done. Without it, the job runs to completion on its own. (Available when the rail is idle; can be disabled server-side via `SPECRAILS_INTERACTIVE_JOBS=false`.)
 
-You can customise the Ultracode pre-prompt per project on the [Settings page](customizing.md#ultracode-pre-prompt).
+You can customise the Freestyle pre-prompt per project on the [Settings page](customizing.md#freestyle-pre-prompt).
 
 ### Running multiple rails
 

package/docs/tracking-cost.md

@@ -8,7 +8,7 @@ Six surfaces, all per-project:
 
 | Surface | What it captures |
 |---------|------------------|
-| **`job`** | Every rail run (the Architect → Developer → Reviewer → Ship pipeline, plus Ultracode and Batch runs) |
+| **`job`** | Every rail run (the Architect → Developer → Reviewer → Ship pipeline, plus Freestyle and Batch runs) |
 | **`quick-spec`** | One-shot Quick spec generation (including a Quick-mode Contract Refine run) |
 | **`explore-spec`** | Every Explore conversation turn (including the Explore Contract Refine run) |
 | **`ai-edit`** | The **AI Edit / Refine** overlay (refining an agent or a ticket) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.18.2",
+  "version": "2.19.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/server/dist/agent-chat-manager.js

@@ -4,41 +4,22 @@ exports.AgentChatManager = void 0;
 const providers_1 = require("./providers");
 const spawn_lifecycle_1 = require("./spawn-lifecycle");
 const agent_cwd_manager_1 = require("./agent-cwd-manager");
+const agent_operator_prompt_1 = require("./agent-operator-prompt");
 const agent_mcp_config_1 = require("./agent-mcp-config");
 const agent_tier_1 = require("./agent-tier");
+const attachment_manager_1 = require("./attachment-manager");
 const agent_store_1 = require("./agent-store");
+const explore_draft_title_1 = require("./explore-draft-title");
 const types_1 = require("./mcp/tools/types");
-// ─── AgentChatManager (design D1) ─────────────────────────────────────────────
-//
-// App-level sibling of ChatManager: spawns an AI CLI from the app-owned agent cwd
-// with the Specrails MCP bridge as its tool source, streams the turn over the
-// app-global `agent_*` WS events (no projectId — fans to all subscribers), and
-// persists to the app registry DB. It reuses the shared spawn→stream→settle core
-// (runAiCliInvocation) rather than re-implementing ChatManager's loop.
-const OPERATOR_SYSTEM_PROMPT = 'You are the Specrails operator agent. Drive the Specrails Desktop app on the ' +
-    "user's behalf using the specrails_* MCP tools. Target a project with " +
-    'specrails_select_project (or the projectId argument); if none is selected and ' +
-    'the request is project-specific, ask whether to create a project or search all. ' +
-    'Follow HTTP-202 actions to completion with specrails_watch. Respect the ' +
-    'permission ladder: if a tool is refused for the current level, tell the user ' +
-    'which level it needs rather than working around it. Be concise; report tool ' +
-    'outputs faithfully, including failures. Format replies for easy reading: ' +
-    'separate distinct ideas into short paragraphs with a blank line between them ' +
-    '(not one dense block), and use bullet lists for enumerations. ' +
-    'When the user has no projects yet, or wants to add one, first explain the UI ' +
-    'steps (click "Add Project" / the + in the left sidebar, enter the repo\'s ' +
-    'folder path, pick an AI provider, then run setup), THEN offer to do it for ' +
-    'them from here: ask for the repo folder path and which AI providers to set up, ' +
-    'then with their go-ahead call specrails_setup add_project (Edit level) and a ' +
-    'single specrails_setup install (Operate level) — one install provisions ALL the ' +
-    'chosen providers in one shot (no need to install them one by one). Setup is ' +
-    'QUICK-only (offline); do NOT offer or mention a "full" or "enrich" install. Use ' +
-    'specrails_setup prerequisites / available_providers first to check the machine.';
 class AgentChatManager {
     _broadcast;
     _db;
     _port;
     _active = new Map();
+    /** Conversations with a turn in-flight but not yet spawned. Closes the TOCTOU
+     *  window the attachment-extraction await opens between the busy guard and
+     *  `_active.set` in onSpawn (mirrors ChatManager's reservation pattern). */
+    _reserved = new Set();
     constructor(broadcast, db, port) {
         this._broadcast = broadcast;
         this._db = db;
@@ -59,10 +40,20 @@ class AgentChatManager {
             this._emitError(conversationId, 'Unknown conversation');
             return;
         }
-        if (this._active.has(conversationId)) {
+        if (this._active.has(conversationId) || this._reserved.has(conversationId)) {
             this._emitError(conversationId, 'The agent is busy. Try again in a moment.');
             return;
         }
+        this._reserved.add(conversationId);
+        try {
+            await this._runTurn(conversation, userText, options);
+        }
+        finally {
+            this._reserved.delete(conversationId);
+        }
+    }
+    async _runTurn(conversation, userText, options) {
+        const conversationId = conversation.id;
         const tierLevel = (0, agent_tier_1.normalizeLevel)(options.tierLevel ?? conversation.tier_level);
         const adapter = (0, providers_1.getAdapter)(conversation.provider);
         // Resolve a model that is VALID for this provider. A stale model from another
@@ -71,15 +62,63 @@ class AgentChatManager {
         const catalog = new Set(adapter.modelCatalog().map((m) => m.value));
         const requested = options.model || conversation.model;
         const model = requested && catalog.has(requested) ? requested : adapter.defaultModel();
+        // Reasoning effort: stored per conversation; null = the app default
+        // ("medium"). Passed only to providers with a per-spawn knob, and only when
+        // the value is in the provider's catalog (a provider switch clears it, but
+        // belt-and-braces against stale rows).
+        const efforts = (adapter.capabilities.reasoningEfforts ?? []);
+        const storedEffort = conversation.reasoning_effort;
+        const reasoningEffort = efforts.length
+            ? (storedEffort && efforts.includes(storedEffort) ? storedEffort : 'medium')
+            : undefined;
         // Make the pinned project (Cursor-style selector) the MCP active project for
         // this turn, so project-scoped tools resolve without the agent having to call
         // specrails_select_project. Home (null) clears it → app-global mode.
         (0, types_1.setActiveProject)(conversation.pinned_project_id ?? null);
-        (0, agent_store_1.addAgentMessage)(this._db, { conversationId, role: 'user', content: userText });
-        // Tell the agent which project is pinned (so it phrases + passes projectId).
-        const prompt = conversation.pinned_project_id
-            ? `[Active project: projectId="${conversation.pinned_project_id}". Use it for project-scoped tools unless told otherwise.]\n\n${userText}`
-            : userText;
+        // Resolve attachments (conversation-keyed) into extracted text blocks +
+        // absolute image paths. Extraction failure degrades to a text-only turn.
+        const attachmentIds = options.attachmentIds ?? [];
+        let userWithAttachments = userText;
+        let imagePaths = [];
+        let hasAttachments = false;
+        if (attachmentIds.length > 0) {
+            try {
+                const resolved = await attachment_manager_1.attachmentManager.getClaudeArgsAgent(conversationId, attachmentIds);
+                if (resolved.textBlocks.length > 0) {
+                    userWithAttachments = `${userText}\n\n## Attached Resources\n\n${resolved.textBlocks.join('\n\n')}`;
+                    hasAttachments = true;
+                }
+                imagePaths = resolved.imagePaths;
+            }
+            catch (err) {
+                console.error(`[agent-chat] attachment extraction failed (${conversationId}):`, err);
+            }
+        }
+        // The conversation may have been deleted while attachments were extracting
+        // (DELETE aborts the child and drops the row) — inserting would violate the FK.
+        if (!(0, agent_store_1.getAgentConversation)(this._db, conversationId))
+            return;
+        (0, agent_store_1.addAgentMessage)(this._db, { conversationId, role: 'user', content: userText, attachmentIds });
+        this._autoTitle(conversationId, conversation.title);
+        // Providers WITHOUT a --system-prompt flag (codex, gemini) drop opts.systemPrompt
+        // for chat turns, so the attachment prompt-injection note would never reach them —
+        // fold it into the user turn instead (same capability-gated pattern as ChatManager).
+        if (hasAttachments && !adapter.capabilities.systemPromptArg) {
+            userWithAttachments = `${attachment_manager_1.USER_ATTACHMENT_SYSTEM_NOTE}\n\n${userWithAttachments}`;
+        }
+        // Per-turn dynamic context (pinned project, permission level, provider) rides
+        // the USER turn, never the system prompt — byte-stability contract (see
+        // agent-operator-prompt.ts).
+        const contextPrefix = conversation.pinned_project_id
+            ? `[Active project: projectId="${conversation.pinned_project_id}" | Permission level: ${tierLevel} | Provider: ${adapter.id}. Use the project for project-scoped tools unless told otherwise.]`
+            : `[No project pinned (Home) | Permission level: ${tierLevel} | Provider: ${adapter.id}]`;
+        const prompt = `${contextPrefix}\n\n${userWithAttachments}`;
+        const systemPrompt = hasAttachments
+            ? `${agent_operator_prompt_1.OPERATOR_SYSTEM_PROMPT}\n\n${attachment_manager_1.USER_ATTACHMENT_SYSTEM_NOTE}`
+            : agent_operator_prompt_1.OPERATOR_SYSTEM_PROMPT;
+        // Only pass native image paths to providers that can vision-load them (codex
+        // `--image`); claude/gemini already have the `@path` ref folded into prompt.
+        const spawnImagePaths = adapter.capabilities.supportsImageInput ? imagePaths : undefined;
         const cwd = (0, agent_cwd_manager_1.ensureAgentCwd)();
         let mcpArgs = [];
         let mcpEnv = {};
@@ -114,10 +153,12 @@ class AgentChatManager {
                 env: { ...process.env, ...mcpEnv },
                 buildOpts: {
                     prompt,
-                    systemPrompt: adapter.capabilities.systemPromptArg ? OPERATOR_SYSTEM_PROMPT : undefined,
+                    systemPrompt: adapter.capabilities.systemPromptArg ? systemPrompt : undefined,
                     model,
                     sessionId: useResume ? conversation.session_id ?? undefined : undefined,
                     extraArgs: mcpArgs,
+                    imagePaths: spawnImagePaths,
+                    reasoning_effort: reasoningEffort,
                 },
                 onSpawn: (child) => {
                     this._active.set(conversationId, child);
@@ -160,6 +201,10 @@ class AgentChatManager {
         };
         const canResume = !!conversation.session_id && adapter.capabilities.nativeResume;
         let r = await invoke(canResume);
+        // Deleted mid-turn (DELETE aborts the child and drops the row): stop here —
+        // no auto-heal respawn, no FK-violating assistant INSERT.
+        if (!(0, agent_store_1.getAgentConversation)(this._db, conversationId))
+            return;
         // Auto-heal a stale/foreign session: a resume that produced no text (e.g. a
         // provider switch leaving another provider's session id, or codex
         // "no rollout found for thread id") retries once as a fresh turn.
@@ -167,6 +212,8 @@ class AgentChatManager {
             console.log(`[agent-chat] resume produced no text — retrying fresh conv=${conversationId}`);
             (0, agent_store_1.updateAgentConversation)(this._db, conversationId, { session_id: null });
             r = await invoke(false);
+            if (!(0, agent_store_1.getAgentConversation)(this._db, conversationId))
+                return;
         }
         if (r.spawnFailed) {
             this._emitError(conversationId, `Failed to launch ${adapter.binary}. Is it installed and on PATH?`);
@@ -191,6 +238,33 @@ class AgentChatManager {
             (r.code !== 0 ? `${adapter.binary} exited with code ${r.code}` : 'The agent returned no output.');
         this._emitError(conversationId, reason);
     }
+    /**
+     * Auto-title a conversation from its first TWO user prompts (deterministic —
+     * no AI spend). Turn 1 sets the title when none exists; turn 2 refines it,
+     * but ONLY while the current title is still turn 1's auto title (a manual
+     * rename is recomputable-detectable and never clobbered). Broadcasts
+     * `agent_title` so the sidebar list updates live.
+     */
+    _autoTitle(conversationId, currentTitle) {
+        try {
+            const userMsgs = (0, agent_store_1.listAgentMessages)(this._db, conversationId).filter((m) => m.role === 'user');
+            if (userMsgs.length === 0 || userMsgs.length > 2)
+                return;
+            const autoFromFirst = (0, explore_draft_title_1.generateAutoTitle)([{ role: 'user', content: userMsgs[0].content }]);
+            const stillAuto = currentTitle === null || (userMsgs.length === 2 && currentTitle === autoFromFirst);
+            if (!stillAuto)
+                return;
+            const source = userMsgs.map((m) => m.content).join(' — ');
+            const title = (0, explore_draft_title_1.generateAutoTitle)([{ role: 'user', content: source }]);
+            if (!title || title === currentTitle)
+                return;
+            (0, agent_store_1.updateAgentConversation)(this._db, conversationId, { title });
+            this._broadcast({ type: 'agent_title', conversationId, title, timestamp: new Date().toISOString() });
+        }
+        catch (err) {
+            console.error(`[agent-chat] auto-title failed (${conversationId}):`, err);
+        }
+    }
     /** Aborts the active turn for a conversation, if any. */
     abort(conversationId) {
         const child = this._active.get(conversationId);

package/server/dist/agent-chat-router.js

@@ -1,10 +1,16 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isAgentChatEnabled = isAgentChatEnabled;
 exports.createAgentChatRouter = createAgentChatRouter;
+const fs_1 = __importDefault(require("fs"));
+const multer_1 = __importDefault(require("multer"));
 const express_1 = require("express");
 const providers_1 = require("./providers");
 const agent_tier_1 = require("./agent-tier");
+const attachment_manager_1 = require("./attachment-manager");
 const agent_store_1 = require("./agent-store");
 function isAgentChatEnabled() {
     return process.env.SPECRAILS_AGENT_CHAT !== 'false';
@@ -20,6 +26,20 @@ function validProvider(provider) {
         return null;
     }
 }
+const attachmentUpload = (0, multer_1.default)({
+    storage: multer_1.default.memoryStorage(),
+    limits: { fileSize: 25 * 1024 * 1024 },
+    fileFilter: (req, file, cb) => {
+        if ((0, attachment_manager_1.isSupportedUploadedFile)({ mimetype: file.mimetype, originalname: file.originalname })) {
+            cb(null, true);
+        }
+        else {
+            ;
+            req.fileRejected = file.mimetype || file.originalname || 'unknown';
+            cb(null, false);
+        }
+    },
+});
 function createAgentChatRouter(deps) {
     const { manager, desktopDb } = deps;
     const router = (0, express_1.Router)();
@@ -34,8 +54,27 @@ function createAgentChatRouter(deps) {
     // Per-provider model catalog for the header model selector.
     router.get('/models', (req, res) => {
         const provider = validProvider(req.query.provider) ?? 'claude';
-        res.json({ provider, models: (0, providers_1.getAdapter)(provider).modelCatalog() });
+        const adapter = (0, providers_1.getAdapter)(provider);
+        res.json({
+            provider,
+            models: adapter.modelCatalog(),
+            // The composer gates the image affordance on this (design D22: capability,
+            // never provider id — gemini stays false until live-verified).
+            supportsImageInput: adapter.capabilities.supportsImageInput === true,
+            // Per-provider reasoning-effort tiers (ascending). Empty ⇒ no selector
+            // (gemini has no per-spawn knob).
+            efforts: adapter.capabilities.reasoningEfforts ?? [],
+        });
     });
+    /** Validate a requested reasoning effort against a provider's catalog. */
+    const validEffort = (provider, value) => {
+        if (value === null)
+            return null;
+        if (typeof value !== 'string')
+            return undefined;
+        const efforts = (0, providers_1.getAdapter)(provider).capabilities.reasoningEfforts ?? [];
+        return efforts.includes(value) ? value : undefined;
+    };
     router.get('/conversations', (_req, res) => {
         res.json({ conversations: (0, agent_store_1.listAgentConversations)(desktopDb) });
     });
@@ -55,6 +94,8 @@ function createAgentChatRouter(deps) {
             model: typeof body.model === 'string' ? body.model : null,
             pinnedProjectId: typeof body.pinnedProjectId === 'string' ? body.pinnedProjectId : null,
             tierLevel: body.tierLevel !== undefined ? (0, agent_tier_1.normalizeLevel)(body.tierLevel) : 0,
+            // Off-catalog values fall back to null (= app default "medium").
+            reasoningEffort: validEffort(provider, body.reasoningEffort) ?? null,
         });
         res.status(201).json({ conversation });
     });
@@ -88,13 +129,15 @@ function createAgentChatRouter(deps) {
                 return;
             }
             patch.provider = v;
-            // Switching provider invalidates the stored session id AND model (both
-            // belong to the previous provider) — clear them so the next turn starts a
-            // fresh session with the new provider's default model (codex rejects
-            // claude's "sonnet"; resume of a foreign thread → "no rollout found").
+            // Switching provider invalidates the stored session id, model AND effort
+            // (all belong to the previous provider) — clear them so the next turn
+            // starts fresh with the new provider's defaults (codex rejects claude's
+            // "sonnet"; claude's "xhigh" is off-catalog for codex; resume of a
+            // foreign thread → "no rollout found").
             if (v !== conversation.provider) {
                 patch.session_id = null;
                 patch.model = null;
+                patch.reasoning_effort = null;
             }
         }
         // Explicit model pick — validated against the (new or current) provider's catalog.
@@ -112,13 +155,127 @@ function createAgentChatRouter(deps) {
                 patch.model = body.model;
             }
         }
+        // Explicit effort pick — validated against the (new or current) provider's
+        // effort catalog; null resets to the app default ("medium").
+        if (body.reasoningEffort !== undefined && patch.reasoning_effort === undefined) {
+            const effectiveProvider = patch.provider ?? conversation.provider;
+            const v = validEffort(effectiveProvider, body.reasoningEffort);
+            if (v === undefined) {
+                res.status(400).json({ error: 'Effort not available for this provider' });
+                return;
+            }
+            patch.reasoning_effort = v;
+        }
         res.json({ conversation: (0, agent_store_1.updateAgentConversation)(desktopDb, conversation.id, patch) });
     });
     router.delete('/conversations/:id', (req, res) => {
-        manager.abort(String(req.params.id));
-        (0, agent_store_1.deleteAgentConversation)(desktopDb, String(req.params.id));
+        const id = String(req.params.id);
+        manager.abort(id);
+        (0, agent_store_1.deleteAgentConversation)(desktopDb, id);
+        // Cascade-remove the conversation's attachment directory (best-effort).
+        void attachment_manager_1.attachmentManager.deleteAllAgent(id).catch((e) => console.error('[agent-chat] attachment cleanup failed:', e));
         res.json({ ok: true });
     });
+    // ── Attachments (conversation-keyed; mirror the ticket attachment routes) ──
+    router.post('/conversations/:id/attachments', attachmentUpload.single('file'), (err, _req, res, next) => {
+        if (err instanceof multer_1.default.MulterError) {
+            const msg = err.code === 'LIMIT_FILE_SIZE' ? 'File too large (max 25 MB)' : `Upload rejected: ${err.code}`;
+            res.status(400).json({ error: msg });
+            return;
+        }
+        if (err) {
+            next(err);
+            return;
+        }
+        next();
+    }, async (req, res) => {
+        const id = String(req.params.id);
+        if (!(0, agent_store_1.getAgentConversation)(desktopDb, id)) {
+            res.status(404).json({ error: 'Unknown conversation' });
+            return;
+        }
+        const file = req.file;
+        if (!file) {
+            const rejected = req.fileRejected;
+            res.status(400).json({ error: rejected ? `Unsupported file type: ${rejected}` : 'No file uploaded' });
+            return;
+        }
+        try {
+            const attachment = await attachment_manager_1.attachmentManager.uploadAgent({
+                conversationId: id,
+                file: { buffer: file.buffer, originalname: file.originalname, mimetype: file.mimetype, size: file.size },
+            });
+            res.status(201).json({ attachment });
+        }
+        catch (e) {
+            const status = e.status ?? 500;
+            console.error('[agent-chat] attachment upload error:', e);
+            res.status(status).json({ error: e instanceof Error ? e.message : 'Upload failed' });
+        }
+    });
+    router.get('/conversations/:id/attachments', (req, res) => {
+        const id = String(req.params.id);
+        if (!(0, agent_store_1.getAgentConversation)(desktopDb, id)) {
+            res.status(404).json({ error: 'Unknown conversation' });
+            return;
+        }
+        res.json({ attachments: attachment_manager_1.attachmentManager.listAgent(id) });
+    });
+    router.get('/conversations/:id/attachments/:attachmentId', (req, res) => {
+        const id = String(req.params.id);
+        if (!(0, agent_store_1.getAgentConversation)(desktopDb, id)) {
+            res.status(404).json({ error: 'Unknown conversation' });
+            return;
+        }
+        const attachmentId = String(req.params.attachmentId);
+        let meta = null;
+        let abs = null;
+        try {
+            meta = attachment_manager_1.attachmentManager.getAgentMeta(id, attachmentId);
+            abs = meta ? attachment_manager_1.attachmentManager.getAgentFilePath(id, attachmentId) : null;
+        }
+        catch {
+            res.status(400).json({ error: 'Invalid attachment id' });
+            return;
+        }
+        if (!meta || !abs) {
+            res.status(404).json({ error: 'Attachment not found' });
+            return;
+        }
+        res.setHeader('Content-Type', meta.mimeType);
+        const asciiName = meta.filename.replace(/[\r\n"]/g, '_');
+        res.setHeader('Content-Disposition', `inline; filename="${asciiName}"; filename*=UTF-8''${encodeURIComponent(meta.filename)}`);
+        // The existsSync check above is not atomic with the stream's async open — a
+        // concurrent conversation/attachment DELETE can rm the file in between, and an
+        // unhandled ReadStream 'error' would take down the sidecar.
+        const stream = fs_1.default.createReadStream(abs);
+        stream.on('error', () => {
+            if (!res.headersSent)
+                res.status(404).json({ error: 'Attachment not found' });
+            else
+                res.destroy();
+        });
+        stream.pipe(res);
+    });
+    router.delete('/conversations/:id/attachments/:attachmentId', async (req, res) => {
+        const id = String(req.params.id);
+        if (!(0, agent_store_1.getAgentConversation)(desktopDb, id)) {
+            res.status(404).json({ error: 'Unknown conversation' });
+            return;
+        }
+        try {
+            const ok = await attachment_manager_1.attachmentManager.deleteAgent(id, String(req.params.attachmentId));
+            if (!ok) {
+                res.status(404).json({ error: 'Attachment not found' });
+                return;
+            }
+            res.status(204).end();
+        }
+        catch (e) {
+            console.error('[agent-chat] attachment delete error:', e);
+            res.status(400).json({ error: 'Delete failed' });
+        }
+    });
     router.post('/conversations/:id/send', (req, res) => {
         const conversation = (0, agent_store_1.getAgentConversation)(desktopDb, String(req.params.id));
         if (!conversation) {
@@ -133,11 +290,16 @@ function createAgentChatRouter(deps) {
         }
         const tierLevel = body.tierLevel !== undefined ? (0, agent_tier_1.normalizeLevel)(body.tierLevel) : undefined;
         const model = typeof body.model === 'string' ? body.model : undefined;
+        let attachmentIds = [];
+        const rawAtt = body.attachments;
+        if (rawAtt && typeof rawAtt === 'object' && Array.isArray(rawAtt.ids)) {
+            attachmentIds = (rawAtt.ids).filter((x) => typeof x === 'string');
+        }
         // Fire-and-forget: the turn streams over WS. Persist the chosen tier first so
         // a refresh mid-turn restores the right level.
         if (tierLevel !== undefined)
             (0, agent_store_1.updateAgentConversation)(desktopDb, conversation.id, { tier_level: tierLevel });
-        void manager.sendMessage(conversation.id, text, { tierLevel, model });
+        void manager.sendMessage(conversation.id, text, { tierLevel, model, attachmentIds }).catch((e) => console.error('[agent-chat] send failed:', e));
         res.status(202).json({ accepted: true });
     });
     router.post('/conversations/:id/abort', (req, res) => {

package/server/dist/agent-cwd-manager.js

@@ -9,6 +9,7 @@ exports.removeAgentCwd = removeAgentCwd;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
+const agent_operator_prompt_1 = require("./agent-operator-prompt");
 // ─── App-level agent working directory (design D1) ────────────────────────────
 //
 // The agent chat spawns the AI CLI from an app-owned cwd (NOT a project path), so
@@ -23,52 +24,6 @@ function agentCwdPath() {
     return path_1.default.join(homeDir(), '.specrails', 'agent-cwd');
 }
 const INSTRUCTION_FILES = ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md'];
-const OPERATOR_INSTRUCTIONS = `# Specrails Operator Agent
-
-You are the in-app Specrails operator. You drive the Specrails Desktop app on the
-user's behalf through the \`specrails_*\` MCP tools (projects, specs, rails, jobs,
-chat, agents, plugins, jira, loops, code, analytics, setup, settings).
-
-## How to work
-- Use \`specrails_select_project\` (or the projectId argument) to target a project.
-  If no project is selected ("Home") and the request is project-specific, ASK the
-  user whether to create a new project or search across all projects — do not guess.
-- For long-running actions that return HTTP 202, use \`specrails_watch\` to follow
-  them to completion instead of assuming they finished.
-- Prefer the meta tools \`specrails_guide\` / \`specrails_search\` / \`specrails_describe\`
-  to discover the exact action/arguments before calling a domain tool.
-
-## Permission ladder
-Your actions are gated by a cumulative level the user sets live:
-observe (read) ▸ edit (write) ▸ operate (launch AI, costs money) ▸ autonomous
-(delete/kill). If a tool is refused for the current level, tell the user which
-level it needs — do not try to work around the refusal.
-
-## Stance
-Be concise and action-oriented. Confirm what you did with concrete references
-(ids, names). Never fabricate results — report tool outputs faithfully, including
-failures.
-
-## Formatting
-Make replies easy to read: separate distinct ideas into short paragraphs with a
-blank line between them (avoid one dense block of text), and use bullet lists for
-enumerations. Give the conversation some breathing room.
-
-## Adding a project
-When the user has no projects yet, or asks to add one:
-1. Explain the UI path: click "Add Project" (the + in the left sidebar), enter the
-   repo's folder path, pick an AI provider, then run setup.
-2. Then OFFER to do it for them from here: ask for the repo folder path and which
-   AI providers to set up, then with their go-ahead call
-   \`specrails_setup(add_project, path, providers)\` (Edit level) and a SINGLE
-   \`specrails_setup(install, projectId)\` (Operate level) — one install provisions
-   ALL the chosen providers in one shot (do not install them one at a time).
-   Use \`specrails_setup(prerequisites)\` / \`available_providers\` first to confirm
-   the machine is ready.
-
-Setup is QUICK-only (fast, offline). Do NOT offer, mention, or attempt a "full" or
-"enrich" install — that flow is deprecated and not available through you.
-`;
 /**
  * Ensures the app-level agent cwd exists with operator instruction files.
  * Idempotent; safe to call on every turn. Returns the cwd path.
@@ -79,7 +34,7 @@ function ensureAgentCwd() {
     for (const name of INSTRUCTION_FILES) {
         // App-owned files (not user-edited) — always (re)write so operator-prompt
         // updates take effect instead of being pinned to the first materialization.
-        fs_1.default.writeFileSync(path_1.default.join(dir, name), OPERATOR_INSTRUCTIONS, 'utf-8');
+        fs_1.default.writeFileSync(path_1.default.join(dir, name), agent_operator_prompt_1.OPERATOR_INSTRUCTIONS, 'utf-8');
     }
     return dir;
 }