specrails-desktop 2.30.2 → 2.31.0

package/server/dist/agent-generator.js

@@ -10,26 +10,26 @@ const crypto_1 = require("crypto");
 const tree_kill_1 = __importDefault(require("tree-kill"));
 const cli_prompt_1 = require("./util/cli-prompt");
 const providers_1 = require("./providers");
+const runtime_1 = require("./providers/runtime");
 const result_event_1 = require("./result-event");
 const ai_invocations_1 = require("./ai-invocations");
 const process_admission_1 = require("./process-admission");
 const transient_children_1 = require("./transient-children");
-const AGENT_STUDIO_ADAPTER = (0, providers_1.getAdapter)('claude');
 /**
  * Finalise the accumulated adapter events (native cost, or pricing-table
  * estimate when the run was killed before its `result` event) and persist one
  * surface='agent-studio' row. Best-effort — a recording failure is logged, never
  * thrown, so it can never break the generate/test flow.
  */
-function recordAgentStudioInvocation(ctx, events, status, startedAtIso) {
+function recordAgentStudioInvocation(ctx, adapter, events, status, startedAtIso) {
     try {
-        const { result, estimated } = (0, result_event_1.finaliseInvocationResult)(AGENT_STUDIO_ADAPTER, events, {
-            fallbackModel: AGENT_STUDIO_ADAPTER.defaultModel(),
+        const { result, estimated } = (0, result_event_1.finaliseInvocationResult)(adapter, events, {
+            fallbackModel: adapter.defaultModel(),
         });
         (0, ai_invocations_1.recordInvocation)(ctx.db, {
             id: (0, crypto_1.randomUUID)(),
             project_id: ctx.projectId,
-            provider: AGENT_STUDIO_ADAPTER.id,
+            provider: adapter.id,
             surface: 'agent-studio',
             surface_ref_id: ctx.surfaceRefId ?? null,
             status,
@@ -78,23 +78,37 @@ function escalateKill(child) {
         catch { /* already gone */ }
     }
 }
+function studioToolPolicy(adapter) {
+    const policies = adapter.capabilities.toolPolicies ?? [];
+    if (policies.includes('none'))
+        return 'none';
+    if (policies.includes('read-only'))
+        return 'read-only';
+    throw new Error(`provider_tool_policy_unsupported:${adapter.id}`);
+}
 async function generateCustomAgent(cwd, opts) {
     const admission = opts.record
         ? (0, process_admission_1.captureProcessAdmission)(opts.record.projectId)
         : (0, process_admission_1.captureProcessAdmission)();
+    const adapter = (0, providers_1.getAdapter)(opts.providerId ?? 'claude');
+    const providerFrontmatter = adapter.id === 'claude'
+        ? [
+            '  - model: one of `sonnet`, `opus`, `haiku`',
+            '  - color: one of `blue`, `green`, `red`, `yellow`, `purple`, `cyan`',
+            '  - memory: `project`',
+        ]
+        : [];
     const systemPrompt = [
         'You are a specrails agent-authoring assistant.',
         '',
         'Your task: given a short description of what the user wants, produce a COMPLETE',
         'Markdown file for a specrails custom agent. The file MUST be valid input for',
-        'Claude Code: YAML frontmatter between `---` separators, followed by the agent body.',
+        `${adapter.displayName}: YAML frontmatter between \`---\` separators, followed by the agent body.`,
         '',
         'Required frontmatter fields:',
         '  - name: the exact agent id (starts with `custom-`, lowercase, kebab-case)',
         '  - description: one sentence saying when this agent should run (include tag hints in square brackets)',
-        '  - model: one of `sonnet`, `opus`, `haiku`',
-        '  - color: one of `blue`, `green`, `red`, `yellow`, `purple`, `cyan`',
-        '  - memory: `project`',
+        ...providerFrontmatter,
         '',
         'Body sections (use `#` headings): Identity, Mission, Workflow protocol, Personality.',
         'Personality block: bullet list of tone, risk_tolerance, detail_level, focus_areas.',
@@ -108,22 +122,17 @@ async function generateCustomAgent(cwd, opts) {
         'Description of what it should do:',
         opts.description,
     ].join('\n');
+    const toolPolicy = studioToolPolicy(adapter);
     return new Promise((resolve, reject) => {
-        const child = (0, cli_prompt_1.spawnClaude)([
-            // This is a pure text transformation. The non-existent sentinel is
-            // intentional: an empty tool list is dropped by some Claude versions
-            // and silently restores the default toolkit.
-            '--tools',
-            '__none__',
-            '--output-format',
-            'stream-json',
-            '--verbose',
-            '--append-system-prompt',
+        const spawnOptions = {
+            prompt: userPrompt,
             systemPrompt,
-            '-p',
-            userPrompt,
-        ], {
-            env: process.env,
+            model: adapter.defaultModel(),
+            toolPolicy,
+        };
+        const args = adapter.buildArgs('agent-refine', spawnOptions);
+        const child = (0, cli_prompt_1.spawnAiCli)(adapter.binary, args, {
+            env: (0, runtime_1.buildProviderEnv)(adapter, spawnOptions),
             stdio: ['ignore', 'pipe', 'pipe'],
             cwd,
         });
@@ -142,7 +151,7 @@ async function generateCustomAgent(cwd, opts) {
             settled = true;
             clearTimeout(killer);
             if (record && admission.isCurrent()) {
-                recordAgentStudioInvocation(record, adapterEvents, status, startedAt);
+                recordAgentStudioInvocation(record, adapter, adapterEvents, status, startedAt);
             }
             complete();
         };
@@ -154,32 +163,11 @@ async function generateCustomAgent(cwd, opts) {
         }, 90_000);
         const reader = (0, readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
         reader.on('line', (line) => {
-            if (record) {
-                const ev = AGENT_STUDIO_ADAPTER.parseStreamLine(line);
-                if (ev)
+            for (const ev of (0, runtime_1.parseStreamEvents)(adapter, line)) {
+                if (record)
                     adapterEvents.push(ev);
-            }
-            let parsed;
-            try {
-                parsed = JSON.parse(line);
-            }
-            catch {
-                return;
-            }
-            if (!parsed || typeof parsed !== 'object')
-                return;
-            // Claude stream-json format: {type:"assistant", message:{content:[{type:"text", text:"..."}]}}
-            const p = parsed;
-            const message = p.message;
-            const content = message?.content;
-            if (Array.isArray(content)) {
-                for (const block of content) {
-                    if (block && typeof block === 'object' && block.type === 'text') {
-                        const text = block.text;
-                        if (typeof text === 'string')
-                            collected += text;
-                    }
-                }
+                if (ev.kind === 'text-delta')
+                    collected += ev.text;
             }
         });
         let stderr = '';
@@ -198,11 +186,11 @@ async function generateCustomAgent(cwd, opts) {
             const status = code === 0 && trimmed ? 'success' : 'failed';
             settle(status, () => {
                 if (code !== 0) {
-                    reject(new Error(`claude exited with code ${code}${stderr ? `: ${stderr.slice(-500)}` : ''}`));
+                    reject(new Error(`${adapter.binary} exited with code ${code}${stderr ? `: ${stderr.slice(-500)}` : ''}`));
                     return;
                 }
                 if (!trimmed) {
-                    reject(new Error('claude returned empty output'));
+                    reject(new Error(`${adapter.binary} returned empty output`));
                     return;
                 }
                 resolve(trimmed);
@@ -226,6 +214,7 @@ async function testCustomAgent(cwd, opts) {
         ? (0, process_admission_1.captureProcessAdmission)(opts.record.projectId)
         : (0, process_admission_1.captureProcessAdmission)();
     const tokenCeiling = opts.tokenCeiling ?? 4000;
+    const adapter = (0, providers_1.getAdapter)(opts.providerId ?? 'claude');
     // Strip YAML frontmatter so we feed only the agent's instructions.
     const body = opts.draftBody.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trim();
     if (!body) {
@@ -242,21 +231,17 @@ async function testCustomAgent(cwd, opts) {
     ].join('\n');
     const draftHash = (0, crypto_1.createHash)('sha256').update(opts.draftBody).digest('hex').slice(0, 16);
     const started = Date.now();
+    const toolPolicy = studioToolPolicy(adapter);
     return new Promise((resolve, reject) => {
-        const child = (0, cli_prompt_1.spawnClaude)([
-            // A Studio smoke test evaluates the supplied instructions and returns
-            // text; it never needs authority over the project it is testing in.
-            '--tools',
-            '__none__',
-            '--output-format',
-            'stream-json',
-            '--verbose',
-            '--append-system-prompt',
+        const spawnOptions = {
+            prompt: opts.sampleTask,
             systemPrompt,
-            '-p',
-            opts.sampleTask,
-        ], {
-            env: process.env,
+            model: adapter.defaultModel(),
+            toolPolicy,
+        };
+        const args = adapter.buildArgs('agent-refine', spawnOptions);
+        const child = (0, cli_prompt_1.spawnAiCli)(adapter.binary, args, {
+            env: (0, runtime_1.buildProviderEnv)(adapter, spawnOptions),
             stdio: ['ignore', 'pipe', 'pipe'],
             cwd,
         });
@@ -275,6 +260,7 @@ async function testCustomAgent(cwd, opts) {
         let msgTokensOut = 0;
         let resultTokensIn;
         let resultTokensOut;
+        let sawUsage = false;
         let truncated = false;
         // Accumulate adapter events for cost recording (surface='agent-studio', MED-3).
         const adapterEvents = [];
@@ -290,7 +276,7 @@ async function testCustomAgent(cwd, opts) {
             settled = true;
             clearTimeout(killer);
             if (record && admission.isCurrent()) {
-                recordAgentStudioInvocation(record, adapterEvents, status, startedAt);
+                recordAgentStudioInvocation(record, adapter, adapterEvents, status, startedAt);
             }
             complete();
         };
@@ -302,10 +288,11 @@ async function testCustomAgent(cwd, opts) {
         }, 120_000);
         const reader = (0, readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
         reader.on('line', (line) => {
-            if (record) {
-                const ev = AGENT_STUDIO_ADAPTER.parseStreamLine(line);
-                if (ev)
+            for (const ev of (0, runtime_1.parseStreamEvents)(adapter, line)) {
+                if (record)
                     adapterEvents.push(ev);
+                if (ev.kind === 'text-delta')
+                    collected += ev.text;
             }
             let parsed;
             try {
@@ -317,37 +304,34 @@ async function testCustomAgent(cwd, opts) {
             if (!parsed || typeof parsed !== 'object')
                 return;
             const p = parsed;
-            // Text blocks
             const message = p.message;
-            const content = message?.content;
-            if (Array.isArray(content)) {
-                for (const block of content) {
-                    if (block && typeof block === 'object' && block.type === 'text') {
-                        const text = block.text;
-                        if (typeof text === 'string')
-                            collected += text;
-                    }
-                }
-            }
             // Usage: the terminal `result` frame carries the cumulative total at the
             // top level; assistant frames carry a per-call `message.usage`. Route each
             // to its own accumulator so they are never double-counted.
             if (p.type === 'result') {
                 const usage = p.usage;
                 if (usage) {
-                    if (typeof usage.input_tokens === 'number')
+                    if (typeof usage.input_tokens === 'number') {
                         resultTokensIn = usage.input_tokens;
-                    if (typeof usage.output_tokens === 'number')
+                        sawUsage = true;
+                    }
+                    if (typeof usage.output_tokens === 'number') {
                         resultTokensOut = usage.output_tokens;
+                        sawUsage = true;
+                    }
                 }
             }
             else {
                 const usage = message?.usage;
                 if (usage) {
-                    if (typeof usage.input_tokens === 'number')
+                    if (typeof usage.input_tokens === 'number') {
                         msgTokensIn += usage.input_tokens;
-                    if (typeof usage.output_tokens === 'number')
+                        sawUsage = true;
+                    }
+                    if (typeof usage.output_tokens === 'number') {
                         msgTokensOut += usage.output_tokens;
+                        sawUsage = true;
+                    }
                 }
             }
             // Enforce token ceiling on the corrected running total.
@@ -373,14 +357,14 @@ async function testCustomAgent(cwd, opts) {
             const status = truncated ? 'aborted' : failedHard ? 'failed' : 'success';
             settle(status, () => {
                 if (failedHard) {
-                    reject(new Error(`claude exited with code ${code}${stderr ? `: ${stderr.slice(-500)}` : ''}`));
+                    reject(new Error(`${adapter.binary} exited with code ${code}${stderr ? `: ${stderr.slice(-500)}` : ''}`));
                     return;
                 }
                 resolve({
                     output: truncated
                         ? collected + `\n\n[… output truncated after reaching ${tokenCeiling}-token ceiling]`
                         : collected,
-                    tokens: runningTotalTokens(),
+                    tokens: sawUsage ? runningTotalTokens() : null,
                     durationMs,
                     draftHash,
                 });

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

@@ -17,6 +17,7 @@ const crypto_1 = require("crypto");
 const path_resolver_1 = require("./path-resolver");
 const win_spawn_1 = require("./util/win-spawn");
 const agent_tier_1 = require("./agent-tier");
+const providers_1 = require("./providers");
 const AGENT_CONVERSATION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
 // ─── Agent MCP wiring (design D8 / D1) ────────────────────────────────────────
 //
@@ -101,11 +102,12 @@ function buildSpecrailsMcpEntry(opts) {
  * Additive + idempotent: preserves any existing (e.g. plugin) mcpServers entries,
  * writes atomically (temp + rename), inlines NO token. Returns true when written.
  */
-function mergeSpecrailsIntoWorkspaceMcp(workspaceDir, port) {
+function mergeSpecrailsIntoWorkspaceMcp(workspaceDir, port, providerId = 'claude') {
     const entry = buildSpecrailsMcpEntry({ port });
     if (!entry)
         return false;
-    const file = path_1.default.join(workspaceDir, '.mcp.json');
+    const adapter = (0, providers_1.getAdapter)(providerId);
+    const file = adapter.projectMcpPath?.(workspaceDir) ?? path_1.default.join(workspaceDir, '.mcp.json');
     let current = {};
     try {
         if (fs_1.default.existsSync(file)) {
@@ -121,7 +123,7 @@ function mergeSpecrailsIntoWorkspaceMcp(workspaceDir, port) {
     const mcpServers = { ...(current.mcpServers ?? {}), specrails: entry };
     const next = { ...current, mcpServers };
     const tmp = `${file}.tmp-${process.pid}`;
-    fs_1.default.mkdirSync(workspaceDir, { recursive: true });
+    fs_1.default.mkdirSync(path_1.default.dirname(file), { recursive: true });
     fs_1.default.writeFileSync(tmp, JSON.stringify(next, null, 2));
     fs_1.default.renameSync(tmp, file);
     return true;
@@ -232,20 +234,22 @@ function codexMcpOverrides(entry) {
  * (agent then runs tool-less / degraded).
  */
 function prepareAgentMcp(opts) {
-    if (opts.adapterId === 'claude') {
+    const adapter = (0, providers_1.getAdapter)(opts.adapterId);
+    if (adapter.id === 'claude') {
         return { extraArgs: buildAgentMcpArgs(opts), env: {} };
     }
     const entry = buildAgentTurnEntry(opts);
     if (!entry)
         return { extraArgs: [], env: {} };
-    if (opts.adapterId === 'codex') {
+    if (adapter.mcpRegistration === 'cli-add') {
         // Inline -c overrides contain only the capability FILE PATH, never its secret.
         return { extraArgs: codexMcpOverrides(entry), env: {} };
     }
-    // gemini + any other project-json provider: write .mcp.json in the spawn cwd.
-    const file = path_1.default.join(opts.cwd, '.mcp.json');
+    // Project-json providers write only their native project config in the
+    // conversation-isolated cwd.
+    const file = adapter.projectMcpPath?.(opts.cwd) ?? path_1.default.join(opts.cwd, '.mcp.json');
     mergeServerIntoJsonFile(file, entry);
-    if (opts.adapterId === 'gemini') {
+    if (adapter.id === 'gemini') {
         // gemini-cli has NEVER read .mcp.json (a Claude convention) — its only MCP
         // surface is `mcpServers` in settings.json (user or <cwd>/.gemini project
         // scope), and an UNTRUSTED cwd suppresses MCP entirely (headless run exits
@@ -254,9 +258,6 @@ function prepareAgentMcp(opts) {
         // via env — the same pattern every other gemini spawn path already uses
         // (chat-manager / queue-manager / cli-prompt). Verified empirically against
         // gemini-cli 0.49.0 (see docs/internals note on FQN tool prefixing).
-        const geminiDir = path_1.default.join(opts.cwd, '.gemini');
-        fs_1.default.mkdirSync(geminiDir, { recursive: true });
-        mergeServerIntoJsonFile(path_1.default.join(geminiDir, 'settings.json'), entry);
         return { extraArgs: [], env: { GEMINI_CLI_TRUST_WORKSPACE: 'true' } };
     }
     return { extraArgs: [], env: {} };
@@ -278,5 +279,10 @@ function mergeServerIntoJsonFile(file, entry) {
         current = {};
     }
     const next = { ...current, mcpServers: { ...(current.mcpServers ?? {}), specrails: entry } };
+    fs_1.default.mkdirSync(path_1.default.dirname(file), { recursive: true, mode: 0o700 });
     fs_1.default.writeFileSync(file, JSON.stringify(next, null, 2), { mode: 0o600 });
+    try {
+        fs_1.default.chmodSync(file, 0o600);
+    }
+    catch { /* best-effort */ }
 }

package/server/dist/agent-operator-prompt.js

@@ -1,10 +1,13 @@
 "use strict";
 // ─── Single source of truth for the in-app operator agent prompts ─────────────
-// OPERATOR_INSTRUCTIONS is the CANONICAL prompt: written to CLAUDE.md/AGENTS.md/
-// GEMINI.md in ~/.specrails/agent-cwd/ — the only channel that reaches all three
-// providers (codex/gemini have no --system-prompt flag). OPERATOR_SYSTEM_PROMPT
-// is a compact distillation passed via --system-prompt on claude only (it
-// REPLACES the CLI's default system prompt — keep it).
+// OPERATOR_INSTRUCTIONS is the CANONICAL prompt written to CLAUDE.md,
+// AGENTS.md, and GEMINI.md in ~/.specrails/agent-cwd/. Kimi's native
+// instructions path is nested under `.kimi-code`, where its per-conversation
+// MCP config also lives; AgentChatManager therefore folds
+// OPERATOR_SYSTEM_PROMPT into Kimi's effective user turn instead of duplicating
+// the prompt in that native file. Claude receives the compact distillation via
+// --system-prompt (it REPLACES the CLI's default system prompt — keep it), while
+// Codex and Gemini auto-load their app-owned instruction files.
 //
 // BYTE-STABILITY CONTRACT: both constants must stay static (no timestamps, no
 // interpolation, no live data) so Anthropic prompt caching hits on turns 2+.
@@ -39,10 +42,10 @@ coding pipelines over them.
   (one pipeline job — Architect → Developer → Reviewer → Ship — over the rail's
   tickets), \`batch-implement\` (dependency-aware waves), Freestyle (API mode
   value \`freestyle\` only — call it \`Freestyle\` in prose; it sends a free-form
-  autonomous prompt straight to Claude, one job per ticket, Claude-only,
-  optional interactive in-job chat), \`loop\` (runs a saved workflow graph per
-  ticket). Launching spawns AI CLI processes that WRITE CODE, RUN TESTS and
-  COMMIT in the repo — it costs money and runs for minutes.
+  autonomous prompt straight to a capable provider, one job per ticket; Claude
+  also supports optional interactive in-job chat), \`loop\` (runs a saved
+  workflow graph per ticket). Launching spawns AI CLI processes that WRITE
+  CODE, RUN TESTS and COMMIT in the repo — it costs money and runs for minutes.
 - **Job** — one spawned run. Outcomes mutate spec status AUTOMATICALLY: launch →
   \`in_progress\`; success → \`done\`; revert → back to \`todo\`; partial confidence →
   \`done\` + \`needs_review\`. NEVER patch a status the pipeline manages; only
@@ -51,11 +54,13 @@ coding pipelines over them.
   publish with \`specrails_loops\`; RUN it with
   \`specrails_rails(launch, mode:'loop', loopId)\`.
 - **Profile** — per-project agent-chain config (which agents, which models,
-  routing). Claude-only; forced to null on codex/gemini rails.
-- **Provider / engine** — claude, codex or gemini. A project installs one or
-  more; AI-spawning actions may pick any installed one. Claude-only features:
-  profiles, Contract Refine, SMASH, Freestyle, interactive jobs. Cost is
-  authoritative on claude, estimated (~) on codex/gemini.
+  routing). Supported by Claude and Kimi; forced to null on Codex/Gemini rails.
+- **Provider / engine** — claude, codex, gemini or kimi. A project installs one
+  or more; AI-spawning actions may pick any installed one. Claude and Kimi
+  support profiles and Freestyle; Contract Refine and SMASH require Claude's
+  structured-action boundary. Persistent interactive jobs remain Claude-only.
+  Cost is authoritative on Claude, estimated (~) on Codex/Gemini, and
+  unavailable when Kimi does not report it.
 
 ## How to work
 
@@ -214,7 +219,8 @@ those through \`specrails_support\` instead.
   Only when the user hands you finished text and wants it untouched; otherwise
   prefer \`commit_draft\`.
 - **Big features**: offer SMASH (\`specrails_specs(smash)\`) to split an epic
-  into children (Claude-only). **Recurring work**: offer a loop.
+  into children when the effective provider supports structured actions
+  (currently Claude). **Recurring work**: offer a loop.
 
 ## Spec refinement mode (super specs)
 
@@ -335,8 +341,9 @@ summary later.
   spec lands, one short background AI pass appends a \`## Contract Layer\`
   section (naming contract, data shapes, state machine, invariants, file touch
   list). Pass \`contractRefine: false\` to skip it when the user declined it or
-  wants zero AI spend. Claude-only; respects the app-wide kill switch; when it
-  cannot run, the spec still lands unenriched.
+  wants zero AI spend. It requires a structured-action provider (currently
+  Claude), respects the app-wide kill switch, and leaves the spec unenriched when
+  it cannot run.
 - The enrichment is asynchronous: the commit returns immediately and the
   ticket updates in place when the Contract Layer arrives. To re-fire it
   later, use \`specrails_specs(contract_refine, id)\` — it also works on
@@ -394,7 +401,8 @@ summary later.
   never quote the raw railIndex as the rail's name.
 - Configure then launch: \`specrails_rails(set_tickets, railIndex, ticketIds)\` →
   \`specrails_rails(launch, railIndex, mode, …)\`. Setting a profile and then
-  switching the rail's engine to codex/gemini silently drops the profile.
+  switching the rail's engine to a provider without profile support
+  (Codex/Gemini) silently drops the profile.
 - When relaunching an \`on_review\` spec that already has an OPEN GitHub PR,
   \`launch\` automatically tries to continue that PR's head branch (matched by
   Jira key / spec id / title) instead of starting from the integration branch.
@@ -503,8 +511,9 @@ summary later.
   spec's status (done / reverted to todo / done with the needs-review flag —
   these are pipeline-managed; do not "fix" them yourself), duration, and cost —
   prefix the cost with \`~\` when the provider reports an estimate
-  (codex/gemini). Offer the Analytics page for detail. On failure, report the
-  failure faithfully and offer the diagnostic export.
+  (Codex/Gemini); say cost is unavailable when Kimi reports none. Offer the
+  Analytics page for detail. On failure, report the failure faithfully and
+  offer the diagnostic export.
 
 ## Stance