typeclaw 0.8.0 → 0.9.0

package/src/inspect/index.ts

@@ -0,0 +1,213 @@
+import { join } from 'node:path'
+
+import { originLabel, shortSessionId } from './label'
+import { renderEvent } from './render'
+import { replayJsonl } from './replay'
+import type { SessionSummary } from './session-list'
+import { isSessionIdShape, listSessions, resolveSession } from './session-list'
+import type { InspectEvent, InspectFilter } from './types'
+import { matchesFilter, parseDuration, parseFilter } from './types'
+
+export { listSessions, resolveSession } from './session-list'
+export type { SessionSummary } from './session-list'
+export { originLabel, shortSessionId } from './label'
+export { renderEvent } from './render'
+export { replayJsonl } from './replay'
+export { streamLive } from './live'
+export { parseDuration, parseFilter } from './types'
+export type { InspectCategory, InspectEvent, InspectFilter } from './types'
+
+export type RunInspectOptions = {
+  agentDir: string
+  sessionIdOrPrefix?: string
+  filter?: string
+  since?: string
+  json?: boolean
+  color: boolean
+  selectSession: SelectSession
+  stdout: (line: string) => void
+  stderr: (line: string) => void
+  liveSource?: LiveSourceFactory
+  signal?: AbortSignal
+}
+
+export type SelectSession = (sessions: SessionSummary[]) => Promise<SessionSummary | null>
+
+export type LiveSourceFactory = (opts: {
+  sessionId: string
+  sinceMs?: number
+  signal?: AbortSignal
+  onSubscribed?: (sessionLive: boolean) => void
+}) => AsyncIterable<InspectEvent>
+
+export type RunInspectResult = { ok: true; exitCode: 0 } | { ok: false; exitCode: number; reason: string }
+
+export async function runInspect(opts: RunInspectOptions): Promise<RunInspectResult> {
+  const filterResult = parseFilter(opts.filter)
+  if (!filterResult.ok) return { ok: false, exitCode: 2, reason: filterResult.reason }
+  const filter = filterResult.filter
+
+  let sinceMs: number | undefined
+  if (opts.since !== undefined) {
+    const d = parseDuration(opts.since)
+    if (!d.ok) return { ok: false, exitCode: 2, reason: d.reason }
+    sinceMs = Date.now() - d.ms
+  }
+
+  const sessionsDir = join(opts.agentDir, 'sessions')
+
+  const summary = await chooseSession(opts, sessionsDir, sinceMs)
+  if (!summary.ok) return summary
+
+  await streamSession({
+    summary: summary.summary,
+    filter,
+    sinceMs,
+    json: opts.json === true,
+    color: opts.color,
+    stdout: opts.stdout,
+    stderr: opts.stderr,
+    ...(opts.liveSource !== undefined ? { liveSource: opts.liveSource } : {}),
+    ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+  })
+  return { ok: true, exitCode: 0 }
+}
+
+async function chooseSession(
+  opts: RunInspectOptions,
+  sessionsDir: string,
+  sinceMs: number | undefined,
+): Promise<{ ok: true; summary: SessionSummary } | { ok: false; exitCode: number; reason: string }> {
+  if (opts.sessionIdOrPrefix !== undefined) {
+    if (opts.json === true && !looksLikeSessionId(opts.sessionIdOrPrefix)) {
+      return {
+        ok: false,
+        exitCode: 2,
+        reason: `--json requires an explicit session id (got "${opts.sessionIdOrPrefix}")`,
+      }
+    }
+    const resolved = await resolveSession(sessionsDir, opts.sessionIdOrPrefix, opts.stderr)
+    if (resolved.ok) return { ok: true, summary: resolved.summary }
+    if (resolved.reason === 'ambiguous') {
+      const lines = ['Ambiguous session prefix matches multiple sessions:']
+      for (const m of resolved.matches) {
+        lines.push(`  ${m.sessionId}  ${m.origin === null ? '(unknown origin)' : originLabel(m.origin)}`)
+      }
+      lines.push('Use the full id or run `typeclaw inspect` without args.')
+      return { ok: false, exitCode: 2, reason: lines.join('\n') }
+    }
+    return { ok: false, exitCode: 1, reason: `No session matching "${opts.sessionIdOrPrefix}" in ${sessionsDir}/` }
+  }
+
+  if (opts.json === true) {
+    return { ok: false, exitCode: 2, reason: '--json requires an explicit session id (interactive picker is disabled)' }
+  }
+
+  const listOpts: Parameters<typeof listSessions>[0] = {
+    sessionsDir,
+    limit: 20,
+    onWarn: opts.stderr,
+  }
+  if (sinceMs !== undefined) listOpts.sinceMs = sinceMs
+  const sessions = await listSessions(listOpts)
+  if (sessions.length === 0) {
+    return {
+      ok: false,
+      exitCode: 1,
+      reason: `No sessions found in ${sessionsDir}/.\nStart a session with \`typeclaw tui\` or send a message from a configured channel.`,
+    }
+  }
+  const picked = await opts.selectSession(sessions)
+  if (picked === null) return { ok: false, exitCode: 130, reason: 'cancelled' }
+  return { ok: true, summary: picked }
+}
+
+async function streamSession(opts: {
+  summary: SessionSummary
+  filter: InspectFilter
+  sinceMs: number | undefined
+  json: boolean
+  color: boolean
+  stdout: (line: string) => void
+  stderr: (line: string) => void
+  liveSource?: LiveSourceFactory
+  signal?: AbortSignal
+}): Promise<void> {
+  if (!opts.json) writeHeader(opts.summary, opts.color, opts.stdout)
+  const emit = (event: InspectEvent): void => {
+    if (opts.sinceMs !== undefined && event.ts > 0 && event.ts < opts.sinceMs) return
+    if (!matchesFilter(event, opts.filter)) return
+    if (opts.json) {
+      opts.stdout(JSON.stringify({ sessionId: opts.summary.sessionId, ...event }))
+    } else {
+      opts.stdout(renderEvent(event, { color: opts.color }))
+    }
+  }
+
+  for await (const event of replayJsonl(opts.summary.sessionFile, { onWarn: opts.stderr })) {
+    emit(event)
+  }
+
+  if (opts.liveSource === undefined) {
+    if (!opts.json) opts.stdout('─── end of transcript ───')
+    return
+  }
+
+  let sessionLive = false
+  const liveIter = opts.liveSource({
+    sessionId: opts.summary.sessionId,
+    ...(opts.sinceMs !== undefined ? { sinceMs: opts.sinceMs } : {}),
+    ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+    onSubscribed: (live) => {
+      sessionLive = live
+    },
+  })
+
+  let liveAnnounced = false
+  try {
+    for await (const event of liveIter) {
+      if (!liveAnnounced && !opts.json) {
+        opts.stdout(
+          divider(opts.color, sessionLive ? '─── live ───' : '─── live (session not in registry; broadcasts only) ───'),
+        )
+        liveAnnounced = true
+      }
+      emit(event)
+    }
+  } catch (err) {
+    opts.stderr(`live tail ended: ${err instanceof Error ? err.message : String(err)}`)
+  }
+  if (!opts.json) opts.stdout('─── end of transcript ───')
+}
+
+function divider(color: boolean, text: string): string {
+  if (color) return `\u001b[2m${text}\u001b[0m`
+  return text
+}
+
+function writeHeader(summary: SessionSummary, color: boolean, stdout: (line: string) => void): void {
+  const id = shortSessionId(summary.sessionId)
+  const label = summary.origin === null ? '(unknown origin)' : originLabel(summary.origin)
+  const started = formatDate(summary.mtimeMs)
+  const headerLine = `─── ${id} · ${label} · last activity ${started} ───`
+  if (color) stdout(`\u001b[2m${headerLine}\u001b[0m`)
+  else stdout(headerLine)
+}
+
+function formatDate(ms: number): string {
+  if (ms === 0) return '--'
+  const d = new Date(ms)
+  const yyyy = d.getFullYear()
+  const mm = String(d.getMonth() + 1).padStart(2, '0')
+  const dd = String(d.getDate()).padStart(2, '0')
+  const hh = String(d.getHours()).padStart(2, '0')
+  const mi = String(d.getMinutes()).padStart(2, '0')
+  const ss = String(d.getSeconds()).padStart(2, '0')
+  return `${yyyy}-${mm}-${dd} ${hh}:${mi}:${ss}`
+}
+
+const MIN_EXPLICIT_ID_LENGTH = 8
+
+function looksLikeSessionId(value: string): boolean {
+  return value.length >= MIN_EXPLICIT_ID_LENGTH && isSessionIdShape(value)
+}

