typeclaw 0.9.2 → 0.11.0

package/src/cli/inspect-controller.ts

@@ -0,0 +1,66 @@
+// Pure controller for the inspect CLI's esc/ctrl-c key dispatch.
+// Owns the AbortController lifecycle and the bare-ESC debounce timer,
+// independent of process.stdin / TTY raw mode (which is wired in src/cli/inspect.ts).
+// Extracted for testability: the lifecycle bug we want to pin is "armForStream's
+// signal must remain valid across pause()/resume() cycles" — verifying that without
+// a real TTY requires this seam.
+
+export type EscChunkResult = { sigint: boolean }
+
+export type EscController = {
+  armForStream: () => AbortSignal
+  onChunk: (chunk: Buffer) => EscChunkResult
+  clearPending: () => void
+  dispose: () => void
+}
+
+export function createEscController({ debounceMs }: { debounceMs: number }): EscController {
+  let currentCtrl: AbortController | null = null
+  let pendingEsc: ReturnType<typeof setTimeout> | null = null
+
+  const clearPending = (): void => {
+    if (pendingEsc !== null) {
+      clearTimeout(pendingEsc)
+      pendingEsc = null
+    }
+  }
+
+  return {
+    armForStream: () => {
+      clearPending()
+      currentCtrl = new AbortController()
+      return currentCtrl.signal
+    },
+    onChunk: (chunk) => {
+      if (chunk.length === 0) return { sigint: false }
+      if (chunk[0] === 0x03) {
+        // Ctrl-C in raw mode arrives as a byte (terminal driver does not generate
+        // SIGINT). Surface to the caller so it can re-issue SIGINT via the OS;
+        // we deliberately keep the AbortController lifecycle separate from SIGINT.
+        return { sigint: true }
+      }
+      if (chunk.length === 1 && chunk[0] === 0x1b) {
+        // Bare ESC: schedule the abort. A follow-up byte within debounceMs (CSI
+        // sequences from arrow keys, mouse, paste) cancels the pending fire.
+        // Snapshot currentCtrl so a late-firing timer can't abort a controller
+        // created by a subsequent armForStream() call.
+        clearPending()
+        const ctrl = currentCtrl
+        pendingEsc = setTimeout(() => {
+          pendingEsc = null
+          ctrl?.abort()
+        }, debounceMs)
+        return { sigint: false }
+      }
+      // Any other byte arriving within the ESC window is the second byte of a CSI
+      // sequence; cancel the pending abort.
+      clearPending()
+      return { sigint: false }
+    },
+    clearPending,
+    dispose: () => {
+      clearPending()
+      currentCtrl = null
+    },
+  }
+}

package/src/cli/inspect.ts

@@ -2,15 +2,18 @@ import { defineCommand } from 'citty'
 
 import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
 import { findAgentDir } from '@/init'
-import { runInspect, streamLive, type LiveSourceFactory, type SessionSummary } from '@/inspect'
+import { runInspectLoop, streamLive, type LiveSourceFactory, type SessionSummary } from '@/inspect'
 import { originLabel, shortSessionId } from '@/inspect/label'
 
+import { createEscController } from './inspect-controller'
 import { cancel, c, errorLine, isCancel } from './ui'
 
