@dfosco/storyboard-core 4.2.0-beta.21 → 4.2.0-beta.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-core",
-  "version": "4.2.0-beta.21",
+  "version": "4.2.0-beta.23",
   "type": "module",
   "license": "MIT",
   "bin": {

package/src/cli/setup.js

@@ -5,7 +5,7 @@
  */
 
 import * as p from '@clack/prompts'
-import { existsSync, writeFileSync, readFileSync, mkdirSync } from 'fs'
+import { existsSync, writeFileSync, readFileSync, mkdirSync, readdirSync, symlinkSync } from 'fs'
 import path from 'path'
 import { execSync } from 'child_process'
 import { generateCaddyfile, isCaddyInstalled, isCaddyRunning, startCaddy, reloadCaddy } from './proxy.js'
@@ -256,6 +256,34 @@ if (isInstalled('code')) {
       }
     } catch { /* ignore */ }
   }
+
+  // Create symlinks in each CLI's expected agent directory.
+  // Source of truth: .agents/*.agent.md
+  // Copilot CLI reads .github/agents/*.md
+  // Claude Code reads .claude/agents/*.md
+  // Codex CLI uses .codex/config.toml (no agent files needed)
+  try {
+    const agentFiles = readdirSync(agentsDir).filter(f => f.endsWith('.agent.md'))
+    const targets = [
+      { dir: path.join('.github', 'agents'), label: 'Copilot CLI' },
+      { dir: path.join('.claude', 'agents'), label: 'Claude Code' },
+    ]
+    for (const { dir, label } of targets) {
+      try { mkdirSync(dir, { recursive: true }) } catch { /* ignore */ }
+      let linked = 0
+      for (const file of agentFiles) {
+        const linkName = file.replace('.agent.md', '.md')
+        const linkPath = path.join(dir, linkName)
+        const target = path.relative(dir, path.join(agentsDir, file))
+        if (!existsSync(linkPath)) {
+          try { symlinkSync(target, linkPath); linked++ } catch { /* ignore */ }
+        }
+      }
+      if (linked > 0) {
+        p.log.success(`${label} agent symlinks created (${dir}/)`)
+      }
+    }
+  } catch { /* ignore */ }
 }
 
 // 8. Proxy

package/src/cli/terminal-welcome.js