package/src/inspect/label.ts

@@ -0,0 +1,50 @@
+import type { MinimalSessionOrigin } from '@/agent/session-meta'
+
+const ADAPTER_DISPLAY: Record<string, string> = {
+  'slack-bot': 'Slack',
+  'discord-bot': 'Discord',
+  github: 'GitHub',
+  'telegram-bot': 'Telegram',
+  kakaotalk: 'KakaoTalk',
+}
+
+const SLACK_CHAT_PREFIX_ADAPTERS = new Set(['slack-bot', 'discord-bot'])
+
+export function originLabel(origin: MinimalSessionOrigin): string {
+  switch (origin.kind) {
+    case 'tui':
+      return 'TUI'
+    case 'cron':
+      return `Cron ${origin.jobId} (${origin.jobKind})`
+    case 'subagent':
+      return `Subagent ${origin.subagent} ← ${shortSessionId(origin.parentSessionId)}`
+    case 'channel':
+      return channelLabel(origin)
+  }
+}
+
+function channelLabel(origin: Extract<MinimalSessionOrigin, { kind: 'channel' }>): string {
+  const platform = ADAPTER_DISPLAY[origin.adapter] ?? origin.adapter
+  const chatPart = renderChat(origin)
+  const wsPart = renderWorkspace(origin)
+  if (wsPart === '') return `${platform} ${chatPart}`
+  return `${platform} ${wsPart}/${chatPart}`
+}
+
+function renderChat(origin: Extract<MinimalSessionOrigin, { kind: 'channel' }>): string {
+  if (origin.chatName !== undefined && origin.chatName !== '') {
+    const prefix = SLACK_CHAT_PREFIX_ADAPTERS.has(origin.adapter) ? '#' : ''
+    return `${prefix}${origin.chatName}`
+  }
+  return origin.chat
+}
+
+function renderWorkspace(origin: Extract<MinimalSessionOrigin, { kind: 'channel' }>): string {
+  if (origin.workspaceName !== undefined && origin.workspaceName !== '') return origin.workspaceName
+  return origin.workspace
+}
+
+export function shortSessionId(sessionId: string): string {
+  if (sessionId.length <= 12) return sessionId
+  return sessionId.slice(0, 12)
+}

