specrails-desktop 2.16.0 → 2.17.0

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

@@ -0,0 +1,229 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loopsTools = loopsTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+/**
+ * Loops — the GLOBAL (cross-project) visual loop-builder library. Routes live at
+ * `/api/loops*` and `/api/loop-templates` (NOT under `/projects` — no projectId).
+ * Gated server-side by SPECRAILS_LOOPS_SECTION (every route 404s when off).
+ *
+ * A single domain-facade tool with an `action` enum and a dynamic tier:
+ *   - read:        list, get, templates, factory, commands, constants_list, preview
+ *   - write:       constant_create, constant_update, import, create, from_template,
+ *                  fork, update, publish, unpublish, duplicate
+ *   - destructive: constant_delete, delete
+ */
+function loopsTools() {
+    return [
+        {
+            name: 'specrails_loops',
+            title: 'Loops',
+            description: 'Manage the global (cross-project) loop library and its templates/factory/constants. ' +
+                'Loops are visual builder graphs reused across projects; this is an APP-LEVEL domain (no projectId). ' +
+                'Actions: ' +
+                'list (all saved loops), ' +
+                'get (one loop by id), ' +
+                'templates (built-in template catalog with graphs), ' +
+                'factory (built-in locked factory loops), ' +
+                'commands (magic-command catalog for the builder palette), ' +
+                'constants_list (global cross-loop constants), ' +
+                'constant_create (write), constant_update (write), constant_delete (destructive), ' +
+                'preview (dry-run resolve tokens of a graph — no spawn), ' +
+                'import (import loops from an export envelope), ' +
+                'create (new Draft loop), ' +
+                'from_template (instantiate from a template), ' +
+                'fork (fork a factory loop into an editable Draft), ' +
+                'update (name/description/graph — reverts to Draft, 409 while running), ' +
+                'publish (graph-validated), unpublish (409 while running), ' +
+                'duplicate (copy a loop), ' +
+                'delete (destructive — 409 while running).',
+            hintTier: 'read',
+            tier: (a) => {
+                const action = a.action;
+                if (action === 'delete' || action === 'constant_delete')
+                    return 'destructive';
+                if ([
+                    'constant_create',
+                    'constant_update',
+                    'import',
+                    'create',
+                    'from_template',
+                    'fork',
+                    'update',
+                    'publish',
+                    'unpublish',
+                    'duplicate',
+                ].includes(action)) {
+                    return 'write';
+                }
+                return 'read';
+            },
+            inputSchema: {
+                action: zod_1.z
+                    .enum([
+                    'list',
+                    'get',
+                    'templates',
+                    'factory',
+                    'commands',
+                    'constants_list',
+                    'constant_create',
+                    'constant_update',
+                    'constant_delete',
+                    'preview',
+                    'import',
+                    'create',
+                    'from_template',
+                    'fork',
+                    'update',
+                    'publish',
+                    'unpublish',
+                    'duplicate',
+                    'delete',
+                ])
+                    .describe('Operation to perform'),
+                loopId: zod_1.z.string().optional().describe('Loop id (for get / update / publish / unpublish / duplicate / delete)'),
+                constantId: zod_1.z.string().optional().describe('Constant id (for constant_update / constant_delete)'),
+                templateId: zod_1.z.string().optional().describe('Template id (for from_template)'),
+                factoryId: zod_1.z.string().optional().describe('Factory loop id (for fork)'),
+                name: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Loop or constant name (required for create / constant_create; optional override for from_template / fork / duplicate / update)'),
+                description: zod_1.z.string().optional().describe('Loop description (for create / update)'),
+                graph: zod_1.z
+                    .record(zod_1.z.unknown())
+                    .optional()
+                    .describe('Loop graph object { nodes, edges, ... } (for create / update; required for preview)'),
+                value: zod_1.z.string().optional().describe('Constant value (for constant_create / constant_update)'),
+                provider: zod_1.z.string().optional().describe('Provider for token resolution in preview (default "claude")'),
+                loops: zod_1.z.array(zod_1.z.unknown()).optional().describe('Array of loop export envelopes (for import)'),
+            },
+            async handler(ctx, args) {
+                const action = args.action;
+                const loopId = args.loopId;
+                const constantId = args.constantId;
+                switch (action) {
+                    // ── Reads ──────────────────────────────────────────────────────────
+                    case 'list':
+                        return (0, types_1.apiCall)(ctx, 'GET', '/loops');
+                    case 'get': {
+                        if (!loopId)
+                            throw new Error('get requires a "loopId".');
+                        return (0, types_1.apiCall)(ctx, 'GET', `/loops/${encodeURIComponent(loopId)}`);
+                    }
+                    case 'templates':
+                        return (0, types_1.apiCall)(ctx, 'GET', '/loop-templates');
+                    case 'factory':
+                        return (0, types_1.apiCall)(ctx, 'GET', '/loops/factory');
+                    case 'commands':
+                        return (0, types_1.apiCall)(ctx, 'GET', '/loops/commands');
+                    case 'constants_list':
+                        return (0, types_1.apiCall)(ctx, 'GET', '/loops/constants');
+                    case 'preview': {
+                        const graph = args.graph;
+                        if (!graph)
+                            throw new Error('preview requires a "graph".');
+                        return (0, types_1.apiCall)(ctx, 'POST', '/loops/preview', {
+                            graph,
+                            ...(args.provider !== undefined ? { provider: args.provider } : {}),
+                        });
+                    }
+                    // ── Constants (write / destructive) ─────────────────────────────────
+                    case 'constant_create': {
+                        const name = args.name;
+                        if (!name)
+                            throw new Error('constant_create requires a "name".');
+                        return (0, types_1.apiCall)(ctx, 'POST', '/loops/constants', {
+                            name,
+                            value: args.value ?? '',
+                        });
+                    }
+                    case 'constant_update': {
+                        if (!constantId)
+                            throw new Error('constant_update requires a "constantId".');
+                        return (0, types_1.apiCall)(ctx, 'PUT', `/loops/constants/${encodeURIComponent(constantId)}`, {
+                            value: args.value ?? '',
+                        });
+                    }
+                    case 'constant_delete': {
+                        if (!constantId)
+                            throw new Error('constant_delete requires a "constantId".');
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `/loops/constants/${encodeURIComponent(constantId)}`);
+                    }
+                    // ── Loops (write) ───────────────────────────────────────────────────
+                    case 'import': {
+                        const loops = args.loops;
+                        if (!Array.isArray(loops))
+                            throw new Error('import requires a "loops" array.');
+                        return (0, types_1.apiCall)(ctx, 'POST', '/loops/import', { loops });
+                    }
+                    case 'create': {
+                        const name = args.name;
+                        if (!name)
+                            throw new Error('create requires a "name".');
+                        return (0, types_1.apiCall)(ctx, 'POST', '/loops', {
+                            name,
+                            ...(args.description !== undefined ? { description: args.description } : {}),
+                            ...(args.graph !== undefined ? { graph: args.graph } : {}),
+                        });
+                    }
+                    case 'from_template': {
+                        const templateId = args.templateId;
+                        if (!templateId)
+                            throw new Error('from_template requires a "templateId".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `/loops/from-template/${encodeURIComponent(templateId)}`, {
+                            ...(args.name !== undefined ? { name: args.name } : {}),
+                        });
+                    }
+                    case 'fork': {
+                        const factoryId = args.factoryId;
+                        if (!factoryId)
+                            throw new Error('fork requires a "factoryId".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `/loops/factory/${encodeURIComponent(factoryId)}/fork`, {
+                            ...(args.name !== undefined ? { name: args.name } : {}),
+                        });
+                    }
+                    case 'update': {
+                        if (!loopId)
+                            throw new Error('update requires a "loopId".');
+                        const body = {};
+                        if (args.name !== undefined)
+                            body.name = args.name;
+                        if (args.description !== undefined)
+                            body.description = args.description;
+                        if (args.graph !== undefined)
+                            body.graph = args.graph;
+                        return (0, types_1.apiCall)(ctx, 'PUT', `/loops/${encodeURIComponent(loopId)}`, body);
+                    }
+                    case 'publish': {
+                        if (!loopId)
+                            throw new Error('publish requires a "loopId".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `/loops/${encodeURIComponent(loopId)}/publish`);
+                    }
+                    case 'unpublish': {
+                        if (!loopId)
+                            throw new Error('unpublish requires a "loopId".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `/loops/${encodeURIComponent(loopId)}/unpublish`);
+                    }
+                    case 'duplicate': {
+                        if (!loopId)
+                            throw new Error('duplicate requires a "loopId".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `/loops/${encodeURIComponent(loopId)}/duplicate`, {
+                            ...(args.name !== undefined ? { name: args.name } : {}),
+                        });
+                    }
+                    // ── Destructive ─────────────────────────────────────────────────────
+                    case 'delete': {
+                        if (!loopId)
+                            throw new Error('delete requires a "loopId".');
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `/loops/${encodeURIComponent(loopId)}`);
+                    }
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}

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

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.metaTools = metaTools;
+const zod_1 = require("zod");
+const guide_1 = require("../guide");
+const types_1 = require("./types");
+/**
+ * Meta tools that teach the platform and aid discovery.
+ * `getSpecs` returns the full catalog (passed lazily to avoid a cycle).
+ */
+function metaTools(getSpecs) {
+    return [
+        {
+            name: 'specrails_guide',
+            title: 'Platform guide',
+            description: 'Returns a self-contained guide to Specrails: concepts, workflow, invariants, and how to use these tools. Read this first.',
+            tier: 'read',
+            inputSchema: {},
+            handler: () => guide_1.SPECRAILS_GUIDE,
+        },
+        {
+            name: 'specrails_search',
+            title: 'Search tools',
+            description: 'Find the right Specrails tool/action for an intent. Returns matching tools with their descriptions.',
+            tier: 'read',
+            inputSchema: {
+                query: zod_1.z.string().describe('Natural-language intent, e.g. "launch the pipeline for a ticket"'),
+            },
+            handler: (_ctx, args) => {
+                const q = String(args.query ?? '').toLowerCase().trim();
+                const terms = q.split(/\s+/).filter(Boolean);
+                const scored = getSpecs()
+                    .filter((s) => s.name !== 'specrails_search')
+                    .map((s) => {
+                    const hay = `${s.name} ${s.title} ${s.description}`.toLowerCase();
+                    const score = terms.reduce((acc, t) => acc + (hay.includes(t) ? 1 : 0), 0);
+                    return { name: s.name, title: s.title, description: s.description, score };
+                })
+                    .filter((r) => r.score > 0)
+                    .sort((a, b) => b.score - a.score)
+                    .slice(0, 8);
+                return scored.length ? scored : { hint: 'No direct match. Call specrails_guide for an overview, or list all tools.' };
+            },
+        },
+        {
+            name: 'specrails_describe',
+            title: 'Describe a tool',
+            description: 'Return the full description and input schema summary for a named Specrails tool.',
+            tier: 'read',
+            inputSchema: {
+                name: zod_1.z.string().describe('Tool name, e.g. "specrails_rails"'),
+            },
+            handler: (_ctx, args) => {
+                const name = String(args.name ?? '');
+                const spec = getSpecs().find((s) => s.name === name);
+                if (!spec)
+                    throw new Error(`Unknown tool "${name}". Use specrails_search to find one.`);
+                return {
+                    name: spec.name,
+                    title: spec.title,
+                    description: spec.description,
+                    inputFields: Object.keys(spec.inputSchema),
+                };
+            },
+        },
+        {
+            name: 'specrails_select_project',
+            title: 'Select active project',
+            description: 'Set the active project so subsequent per-project tools may omit projectId. Pass an id or a path. Pass null to clear.',
+            tier: 'read',
+            inputSchema: {
+                projectId: zod_1.z.string().nullable().optional().describe('Project id to make active, or null to clear'),
+                path: zod_1.z.string().optional().describe('Resolve+select a project by filesystem path instead of id'),
+            },
+            handler: (ctx, args) => {
+                if (args.path) {
+                    const pc = ctx.registry.getContextByPath(String(args.path));
+                    if (!pc)
+                        throw new Error(`No project registered at path "${args.path}".`);
+                    (0, types_1.setActiveProject)(pc.project.id);
+                    return { active: pc.project.id, name: pc.project.name };
+                }
+                if (args.projectId === null) {
+                    (0, types_1.setActiveProject)(null);
+                    return { active: null };
+                }
+                const id = args.projectId;
+                if (!id)
+                    throw new Error('Provide a projectId, a path, or null.');
+                const pc = (0, types_1.requireProject)(ctx, id);
+                (0, types_1.setActiveProject)(pc.project.id);
+                return { active: pc.project.id, name: pc.project.name };
+            },
+        },
+    ];
+}

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

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginsTools = pluginsTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+/**
+ * Plugins (Integrations) domain facade. Per-project marketplace of MCP-based
+ * integrations (bundled-only in v1). Maps each action to the matching REST
+ * endpoint under `/api/projects/:projectId/plugins`.
+ *
+ * Excluded by design (v1 out of scope): the `uv` prerequisite installer
+ * (`/plugins/_prerequisites/:prereq/install`) and the marketplace
+ * global-settings mutation (`/plugins/_marketplace/disable`).
+ */
+function pluginsTools() {
+    return [
+        {
+            name: 'specrails_plugins',
+            title: 'Plugins',
+            description: 'List and manage a project\'s MCP-based integration plugins (Integrations). ' +
+                'Actions: list (catalog with status/health/version/drift), preview (dry-run install diff + requirements), ' +
+                'install (write — runs the installer + verify, surgically merges .mcp.json, streams plugin.install_progress; long-running), ' +
+                'uninstall (destructive — reverts contributors, removes owned mcpServers + installed files, drops state), ' +
+                'activate (re-enable an installed-but-off plugin), deactivate (toggle off without uninstalling), ' +
+                'update (apply manifest drift — re-merge owned mcpServers + re-apply contributors), ' +
+                'health (on-demand verify of an installed plugin).',
+            hintTier: 'read',
+            tier: (a) => {
+                const action = a.action;
+                if (action === 'uninstall')
+                    return 'destructive';
+                if (['install', 'activate', 'deactivate', 'update'].includes(action))
+                    return 'write';
+                return 'read';
+            },
+            inputSchema: {
+                action: zod_1.z
+                    .enum(['list', 'preview', 'install', 'uninstall', 'activate', 'deactivate', 'update', 'health'])
+                    .describe('Operation to perform'),
+                projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+                name: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Bundled plugin name (required for preview/install/uninstall/activate/deactivate/update/health)'),
+            },
+            async handler(ctx, args) {
+                const base = `${(0, types_1.projectPath)(ctx, args.projectId)}/plugins`;
+                const action = args.action;
+                const name = args.name;
+                const requireName = () => {
+                    if (!name)
+                        throw new Error(`Action "${action}" requires a "name" (bundled plugin name).`);
+                    return encodeURIComponent(name);
+                };
+                switch (action) {
+                    case 'list':
+                        return (0, types_1.apiCall)(ctx, 'GET', base);
+                    case 'preview':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/${requireName()}/preview-install`);
+                    case 'install': {
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/${requireName()}/install`);
+                        return {
+                            ...(typeof r === 'object' && r !== null ? r : { result: r }),
+                            hint: 'Install runs the plugin installer + verify and streams plugin.install_progress / plugin.installed WS events. Use specrails_watch to observe progress, or call action="health" to confirm the plugin verified.',
+                        };
+                    }
+                    case 'uninstall':
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/${requireName()}`);
+                    case 'activate':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/${requireName()}/activate`);
+                    case 'deactivate':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/${requireName()}/deactivate`);
+                    case 'update':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/${requireName()}/update`);
+                    case 'health':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/${requireName()}/health`);
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}

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

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeProject = serializeProject;
+exports.projectsTools = projectsTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+function serializeProject(p) {
+    return {
+        id: p.id,
+        slug: p.slug,
+        name: p.name,
+        path: p.path,
+        provider: p.provider,
+        providers: p.providers,
+        addedAt: p.added_at,
+        lastSeenAt: p.last_seen_at,
+    };
+}
+function projectsTools() {
+    return [
+        {
+            name: 'specrails_projects',
+            title: 'Projects',
+            description: 'List and inspect registered Specrails projects, resolve a project by filesystem path, or unregister one. ' +
+                'Actions: list, get, resolve (by path), unregister (destructive — removes the project and its workspace).',
+            hintTier: 'read',
+            tier: (args) => (args.action === 'unregister' ? 'destructive' : 'read'),
+            inputSchema: {
+                action: zod_1.z.enum(['list', 'get', 'resolve', 'unregister']).describe('Operation to perform'),
+                projectId: zod_1.z.string().optional().describe('Project id (for get / unregister)'),
+                path: zod_1.z.string().optional().describe('Filesystem path (for resolve)'),
+            },
+            handler: (ctx, args) => {
+                const action = args.action;
+                switch (action) {
+                    case 'list':
+                        return ctx.registry.listContexts().map((c) => serializeProject(c.project));
+                    case 'get':
+                        return serializeProject((0, types_1.requireProject)(ctx, args.projectId).project);
+                    case 'resolve': {
+                        const p = args.path;
+                        if (!p)
+                            throw new Error('resolve requires a "path".');
+                        const pc = ctx.registry.getContextByPath(p);
+                        return pc ? serializeProject(pc.project) : { resolved: false };
+                    }
+                    case 'unregister': {
+                        const id = args.projectId;
+                        if (!id)
+                            throw new Error('unregister requires a "projectId".');
+                        if (!ctx.registry.getContext(id))
+                            throw new Error(`Unknown projectId "${id}".`);
+                        ctx.registry.removeProject(id);
+                        return { ok: true, unregistered: id };
+                    }
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}

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

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.railsTools = railsTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+/**
+ * Rails domain facade. A "rail" is a numbered launch slot per project: it holds
+ * a set of assigned ticket IDs plus a mode/profile/engine/name, and launching it
+ * spawns the AI pipeline (claude/codex/gemini) over those tickets.
+ *
+ * Every operation is per-project under /api/projects/:projectId/rails. The
+ * launch action is the only cost-incurring / repo-mutating one (ai-spawn, 202);
+ * stop is destructive (kills running child process trees + cancels queued jobs).
+ */
+function railsTools() {
+    return [
+        {
+            name: 'specrails_rails',
+            title: 'Rails',
+            description: 'List and configure a project\'s rail launch slots, then launch or stop the AI pipeline for a rail. ' +
+                'A rail holds assigned ticket IDs plus a mode/profile/engine/name. ' +
+                'Actions: list (rails + active jobs/loop runs), set_tickets (assign ticket IDs), set_profile (default agent profile, null=legacy), ' +
+                'set_engine (provider override, null=primary), set_name (display label, null clears), ' +
+                'launch (ai-spawn — spawns claude/codex/gemini CLI job(s) that WRITE CODE, RUN TESTS, COMMIT, and INCUR TOKEN COST; returns 202 with jobId/jobIds/loopRunIds), ' +
+                'stop (destructive — kills all active jobs and loop runs for the rail).',
+            hintTier: 'read',
+            tier: (a) => {
+                const action = a.action;
+                if (action === 'stop')
+                    return 'destructive';
+                if (action === 'launch')
+                    return 'ai-spawn';
+                if (action === 'set_tickets' || action === 'set_profile' || action === 'set_engine' || action === 'set_name')
+                    return 'write';
+                return 'read';
+            },
+            inputSchema: {
+                action: zod_1.z
+                    .enum(['list', 'set_tickets', 'set_profile', 'set_engine', 'set_name', 'launch', 'stop'])
+                    .describe('Operation to perform'),
+                projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+                railIndex: zod_1.z
+                    .number()
+                    .int()
+                    .min(0)
+                    .optional()
+                    .describe('Rail slot index (required for every action except list)'),
+                // set_tickets
+                ticketIds: zod_1.z
+                    .array(zod_1.z.number().int())
+                    .optional()
+                    .describe('Ticket IDs to assign to the rail (set_tickets — replaces the existing set)'),
+                // set_profile
+                profileName: zod_1.z
+                    .string()
+                    .nullable()
+                    .optional()
+                    .describe('Agent profile name; null forces legacy/no-profile mode (set_profile; also optional override for launch)'),
+                // set_engine / launch
+                aiEngine: zod_1.z
+                    .string()
+                    .nullable()
+                    .optional()
+                    .describe('AI engine/provider override; null = project primary (set_engine; also optional override for launch). Must be an installed provider.'),
+                // set_name
+                name: zod_1.z
+                    .string()
+                    .nullable()
+                    .optional()
+                    .describe('Rail display label (<=60 chars); null/empty clears to default (set_name)'),
+                // launch
+                mode: zod_1.z
+                    .enum(['implement', 'batch-implement', 'ultracode', 'loop'])
+                    .optional()
+                    .describe('Launch mode (launch; default "implement"). ultracode is Claude-only and runs one job per ticket; loop runs an app-driven loop per ticket.'),
+                model: zod_1.z
+                    .enum(['haiku', 'sonnet', 'opus'])
+                    .optional()
+                    .describe('Ultracode Claude model (launch, ultracode mode only). For loop mode, a provider-valid model string.'),
+                interactive: zod_1.z
+                    .boolean()
+                    .optional()
+                    .describe('Interactive ultracode session (launch, ultracode + Claude only; requires the interactive-jobs feature)'),
+                loopId: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Loop id to run (launch). Factory ids (e.g. "factory:implement") map to a legacy mode; a custom published loop id keeps mode="loop".'),
+                reasoning_effort: zod_1.z
+                    .enum(['low', 'medium', 'high'])
+                    .optional()
+                    .describe('Reasoning-effort tier for loop launches (launch, loop mode)'),
+            },
+            async handler(ctx, args) {
+                const base = `${(0, types_1.projectPath)(ctx, args.projectId)}/rails`;
+                const action = args.action;
+                const requireRailIndex = () => {
+                    const idx = args.railIndex;
+                    if (typeof idx !== 'number' || !Number.isInteger(idx) || idx < 0) {
+                        throw new Error(`Action "${action}" requires a non-negative integer "railIndex".`);
+                    }
+                    return idx;
+                };
+                switch (action) {
+                    case 'list':
+                        return (0, types_1.apiCall)(ctx, 'GET', base);
+                    case 'set_tickets': {
+                        const railIndex = requireRailIndex();
+                        const ticketIds = args.ticketIds;
+                        if (!Array.isArray(ticketIds)) {
+                            throw new Error('set_tickets requires "ticketIds" (an array of numbers).');
+                        }
+                        const body = { ticketIds };
+                        if (args.mode !== undefined)
+                            body.mode = args.mode;
+                        if ('profileName' in args && args.profileName !== undefined)
+                            body.profileName = args.profileName;
+                        if ('aiEngine' in args && args.aiEngine !== undefined)
+                            body.aiEngine = args.aiEngine;
+                        return (0, types_1.apiCall)(ctx, 'PUT', `${base}/${railIndex}/tickets`, body);
+                    }
+                    case 'set_profile': {
+                        const railIndex = requireRailIndex();
+                        if (!('profileName' in args)) {
+                            throw new Error('set_profile requires "profileName" (string or null).');
+                        }
+                        return (0, types_1.apiCall)(ctx, 'PUT', `${base}/${railIndex}/profile`, {
+                            profileName: (args.profileName ?? null),
+                        });
+                    }
+                    case 'set_engine': {
+                        const railIndex = requireRailIndex();
+                        if (!('aiEngine' in args)) {
+                            throw new Error('set_engine requires "aiEngine" (string or null).');
+                        }
+                        return (0, types_1.apiCall)(ctx, 'PUT', `${base}/${railIndex}/engine`, {
+                            aiEngine: (args.aiEngine ?? null),
+                        });
+                    }
+                    case 'set_name': {
+                        const railIndex = requireRailIndex();
+                        if (!('name' in args)) {
+                            throw new Error('set_name requires "name" (string or null).');
+                        }
+                        return (0, types_1.apiCall)(ctx, 'PUT', `${base}/${railIndex}/name`, {
+                            name: (args.name ?? null),
+                        });
+                    }
+                    case 'launch': {
+                        const railIndex = requireRailIndex();
+                        const body = {};
+                        if (args.mode !== undefined)
+                            body.mode = args.mode;
+                        if ('profileName' in args && args.profileName !== undefined)
+                            body.profileName = args.profileName;
+                        if ('aiEngine' in args && args.aiEngine !== undefined)
+                            body.aiEngine = args.aiEngine;
+                        if (args.model !== undefined)
+                            body.model = args.model;
+                        if (args.interactive !== undefined)
+                            body.interactive = args.interactive;
+                        if (args.loopId !== undefined)
+                            body.loopId = args.loopId;
+                        if (args.reasoning_effort !== undefined)
+                            body.reasoning_effort = args.reasoning_effort;
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/${railIndex}/launch`, body);
+                        return {
+                            ...r,
+                            hint: 'Launch accepted (202). Use specrails_watch with the returned jobId/jobIds (or loopRunIds for loop mode) to await completion. Live output streams over the job WS.',
+                        };
+                    }
+                    case 'stop': {
+                        const railIndex = requireRailIndex();
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/${railIndex}/stop`);
+                    }
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}