@@ -24,6 +24,27 @@ import { dim, cyan, bold } from './intro.js'
 import { takePendingMessages } from '../canvas/terminal-config.js'
 
 const blue = (s) => `\x1b[34m${s}\x1b[0m`
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`
+
+/**
+ * Drain any pending bytes from stdin to prevent stale mouse escape sequences
+ * (or other buffered input) from being consumed by Clack prompts.
+ * This is critical after tmux mouse mode was on — mouse events from the
+ * browser widget are sent as escape sequences to stdin.
+ */
+function drainStdin() {
+  if (!process.stdin.readable) return
+  const wasPaused = process.stdin.isPaused?.()
+  try {
+    process.stdin.setRawMode?.(true)
+    process.stdin.resume()
+    // Read and discard all buffered data
+    while (process.stdin.read() !== null) { /* discard */ }
+  } catch { /* best effort */ }
+  if (wasPaused) {
+    try { process.stdin.pause() } catch {}
+  }
+}
 
 // Prepend .storyboard/terminals/bin/ to PATH so `start`, `copilot`, etc.
 // are available in child shells. Done once at startup; child shells inherit it.
@@ -32,6 +53,19 @@ if (existsSync(binDir) && !process.env.PATH?.includes(binDir)) {
   process.env.PATH = `${binDir}:${process.env.PATH || ''}`
 }
 
+/**
+ * Return a copy of process.env with the .storyboard/terminals/bin/ dir
+ * stripped from PATH. Used when spawning agent commands so the real binary
+ * is found instead of the wrapper scripts that route back through
+ * terminal-welcome (which would cause infinite recursion).
+ */
+function agentEnv() {
+  const cleanPath = (process.env.PATH || '').split(':')
+    .filter(p => !p.endsWith('.storyboard/terminals/bin'))
+    .join(':')
+  return { ...process.env, PATH: cleanPath }
+}
+
 /**
  * Read agents config from storyboard.config.json.
  * Returns an array of { id, label, startupCommand, resumeCommand } entries.
@@ -189,14 +223,21 @@ async function launchAgent(agent, { isInitialStartup = false } = {}) {
   p.outro(dim(`Starting ${agent.label}...`))
   setMouse(true)
 
+  let exitCode = null
+  const startTime = Date.now()
+
   try {
     const shell = process.env.SHELL || '/bin/zsh'
-    const child = spawn(shell, ['-lc', agent.startupCommand], { stdio: 'inherit' })
+    const child = spawn(shell, ['-lc', agent.startupCommand], {
+      stdio: 'inherit',
+      env: agentEnv(),
+    })
 
     // Context injection — inject identity, postStartup, and pending messages
     // after the agent reaches readiness. Skip on initial --startup since
     // terminal-server.js handles that path independently.
     let pollInterval = null
+    let readinessTimeout = null
     const tmuxName = !isInitialStartup ? getTmuxName() : null
     const widgetId = process.env.STORYBOARD_WIDGET_ID
 
@@ -234,7 +275,7 @@ async function launchAgent(agent, { isInitialStartup = false } = {}) {
           } catch {}
         }, 2000)
         // Timeout after 30s — don't wait forever
-        setTimeout(() => {
+        readinessTimeout = setTimeout(() => {
           if (!contextSent) {
             contextSent = true
             if (pollInterval) { clearInterval(pollInterval); pollInterval = null }
@@ -251,30 +292,45 @@ async function launchAgent(agent, { isInitialStartup = false } = {}) {
       }
     }
 
-    await new Promise((resolve) => {
-      child.on('close', () => {
+    exitCode = await new Promise((resolve) => {
+      child.on('close', (code) => {
         if (pollInterval) {
           if (typeof pollInterval.clear === 'function') pollInterval.clear()
           else clearInterval(pollInterval)
         }
-        resolve()
+        if (readinessTimeout) clearTimeout(readinessTimeout)
+        resolve(code)
       })
       child.on('error', () => {
         if (pollInterval) {
           if (typeof pollInterval.clear === 'function') pollInterval.clear()
           else clearInterval(pollInterval)
         }
-        resolve()
+        if (readinessTimeout) clearTimeout(readinessTimeout)
+        resolve(1)
       })
     })
   } catch {
     p.log.error(`Failed to start ${agent.label}. Is it installed?`)
     await new Promise(r => setTimeout(r, 2000))
+    exitCode = 1
+  } finally {
+    // Always disable mouse and drain stdin before returning to the welcome
+    // loop. Without this, tmux mouse escape sequences from the browser widget
+    // accumulate in stdin while the agent runs, and Clack's p.select() reads
+    // them as keystrokes — auto-selecting menu options in a tight loop.
+    setMouse(false)
+    await new Promise(r => setTimeout(r, 50))
+    drainStdin()
   }
+
+  const durationMs = Date.now() - startTime
+  return { exitCode, durationMs }
 }
 
 async function welcomeLoop() {
   let firstIteration = true
+  const MAX_STARTUP_RETRIES = 2
 
   while (true) {
     // On first iteration with --startup, auto-launch the command
@@ -294,14 +350,35 @@ async function welcomeLoop() {
         startupCmd.startsWith(a.startupCommand?.split(' ')[0])
       )
       const agent = matchedAgent || { label: startupCmd.split(/\s+/)[0], startupCommand: startupCmd }
-      await launchAgent(agent, { isInitialStartup: true })
-      resetTerminal()
-      continue
+
+      let succeeded = false
+      for (let attempt = 0; attempt < MAX_STARTUP_RETRIES; attempt++) {
+        const result = await launchAgent(agent, { isInitialStartup: true })
+        resetTerminal()
+
+        // Normal exit (user quit the agent) — proceed to welcome menu
+        if (result.exitCode === 0 || result.exitCode === null) { succeeded = true; break }
+
+        // Non-zero exit — agent crashed or failed to start
+        const isLastAttempt = attempt === MAX_STARTUP_RETRIES - 1
+        if (isLastAttempt) {
+          p.log.warn(yellow(`${agent.label} failed to start (exit code ${result.exitCode}).`))
+          p.log.info(dim('Falling back to the welcome menu. You can retry from there.'))
+          await new Promise(r => setTimeout(r, 2000))
+        } else {
+          p.log.warn(yellow(`${agent.label} exited unexpectedly (exit code ${result.exitCode}). Retrying...`))
+          await new Promise(r => setTimeout(r, 3000))
+        }
+      }
+
+      if (succeeded) continue
+      // Fall through to the interactive welcome menu
     }
     firstIteration = false
 
     resetTerminal()
     setMouse(false)
+    drainStdin()
     console.clear()
     p.intro(`${bold('storyboard terminal')}`)
 
@@ -310,6 +387,7 @@ async function welcomeLoop() {
       ? { value: 'agents', label: '✦ Start a new agent session' }
       : { value: 'copilot', label: `✦ Start a new ${agents[0]?.label || 'Copilot'} session` }
 
+    drainStdin()
     const action = await p.select({
       message: 'How would you like to start?',
       options: [
@@ -326,6 +404,7 @@ async function welcomeLoop() {
 
     if (action === 'agents') {
       // Multi-agent sub-select
+      drainStdin()
       const agentChoice = await p.select({
         message: 'Which agent?',
         options: agents.map(a => ({
@@ -378,6 +457,7 @@ async function welcomeLoop() {
         { value: 'terminal', label: '⊞ Terminal sessions' },
       ]
 
+      drainStdin()
       const sessionChoice = await p.select({
         message: 'Browse sessions',
         options: sessionOptions,
@@ -409,7 +489,10 @@ async function welcomeLoop() {
           setMouse(true)
           try {
             const shell = process.env.SHELL || '/bin/zsh'
-            const child = spawn(shell, ['-lc', agent.resumeCommand], { stdio: 'inherit' })
+            const child = spawn(shell, ['-lc', agent.resumeCommand], {
+              stdio: 'inherit',
+              env: agentEnv(),
+            })
             await new Promise((resolve) => {
               child.on('close', resolve)
               child.on('error', resolve)

package/src/tools/handlers/canvasAgents.js

@@ -7,7 +7,7 @@
 export const id = 'canvas-agents'
 
 export async function guard(ctx) {
-  const { getConfig } = await import('../../configStore.js')
+  const { getConfig } = await import('@dfosco/storyboard-core')
   const canvasConfig = getConfig('canvas')
   const agents = canvasConfig?.agents
   return agents && typeof agents === 'object' && Object.keys(agents).length > 0

package/src/tools/handlers/canvasToolbar.js

@@ -5,7 +5,7 @@
  * handler. The component() export returns the component matching the tool's
  * render type, resolved at load time via the toolConfig passed to component().
  */
-import { getCanvasZoom } from '../../canvasConfig.js'
+import { getCanvasZoom } from '@dfosco/storyboard-core'
 
 export const id = 'canvas-toolbar'
 

package/src/tools/handlers/devtools.js

@@ -19,11 +19,11 @@ export async function handler(ctx) {
   let commentsAuth = null
   let prodMode = null
   let ff = null
-  try { loader = await import('../../loader.js') } catch { /* optional */ }
+  try { loader = await import('@dfosco/storyboard-core') } catch { /* optional */ }
   try { hm = await import('../../hideMode.js') } catch { /* optional */ }
   try { commentsAuth = await import('../../comments/auth.js') } catch { /* optional */ }
   try { prodMode = await import('../../prodMode.js') } catch { /* optional */ }
-  try { ff = await import('../../featureFlags.js') } catch { /* optional */ }
+  try { ff = await import('@dfosco/storyboard-core') } catch { /* optional */ }
 
   return {
     getChildren: () => {

package/src/tools/handlers/featureFlags.js

@@ -6,7 +6,7 @@
 export const id = 'feature-flags'
 
 export async function handler() {
-  const ff = await import('../../featureFlags.js')
+  const ff = await import('@dfosco/storyboard-core')
 
   return {
     getChildren: () =>

package/src/tools/handlers/flows.js

@@ -7,8 +7,8 @@
 export const id = 'flows'
 
 export async function handler(ctx) {
-  const loader = await import('../../loader.js')
-  const vf = await import('../../viewfinder.js')
+  const loader = await import('@dfosco/storyboard-core')
+  const vf = loader
   const { basePath = '/' } = ctx
 
   return {