package/src/inspect/live.ts

@@ -0,0 +1,221 @@
+import type { InspectClientMessage, InspectFramePayload, InspectServerMessage } from '@/shared'
+
+import type { InspectEvent } from './types'
+
+export type StreamLiveOptions = {
+  url: string
+  sessionId: string
+  sinceMs?: number
+  signal?: AbortSignal
+  WebSocketImpl?: typeof WebSocket
+  onSubscribed?: (live: boolean) => void
+  onError?: (message: string) => void
+}
+
+export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<InspectEvent> {
+  const WS = opts.WebSocketImpl ?? WebSocket
+  const ws = new WS(opts.url)
+  const buffer: InspectEvent[] = []
+  let resolveNext: ((value: { event: InspectEvent | null; done: boolean }) => void) | null = null
+  let closed = false
+  let pendingError: string | null = null
+
+  const accumulators = new Map<string, string>()
+
+  const wake = (): void => {
+    if (resolveNext !== null) {
+      const fn = resolveNext
+      resolveNext = null
+      const next = buffer.shift() ?? null
+      fn({ event: next, done: closed && buffer.length === 0 && next === null })
+    }
+  }
+
+  ws.addEventListener('message', (e) => {
+    let msg: InspectServerMessage
+    try {
+      msg = JSON.parse(String((e as MessageEvent).data)) as InspectServerMessage
+    } catch {
+      return
+    }
+    if (msg.type === 'subscribed') {
+      opts.onSubscribed?.(msg.sessionLive)
+      return
+    }
+    if (msg.type === 'error') {
+      opts.onError?.(msg.message)
+      pendingError = msg.message
+      closed = true
+      try {
+        ws.close()
+      } catch {
+        /* ignore */
+      }
+      wake()
+      return
+    }
+    if (msg.type !== 'frame') return
+    const event = frameToEvent(msg.payload, msg.ts, accumulators)
+    if (event !== null) {
+      buffer.push(event)
+      wake()
+    }
+  })
+
+  const onOpen = new Promise<void>((resolve, reject) => {
+    ws.addEventListener('open', () => resolve(), { once: true })
+    ws.addEventListener('error', () => reject(new Error('websocket connection failed')), { once: true })
+  })
+  ws.addEventListener('close', () => {
+    closed = true
+    wake()
+  })
+
+  if (opts.signal !== undefined) {
+    if (opts.signal.aborted) {
+      try {
+        ws.close()
+      } catch {
+        /* ignore */
+      }
+    } else {
+      opts.signal.addEventListener(
+        'abort',
+        () => {
+          closed = true
+          try {
+            ws.close()
+          } catch {
+            /* ignore */
+          }
+          wake()
+        },
+        { once: true },
+      )
+    }
+  }
+
+  try {
+    await onOpen
+  } catch (err) {
+    closed = true
+    throw err
+  }
+
+  const subscribe: InspectClientMessage = {
+    type: 'subscribe',
+    sessionId: opts.sessionId,
+    ...(opts.sinceMs !== undefined ? { sinceMs: opts.sinceMs } : {}),
+  }
+  ws.send(JSON.stringify(subscribe))
+
+  while (true) {
+    if (buffer.length > 0) {
+      const next = buffer.shift()!
+      yield next
+      continue
+    }
+    if (closed) {
+      if (pendingError !== null) throw new Error(pendingError)
+      return
+    }
+    const { event, done } = await new Promise<{ event: InspectEvent | null; done: boolean }>((resolve) => {
+      resolveNext = resolve
+    })
+    if (event !== null) yield event
+    if (done) {
+      if (pendingError !== null) throw new Error(pendingError)
+      return
+    }
+  }
+}
+
+function frameToEvent(
+  payload: InspectFramePayload,
+  ts: number,
+  accumulators: Map<string, string>,
+): InspectEvent | null {
+  switch (payload.kind) {
+    case 'text_delta': {
+      const existing = accumulators.get(payload.sessionId) ?? ''
+      accumulators.set(payload.sessionId, existing + payload.delta)
+      return null
+    }
+    case 'tool_start':
+      return {
+        cat: 'tool',
+        ts,
+        phase: 'start',
+        toolCallId: payload.toolCallId,
+        name: payload.name,
+        ...(payload.args !== undefined ? { args: payload.args } : {}),
+      }
+    case 'tool_end':
+      return {
+        cat: 'tool',
+        ts,
+        phase: 'end',
+        toolCallId: payload.toolCallId,
+        name: payload.name,
+        ...(payload.result !== undefined ? { result: payload.result } : {}),
+        isError: payload.isError,
+        durationMs: payload.durationMs,
+      }
+    case 'message_end':
+      return messageEndToEvents(payload, ts, accumulators)
+    case 'broadcast':
+      return {
+        cat: 'broadcast',
+        ts,
+        payload: payload.payload,
+        ...(payload.meta !== undefined ? { meta: payload.meta } : {}),
+      }
+    case 'cron-fire':
+      return { cat: 'cron-fire', ts, jobId: payload.jobId, payload: payload.payload }
+    default:
+      return null
+  }
+}
+
+function messageEndToEvents(
+  payload: Extract<InspectFramePayload, { kind: 'message_end' }>,
+  ts: number,
+  accumulators: Map<string, string>,
+): InspectEvent | null {
+  if (payload.role === 'assistant') {
+    const text = takeAccumulator(accumulators, payload.sessionId)
+    if (text !== null && text !== '') {
+      const event: InspectEvent = {
+        cat: 'assistant',
+        ts,
+        text,
+        ...(payload.provider !== undefined ? { provider: payload.provider } : {}),
+        ...(payload.model !== undefined ? { model: payload.model } : {}),
+      }
+      if (payload.errorMessage !== undefined) {
+        return event
+      }
+      return event
+    }
+    if (payload.errorMessage !== undefined) {
+      return { cat: 'error', ts, message: payload.errorMessage }
+    }
+    if (payload.usage !== undefined && (payload.usage.totalTokens > 0 || payload.stopReason !== undefined)) {
+      return {
+        cat: 'done',
+        ts,
+        ...(payload.stopReason !== undefined ? { stopReason: payload.stopReason } : {}),
+        ...payload.usage,
+      }
+    }
+    return null
+  }
+  return null
+}
+
+function takeAccumulator(accumulators: Map<string, string>, sessionId: string): string | null {
+  const value = accumulators.get(sessionId)
+  if (value === undefined) return null
+  accumulators.delete(sessionId)
+  return value
+}

