@brimveyn/aimux 1.16.3 → 1.18.1

package/src/cli/client/workspace-resolver.ts

@@ -0,0 +1,57 @@
+import type { SessionRecord } from '../../state/types'
+
+import { findMostRecentSession, loadSessionCatalog } from '../../state/session-catalog'
+
+/**
+ * Resolve `--workspace W` to a session record from the catalog. Falls back to
+ * the most recently opened session when the flag is absent. Throws when the
+ * catalog is empty (no session has ever been created) or when the explicit
+ * name/id doesn't match.
+ *
+ * Matching: exact id wins; otherwise exact name (case-sensitive); otherwise
+ * unique case-insensitive name match.
+ */
+export function resolveWorkspace(name: string | undefined): SessionRecord {
+  const sessions = loadSessionCatalog()
+  if (sessions.length === 0) {
+    throw new Error(
+      'no sessions found — create one from the aimux UI first (or pass --workspace once created)'
+    )
+  }
+
+  if (name === undefined || name === '') {
+    const active = findMostRecentSession(sessions)
+    if (!active) {
+      throw new Error('no active workspace and the catalog is empty')
+    }
+    return active
+  }
+
+  const byId = sessions.find((session) => session.id === name)
+  if (byId) return byId
+
+  const exactNameMatches = sessions.filter((session) => session.name === name)
+  if (exactNameMatches.length > 1) {
+    throw new Error(
+      `workspace "${name}" matches multiple sessions: ${exactNameMatches.map((s) => s.id).join(', ')}`
+    )
+  }
+  const exactOnly = exactNameMatches[0]
+  if (exactOnly) return exactOnly
+
+  const lower = name.toLowerCase()
+  const ciMatches = sessions.filter((session) => session.name.toLowerCase() === lower)
+  if (ciMatches.length > 1) {
+    throw new Error(
+      `workspace "${name}" matches multiple sessions: ${ciMatches.map((s) => s.id).join(', ')}`
+    )
+  }
+  const ciOnly = ciMatches[0]
+  if (ciOnly) return ciOnly
+
+  throw new Error(`workspace not found: ${name}`)
+}
+
+export function listWorkspaces(): SessionRecord[] {
+  return loadSessionCatalog()
+}

package/src/cli/commands/tab/close.ts

@@ -0,0 +1,33 @@
+import type { CliCommand } from '../../registry'
+
+import { IPC_CAPABILITY_THIN_ATTACH } from '../../../ipc/protocol'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+
+export const tabClose: CliCommand = {
+  args: [{ name: 'tabId', required: true }],
+  flags: SHARED_FLAGS,
+  group: 'tab',
+  run: async (ctx) => {
+    const tabId = ctx.args.positionals[0]
+    if (typeof tabId !== 'string' || tabId.length === 0) {
+      throw new Error('tabId is required')
+    }
+
+    const workspace = ctx.getWorkspace()
+    const daemon = await ctx.getDaemon()
+
+    if (!daemon.hasCapability(IPC_CAPABILITY_THIN_ATTACH)) {
+      throw new Error(
+        'daemon predates thinAttach capability — restart aimux to pick up the new daemon'
+      )
+    }
+    await daemon.attach({ cols: 0, rows: 0, sessionId: workspace.id, thin: true })
+    await daemon.expectOk('closeTab', { tabId })
+
+    writeJson({ ok: true })
+    return EXIT_OK
+  },
+  summary: 'Close a tab in the workspace',
+  verb: 'close',
+}

package/src/cli/commands/tab/create.ts

