typeclaw 0.25.0 → 0.27.0

package/src/cli/inspect.ts

@@ -2,7 +2,19 @@ import { defineCommand } from 'citty'
 
 import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
 import { findAgentDir } from '@/init'
-import { runInspectLoop, streamLive, type LiveSourceFactory, type SessionSummary } from '@/inspect'
+import {
+  listViewerItems,
+  openViewerItem,
+  parseDuration,
+  parseFilter,
+  resolveSession,
+  runInspectLoop,
+  runViewerLoop,
+  streamLive,
+  type LiveSourceFactory,
+  type SessionSummary,
+  type ViewerItem,
+} from '@/inspect'
 import { originLabel, shortSessionId } from '@/inspect/label'
 
 import { createTailScope } from './inspect-controller'
@@ -13,12 +25,12 @@ const ESC_DEBOUNCE_MS = 50
 export const inspectCommand = defineCommand({
   meta: {
     name: 'inspect',
-    description: 'observe a session: replay the transcript, then tail live activity (host stage)',
+    description: 'session viewer: pick a session, the live TUI, or container logs to observe (host stage)',
   },
   args: {
     session: {
       type: 'positional',
-      description: 'session id or short prefix (omit to pick from a list)',
+      description: 'session id or short prefix (omit to pick from the list)',
       required: false,
     },
     filter: {
@@ -42,42 +54,175 @@ 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 isJson = args.json === true
-    const liveSource = isJson ? undefined : await buildLiveSource(cwd)
-    const interactive = !isJson && Boolean(process.stdin.isTTY)
-    const liveHint = interactive ? escHintLine(color) : undefined
-
-    const result = await runInspectLoop({
-      agentDir: cwd,
-      ...(sessionArg !== undefined ? { sessionIdOrPrefix: sessionArg } : {}),
-      ...(filterArg !== undefined ? { filter: filterArg } : {}),
-      ...(sinceArg !== undefined ? { since: sinceArg } : {}),
-      json: isJson,
-      color,
-      selectSession: (sessions, selectOpts) => clackSelect(sessions, selectOpts?.initialSessionId),
-      ...(liveSource !== undefined ? { liveSource } : {}),
-      createTailScope: () => createTailScope({ debounceMs: ESC_DEBOUNCE_MS }),
-      ...(interactive ? { interactive: true } : {}),
-      ...(liveHint !== undefined ? { liveHint } : {}),
-      stdout: (line) => process.stdout.write(`${line}\n`),
-      stderr: (line) => process.stderr.write(`${line}\n`),
-    })
 
-    if (!result.ok) {
-      process.stderr.write(`${errorLine(result.reason)}\n`)
-      process.exit(result.exitCode)
+    // JSON mode stays the scriptable, session-only path: no list, no logs/tui
+    // rows, explicit session id required. Behavior is unchanged from before the
+    // viewer merge.
+    if (isJson) {
+      const result = await runInspectLoop({
+        agentDir: cwd,
+        ...(sessionArg !== undefined ? { sessionIdOrPrefix: sessionArg } : {}),
+        ...(filterArg !== undefined ? { filter: filterArg } : {}),
+        ...(sinceArg !== undefined ? { since: sinceArg } : {}),
+        json: true,
+        color,
+        selectSession: (sessions, selectOpts) => clackSelectSession(sessions, selectOpts?.initialSessionId),
+        createTailScope: () => createTailScope({ debounceMs: ESC_DEBOUNCE_MS }),
+        stdout: (line) => process.stdout.write(`${line}\n`),
+        stderr: (line) => process.stderr.write(`${line}\n`),
+      })
+      finish(result)
+      return
     }
-    process.exit(result.exitCode)
+
+    const exitCode = await runInspectViewer({
+      cwd,
+      ...(sessionArg !== undefined ? { sessionArg } : {}),
+      ...(filterArg !== undefined ? { filterArg } : {}),
+      ...(sinceArg !== undefined ? { sinceArg } : {}),
+      color,
+    })
+    process.exit(exitCode)
   },
 })
 
-async function buildLiveSource(cwd: string): Promise<LiveSourceFactory | undefined> {
-  const precheck = await requireContainerRunning({ cwd })
-  if (!precheck.ok) {
-    process.stderr.write(`${c.yellow('⚠')} ${precheck.reason}; tailing live events disabled\n`)
-    return undefined
+export type RunInspectViewerOptions = {
+  cwd: string
+  sessionArg?: string
+  filterArg?: string
+  sinceArg?: string
+  color?: boolean
+  // Set false by the `tui` detach handoff: the live session was just ended, so
+  // no row should be offered as writable (see listViewerItems).
+  allowWritable?: boolean
+}
+
+// The interactive session-viewer: list → open → back to list. Shared by the
+// `inspect` command and `tui`'s esc-detach fallthrough. Returns an exit code
+// instead of calling process.exit so callers can chain (e.g. tui drops here).
+export async function runInspectViewer(opts: RunInspectViewerOptions): Promise<number> {
+  const { cwd } = opts
+  const color = opts.color ?? useColor()
+
+  const filterResult = parseFilter(opts.filterArg)
+  if (!filterResult.ok) {
+    process.stderr.write(`${errorLine(filterResult.reason)}\n`)
+    return 2
+  }
+  let sinceMs: number | undefined
+  if (opts.sinceArg !== undefined) {
+    const d = parseDuration(opts.sinceArg)
+    if (!d.ok) {
+      process.stderr.write(`${errorLine(d.reason)}\n`)
+      return 2
+    }
+    sinceMs = Date.now() - d.ms
+  }
+
+  const containerRunning = (await requireContainerRunning({ cwd })).ok
+  if (!containerRunning) {
+    process.stderr.write(`${c.yellow('⚠')} container not running; showing read-only history and logs only\n`)
+  }
+
+  const sessionsDir = `${cwd}/sessions`
+
+  // Resolve a session arg (id or short prefix) to a full session id BEFORE the
+  // loop: runViewerLoop matches preselectKey against exact itemKeys, so a bare
+  // prefix would otherwise miss every row and report "no sessions". 'logs' is a
+  // reserved key, not a session, so it bypasses resolution.
+  let preselectKey: string | undefined
+  if (opts.sessionArg !== undefined && opts.sessionArg !== 'logs') {
+    const resolved = await resolveSession(sessionsDir, opts.sessionArg, (l) => process.stderr.write(`${l}\n`))
+    if (!resolved.ok) {
+      const reason =
+        resolved.reason === 'ambiguous'
+          ? `Ambiguous session prefix "${opts.sessionArg}" matches ${resolved.matches.length} sessions. Use a longer prefix or run \`typeclaw inspect\` without args.`
+          : `No session matching "${opts.sessionArg}" in ${sessionsDir}/`
+      process.stderr.write(`${errorLine(reason)}\n`)
+      return resolved.reason === 'ambiguous' ? 2 : 1
+    }
+    preselectKey = resolved.summary.sessionId
+  } else if (opts.sessionArg === 'logs') {
+    preselectKey = 'logs'
+  }
+
+  const interactive = Boolean(process.stdin.isTTY)
+  const liveHint = interactive ? escHintLine(color) : undefined
+  const liveSource = containerRunning ? await buildLiveSource(cwd) : undefined
+
+  const stdout = (line: string): void => {
+    process.stdout.write(`${line}\n`)
+  }
+  const stderr = (line: string): void => {
+    process.stderr.write(`${line}\n`)
+  }
+
+  const open = openViewerItem({
+    cwd,
+    filter: filterResult.filter,
+    sinceMs,
+    json: false,
+    color,
+    interactive,
+    stdout,
+    stderr,
+    resolveTuiUrl: () => resolveTuiUrl(cwd),
+    ...(liveSource !== undefined ? { liveSource } : {}),
+    ...(liveHint !== undefined ? { liveHint } : {}),
+  })
+
+  const cliAllowWritable = opts.allowWritable !== false
+  const result = await runViewerLoop<ViewerItem>({
+    listItems: async ({ allowWritable: loopAllowWritable }) => {
+      const listOpts: Parameters<typeof listViewerItems>[0] = {
+        sessionsDir,
+        containerRunning,
+        // Compose the CLI-level permission (false on tui detach handoff) with
+        // the loop-level one (false after returning to the picker from a viewer).
+        allowWritable: cliAllowWritable && loopAllowWritable,
+        limit: 20,
+        onWarn: stderr,
+      }
+      if (sinceMs !== undefined) listOpts.sinceMs = sinceMs
+      return (await listViewerItems(listOpts)).items
+    },
+    keyOf: (item) => (item.kind === 'logs' ? 'logs' : item.summary.sessionId),
+    ...(preselectKey !== undefined ? { preselectKey } : {}),
+    selectItem: (items, selectOpts) => clackSelectItem(items, selectOpts.initialKey),
+    openItem: open,
+    createTailScope: () => createTailScope({ debounceMs: ESC_DEBOUNCE_MS }),
+    onEmpty: () => ({
+      ok: false,
+      exitCode: 1,
+      reason: `No sessions found in ${sessionsDir}/.\nStart a session with \`typeclaw tui\` or send a message from a configured channel.`,
+    }),
+  })
+
+  if (!result.ok && result.reason !== undefined) {
+    process.stderr.write(`${errorLine(result.reason)}\n`)
+  }
+  return result.exitCode
+}
+
+function finish(result: { ok: boolean; exitCode: number; reason?: string }): void {
+  if (!result.ok && result.reason !== undefined) {
+    process.stderr.write(`${errorLine(result.reason)}\n`)
   }
+  process.exit(result.exitCode)
+}
+
+async function resolveTuiUrl(cwd: string): Promise<string> {
+  const precheck = await requireContainerRunning({ cwd })
+  if (!precheck.ok) throw new Error(precheck.reason)
+  const port = await resolveHostPort({ cwd })
+  const token = await resolveTuiToken({ cwd })
+  const url = new URL(`ws://127.0.0.1:${port}`)
+  if (token !== null) url.searchParams.set('token', token)
+  return url.toString()
+}
+
+async function buildLiveSource(cwd: string): Promise<LiveSourceFactory | undefined> {
   const port = await resolveHostPort({ cwd })
   const token = await resolveTuiToken({ cwd })
   const baseUrl = new URL(`ws://127.0.0.1:${port}/inspect`)
@@ -94,7 +239,7 @@ async function buildLiveSource(cwd: string): Promise<LiveSourceFactory | undefin
 }
 
 function escHintLine(color: boolean): string {
-  const text = '(esc to return to session list · q to quit)'
+  const text = '(esc to return to the list · q to quit)'
   return color ? `\u001b[2m${text}\u001b[0m` : text
 }
 
@@ -105,7 +250,29 @@ function useColor(): boolean {
   return Boolean(process.stdout.isTTY)
 }
 
-async function clackSelect(
+async function clackSelectItem(items: ViewerItem[], initialKey: string | undefined): Promise<ViewerItem | null> {
+  const { select } = await import('@clack/prompts')
+  prepareStdinForClack()
+  const keyOf = (item: ViewerItem): string => (item.kind === 'logs' ? 'logs' : item.summary.sessionId)
+  const preferred =
+    initialKey !== undefined && items.some((i) => keyOf(i) === initialKey) ? initialKey : keyOf(items[0]!)
+  const picked = await select<string>({
+    message: `Pick what to view (showing ${items.length})`,
+    options: items.map((item) => ({
+      value: keyOf(item),
+      label: itemLabel(item),
+      ...itemHint(item),
+    })),
+    initialValue: preferred,
+  })
+  if (isCancel(picked)) {
+    cancel('Cancelled.')
+    return null
+  }
+  return items.find((i) => keyOf(i) === picked) ?? null
+}
+
+async function clackSelectSession(
   sessions: SessionSummary[],
   initialSessionId: string | undefined,
 ): Promise<SessionSummary | null> {
@@ -119,7 +286,7 @@ async function clackSelect(
     message: `Pick a session to inspect (showing ${sessions.length})`,
     options: sessions.map((s) => ({
       value: s.sessionId,
-      label: formatRowLabel(s),
+      label: sessionRowLabel(s),
       ...(s.firstPrompt !== null ? { hint: truncate(s.firstPrompt, 60) } : { hint: '(no prompt)' }),
     })),
     initialValue: preferred,
@@ -131,7 +298,20 @@ async function clackSelect(
   return sessions.find((s) => s.sessionId === picked) ?? null
 }
 
-function formatRowLabel(s: SessionSummary): string {
+function itemLabel(item: ViewerItem): string {
+  if (item.kind === 'logs') return `${c.dim('▤')} container logs`
+  if (item.kind === 'tui') return `${c.green('●')} ${c.bold('live TUI')}  ${sessionRowLabel(item.summary)}`
+  return `${c.dim('○')} ${sessionRowLabel(item.summary)}`
+}
+
+function itemHint(item: ViewerItem): { hint: string } {
+  if (item.kind === 'logs') return { hint: 'read-only · works offline' }
+  if (item.kind === 'tui') return { hint: 'read+write · esc detaches and ends the live session' }
+  if (item.summary.firstPrompt !== null) return { hint: truncate(item.summary.firstPrompt, 60) }
+  return { hint: '(no prompt)' }
+}
+
+function sessionRowLabel(s: SessionSummary): string {
   const id = shortSessionId(s.sessionId)
   const label = s.origin === null ? '(unknown origin)' : originLabel(s.origin)
   const when = formatRelative(s.mtimeMs)

package/src/cli/logs.ts

@@ -3,6 +3,7 @@ import { defineCommand } from 'citty'
 import { logs, parseTailValue } from '@/container'
 import { findAgentDir } from '@/init'
 
+import { runInspectViewer } from './inspect'
 import { c, errorLine } from './ui'
 
 export const logsCommand = defineCommand({
@@ -22,6 +23,11 @@ export const logsCommand = defineCommand({
       alias: 'n',
       description: 'number of lines to show from the end of the logs (non-negative integer or "all")',
     },
+    list: {
+      type: 'boolean',
+      description: 'open the session viewer on the logs entry instead of dumping logs',
+      default: false,
+    },
   },
   async run({ args }) {
     const cwd = findAgentDir(process.cwd()) ?? process.cwd()
@@ -36,6 +42,15 @@ export const logsCommand = defineCommand({
       tail = parsed.value
     }
 
+    // The viewer is strictly opt-in via --list, so the default `typeclaw logs`
+    // (piped, redirected, -f, or a plain TTY dump) keeps the raw `docker logs`
+    // pump that `typeclaw logs | grep` and CI depend on. --list drops into the
+    // session viewer pre-opened on the logs entry, where esc returns to the list.
+    if (args.list) {
+      const exitCode = await runInspectViewer({ cwd, sessionArg: 'logs' })
+      process.exit(exitCode)
+    }
+
     if (args.follow) {
       console.log(c.cyan('Streaming container logs...'))
     } else {

package/src/cli/tui.ts

@@ -3,14 +3,16 @@ import { defineCommand } from 'citty'
 import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
 import { findAgentDir } from '@/init'
 import { CLI_VERSION } from '@/init/cli-version'
-import { createTui, formatVersionMismatchWarning } from '@/tui'
+import { runTuiViewer } from '@/inspect'
+import { formatVersionMismatchWarning } from '@/tui'
 
+import { runInspectViewer } from './inspect'
 import { errorLine } from './ui'
 
 export const tui = defineCommand({
   meta: {
     name: 'tui',
-    description: 'start the tui client',
+    description: 'open the live agent session in the read+write viewer (host stage)',
   },
   args: {
     prompt: {
@@ -25,50 +27,42 @@ export const tui = defineCommand({
     },
   },
   async run({ args }) {
-    const resolveUrl: () => Promise<string> = args.url !== undefined ? async () => args.url as string : defaultUrl
+    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    const resolveUrl: () => Promise<string> =
+      args.url !== undefined ? async () => args.url as string : () => defaultUrl(cwd)
 
-    let initialPrompt: string | undefined = args.prompt
-    let attempt = 0
-    const RECONNECT_MAX_ATTEMPTS = 30
-    const RECONNECT_BACKOFF_MS = 1_000
+    const result = await runTuiViewer({
+      resolveUrl,
+      ...(args.prompt !== undefined ? { initialPrompt: args.prompt } : {}),
+      expectedVersion: CLI_VERSION,
+      onVersionMismatch: (info) => {
+        process.stderr.write(`${formatVersionMismatchWarning(info)}\n`)
+      },
+      stderr: (line) => process.stderr.write(`${line}\n`),
+    })
 
-    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))
+    // Esc detached from the live session: drop into the viewer list so the user
+    // can pick another session or the container logs — `tui` is just a deep-link
+    // into the session viewer, pre-opened on the live session. allowWritable
+    // is false because detaching ended the live session, so no row may be
+    // offered as a writable "live TUI" anymore.
+    if (result.ok && result.escToPicker === true) {
+      const viewerExit = await runInspectViewer({ cwd, allowWritable: false })
+      process.exit(viewerExit)
+      return
     }
+
+    if (!result.ok) {
+      process.stderr.write(`${errorLine(result.reason)}\n`)
+      process.exit(result.exitCode)
+    }
+    process.exit(result.exitCode)
   },
 })
 
-async function defaultUrl(): Promise<string> {
-  const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+async function defaultUrl(cwd: string): Promise<string> {
   const precheck = await requireContainerRunning({ cwd })
-  if (!precheck.ok) {
-    console.error(errorLine(precheck.reason))
-    process.exit(1)
-  }
+  if (!precheck.ok) throw new Error(precheck.reason)
   const port = await resolveHostPort({ cwd })
   const token = await resolveTuiToken({ cwd })
   const url = new URL(`ws://127.0.0.1:${port}`)

package/src/compose/logs.ts

@@ -100,7 +100,7 @@ export async function composeLogs({
       follow,
       ...(tail !== undefined ? { tail } : {}),
     })
-    const proc = bun.spawn({ cmd, stdout: 'pipe', stderr: 'pipe' })
+    const proc = bun.spawn({ cmd, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' })
     return { agent, proc }
   })
 

package/src/config/config.ts

@@ -5,7 +5,7 @@ import { isAbsolute, join, resolve } from 'node:path'
 import type { Model } from '@mariozechner/pi-ai'
 import { z } from 'zod'
 
-import { channelsSchema } from '@/channels/schema'
+import { channelsSchema, SEEDED_GITHUB_EVENT_ALLOWLISTS } from '@/channels/schema'
 import { commitSystemFileSync } from '@/git/system-commit'
 import { rolesConfigSchema } from '@/permissions/schema'
 import { secretFieldSchema } from '@/secrets/resolve'
@@ -810,6 +810,7 @@ export type MigrationStep =
   | { kind: 'strip-permissions-gate-channel-respond' }
   | { kind: 'model-to-models'; ref: string }
   | { kind: 'drop-stale-model'; ref: string }
+  | { kind: 'drop-github-seeded-event-allowlist' }
 
 export type MigrationResult = { json: unknown; changed: boolean; applied: MigrationStep[] }
 
@@ -830,13 +831,15 @@ export function migrateLegacyConfigShape(json: unknown): MigrationResult {
   // silently — same precedence rule as the dockerfile/gitignore migrations.
   const hasLegacyModel = 'model' in obj && !('models' in obj) && typeof obj.model === 'string'
   const hasStaleModelAlongsideModels = 'model' in obj && 'models' in obj
+  const hasSeededGithubEventAllowlist = isSeededGithubEventAllowlist(obj)
   if (
     !hasLegacyDockerfile &&
     !hasLegacyGitignore &&
     !channelsAllowMigration.found &&
     !hasLegacyGateChannelRespond &&
     !hasLegacyModel &&
-    !hasStaleModelAlongsideModels
+    !hasStaleModelAlongsideModels &&
+    !hasSeededGithubEventAllowlist
   ) {
     return { json, changed: false, applied: [] }
   }
@@ -897,9 +900,43 @@ export function migrateLegacyConfigShape(json: unknown): MigrationResult {
     delete next.model
     applied.push({ kind: 'drop-stale-model', ref })
   }
+  if (hasSeededGithubEventAllowlist) {
+    dropSeededGithubEventAllowlist(next)
+    applied.push({ kind: 'drop-github-seeded-event-allowlist' })
+  }
   return { json: next, changed: true, applied }
 }
 
+// True when channels.github.eventAllowlist deep-equals an allowlist that
+// `channel add` / `init` has previously seeded verbatim. Such a value is
+// indistinguishable from "the default at that time", so stripping it lets the
+// config re-track the shipped default. A user who hand-edited to any other set
+// (added/removed/reordered an event) fails this check and is preserved.
+function isSeededGithubEventAllowlist(obj: Record<string, unknown>): boolean {
+  const github = isPlainObject(obj.channels) ? obj.channels.github : undefined
+  if (!isPlainObject(github)) return false
+  const list = github.eventAllowlist
+  if (!Array.isArray(list)) return false
+  return SEEDED_GITHUB_EVENT_ALLOWLISTS.some((seeded) => arraysEqual(list, seeded))
+}
+
+function dropSeededGithubEventAllowlist(next: Record<string, unknown>): void {
+  const channels = next.channels
+  if (!isPlainObject(channels)) return
+  const github = channels.github
+  if (!isPlainObject(github)) return
+  const { eventAllowlist: _dropped, ...rest } = github
+  next.channels = { ...channels, github: rest }
+}
+
+function arraysEqual(a: readonly unknown[], b: readonly unknown[]): boolean {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false
+  }
+  return true
+}
+
 // Builds a meaningful one-line git commit subject for a typeclaw.json
 // migration. Single-step migrations get a specific subject; multi-step ones
 // fall back to a stable summary subject with the count. The body (after the
@@ -949,6 +986,8 @@ function shortStepLabel(step: MigrationStep): string {
       return 'lift model → models.default'
     case 'drop-stale-model':
       return 'drop stale legacy model alongside models'
+    case 'drop-github-seeded-event-allowlist':
+      return 'drop seeded channels.github.eventAllowlist'
   }
 }
 
@@ -972,6 +1011,8 @@ function describeStep(step: MigrationStep): string {
       return step.ref !== ''
         ? `drop stale top-level model (${step.ref}) — models block takes precedence`
         : 'drop stale top-level model — models block takes precedence'
+    case 'drop-github-seeded-event-allowlist':
+      return 'drop seeded channels.github.eventAllowlist so it re-tracks the shipped default'
   }
 }