typeclaw 0.26.0 → 0.27.0

package/src/inspect/session-list.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path'
 
 import type { MinimalSessionOrigin } from '@/agent/session-meta'
 
+import { previewForHint } from './preview'
 import { replayJsonl } from './replay'
 
 export type SessionSummary = {
@@ -139,18 +140,29 @@ async function peekSession(
   onWarn?: (msg: string) => void,
 ): Promise<{ origin: MinimalSessionOrigin | null; firstPrompt: string | null }> {
   let origin: MinimalSessionOrigin | null = null
-  let firstPrompt: string | null = null
+  const userTexts: string[] = []
   let bytesRead = 0
   for await (const event of replayJsonl(path, onWarn !== undefined ? { onWarn } : {})) {
     if (event.cat === 'meta' && origin === null) origin = event.origin
-    if (event.cat === 'user' && firstPrompt === null) firstPrompt = event.text
-    if (origin !== null && firstPrompt !== null) break
+    if (event.cat === 'user' && userTexts.length < MAX_PREVIEW_CANDIDATES) userTexts.push(event.text)
+    if (origin !== null && userTexts.length >= MAX_PREVIEW_CANDIDATES) break
     bytesRead += approximateSize(event)
     if (bytesRead > PREVIEW_MAX_BYTES) break
   }
+  // Resolve the hint after the loop so origin (which selects the extraction
+  // strategy) is known even if a user event precedes the meta event. A turn
+  // that is pure injected preamble yields null, so fall through to the next user
+  // turn for a useful glance.
+  let firstPrompt: string | null = null
+  for (const text of userTexts) {
+    firstPrompt = previewForHint(origin, text)
+    if (firstPrompt !== null) break
+  }
   return { origin, firstPrompt }
 }
 
+const MAX_PREVIEW_CANDIDATES = 5
+
 function approximateSize(event: { ts: number }): number {
   return JSON.stringify(event).length
 }

package/src/inspect/transcript-view.ts

@@ -0,0 +1,182 @@
+import {
+  Key,
+  Markdown,
+  matchesKey,
+  ProcessTerminal,
+  type Component,
+  type Terminal,
+  Text,
+  TUI,
+} from '@mariozechner/pi-tui'
+
+import { formatToolEnd, formatToolStart, formatUserPromptHistory } from '@/tui/format'
+import { colors, markdownTheme } from '@/tui/theme'
+
+import { streamSessionEvents, type LiveSourceFactory, type StreamPhase } from './index'
+import { originLabel, shortSessionId } from './label'
+import type { SessionSummary } from './session-list'
+import type { InspectEvent, InspectFilter } from './types'
+
+export type TranscriptViewOutcome = { reason: 'back' | 'exit' }
+
+export type TranscriptViewOptions = {
+  summary: SessionSummary
+  filter: InspectFilter
+  sinceMs: number | undefined
+  liveSource?: LiveSourceFactory
+  createTerminal?: () => Terminal
+}
+
+// Read-only pi-tui transcript viewer: the rich counterpart to the line
+// renderer, matching the live TUI's look (markdown assistant blocks, formatted
+// tool panels) but with NO editor and NO websocket writes. It owns its own
+// raw-mode terminal, so the caller must NOT wrap it in a tail scope (a second
+// raw-stdin owner would corrupt input — same rule as the writable tui branch).
+// esc -> back to the list; q / ctrl-c -> exit.
+export function createTranscriptView(opts: TranscriptViewOptions) {
+  async function run(): Promise<TranscriptViewOutcome> {
+    const terminal = (opts.createTerminal ?? (() => new ProcessTerminal()))()
+    const tui = new TUI(terminal)
+
+    const status = new Text(statusLine('replay'), 0, 0)
+    tui.addChild(new Text(header(opts.summary), 0, 0))
+    tui.addChild(status)
+    tui.start()
+    tui.requestRender()
+
+    // The status line is pinned last (no editor to pin, unlike createTui). Each
+    // appended history entry is inserted before it: strip status, add entry,
+    // re-add status.
+    const append = (component: Component): void => {
+      tui.removeChild(status)
+      tui.addChild(component)
+      tui.addChild(status)
+    }
+
+    let settle: ((o: TranscriptViewOutcome) => void) | null = null
+    const outcome = new Promise<TranscriptViewOutcome>((resolve) => {
+      settle = resolve
+    })
+    const finish = (reason: TranscriptViewOutcome['reason']): void => {
+      if (settle === null) return
+      const fn = settle
+      settle = null
+      tui.stop()
+      fn({ reason })
+    }
+
+    tui.addInputListener((data) => {
+      if (matchesKey(data, Key.ctrl('c')) || data === 'q') {
+        finish('exit')
+        return { consume: true }
+      }
+      if (matchesKey(data, Key.escape)) {
+        finish('back')
+        return { consume: true }
+      }
+      return undefined
+    })
+
+    const abort = new AbortController()
+    // Drive the shared read pipeline into the component tree. Batch renders
+    // during replay (one render at replay-end) to avoid redraw storms on long
+    // transcripts; render per event once live.
+    let live = false
+    const onEvent = (event: InspectEvent): void => {
+      append(componentFor(event))
+      if (live) tui.requestRender()
+    }
+    const onPhase = (phase: StreamPhase): void => {
+      if (phase.phase === 'replay-end') {
+        tui.requestRender()
+      } else if (phase.phase === 'live-start') {
+        append(new Text(divider(phase.sessionLive ? 'live' : 'live (broadcasts only)'), 0, 0))
+        live = true
+        tui.requestRender()
+      }
+    }
+
+    const pump = streamSessionEvents({
+      summary: opts.summary,
+      filter: opts.filter,
+      sinceMs: opts.sinceMs,
+      onEvent,
+      onPhase,
+      signal: abort.signal,
+      ...(opts.liveSource !== undefined ? { liveSource: opts.liveSource } : {}),
+      blockWhenReplayOnly: true,
+    })
+
+    const result = await outcome
+    // The viewer was dismissed: stop the pipeline (replay-only idle wait, or a
+    // live tail) so it does not run past the closed terminal.
+    abort.abort()
+    await pump.catch(() => {})
+    return result
+  }
+
+  return { run }
+}
+
+export function componentFor(event: InspectEvent): Component {
+  switch (event.cat) {
+    case 'assistant':
+      return new Markdown(event.text, 0, 0, markdownTheme)
+    case 'user':
+      return new Text(formatUserPromptHistory(event.text), 0, 0)
+    case 'tool':
+      return new Text(
+        event.phase === 'start'
+          ? formatToolStart(event.name, event.args)
+          : formatToolEnd(event.name, event.isError === true, event.result, event.durationMs ?? 0),
+        0,
+        0,
+      )
+    case 'thinking':
+      return new Text(colors.gray(event.redacted === true ? '[redacted thinking]' : event.text), 0, 0)
+    case 'meta':
+      return new Text(colors.dim(`origin: ${originLabel(event.origin)}`), 0, 0)
+    case 'error':
+      return new Text(
+        event.stopReason === 'aborted' ? colors.yellow(event.message) : colors.red(`error: ${event.message}`),
+        0,
+        0,
+      )
+    case 'done':
+      return new Text(colors.dim(doneSummary(event)), 0, 0)
+    case 'broadcast':
+      return new Text(colors.dim(`broadcast: ${compact(event.payload)}`), 0, 0)
+    case 'cron-fire':
+      return new Text(colors.dim(`cron ${event.jobId} fired`), 0, 0)
+    case 'inbound':
+      return new Text(colors.cyan(`[${event.decision}] ${event.authorName}: ${event.text}`), 0, 0)
+  }
+}
+
+function doneSummary(event: Extract<InspectEvent, { cat: 'done' }>): string {
+  const parts = [`${event.input} in / ${event.output} out tok`, `$${event.cost.toFixed(4)}`]
+  if (event.stopReason !== undefined) parts.push(`stop=${event.stopReason}`)
+  return parts.join(' · ')
+}
+
+function compact(payload: unknown): string {
+  if (payload !== null && typeof payload === 'object' && 'kind' in payload) {
+    return String((payload as { kind: unknown }).kind)
+  }
+  const s = JSON.stringify(payload) ?? String(payload)
+  return s.length > 200 ? `${s.slice(0, 200)}…` : s
+}
+
+function header(summary: SessionSummary): string {
+  const id = shortSessionId(summary.sessionId)
+  const label = summary.origin === null ? '(unknown origin)' : originLabel(summary.origin)
+  return colors.dim(`─── ${id} · ${label} ───`)
+}
+
+function statusLine(_phase: 'replay'): string {
+  return colors.dim('── read-only · esc to return to list · q to quit ──')
+}
+
+function divider(text: string): string {
+  return colors.dim(`─── ${text} ───`)
+}

package/src/inspect/tui-item.ts

@@ -0,0 +1,97 @@
+import { createTui, type TuiRunResult } from '@/tui'
+
+import type { RunInspectResult } from './index'
+
+export type TuiRunner = (opts: {
+  url: string
+  initialPrompt?: string
+  expectedVersion?: string
+  onVersionMismatch?: (info: { expected: string; actual: string }) => void
+}) => Promise<TuiRunResult>
+
+export type RunTuiViewerOptions = {
+  resolveUrl: () => Promise<string>
+  initialPrompt?: string
+  expectedVersion?: string
+  onVersionMismatch?: (info: { expected: string; actual: string }) => void
+  stderr: (line: string) => void
+  runTui?: TuiRunner
+  reconnectMaxAttempts?: number
+  reconnectBackoffMs?: number
+  sleep?: (ms: number) => Promise<void>
+}
+
+const DEFAULT_RECONNECT_MAX_ATTEMPTS = 30
+const DEFAULT_RECONNECT_BACKOFF_MS = 1_000
+
+// The interactive read+write viewer branch. Unlike session/logs, this does NOT
+// run under the loop's tail scope: createTui owns its own raw-mode pi-tui
+// terminal and esc/ctrl-c handling, so a second raw-stdin owner would corrupt
+// input. The branch maps createTui's outcome into the loop's result contract:
+// detach → back to the list (escToPicker), exit → terminate, lostConnection →
+// reconnect (the self-restart case), connectFailed → error result.
+export async function runTuiViewer(opts: RunTuiViewerOptions): Promise<RunInspectResult> {
+  const runTui = opts.runTui ?? defaultRunTui
+  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)))
+  const maxAttempts = opts.reconnectMaxAttempts ?? DEFAULT_RECONNECT_MAX_ATTEMPTS
+  const backoffMs = opts.reconnectBackoffMs ?? DEFAULT_RECONNECT_BACKOFF_MS
+
+  let initialPrompt = opts.initialPrompt
+  let attempt = 0
+
+  while (true) {
+    let url: string
+    try {
+      url = await opts.resolveUrl()
+    } catch (err) {
+      return { ok: false, exitCode: 1, reason: errorMessage(err) }
+    }
+
+    let result: TuiRunResult
+    try {
+      result = await runTui({
+        url,
+        ...(initialPrompt !== undefined ? { initialPrompt } : {}),
+        ...(opts.expectedVersion !== undefined ? { expectedVersion: opts.expectedVersion } : {}),
+        ...(opts.onVersionMismatch !== undefined ? { onVersionMismatch: opts.onVersionMismatch } : {}),
+      })
+    } catch (err) {
+      return { ok: false, exitCode: 1, reason: errorMessage(err) }
+    }
+
+    if (result.reason === 'detach') return { ok: true, exitCode: 0, escToPicker: true }
+    if (result.reason === 'exit') return { ok: true, exitCode: result.exitCode }
+    if (result.reason === 'connectFailed') return { ok: false, exitCode: 1, reason: 'connection failed' }
+
+    // lostConnection: the WS dropped post-handshake (self-restart, network
+    // blip). Re-resolve the URL because the host port can change across
+    // container lifecycles, then reconnect. Clear the initial prompt so a
+    // reconnect resuming the same session does not re-send it to the LLM.
+    initialPrompt = undefined
+    attempt += 1
+    if (attempt > maxAttempts) {
+      return { ok: false, exitCode: 1, reason: `disconnected; gave up after ${maxAttempts} reconnect attempts` }
+    }
+    opts.stderr(`reconnecting (attempt ${attempt}/${maxAttempts})...`)
+    await sleep(backoffMs)
+  }
+}
+
+function defaultRunTui(opts: {
+  url: string
+  initialPrompt?: string
+  expectedVersion?: string
+  onVersionMismatch?: (info: { expected: string; actual: string }) => void
+}): Promise<TuiRunResult> {
+  return createTui({
+    url: opts.url,
+    exit: () => {},
+    ...(opts.initialPrompt !== undefined ? { initialPrompt: opts.initialPrompt } : {}),
+    ...(opts.expectedVersion !== undefined ? { expectedVersion: opts.expectedVersion } : {}),
+    ...(opts.onVersionMismatch !== undefined ? { onVersionMismatch: opts.onVersionMismatch } : {}),
+  }).run()
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}

