specrails-desktop 2.36.0 → 2.42.2

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

@@ -3,20 +3,25 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.specsTools = specsTools;
 const zod_1 = require("zod");
 const types_1 = require("./types");
+const agent_spec_framing_1 = require("../../agent-spec-framing");
 // Per-action danger classification for the specs (tickets) facade.
 const DESTRUCTIVE_ACTIONS = new Set(['delete', 'smash_undo', 'delete_epic_children']);
 // `create` routes through Quick Add Spec (generate-spec) so MCP-created specs
 // match the app's "Add Spec → Quick" flow — hence ai-spawn, not write.
 const AI_SPAWN_ACTIONS = new Set(['create', 'generate', 'ai_edit', 'contract_refine', 'smash']);
-// `commit_draft` (POST /tickets/from-draft) may fire-and-forget a Contract
-// Refine spawn as a side-effect (Explore-origin flips per the conversation's
-// scope; agent-authored inserts by the facade's default-ON `contractRefine` —
-// opt out per call with `contractRefine: false`), but the call itself is a
-// synchronous store mutation (a write), so it is classified as `write`.
+// A post-commit background AI pass still incurs cost. Classify commit_draft
+// using its actual side effects, not the synchronous HTTP response alone.
 const WRITE_ACTIONS = new Set([
     'update', 'from_prompt', 'save_draft', 'commit_draft', 'cancel_ai_edit',
 ]);
