spectoflow 0.20.0 → 0.20.1

package/README.md

@@ -21,10 +21,12 @@ You speak in plain language; the framework classifies your intent and runs the r
 ceremonial command to start.
 
 **Works with whichever coding agent you have** — Claude Code, Codex, Cursor, Gemini CLI, OpenCode,
-Kiro CLI, and Antigravity are auto-detected at `init`. The dashboard's topbar always shows the
-**active agent**, front and center, with a switcher: pick another and it's verified as genuinely
+Kiro CLI, Antigravity, and Kimi CLI are auto-detected at `init`. The dashboard's topbar always shows
+the **active agent**, front and center, with a switcher: pick another and it's verified as genuinely
 installed before activating (a red **"No agent found"** if none is) — it never silently activates
-something that isn't there.
+something that isn't there. (Kimi CLI doesn't yet ship a non-interactive run mode, so spectoflow can
+set it as active but won't try to spawn it — the agent pickers that launch a run grey it out rather
+than hide it.)
 
 ## Install
 

package/lib/adapters.js

@@ -68,11 +68,20 @@ Argument: \`$ARGUMENTS\`
 
 // Priority order = which agent becomes the default when several are detected.
 //
-// Considered and left out (researched, not re-added on a whim): Kimi Code CLI (MoonshotAI/kimi-cli)
-// and DeepSeek Harness (deepseek-ai/deepseek-harness) — as of Sept 2026 neither ships a genuine
-// non-interactive one-shot mode (prompt-as-trailing-arg, stdout, exit) that runner.js's spawn model
-// needs; Kimi is interactive/ACP-only, DeepSeek Harness is a local web-app framework. Revisit if
-// either ships a headless flag — a fabricated runner command would just fail silently for real users.
+// `headless: false` marks an agent spectoflow can DETECT and let you set as active, but never spawn
+// itself — no confirmed non-interactive one-shot mode (prompt as trailing arg → stdout → exit) as of
+// this research pass, so `runner` is null on purpose (a fabricated command would just fail silently
+// for real users). The dashboard still lists it and shows why Run/Orchestrate/Summarize are disabled
+// for it, rather than hiding it — you can drive it yourself in its own terminal meanwhile, and
+// `config.json → runners` is still yours to hand-wire a command into if one ships later.
+//
+// Left out of KNOWN_AGENTS entirely (not even headless:false) — researched, not re-added on a whim:
+// DeepSeek Harness (deepseek-ai/deepseek-harness). It has no single installable binary to detect —
+// it's invoked as `npx @deepseek-ai/dsh <subcommand>`, is explicitly a local WEB-APP framework (not a
+// terminal chat/prompt tool like the others), and ships as an August-2026 "developer preview" whose
+// APIs the project itself says will change. Detecting "is npx present" would not mean deepseek-harness
+// is; it doesn't fit this registry's detection model. Revisit once it (or Kimi) publishes a real
+// one-shot flag, or wire a custom command into config.json → runners by hand in the meantime.
 const REGISTRY = [
   {
     id: 'claude',
@@ -81,44 +90,58 @@ const REGISTRY = [
       { path: '.claude/commands/spectoflow.md', content: SLASH_CMD },
     ],
     runner: 'claude -p --permission-mode acceptEdits',
+    headless: true,
     detect: { bin: 'claude', dirs: ['.claude'] },
   },
   {
     id: 'codex',
     entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }],
     runner: 'codex exec',
+    headless: true,
     detect: { bin: 'codex', dirs: ['.codex'] },
   },
   {
     id: 'cursor',
     entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }],
     runner: 'cursor-agent -p',
+    headless: true,
     detect: { bin: 'cursor-agent', dirs: ['.cursor'] },
   },
   {
     id: 'gemini',
     entries: [{ path: 'GEMINI.md', content: GEMINI_MD }],
     runner: 'gemini -p',
+    headless: true,
     detect: { bin: 'gemini', dirs: ['.gemini'] },
   },
   {
     id: 'opencode',
     entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }],
     runner: 'opencode run --quiet',
+    headless: true,
     detect: { bin: 'opencode', dirs: ['.opencode'] },
   },
   {
     id: 'kiro',
     entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }],
     runner: 'kiro-cli chat --no-interactive --trust-all-tools',
+    headless: true,
     detect: { bin: 'kiro-cli', dirs: ['.kiro'] },
   },
   {
     id: 'antigravity',
     entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }],
     runner: 'agy -p',
+    headless: true,
     detect: { bin: 'agy' },
   },
+  {
+    id: 'kimi',
+    entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }],
+    runner: null, // no confirmed non-interactive one-shot mode — see the note above REGISTRY
+    headless: false,
+    detect: { bin: 'kimi', dirs: [] },
+  },
 ];
 
 const byId = (id) => REGISTRY.find((a) => a.id === id);
@@ -148,7 +171,7 @@ function defaultRunners(agents) {
   const out = {};
   for (const id of agents) {
     const a = byId(id);
-    if (a) out[id] = a.runner;
+    if (a && a.runner) out[id] = a.runner; // headless:false agents (e.g. kimi) have no runner to seed
   }
   return out;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectoflow",
-  "version": "0.20.0",
+  "version": "0.20.1",
   "description": "Agent-agnostic spec-driven development framework + real-time local control plane. Markdown artifacts, intent router, workflow-by-scope.",
   "keywords": [
     "spec-driven-development",

package/templates/dashboard/public/app.js

@@ -95,7 +95,8 @@ function setChat(open){
   $('#chat').setAttribute('aria-hidden', open?'false':'true');
   $('#chatFab').classList.toggle('is-open',open);
   try{ localStorage.setItem('spf-chat', open?'1':'0'); }catch{}
-  if(open) setTimeout(()=>$('#runPrompt').focus(),60);
+  // Land where you can actually type, not wherever the log happened to be scrolled last.
+  if(open) setTimeout(()=>{ scrollChat($('#chatLog')); $('#runPrompt').focus(); },60);
 }
 // doRun/doOrchestrate default to the floating widget's textarea/select; the Chat tab has its own
 // #tabRunPrompt/#tabRunAgent (an id can't be shared by two elements) and passes them explicitly —
@@ -139,11 +140,10 @@ function render(){
   // in renderSettings() below (called on every render tick) and saved via saveSettings().
   // agent select — widget (#runAgent) and Chat tab (#tabRunAgent) each get their own populated
   // <select>, since an id can't be shared by two elements; same option list, same source of truth.
-  const runners=Object.keys((c.runners)||{claude:1});
-  [$('#runAgent'),$('#tabRunAgent')].forEach(sel=>{
-    if(!sel) return;
-    if(sel.options.length!==runners.length){ sel.innerHTML=''; runners.forEach(k=>{ const o=document.createElement('option'); o.value=k; o.textContent=k; sel.append(o); }); if(c.agent) sel.value=c.agent; }
-  });
+  // Shows every known agent (not just ones already in config.json → runners — a freshly-installed
+  // agent works the first time, runner.js falls back to the registry default), disabling any that
+  // isn't genuinely installed or can't run headless (e.g. kimi).
+  [$('#runAgent'),$('#tabRunAgent')].forEach(sel=>fillAgentSelect(sel,P.knownAgents||[],runnableAgentIds(),c.agent));
   const s=SpectoStats.stats(P);
   const meterFill=$('#globalMeterFill');
   if(meterFill) meterFill.style.width=(s.pct||0)+'%';
@@ -717,6 +717,12 @@ function setModeSelects(mode){ [$('#setMode'),$('#topMode')].forEach(s=>{ if(s)
 // the user activate an agent that isn't actually installed — options for a not-installed known agent
 // are present but disabled, and P.installedAgents itself comes from the server testing each agent's
 // real CLI (bin on PATH, or the project's own config dir), not a guess.
+// ids that can actually be SPAWNED right now: installed AND headless-capable (a known agent like
+// kimi can be "installed" and even the active agent, but nothing can run it non-interactively).
+function runnableAgentIds(){
+  const installed=P.installedAgents||[];
+  return (P.knownAgents||[]).filter(a=>a.headless&&installed.includes(a.id)).map(a=>a.id);
+}
 function fillAgentSelect(sel,known,installed,active){
   if(!sel) return;
   const empty=!installed.length;
@@ -936,9 +942,7 @@ function renderCustomize(){
       const form=el('div','cz-form');
       const ta=el('textarea','chat-ta'); ta.placeholder=t('customize.describePh');
       const sel=el('select','chat-agent');
-      const runners=Object.keys((P.config&&P.config.runners)||{claude:1});
-      runners.forEach((k)=>{ const o=document.createElement('option'); o.value=k; o.textContent=k; sel.append(o); });
-      if(P.config&&P.config.agent) sel.value=P.config.agent;
+      fillAgentSelect(sel,P.knownAgents||[],runnableAgentIds(),P.config&&P.config.agent);
       const actions=el('div','cz-form-actions');
       const autoBtn=el('button','btn',t('customize.auto'));
       const goBtn=el('button','btn primary',t('customize.generate'));
@@ -978,6 +982,10 @@ function navigateTab(tabId,push){
   }
   applyActiveTab();
   closeNav(); // a tab pick closes the mobile menu
+  // Landing on Chat: go straight to where you can read the latest and type, not wherever the log
+  // was scrolled to last (only on an actual switch INTO the tab — applyActiveTab() alone runs on
+  // every SSE render tick too, and re-scrolling/re-focusing there would fight the user's typing).
+  if(tabId==='chat') setTimeout(()=>{ scrollChat($('#chatTabLog')); $('#tabRunPrompt').focus(); },60);
 }
 function closeNav(){ document.body.classList.remove('nav-open'); const nt=$('#navToggle'); if(nt) nt.setAttribute('aria-expanded','false'); }
 
@@ -1297,6 +1305,8 @@ $('#chatClose').addEventListener('click',()=> setChat(false));
 try{ if(localStorage.getItem('spf-chat')==='1') setChat(true); }catch{}
 $('#runBtn').addEventListener('click',()=>doRun());
 $('#orchBtn').addEventListener('click',()=>doOrchestrate());
+$('#widgetSummarizeBtn').addEventListener('click',()=>summarizeChat($('#runAgent')));
+$('#widgetClearBtn').addEventListener('click',clearChat);
 $('#runPrompt').addEventListener('keydown',e=>{ if((e.metaKey||e.ctrlKey)&&e.key==='Enter')doRun(); });
 // Chat tab — same doRun/doOrchestrate/approve, its own textarea/select (#tabRunPrompt/#tabRunAgent)
 $('#tabRunBtn').addEventListener('click',()=>doRun($('#tabRunPrompt'),$('#tabRunAgent')));

package/templates/dashboard/public/index.html

@@ -201,16 +201,18 @@
             <h2 class="panel-title" data-i18n="nav.chat">Chat</h2>
             <p class="panel-sub" data-i18n="chat.tabSub">Full conversation with the runner — the same run as the widget, more room to read it.</p>
           </div>
-          <div class="chat-tab-head-actions">
-            <button id="tabSummarizeBtn" class="mini-btn" data-i18n-title="chat.summarizeTitle" data-i18n="action.summarize" title="Condense the recent activity into a summary">Summarize</button>
-            <button id="tabClearBtn" class="mini-btn" data-i18n-title="chat.clearTitle" data-i18n="action.clear" title="Clear the chat log">Clear</button>
-            <select id="tabRunAgent" class="chat-agent" title="Agent"></select>
-          </div>
         </div>
         <div class="chat-tab-log" id="chatTabLog">
           <div class="chat-idle" data-i18n-html="chat.idle">Type a request — the agent runs headless in this project with full memory
             (<code>CLAUDE.md → AGENTS.md</code>) and updates the board live.</div>
         </div>
+        <!-- Toolbar right above the input, not up in the header — this is where you're looking
+             when you reach for Summarize/Clear or switch which agent the next message runs on. -->
+        <div class="chat-tab-toolbar">
+          <button id="tabSummarizeBtn" class="mini-btn" data-i18n-title="chat.summarizeTitle" data-i18n="action.summarize" title="Condense the recent activity into a summary">Summarize</button>
+          <button id="tabClearBtn" class="mini-btn" data-i18n-title="chat.clearTitle" data-i18n="action.clear" title="Clear the chat log">Clear</button>
+          <select id="tabRunAgent" class="chat-agent" title="Agent"></select>
+        </div>
         <div class="chat-tab-input">
           <textarea id="tabRunPrompt" class="chat-ta" data-i18n-ph="chat.inputPlaceholder" placeholder="e.g. Add a login feature with email + password"></textarea>
           <div class="chat-tab-actions">
@@ -306,13 +308,17 @@
         <span class="chat-title" data-i18n="chat.widgetTitle">Run an agent</span>
         <span class="chat-sub" data-i18n="chat.widgetSub">Quick access · full view in the Chat tab</span>
       </div>
-      <select id="runAgent" class="chat-agent" title="Agent"></select>
       <button class="chat-close" id="chatClose" aria-label="Close">×</button>
     </div>
     <div class="chat-log" id="chatLog">
       <div class="chat-idle" data-i18n-html="chat.idle">Type a request — the agent runs headless in this project with full memory
         (<code>CLAUDE.md → AGENTS.md</code>) and updates the board live.</div>
     </div>
+    <div class="chat-toolbar">
+      <button id="widgetSummarizeBtn" class="mini-btn" data-i18n-title="chat.summarizeTitle" data-i18n="action.summarize" title="Condense the recent activity into a summary">Summarize</button>
+      <button id="widgetClearBtn" class="mini-btn" data-i18n-title="chat.clearTitle" data-i18n="action.clear" title="Clear the chat log">Clear</button>
+      <select id="runAgent" class="chat-agent" title="Agent"></select>
+    </div>
     <div class="chat-input">
       <textarea id="runPrompt" class="chat-ta" data-i18n-ph="chat.inputPlaceholder" placeholder="e.g. Add a login feature with email + password"></textarea>
       <button id="runBtn" class="btn primary chat-send" data-i18n="action.send">Send</button>

package/templates/dashboard/public/styles.css

@@ -378,7 +378,8 @@ body { background:var(--bg); color:var(--ink); font-family:var(--sans); font-siz
 .chat-title { font-weight:700; font-size:15px; }
 .chat-sub { font-size:10px; color:var(--faint); text-transform:uppercase; letter-spacing:.04em; }
 .chat-agent { margin-left:auto; flex-shrink:0; font:inherit; font-size:12px; background:var(--surface); color:var(--ink); border:1px solid var(--line); border-radius:7px; padding:5px 8px; }
-.chat-close { width:28px; height:28px; flex-shrink:0; border:1px solid var(--line); background:var(--surface-2); color:var(--muted); border-radius:8px; font-size:17px; cursor:pointer; transition:border-color .15s,color .15s; }
+.chat-toolbar { display:flex; align-items:center; gap:8px; padding:8px 14px; border-top:1px solid var(--line); flex-wrap:wrap; }
+.chat-close { width:28px; height:28px; flex-shrink:0; margin-left:auto; border:1px solid var(--line); background:var(--surface-2); color:var(--muted); border-radius:8px; font-size:17px; cursor:pointer; transition:border-color .15s,color .15s; }
 .chat-close:hover { border-color:color-mix(in srgb,var(--s-blocked) 45%,var(--line)); color:var(--ink); }
 .chat-log { flex:1; overflow-y:auto; padding:16px; display:flex; flex-direction:column; gap:11px; }
 .chat-idle { color:var(--faint); font-style:italic; font-size:12.5px; }
@@ -414,10 +415,10 @@ body { background:var(--bg); color:var(--ink); font-family:var(--sans); font-siz
 .chat-tab-head { display:flex; align-items:flex-start; gap:14px; margin-bottom:14px; }
 .chat-tab-head .panel-title { margin:0; }
 .chat-tab-head .panel-sub { margin:2px 0 0; }
-.chat-tab-head-actions { display:flex; align-items:center; gap:8px; margin-left:auto; flex-shrink:0; flex-wrap:wrap; }
-.chat-tab-head .chat-agent { flex-shrink:0; }
 .chat-tab-log { flex:1; min-height:220px; overflow-y:auto; display:flex; flex-direction:column; gap:12px; background:var(--surface); border:1px solid var(--line); border-radius:var(--radius); padding:20px; box-shadow:var(--shadow); }
-.chat-tab-input { display:flex; gap:10px; margin-top:14px; }
+.chat-tab-toolbar { display:flex; align-items:center; gap:8px; margin-top:10px; flex-wrap:wrap; }
+.chat-tab-toolbar .chat-agent { margin-left:auto; flex-shrink:0; }
+.chat-tab-input { display:flex; gap:10px; margin-top:10px; }
 .chat-tab-input .chat-ta { flex:1; min-height:56px; max-height:180px; }
 .chat-tab-actions { display:flex; flex-direction:column; gap:8px; flex-shrink:0; }
 .chat-tab-wrap .chat-warn { margin:8px 0 0; }

package/templates/dashboard/runner.js

@@ -9,6 +9,18 @@
  */
 const { spawn } = require('child_process');
 const store = require('../lib/store');
+const agentsRegistry = require('../lib/agents-registry');
+
+// The command to run `which`: config.json's own runners map first (an explicit user choice always
+// wins), falling back to the registry's default for a known, headless-capable, genuinely-installed
+// agent — so picking one from a per-message agent list works the first time, before it's ever been
+// the project's "active agent" and had a runner seeded into config.json for it.
+function resolveRunnerCommand(root, cfg, which, opts) {
+  if (cfg.runners && cfg.runners[which]) return cfg.runners[which];
+  const known = agentsRegistry.KNOWN_AGENTS.find((a) => a.id === which);
+  if (known && known.runner && agentsRegistry.isAgentInstalled(which, root, opts)) return known.runner;
+  return null;
+}
 
 function runStart(root, run) {
   const rt = store.readRuntime(root); rt.agents = rt.agents || []; rt.agents.push(run); store.writeRuntime(root, rt);
@@ -50,7 +62,7 @@ function pushAttention(root, text, by) {
 function startRun(root, { prompt, agent, logPrompt = true }, emit) {
   const cfg = store.readConfig(root);
   const which = agent || cfg.agent || 'claude';
-  const cmdStr = cfg.runners && cfg.runners[which];
+  const cmdStr = resolveRunnerCommand(root, cfg, which);
   if (!cmdStr) return { error: `No runner configured for "${which}".` };
   const parts = cmdStr.split(/\s+/).filter(Boolean);
   const runId = 'r' + Date.now().toString(36);
@@ -97,4 +109,4 @@ function startRun(root, { prompt, agent, logPrompt = true }, emit) {
   return { runId, child };
 }
 
-module.exports = { startRun };
+module.exports = { startRun, resolveRunnerCommand };

package/templates/dashboard/server.js

@@ -35,7 +35,7 @@ function project(){
   // Known vs. actually-installed agents — the topbar switcher needs both: the full list to offer,
   // and which ones are real (bin on PATH, or the project already has that agent's config dir) so it
   // can refuse to activate one that isn't there.
-  p.knownAgents = agentsRegistry.KNOWN_AGENTS.map((a) => ({ id: a.id, label: a.label }));
+  p.knownAgents = agentsRegistry.KNOWN_AGENTS.map((a) => ({ id: a.id, label: a.label, headless: a.headless }));
   p.installedAgents = agentsRegistry.installedAgents(ROOT);
   return p;
 }
@@ -62,8 +62,11 @@ function writeConfig(patch){
     }
     cfg.agent = id;
     // Seed a default runner if this agent was never configured (e.g. installed after init/update).
+    // A headless:false agent (e.g. kimi) has no runner to seed — it can still be the active agent,
+    // it just can't be spawned by Run/Orchestrate/Summarize (disabled client-side; runner.js and
+    // summarize.js also refuse server-side either way).
     const known = agentsRegistry.KNOWN_AGENTS.find((a) => a.id === id);
-    if (known) { cfg.runners = cfg.runners || {}; if (!cfg.runners[id]) cfg.runners[id] = known.runner; }
+    if (known && known.runner) { cfg.runners = cfg.runners || {}; if (!cfg.runners[id]) cfg.runners[id] = known.runner; }
   }
   fs.writeFileSync(cp, JSON.stringify(cfg, null, 2) + '\n');
   return cfg;

package/templates/dashboard/summarize.js

@@ -6,6 +6,7 @@
  */
 const { spawn } = require('child_process');
 const store = require('../lib/store');
+const { resolveRunnerCommand } = require('./runner');
 
 const DEFAULT_LIMIT = 40;
 
@@ -20,7 +21,7 @@ function formatLog(messages, limit = DEFAULT_LIMIT) {
 function runSummarize(root, { agent } = {}, emit) {
   const cfg = store.readConfig(root);
   const which = agent || cfg.agent || 'claude';
-  const cmdStr = cfg.runners && cfg.runners[which];
+  const cmdStr = resolveRunnerCommand(root, cfg, which);
   if (!cmdStr) return { error: `No runner configured for "${which}".` };
 
   const rt = store.readRuntime(root);

package/templates/lib/agents-registry.js

@@ -9,14 +9,19 @@
 const fs = require('fs');
 const path = require('path');
 
+// headless:false = detectable and selectable as the active agent, but spectoflow never spawns it
+// itself (no confirmed non-interactive one-shot mode) — Run/Orchestrate/Summarize stay disabled for
+// it client-side; runner/summarize.js also refuse server-side (defense in depth). See the longer
+// rationale above lib/adapters.js's REGISTRY, the richer install-time twin of this list.
 const KNOWN_AGENTS = [
-  { id: 'claude', label: 'Claude Code', bin: 'claude', dirs: ['.claude'], runner: 'claude -p --permission-mode acceptEdits' },
-  { id: 'codex', label: 'Codex', bin: 'codex', dirs: ['.codex'], runner: 'codex exec' },
-  { id: 'cursor', label: 'Cursor', bin: 'cursor-agent', dirs: ['.cursor'], runner: 'cursor-agent -p' },
-  { id: 'gemini', label: 'Gemini CLI', bin: 'gemini', dirs: ['.gemini'], runner: 'gemini -p' },
-  { id: 'opencode', label: 'OpenCode', bin: 'opencode', dirs: ['.opencode'], runner: 'opencode run --quiet' },
-  { id: 'kiro', label: 'Kiro CLI', bin: 'kiro-cli', dirs: ['.kiro'], runner: 'kiro-cli chat --no-interactive --trust-all-tools' },
-  { id: 'antigravity', label: 'Antigravity', bin: 'agy', dirs: [], runner: 'agy -p' },
+  { id: 'claude', label: 'Claude Code', bin: 'claude', dirs: ['.claude'], runner: 'claude -p --permission-mode acceptEdits', headless: true },
+  { id: 'codex', label: 'Codex', bin: 'codex', dirs: ['.codex'], runner: 'codex exec', headless: true },
+  { id: 'cursor', label: 'Cursor', bin: 'cursor-agent', dirs: ['.cursor'], runner: 'cursor-agent -p', headless: true },
+  { id: 'gemini', label: 'Gemini CLI', bin: 'gemini', dirs: ['.gemini'], runner: 'gemini -p', headless: true },
+  { id: 'opencode', label: 'OpenCode', bin: 'opencode', dirs: ['.opencode'], runner: 'opencode run --quiet', headless: true },
+  { id: 'kiro', label: 'Kiro CLI', bin: 'kiro-cli', dirs: ['.kiro'], runner: 'kiro-cli chat --no-interactive --trust-all-tools', headless: true },
+  { id: 'antigravity', label: 'Antigravity', bin: 'agy', dirs: [], runner: 'agy -p', headless: true },
+  { id: 'kimi', label: 'Kimi CLI', bin: 'kimi', dirs: [], runner: null, headless: false },
 ];
 
 // Is `bin` an executable resolvable on PATH? On win32, an extension from PATHEXT is required, so we