package/src/skills/typeclaw-channel-github/SKILL.md

@@ -20,7 +20,7 @@ Before you pick an action, classify the inbound. Skipping this step is how a PR
 
 1. **Is this a PR, and do I have an unresolved blocking obligation on it?** On any `pr:N` inbound, before anything else, check whether you owe this PR a verdict you have not yet landed. Check **both** signals below — checking only formal review state misses the very failure this gate exists to catch, because a prior block may never have become formal state:
    - **Formal review state.** Run the step-1 re-review query in the PR review flow (`gh api --paginate --slurp /repos/owner/repo/pulls/<N>/reviews --jq '…'` filtered to `{CHANGES_REQUESTED, APPROVED}`). If your latest **blocking decision** is `CHANGES_REQUESTED`, you have a live sticky block.
-   - **Flat-comment blockers you authored.** A prior "request changes" may have been posted as a plain PR/issue comment instead of a formal review — in which case **no `CHANGES_REQUESTED` row exists** and the query above returns empty even though you blocked the PR in prose. So also scan your own recent comments (`gh api /repos/owner/repo/issues/<N>/comments --jq '[.[] | select(.user.login == "<your-login>")]'`) for one that requested changes / raised blockers and has not since been superseded by a formal review or a clear retraction. For routing, a blocking comment you wrote is as binding as a formal `CHANGES_REQUESTED`.
+   - **Flat-comment blockers you authored.** A prior "request changes" may have been posted as a plain PR/issue comment instead of a formal review — in which case **no `CHANGES_REQUESTED` row exists** and the query above returns empty even though you blocked the PR in prose. So also scan your own recent comments (`gh api /repos/owner/repo/issues/<N>/comments --jq '[.[] | select(.user.login == "<your-login>")]'`) for one that requested changes / raised blockers and has not since been superseded by a formal review or a clear retraction. For routing, a blocking comment you wrote is as binding as a formal `CHANGES_REQUESTED`. **A courtesy acknowledgement is not a retraction.** A reply you posted like "nice, that closes the hole" / "thanks, looks good" / "✅" does **not** supersede or retract a blocker you raised — it is a chat ack, not a verdict, and it carries no review state. The blocker stays binding until you land a **formal** `APPROVE`/`REQUEST_CHANGES` (or dismiss your prior review). So when an earlier "✅ thanks" of yours is the only thing between your blocker and the author's address-comment, the blocker is **still live** and this inbound is a re-review — do not let your own ack downgrade it.
 
    If **either** signal shows an unresolved blocker you raised, this inbound is a **re-review** — go to the **PR review flow** regardless of how it is phrased. An author commenting "fixed both issues" / "addressed your feedback" / "pushed a fix" is a re-review trigger, **not** a thread-resolve trigger. A re-review is closed by re-deciding the verdict and landing a **formal** review via `POST /pulls/<N>/reviews`: `APPROVE` clears a sticky `CHANGES_REQUESTED`; a comment or a flat reply clears neither a formal block nor a flat-comment blocker — it just strands the verdict again, which is the original bug.
 