-function resolveSpecsTier(action) {
+function resolveSpecsTier(action, args) {
+    if (action === 'commit_draft') {
+        // Explore's stored scope governs refinement; its route does not accept an
+        // opt-out override here. A standalone draft flip does not launch AI.
+        if (args.conversationId)
+            return 'ai-spawn';
+        return args.draftTicketId != null || args.contractRefine === false ? 'write' : 'ai-spawn';
+    }
     if (DESTRUCTIVE_ACTIONS.has(action))
         return 'destructive';
     if (AI_SPAWN_ACTIONS.has(action))
@@ -45,7 +50,7 @@ function specsTools() {
                 'from_prompt (verbatim insert, no AI — use ONLY when you already have a complete finished spec to store as-is; ' +
                 'cannot set acceptanceCriteria or shortSummary — prefer commit_draft for structured specs), ' +
                 'save_draft (persist an Explore conversation as a draft), ' +
-                'commit_draft (write — TWO uses: (a) flip an Explore draft to a real spec, passing conversationId from ' +
+                'commit_draft (ai-spawn when refinement may run; write for standalone draft flips or new inserts with contractRefine:false — TWO uses: (a) flip an Explore draft to a real spec, passing conversationId from ' +
                 'specrails_chat and/or draftTicketId; (b) with NO conversationId/draftTicketId, insert a COMPLETE spec you ' +
                 'authored in ONE call: title (required), description, acceptanceCriteria, priority, labels, shortSummary, ' +
                 'assignee, prerequisites, metadata. THE canonical way to persist a spec refined in conversation — do NOT route ' +
@@ -62,7 +67,7 @@ function specsTools() {
                 'list_attachments, get_attachment. The generate/ai_edit/contract_refine/smash actions are async (HTTP 202) — ' +
                 'results arrive over the WebSocket, not the HTTP response.',
             hintTier: 'read',
-            tier: (args) => resolveSpecsTier(args.action),
+            tier: (args) => resolveSpecsTier(args.action, args),
             inputSchema: {
                 action: zod_1.z
                     .enum([
@@ -88,6 +93,8 @@ function specsTools() {
                 ])
                     .describe('Operation to perform'),
                 projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+                repositoryIds: zod_1.z.array(zod_1.z.string().min(1)).min(1).max(50).optional().describe('Affected repositories for this shared spec. Nonempty unique membership IDs from this project. Omission preserves existing scope; historical specs default to primary only.'),
+                repositoryId: zod_1.z.string().min(1).optional().describe('files_touched only: repository to inspect; required for multi-repository projects.'),
                 // ── Ticket identity ──────────────────────────────────────────────
                 id: zod_1.z
                     .number()
@@ -101,6 +108,8 @@ function specsTools() {
                     .describe('list: CSV status filter (draft|todo|in_progress|on_review|done|cancelled). update: set ticket status — note job outcomes set in_progress/on_review/done automatically (on_review = implemented, awaiting PR review); do not fight the pipeline.'),
                 label: zod_1.z.string().optional().describe('list: filter by label (CSV)'),
                 q: zod_1.z.string().optional().describe('list: free-text search over title + description'),
+                limit: zod_1.z.number().int().positive().max(100).optional().describe('list: compact results per page (default 50, maximum 100)'),
+                offset: zod_1.z.number().int().nonnegative().optional().describe('list: zero-based offset for the next compact page'),
                 // ── create / update / from_prompt / commit_draft fields ──────────
                 title: zod_1.z.string().optional().describe('Ticket title (required for create / commit_draft)'),
                 description: zod_1.z
@@ -113,7 +122,7 @@ function specsTools() {
                     .optional()
                     .describe('update/from_prompt/commit_draft: ticket priority. update: null allowed only for drafts'),
                 labels: zod_1.z.array(zod_1.z.string()).optional().describe('update/from_prompt/save_draft/commit_draft: labels array'),
-                assignee: zod_1.z.string().optional().describe('update/commit_draft: assignee'),
+                assignee: zod_1.z.string().nullable().optional().describe('update/commit_draft: assignee; null clears'),
                 prerequisites: zod_1.z.array(zod_1.z.number().int()).optional().describe('update/commit_draft: prerequisite ticket ids'),
                 metadata: zod_1.z.record(zod_1.z.unknown()).optional().describe('update/commit_draft: free-form metadata object (update merges keys)'),
                 acceptanceCriteria: zod_1.z
@@ -121,7 +130,7 @@ function specsTools() {
                     .optional()
                     .describe('update/commit_draft: acceptance-criteria bullets folded into the description'),
                 shortSummary: zod_1.z.string().optional().describe('commit_draft: explicit short summary (camelCase key)'),
-                short_summary: zod_1.z.string().optional().describe('update: explicit short summary (snake_case key; null clears)'),
+                short_summary: zod_1.z.string().nullable().optional().describe('update: explicit short summary (snake_case key; null clears)'),
                 structured: zod_1.z.boolean().optional().describe('from_prompt: lightly structure the verbatim prompt'),
                 createLocal: zod_1.z.boolean().optional().describe('create/generate/commit_draft: keep the spec local (skip Jira promote)'),
                 // ── draft linkage ────────────────────────────────────────────────
@@ -192,6 +201,7 @@ function specsTools() {
                     attachmentIds: args.attachmentIds,
                     pendingSpecId: args.pendingSpecId,
                     createLocal: args.createLocal,
+                    ...(args.repositoryIds === undefined ? {} : { repositoryIds: args.repositoryIds }),
                 });
                 switch (action) {
                     // ── reads ──────────────────────────────────────────────────────
@@ -204,14 +214,40 @@ function specsTools() {
                         if (typeof args.q === 'string')
                             qs.set('q', args.q);
                         const suffix = qs.toString() ? `?${qs.toString()}` : '';
-                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/tickets${suffix}`);
+                        const result = await (0, types_1.apiCall)(ctx, 'GET', `${base}/tickets${suffix}`);
+                        const tickets = Array.isArray(result.tickets) ? result.tickets : [];
+                        const offset = typeof args.offset === 'number' ? args.offset : 0;
+                        const limit = typeof args.limit === 'number' ? args.limit : 50;
+                        const page = tickets.slice(offset, offset + limit).map((ticket) => ({
+                            id: ticket.id,
+                            title: ticket.title,
+                            status: ticket.status,
+                            priority: ticket.priority,
+                            labels: ticket.labels,
+                            ...(ticket.repositoryIds === undefined ? {} : { repositoryIds: ticket.repositoryIds }),
+                            shortSummary: ticket.short_summary ?? ticket.shortSummary ?? null,
+                            updatedAt: ticket.updated_at ?? ticket.updatedAt,
+                        }));
+                        const nextOffset = offset + page.length < tickets.length ? offset + page.length : null;
+                        return {
+                            tickets: page,
+                            revision: result.revision,
+                            total: result.total ?? tickets.length,
+                            matched: tickets.length,
+                            offset,
+                            limit,
+                            nextOffset,
+                            hint: nextOffset == null
+                                ? 'List complete. Use get(id) for the full description and acceptance criteria.'
+                                : `More specs are available. Call list with offset=${nextOffset}; use get(id) for full details.`,
+                        };
                     }
                     case 'get':
                         return (0, types_1.apiCall)(ctx, 'GET', `${base}/tickets/${requireId()}`);
                     case 'spending_summary':
                         return (0, types_1.apiCall)(ctx, 'GET', `${base}/tickets/${requireId()}/spending-summary`);
                     case 'files_touched':
-                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/code/provenance?ticketId=${requireId()}`);
+                        return (0, types_1.apiCall)(ctx, 'GET', `${(0, types_1.repositoryPath)(ctx, args.projectId, args.repositoryId)}/code/provenance?ticketId=${requireId()}`);
                     case 'list_attachments': {
                         const ticketId = args.ticketId;
                         if (!ticketId)
@@ -225,7 +261,17 @@ function specsTools() {
                             throw new Error('get_attachment requires a "ticketId".');
                         if (!attachmentId)
                             throw new Error('get_attachment requires an "attachmentId".');
-                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/tickets/${encodeURIComponent(ticketId)}/attachments/${encodeURIComponent(attachmentId)}`);
+                        // The download endpoint streams binary files; decoding those as
+                        // text corrupts their content and can exhaust the model context.
+                        const list = await (0, types_1.apiCall)(ctx, 'GET', `${base}/tickets/${encodeURIComponent(ticketId)}/attachments`);
+                        const attachment = list.attachments?.find((entry) => entry.id === attachmentId);
+                        if (!attachment)
+                            throw new Error('Attachment not found. Use list_attachments to read current attachment ids.');
+                        return {
+                            attachment,
+                            path: `${base}/tickets/${encodeURIComponent(ticketId)}/attachments/${encodeURIComponent(attachmentId)}`,
+                            hint: 'Attachment metadata and download path; binary content is not inlined. Fetch the authenticated REST download or open the attachment in the app.',
+                        };
                     }
                     // ── writes (synchronous store mutations) ────────────────────────
                     case 'create': {
@@ -264,6 +310,7 @@ function specsTools() {
                             metadata: args.metadata,
                             acceptanceCriteria: args.acceptanceCriteria,
                             short_summary: args.short_summary,
+                            ...(args.repositoryIds === undefined ? {} : { repositoryIds: args.repositoryIds }),
                         });
                     case 'from_prompt':
                         return (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/from-prompt`, {
@@ -272,6 +319,7 @@ function specsTools() {
                             labels: args.labels,
                             priority: args.priority,
                             structured: args.structured,
+                            ...(args.repositoryIds === undefined ? {} : { repositoryIds: args.repositoryIds }),
                             pendingSpecId: args.pendingSpecId,
                         });
                     case 'save_draft': {
@@ -283,6 +331,7 @@ function specsTools() {
                             description: args.description,
                             labels: args.labels,
                             editTicketId: args.editTicketId,
+                            ...(args.repositoryIds === undefined ? {} : { repositoryIds: args.repositoryIds }),
                         });
                     }
                     case 'commit_draft': {
@@ -299,7 +348,22 @@ function specsTools() {
                             : agentAuthored
                                 ? true
                                 : undefined;
-                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/from-draft`, {
+                        // The framing gate (critical-spec-framing): a spec the in-app agent
+                        // authored may not be persisted until the conversation holds a
+                        // problem frame the user has answered, and one frame authorises ONE
+                        // spec. Applied ONLY to first-party calls carrying a conversation —
+                        // an external MCP client cannot render the framing card and holds no
+                        // conversation here, so its behaviour is byte-identical to before.
+                        // Throwing lands in registerTieredTool's catch, producing the same
+                        // errorResult shape a tier refusal does.
+                        const framedConversationId = ctx.firstPartyAgent ? ctx.originConversationId : null;
+                        const agentProvider = framedConversationId ? (0, types_1.originConversationDefaults)(ctx).provider : undefined;
+                        if (framedConversationId) {
+                            const refusal = (0, agent_spec_framing_1.checkSpecFraming)(ctx.desktopDb, framedConversationId);
+                            if (refusal)
+                                throw new Error(refusal);
+                        }
+                        const committed = await (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/from-draft`, {
                             title: args.title,
                             description: args.description,
                             draftTicketId: args.draftTicketId,
@@ -313,8 +377,16 @@ function specsTools() {
                             prerequisites: args.prerequisites,
                             metadata: args.metadata,
                             createLocal: args.createLocal,
+                            ...(args.repositoryIds === undefined ? {} : { repositoryIds: args.repositoryIds }),
                             contractRefine,
+                            agentProvider,
                         });
+                        // Spend the frame only on a spec that actually landed: a refusal or
+                        // a failed write above throws before reaching here, so nothing is
+                        // consumed by an attempt.
+                        if (framedConversationId)
+                            (0, agent_spec_framing_1.recordSpecCommitted)(ctx.desktopDb, framedConversationId);
+                        return committed;
                     }
                     case 'cancel_ai_edit': {
                         if (!args.requestId)

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

@@ -150,7 +150,7 @@ function inferTopic(question) {
     return 'general_usage';
 }
 async function collectDiagnostics(ctx, projectId, topic) {
-    const projects = ctx.registry.listContexts().map((c) => (0, projects_1.serializeProject)(c.project));
+    const projects = ctx.registry.listProjects().map((p) => ({ ...(0, projects_1.serializeProject)(p), available: !!ctx.registry.getContext(p.id) }));
     const selectedProjectId = projectId ?? (0, types_1.getActiveProject)(ctx) ?? undefined;
     const out = {
         mcp: {

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

@@ -1,17 +1,38 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpApiError = void 0;
 exports.apiCall = apiCall;
 exports.projectPath = projectPath;
+exports.requireRepository = requireRepository;
+exports.repositoryPath = repositoryPath;
 exports.originConversationDefaults = originConversationDefaults;
 exports.requireProject = requireProject;
 exports.setActiveProject = setActiveProject;
 exports.getActiveProject = getActiveProject;
+exports.toolTierAllowed = toolTierAllowed;
 exports.registerTieredTool = registerTieredTool;
 const mcp_tiers_1 = require("../mcp-tiers");
-const auth_1 = require("../../auth");
+const internal_api_1 = require("../../internal-api");
 const agent_tier_1 = require("../../agent-tier");
 const agent_store_1 = require("../../agent-store");
 const agent_capability_1 = require("../agent-capability");
+const project_repositories_1 = require("../../project-repositories");
+const agent_steering_1 = require("../../agent-steering");
+class McpApiError extends Error {
+    status;
+    data;
+    code;
+    constructor(message, status, data) {
+        super(message);
+        this.status = status;
+        this.data = data;
+        this.name = 'McpApiError';
+        const error = data?.error;
+        if (typeof error === 'string')
+            this.code = error;
+    }
+}
+exports.McpApiError = McpApiError;
 /**
  * Calls the app's own REST API over loopback using the MASTER token (held
  * server-side, never exposed to the MCP client). This reuses every router's
@@ -20,33 +41,45 @@ const agent_capability_1 = require("../agent-capability");
  * after `/api` (e.g. `/projects/<id>/tickets`).
  */
 async function apiCall(ctx, method, path, body) {
-    const url = `http://127.0.0.1:${ctx.desktopPort}/api${path}`;
-    const res = await fetch(url, {
-        method,
-        headers: {
-            Authorization: `Bearer ${(0, auth_1.loadOrGenerateToken)()}`,
-            ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
-        },
-        body: body !== undefined ? JSON.stringify(body) : undefined,
-    });
-    const text = await res.text();
-    let data;
-    try {
-        data = text ? JSON.parse(text) : null;
-    }
-    catch {
-        data = text;
-    }
+    // Shared loopback client (server/internal-api.ts) — also drives the milestone
+    // launch chain's chunk launches, so both stay byte-identical to a dashboard call.
+    // MCP calls additionally retain their request cancellation and bounded wait;
+    // those lifetimes belong to this call, not to the durable milestone chain.
+    const signal = ctx.signal
+        ? AbortSignal.any([ctx.signal, AbortSignal.timeout(120_000)])
+        : AbortSignal.timeout(120_000);
+    const res = await (0, internal_api_1.createInternalApi)({
+        port: ctx.desktopPort,
+        fetchImpl: (input, init) => fetch(input, { ...init, signal }),
+    }).call(method, path, body);
     if (!res.ok) {
+        const data = res.body;
         const detail = typeof data === 'object' && data !== null ? JSON.stringify(data) : String(data);
-        throw new Error(`API ${method} ${path} → ${res.status}: ${detail}`);
+        throw new McpApiError(`API ${method} ${path} → ${res.status}: ${detail}`, res.status, data);
     }
-    return data;
+    return res.body;
 }
 /** Convenience: build the `/projects/<id>` path prefix for a resolved project. */
 function projectPath(ctx, projectId) {
     return `/projects/${requireProject(ctx, projectId).project.id}`;
 }
+/** Repository identity is relative to the resolved project, never a free path
+ * or another project's membership. MCP requires a choice where a file/Git
+ * operation could otherwise silently target the primary. */
+function requireRepository(ctx, projectId, repositoryId) {
+    const { project } = requireProject(ctx, projectId);
+    const repositories = (0, project_repositories_1.getProjectRepositories)(project);
+    if (repositoryId === undefined && repositories.length > 1) {
+        const data = { error: 'repository_required', projectId: project.id, repositories };
+        throw new McpApiError(`Provide repositoryId for this multi-repository project: ${JSON.stringify(data)}`, 400, data);
+    }
+    return (0, project_repositories_1.resolveProjectRepository)(project, repositoryId);
+}
+function repositoryPath(ctx, projectId, repositoryId) {
+    const repository = requireRepository(ctx, projectId, repositoryId);
+    const base = `/projects/${encodeURIComponent(repository.projectId)}`;
+    return repositoryId === undefined ? base : `${base}/repositories/${encodeURIComponent(repository.id)}`;
+}
 /**
  * Launch defaults derived from the LAUNCHING agent-chat conversation (the
  * authenticated origin carried on `ctx.originConversationId`). When the in-app agent
@@ -69,6 +102,7 @@ function originConversationDefaults(ctx) {
             return {};
         return {
             ...(conv.provider ? { provider: conv.provider } : {}),
+            ...(conv.model ? { model: conv.model } : {}),
             ...(conv.reasoning_effort ? { reasoningEffort: conv.reasoning_effort } : {}),
         };
     }
@@ -83,8 +117,12 @@ function requireProject(ctx, projectId) {
         throw new Error('No project specified and no active project selected. Call specrails_select_project or pass projectId.');
     }
     const pc = ctx.registry.getContext(id);
-    if (!pc)
+    if (!pc) {
+        if (ctx.registry.getProjectRow?.(id)) {
+            throw new Error(`Project "${id}" is registered but its database is temporarily unavailable. Retry after recovery; do not register a duplicate project.`);
+        }
         throw new Error(`Unknown projectId "${id}". Use specrails_projects(list) to see valid ids.`);
+    }
     return pc;
 }
 // ── Active-project stickiness (per server process) ────────────────────────────
@@ -93,11 +131,25 @@ function requireProject(ctx, projectId) {
 // wins over the process-wide selection. `setActiveProject` remains for
 // `specrails_select_project`; request context must never mutate this global.
 let _activeProjectId = null;
-function setActiveProject(id) {
-    _activeProjectId = id;
+function setActiveProject(ctxOrId, id) {
+    if (typeof ctxOrId === 'object' && ctxOrId !== null) {
+        ctxOrId.sessionState ??= { activeProjectId: null };
+        ctxOrId.sessionState.activeProjectId = id ?? null;
+    }
+    else {
+        // Compatibility for direct legacy unit callers. Live transports always
+        // provide sessionState and never consult or change this fallback.
+        _activeProjectId = ctxOrId;
+    }
 }
 function getActiveProject(ctx) {
-    return ctx.requestProjectId !== undefined ? ctx.requestProjectId : _activeProjectId;
+    return ctx.requestProjectId !== undefined ? ctx.requestProjectId
+        : ctx.sessionState ? ctx.sessionState.activeProjectId : _activeProjectId;
+}
+function toolTierAllowed(ctx, tier) {
+    return ctx.firstPartyAgent && ctx.agentTierLevel !== undefined
+        ? (0, agent_tier_1.levelAllowsTier)(ctx.agentTierLevel, tier)
+        : (0, mcp_tiers_1.isTierEnabled)(ctx.desktopDb, tier);
 }
 function tierAnnotations(tier) {
     switch (tier) {
@@ -112,7 +164,7 @@ function tierAnnotations(tier) {
     }
 }
 function toResult(data) {
-    const text = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+    const text = typeof data === 'string' ? data : JSON.stringify(data ?? null, null, 2);
     return { content: [{ type: 'text', text }] };
 }
 function errorResult(message) {
@@ -151,42 +203,64 @@ function emitMcpActivity(ctx, spec, args, tier) {
  * the tier check because it lives here, not in the handler.
  */
 function registerTieredTool(server, ctx, spec) {
-    const hintTier = spec.hintTier ?? (typeof spec.tier === 'string' ? spec.tier : 'write');
+    // An action facade may read, write, launch AI and delete data through ONE
+    // protocol tool. Advertising the common read action as readOnlyHint:true
+    // misleads clients that use annotations when approving mutations.
+    const annotations = typeof spec.tier === 'function'
+        ? { readOnlyHint: false, destructiveHint: true, openWorldHint: true }
+        : tierAnnotations(spec.tier);
     server.registerTool(spec.name, {
         title: spec.title,
         description: spec.description,
         inputSchema: spec.inputSchema,
-        annotations: tierAnnotations(hintTier),
+        annotations,
     }, async (args, extra) => {
+        if (extra?.signal?.aborted)
+            return errorResult('MCP request was cancelled before execution.');
         // Loopback identifies a machine, not a trusted caller. All first-party
         // authority and context come from this unguessable, server-minted bearer;
         // legacy tier/project/conversation headers are deliberately ignored.
-        const capability = (0, agent_capability_1.verifyAgentCapability)(extra?.requestInfo?.headers?.[agent_tier_1.AGENT_CAPABILITY_HEADER]);
+        const suppliedCapability = extra?.requestInfo?.headers?.[agent_tier_1.AGENT_CAPABILITY_HEADER];
+        const capability = (0, agent_capability_1.verifyAgentCapability)(suppliedCapability);
+        if (suppliedCapability !== undefined && !capability) {
+            return errorResult('Agent capability expired or was revoked. Start a new mission turn to reconnect.');
+        }
         const callCtx = capability
             ? {
                 ...ctx,
                 requestProjectId: capability.projectId,
                 originConversationId: capability.conversationId,
                 firstPartyAgent: true,
+                agentTierLevel: capability.tierLevel,
             }
-            : ctx;
+            : { ...ctx };
+        callCtx.signal = extra?.signal;
         const tier = typeof spec.tier === 'function' ? spec.tier(args ?? {}) : spec.tier;
-        if (capability) {
-            if (!(0, agent_tier_1.levelAllowsTier)(capability.tierLevel, tier)) {
-                return errorResult((0, mcp_tiers_1.tierRefusalMessage)(tier));
-            }
-        }
-        else if (!(0, mcp_tiers_1.isTierEnabled)(ctx.desktopDb, tier)) {
+        if (!toolTierAllowed(callCtx, tier)) {
             return errorResult((0, mcp_tiers_1.tierRefusalMessage)(tier));
         }
-        try {
-            const data = await spec.handler(callCtx, args ?? {});
-            if (tier !== 'read')
-                emitMcpActivity(callCtx, spec, args ?? {}, tier);
-            return toResult(data);
-        }
-        catch (err) {
-            return errorResult(err instanceof Error ? err.message : String(err));
+        const operation = async () => {
+            try {
+                const data = await spec.handler(callCtx, args ?? {});
+                if (tier !== 'read')
+                    emitMcpActivity(callCtx, spec, args ?? {}, tier);
+                return toResult(data);
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        };
+        if (capability && typeof suppliedCapability === 'string') {
+            callCtx.acknowledgeAgentUpdates = revision => (0, agent_steering_1.acknowledgeAgentSteering)(ctx.desktopDb, suppliedCapability, revision);
+            callCtx.acknowledgeAgentInputsRead = inputIds => (0, agent_steering_1.acknowledgeAgentInputsRead)(ctx.desktopDb, suppliedCapability, inputIds);
+            callCtx.onMissionInput = listener => (0, agent_steering_1.onAgentSteering)(ctx.desktopDb, suppliedCapability, listener);
+            return (0, agent_steering_1.runWithAgentSteering)(ctx.desktopDb, suppliedCapability, extra?.signal, operation, {
+                acknowledgement: spec.name === 'specrails_mission' && args?.action === 'acknowledge_updates',
+            });
         }
+        callCtx.acknowledgeAgentUpdates = undefined;
+        callCtx.acknowledgeAgentInputsRead = undefined;
+        callCtx.onMissionInput = undefined;
+        return operation();
     });
 }