@@ -0,0 +1,109 @@
+import { resolve as resolvePath } from 'node:path'
+
+import type { CliCommand } from '../../registry'
+
+import {
+  IPC_CAPABILITY_CREATE_TAB_SIZE_FALLBACK,
+  IPC_CAPABILITY_THIN_ATTACH,
+} from '../../../ipc/protocol'
+import { createPrefixedId } from '../../../platform/id'
+import { getAllAssistantOptions, parseCommand } from '../../../pty/command-registry'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+
+const FALLBACK_COLS = 200
+const FALLBACK_ROWS = 60
+
+export const tabCreate: CliCommand = {
+  args: [],
+  flags: [
+    ...SHARED_FLAGS,
+    {
+      description: 'assistant id (claude, codex, opencode, terminal, ...)',
+      kind: 'string',
+      name: 'assistant',
+    },
+    { description: 'tab title (defaults to assistant label)', kind: 'string', name: 'title' },
+    { description: 'cwd for the spawned PTY', kind: 'string', name: 'cwd' },
+    {
+      description: 'explicit command (overrides the assistant default)',
+      kind: 'string',
+      name: 'command',
+    },
+    {
+      description: 'worktree id the tab belongs to (defaults to the workspace’s active worktree)',
+      kind: 'string',
+      name: 'worktree',
+    },
+  ],
+  group: 'tab',
+  run: async (ctx) => {
+    const assistantId = ctx.args.flags.assistant
+    if (typeof assistantId !== 'string' || assistantId.length === 0) {
+      throw new Error('--assistant is required')
+    }
+    const options = getAllAssistantOptions({})
+    const option = options.find((o) => o.id === assistantId)
+    if (!option) {
+      throw new Error(
+        `unknown assistant: ${assistantId} (known: ${options.map((o) => o.id).join(', ')})`
+      )
+    }
+    const command =
+      typeof ctx.args.flags.command === 'string' ? ctx.args.flags.command : option.command
+    const title = typeof ctx.args.flags.title === 'string' ? ctx.args.flags.title : option.label
+    const cwdRaw = typeof ctx.args.flags.cwd === 'string' ? ctx.args.flags.cwd : undefined
+    const cwd = cwdRaw === undefined ? undefined : resolvePath(cwdRaw)
+
+    const workspace = ctx.getWorkspace()
+    const daemon = await ctx.getDaemon()
+
+    if (!daemon.hasCapability(IPC_CAPABILITY_THIN_ATTACH)) {
+      throw new Error(
+        'daemon predates thinAttach capability — restart aimux to pick up the new daemon'
+      )
+    }
+
+    // Resolve worktreeId: explicit flag wins, otherwise the workspace's
+    // currently-active worktree, otherwise undefined (= no grouping).
+    const worktreeFlag =
+      typeof ctx.args.flags.worktree === 'string' ? ctx.args.flags.worktree : undefined
+    let worktreeId: string | undefined = worktreeFlag ?? workspace.activeWorktreeId
+    if (worktreeFlag !== undefined) {
+      const known = workspace.worktrees?.some((w) => w.id === worktreeFlag) ?? false
+      if (!known) {
+        const ids = workspace.worktrees?.map((w) => w.id).join(', ') ?? '(none)'
+        throw new Error(`unknown worktree id: ${worktreeFlag} (known: ${ids})`)
+      }
+      worktreeId = worktreeFlag
+    }
+
+    // Thin-attach so we don't clobber the UI's dimensions on the same session.
+    await daemon.attach({ cols: 0, rows: 0, sessionId: workspace.id, thin: true })
+
+    const { args, executable } = parseCommand(command)
+    const tabId = createPrefixedId('tab')
+
+    // cols/rows = 0 means "fall back to the session's last attached size" on
+    // v11 daemons. Without that capability we have nothing reasonable to put
+    // here (the CLI has no terminal of its own), so use a roomy fallback —
+    // PTYs are reflowable, so 200×60 won't break anything that adapts.
+    const useFallback = daemon.hasCapability(IPC_CAPABILITY_CREATE_TAB_SIZE_FALLBACK)
+    await daemon.expectOk('createTab', {
+      args,
+      assistant: assistantId,
+      cols: useFallback ? 0 : FALLBACK_COLS,
+      command: executable,
+      cwd,
+      rows: useFallback ? 0 : FALLBACK_ROWS,
+      tabId,
+      title,
+      worktreeId,
+    })
+
+    writeJson({ assistant: assistantId, command, tabId, title, worktreeId })
+    return EXIT_OK
+  },
+  summary: 'Create a new tab in the active workspace',
+  verb: 'create',
+}

package/src/cli/commands/tab/focus.ts