@@ -201,6 +201,8 @@ A review you posted leaves inline comment threads open on the PR. When one of **
 
 **The base principle: whoever opened the thread closes it.** Resolve only threads whose root comment **you** authored. Never resolve a human reviewer's thread on your behalf — that erases their open question. The thread you can resolve is the one you started; the inbound that brings you here is a **review-thread reply on `pr:N` with `thread` set**, replying inside a thread you opened.
 
+> **Thread cleanup is not the same as discharging a PR-level block.** Resolving an inline thread closes that one thread; it carries **no** review state and does **not** clear a PR-level blocking obligation (a sticky `CHANGES_REQUESTED`, or a flat blocker you authored on the PR conversation). Those are two separate duties. If triage #1 found a live PR-level block, that inbound is a **re-review** and the PR review flow wins over this section — you owe a formal `APPROVE`/`REQUEST_CHANGES`, and resolving threads (or a chat ✅) must **not** be your final response. Reach this section only for a thread-scoped reply on a PR where you owe no PR-level verdict (triage #1 came back clean). When in doubt, re-run triage #1 first.
+
 ### When a thread counts as addressed
 
 Do not resolve on a bare "done" claim. A reply that says "fixed" is a prompt to check, not proof. Before resolving, **verify the fix at the PR's current head SHA**:

