@catdaemon/pi-cmux 0.1.0 → 0.1.2

package/README.md

@@ -1,5 +1,46 @@
-# @catdaemon/pi-cmux
+# pi-cmux
 
 cmux status and notification integration for Pi.
 
-The extension updates cmux status when the main Pi agent starts/finishes work and sends a cmux notification when a turn completes. It also exports helper functions for other Pi extensions that need cmux notifications.
+## Why
+
+When Pi runs inside cmux, it is useful for the surrounding workspace to know whether the agent is busy, idle, or waiting for attention. Without an integration, the user has to keep checking the Pi surface manually to see whether a turn has finished or whether an approval prompt needs feedback.
+
+`pi-cmux` bridges Pi and cmux with lightweight status updates and notifications. It keeps the cmux surface informed while avoiding noise from subagent sessions by default.
+
+This is especially useful for:
+
+- Seeing at a glance whether Pi is currently working
+- Getting notified when an agent turn finishes
+- Surfacing approval prompts from guard extensions
+- Sharing cmux notification helpers with other Pi extensions
+
+## What it does
+
+This Pi package adds cmux integration to Pi:
+
+- **Agent status updates**: sets a cmux status while the main agent is running and returns it to idle when the turn ends.
+- **Done notifications**: sends a cmux notification when a main agent turn completes.
+- **Feedback notifications**: exports helpers that other extensions can use to notify cmux when user feedback is needed.
+- **Subagent filtering**: suppresses subagent turn noise by default.
+- **Runtime status command**: `/cmux-status` shows whether cmux environment variables are detected and how the integration is configured.
+- **Environment configuration**: supports `PI_CMUX_STATUS_KEY`, `PI_CMUX_NOTIFY_DONE`, `PI_CMUX_STATUS_PREVIEW`, and `PI_CMUX_INCLUDE_SUBAGENTS`.
+
+## Install from npm
+
+```bash
+pi install npm:@catdaemon/pi-cmux
+```
+
+Then reload Pi:
+
+```text
+/reload
+/cmux-status
+```
+
+## Runtime dependencies
+
+This package expects the `cmux` CLI to be available when Pi is running inside cmux. Outside cmux, it safely no-ops.
+
+Other Pi extensions can import its notification helpers when they need to signal cmux feedback or completion events.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catdaemon/pi-cmux",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "cmux status and notification integration for Pi.",
   "type": "module",
   "keywords": ["pi-package", "pi", "cmux", "notifications"],

package/src/cmuxIntegration.ts