@@ -0,0 +1,33 @@
+import type { CliCommand } from '../../registry'
+
+import { IPC_CAPABILITY_THIN_ATTACH } from '../../../ipc/protocol'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+
+export const tabFocus: CliCommand = {
+  args: [{ name: 'tabId', required: true }],
+  flags: SHARED_FLAGS,
+  group: 'tab',
+  run: async (ctx) => {
+    const tabId = ctx.args.positionals[0]
+    if (typeof tabId !== 'string' || tabId.length === 0) {
+      throw new Error('tabId is required')
+    }
+
+    const workspace = ctx.getWorkspace()
+    const daemon = await ctx.getDaemon()
+
+    if (!daemon.hasCapability(IPC_CAPABILITY_THIN_ATTACH)) {
+      throw new Error(
+        'daemon predates thinAttach capability — restart aimux to pick up the new daemon'
+      )
+    }
+    await daemon.attach({ cols: 0, rows: 0, sessionId: workspace.id, thin: true })
+    await daemon.expectOk('setActiveTab', { tabId })
+
+    writeJson({ ok: true })
+    return EXIT_OK
+  },
+  summary: 'Set the active tab in the workspace',
+  verb: 'focus',
+}

package/src/cli/commands/tab/list.ts

@@ -0,0 +1,52 @@
+import type { CliCommand } from '../../registry'
+
+import { IPC_CAPABILITY_LIST_TABS, IPC_CAPABILITY_THIN_ATTACH } from '../../../ipc/protocol'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+
+export const tabList: CliCommand = {
+  args: [],
+  flags: SHARED_FLAGS,
+  group: 'tab',
+  run: async (ctx) => {
+    const workspace = ctx.getWorkspace()
+    const daemon = await ctx.getDaemon()
+
+    if (daemon.hasCapability(IPC_CAPABILITY_LIST_TABS)) {
+      const result = await daemon.listTabs(workspace.id)
+      writeJson({ activeTabId: result.activeTabId, tabs: result.tabs })
+      return EXIT_OK
+    }
+
+    if (!daemon.hasCapability(IPC_CAPABILITY_THIN_ATTACH)) {
+      throw new Error(
+        'daemon predates listTabs and thinAttach capabilities — restart aimux to pick up the new daemon'
+      )
+    }
+
+    // Fallback: thin-attach to read the same information without resizing the
+    // session. Pre-listTabs daemons that advertise thinAttach would in
+    // principle land here, but that combination shouldn't ship.
+    const attach = await daemon.attach({
+      cols: 0,
+      rows: 0,
+      sessionId: workspace.id,
+      thin: true,
+    })
+    writeJson({
+      activeTabId: attach.activeTabId,
+      tabs: attach.tabs.map((tab) => ({
+        activity: tab.activity,
+        assistant: tab.assistant,
+        command: tab.command,
+        id: tab.id,
+        status: tab.status,
+        title: tab.title,
+        worktreeId: tab.worktreeId,
+      })),
+    })
+    return EXIT_OK
+  },
+  summary: 'List tabs in the active workspace',
+  verb: 'list',
+}

package/src/cli/commands/tab/send.ts

