specrails-desktop 2.30.2 → 2.31.0

package/server/dist/loop-run-manager.js

@@ -19,6 +19,7 @@ const loop_runs_store_1 = require("./loop-runs-store");
 const ai_invocations_1 = require("./ai-invocations");
 const ids_1 = require("./ids");
 const providers_1 = require("./providers");
+const runtime_1 = require("./providers/runtime");
 const result_event_1 = require("./result-event");
 const rails_store_1 = require("./rails-store");
 const IMPLEMENT_CMD_TOKEN_RE = /\{\{\s*cmd:(?:implement|batch)\s*\}\}/;
@@ -153,13 +154,14 @@ function insertLoopInvocation(db, payload, result, finishedAt) {
       FROM ai_invocations
      WHERE surface = 'loop' AND loop_run_id = ?
   `).get(payload.runId);
+    const usageTelemetryAvailable = (0, providers_1.getAdapter)(payload.provider).capabilities.reportsUsage !== false;
     db.prepare(`
     UPDATE jobs
        SET total_cost_usd = ?, tokens_in = ?, tokens_out = ?,
            tokens_cache_read = ?, tokens_cache_create = ?,
            duration_ms = ?, num_turns = ?
      WHERE id = ? AND owner = 'loop'
-  `).run(aggregate.cost, aggregate.tokens_in, aggregate.tokens_out, aggregate.cache_read, aggregate.cache_create, aggregate.duration, aggregate.turns, payload.runId);
+  `).run(usageTelemetryAvailable ? aggregate.cost : null, usageTelemetryAvailable ? aggregate.tokens_in : null, usageTelemetryAvailable ? aggregate.tokens_out : null, usageTelemetryAvailable ? aggregate.cache_read : null, usageTelemetryAvailable ? aggregate.cache_create : null, aggregate.duration, usageTelemetryAvailable ? aggregate.turns : null, payload.runId);
 }
 /** Recover every AI/decider step that was staged before provider spawn but did
  * not atomically land its invocation. Completed interactive turns are the jobs
@@ -226,9 +228,9 @@ function recoverOrphanLoopStepAccounting(db, finishedAt = new Date().toISOString
        ORDER BY seq
     `).all(payload.runId, payload.completedEventSeq ?? -1);
         const adapter = (0, providers_1.getAdapter)(payload.provider);
+        const usageTelemetryAvailable = adapter.capabilities.reportsUsage !== false;
         const events = rawRows
-            .map((raw) => adapter.parseStreamLine(raw.payload))
-            .filter((event) => event != null);
+            .flatMap((raw) => [...(0, runtime_1.parseStreamEvents)(adapter, raw.payload)]);
         const { result: partial, estimated } = (0, result_event_1.finaliseInvocationResult)(adapter, events, {
             fallbackModel: payload.model ?? undefined,
         });
@@ -260,19 +262,34 @@ function recoverOrphanLoopStepAccounting(db, finishedAt = new Date().toISOString
         // never both.
         const recoveredDurationMs = (payload.completedDurationMs ?? 0) + partialDurationMs;
         const didRecover = (0, loop_runs_store_1.completeLoopStepRecovery)(db, payload.runId, payload.stepKey, (stable) => {
-            if (partialUsage.tokens_in || partialUsage.tokens_out ||
-                partialUsage.tokens_cache_read || partialUsage.tokens_cache_create ||
-                partialUsage.total_cost_usd || partialUsage.num_turns) {
+            if (usageTelemetryAvailable &&
+                (partialUsage.tokens_in || partialUsage.tokens_out ||
+                    partialUsage.tokens_cache_read || partialUsage.tokens_cache_create ||
+                    partialUsage.total_cost_usd || partialUsage.num_turns)) {
                 (0, db_1.accumulateInteractiveTurn)(db, payload.runId, partialUsage);
             }
             insertLoopInvocation(db, stable, {
-                cost: completed.totalCostUsd + partialUsage.total_cost_usd,
-                tokens: completed.tokensIn + completed.tokensOut + partialUsage.tokens_in + partialUsage.tokens_out,
-                tokensIn: completed.tokensIn + partialUsage.tokens_in,
-                tokensOut: completed.tokensOut + partialUsage.tokens_out,
-                tokensCacheRead: completed.tokensCacheRead + partialUsage.tokens_cache_read,
-                tokensCacheCreate: completed.tokensCacheCreate + partialUsage.tokens_cache_create,
-                numTurns: completed.numTurns + partialUsage.num_turns,
+                cost: usageTelemetryAvailable
+                    ? completed.totalCostUsd + partialUsage.total_cost_usd
+                    : undefined,
+                tokens: usageTelemetryAvailable
+                    ? completed.tokensIn + completed.tokensOut + partialUsage.tokens_in + partialUsage.tokens_out
+                    : undefined,
+                tokensIn: usageTelemetryAvailable
+                    ? completed.tokensIn + partialUsage.tokens_in
+                    : undefined,
+                tokensOut: usageTelemetryAvailable
+                    ? completed.tokensOut + partialUsage.tokens_out
+                    : undefined,
+                tokensCacheRead: usageTelemetryAvailable
+                    ? completed.tokensCacheRead + partialUsage.tokens_cache_read
+                    : undefined,
+                tokensCacheCreate: usageTelemetryAvailable
+                    ? completed.tokensCacheCreate + partialUsage.tokens_cache_create
+                    : undefined,
+                numTurns: usageTelemetryAvailable
+                    ? completed.numTurns + partialUsage.num_turns
+                    : undefined,
                 durationMs: recoveredDurationMs,
                 model: partial.model ?? payload.model ?? undefined,
                 sessionId: partial.session_id,
@@ -474,6 +491,14 @@ class LoopRunManager {
     async run(req) {
         if (this._disposed)
             throw new Error('LoopRunManager is shut down');
+        const adapter = (0, providers_1.getAdapter)(req.provider);
+        // A Decider is a structured, read-only judgment over repository state.
+        // Prompt wording is not a permission boundary: reject before allocating or
+        // persisting the run when the CLI cannot enforce read-only natively.
+        if (req.graph.nodes.some((node) => node.type === 'decider')) {
+            (0, providers_1.requireToolPolicy)(adapter, 'read-only');
+        }
+        const usageTelemetryAvailable = adapter.capabilities.reportsUsage !== false;
         const neverAfterDispose = () => new Promise(() => { });
         const runId = req.runId ?? (0, ids_1.newId)();
         const maxIterations = req.graph.config.maxIterations;
@@ -489,9 +514,13 @@ class LoopRunManager {
         // cap (may overshoot by at most one step). Honest accuracy caveat: for
         // non-Claude providers the per-step cost is ESTIMATED (rate card) — see the
         // fail-open warning below when a step yields no priced cost.
-        const maxCostUsd = typeof req.graph.config.maxCostUsd === 'number' && req.graph.config.maxCostUsd > 0
+        const configuredMaxCostUsd = typeof req.graph.config.maxCostUsd === 'number' && req.graph.config.maxCostUsd > 0
             ? req.graph.config.maxCostUsd
             : undefined;
+        // A cap with no observable usage is not a guard at all. Disable it rather
+        // than pretending an unknown bill is $0 and surface the limitation in the
+        // run log below.
+        const maxCostUsd = usageTelemetryAvailable ? configuredMaxCostUsd : undefined;
         const launchStartedAt = new Date(this.now()).toISOString();
         const jobCommand = `loop: ${req.loopName ?? req.loopId}${req.ticketId != null ? ` #${req.ticketId}` : ''}`;
         const exactTicketIds = req.spec?.ticketIds ?? (req.ticketId == null ? [] : [req.ticketId]);
@@ -610,6 +639,8 @@ class LoopRunManager {
                 const parsed = JSON.parse(line);
                 if (typeof parsed.type === 'string')
                     eventType = parsed.type;
+                else if (typeof parsed.role === 'string')
+                    eventType = parsed.role;
             }
             catch { /* not JSON */ }
             if (!eventType) {
@@ -635,6 +666,12 @@ class LoopRunManager {
         logLine(`▶ Loop "${req.loopName ?? req.loopId}" started${req.spec?.title ? ` — spec: ${req.spec.title}` : ''}`);
         if (req.isolation)
             logLine(`⎇ Isolated worktree: ${req.isolation.worktreePath} (branch ${req.isolation.branch})`);
+        if (!usageTelemetryAvailable) {
+            logLine(`⚠️ ${adapter.displayName} does not report token/cost usage in headless mode; usage totals will remain unavailable.` +
+                (configuredMaxCostUsd !== undefined
+                    ? ' The configured maxCostUsd guard is disabled because it cannot be verified.'
+                    : ''), 'stderr');
+        }
         // Per-run graph SNAPSHOT — once, before the first loop_step — so a later
         // edit/delete of the loop never breaks the historical replay of this run.
         const graphPayload = {
@@ -655,11 +692,11 @@ class LoopRunManager {
         let totalTokens = 0;
         let totalDuration = 0;
         let finalJobUsage = {
-            tokensIn: 0,
-            tokensOut: 0,
-            tokensCacheRead: 0,
-            tokensCacheCreate: 0,
-            numTurns: 0,
+            tokensIn: usageTelemetryAvailable ? 0 : null,
+            tokensOut: usageTelemetryAvailable ? 0 : null,
+            tokensCacheRead: usageTelemetryAvailable ? 0 : null,
+            tokensCacheCreate: usageTelemetryAvailable ? 0 : null,
+            numTurns: usageTelemetryAvailable ? 0 : null,
         };
         let aiSessionId;
         // Consecutive AI steps that hard-failed with no output (provider down /
@@ -706,13 +743,16 @@ class LoopRunManager {
         // The REAL turn-start instant, captured before the step/decider await. The
         // row is bucketed/ordered by started_at, so it must be the start, not finish.
         startedAt, stepKey) => {
-            totalCost += r.cost ?? 0;
+            if (usageTelemetryAvailable)
+                totalCost += r.cost ?? 0;
             // A cost-bearing step that produced work (tokens) or hard-failed but reports
             // no priced cost → its real spend is missing from the total. The common case
             // is a claude step killed by timeout before its terminal `result` event:
             // tokens streamed, but cost (and tokens) are dropped, so the step bills $0.
             // Flag the run total as a lower bound and say so, per occurrence.
-            const costBearingButUnpriced = r.cost == null && (r.failed === true || (r.tokens ?? 0) > 0);
+            const costBearingButUnpriced = usageTelemetryAvailable
+                && r.cost == null
+                && (r.failed === true || (r.tokens ?? 0) > 0);
             if (costBearingButUnpriced) {
                 costUncertain = true;
                 costUnknownWarned = true; // this line already carries the cap caveat below
@@ -720,11 +760,16 @@ class LoopRunManager {
             }
             // Honest cost-cap caveat: a cost-bearing step that reports no figure means
             // the cap can't be enforced precisely from here on. Warn once (live).
-            if (maxCostUsd !== undefined && r.cost == null && !costUnknownWarned) {
+            if (usageTelemetryAvailable
+                && maxCostUsd !== undefined
+                && r.cost == null
+                && !costUnknownWarned) {
                 costUnknownWarned = true;
                 logLine('⚠️ A step reported no priced cost (non-Claude estimate / unknown model / failed step) — the cost cap may under-count.', 'stderr');
             }
-            totalTokens += r.tokens ?? ((r.tokensIn ?? 0) + (r.tokensOut ?? 0));
+            if (usageTelemetryAvailable) {
+                totalTokens += r.tokens ?? ((r.tokensIn ?? 0) + (r.tokensOut ?? 0));
+            }
             totalDuration += r.durationMs ?? 0;
             const finishedAt = new Date(this.now()).toISOString();
             if (stepKey) {
@@ -1237,7 +1282,7 @@ class LoopRunManager {
                                 // session so the next pass starts fresh (re-reads the code on disk).
                                 // Provider-agnostic: clearing aiSessionId makes runAiStep use the
                                 // 'rail-job' (fresh) action, which every adapter maps to its own
-                                // native spawn — no claude/codex/gemini branching here.
+                                // native spawn — no claude/codex/gemini/kimi branching here.
                                 if (target === firstStepId)
                                     aiSessionId = undefined;
                             }
@@ -1303,8 +1348,10 @@ class LoopRunManager {
           FROM ai_invocations
          WHERE surface = 'loop' AND loop_run_id = ?
       `).get(runId);
-            totalCost = aggregate.cost;
-            totalTokens = aggregate.tokens_in + aggregate.tokens_out;
+            if (usageTelemetryAvailable) {
+                totalCost = aggregate.cost;
+                totalTokens = aggregate.tokens_in + aggregate.tokens_out;
+            }
             if (recoveredSteps > 0) {
                 // Recovery already committed the authoritative D+X totals. Refresh the
                 // traversal locals before finishLoopRunAndJob; otherwise a catch path
@@ -1319,18 +1366,21 @@ class LoopRunManager {
                     iteration = Math.max(iteration, durable.iteration_count);
                 }
             }
-            finalJobUsage = {
-                tokensIn: aggregate.tokens_in,
-                tokensOut: aggregate.tokens_out,
-                tokensCacheRead: aggregate.cache_read,
-                tokensCacheCreate: aggregate.cache_create,
-                numTurns: aggregate.turns,
-            };
+            if (usageTelemetryAvailable) {
+                finalJobUsage = {
+                    tokensIn: aggregate.tokens_in,
+                    tokensOut: aggregate.tokens_out,
+                    tokensCacheRead: aggregate.cache_read,
+                    tokensCacheCreate: aggregate.cache_create,
+                    numTurns: aggregate.turns,
+                };
+            }
         }
         catch (err) {
             console.error(`[loop] staged accounting reconciliation failed for ${runId}:`, err);
         }
-        console.log(`[loop] settle run=${runId} outcome=${outcome} iterations=${iteration} cost=$${totalCost.toFixed(4)}`);
+        console.log(`[loop] settle run=${runId} outcome=${outcome} iterations=${iteration} ` +
+            (usageTelemetryAvailable ? `cost=$${totalCost.toFixed(4)}` : 'usage=unavailable'));
         // Settle the backing job so the Jobs list + JobDetail reflect the final
         // status, and emit job.finalized so an open JobDetail re-fetches + stops the
         // live stream (mirrors QueueManager).
@@ -1341,14 +1391,20 @@ class LoopRunManager {
             : outcome === 'stopped' || outcome === 'stalled' ? 'canceled'
                 : 'failed';
         // `≥` when any cost-bearing step ended unpriced (timeout/crash) — the figure
-        // is a lower bound, not exact.
-        logLine(`\n■ Loop finished: ${outcome} — ${iteration} iteration${iteration === 1 ? '' : 's'}, ${costUncertain ? '≥ ' : ''}$${totalCost.toFixed(4)}`);
+        // is a lower bound, not exact. Providers without usage telemetry get an
+        // explicit unavailable marker, never a fabricated "$0.0000".
+        logLine(`\n■ Loop finished: ${outcome} — ${iteration} iteration${iteration === 1 ? '' : 's'}, ` +
+            (usageTelemetryAvailable
+                ? `${costUncertain ? '≥ ' : ''}$${totalCost.toFixed(4)}`
+                : 'usage/cost unavailable'));
         const finishedAt = new Date(this.now()).toISOString();
         (0, loop_runs_store_1.finishLoopRunAndJob)(this.db, runId, {
             outcome,
             finishedAt,
             counters: {
                 iterationCount: iteration,
+                // loop_runs retains its legacy non-null internal counters; public/job
+                // telemetry below carries the honest nullable availability contract.
                 totalCostUsd: totalCost,
                 totalTokens,
                 totalDurationMs: totalDuration,
@@ -1356,7 +1412,7 @@ class LoopRunManager {
             job: {
                 exitCode: outcome === 'success' ? 0 : 1,
                 status: jobStatus,
-                totalCostUsd: totalCost,
+                totalCostUsd: usageTelemetryAvailable ? totalCost : null,
                 tokensIn: finalJobUsage.tokensIn,
                 tokensOut: finalJobUsage.tokensOut,
                 tokensCacheRead: finalJobUsage.tokensCacheRead,
@@ -1377,7 +1433,7 @@ class LoopRunManager {
                 tokens_out: finalJobUsage.tokensOut,
                 tokens_cache_read: finalJobUsage.tokensCacheRead,
                 tokens_cache_create: finalJobUsage.tokensCacheCreate,
-                total_cost_usd: totalCost,
+                total_cost_usd: usageTelemetryAvailable ? totalCost : null,
                 num_turns: finalJobUsage.numTurns,
             },
             timestamp: new Date(this.now()).toISOString(),
@@ -1390,7 +1446,12 @@ class LoopRunManager {
             status: outcome,
             ticketIds: exactTicketIds,
         });
-        return { runId, outcome, iterations: iteration, totalCostUsd: totalCost };
+        return {
+            runId,
+            outcome,
+            iterations: iteration,
+            totalCostUsd: usageTelemetryAvailable ? totalCost : null,
+        };
     }
     /**
      * Run ONE ai-step as a resident interactive session (settleMode 'auto'):

package/server/dist/loops-router.js

@@ -64,7 +64,7 @@ function registerLoopsRoutes(router, deps) {
                 name: f.name,
                 description: f.description,
                 mode: f.mode,
-                claudeOnly: f.claudeOnly ?? false,
+                requiredCapability: f.requiredCapability ?? null,
                 graph: f.graph,
             })),
         });

package/server/dist/mcp/guide.js

@@ -17,7 +17,7 @@ differs by client kind (see below).
 
 Specrails is a local dashboard + pipeline runner that manages multiple software
 projects (registered repositories) and drives AI coding agents (Claude Code,
-Codex, Gemini) to implement specs.
+Codex, Gemini, Kimi Code) to implement specs.
 
 ## The object model
 
@@ -46,8 +46,8 @@ Codex, Gemini) to implement specs.
 - **Loop**: an APP-LEVEL saved workflow graph (not project-scoped). Author with
   \`specrails_loops\`; RUN it with \`specrails_rails(launch, mode:'loop', loopId)\`.
 - **Profile**: per-project agent configuration (which agents, which models,
-  routing). CLAUDE-ONLY; forced to null for codex/gemini rails.
-- **Provider / engine**: claude, codex or gemini. A project installs one or
+  routing). Supported by Claude and Kimi; forced to null for Codex/Gemini rails.
+- **Provider / engine**: claude, codex, gemini or kimi. A project installs one or
   more; a requested engine must be one of the installed set.
 - **Plugin**: an MCP-based integration installed per project (e.g. serena).
 
@@ -135,15 +135,15 @@ heading inside the description); \`labels\`; \`priority\`. Spec content is Engli
   - \`implement\`: one pipeline job (Architect → Developer → Reviewer → Ship)
     over the rail's tickets.
   - \`batch-implement\`: dependency-aware waves across many tickets.
-  - Freestyle: sends a free-form autonomous prompt straight to Claude — one job
-    per ticket; Claude-only; \`model\` picker; optional \`interactive\` in-job
-    chat (settle with \`specrails_jobs(finalize)\`). To launch it through the API,
-    pass the canonical mode value \`freestyle\`. In user-facing language, call
+  - Freestyle: sends a free-form autonomous prompt to a capable provider — one
+    job per ticket; Claude and Kimi; \`model\` picker. Claude additionally
+    supports optional \`interactive\` in-job chat (settle with
+    \`specrails_jobs(finalize)\`). To launch it through the API, pass the canonical mode value \`freestyle\`. In user-facing language, call
     the feature "Freestyle".
   - \`loop\`: runs a published loop graph per ticket (\`loopId\`,
     \`reasoning_effort\`).
-- Profiles are Claude-only: a profile set on a rail that is then pointed at
-  codex/gemini is force-nulled.
+- Profiles are supported by Claude and Kimi: a profile set on a rail that is
+  then pointed at Codex/Gemini is force-nulled.
 - \`stop\` kills the rail's process tree AND cancels its queued jobs
   (destructive).
 - \`specrails_jobs(spawn, command)\` bypasses rails and enqueues an arbitrary
@@ -196,20 +196,27 @@ global update work. Note the
 embedded spec-refinement happy path (investigate + commit_draft) needs only
 read + write — ai-spawn is required only to launch work or spawn a nested AI.
 
-## Providers & Claude-only surface
+## Providers & capability-gated surfaces
 
 - Installed providers are per-project; AI-spawning calls may pick any installed
   one (\`aiEngine\`); rails carry a per-rail engine.
-- CLAUDE-ONLY: agent profiles, Contract Refine, SMASH, Freestyle mode (API mode
-  \`freestyle\`; say "Freestyle" to users), interactive jobs. They are
-  rejected or inert when the effective engine is codex or gemini.
-- Cost figures are authoritative for claude and estimated for codex/gemini
-  (flagged as estimated in analytics).
+- Claude and Kimi support agent profiles and Freestyle mode (pass the canonical
+  API value \`freestyle\`; call the feature "Freestyle" to users). Persistent
+  interactive jobs remain Claude-only.
+- Kimi prompt mode cannot enforce a no-tools or read-only boundary. Consequently
+  pure-output and safety-bounded surfaces fail closed before spawn: Quick Spec,
+  AI Edit, Contract Refine, SMASH, Builder chat/commit, milestone generation,
+  Loop Decider, Code Explorer AI summaries, and Agent Studio automation. Use
+  Explore/direct authoring or another installed provider for those surfaces.
+- Cost figures are authoritative for Claude and estimated for Codex/Gemini
+  (flagged as estimated in analytics). Kimi cost is unavailable when its stream
+  omits usage and billing data.
 
 ## Domain cheat-sheet
 
 - **Epics / SMASH** (\`specrails_specs\`): \`smash\` splits a large spec into child
-  specs (Claude-only); \`smash_undo\` restores (needs the \`smashedAt\` stamp);
+  specs with a structured-action provider (currently Claude); \`smash_undo\`
+  restores (needs the \`smashedAt\` stamp);
   \`delete_epic_children\` removes a whole family.
 - **Attachments**: \`list_attachments\` / \`get_attachment\` read files the user
   attached in the app UI; \`generate\` / \`ai_edit\` accept \`attachmentIds\`.