+const ESC_LISTEN_DELAY_MS = 50
+
 export const inspectCommand = defineCommand({
   meta: {
     name: 'inspect',
-    description: 'replay a session transcript and tail live activity (host stage)',
+    description: 'observe a session: replay the transcript, then tail live activity (host stage)',
   },
   args: {
     session: {
@@ -32,12 +35,6 @@ export const inspectCommand = defineCommand({
       description: 'emit one JSON event per line; requires an explicit session id',
       default: false,
     },
-    follow: {
-      type: 'boolean',
-      description:
-        'tail live activity after replay (default: true when the container is running); pass --no-follow to replay-then-exit',
-      default: true,
-    },
   },
   async run({ args }) {
     const cwd = findAgentDir(process.cwd()) ?? process.cwd()
@@ -45,26 +42,39 @@ export const inspectCommand = defineCommand({
     const sessionArg = typeof args.session === 'string' ? args.session : undefined
     const filterArg = typeof args.filter === 'string' ? args.filter : undefined
     const sinceArg = typeof args.since === 'string' ? args.since : undefined
-    const follow = args.follow !== false
 
     const isJson = args.json === true
-    const liveSource = !follow || isJson ? undefined : await buildLiveSource(cwd)
+    const liveSource = isJson ? undefined : await buildLiveSource(cwd)
     const signal = installSigintAbort()
+    const escListener = isJson ? null : createEscListener()
+    const liveHint = escListener === null ? undefined : escHintLine(color)
 
-    const result = await runInspect({
+    const result = await runInspectLoop({
       agentDir: cwd,
       ...(sessionArg !== undefined ? { sessionIdOrPrefix: sessionArg } : {}),
       ...(filterArg !== undefined ? { filter: filterArg } : {}),
       ...(sinceArg !== undefined ? { since: sinceArg } : {}),
       json: isJson,
       color,
-      selectSession: clackSelect,
+      selectSession: (sessions, selectOpts) => {
+        escListener?.pause()
+        return clackSelect(sessions, selectOpts?.initialSessionId).finally(() => {
+          escListener?.resume()
+        })
+      },
       ...(liveSource !== undefined ? { liveSource } : {}),
       signal,
+      newEscSignal: () => {
+        if (escListener === null) return new AbortController().signal
+        return escListener.armForStream()
+      },
+      ...(liveHint !== undefined ? { liveHint } : {}),
       stdout: (line) => process.stdout.write(`${line}\n`),
       stderr: (line) => process.stderr.write(`${line}\n`),
     })
 
+    escListener?.stop()
+
     if (!result.ok) {
       process.stderr.write(`${errorLine(result.reason)}\n`)
       process.exit(result.exitCode)
@@ -104,6 +114,74 @@ function installSigintAbort(): AbortSignal {
   return ctrl.signal
 }
 
+type EscListener = {
+  armForStream: () => AbortSignal
+  pause: () => void
+  resume: () => void
+  stop: () => void
+}
+
+function createEscListener(): EscListener | null {
+  const stdin = process.stdin
+  if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') return null
+
+  const ctrl = createEscController({ debounceMs: ESC_LISTEN_DELAY_MS })
+  let active = false
+
+  const onData = (chunk: Buffer): void => {
+    const { sigint } = ctrl.onChunk(chunk)
+    if (sigint) process.kill(process.pid, 'SIGINT')
+  }
+
+  const start = (): void => {
+    if (active) return
+    active = true
+    stdin.setRawMode(true)
+    stdin.resume()
+    stdin.on('data', onData)
+  }
+  const stop = (): void => {
+    if (!active) return
+    active = false
+    stdin.off('data', onData)
+    try {
+      stdin.setRawMode(false)
+    } catch {
+      /* terminal already torn down */
+    }
+    stdin.pause()
+    ctrl.clearPending()
+  }
+
+  return {
+    armForStream: () => {
+      const signal = ctrl.armForStream()
+      start()
+      return signal
+    },
+    pause: () => {
+      stop()
+    },
+    resume: () => {
+      // Resume the listener WITHOUT replacing the AbortController.
+      // The signal returned by armForStream() is held by the live source
+      // through streamSession's combinedSignal; replacing the controller
+      // here would orphan that signal so a subsequent ESC press could
+      // not abort the live tail.
+      start()
+    },
+    stop: () => {
+      ctrl.dispose()
+      stop()
+    },
+  }
+}
+
+function escHintLine(color: boolean): string {
+  const text = '(press esc to return to session list)'
+  return color ? `\u001b[2m${text}\u001b[0m` : text
+}
+
 function useColor(): boolean {
   if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '') return false
   if (process.env.FORCE_COLOR === '0') return false
@@ -111,8 +189,15 @@ function useColor(): boolean {
   return Boolean(process.stdout.isTTY)
 }
 
-async function clackSelect(sessions: SessionSummary[]): Promise<SessionSummary | null> {
+async function clackSelect(
+  sessions: SessionSummary[],
+  initialSessionId: string | undefined,
+): Promise<SessionSummary | null> {
   const { select } = await import('@clack/prompts')
+  const preferred =
+    initialSessionId !== undefined && sessions.some((s) => s.sessionId === initialSessionId)
+      ? initialSessionId
+      : sessions[0]?.sessionId
   const picked = await select<string>({
     message: `Pick a session to inspect (showing ${sessions.length})`,
     options: sessions.map((s) => ({
@@ -120,7 +205,7 @@ async function clackSelect(sessions: SessionSummary[]): Promise<SessionSummary |
       label: formatRowLabel(s),
       ...(s.firstPrompt !== null ? { hint: truncate(s.firstPrompt, 60) } : { hint: '(no prompt)' }),
     })),
-    initialValue: sessions[0]?.sessionId,
+    initialValue: preferred,
   })
   if (isCancel(picked)) {
     cancel('Cancelled.')

package/src/cli/role.ts

@@ -11,7 +11,7 @@ const claimSub = defineCommand({
   meta: {
     name: 'claim',
     description:
-      'claim a channel identity (Slack/Discord/etc.) for a role on this agent. Sends a code via the host CLI; you DM that code back to the bot to prove control of the channel account.',
+      'claim a channel identity (Slack/Discord/etc.) for a role on this agent. Sends a code via the host CLI; you send that code back to the bot from any chat (DM, group, channel) to prove control of the channel account. The resulting match rule grants the role to your author identity across every chat on that platform.',
   },
   args: {
     as: {
@@ -57,7 +57,7 @@ const claimSub = defineCommand({
         s.stop('Ready.')
         const expiresInSec = Math.max(0, Math.round((payload.expiresAt - Date.now()) / 1000))
         const lines = [
-          `Send this message to your bot as a DM:`,
+          `Send this message to your bot from any chat (DM, group, or channel):`,
           '',
           `  ${c.bold(payload.code)}`,
           '',

package/src/cli/run.ts

@@ -49,21 +49,40 @@ export const run = defineCommand({
       initialPrompt: args.prompt,
     })
 
-    const onSignal = () => {
-      stop()
-      process.exit(0)
+    const exit = (code: number): void => {
+      process.exit(code)
+    }
+    const onSignal = (): void => {
+      void shutdown({ stop, exit })
     }
     process.once('SIGINT', onSignal)
     process.once('SIGTERM', onSignal)
 
     if (tuiPromise) {
       await tuiPromise
-      stop()
-      process.exit(0)
+      await shutdown({ stop, exit })
     }
   },
 })
 
+// Awaits `stop()` BEFORE exiting so async teardown side-effects (channel
+// adapter teardown, in particular GitHub webhook deregistration) actually
+// complete. The previous code called `stop()` without awaiting and then
+// `process.exit(0)` synchronously, so the in-process DELETE /repos/.../hooks/
+// requests never went out and webhooks survived `typeclaw stop` (which
+// `docker stop`s the container → SIGTERM).
+export async function shutdown(deps: {
+  stop: () => void | Promise<void>
+  exit: (code: number) => void
+}): Promise<void> {
+  try {
+    await deps.stop()
+    deps.exit(0)
+  } catch {
+    deps.exit(1)
+  }
+}
+
 function resolveAttachTui({
   tui,
   noTui,

package/src/cli/tui.ts

@@ -25,16 +25,40 @@ export const tui = defineCommand({
     },
   },
   async run({ args }) {
-    const url = args.url ?? (await defaultUrl())
-    const tui = createTui({
-      url,
-      ...(args.prompt !== undefined ? { initialPrompt: args.prompt } : {}),
-      expectedVersion: CLI_VERSION,
-      onVersionMismatch: (info) => {
-        process.stderr.write(`${formatVersionMismatchWarning(info)}\n`)
-      },
-    })
-    await tui.run()
+    const resolveUrl: () => Promise<string> = args.url !== undefined ? async () => args.url as string : defaultUrl
+
+    let initialPrompt: string | undefined = args.prompt
+    let attempt = 0
+    const RECONNECT_MAX_ATTEMPTS = 30
+    const RECONNECT_BACKOFF_MS = 1_000
+
+    while (true) {
+      const url = await resolveUrl()
+      const tui = createTui({
+        url,
+        ...(initialPrompt !== undefined ? { initialPrompt } : {}),
+        expectedVersion: CLI_VERSION,
+        onVersionMismatch: (info) => {
+          process.stderr.write(`${formatVersionMismatchWarning(info)}\n`)
+        },
+      })
+      const outcome = await tui.run()
+      if (!outcome.lostConnection) return
+      // The TUI lost its WS post-handshake (container restart, network blip,
+      // hostd hiccup). Re-resolve the URL because the host port can change
+      // across container lifecycles (see resolveHostPort), then reconnect.
+      // The initial prompt is intentionally cleared after the first cycle:
+      // on a reconnect, the agent is resuming the same session — replaying
+      // the prompt would re-send it to the LLM.
+      initialPrompt = undefined
+      attempt += 1
+      if (attempt > RECONNECT_MAX_ATTEMPTS) {
+        console.error(errorLine(`disconnected; gave up after ${RECONNECT_MAX_ATTEMPTS} reconnect attempts`))
+        process.exit(1)
+      }
+      process.stderr.write(`reconnecting (attempt ${attempt}/${RECONNECT_MAX_ATTEMPTS})...\n`)
+      await new Promise((resolve) => setTimeout(resolve, RECONNECT_BACKOFF_MS))
+    }
   },
 })