typeclaw 0.19.0 → 0.21.0

package/src/cli/dreams.ts

@@ -0,0 +1,147 @@
+import { defineCommand } from 'citty'
+
+import { type DreamEntry, renderListRow, runDreams, type ViewAction } from '@/dreams'
+import { findAgentDir } from '@/init'
+
+import { createEscController } from './inspect-controller'
+import { c, cancel, errorLine, isCancel } from './ui'
+
+const ESC_DEBOUNCE_MS = 50
+const QUIT_KEY = 0x71
+
+export const dreamsCommand = defineCommand({
+  meta: {
+    name: 'dreams',
+    description: "browse the dreaming subagent's memory-consolidation journal from git history (host stage)",
+  },
+  args: {
+    limit: {
+      type: 'string',
+      description: 'show at most N most-recent dreams',
+    },
+    json: {
+      type: 'boolean',
+      description: 'emit one JSON object per dream (subject-level)',
+      default: false,
+    },
+    details: {
+      type: 'boolean',
+      description: 'with --json, hydrate each dream with its consolidated fragments/shards/skills',
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    const color = useColor()
+    const limit = parseLimit(args.limit)
+    const interactive = isInteractive() && args.json !== true
+
+    const result = await runDreams({
+      agentDir: cwd,
+      json: args.json === true,
+      details: args.details === true,
+      color,
+      ...(limit !== undefined ? { limit } : {}),
+      selectDream: (entries, selectOpts) => clackSelect(entries, color, selectOpts?.initialSha),
+      ...(interactive ? { viewDream: () => waitForViewerKey(color) } : {}),
+      stdout: (line) => process.stdout.write(`${line}\n`),
+    })
+
+    if (!result.ok) {
+      process.stderr.write(`${errorLine(result.reason)}\n`)
+      process.exit(result.exitCode)
+    }
+    process.exit(result.exitCode)
+  },
+})
+
+function isInteractive(): boolean {
+  return Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY)
+}
+
+type RawInput = Pick<NodeJS.ReadStream, 'isTTY' | 'setRawMode' | 'resume' | 'pause' | 'on' | 'off'>
+
+// Esc routes through createEscController so a standalone Esc returns 'back'
+// while a multi-byte CSI sequence (↑/↓ arrows) does not. Teardown restores
+// raw mode but deliberately does NOT pause stdin: clack cannot re-flow a
+// paused process.stdin under Bun, so the next picker would freeze — the same
+// reason cli/inspect.ts leaves the stream flowing on its return path.
+export async function waitForViewerKey(color: boolean, input: RawInput = process.stdin): Promise<ViewAction> {
+  const stdin = input
+  if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') return 'exit'
+
+  process.stdout.write(`${viewerHintLine(color)}\n`)
+
+  const ctrl = createEscController({ debounceMs: ESC_DEBOUNCE_MS })
+  const escSignal = ctrl.armForStream()
+
+  return new Promise<ViewAction>((resolve) => {
+    let settled = false
+    const finish = (action: ViewAction): void => {
+      if (settled) return
+      settled = true
+      escSignal.removeEventListener('abort', onEscAbort)
+      stdin.off('data', onData)
+      ctrl.dispose()
+      try {
+        stdin.setRawMode(false)
+      } catch {
+        /* terminal already torn down */
+      }
+      resolve(action)
+    }
+    const onEscAbort = (): void => finish('back')
+    const onData = (chunk: Buffer): void => {
+      if (chunk[0] === QUIT_KEY) {
+        finish('exit')
+        return
+      }
+      const { sigint } = ctrl.onChunk(chunk)
+      if (sigint) finish('exit')
+    }
+    escSignal.addEventListener('abort', onEscAbort, { once: true })
+    stdin.setRawMode(true)
+    stdin.resume()
+    stdin.on('data', onData)
+  })
+}
+
+function viewerHintLine(color: boolean): string {
+  const text = '(esc to go back to the list · q to quit)'
+  return color ? c.dim(text) : text
+}
+
+function parseLimit(raw: unknown): number | undefined {
+  if (typeof raw !== 'string') return undefined
+  const n = Number.parseInt(raw, 10)
+  return Number.isFinite(n) && n > 0 ? n : undefined
+}
+
+async function clackSelect(
+  entries: DreamEntry[],
+  color: boolean,
+  initialSha: string | undefined,
+): Promise<DreamEntry | null> {
+  const { select } = await import('@clack/prompts')
+  const preferred = initialSha !== undefined && entries.some((e) => e.sha === initialSha) ? initialSha : entries[0]?.sha
+  const picked = await select<string>({
+    message: `Pick a dream to open (${entries.length} total)`,
+    options: entries.map((entry) => ({
+      value: entry.sha,
+      label: renderListRow(entry, { color }),
+    })),
+    initialValue: preferred,
+  })
+  if (isCancel(picked)) {
+    cancel('Cancelled.')
+    return null
+  }
+  return entries.find((entry) => entry.sha === picked) ?? null
+}
+
+function useColor(): boolean {
+  if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '') return false
+  if (process.env.FORCE_COLOR === '0') return false
+  if (process.env.FORCE_COLOR) return true
+  return Boolean(process.stdout.isTTY)
+}

