@phenx-inc/ctlsurf 0.9.0 → 0.10.0

package/src/main/index.ts

@@ -24,6 +24,7 @@ function log(...args: unknown[]): void {
 import { AgentConfig, getDefaultAgent, getAvailableAgents } from './agents'
 import { getSettingsDir } from './settingsDir'
 import { Orchestrator } from './orchestrator'
+import { AttentionController } from './agentState'
 
 let mainWindow: BrowserWindow | null = null
 
@@ -50,43 +51,47 @@ function getProjectAbbrev(cwdPath: string): string {
   return word.slice(0, 2).toUpperCase()
 }
 
-function createOverlayIcon(text: string): Electron.NativeImage {
-  // Create a 32x32 overlay with text for Windows/Linux
+// Draw a 32x32 filled circle overlay. `red` switches between the project-badge
+// blue and the "awaiting input" red dot.
+function createDotOverlay(red: boolean): Electron.NativeImage {
   const size = 32
   const canvas = Buffer.alloc(size * size * 4, 0) // RGBA
-
-  // Fill with a semi-transparent dark background circle
+  const [r, g, b] = red ? [235, 64, 52] : [122, 162, 247]
   for (let y = 0; y < size; y++) {
     for (let x = 0; x < size; x++) {
       const cx = x - size / 2
       const cy = y - size / 2
-      const dist = Math.sqrt(cx * cx + cy * cy)
-      if (dist <= size / 2) {
+      if (Math.sqrt(cx * cx + cy * cy) <= size / 2) {
         const idx = (y * size + x) * 4
-        canvas[idx] = 122     // R (blue-ish)
-        canvas[idx + 1] = 162 // G
-        canvas[idx + 2] = 247 // B
-        canvas[idx + 3] = 220 // A
+        canvas[idx] = r
+        canvas[idx + 1] = g
+        canvas[idx + 2] = b
+        canvas[idx + 3] = 235
       }
     }
   }
-
   return nativeImage.createFromBuffer(canvas, { width: size, height: size })
 }
 
-function updateProjectBadge(cwdPath: string | null): void {
-  if (!cwdPath) return
-  const abbrev = getProjectAbbrev(cwdPath)
+// Last project abbreviation, so the steady badge can be restored after the
+// "awaiting input" indicator clears.
+let projectAbbrev = ''
 
-  // macOS: dock badge shows text directly
+function applySteadyBadge(): void {
   if (process.platform === 'darwin' && app.dock) {
-    app.dock.setBadge(abbrev)
+    app.dock.setBadge(projectAbbrev)
   }
-
-  // Windows: overlay icon on taskbar
   if (process.platform === 'win32' && mainWindow) {
-    mainWindow.setOverlayIcon(createOverlayIcon(abbrev), abbrev)
+    mainWindow.setOverlayIcon(projectAbbrev ? createDotOverlay(false) : null, projectAbbrev)
   }
+}
+
+function updateProjectBadge(cwdPath: string | null): void {
+  if (!cwdPath) return
+  projectAbbrev = getProjectAbbrev(cwdPath)
+
+  // Don't stomp the awaiting-input blink; it restores the steady badge itself.
+  if (!blinkTimer) applySteadyBadge()
 
   // All platforms: update window title
   if (mainWindow) {
@@ -95,6 +100,76 @@ function updateProjectBadge(cwdPath: string | null): void {
   }
 }
 
+// ─── "Awaiting input" attention indicator (cross-platform) ──────────
+//
+// The detection is OS-independent; only the visual differs:
+//   macOS   — blink a red dot in the dock badge + one bounce
+//   Windows — red overlay icon on the taskbar button + flash the button
+//   Linux   — badge count where supported + flash (window urgency hint)
+// While the window is focused the dock/taskbar nag is suppressed (the in-app
+// dot is enough); the renderer always gets `agent:state` regardless of OS.
+
+const attention = new AttentionController()
+let blinkTimer: ReturnType<typeof setInterval> | null = null
+let blinkOn = false
+let bounceId = -1
+
+function setAwaitingIndicator(on: boolean): void {
+  applyAttention(attention.setAwaiting(on))
+}
+
+function applyAttention(active: boolean): void {
+  if (active) startAttention()
+  else stopAttention()
+}
+
+function startAttention(): void {
+  if (blinkTimer) return
+  log('[agent-state] attention START (blink + bounce)')
+
+  if (process.platform === 'darwin' && app.dock) {
+    bounceId = app.dock.bounce('informational')
+  }
+  if (process.platform === 'win32' && mainWindow) {
+    mainWindow.setOverlayIcon(createDotOverlay(true), 'Awaiting input')
+    mainWindow.flashFrame(true)
+  }
+  if (process.platform === 'linux') {
+    if (typeof app.badgeCount === 'number') app.badgeCount = 1
+    mainWindow?.flashFrame(true)
+  }
+
+  // Blink the macOS dock badge — the whole red pill (project initials and all)
+  // toggles on/off, so the project letters are preserved on the "on" frames
+  // rather than being replaced by a dot.
+  blinkOn = true
+  blinkTimer = setInterval(() => {
+    blinkOn = !blinkOn
+    if (process.platform === 'darwin' && app.dock) {
+      app.dock.setBadge(blinkOn ? (projectAbbrev || '●') : '')
+    }
+  }, 600)
+}
+
+function stopAttention(): void {
+  if (blinkTimer) {
+    clearInterval(blinkTimer)
+    blinkTimer = null
+    log('[agent-state] attention STOP')
+  }
+  if (process.platform === 'darwin' && app.dock) {
+    if (bounceId >= 0) { app.dock.cancelBounce(bounceId); bounceId = -1 }
+  }
+  if (process.platform === 'win32' && mainWindow) {
+    mainWindow.flashFrame(false)
+  }
+  if (process.platform === 'linux') {
+    if (typeof app.badgeCount === 'number') app.badgeCount = 0
+    mainWindow?.flashFrame(false)
+  }
+  applySteadyBadge()
+}
+
 // ─── Orchestrator (shared logic) ──────────────────
 
 const orchestrator = new Orchestrator(
@@ -107,6 +182,11 @@ const orchestrator = new Orchestrator(
     onWorkerRegistered: (data) => mainWindow?.webContents.send('worker:registered', data),
     onProjectChanged: (name) => mainWindow?.webContents.send('app:projectChanged', name),
     onAgentMessage: (text) => mainWindow?.webContents.send('agent:message', text),
+    onAgentStateChange: (tabId, state, anyAwaiting) => {
+      log(`[agent-state] tab=${tabId} state=${state} anyAwaiting=${anyAwaiting}`)
+      mainWindow?.webContents.send('agent:state', tabId, state, anyAwaiting)
+      setAwaitingIndicator(anyAwaiting)
+    },
     onCwdChanged: () => {
       mainWindow?.webContents.send('app:cwdChanged')
       updateProjectBadge(orchestrator.cwd)
@@ -146,6 +226,12 @@ function createWindow(): void {
     mainWindow.loadFile(path.join(__dirname, '../renderer/index.html'))
   }
 
+  // Focusing the window means the user is here — drop the dock/taskbar nag (the
+  // in-app dot still shows the state). Re-arm it if the agent is still awaiting
+  // when focus is lost again.
+  mainWindow.on('focus', () => applyAttention(attention.setFocused(true)))
+  mainWindow.on('blur', () => applyAttention(attention.setFocused(false)))
+
   mainWindow.on('closed', () => {
     mainWindow = null
   })

package/src/main/orchestrator.ts

@@ -7,6 +7,7 @@ import { AgentConfig, isCodingAgent } from './agents'
 import { CtlsurfApi } from './ctlsurfApi'
 import { ConversationBridge } from './bridge'
 import { TranscriptTailer, supportsTranscriptLogging, readLatestAssistantReply } from './transcripts'
+import { AgentStateMonitor, type AgentState } from './agentState'
 import { WorkerWsClient, type WorkerWsStatus, type IncomingMessage } from './workerWs'
 import { TimeTracker } from './timeTracker'
 import { TicketStore, type TicketInput } from './ticketStore'
@@ -51,6 +52,10 @@ export interface OrchestratorEvents {
   // text-to-speech. Optional and wired only by the Electron entry — the
   // headless build leaves it unset, so replies are never spoken in a terminal.
   onAgentMessage?: (text: string) => void
+  // Real-time agent activity state (busy vs awaiting the user). `anyAwaiting`
+  // is true when any tab is waiting on the user, and drives the dock/taskbar
+  // attention indicator. Optional — only the Electron entry wires it.
+  onAgentStateChange?: (tabId: string, state: AgentState, anyAwaiting: boolean) => void
 }
 
 interface TabState {
@@ -102,11 +107,17 @@ export class Orchestrator {
   private noProjectPollCwd: string | null = null
   private currentProjectName: string | null = null
   private transcriptTailer: TranscriptTailer | null = null
+  private readonly stateMonitor: AgentStateMonitor
 
   constructor(settingsDir: string, events: OrchestratorEvents) {
     this.settingsDir = settingsDir
     this.events = events
 
+    this.stateMonitor = new AgentStateMonitor(({ tabId, state, anyAwaiting }) => {
+      this.events.onAgentStateChange?.(tabId, state, anyAwaiting)
+    })
+    this.stateMonitor.start()
+
     this.workerWs = new WorkerWsClient({
       onStatusChange: (status: WorkerWsStatus) => {
         log(`[worker-ws] Status: ${status}`)
@@ -119,9 +130,10 @@ export class Orchestrator {
 
         if (message.type === 'prompt' || message.type === 'task_dispatch') {
           const activeTab = this.activeTabId ? this.tabs.get(this.activeTabId) : null
-          if (activeTab) {
+          if (activeTab && this.activeTabId) {
             activeTab.ptyManager.write(message.content + '\r')
             this.bridge.feedInput(message.content + '\r')
+            this.stateMonitor.noteInput(this.activeTabId, message.content + '\r')
           }
         }
       },
@@ -463,10 +475,14 @@ export class Orchestrator {
     const ptyManager = new PtyManager(agent, cwd)
     const tab: TabState = { ptyManager, agent, cwd, termStreamBuffer: '', termStreamTimer: null }
     this.tabs.set(tabId, tab)
+    // Track all tabs (not just the active one): a background agent finishing is
+    // exactly when the dock indicator is most useful.
+    this.stateMonitor.trackTab(tabId, agent.id, cwd)
 
     ptyManager.onData((data: string) => {
       this.events.onPtyData(tabId, data)
       this.timeTracker.recordActivity(tabId)
+      this.stateMonitor.feed(tabId, data)
       if (tabId === this.activeTabId) {
         this.bridge.feedOutput(data)
         this.streamTerminalData(tabId, data)
@@ -485,6 +501,7 @@ export class Orchestrator {
       // Clean up tab state
       const t = this.tabs.get(tabId)
       if (t?.termStreamTimer) clearTimeout(t.termStreamTimer)
+      this.stateMonitor.removeTab(tabId)
     })
 
     this.startChatLogging(agent, cwd)
@@ -511,6 +528,7 @@ export class Orchestrator {
 
   writePty(tabId: string, data: string): void {
     this.tabs.get(tabId)?.ptyManager.write(data)
+    this.stateMonitor.noteInput(tabId, data)
     if (tabId === this.activeTabId) {
       this.bridge.feedInput(data)
     }
@@ -531,6 +549,7 @@ export class Orchestrator {
     await this.timeTracker.endSession(tabId)
     tab.ptyManager.kill()
     this.tabs.delete(tabId)
+    this.stateMonitor.removeTab(tabId)
     if (tabId === this.activeTabId) {
       this.stopChatLogging()
       if (isCodingAgent(tab.agent)) {
@@ -702,6 +721,7 @@ export class Orchestrator {
   async shutdown(): Promise<void> {
     this.stopNoProjectPolling()
     this.stopChatLogging()
+    this.stateMonitor.stop()
     await this.timeTracker.endAll()
     for (const [, tab] of this.tabs) {
       if (tab.termStreamTimer) clearTimeout(tab.termStreamTimer)

package/src/preload/index.ts

@@ -119,6 +119,14 @@ const api = {
     ipcRenderer.on('agent:message', listener)
     return () => ipcRenderer.removeListener('agent:message', listener)
   },
+  // Real-time agent activity state for an in-app indicator dot.
+  // state: 'idle' | 'busy' | 'awaiting_input' | 'awaiting_decision'
+  onAgentState: (callback: (tabId: string, state: string, anyAwaiting: boolean) => void) => {
+    const listener = (_event: Electron.IpcRendererEvent, tabId: string, state: string, anyAwaiting: boolean) =>
+      callback(tabId, state, anyAwaiting)
+    ipcRenderer.on('agent:state', listener)
+    return () => ipcRenderer.removeListener('agent:state', listener)
+  },
   // Latest assistant reply from the active tab's transcript (null if none).
   getLastReply: (): Promise<string | null> =>
     ipcRenderer.invoke('agent:getLastReply'),

package/src/renderer/App.tsx

@@ -60,6 +60,7 @@ declare global {
       getSpeakReplies: () => Promise<{ enabled: boolean }>
       setSpeakReplies: (enabled: boolean) => Promise<{ enabled: boolean }>
       onAgentMessage: (callback: (text: string) => void) => () => void
+      onAgentState: (callback: (tabId: string, state: string, anyAwaiting: boolean) => void) => () => void
       getLastReply: () => Promise<string | null>
       createProject: () => Promise<{ ok: boolean; folder_id?: string; error?: string }>
       getWebviewInfo: () => Promise<{
@@ -137,6 +138,9 @@ export default function App() {
   })
   const [activeTabId, setActiveTabId] = useState<string>(tabs[0].id)
   const [trackingActive, setTrackingActive] = useState(false)
+  // Per-tab agent activity ('busy' | 'awaiting_input' | 'awaiting_decision' | 'idle'),
+  // driven by the main process. Powers the awaiting-input dot on each tab.
+  const [agentStates, setAgentStates] = useState<Record<string, string>>({})
   const [showTicketPanel, setShowTicketPanel] = useState(false)
   // Draggable on-canvas push-to-talk mic; visibility persists across launches.
   const [showFloatingMic, setShowFloatingMic] = useState<boolean>(() => {
@@ -202,6 +206,16 @@ export default function App() {
     return unsub
   }, [])
 
+  // Track each tab's agent activity for the awaiting-input dot. The aggregate-
+  // only signal arrives with an empty tabId, which we ignore here.
+  useEffect(() => {
+    const unsub = window.worker.onAgentState((tabId, state) => {
+      if (!tabId) return
+      setAgentStates(prev => (prev[tabId] === state ? prev : { ...prev, [tabId]: state }))
+    })
+    return unsub
+  }, [])
+
   // Reflect tracking state for the active tab; refresh on tab switch and poll
   // periodically so the UI catches changes (e.g. a session ending naturally).
   useEffect(() => {
@@ -424,8 +438,15 @@ export default function App() {
               >
                 <span className="terminal-tab-label">
                   {tab.agent ? tab.agent.name : tab.label}
-                  {tab.agentStatus === 'active' && <span className="terminal-tab-dot active" />}
-                  {tab.agentStatus === 'exited' && <span className="terminal-tab-dot exited" />}
+                  {tab.agentStatus === 'exited' ? (
+                    <span className="terminal-tab-dot exited" />
+                  ) : agentStates[tab.id] === 'awaiting_decision' ? (
+                    <span className="terminal-tab-dot decision" title="Awaiting your approval" />
+                  ) : agentStates[tab.id] === 'awaiting_input' ? (
+                    <span className="terminal-tab-dot awaiting" title="Awaiting your input" />
+                  ) : tab.agentStatus === 'active' ? (
+                    <span className="terminal-tab-dot active" />
+                  ) : null}
                 </span>
                 {tabs.length > 1 && (
                   <button

package/src/renderer/styles.css

@@ -202,6 +202,24 @@ html, body, #root {
   background: #565f89;
 }
 
+/* Agent is waiting on the user — pulse to draw the eye across tabs. */
+.terminal-tab-dot.awaiting {
+  background: #e0af68; /* amber: waiting for next prompt */
+  color: #e0af68;      /* drives the box-shadow glow via currentColor */
+  animation: tab-dot-pulse 1.1s ease-in-out infinite;
+}
+
+.terminal-tab-dot.decision {
+  background: #f7768e; /* red: blocked on an approval/permission prompt */
+  color: #f7768e;
+  animation: tab-dot-pulse 1.1s ease-in-out infinite;
+}
+
+@keyframes tab-dot-pulse {
+  0%, 100% { opacity: 1; box-shadow: 0 0 0 0 currentColor; }
+  50% { opacity: 0.35; box-shadow: 0 0 4px 1px currentColor; }
+}
+
 .terminal-tab-close {
   background: none;
   border: none;