package/src/inspect/render.ts

@@ -0,0 +1,163 @@
+import { styleText } from 'node:util'
+
+import { originLabel } from './label'
+import type { InspectEvent } from './types'
+
+export type RenderOptions = {
+  color: boolean
+  maxTextLength?: number
+}
+
+export function renderEvent(event: InspectEvent, opts: RenderOptions): string {
+  const time = renderTime(event.ts, opts)
+  const tag = renderTag(event, opts)
+  const body = renderBody(event, opts)
+  return `${time}  ${tag}  ${body}`
+}
+
+const DEFAULT_MAX_TEXT = 200
+
+function renderTime(ts: number, opts: RenderOptions): string {
+  if (ts === 0) return tint(opts, 'dim', '--:--:--')
+  const d = new Date(ts)
+  const hh = String(d.getHours()).padStart(2, '0')
+  const mm = String(d.getMinutes()).padStart(2, '0')
+  const ss = String(d.getSeconds()).padStart(2, '0')
+  return tint(opts, 'dim', `${hh}:${mm}:${ss}`)
+}
+
+function renderTag(event: InspectEvent, opts: RenderOptions): string {
+  switch (event.cat) {
+    case 'meta':
+      return tint(opts, 'magenta', padEnd('meta', 9))
+    case 'user':
+      return tint(opts, 'cyan', padEnd('user', 9))
+    case 'assistant':
+      return tint(opts, 'green', padEnd('assist', 9))
+    case 'tool':
+      return tint(opts, 'yellow', padEnd(event.phase === 'start' ? 'tool ▸' : 'tool ◂', 9))
+    case 'error':
+      return tint(opts, 'red', padEnd('error', 9))
+    case 'done':
+      return tint(opts, 'gray', padEnd('done', 9))
+    case 'broadcast':
+      return tint(opts, 'magenta', padEnd('bcast', 9))
+    case 'cron-fire':
+      return tint(opts, 'magenta', padEnd('cron', 9))
+  }
+}
+
+function renderBody(event: InspectEvent, opts: RenderOptions): string {
+  switch (event.cat) {
+    case 'meta':
+      return `origin: ${originLabel(event.origin)}`
+    case 'user':
+      return truncate(singleLine(event.text), opts.maxTextLength ?? DEFAULT_MAX_TEXT)
+    case 'assistant':
+      return truncate(singleLine(event.text), opts.maxTextLength ?? DEFAULT_MAX_TEXT)
+    case 'tool': {
+      if (event.phase === 'start') {
+        return `${event.name}(${renderArgs(event.args)})`
+      }
+      const dur = formatDuration(event.durationMs ?? 0)
+      const status = event.isError ? tint(opts, 'red', 'error') : 'ok'
+      const result = renderResult(event.result, opts.maxTextLength ?? DEFAULT_MAX_TEXT)
+      return `${event.name} → ${status}${result ? ` ${result}` : ''} (${dur})`
+    }
+    case 'error':
+      return tint(opts, 'red', truncate(singleLine(event.message), opts.maxTextLength ?? DEFAULT_MAX_TEXT))
+    case 'done':
+      return renderDone(event, opts)
+    case 'broadcast':
+      return renderBroadcastBody(event.payload, opts.maxTextLength ?? DEFAULT_MAX_TEXT)
+    case 'cron-fire':
+      return `${event.jobId} fired`
+  }
+}
+
+function renderBroadcastBody(payload: unknown, maxLen: number): string {
+  if (payload !== null && typeof payload === 'object') {
+    const kind = (payload as { kind?: unknown }).kind
+    if (typeof kind === 'string') {
+      const rest = renderArgs(payload)
+      return rest === '' ? kind : `${kind} ${rest}`
+    }
+  }
+  try {
+    const compact = JSON.stringify(payload)
+    if (compact === undefined) return ''
+    if (compact.length <= maxLen) return compact
+    return `${compact.slice(0, maxLen)}…`
+  } catch {
+    return ''
+  }
+}
+
+function renderDone(event: Extract<InspectEvent, { cat: 'done' }>, opts: RenderOptions): string {
+  const parts: string[] = []
+  if (event.totalTokens > 0) parts.push(`tokens: ${event.input} in / ${event.output} out`)
+  if (event.cost > 0) parts.push(`$${event.cost.toFixed(4)}`)
+  if (event.stopReason !== undefined) parts.push(`stop=${event.stopReason}`)
+  return tint(opts, 'dim', parts.join(' · ') || '(no usage)')
+}
+
+function renderArgs(args: unknown): string {
+  if (args === undefined) return ''
+  if (typeof args === 'string') return JSON.stringify(args)
+  try {
+    const compact = JSON.stringify(args)
+    if (compact === undefined) return ''
+    if (compact.length <= 120) return compact
+    return `${compact.slice(0, 120)}…`
+  } catch {
+    return '<unserializable>'
+  }
+}
+
+function renderResult(result: unknown, maxLen: number): string {
+  if (result === undefined || result === null) return ''
+  if (typeof result === 'string') {
+    const text = singleLine(result)
+    if (text === '') return ''
+    return `"${truncate(text, Math.min(80, maxLen))}"`
+  }
+  if (typeof result === 'number' || typeof result === 'boolean') return String(result)
+  try {
+    const compact = JSON.stringify(result)
+    if (compact === undefined) return ''
+    if (compact.length <= 80) return compact
+    return `${compact.slice(0, 80)}…`
+  } catch {
+    return ''
+  }
+}
+
+function truncate(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text
+  return `${text.slice(0, maxLen)}…`
+}
+
+function singleLine(text: string): string {
+  return text.replace(/\s+/g, ' ').trim()
+}
+
+function padEnd(text: string, width: number): string {
+  if (text.length >= width) return text
+  return text + ' '.repeat(width - text.length)
+}
+
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`
+  const s = ms / 1000
+  if (s < 60) return `${s.toFixed(1)}s`
+  const m = Math.floor(s / 60)
+  const sec = Math.round(s % 60)
+  return `${m}m${sec}s`
+}
+
+type ColorName = 'dim' | 'magenta' | 'cyan' | 'green' | 'yellow' | 'red' | 'gray'
+
+function tint(opts: RenderOptions, color: ColorName, text: string): string {
+  if (!opts.color) return text
+  return styleText(color, text)
+}