@@ -13,13 +13,59 @@ import {
 const DEFAULT_STATUS_KEY = 'pi-agent'
 const SUBAGENT_SESSION_DIR = join(getAgentDir(), 'subagents', 'sessions')
 
-type CmuxIntegrationConfig = {
+export type CmuxIntegrationConfig = {
   statusKey: string
   notifyDone: boolean
   includePromptPreviewInStatus: boolean
   includeSubagents: boolean
 }
 
+type ActiveTurn = {
+  prompt: string
+  startedAt: number
+}
+
+type FinishedTurn = ActiveTurn & {
+  remainingActiveTurns: number
+}
+
+export type CmuxTurnTracker = {
+  start(input: { key: string; prompt: string; ignored: boolean; now: number }): void
+  finish(key: string): FinishedTurn | undefined
+  activeCount(): number
+}
+
+function createTurnTracker(): CmuxTurnTracker {
+  const activeTurns = new Map<string, ActiveTurn>()
+  const ignoredTurns = new Set<string>()
+
+  return {
+    start(input) {
+      activeTurns.delete(input.key)
+      ignoredTurns.delete(input.key)
+      if (input.ignored) {
+        ignoredTurns.add(input.key)
+        return
+      }
+      activeTurns.set(input.key, { prompt: input.prompt, startedAt: input.now })
+    },
+    finish(key) {
+      if (ignoredTurns.delete(key)) return undefined
+      const turn = activeTurns.get(key)
+      activeTurns.delete(key)
+      if (!turn) return undefined
+      return { ...turn, remainingActiveTurns: activeTurns.size }
+    },
+    activeCount() {
+      return activeTurns.size
+    },
+  }
+}
+
+export function createCmuxTurnTrackerForTest(): CmuxTurnTracker {
+  return createTurnTracker()
+}
+
 function readConfig(env: NodeJS.ProcessEnv = process.env): CmuxIntegrationConfig {
   return {
     statusKey: env.PI_CMUX_STATUS_KEY || DEFAULT_STATUS_KEY,
@@ -53,21 +99,20 @@ function sessionKey(ctx: ExtensionContext) {
 }
 
 export default function cmuxIntegration(pi: ExtensionAPI) {
-  const activePrompts = new Map<string, string>()
-  const activeStarts = new Map<string, number>()
+  const turnTracker = createTurnTracker()
   const config = readConfig()
 
   pi.on('before_agent_start', async (event, ctx) => {
     const key = sessionKey(ctx)
-    if (!isCmuxEnvironment() || shouldIgnoreTurn(ctx, event.prompt, config)) {
-      activePrompts.delete(key)
-      activeStarts.delete(key)
+    if (!isCmuxEnvironment()) {
+      turnTracker.finish(key)
       return undefined
     }
 
+    const ignored = shouldIgnoreTurn(ctx, event.prompt, config)
     const preview = truncatePreview(event.prompt)
-    activePrompts.set(key, preview)
-    activeStarts.set(key, Date.now())
+    turnTracker.start({ key, prompt: preview, ignored, now: Date.now() })
+    if (ignored) return undefined
     const status = config.includePromptPreviewInStatus ? `Running: ${truncatePreview(event.prompt, 48)}` : 'Running'
     void setCmuxStatus(pi, config.statusKey, status, { icon: 'sparkles', color: '#3b82f6', signal: ctx.signal })
     return undefined
@@ -75,23 +120,16 @@ export default function cmuxIntegration(pi: ExtensionAPI) {
 
   pi.on('agent_end', async (_event, ctx) => {
     const key = sessionKey(ctx)
-    if (!isCmuxEnvironment() || (!config.includeSubagents && isSubagentSession(ctx))) {
-      activePrompts.delete(key)
-      activeStarts.delete(key)
-      return
-    }
+    const finished = turnTracker.finish(key)
+    if (!isCmuxEnvironment() || !finished) return
 
-    const prompt = activePrompts.get(key)
-    const startedAt = activeStarts.get(key)
-    activePrompts.delete(key)
-    activeStarts.delete(key)
-
-    const elapsed = startedAt ? Math.max(1, Math.round((Date.now() - startedAt) / 1000)) : undefined
-    const idleText = elapsed ? `Idle (${elapsed}s)` : 'Idle'
-    void setCmuxStatus(pi, config.statusKey, idleText, { icon: 'check', color: '#34c759', signal: ctx.signal })
+    const elapsed = Math.max(1, Math.round((Date.now() - finished.startedAt) / 1000))
+    if (finished.remainingActiveTurns === 0) {
+      void setCmuxStatus(pi, config.statusKey, `Idle (${elapsed}s)`, { icon: 'check', color: '#34c759', signal: ctx.signal })
+    }
 
     if (config.notifyDone) {
-      const body = prompt ? `Finished: ${prompt}` : 'Agent finished and is ready for your next message.'
+      const body = finished.prompt ? `Finished: ${finished.prompt}` : 'Agent finished and is ready for your next message.'
       void notifyCmuxDone(pi, elapsed ? `${body}\nElapsed: ${elapsed}s` : body, {
         title: 'Pi',
         subtitle: 'Done',

package/src/tests/turnTracker.test.ts

@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+import { createCmuxTurnTrackerForTest } from '../cmuxIntegration.ts'
+
+describe('cmux turn tracker', () => {
+  it('does not finish ignored subagent turns', () => {
+    const tracker = createCmuxTurnTrackerForTest()
+    tracker.start({ key: 'subagent', prompt: 'subagent work', ignored: true, now: 1000 })
+
+    assert.equal(tracker.activeCount(), 0)
+    assert.equal(tracker.finish('subagent'), undefined)
+  })
+
+  it('keeps workspace running until all tracked turns finish', () => {
+    const tracker = createCmuxTurnTrackerForTest()
+    tracker.start({ key: 'main', prompt: 'main work', ignored: false, now: 1000 })
+    tracker.start({ key: 'worker', prompt: 'worker work', ignored: false, now: 2000 })
+
+    const first = tracker.finish('worker')
+    assert.equal(first?.remainingActiveTurns, 1)
+    assert.equal(tracker.activeCount(), 1)
+
+    const second = tracker.finish('main')
+    assert.equal(second?.remainingActiveTurns, 0)
+    assert.equal(tracker.activeCount(), 0)
+  })
+})