specrails-desktop 2.30.2 → 2.31.0

package/server/dist/framework-manager.js

@@ -26,6 +26,22 @@ const path_resolver_1 = require("./path-resolver");
 function nodeInterpreter() {
     return (0, path_resolver_1.resolveBundledNodeExe)() ?? process.execPath;
 }
+/**
+ * Resolve symlinks in the CLI path we pass as the child's argv[1]. Core's
+ * cli.js auto-run guard compares import.meta.url (realpathed by Node's ESM
+ * loader) against pathToFileURL(process.argv[1]) — a symlinked argv[1] (e.g.
+ * a staging dir under macOS /var/folders) makes them differ, so main() never
+ * runs and the child exits 0 as a silent no-op. Realpathing here keeps the
+ * guard true regardless of where the core package lives.
+ */
+function realpathOrSelf(p) {
+    try {
+        return fs_1.default.realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
 /** `~/.specrails/framework` — same home as the registry. */
 function frameworkRoot(home) {
     return path_1.default.join((0, artifact_registry_1.resolveHome)(home), '.specrails', 'framework');
@@ -121,9 +137,10 @@ class FrameworkManager {
     resolveCli() {
         if (this.coreRoot) {
             const cli = path_1.default.join(this.coreRoot, 'dist', 'installer', 'cli.js');
-            return fs_1.default.existsSync(cli) ? cli : null;
+            return fs_1.default.existsSync(cli) ? realpathOrSelf(cli) : null;
         }
-        return (0, bundled_core_1.getBundledCoreCli)();
+        const bundled = (0, bundled_core_1.getBundledCoreCli)();
+        return bundled ? realpathOrSelf(bundled) : null;
     }
     /** True when a usable core (override or bundled) is present (else methods no-op). */
     isAvailable() {

package/server/dist/framework-migration.js

@@ -11,16 +11,30 @@ const path_1 = __importDefault(require("path"));
 const framework_manager_1 = require("./framework-manager");
 const workspace_manager_1 = require("./workspace-manager");
 const artifact_registry_1 = require("./artifact-registry");
-/** The shared, statically-linked subtrees of a providerDir. `agent-memory` is
- *  intentionally absent — it is real per-workspace state, never compared/linked. */
+const providers_1 = require("./providers");
+/** Whole-directory shared subtrees for the legacy providers. `agent-memory` is
+ * intentionally absent — it is real per-workspace state, never compared/linked. */
 const SHARED_SUBTREES = ['commands', 'agents', 'skills', 'rules'];
+/**
+ * Roots that core assembles as whole-directory framework links.
+ *
+ * Kimi is intentionally special: `.kimi-code/skills` remains a REAL directory
+ * and core links only the framework-owned children within it. That merged layout
+ * is what lets Kimi keep OpenSpec skills and desktop-authored `custom-*` roles
+ * as direct children. Treating the root as a copied shared subtree would back it up,
+ * expect a root symlink that core will never create, then revert every launch.
+ */
+function sharedSubtreesFor(provider) {
+    return provider === 'kimi' ? ['rules'] : SHARED_SUBTREES;
+}
 /** Map a provider id to its providerDir name (mirrors core). */
 function providerDirFor(provider) {
-    if (provider === 'codex')
-        return '.codex';
-    if (provider === 'gemini')
-        return '.gemini';
-    return '.claude';
+    try {
+        return (0, providers_1.getAdapter)(provider).projectDirName;
+    }
+    catch {
+        return '.claude';
+    }
 }
 /** sha256 of a file's bytes, or null when unreadable. */
 function hashFile(p) {
@@ -83,9 +97,9 @@ function isCustomAgent(rel) {
  * from (or is missing in) `current` — excluding `custom-*` agents — counts as
  * local divergence.
  */
-function compareSharedSubtrees(workspaceProviderDir, fwProviderDir) {
+function compareSharedSubtrees(workspaceProviderDir, fwProviderDir, subtrees) {
     let hadSharedSubtree = false;
-    for (const sub of SHARED_SUBTREES) {
+    for (const sub of subtrees) {
         const copyDir = path_1.default.join(workspaceProviderDir, sub);
         if (!isRealDir(copyDir))
             continue;
@@ -154,15 +168,16 @@ function runMigration(slug, projectPath, provider, fwCurrent, fm, opts) {
     const ws = (0, workspace_manager_1.workspacePathFor)(slug, opts.home);
     const wsProviderDir = path_1.default.join(ws, providerDir);
     const fwProviderDir = path_1.default.join(fwCurrent, providerDir);
+    const sharedSubtrees = sharedSubtreesFor(provider);
     // Idempotent: if any shared subtree is already a symlink into `current`, the
     // workspace is migrated — no-op.
-    for (const sub of SHARED_SUBTREES) {
+    for (const sub of sharedSubtrees) {
         if (linkResolvesIntoFramework(path_1.default.join(wsProviderDir, sub), fwCurrent)) {
             return { outcome: 'already-symlinked' };
         }
     }
     // Detect the migratable real-copy layout + the local-divergence guard.
-    const cmp = compareSharedSubtrees(wsProviderDir, fwProviderDir);
+    const cmp = compareSharedSubtrees(wsProviderDir, fwProviderDir, sharedSubtrees);
     if (!cmp.hadSharedSubtree) {
         return { outcome: 'not-a-copy' };
     }
@@ -172,7 +187,7 @@ function runMigration(slug, projectPath, provider, fwCurrent, fm, opts) {
     }
     // ── Backup the copied shared subtrees (never delete). ──────────────────────
     const backedUp = [];
-    for (const sub of SHARED_SUBTREES) {
+    for (const sub of sharedSubtrees) {
         const live = path_1.default.join(wsProviderDir, sub);
         if (!isRealDir(live))
             continue;

package/server/dist/install-config-path.js

@@ -48,7 +48,7 @@ function isSafeSlug(slug) {
         !slug.includes('..'));
 }
 /** True when a provider id is a safe filename segment (registry ids are
- *  lowercase-kebab — `claude` / `codex` / `gemini`). */
+ *  lowercase-kebab — `claude` / `codex` / `gemini` / `kimi`). */
 function isSafeProvider(provider) {
     return typeof provider === 'string' && /^[a-z0-9][a-z0-9-]*$/.test(provider);
 }

package/server/dist/interactive-job-session.js

@@ -39,6 +39,7 @@ const explore_stdin_session_1 = require("./explore-stdin-session");
 const result_event_1 = require("./result-event");
 const db_1 = require("./db");
 const stream_display_1 = require("./util/stream-display");
+const runtime_1 = require("./providers/runtime");
 /** Claude's stream-json result frames do not carry a turn id. Hash a canonical
  * representation of the real frame instead: an exact/semantic retransmission
  * remains identifiable even after the next stdin turn has been armed, while a
@@ -443,10 +444,10 @@ class InteractiveJobSession {
             if (this._acceptedResultSignatures.has(signature))
                 return;
         }
-        const adapterEv = this._adapter.parseStreamLine(line);
-        if (adapterEv) {
-            this._turnEvents.push(adapterEv);
-            if (!this._sawModelWork && isModelWorkEvent(adapterEv))
+        const adapterEvents = (0, runtime_1.parseStreamEvents)(this._adapter, line);
+        for (const adapterEvent of adapterEvents) {
+            this._turnEvents.push(adapterEvent);
+            if (!this._sawModelWork && isModelWorkEvent(adapterEvent))
                 this._sawModelWork = true;
         }
         if (parsed) {
@@ -476,8 +477,9 @@ class InteractiveJobSession {
         }
         else {
             this._persistLog('stdout', line);
-            if (adapterEv?.kind === 'text-delta') {
-                this._emitLog('stdout', adapterEv.text);
+            const textEvent = adapterEvents.find((event) => event.kind === 'text-delta');
+            if (textEvent?.kind === 'text-delta') {
+                this._emitLog('stdout', textEvent.text);
             }
             else {
                 this._emitLog('stdout', line);

package/server/dist/loop-command-catalog.js

@@ -8,8 +8,9 @@
  *    claude `/specrails:<name>`, codex `$<name>` (skill), gemini `/specrails:<name>`.
  *    Mirrors QueueManager's rail invocation (`/specrails:implement #1 #2 --yes`).
  *  - `template`: a provider-invariant curated prompt (no core coupling).
- *  - `native`: a raw autonomous Freestyle command — claude-only, NOT a slash
- *    command; it expands to a self-contained autonomous prompt.
+ *  - `native`: a raw autonomous Freestyle command — gated by the provider's
+ *    Freestyle capability, NOT a slash command; it expands to a self-contained
+ *    autonomous prompt.
  *
  * Each command declares its TICKET SCOPE:
  *  - `all`        → one run over ALL the rail's tickets (`#1 #2 #3`). implement, batch.
@@ -24,6 +25,8 @@ exports.getLoopCommand = getLoopCommand;
 exports.expandCommands = expandCommands;
 exports.dominantTicketScope = dominantTicketScope;
 exports.referencesClaudeOnlyCommand = referencesClaudeOnlyCommand;
+exports.referencesUnsupportedProviderCommand = referencesUnsupportedProviderCommand;
+const registry_1 = require("./providers/registry");
 /** The autonomous prompt a `native` command (Freestyle) expands to for the
  *  LoopRunManager path. Factory Freestyle loops route to QueueManager's real
  *  `_buildFreestylePrompt` instead (phase A); this is the custom-loop fallback. */
@@ -70,9 +73,9 @@ exports.LOOP_COMMANDS = [
     {
         name: 'freestyle',
         label: 'Freestyle',
-        description: 'Free-form autonomous per-ticket implementation — Claude receives the spec as a prompt and works it end-to-end with no pipeline. Claude only. Internal token: {{cmd:freestyle}}.',
+        description: 'Free-form autonomous per-ticket implementation — the selected capable provider receives the spec as a prompt and works it end-to-end with no pipeline. Internal token: {{cmd:freestyle}}.',
         native: true,
-        claudeOnly: true,
+        requiredCapability: 'freestyle',
         ticketScope: 'per-ticket',
     },
     {
@@ -134,19 +137,19 @@ exports.LOOP_COMMANDS = [
     {
         name: 'opsx:ff', label: 'opsx:ff', ticketScope: 'per-ticket',
         description: 'OpenSpec fast-forward: create (or continue) a change and generate all its artifacts (proposal, specs, design, tasks). Native /opsx:ff (claude/gemini) or $opsx:ff (codex).',
-        providerNative: { claude: '/opsx:ff', gemini: '/opsx:ff', codex: '$opsx:ff' },
+        providerNative: { claude: '/opsx:ff', gemini: '/opsx:ff', codex: '$opsx:ff', kimi: '/skill:openspec-ff-change' },
         template: 'Create or continue an OpenSpec change for the work described next and generate all of its artifacts (proposal, specs, design, and tasks) so it is ready to implement.',
     },
     {
         name: 'opsx:apply', label: 'opsx:apply', ticketScope: 'per-ticket',
         description: 'OpenSpec apply: implement all pending tasks of the active change. Native /opsx:apply (claude/gemini) or $opsx:apply (codex).',
-        providerNative: { claude: '/opsx:apply', gemini: '/opsx:apply', codex: '$opsx:apply' },
+        providerNative: { claude: '/opsx:apply', gemini: '/opsx:apply', codex: '$opsx:apply', kimi: '/skill:openspec-apply-change' },
         template: 'Implement every pending task of the active OpenSpec change, editing the code as needed and marking each task complete as you finish it.',
     },
     {
         name: 'opsx:verify', label: 'opsx:verify', ticketScope: 'per-ticket',
         description: "OpenSpec verify: check the active change's implementation against its specs/tasks; ends with VERIFICATION: PASS|FAIL. Native /opsx:verify (claude/gemini) or $opsx:verify (codex).",
-        providerNative: { claude: '/opsx:verify', gemini: '/opsx:verify', codex: '$opsx:verify' },
+        providerNative: { claude: '/opsx:verify', gemini: '/opsx:verify', codex: '$opsx:verify', kimi: '/skill:openspec-verify-change' },
         template: 'Verify the active OpenSpec change: inspect the REAL implementation against its specs, design, and tasks. Finish with exactly `VERIFICATION: PASS` when nothing required is missing, or `VERIFICATION: FAIL — <what is still missing>` otherwise.',
     },
     // ── Merge-resolver (parallel rails: integrate worktree branches back) ───────
@@ -225,7 +228,11 @@ const CMD_TOKEN_RE = /\{\{\s*cmd:([\w:-]+)\s*\}\}/g;
  *  identical in shape to the rail's `/specrails:implement #1 #2 --yes`. Codex has
  *  no `/namespace:cmd` parser, so it invokes the equivalent `$<name>` skill. */
 function nativeInvocation(coreCommand, provider, ids) {
-    const head = provider === 'codex' ? `$${coreCommand}` : `/specrails:${coreCommand}`;
+    const head = provider === 'codex'
+        ? `$${coreCommand}`
+        : provider === 'kimi'
+            ? `/skill:specrails-${coreCommand}`
+            : `/specrails:${coreCommand}`;
     const tickets = ids.length ? ' ' + ids.map((id) => `#${id}`).join(' ') : '';
     return `${head}${tickets} --yes`;
 }
@@ -267,10 +274,20 @@ function dominantTicketScope(text) {
     }
     return sawPerTicket ? 'per-ticket' : 'per-ticket';
 }
-/** True if a prompt references any claude-only command (e.g. Freestyle's canonical token). */
+/** Legacy helper retained for API compatibility. */
 function referencesClaudeOnlyCommand(text) {
     for (const m of text.matchAll(CMD_TOKEN_RE)) {
-        if (COMMANDS_BY_NAME.get(m[1])?.claudeOnly)
+        if (COMMANDS_BY_NAME.get(m[1])?.requiredCapability === 'freestyle')
+            return true;
+    }
+    return false;
+}
+/** True when a prompt uses a command the selected provider cannot execute. */
+function referencesUnsupportedProviderCommand(text, provider) {
+    const capabilities = (0, registry_1.getAdapter)(provider).capabilities;
+    for (const m of text.matchAll(CMD_TOKEN_RE)) {
+        const required = COMMANDS_BY_NAME.get(m[1])?.requiredCapability;
+        if (required && capabilities[required] !== true)
             return true;
     }
     return false;

package/server/dist/loop-executors.js

@@ -23,6 +23,7 @@ const result_event_1 = require("./result-event");
 const loop_decider_1 = require("./loop-decider");
 const rail_isolation_1 = require("./rail-isolation");
 const feature_flags_1 = require("./feature-flags");
+const runtime_1 = require("./providers/runtime");
 // Per-step wall-clock caps so a single hung step can't block the engine's
 // overall deadline check (which only runs between nodes).
 const AI_STEP_TIMEOUT_MS = 15 * 60_000;
@@ -109,13 +110,10 @@ function aiStepEnv(env, repoDir) {
  *    no-op under danger-full-access on iteration 1.
  */
 function aiStepExtraArgs(adapter, cwd, repoDir) {
-    return !repoDir
-        ? undefined
-        : adapter.id === 'claude'
-            ? ['--add-dir', repoDir]
-            : adapter.id === 'codex'
-                ? ['-c', `sandbox_workspace_write.writable_roots=[${JSON.stringify(repoDir)}, ${JSON.stringify(cwd)}]`]
-                : undefined;
+    if (!repoDir)
+        return undefined;
+    const args = (0, runtime_1.buildProviderRepoAccessArgs)(adapter, [repoDir, ...(adapter.id === 'codex' ? [cwd] : [])]);
+    return args.length > 0 ? args : undefined;
 }
 function createLoopExecutors(opts = {}) {
     const resolveEnv = () => typeof opts.env === 'function' ? opts.env() : opts.env ?? process.env;
@@ -150,6 +148,14 @@ function createLoopExecutors(opts = {}) {
             // agent self-heal on Windows.
             const stepEnv = aiStepEnv(resolveEnv(), repoDir);
             const extraArgs = aiStepExtraArgs(adapter, cwd, repoDir);
+            const effectivePrompt = (0, runtime_1.formatProviderCommand)(adapter, prompt, cwd, sessionId ?? undefined);
+            const buildOpts = {
+                prompt: effectivePrompt,
+                model,
+                sessionId: sessionId ?? undefined,
+                reasoning_effort: effort,
+                extraArgs,
+            };
             if (repoDir) {
                 try {
                     (0, workspace_manager_1.ensureFrameworkAgents)(cwd, adapter.projectDirName);
@@ -169,12 +175,13 @@ function createLoopExecutors(opts = {}) {
             // surface the REAL reason (e.g. "You've hit your usage limit") instead of
             // the `stderrTail`, which often holds only an informational line.
             let errorText;
+            const wallStartedAt = Date.now();
             const res = await (0, spawn_lifecycle_1.runAiCliInvocation)({
                 adapter,
                 action,
-                buildOpts: { prompt, model, sessionId: sessionId ?? undefined, reasoning_effort: effort, extraArgs },
+                buildOpts,
                 cwd,
-                env: stepEnv,
+                env: (0, runtime_1.buildProviderEnv)(adapter, buildOpts, stepEnv),
                 timeoutMs: aiStepTimeoutMs ?? AI_STEP_TIMEOUT_MS,
                 onSpawn,
                 // Two complementary streams, mirroring QueueManager's contract:
@@ -194,7 +201,10 @@ function createLoopExecutors(opts = {}) {
                         errorText = ev.message;
                 },
             });
-            const failed = res.spawnFailed || res.timedOut || (res.code != null && res.code !== 0);
+            const failed = res.spawnFailed ||
+                res.timedOut ||
+                (res.code != null && res.code !== 0) ||
+                errorText !== undefined;
             if (res.spawnFailed) {
                 errorText = errorText ?? `failed to spawn "${adapter.binary}" (on PATH?)`;
                 const msg = `AI step: ${errorText}`;
@@ -219,11 +229,24 @@ function createLoopExecutors(opts = {}) {
                 console.error(`[loop] ${msg}`);
                 onLine?.(msg, 'stderr');
             }
-            const { result, estimated } = (0, result_event_1.finaliseInvocationResult)(adapter, res.events, { fallbackModel: model });
-            const tokensIn = result.tokens_in ?? 0;
-            const tokensOut = result.tokens_out ?? 0;
-            const tokensCacheRead = result.tokens_cache_read ?? 0;
-            const tokensCacheCreate = result.tokens_cache_create ?? 0;
+            else if (errorText) {
+                // A normalized provider error is terminal even if an upstream CLI
+                // anomalously reports a clean process exit.
+                const msg = `AI step: ${adapter.binary} reported an error — ${errorText}`;
+                console.error(`[loop] ${msg}`);
+                onLine?.(msg, 'stderr');
+            }
+            const { result, estimated } = (0, result_event_1.finaliseInvocationResult)(adapter, res.events, {
+                fallbackModel: model,
+                durationMs: Math.max(0, Date.now() - wallStartedAt),
+            });
+            const tokensIn = result.tokens_in;
+            const tokensOut = result.tokens_out;
+            const tokensCacheRead = result.tokens_cache_read;
+            const tokensCacheCreate = result.tokens_cache_create;
+            const tokens = tokensIn === undefined && tokensOut === undefined
+                ? undefined
+                : (tokensIn ?? 0) + (tokensOut ?? 0);
             return {
                 text,
                 sessionId: res.sessionId ?? undefined,
@@ -234,7 +257,7 @@ function createLoopExecutors(opts = {}) {
                 // cache tokens or the claude loop-job token display would inflate. The
                 // full cache breakdown is persisted to the ai_invocations row via the
                 // structured tokensCacheRead/tokensCacheCreate fields below.
-                tokens: tokensIn + tokensOut,
+                tokens,
                 tokensIn,
                 tokensOut,
                 tokensCacheRead,
@@ -280,7 +303,7 @@ function createLoopExecutors(opts = {}) {
                 (0, claude_trust_1.ensureClaudeTrusted)(adapter.id, [cwd, repoDir]);
             }
             catch { /* best-effort */ }
-            const args = adapter.buildArgs('chat-stream', {
+            const buildOpts = {
                 // chat-stream feeds the prompt over stdin per-turn, so the argv `prompt`
                 // is unused — pass empty to satisfy the shared SpawnOptions shape.
                 prompt: '',
@@ -291,10 +314,11 @@ function createLoopExecutors(opts = {}) {
                 sessionId: sessionId ?? undefined,
                 reasoning_effort: effort,
                 extraArgs,
-            });
+            };
+            const args = adapter.buildArgs('chat-stream', buildOpts);
             return {
                 adapter,
-                spec: { binary: adapter.binary, args, cwd, env: stepEnv },
+                spec: { binary: adapter.binary, args, cwd, env: (0, runtime_1.buildProviderEnv)(adapter, buildOpts, stepEnv) },
                 // The loop's ai-step timeout bounds the WHOLE step, interactive included.
                 stepTimeoutMs: aiStepTimeoutMs ?? AI_STEP_TIMEOUT_MS,
             };
@@ -309,12 +333,14 @@ function createLoopExecutors(opts = {}) {
             const decEnv = repoDir ? { ...baseEnv, SPECRAILS_REPO_DIR: repoDir } : baseEnv;
             // spec-gen is a one-shot, system-prompted invocation (workspace-write on
             // codex, not full-access) — appropriate for a read-only judgment.
+            const buildOpts = { prompt: userPrompt, systemPrompt, model, maxTurns: 1, reasoning_effort: effort, toolPolicy: 'read-only' };
+            const wallStartedAt = Date.now();
             const res = await (0, spawn_lifecycle_1.runAiCliInvocation)({
                 adapter,
                 action: 'spec-gen',
-                buildOpts: { prompt: userPrompt, systemPrompt, model, maxTurns: 1, reasoning_effort: effort },
+                buildOpts,
                 cwd,
-                env: decEnv,
+                env: (0, runtime_1.buildProviderEnv)(adapter, buildOpts, decEnv),
                 timeoutMs: DECIDER_TIMEOUT_MS,
                 onSpawn,
                 onStdoutLine: onRawLine,
@@ -322,11 +348,17 @@ function createLoopExecutors(opts = {}) {
                     text += ev.text; },
             });
             const decision = (0, loop_decider_1.parseDeciderDecision)(text);
-            const { result, estimated } = (0, result_event_1.finaliseInvocationResult)(adapter, res.events, { fallbackModel: model });
-            const tokensIn = result.tokens_in ?? 0;
-            const tokensOut = result.tokens_out ?? 0;
-            const tokensCacheRead = result.tokens_cache_read ?? 0;
-            const tokensCacheCreate = result.tokens_cache_create ?? 0;
+            const { result, estimated } = (0, result_event_1.finaliseInvocationResult)(adapter, res.events, {
+                fallbackModel: model,
+                durationMs: Math.max(0, Date.now() - wallStartedAt),
+            });
+            const tokensIn = result.tokens_in;
+            const tokensOut = result.tokens_out;
+            const tokensCacheRead = result.tokens_cache_read;
+            const tokensCacheCreate = result.tokens_cache_create;
+            const tokens = tokensIn === undefined && tokensOut === undefined
+                ? undefined
+                : (tokensIn ?? 0) + (tokensOut ?? 0);
             return {
                 ...decision,
                 cost: result.total_cost_usd,
@@ -336,7 +368,7 @@ function createLoopExecutors(opts = {}) {
                 // cache tokens or the claude loop-job token display would inflate. The
                 // full cache breakdown is persisted to the ai_invocations row via the
                 // structured tokensCacheRead/tokensCacheCreate fields below.
-                tokens: tokensIn + tokensOut,
+                tokens,
                 tokensIn,
                 tokensOut,
                 tokensCacheRead,

package/server/dist/loop-factory.js

@@ -42,9 +42,9 @@ exports.FACTORY_LOOPS = [
         // with full freedom — no pipeline, it works like a regular coding agent.
         // The id/mode strings are the canonical rail contract.
         name: 'Freestyle',
-        description: 'Hands the spec straight to the model with full freedom — no pipeline, it works like a regular coding agent, then verify + refine until green. Claude only.',
+        description: 'Hands the spec straight to the model with full freedom — no pipeline, it works like a regular coding agent, then verify + refine until green.',
         mode: 'freestyle',
-        claudeOnly: true,
+        requiredCapability: 'freestyle',
         graph: (0, loop_templates_1.fixLoopGraph)(['{{cmd:freestyle}}'], GREEN_GOAL, FACTORY_MAX_ITERATIONS, FACTORY_LOOP_TIMEOUT_MIN, FACTORY_AI_STEP_TIMEOUT_MIN),
     },
     SDD_QUICK_OPENSPEC_FACTORY,