@@ -0,0 +1,83 @@
+import type { CliCommand } from '../../registry'
+
+import { IPC_CAPABILITY_THIN_ATTACH } from '../../../ipc/protocol'
+import { bracketedPaste, notationToBytes } from '../../chord'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+
+/**
+ * Lower a chord/paste buffer of bytes into the string the protocol expects.
+ * Every byte we emit is < 0x80 (control chars or printable ASCII), so a
+ * Latin-1 decode is faithful — the receiving PTY's UTF-8 path treats each
+ * single byte as itself.
+ */
+function bytesToString(bytes: Buffer): string {
+  let out = ''
+  for (const byte of bytes) {
+    out += String.fromCharCode(byte)
+  }
+  return out
+}
+
+export const tabSend: CliCommand = {
+  args: [{ name: 'tabId', required: true }, { name: 'text' }],
+  flags: [
+    ...SHARED_FLAGS,
+    { description: 'append \\r so the receiving CLI submits', kind: 'boolean', name: 'enter' },
+    {
+      description: 'interpret <text> as a vim-style key chord (e.g. <C-c>, <Esc>, <Up><Up>)',
+      kind: 'boolean',
+      name: 'keys',
+    },
+    {
+      description: 'read the payload from stdin instead of <text>',
+      kind: 'boolean',
+      name: 'stdin',
+    },
+  ],
+  group: 'tab',
+  run: async (ctx) => {
+    const tabId = ctx.args.positionals[0]
+    if (typeof tabId !== 'string' || tabId.length === 0) {
+      throw new Error('tabId is required')
+    }
+
+    const fromStdin = ctx.args.flags.stdin === true
+    const asKeys = ctx.args.flags.keys === true
+    const appendEnter = ctx.args.flags.enter === true
+
+    let data: string
+    if (fromStdin) {
+      const stdinText = await Bun.stdin.text()
+      data = asKeys ? bytesToString(notationToBytes(stdinText)) : bracketedPaste(stdinText)
+    } else {
+      const text = ctx.args.positionals[1] ?? ''
+      if (asKeys) {
+        if (text === '') throw new Error('--keys requires the chord notation as <text>')
+        data = bytesToString(notationToBytes(text))
+      } else {
+        data = bracketedPaste(text)
+      }
+    }
+
+    if (appendEnter) {
+      data = `${data}\r`
+    }
+
+    const workspace = ctx.getWorkspace()
+    const daemon = await ctx.getDaemon()
+    if (!daemon.hasCapability(IPC_CAPABILITY_THIN_ATTACH)) {
+      throw new Error(
+        'daemon predates thinAttach capability — restart aimux to pick up the new daemon'
+      )
+    }
+
+    await daemon.attach({ cols: 0, rows: 0, sessionId: workspace.id, thin: true })
+    await daemon.expectOk('write', { data, tabId })
+
+    writeJson({ bytesWritten: Buffer.byteLength(data, 'utf8'), ok: true })
+    return EXIT_OK
+  },
+  summary: 'Write text or a key chord to a tab',
+  verb: 'send',
+}

package/src/cli/commands/tab/snapshot.ts

@@ -0,0 +1,127 @@
+import type { TerminalSnapshot } from '../../../state/types'
+import type { CliCommand } from '../../registry'
+
+import { IPC_CAPABILITY_THIN_ATTACH } from '../../../ipc/protocol'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+import { snapshotTailLines, snapshotToLines } from '../../snapshot-render'
+
+const RENDER_WAIT_MS = 500
+
+export const tabSnapshot: CliCommand = {
+  args: [{ name: 'tabId', required: true }],
+  flags: [
+    ...SHARED_FLAGS,
+    { description: 'return only the last N non-blank lines', kind: 'number', name: 'tail' },
+    {
+      description: 'output format: json (default) or text (raw screen dump)',
+      kind: 'string',
+      name: 'format',
+    },
+    {
+      description: 'do not strip trailing whitespace from each line',
+      kind: 'boolean',
+      name: 'no-trim',
+    },
+  ],
+  group: 'tab',
+  run: async (ctx) => {
+    const tabId = ctx.args.positionals[0]
+    if (typeof tabId !== 'string' || tabId.length === 0) {
+      throw new Error('tabId is required')
+    }
+    const tail = typeof ctx.args.flags.tail === 'number' ? ctx.args.flags.tail : 0
+    const format = ctx.args.flags.format ?? 'json'
+    if (format !== 'json' && format !== 'text') {
+      throw new Error(`--format must be "json" or "text" (got: ${String(format)})`)
+    }
+    const renderOptions = { trim: ctx.args.flags['no-trim'] !== true }
+
+    const workspace = ctx.getWorkspace()
+    const daemon = await ctx.getDaemon()
+    if (!daemon.hasCapability(IPC_CAPABILITY_THIN_ATTACH)) {
+      throw new Error(
+        'daemon predates thinAttach capability — restart aimux to pick up the new daemon'
+      )
+    }
+
+    // Subscribe BEFORE attaching so a render fired between attach completion
+    // and our subscription doesn't slip through.
+    const renderState: { cancel: (() => void) | null } = { cancel: null }
+    const renderPromise = new Promise<TerminalSnapshot | null>((resolve) => {
+      const off = daemon.on('tabRender', (payload) => {
+        if (payload.tabId !== tabId) return
+        off()
+        clearTimeout(timer)
+        renderState.cancel = null
+        resolve(payload.viewport)
+      })
+      const timer = setTimeout(() => {
+        off()
+        renderState.cancel = null
+        resolve(null)
+      }, RENDER_WAIT_MS)
+      renderState.cancel = () => {
+        clearTimeout(timer)
+        off()
+        resolve(null)
+      }
+    })
+
+    const attach = await daemon.attach({
+      cols: 0,
+      rows: 0,
+      sessionId: workspace.id,
+      thin: true,
+    })
+    const tab = attach.tabs.find((t) => t.id === tabId)
+    if (!tab) {
+      renderState.cancel?.()
+      throw new Error(`tab not found: ${tabId}`)
+    }
+
+    let snapshot = tab.viewport
+    if (!snapshot || snapshot.lines.length === 0) {
+      const awaited = await renderPromise
+      if (awaited) snapshot = awaited
+    } else {
+      renderState.cancel?.()
+    }
+
+    if (!snapshot) {
+      throw new Error('no snapshot available within timeout')
+    }
+
+    const lines =
+      tail > 0
+        ? snapshotTailLines(snapshot, tail, renderOptions)
+        : snapshotToLines(snapshot, renderOptions)
+
+    if (format === 'text') {
+      // Raw screen dump: best fit when piping into an LLM prompt — no JSON
+      // escape noise, the model sees the terminal exactly as it appears.
+      // The tail-trim and per-line trim already ran above; just join.
+      process.stdout.write(`${lines.join('\n')}\n`)
+      return EXIT_OK
+    }
+
+    let widest = 0
+    for (const line of lines) {
+      if (line.length > widest) widest = line.length
+    }
+    writeJson({
+      cols: widest,
+      cursor: {
+        col: snapshot.cursorCol ?? null,
+        row: snapshot.cursorRow ?? null,
+        visible: snapshot.cursorVisible,
+      },
+      lines,
+      rows: lines.length,
+      tabId,
+    })
+    return EXIT_OK
+  },
+  summary: 'Snapshot the visible viewport of a tab as plain text',
+  verb: 'snapshot',
+}