package/src/cli/index.ts

@@ -23,6 +23,7 @@ const main = defineCommand({
     reload: () => import('./reload').then((m) => m.reload),
     logs: () => import('./logs').then((m) => m.logsCommand),
     inspect: () => import('./inspect').then((m) => m.inspectCommand),
+    dreams: () => import('./dreams').then((m) => m.dreamsCommand),
     shell: () => import('./shell').then((m) => m.shellCommand),
     compose: () => import('./compose').then((m) => m.composeCommand),
     channel: () => import('./channel').then((m) => m.channelCommand),

package/src/cli/inspect.ts

@@ -75,6 +75,9 @@ export const inspectCommand = defineCommand({
           if (escListener === null) return new AbortController().signal
           return escListener.armForStream()
         },
+        afterEscStream: () => {
+          escListener?.pause()
+        },
         ...(liveHint !== undefined ? { liveHint } : {}),
         stdout: (line) => process.stdout.write(`${line}\n`),
         stderr: (line) => process.stderr.write(`${line}\n`),

package/src/dreams/git.ts

@@ -0,0 +1,85 @@
+export type GitResult = { exitCode: number; stdout: string; stderr: string }
+export type SpawnGit = (args: string[], cwd: string) => Promise<GitResult>
+
+export type RawCommit = {
+  sha: string
+  shortSha: string
+  committedAt: string
+  subject: string
+}
+
+export type ResolveRepoResult = { ok: true; root: string } | { ok: false; reason: 'not-a-repo' | 'git-failed' }
+
+const FIELD_SEP = '\x1f'
+const RECORD_SEP = '\x1e'
+
+export async function resolveGitRepo(cwd: string, spawnGit: SpawnGit = defaultSpawnGit): Promise<ResolveRepoResult> {
+  const res = await spawnGit(['rev-parse', '--show-toplevel'], cwd)
+  if (res.exitCode === 0) {
+    const root = res.stdout.trim()
+    if (root.length > 0) return { ok: true, root }
+    return { ok: false, reason: 'git-failed' }
+  }
+  if (/not a git repository/i.test(res.stderr)) return { ok: false, reason: 'not-a-repo' }
+  return { ok: false, reason: 'git-failed' }
+}
+
+const DREAM_SUBJECT_PREFIX = 'dream: '
+
+export async function readDreamCommitLog(
+  root: string,
+  opts: { limit?: number } = {},
+  spawnGit: SpawnGit = defaultSpawnGit,
+): Promise<RawCommit[]> {
+  // --grep is only a cheap pre-filter: it matches ANY line of the commit
+  // message, so a non-dream commit with a `dream: ...` body line slips
+  // through. The subject is the authoritative contract, so the prefix filter
+  // below is what actually decides membership — and the limit is applied
+  // AFTER it so body-matching impostors can't consume a slot and shrink the
+  // result below the requested count.
+  const args = ['log', '--grep=^dream: ', `--format=%H${FIELD_SEP}%h${FIELD_SEP}%cI${FIELD_SEP}%s${RECORD_SEP}`]
+
+  const res = await spawnGit(args, root)
+  if (res.exitCode !== 0) return []
+  const dreams = parseLogOutput(res.stdout).filter((c) => c.subject.startsWith(DREAM_SUBJECT_PREFIX))
+  if (opts.limit !== undefined && opts.limit > 0) return dreams.slice(0, opts.limit)
+  return dreams
+}
+
+export function parseLogOutput(stdout: string): RawCommit[] {
+  const commits: RawCommit[] = []
+  for (const record of stdout.split(RECORD_SEP)) {
+    const trimmed = record.replace(/^\n+/, '')
+    if (trimmed.length === 0) continue
+    const [sha, shortSha, committedAt, subject] = trimmed.split(FIELD_SEP)
+    if (sha === undefined || shortSha === undefined || committedAt === undefined || subject === undefined) continue
+    commits.push({ sha, shortSha, committedAt, subject })
+  }
+  return commits
+}
+
+export async function readDreamCommitShow(
+  root: string,
+  sha: string,
+  spawnGit: SpawnGit = defaultSpawnGit,
+): Promise<{ nameStatus: string; patch: string } | null> {
+  const nameStatus = await spawnGit(['show', '--no-color', '--find-renames', '--format=', '--name-status', sha], root)
+  if (nameStatus.exitCode !== 0) return null
+  const patch = await spawnGit(['show', '--no-color', '--format=', '--unified=0', sha], root)
+  if (patch.exitCode !== 0) return null
+  return { nameStatus: nameStatus.stdout, patch: patch.stdout }
+}
+
+const defaultSpawnGit: SpawnGit = async (args, cwd) => {
+  const bun = (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
+  if (!bun) return { exitCode: -1, stdout: '', stderr: 'bun runtime not available' }
+  try {
+    const proc = bun.spawn({ cmd: ['git', ...args], cwd, stdout: 'pipe', stderr: 'pipe' })
+    const exitCode = await proc.exited
+    const stdout = await new Response(proc.stdout).text()
+    const stderr = await new Response(proc.stderr).text()
+    return { exitCode, stdout, stderr }
+  } catch (err) {
+    return { exitCode: -1, stdout: '', stderr: err instanceof Error ? err.message : String(err) }
+  }
+}

package/src/dreams/index.ts

@@ -0,0 +1,134 @@
+import { readDreamCommitLog, readDreamCommitShow, resolveGitRepo, type SpawnGit } from './git'
+import { parseDreamDetail, parseDreamSubject } from './parse'
+import { renderDetail, renderListRow, type RenderOptions, toJsonShape } from './render'
+import type { DreamEntry } from './types'
+
+export type { SpawnGit } from './git'
+export type { DreamEntry } from './types'
+export { renderDetail, renderListRow, toJsonShape } from './render'
+export { parseDreamDetail, parseDreamSubject } from './parse'
+
+export type SelectDreamOptions = {
+  initialSha?: string
+}
+
+export type SelectDream = (entries: DreamEntry[], opts?: SelectDreamOptions) => Promise<DreamEntry | null>
+
+// 'back' re-opens the picker with the just-viewed dream pre-selected.
+export type ViewAction = 'back' | 'exit'
+export type ViewDream = () => Promise<ViewAction>
+
+export type RunDreamsOptions = {
+  agentDir: string
+  json: boolean
+  details: boolean
+  color: boolean
+  limit?: number
+  selectDream: SelectDream
+  viewDream?: ViewDream
+  stdout: (line: string) => void
+  spawnGit?: SpawnGit
+}
+
+export type RunDreamsResult = { ok: true; exitCode: 0 } | { ok: false; exitCode: number; reason: string }
+
+export async function listDreams(
+  agentDir: string,
+  opts: { limit?: number } = {},
+  spawnGit?: SpawnGit,
+): Promise<DreamEntry[]> {
+  const repo = await resolveGitRepo(agentDir, spawnGit)
+  if (!repo.ok) return []
+  const commits = await readDreamCommitLog(repo.root, opts.limit !== undefined ? { limit: opts.limit } : {}, spawnGit)
+  return commits.map((commit) => {
+    const subject = parseDreamSubject(commit.subject)
+    return {
+      sha: commit.sha,
+      shortSha: commit.shortSha,
+      subject: commit.subject,
+      committedAt: commit.committedAt,
+      isDreamCommit: subject.isDreamCommit,
+      summary: subject.summary,
+      emoji: subject.emoji,
+      categories: subject.categories,
+    }
+  })
+}
+
+export async function hydrateDream(agentDir: string, entry: DreamEntry, spawnGit?: SpawnGit): Promise<DreamEntry> {
+  const repo = await resolveGitRepo(agentDir, spawnGit)
+  if (!repo.ok) return entry
+  const show = await readDreamCommitShow(repo.root, entry.sha, spawnGit)
+  if (show === null) return entry
+  return { ...entry, detail: parseDreamDetail(show.nameStatus, show.patch) }
+}
+
+export async function runDreams(opts: RunDreamsOptions): Promise<RunDreamsResult> {
+  const repo = await resolveGitRepo(opts.agentDir, opts.spawnGit)
+  if (!repo.ok) {
+    if (repo.reason === 'not-a-repo') {
+      return {
+        ok: false,
+        exitCode: 1,
+        reason:
+          "Not a git repository. Dreams live in the agent folder's git history — run this from your agent folder.",
+      }
+    }
+    return { ok: false, exitCode: 1, reason: 'git failed while resolving the repository root.' }
+  }
+
+  const entries = await listDreams(opts.agentDir, opts.limit !== undefined ? { limit: opts.limit } : {}, opts.spawnGit)
+  const renderOpts: RenderOptions = { color: opts.color }
+
+  if (opts.json) return runJson(opts, repo.root, entries)
+
+  if (entries.length === 0) {
+    opts.stdout('No dreams yet. The dreaming subagent commits here after it consolidates memory.')
+    return { ok: true, exitCode: 0 }
+  }
+
+  if (!isInteractive()) {
+    for (const entry of entries) opts.stdout(renderListRow(entry, renderOpts))
+    return { ok: true, exitCode: 0 }
+  }
+
+  return runInteractiveLoop(opts, entries, renderOpts)
+}
+
+async function runInteractiveLoop(
+  opts: RunDreamsOptions,
+  entries: DreamEntry[],
+  renderOpts: RenderOptions,
+): Promise<RunDreamsResult> {
+  let initialSha: string | undefined
+  while (true) {
+    const picked = await opts.selectDream(entries, initialSha !== undefined ? { initialSha } : {})
+    if (picked === null) return { ok: true, exitCode: 0 }
+    initialSha = picked.sha
+
+    const hydrated = await hydrateDream(opts.agentDir, picked, opts.spawnGit)
+    opts.stdout(renderDetail(hydrated, renderOpts))
+
+    if (opts.viewDream === undefined) return { ok: true, exitCode: 0 }
+    const action = await opts.viewDream()
+    if (action === 'exit') return { ok: true, exitCode: 0 }
+  }
+}
+
+async function runJson(opts: RunDreamsOptions, root: string, entries: DreamEntry[]): Promise<RunDreamsResult> {
+  for (const entry of entries) {
+    const final = opts.details ? await hydrateEntryFromRoot(root, entry, opts.spawnGit) : entry
+    opts.stdout(JSON.stringify(toJsonShape(final)))
+  }
+  return { ok: true, exitCode: 0 }
+}
+
+async function hydrateEntryFromRoot(root: string, entry: DreamEntry, spawnGit?: SpawnGit): Promise<DreamEntry> {
+  const show = await readDreamCommitShow(root, entry.sha, spawnGit)
+  if (show === null) return entry
+  return { ...entry, detail: parseDreamDetail(show.nameStatus, show.patch) }
+}
+
+function isInteractive(): boolean {
+  return Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY)
+}

package/src/dreams/parse.ts

@@ -0,0 +1,224 @@
+import {
+  type DreamCategory,
+  type DreamEmoji,
+  DREAM_EMOJI_POOL,
+  type DreamEntryDetail,
+  type FragmentEventSummary,
+  type ShardChangeStatus,
+  type SkillCreation,
+  type TopicShardChange,
+} from './types'
+
+const BODY_PREVIEW_MAX = 80
+const EMOJI_SET = new Set<string>(DREAM_EMOJI_POOL)
+const STREAM_PATH = /^memory\/(?:streams\/)?(\d{4}-\d{2}-\d{2})\.jsonl$/
+const TOPIC_PATH = /^memory\/topics\/(.+)\.md$/
+const SKILL_PATH = /^memory\/skills\/([^/]+)\/SKILL\.md$/
+const STATE_PATH = 'memory/.dreaming-state.json'
+
+export type DreamSubject = {
+  isDreamCommit: boolean
+  summary: string | null
+  emoji: DreamEmoji | null
+  categories: DreamCategory[]
+}
+
+export function parseDreamSubject(subject: string): DreamSubject {
+  const match = /^dream:\s+(.*)$/.exec(subject)
+  if (match === null) {
+    return { isDreamCommit: false, summary: null, emoji: null, categories: [] }
+  }
+
+  const rest = (match[1] ?? '').trim()
+  const { summary, emoji } = splitTrailingEmoji(rest)
+  return {
+    isDreamCommit: true,
+    summary: summary.length > 0 ? summary : null,
+    emoji,
+    categories: classifySummary(summary),
+  }
+}
+
+function splitTrailingEmoji(rest: string): { summary: string; emoji: DreamEmoji | null } {
+  const chars = [...rest]
+  const last = chars.at(-1)
+  if (last !== undefined && EMOJI_SET.has(last)) {
+    return { summary: chars.slice(0, -1).join('').trim(), emoji: last as DreamEmoji }
+  }
+  return { summary: rest, emoji: null }
+}
+
+function classifySummary(summary: string): DreamCategory[] {
+  const categories: DreamCategory[] = []
+  if (/\bfragments?\b/.test(summary)) categories.push('fragments')
+  if (/\bskills?\b/.test(summary)) categories.push('skills')
+  if (/watermarks only/.test(summary)) categories.push('watermarks-only')
+  if (/^snapshot$/.test(summary)) categories.push('snapshot')
+  if (categories.length === 0) categories.push('other')
+  return categories
+}
+
+export function parseDreamDetail(nameStatus: string, patch: string): DreamEntryDetail {
+  const warnings: string[] = []
+  const changedTopics: TopicShardChange[] = []
+  const createdSkills: SkillCreation[] = []
+  let stateChanged = false
+
+  for (const { status, path, oldPath } of parseNameStatus(nameStatus)) {
+    if (path === STATE_PATH || oldPath === STATE_PATH) {
+      stateChanged = true
+      continue
+    }
+    const topic = TOPIC_PATH.exec(path)
+    if (topic !== null) {
+      changedTopics.push({ path, slug: topic[1] ?? path, status, additions: null, deletions: null })
+      continue
+    }
+    if (status === 'added') {
+      const skill = SKILL_PATH.exec(path)
+      if (skill !== null) createdSkills.push({ name: skill[1] ?? '', path })
+    }
+  }
+
+  applyTopicLineCounts(changedTopics, patch, warnings)
+  const addedFragments = extractAddedFragments(patch, warnings)
+
+  return { addedFragments, changedTopics, createdSkills, stateChanged, parseWarnings: warnings }
+}
+
+type NameStatusRow = { status: ShardChangeStatus; path: string; oldPath: string | null }
+
+function parseNameStatus(nameStatus: string): NameStatusRow[] {
+  const rows: NameStatusRow[] = []
+  for (const line of nameStatus.split('\n')) {
+    if (line.trim().length === 0) continue
+    const cols = line.split('\t')
+    const code = cols[0] ?? ''
+    if (code.startsWith('R')) {
+      const oldPath = cols[1] ?? ''
+      const newPath = cols[2] ?? ''
+      if (newPath.length > 0) rows.push({ status: 'renamed', path: newPath, oldPath })
+      continue
+    }
+    const path = cols[1] ?? ''
+    if (path.length === 0) continue
+    rows.push({ status: mapStatusCode(code), path, oldPath: null })
+  }
+  return rows
+}
+
+function mapStatusCode(code: string): ShardChangeStatus {
+  const c = code.charAt(0)
+  if (c === 'A') return 'added'
+  if (c === 'M') return 'modified'
+  if (c === 'D') return 'deleted'
+  if (c === 'R') return 'renamed'
+  return 'unknown'
+}
+
+type ParsedHunk = { path: string; addedLines: string[] }
+
+function* iterateHunks(patch: string): Generator<ParsedHunk> {
+  let currentPath: string | null = null
+  let added: string[] = []
+  const flush = function* (): Generator<ParsedHunk> {
+    if (currentPath !== null) yield { path: currentPath, addedLines: added }
+  }
+
+  for (const line of patch.split('\n')) {
+    if (line.startsWith('diff --git ')) {
+      yield* flush()
+      currentPath = null
+      added = []
+      continue
+    }
+    if (line.startsWith('+++ ')) {
+      currentPath = stripDiffPathPrefix(line.slice(4))
+      continue
+    }
+    if (line.startsWith('+') && !line.startsWith('+++')) {
+      added.push(line.slice(1))
+    }
+  }
+  yield* flush()
+}
+
+function stripDiffPathPrefix(raw: string): string {
+  const trimmed = raw.trim()
+  if (trimmed === '/dev/null') return trimmed
+  return trimmed.replace(/^b\//, '')
+}
+
+function extractAddedFragments(patch: string, warnings: string[]): FragmentEventSummary[] {
+  const out: FragmentEventSummary[] = []
+  for (const hunk of iterateHunks(patch)) {
+    const streamMatch = STREAM_PATH.exec(hunk.path)
+    if (streamMatch === null) continue
+    const streamDate = streamMatch[1] ?? null
+    for (const line of hunk.addedLines) {
+      if (line.trim().length === 0) continue
+      const fragment = parseFragmentLine(line, streamDate)
+      if (fragment === null) {
+        warnings.push(`unparseable stream line in ${hunk.path}`)
+        continue
+      }
+      if (fragment !== 'skip') out.push(fragment)
+    }
+  }
+  return out
+}
+
+function parseFragmentLine(line: string, streamDate: string | null): FragmentEventSummary | 'skip' | null {
+  let raw: unknown
+  try {
+    raw = JSON.parse(line)
+  } catch {
+    return null
+  }
+  if (typeof raw !== 'object' || raw === null) return null
+  const obj = raw as Record<string, unknown>
+  if (obj.type !== 'fragment') return 'skip'
+  if (typeof obj.id !== 'string' || obj.id.length === 0) return null
+  return {
+    id: obj.id,
+    streamDate,
+    topic: typeof obj.topic === 'string' ? obj.topic : null,
+    bodyPreview: typeof obj.body === 'string' ? preview(obj.body) : null,
+  }
+}
+
+function applyTopicLineCounts(topics: TopicShardChange[], patch: string, warnings: string[]): void {
+  if (topics.length === 0) return
+  const counts = new Map<string, { additions: number; deletions: number }>()
+  let currentPath: string | null = null
+
+  for (const line of patch.split('\n')) {
+    if (line.startsWith('+++ ')) {
+      currentPath = stripDiffPathPrefix(line.slice(4))
+      if (currentPath !== null && !counts.has(currentPath)) counts.set(currentPath, { additions: 0, deletions: 0 })
+      continue
+    }
+    if (currentPath === null) continue
+    const bucket = counts.get(currentPath)
+    if (bucket === undefined) continue
+    if (line.startsWith('+') && !line.startsWith('+++')) bucket.additions++
+    else if (line.startsWith('-') && !line.startsWith('---')) bucket.deletions++
+  }
+
+  for (const topic of topics) {
+    if (topic.status === 'deleted') continue
+    const bucket = counts.get(topic.path)
+    if (bucket === undefined) {
+      if (topic.status === 'modified') warnings.push(`no diff hunk for modified topic ${topic.path}`)
+      continue
+    }
+    topic.additions = bucket.additions
+    topic.deletions = bucket.deletions
+  }
+}
+
+function preview(body: string): string {
+  const oneline = body.replace(/\s+/g, ' ').trim()
+  if (oneline.length <= BODY_PREVIEW_MAX) return oneline
+  return `${oneline.slice(0, BODY_PREVIEW_MAX)}…`
+}