package/src/tui/index.ts

@@ -50,13 +50,21 @@ export type TuiOptions = {
   onVersionMismatch?: (info: VersionMismatch) => void
 }
 
-// Outcome of a single `run()` cycle. The CLI's reconnect loop reads this to
-// decide whether to spin again or exit. `lostConnection` is true when the
-// WS closed AFTER the connected handshake without a deliberate /quit or
-// Ctrl+C — exactly the case a self-restart produces, and the only one
-// where a fresh connect can recover the session. Quit / Ctrl+C / pre-
-// handshake errors all resolve with `lostConnection: false`.
-export type TuiRunOutcome = { lostConnection: boolean }
+// Outcome of a single `run()` cycle.
+//   - 'detach': idle Esc — return to the session-viewer list. Closing the WS
+//     ends the server-side AgentSession (accepted; the list re-shows it as a
+//     read-only transcript).
+//   - 'exit': deliberate /quit or Ctrl+C — terminate the client.
+//   - 'lostConnection': WS closed AFTER the handshake without a deliberate
+//     quit/detach — exactly the self-restart case, and the only one where a
+//     fresh connect can recover the session.
+//   - 'connectFailed': pre-handshake connect/handshake error.
+// The CLI reconnect loop spins only on 'lostConnection'.
+export type TuiRunResult =
+  | { reason: 'detach' }
+  | { reason: 'exit'; exitCode: number }
+  | { reason: 'lostConnection' }
+  | { reason: 'connectFailed' }
 
 export function createTui({
   url,
@@ -68,7 +76,7 @@ export function createTui({
   expectedVersion,
   onVersionMismatch,
 }: TuiOptions) {
-  async function run(): Promise<TuiRunOutcome> {
+  async function run(): Promise<TuiRunResult> {
     const terminal = createTerminal()
     const tui = new TUI(terminal)
     const displayUrl = redactUrl(url)
@@ -78,13 +86,19 @@ export function createTui({
     tui.start()
     tui.requestRender()
 
-    const client = await createClient(url).catch((err) => {
+    // Pre-handshake failures resolve 'connectFailed' (not throw): the standalone
+    // CLI injects exit=process.exit so exit(1) ends the process and the return is
+    // moot; the viewer injects a no-op exit so run() resolves cleanly and the
+    // caller maps connectFailed into an error result instead of an uncaught reject.
+    const maybeClient = await createClient(url).catch((err) => {
       status.setText(colors.red(`connection error: ${err instanceof Error ? err.message : String(err)}`))
       tui.requestRender()
       tui.stop()
       exit(1)
-      throw err
+      return null
     })
+    if (maybeClient === null) return { reason: 'connectFailed' }
+    const client = maybeClient
 
     const handshake = await waitForConnected(client, displayUrl, handshakeTimeoutMs).catch((err) => {
       status.setText(colors.red(`connection error: ${err instanceof Error ? err.message : String(err)}`))
@@ -92,10 +106,10 @@ export function createTui({
       client.close()
       tui.stop()
       exit(1)
-      throw err
+      return null
     })
+    if (handshake === null) return { reason: 'connectFailed' }
 
-    let userInitiatedShutdown = false
     const { sessionId, serverVersion } = handshake
     status.setText(colors.dim(`session: ${sessionId}`))
     tui.requestRender()
@@ -231,12 +245,23 @@ export function createTui({
       }
     })
 
-    const closed = new Promise<boolean>((resolve) => {
-      client.onClose(() => {
-        appendHistory(new Text(colors.dim('disconnected'), 0, 0))
-        tui.requestRender()
-        resolve(!userInitiatedShutdown)
-      })
+    let settleOutcome: ((result: TuiRunResult) => void) | null = null
+    const outcome = new Promise<TuiRunResult>((resolve) => {
+      settleOutcome = resolve
+    })
+    const settle = (result: TuiRunResult): void => {
+      if (settleOutcome === null) return
+      const fn = settleOutcome
+      settleOutcome = null
+      fn(result)
+    }
+
+    client.onClose(() => {
+      appendHistory(new Text(colors.dim('disconnected'), 0, 0))
+      tui.requestRender()
+      // A user-initiated detach/exit already closed the WS deliberately and
+      // settled the outcome; onClose then fires but must not override it.
+      settle({ reason: 'lostConnection' })
     })
 
     function send(text: string): Promise<void> {
@@ -249,7 +274,7 @@ export function createTui({
 
     function runTuiCommand(command: TuiCommandName): boolean {
       if (command === 'quit') {
-        shutdown(0)
+        exitWith(0)
         return true
       }
       if (command === 'reload') {
@@ -266,29 +291,44 @@ export function createTui({
       return true
     }
 
-    // Esc aborts an in-flight reply. The Editor does not bind Esc, so a
-    // top-level input listener can intercept it without fighting the editor.
+    // Esc means "abort the in-flight reply" while a turn is generating, and
+    // "detach back to the session list" when idle. The Editor does not bind
+    // Esc, so a top-level listener intercepts it without fighting the editor.
     tui.addInputListener((data) => {
-      if (matchesKey(data, Key.escape) && replyInFlight) {
+      if (!matchesKey(data, Key.escape)) return undefined
+      if (replyInFlight) {
         client.send({ type: 'abort' })
         return { consume: true }
       }
-      return undefined
+      detach()
+      return { consume: true }
     })
 
-    const shutdown = (code: number) => {
-      userInitiatedShutdown = true
+    // Settle BEFORE closing the client: client.close() fires onClose, which
+    // settles 'lostConnection'. settle() is idempotent, so the first call wins —
+    // settling the deliberate outcome first keeps the later onClose a no-op.
+    const teardown = (): void => {
       tui.stop()
       client.close()
+    }
+
+    const exitWith = (code: number): void => {
+      settle({ reason: 'exit', exitCode: code })
+      teardown()
       exit(code)
     }
 
-    // Ctrl+C exits cleanly. In raw mode the kernel does NOT generate SIGINT,
-    // so we must intercept the \x03 byte ourselves. The Editor would otherwise
-    // swallow it. tui.stop() restores raw-mode/cursor/echo before we exit.
+    const detach = (): void => {
+      settle({ reason: 'detach' })
+      teardown()
+    }
+
+    // Ctrl+C exits the client. In raw mode the kernel does NOT generate SIGINT,
+    // so we intercept the \x03 byte ourselves; the Editor would otherwise
+    // swallow it. teardown() restores raw-mode/cursor/echo before we settle.
     tui.addInputListener((data) => {
       if (matchesKey(data, Key.ctrl('c'))) {
-        shutdown(0)
+        exitWith(0)
         return { consume: true }
       }
       return undefined
@@ -330,15 +370,15 @@ export function createTui({
       const command = parseBareTuiCommand(initialPrompt)
       if (command !== null) {
         runTuiCommand(command)
-        if (command === 'quit') return { lostConnection: false }
+        if (command === 'quit') return { reason: 'exit', exitCode: 0 }
       } else {
         await send(initialPrompt)
       }
     }
 
-    const lostConnection = await closed
+    const result = await outcome
     tui.stop()
-    return { lostConnection }
+    return result
   }
 
   return { run }