specrails-desktop 2.36.0 → 2.42.2

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

@@ -16,16 +16,12 @@ const agent_capability_1 = require("./agent-capability");
 function jsonRpcError(message, code = -32000) {
     return { jsonrpc: '2.0', error: { code, message }, id: null };
 }
-/**
- * Embedded MCP server manager. Mirrors the MobileGateway lifecycle shape
- * (isEnabledSetting / setEnabled / start / stop / status) but mounts on the
- * EXISTING Express app rather than binding a second port. Uses the SDK's
- * stateful streamable-HTTP transport (a transport per MCP session).
- */
+const SESSION_IDLE_MS = 30 * 60 * 1000;
 class McpServerManager {
     _ctx;
     _version;
-    _transports = {};
+    _sessions = new Map();
+    _pending = new Set();
     _toolCount;
     constructor(deps) {
         this._ctx = {
@@ -45,7 +41,7 @@ class McpServerManager {
     async setEnabled(enabled) {
         (0, desktop_db_1.setDesktopSetting)(this._ctx.desktopDb, mcp_tiers_1.MCP_ENABLED_KEY, enabled ? 'true' : 'false');
         if (!enabled)
-            await this.stop();
+            await this.stop(true);
         this._ctx.broadcast({ type: 'mcp.state', enabled, running: enabled });
         return this.status();
     }
@@ -55,33 +51,53 @@ class McpServerManager {
     async start() {
         /* no-op: served on the shared app, gated by isEnabledSetting() */
     }
-    /** Close all open MCP sessions. */
-    async stop() {
-        for (const sid of Object.keys(this._transports)) {
-            try {
-                await this._transports[sid].close();
-            }
-            catch {
-                /* ignore */
-            }
-            delete this._transports[sid];
+    /** Shutdown/rotation closes everything; the external Settings toggle must
+     * preserve first-party turns governed by their independent permission tier. */
+    async stop(externalOnly = false) {
+        const sessions = [...new Set([...this._sessions.values(), ...this._pending])]
+            .filter((session) => !externalOnly || session.capabilityHash === null);
+        await Promise.allSettled(sessions.map((session) => this.closeSession(session)));
+    }
+    async closeSession(session) {
+        if (session.closed)
+            return;
+        this.forgetSession(session);
+        try {
+            await session.server.close();
         }
+        catch { /* best-effort teardown */ }
+    }
+    forgetSession(session) {
+        session.closed = true;
+        if (session.timer)
+            clearTimeout(session.timer);
+        session.unsubscribe?.();
+        this._pending.delete(session);
+        if (session.transport.sessionId)
+            this._sessions.delete(session.transport.sessionId);
+    }
+    touchSession(session, expiresAt) {
+        if (session.timer)
+            clearTimeout(session.timer);
+        session.timer = setTimeout(() => { void this.closeSession(session); }, Math.max(1, Math.min(SESSION_IDLE_MS, (expiresAt ?? Infinity) - Date.now())));
+        session.timer.unref?.();
     }
     status() {
         return {
             enabled: this.isEnabledSetting(),
             running: this.isEnabledSetting(),
-            activeSessions: Object.keys(this._transports).length,
+            activeSessions: this._sessions.size,
             toolCount: this._toolCount,
         };
     }
     /** Build a fresh McpServer with the full tool + resource catalog registered. */
     buildServer() {
         const server = new mcp_js_1.McpServer({ name: 'specrails-desktop', version: this._version }, { capabilities: { logging: {}, tools: {}, resources: {} } });
+        const context = { ...this._ctx, sessionState: { activeProjectId: null } };
         for (const spec of (0, catalog_1.buildToolSpecs)()) {
-            (0, types_1.registerTieredTool)(server, this._ctx, spec);
+            (0, types_1.registerTieredTool)(server, context, spec);
         }
-        (0, resources_1.registerResources)(server, this._ctx);
+        (0, resources_1.registerResources)(server, context);
         return server;
     }
     /**
@@ -93,53 +109,83 @@ class McpServerManager {
         // The external Settings toggle gates third-party clients. Only a live,
         // server-minted per-turn capability identifies the in-app agent and may
         // bypass it; caller-authored context headers grant no authority.
-        const isFirstPartyAgent = (0, agent_capability_1.verifyAgentCapability)(req.headers[agent_tier_1.AGENT_CAPABILITY_HEADER]) !== null;
-        if (!this.isEnabledSetting() && !isFirstPartyAgent) {
+        const suppliedCapability = req.headers[agent_tier_1.AGENT_CAPABILITY_HEADER];
+        const capability = (0, agent_capability_1.verifyAgentCapability)(suppliedCapability);
+        if (suppliedCapability !== undefined && !capability) {
+            res.status(401).json(jsonRpcError('Agent capability expired or was revoked. Start a new mission turn.', -32001));
+            return;
+        }
+        if (!this.isEnabledSetting() && !capability) {
             res.status(404).json(jsonRpcError('MCP is disabled. Enable it in the Specrails app under Settings ▸ MCP.', -32004));
             return;
         }
-        const sessionId = req.headers['mcp-session-id'];
+        const suppliedSession = req.headers['mcp-session-id'];
+        if (suppliedSession !== undefined && (typeof suppliedSession !== 'string' || !suppliedSession.trim())) {
+            res.status(400).json(jsonRpcError('Invalid mcp-session-id.'));
+            return;
+        }
+        const sessionId = suppliedSession;
+        const capabilityHash = capability && typeof suppliedCapability === 'string'
+            ? (0, crypto_1.createHash)('sha256').update(suppliedCapability.trim()).digest('hex') : null;
+        let session = sessionId ? this._sessions.get(sessionId) : undefined;
+        if (sessionId && !session) {
+            // Streamable HTTP clients recognize 404 as an expired session and must
+            // initialize again. 400 left SDK clients stuck with the stale id forever.
+            res.status(404).json(jsonRpcError('Unknown or expired MCP session. Reinitialize.'));
+            return;
+        }
+        if (session && session.capabilityHash !== capabilityHash) {
+            res.status(403).json(jsonRpcError('MCP session belongs to a different agent turn or client. Reinitialize.'));
+            return;
+        }
         try {
             if (req.method === 'POST') {
-                let transport = sessionId ? this._transports[sessionId] : undefined;
-                if (!transport) {
-                    if (sessionId) {
-                        res.status(400).json(jsonRpcError('Unknown or expired MCP session. Reinitialize.'));
-                        return;
-                    }
+                if (!session) {
                     if (!(0, types_js_1.isInitializeRequest)(req.body)) {
                         res.status(400).json(jsonRpcError('Missing mcp-session-id and body is not an initialize request.'));
                         return;
                     }
-                    transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
+                    const server = this.buildServer();
+                    const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
                         sessionIdGenerator: () => (0, crypto_1.randomUUID)(),
                         onsessioninitialized: (sid) => {
-                            this._transports[sid] = transport;
+                            this._pending.delete(created);
+                            this._sessions.set(sid, created);
                         },
                     });
-                    transport.onclose = () => {
-                        const sid = transport?.sessionId;
-                        if (sid && this._transports[sid])
-                            delete this._transports[sid];
-                    };
-                    const server = this.buildServer();
+                    const created = { transport, server, capabilityHash, closed: false };
+                    session = created;
+                    this._pending.add(created);
+                    transport.onclose = () => { this.forgetSession(created); };
+                    if (capability && typeof suppliedCapability === 'string') {
+                        created.unsubscribe = (0, agent_capability_1.onAgentCapabilityRevoked)(suppliedCapability, () => { void this.closeSession(created); });
+                    }
                     await server.connect(transport);
                 }
-                await transport.handleRequest(req, res, req.body);
+                if (session.closed) {
+                    res.status(503).json(jsonRpcError('MCP session closed during initialization. Reconnect.'));
+                    return;
+                }
+                this.touchSession(session, capability?.expiresAt);
+                await session.transport.handleRequest(req, res, req.body);
+                if (!session.transport.sessionId)
+                    await this.closeSession(session);
                 return;
             }
             if (req.method === 'GET' || req.method === 'DELETE') {
-                const transport = sessionId ? this._transports[sessionId] : undefined;
-                if (!transport) {
-                    res.status(400).json(jsonRpcError('Missing or unknown mcp-session-id.'));
+                if (!session) {
+                    res.status(400).json(jsonRpcError('Missing mcp-session-id.'));
                     return;
                 }
-                await transport.handleRequest(req, res);
+                this.touchSession(session, capability?.expiresAt);
+                await session.transport.handleRequest(req, res);
                 return;
             }
             res.status(405).json(jsonRpcError('Method not allowed.'));
         }
         catch (err) {
+            if (session && !session.transport.sessionId)
+                await this.closeSession(session);
             if (!res.headersSent) {
                 res.status(500).json(jsonRpcError(err instanceof Error ? err.message : 'Internal MCP error', -32603));
             }

package/server/dist/mcp/mcp-tiers.js

@@ -7,26 +7,27 @@ exports.tierLabel = tierLabel;
 exports.tierRefusalMessage = tierRefusalMessage;
 const desktop_db_1 = require("../desktop-db");
 exports.MCP_TIERS = ['read', 'write', 'ai-spawn', 'destructive'];
-/** desktop_settings keys for the opt-in tiers (read is implicit). */
+/** desktop_settings keys for the opt-out tiers (all on by default; read is implicit). */
 exports.TIER_SETTING_KEY = {
     write: 'mcp_tier_write',
     'ai-spawn': 'mcp_tier_ai_spawn',
     destructive: 'mcp_tier_destructive',
 };
 exports.MCP_ENABLED_KEY = 'mcp_enabled';
-/** True when MCP itself is enabled (default false). */
+/** True when MCP itself is enabled (default TRUE — only an explicit 'false' disables). */
 function isMcpEnabled(db) {
-    return (0, desktop_db_1.getDesktopSetting)(db, exports.MCP_ENABLED_KEY) === 'true';
+    return (0, desktop_db_1.getDesktopSetting)(db, exports.MCP_ENABLED_KEY) !== 'false';
 }
 /**
  * True when a tool of the given tier may run right now. Read is always allowed
  * (its availability is governed by MCP being enabled, checked at the transport
- * gate). The other tiers require their opt-in flag to be 'true'.
+ * gate). The other tiers default ON and are disabled only when the user has
+ * explicitly stored 'false' for them (opt-out).
  */
 function isTierEnabled(db, tier) {
     if (tier === 'read')
         return true;
-    return (0, desktop_db_1.getDesktopSetting)(db, exports.TIER_SETTING_KEY[tier]) === 'true';
+    return (0, desktop_db_1.getDesktopSetting)(db, exports.TIER_SETTING_KEY[tier]) !== 'false';
 }
 /** Human-readable label for a tier, used in refusal messages. */
 function tierLabel(tier) {

package/server/dist/mcp/mcp-token.js

@@ -84,8 +84,10 @@ function getMcpToken() {
  */
 function regenerateMcpToken() {
     const next = generateToken();
+    // Commit the file before switching the live credential. If persistence
+    // fails, bridges must still authenticate with the existing on-disk token.
+    (0, secure_token_file_1.writePrivateTextFile)(tokenPath(), next);
     _mcpToken = next;
-    persist(next);
     return next;
 }
 /** Extracts a bearer token from `Authorization: Bearer <t>` or `X-Desktop-Token`. */

package/server/dist/mcp/resources.js

@@ -4,6 +4,7 @@ exports.registerResources = registerResources;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const guide_1 = require("./guide");
 const projects_1 = require("./tools/projects");
+const desktop_db_1 = require("../desktop-db");
 // Read-only state exposed as MCP resources. Read-tier only (resources are never
 // mutating). Per-project resource templates (tickets, rails, analytics) are
 // added in subsequent phases.
@@ -12,13 +13,13 @@ function registerResources(server, ctx) {
         contents: [{ uri: uri.href, text: guide_1.SPECRAILS_GUIDE }],
     }));
     server.registerResource('projects', 'specrails://projects', { title: 'Projects', description: 'All registered Specrails projects.', mimeType: 'application/json' }, async (uri) => ({
-        contents: [{ uri: uri.href, text: JSON.stringify(ctx.registry.listContexts().map((c) => (0, projects_1.serializeProject)(c.project)), null, 2) }],
+        contents: [{ uri: uri.href, text: JSON.stringify((0, desktop_db_1.listProjects)(ctx.desktopDb).map(projects_1.serializeProject), null, 2) }],
     }));
     server.registerResource('project', new mcp_js_1.ResourceTemplate('specrails://projects/{projectId}', { list: undefined }), { title: 'Project', description: 'A single project by id.', mimeType: 'application/json' }, async (uri, variables) => {
         const projectId = String(variables.projectId);
-        const pc = ctx.registry.getContext(projectId);
-        if (!pc)
+        const project = (0, desktop_db_1.getProject)(ctx.desktopDb, projectId);
+        if (!project)
             throw new Error(`Unknown projectId "${projectId}".`);
-        return { contents: [{ uri: uri.href, text: JSON.stringify((0, projects_1.serializeProject)(pc.project), null, 2) }] };
+        return { contents: [{ uri: uri.href, text: JSON.stringify((0, projects_1.serializeProject)(project), null, 2) }] };
     });
 }

package/server/dist/mcp/tools/catalog.js

@@ -19,6 +19,8 @@ const analytics_1 = require("./analytics");
 const git_1 = require("./git");
 const support_1 = require("./support");
 const env_1 = require("./env");
+const context_1 = require("./context");
+const mission_1 = require("./mission");
 /**
  * The full MCP tool catalog. Domain-facade tools each expose an `action` enum
  * and call the app's REST API over loopback (see apiCall). Meta tools receive a
@@ -28,6 +30,8 @@ function buildToolSpecs() {
     const specs = [];
     // App-level + meta + watch
     specs.push(...(0, projects_1.projectsTools)());
+    specs.push(...(0, context_1.contextTools)());
+    specs.push(...(0, mission_1.missionTools)());
     specs.push(...(0, app_settings_1.appTools)());
     specs.push((0, watch_1.watchTool)());
     // Per-project domains

package/server/dist/mcp/tools/code.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.codeTools = codeTools;
 const zod_1 = require("zod");
 const types_1 = require("./types");
+const project_repositories_1 = require("../../project-repositories");
 /**
  * Read-only Code Explorer surface for a project: the AI-touched file tree,
  * file contents + plain-language AI summaries, "touched by AI" provenance, and
@@ -23,29 +24,47 @@ function codeTools() {
             name: 'specrails_code',
             title: 'Code Explorer',
             description: 'Read-only browse a project\'s source through the Code Explorer: list the file tree ' +
-                '(default scoped to AI-touched files, optional provenance rollup), read a file with its ' +
-                'AI summary + staleness + provenance, fetch a stored summary alone, regenerate a file\'s ' +
-                'AI summary (cost-incurring, async), list "touched by AI" provenance rows, and fetch the ' +
-                'stored unified-diff a job applied to a file. ' +
-                'Actions: tree, read_file, summary, regenerate_summary (ai-spawn — spawns an AI CLI, ' +
+                '(default scoped to AI-touched files, optional provenance rollup), locate a file by name / ' +
+                'path suffix, read a bounded file range with a stable content hash, fetch a stored ' +
+                'summary alone, regenerate a file\'s AI summary (cost-incurring, async), list "touched by ' +
+                'AI" provenance rows, and fetch the stored unified-diff a job applied to a file. ' +
+                'Actions: tree, find (name / path-suffix / fragment → ranked project-relative paths; use it ' +
+                'when read_file 404s — a path copied from a stack trace or import is usually relative to a ' +
+                'subdirectory), search (literal source content, scoped path and explicit scan budgets), ' +
+                'read_file (bounded line/column pages with hash and continuation, default 200 lines), summary, regenerate_summary (ai-spawn — spawns an AI CLI, ' +
                 'incurs cost, returns 202 then completes over WS), provenance, diff. ' +
                 'Requires SPECRAILS_CODE_EXPLORER (default on); the /code prefix 404s when disabled.',
             hintTier: 'read',
             tier: (a) => (a.action === 'regenerate_summary' ? 'ai-spawn' : 'read'),
             inputSchema: {
                 action: zod_1.z
-                    .enum(['tree', 'read_file', 'summary', 'regenerate_summary', 'provenance', 'diff'])
+                    .enum(['tree', 'find', 'search', 'read_file', 'summary', 'regenerate_summary', 'provenance', 'diff'])
                     .describe('Operation to perform'),
                 projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+                repositoryId: zod_1.z.string().min(1).optional().describe('Repository membership ID. Required for individual tree/file/summary/provenance/diff actions in multi-repository projects. Omit for find/search to discover across members under one shared budget.'),
                 path: zod_1.z
                     .string()
                     .optional()
                     .describe('Project-relative file path. Required for read_file/summary/regenerate_summary/diff; ' +
-                    'optional narrowing filter for provenance.'),
+                    'optional directory/file prefix for search or narrowing filter for provenance.'),
+                file: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Compatibility alias for path (accepted for read_file/summary/regenerate_summary/diff)'),
+                query: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('search: literal single-line source text (not regex). find: file name, path suffix (e.g. components/detail/LessonView.tsx) or fragment ' +
+                    'to locate, case-insensitive. Falls back to path/file when omitted.'),
                 filter: zod_1.z
                     .enum(['touched-by-ai', 'all'])
                     .optional()
                     .describe('tree only: scope to AI-touched files (default) or the whole repo'),
+                caseSensitive: zod_1.z.boolean().optional().describe('search only: match exact character case (default false)'),
+                startLine: zod_1.z.number().int().positive().optional().describe('read_file only: first line, 1-based (default 1)'),
+                endLine: zod_1.z.number().int().positive().optional().describe('read_file only: last line inclusive (default startLine + 199; at most 500 lines returned)'),
+                startColumn: zod_1.z.number().int().positive().optional().describe('read_file only: resume at nextColumn when a long line was split by the character budget (default 1)'),
+                expectedHash: zod_1.z.string().regex(/^[a-f0-9]{64}$/i).optional().describe('read_file only: hash from the previous page/search; rejects changed files so pages cannot silently mix revisions'),
                 withProvenance: zod_1.z
                     .boolean()
                     .optional()
@@ -54,6 +73,13 @@ function codeTools() {
                     .string()
                     .optional()
                     .describe('tree only: opaque pagination cursor from a prior response\'s nextCursor'),
+                limit: zod_1.z
+                    .number()
+                    .int()
+                    .positive()
+                    .max(500)
+                    .optional()
+                    .describe('tree: entries per page (default 200, maximum 500); find: matches (default 20, max 50); search: matching lines (default 30, max 100)'),
                 ticketId: zod_1.z
                     .number()
                     .int()
@@ -71,14 +97,47 @@ function codeTools() {
                     'incurs cost beyond the configured limit.'),
             },
             async handler(ctx, args) {
-                const base = (0, types_1.projectPath)(ctx, args.projectId);
                 const action = args.action;
+                const projectId = args.projectId;
+                const repositoryId = args.repositoryId;
+                if (repositoryId === undefined && ['find', 'search'].includes(action) && (0, project_repositories_1.getProjectRepositories)((0, types_1.requireProject)(ctx, projectId).project).length > 1) {
+                    const query = (args.query ?? args.path ?? args.file);
+                    if (!query?.trim())
+                        throw new Error(`Action "${action}" requires a "query".`);
+                    const qs = new URLSearchParams({ kind: action, q: query });
+                    if (args.limit !== undefined)
+                        qs.set('limit', String(args.limit));
+                    if (action === 'search' && args.path)
+                        qs.set('path', String(args.path));
+                    if (args.caseSensitive === true)
+                        qs.set('caseSensitive', 'true');
+                    return (0, types_1.apiCall)(ctx, 'GET', `${(0, types_1.projectPath)(ctx, projectId)}/code/discover?${qs}`);
+                }
+                const base = (0, types_1.repositoryPath)(ctx, projectId, repositoryId);
                 const requirePath = () => {
-                    const p = args.path;
+                    const p = (args.path ?? args.file);
                     if (!p || p.trim() === '')
                         throw new Error(`Action "${action}" requires a "path".`);
                     return p;
                 };
+                // A bare `→ 404: {"error":"file not found"}` sent callers into a
+                // ToolSearch/retry loop: the path they hold is usually right, just
+                // relative to a subdirectory. Point them at `find` instead of leaving
+                // them to page through `tree`.
+                const withNotFoundHint = async (p, run) => {
+                    try {
+                        return await run();
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        if (!/→ 404: .*file not found/.test(msg))
+                            throw err;
+                        const base = p.replace(/\\/g, '/').replace(/\/+$/, '').split('/').pop() || p;
+                        throw new Error(`${msg}. Paths are relative to the project root and "${p}" may live under a subdirectory ` +
+                            '(a path copied from a stack trace or import usually does). Locate it with ' +
+                            `specrails_code(action: "find", query: ${JSON.stringify(base)}) and retry with the returned path.`);
+                    }
+                };
                 switch (action) {
                     case 'tree': {
                         const qs = new URLSearchParams();
@@ -88,20 +147,72 @@ function codeTools() {
                             qs.set('withProvenance', '1');
                         if (args.cursor)
                             qs.set('cursor', args.cursor);
+                        qs.set('limit', String(typeof args.limit === 'number' ? args.limit : 200));
                         if (typeof args.ticketId === 'number')
                             qs.set('ticketId', String(args.ticketId));
                         if (args.jobId)
                             qs.set('jobId', args.jobId);
                         const suffix = qs.toString() ? `?${qs.toString()}` : '';
-                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/code/tree${suffix}`);
+                        const result = await (0, types_1.apiCall)(ctx, 'GET', `${base}/code/tree${suffix}`);
+                        if (args.withProvenance === true || !Array.isArray(result.entries))
+                            return result;
+                        return {
+                            ...result,
+                            entries: result.entries.map((entry) => {
+                                const item = entry;
+                                return { path: item.path, kind: item.kind, ...(item.repositoryId ? { repositoryId: item.repositoryId } : {}) };
+                            }),
+                            hint: result.nextCursor
+                                ? 'More files are available. Call tree again with this nextCursor; prefer targeted read_file calls.'
+                                : 'Tree complete. Prefer targeted read_file calls.',
+                        };
+                    }
+                    case 'find': {
+                        const q = (args.query ?? args.path ?? args.file)?.trim();
+                        if (!q)
+                            throw new Error('Action "find" requires a "query" (file name, path suffix or fragment).');
+                        const qs = new URLSearchParams({ q });
+                        qs.set('limit', String(typeof args.limit === 'number' ? Math.min(args.limit, 50) : 20));
+                        const r = (await (0, types_1.apiCall)(ctx, 'GET', `${base}/code/find?${qs.toString()}`));
+                        const matches = Array.isArray(r.matches) ? r.matches : [];
+                        return {
+                            ...r,
+                            hint: matches.length
+                                ? 'Call read_file with one of these project-relative paths (best match first).'
+                                : r.truncated
+                                    ? 'Partial scan found no matches; this does not prove absence. Narrow the query and retry or inspect the project tree.'
+                                    : 'No file matches. The scan skips build/dependency trees, dot-directories and gitignored paths; ' +
+                                        'try a shorter fragment or the bare file name.',
+                        };
+                    }
+                    case 'search': {
+                        const query = args.query;
+                        if (!query?.trim())
+                            throw new Error('Action "search" requires a literal source-text "query".');
+                        if (typeof args.limit === 'number' && args.limit > 100)
+                            throw new Error('Action "search" limit must be at most 100.');
+                        const qs = new URLSearchParams({ q: query, limit: String(args.limit ?? 30), caseSensitive: String(args.caseSensitive === true) });
+                        if (args.path)
+                            qs.set('path', args.path);
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/code/search?${qs.toString()}`);
                     }
                     case 'read_file': {
-                        const qs = new URLSearchParams({ path: requirePath() });
-                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/code/file?${qs.toString()}`);
+                        const p = requirePath();
+                        const startLine = typeof args.startLine === 'number' ? args.startLine : 1;
+                        const endLine = typeof args.endLine === 'number' ? args.endLine : startLine + 199;
+                        if (endLine < startLine)
+                            throw new Error('endLine must be greater than or equal to startLine.');
+                        const qs = new URLSearchParams({ path: p, startLine: String(startLine), endLine: String(endLine) });
+                        if (args.startColumn !== undefined)
+                            qs.set('startColumn', String(args.startColumn));
+                        if (args.expectedHash)
+                            qs.set('expectedHash', args.expectedHash);
+                        return withNotFoundHint(p, () => (0, types_1.apiCall)(ctx, 'GET', `${base}/code/file?${qs.toString()}`));
                     }
                     case 'summary': {
-                        const qs = new URLSearchParams({ path: requirePath() });
-                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/code/summary?${qs.toString()}`);
+                        const p = requirePath();
+                        const qs = new URLSearchParams({ path: p });
+                        return withNotFoundHint(p, () => (0, types_1.apiCall)(ctx, 'GET', `${base}/code/summary?${qs.toString()}`));
                     }
                     case 'regenerate_summary': {
                         const qs = new URLSearchParams({ path: requirePath() });