package/src/cli/commands/tab/tail.ts

@@ -0,0 +1,171 @@
+import type { TerminalSnapshot } from '../../../state/types'
+import type { CliCommand } from '../../registry'
+
+import { IPC_CAPABILITY_THIN_ATTACH } from '../../../ipc/protocol'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, EXIT_RUNTIME, EXIT_TIMEOUT, writeNdjson } from '../../output'
+import { snapshotToLines } from '../../snapshot-render'
+
+interface Cursor {
+  row: number | null
+  col: number | null
+  visible: boolean
+}
+
+function toCursor(snapshot: TerminalSnapshot): Cursor {
+  return {
+    col: snapshot.cursorCol ?? null,
+    row: snapshot.cursorRow ?? null,
+    visible: snapshot.cursorVisible,
+  }
+}
+
+export const tabTail: CliCommand = {
+  args: [{ name: 'tabId', required: true }],
+  flags: [
+    ...SHARED_FLAGS,
+    {
+      description: 'emit the raw TerminalSnapshot instead of the trimmed text lines',
+      kind: 'boolean',
+      name: 'raw',
+    },
+    {
+      description: 'coalesce renders arriving within N ms (default 0 = no coalescing)',
+      kind: 'number',
+      name: 'rate-limit-ms',
+    },
+    {
+      description: 'also emit tabStatus records interleaved with renders',
+      kind: 'boolean',
+      name: 'follow-status',
+    },
+    {
+      description: 'exit after N milliseconds even if the tab is still alive',
+      kind: 'number',
+      name: 'timeout',
+    },
+  ],
+  group: 'tab',
+  run: async (ctx) => {
+    const tabId = ctx.args.positionals[0]
+    if (typeof tabId !== 'string' || tabId.length === 0) {
+      throw new Error('tabId is required')
+    }
+    const raw = ctx.args.flags.raw === true
+    const rateLimitMs =
+      typeof ctx.args.flags['rate-limit-ms'] === 'number' ? ctx.args.flags['rate-limit-ms'] : 0
+    const followStatus = ctx.args.flags['follow-status'] === true
+    const timeoutMs = typeof ctx.args.flags.timeout === 'number' ? ctx.args.flags.timeout : 0
+
+    const workspace = ctx.getWorkspace()
+    const daemon = await ctx.getDaemon()
+    if (!daemon.hasCapability(IPC_CAPABILITY_THIN_ATTACH)) {
+      throw new Error(
+        'daemon predates thinAttach capability — restart aimux to pick up the new daemon'
+      )
+    }
+
+    const start = Date.now()
+    // Attach before wiring subscribers so replay renders arrive after we
+    // print the "attached" marker; that keeps NDJSON output deterministic
+    // for downstream consumers.
+    const attach = await daemon.attach({ cols: 0, rows: 0, sessionId: workspace.id, thin: true })
+
+    // Fail fast on a bad tabId — otherwise tail would sit silent until
+    // --timeout, since no matching tabRender/tabExit would ever fire.
+    if (!attach.tabs.some((t) => t.id === tabId)) {
+      throw new Error(`tab not found: ${tabId}`)
+    }
+
+    return new Promise<number>((resolve) => {
+      let lastEmitAt = 0
+      let pendingViewport: TerminalSnapshot | null = null
+      let coalesceTimer: ReturnType<typeof setTimeout> | null = null
+
+      const emitRender = (viewport: TerminalSnapshot): void => {
+        const ts = Date.now() - start
+        if (raw) {
+          writeNdjson({ tabId, ts, type: 'render', viewport })
+        } else {
+          writeNdjson({
+            cursor: toCursor(viewport),
+            lines: snapshotToLines(viewport, { trim: true }),
+            tabId,
+            ts,
+            type: 'render',
+          })
+        }
+        lastEmitAt = Date.now()
+      }
+
+      const scheduleCoalesced = (viewport: TerminalSnapshot): void => {
+        pendingViewport = viewport
+        if (coalesceTimer) return
+        const elapsed = Date.now() - lastEmitAt
+        const wait = Math.max(0, rateLimitMs - elapsed)
+        coalesceTimer = setTimeout(() => {
+          coalesceTimer = null
+          const v = pendingViewport
+          pendingViewport = null
+          if (v) emitRender(v)
+        }, wait)
+      }
+
+      const offRender = daemon.on('tabRender', (payload) => {
+        if (payload.tabId !== tabId) return
+        if (rateLimitMs > 0) {
+          scheduleCoalesced(payload.viewport)
+        } else {
+          emitRender(payload.viewport)
+        }
+      })
+      const offExit = daemon.on('tabExit', (payload) => {
+        if (payload.tabId !== tabId) return
+        writeNdjson({ exitCode: payload.exitCode, tabId, ts: Date.now() - start, type: 'exit' })
+        cleanup()
+        resolve(EXIT_OK)
+      })
+      const offError = daemon.on('tabError', (payload) => {
+        if (payload.tabId !== tabId) return
+        writeNdjson({ error: payload.message, tabId, ts: Date.now() - start, type: 'error' })
+        cleanup()
+        resolve(EXIT_RUNTIME)
+      })
+      const noop = (): void => {}
+      const offStatus = followStatus
+        ? daemon.on('tabStatus', (payload) => {
+            if (payload.tabId !== tabId) return
+            writeNdjson({
+              status: payload.status,
+              tabId,
+              ts: Date.now() - start,
+              type: 'status',
+            })
+          })
+        : noop
+
+      const timer =
+        timeoutMs > 0
+          ? setTimeout(() => {
+              writeNdjson({ tabId, ts: Date.now() - start, type: 'timeout' })
+              cleanup()
+              resolve(EXIT_TIMEOUT)
+            }, timeoutMs)
+          : null
+
+      const cleanup = (): void => {
+        offRender()
+        offExit()
+        offError()
+        offStatus()
+        if (coalesceTimer) {
+          clearTimeout(coalesceTimer)
+          coalesceTimer = null
+        }
+        if (timer) clearTimeout(timer)
+      }
+    })
+  },
+  summary: 'Stream a tab’s render events as NDJSON',
+  verb: 'tail',
+}