typeclaw 0.1.4 → 0.1.6

package/src/channels/schema.ts

@@ -4,11 +4,6 @@ export const ADAPTER_IDS = ['discord-bot', 'kakaotalk', 'slack-bot', 'telegram-b
 
 export type AdapterId = (typeof ADAPTER_IDS)[number]
 
-const allowRuleSchema = z.string().min(1).refine(isValidAllowRule, {
-  message:
-    'allow rule must be one of: *, guild:*, guild:<id>, guild:<id>/<channel>, team:*, team:<id>, team:<id>/<channel>, tg:*, tg:<chat_id>, channel:<id>, dm:*, dm:<id>, im:*, im:<id>, kakao:*, kakao:<chat>, kakao:dm/*, kakao:group/*, kakao:open/*',
-})
-
 const engagementTriggerSchema = z.enum(['mention', 'reply', 'dm'])
 
 const stickinessSchema = z.union([
@@ -92,8 +87,13 @@ const historySchema = z
     },
   })
 
+// Deliberately non-strict: a stale on-disk file may still carry the
+// legacy `allow` field (`migrateLegacyConfigShape` lifts it into
+// `roles.member.match[]` on load, but a between-reload window can
+// briefly contain both). Zod silently drops unknown keys here, which is
+// exactly what we want — a hard `.strict()` reject would brick recovery
+// for any user mid-migration.
 const adapterSchema = z.object({
-  allow: z.array(allowRuleSchema).default([]),
   engagement: engagementSchema,
   history: historySchema,
   enabled: z.boolean().default(true),
@@ -118,156 +118,6 @@ export const channelsSchema = z
   })
   .default({})
 
-export type AllowRule = string
 export type EngagementConfig = z.infer<typeof engagementSchema>
 export type ChannelAdapterConfig = z.infer<typeof adapterSchema>
-export type KakaotalkAdapterConfig = ChannelAdapterConfig
 export type ChannelsConfig = z.infer<typeof channelsSchema>
-
-// Discord IDs are numeric snowflakes; Slack IDs start with a single uppercase
-// letter (T for teams, C/D/G for channels) followed by alphanumerics; Telegram
-// chat IDs are signed integers (negative for groups, `-100…` for supergroups
-// and channels); KakaoTalk chat IDs are LOCO-protocol decimal integers
-// (large enough to need BigInt at the protocol layer, but rendered as plain
-// decimal strings here). All shapes are accepted on every adapter so the
-// allow list stays declarative — the runtime ensures only the right adapter
-// ever sees its own IDs.
-const RULE_PATTERNS = [
-  /^\*$/,
-  // Discord
-  /^guild:\*$/,
-  /^guild:[0-9]+$/,
-  /^guild:[0-9]+\/[0-9]+$/,
-  /^dm:\*$/,
-  /^dm:[0-9]+$/,
-  // Slack
-  /^team:\*$/,
-  /^team:[A-Z0-9]+$/,
-  /^team:[A-Z0-9]+\/[A-Z0-9]+$/,
-  /^im:\*$/,
-  /^im:[A-Z0-9]+$/,
-  // Telegram (`tg:*` admits all chats; `tg:<chat_id>` scopes to one chat —
-  // numeric, may be negative). There is no team/guild concept; every chat is
-  // identified by its absolute id.
-  /^tg:\*$/,
-  /^tg:-?[0-9]+$/,
-  // KakaoTalk: a single workspace per logged-in account, so the rules scope
-  // by chat-type (1:1 / group / open) rather than by workspace. `kakao:*`
-  // admits every chat the account can see; `kakao:dm/*`, `kakao:group/*`,
-  // `kakao:open/*` admit one chat-type bucket; `kakao:<chat-id>` admits a
-  // single chat. The runtime classifies each chat into a bucket based on
-  // KakaoChat.type at chat-resolver time and surfaces the bucket via the
-  // workspace coordinate.
-  /^kakao:\*$/,
-  /^kakao:dm\/\*$/,
-  /^kakao:group\/\*$/,
-  /^kakao:open\/\*$/,
-  /^kakao:[0-9]+$/,
-  // Shared (channel ids are unique on both platforms)
-  /^channel:[A-Z0-9]+$/,
-  /^channel:-?[0-9]+$/,
-]
-
-function isValidAllowRule(rule: string): boolean {
-  return RULE_PATTERNS.some((p) => p.test(rule))
-}
-
-export function isAllowed(rules: readonly AllowRule[], workspace: string, chat: string): boolean {
-  for (const rule of rules) {
-    if (matchRule(rule, workspace, chat)) return true
-  }
-  return false
-}
-
-// `*`              → every workspace channel + every DM (catch-all)
-// `guild:*`        → every Discord guild channel (no DMs)
-// `guild:G`        → every channel in guild G
-// `guild:G/C`      → channel C in guild G only
-// `team:*`         → every Slack team channel (no DMs)
-// `team:T`         → every channel in team T
-// `team:T/C`       → channel C in team T only
-// `tg:*`           → every Telegram chat (DMs, groups, supergroups, channels)
-// `tg:C`           → Telegram chat C only (signed numeric chat id)
-// `channel:C`      → channel C in any workspace (IDs are globally unique on
-//                    Discord/Slack and Telegram chat ids are also globally
-//                    unique numeric values)
-// `dm:*`           → every Discord DM
-// `dm:C`           → Discord DM channel C only
-// `im:*`           → every Slack DM (im channel)
-// `im:D`           → Slack DM channel D only
-// `kakao:*`            → every KakaoTalk chat the account is in
-// `kakao:dm/*`         → every KakaoTalk 1:1 chat
-// `kakao:group/*`      → every KakaoTalk group chat
-// `kakao:open/*`       → every KakaoTalk open chat
-// `kakao:<id>`         → KakaoTalk chat with the given numeric chat_id
-//
-// `guild:`/`dm:`, `team:`/`im:`, `tg:`, and `kakao:` identify which adapter
-// the rule was written for, but the matcher applies any rule that the
-// (workspace, chat) pair satisfies. That keeps the adapter-side coupling at
-// the schema/UX layer (Slack users write `team:`, Discord users write
-// `guild:`, Telegram users write `tg:`, KakaoTalk users write `kakao:`)
-// without bloating the matching logic. Telegram has no workspace concept;
-// the adapter pins workspace to `'telegram'` so `tg:*` only ever admits
-// Telegram chats. KakaoTalk uses `@kakao-dm` / `@kakao-group` / `@kakao-open`
-// as workspace coordinates so the bucket-* rules are pure prefix matches
-// against `workspace`.
-function matchRule(rule: string, workspace: string, chat: string): boolean {
-  // KakaoTalk workspaces accept the global `*` catch-all or any `kakao:`
-  // rule. Adapter-specific non-kakao rules (`team:*`, `guild:*`, `dm:*`,
-  // `im:*`, `tg:*`) never admit kakao workspaces — those are scoped to
-  // their own adapter's coordinate space and would be meaningless here.
-  // The init wizard still defaults kakaotalk to the narrower `kakao:dm/*`
-  // (group chats with personal accounts are sensitive — every member sees
-  // every reply), so opting into `*` is an explicit, per-adapter decision
-  // made in `channels.kakaotalk.allow`.
-  if (KAKAO_WORKSPACES.has(workspace)) {
-    if (rule === '*') return true
-    if (rule.startsWith('kakao:')) return matchKakaoRule(rule.slice(6), workspace, chat)
-    return false
-  }
-
-  if (rule === '*') return true
-  if (rule.startsWith('kakao:')) return false
-
-  if (workspace === '@dm') {
-    if (rule === 'dm:*' || rule === 'im:*') return true
-    if (rule.startsWith('dm:')) return rule.slice(3) === chat
-    if (rule.startsWith('im:')) return rule.slice(3) === chat
-    if (rule.startsWith('channel:')) return rule.slice(8) === chat
-    return false
-  }
-
-  if (workspace === 'telegram') {
-    if (rule === 'tg:*') return true
-    if (rule.startsWith('tg:')) return rule.slice(3) === chat
-    if (rule.startsWith('channel:')) return rule.slice(8) === chat
-    return false
-  }
-
-  if (rule === 'guild:*' || rule === 'team:*') return true
-  if (rule.startsWith('channel:')) return rule.slice(8) === chat
-  if (rule.startsWith('guild:')) {
-    const body = rule.slice(6)
-    const slash = body.indexOf('/')
-    if (slash === -1) return body === workspace
-    return body.slice(0, slash) === workspace && body.slice(slash + 1) === chat
-  }
-  if (rule.startsWith('team:')) {
-    const body = rule.slice(5)
-    const slash = body.indexOf('/')
-    if (slash === -1) return body === workspace
-    return body.slice(0, slash) === workspace && body.slice(slash + 1) === chat
-  }
-  return false
-}
-
-const KAKAO_WORKSPACES = new Set(['@kakao-dm', '@kakao-group', '@kakao-open'])
-
-function matchKakaoRule(body: string, workspace: string, chat: string): boolean {
-  if (!KAKAO_WORKSPACES.has(workspace)) return false
-  if (body === '*') return true
-  if (body === 'dm/*') return workspace === '@kakao-dm'
-  if (body === 'group/*') return workspace === '@kakao-group'
-  if (body === 'open/*') return workspace === '@kakao-open'
-  return body === chat
-}

package/src/cli/channel.ts

@@ -14,6 +14,7 @@ import {
   type KakaotalkAuthResult,
 } from '@/init'
 import { runKakaotalkBootstrap } from '@/init/kakaotalk-auth'
+import { SecretsKakaoCredentialStore } from '@/secrets/kakao-store'
 
 import { c, done, errorLine } from './ui'
 
@@ -68,6 +69,44 @@ const addSub = defineCommand({
   },
 })
 
+// Only adapters with an interactive credential flow appear here. Bot tokens
+// (Discord/Slack/Telegram) are rotated by editing secrets.json or .env
+// directly — they don't need a guided CLI flow because there's no
+// passcode-on-phone equivalent. KakaoTalk is the only adapter that does, so
+// it's the only adapter that needs `reauth`.
+const REAUTHABLE_ADAPTERS = ['kakaotalk'] as const
+type ReauthableAdapter = (typeof REAUTHABLE_ADAPTERS)[number]
+
+const reauthSub = defineCommand({
+  meta: {
+    name: 'reauth',
+    description:
+      're-authenticate a channel adapter (currently only `kakaotalk`). Use after a stale-token 401 or to rotate the saved password.',
+  },
+  args: {
+    adapter: {
+      type: 'positional',
+      description: `which adapter to re-authenticate (${REAUTHABLE_ADAPTERS.join(' | ')})`,
+      required: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+
+    if (!isInitialized(cwd)) {
+      console.error(errorLine('TypeClaw config file not found. Run `typeclaw init` first, or cd into an agent folder.'))
+      process.exit(1)
+    }
+
+    const configured = await readConfiguredChannels(cwd)
+    const adapter = await resolveReauthableAdapter(args.adapter, configured)
+
+    intro(`Re-authenticating channel: ${CHANNEL_LABELS[adapter]}`)
+
+    await runReauth(cwd, adapter)
+  },
+})
+
 export const channelCommand = defineCommand({
   meta: {
     name: 'channel',
@@ -75,9 +114,162 @@ export const channelCommand = defineCommand({
   },
   subCommands: {
     add: addSub,
+    reauth: reauthSub,
   },
 })
 
+async function resolveReauthableAdapter(
+  requested: string | undefined,
+  configured: Set<ChannelKind>,
+): Promise<ReauthableAdapter> {
+  if (requested !== undefined) {
+    if (!isReauthableAdapter(requested)) {
+      console.error(
+        errorLine(`Adapter "${requested}" does not support reauth. Supported: ${REAUTHABLE_ADAPTERS.join(', ')}.`),
+      )
+      process.exit(1)
+    }
+    if (!configured.has(requested)) {
+      console.error(
+        errorLine(
+          `${CHANNEL_LABELS[requested]} ("${requested}") is not configured in typeclaw.json. Run \`typeclaw channel add ${requested}\` first.`,
+        ),
+      )
+      process.exit(1)
+    }
+    return requested
+  }
+
+  const available = REAUTHABLE_ADAPTERS.filter((kind) => configured.has(kind))
+  if (available.length === 0) {
+    console.error(
+      errorLine(
+        `No reauth-capable channels are configured. Run \`typeclaw channel add ${REAUTHABLE_ADAPTERS[0]}\` first.`,
+      ),
+    )
+    process.exit(1)
+  }
+  if (available.length === 1) return available[0]!
+
+  const selected = await select<ReauthableAdapter>({
+    message: 'Pick a channel to re-authenticate',
+    options: available.map((kind) => ({ value: kind, label: CHANNEL_LABELS[kind] })),
+    initialValue: available[0],
+  })
+  if (isCancel(selected)) {
+    cancel('Aborted.')
+    process.exit(0)
+  }
+  return selected
+}
+
+function isReauthableAdapter(value: string): value is ReauthableAdapter {
+  return (REAUTHABLE_ADAPTERS as ReadonlyArray<string>).includes(value)
+}
+
+async function runReauth(cwd: string, adapter: ReauthableAdapter): Promise<void> {
+  switch (adapter) {
+    case 'kakaotalk':
+      await runKakaotalkReauth(cwd)
+      return
+  }
+}
+
+async function runKakaotalkReauth(cwd: string): Promise<void> {
+  const existingEmail = await readExistingKakaotalkEmail(cwd)
+  const creds = await promptKakaotalkCredentials({ defaultEmail: existingEmail })
+
+  const s = spinner()
+  s.start('Logging in to KakaoTalk...')
+  const result = await runKakaotalkBootstrap({
+    email: creds.email,
+    password: creds.password,
+    agentDir: cwd,
+    callbacks: {
+      onPasscode: (code) => log.info(`Confirm this passcode on your phone: ${code}`),
+    },
+  })
+  if (!result.ok) {
+    s.stop(`KakaoTalk login failed: ${result.reason}`)
+    process.exit(1)
+  }
+  s.stop('KakaoTalk credentials refreshed in secrets.json.')
+
+  await maybePromptReauthRefresh(cwd, 'kakaotalk')
+}
+
+async function readExistingKakaotalkEmail(cwd: string): Promise<string | undefined> {
+  try {
+    const store = new SecretsKakaoCredentialStore({ mode: 'host', secretsPath: `${cwd}/secrets.json` })
+    const account = await store.getAccountWithRenewalFields()
+    return account?.email ?? undefined
+  } catch {
+    // First-time reauth or a brand-new agent dir: no account yet, prompt from scratch.
+    return undefined
+  }
+}
+
+// The renewed tokens are already on disk via secrets.json. What still needs
+// to happen depends on the running adapter's state:
+//   - Container NOT running → nothing to do; next `typeclaw start` picks them up.
+//   - Container running, adapter previously 401'd → `typeclaw reload` re-runs
+//     startAdapter, which loads the fresh tokens.
+//   - Container running, adapter currently live (e.g. proactive rotation) →
+//     reload will report `restart-required` because tokens are captured at
+//     start time; `typeclaw restart` is needed to actually pick them up.
+// We can't reliably distinguish the last two cases from outside the container
+// without calling reload first, so the next-step hints surface both paths.
+async function maybePromptReauthRefresh(cwd: string, adapter: ReauthableAdapter): Promise<void> {
+  const label = CHANNEL_LABELS[adapter]
+  const current = await status({ cwd }).catch(() => null)
+  if (current === null || current.kind !== 'running') {
+    done({
+      title: c.green(`${label} re-authenticated.`),
+      hints: [
+        { label: 'Start the agent:', command: 'typeclaw start' },
+        { label: 'Then check status:', command: 'typeclaw status' },
+      ],
+    })
+    return
+  }
+
+  const restartNow = await confirm({
+    message:
+      'The agent container is running. Restart it now so the adapter picks up the fresh credentials (recommended)?',
+    initialValue: true,
+  })
+  if (isCancel(restartNow) || !restartNow) {
+    done({
+      title: c.green(`${label} re-authenticated.`),
+      hints: [
+        { label: 'Try a live reload first:', command: 'typeclaw reload' },
+        { label: 'If reload reports restart-required:', command: 'typeclaw restart' },
+      ],
+    })
+    return
+  }
+
+  const stopped = await stop({ cwd })
+  if (!stopped.ok) {
+    console.error(errorLine(`Restart failed during stop: ${stopped.reason}`))
+    process.exit(1)
+  }
+  const started = await start({ cwd, preferredHostPort: config.port, cliEntry: process.argv[1] })
+  if (!started.ok) {
+    console.error(errorLine(`Restart failed during start: ${started.reason}`))
+    process.exit(1)
+  }
+  done({
+    title: c.green(
+      `${label} re-authenticated. Restarted ${started.plan.containerName} on host port ${started.hostPort}.`,
+    ),
+    hints: [
+      { label: 'Attach TUI:', command: 'typeclaw tui' },
+      { label: 'Follow logs:', command: 'typeclaw logs -f' },
+    ],
+  })
+}
+
 function validateAdapterArg(adapter: string, configured: Set<ChannelKind>): ChannelKind {
   if (!isChannelKind(adapter)) {
     console.error(errorLine(`Unknown adapter "${adapter}". Expected one of: ${CHANNEL_KINDS.join(', ')}.`))
@@ -86,7 +278,7 @@ function validateAdapterArg(adapter: string, configured: Set<ChannelKind>): Chan
   if (configured.has(adapter)) {
     console.error(
       errorLine(
-        `${CHANNEL_LABELS[adapter]} ("${adapter}") is already configured in typeclaw.json. Edit the file directly to change its allow list.`,
+        `${CHANNEL_LABELS[adapter]} ("${adapter}") is already configured in typeclaw.json. Edit the file directly to change its configuration.`,
       ),
     )
     process.exit(1)
@@ -282,20 +474,24 @@ async function promptTelegramToken(): Promise<string> {
   return token
 }
 
-async function promptKakaotalkCredentials(): Promise<{ email: string; password: string }> {
+async function promptKakaotalkCredentials(
+  opts: { defaultEmail?: string } = {},
+): Promise<{ email: string; password: string }> {
   note(
     [
       'KakaoTalk authentication uses a personal account, registered as a',
       'tablet sub-device. Messages will be sent and received under this',
       'account. Use a non-primary account if possible.',
       '',
-      'After you submit the password, KakaoTalk may ask you to confirm a',
-      'passcode on your phone. Watch the screen for the code.',
+      'On reauth, the existing device_uuid is preserved automatically, so',
+      'subsequent logins for the same account typically skip the phone',
+      'passcode confirmation.',
     ].join('\n'),
     'About to log in to KakaoTalk',
   )
   const email = await text({
     message: 'KakaoTalk email',
+    ...(opts.defaultEmail !== undefined ? { initialValue: opts.defaultEmail, placeholder: opts.defaultEmail } : {}),
     validate: (value) => (value && value.length > 0 ? undefined : 'Email is required'),
   })
   if (isCancel(email)) {

package/src/cli/compose-usage.ts

@@ -0,0 +1,182 @@
+import { styleText } from 'node:util'
+
+import type { ComposeUsageResult } from '@/compose'
+import type { UsageReport, UsageTotals } from '@/usage'
+import { formatCacheHitRate, formatCost, formatTokens } from '@/usage/format'
+
+export type FormatComposeUsageOptions = {
+  useColor?: boolean
+}
+
+type ColorFn = (s: string) => string
+type Palette = {
+  bold: ColorFn
+  dim: ColorFn
+  cyan: ColorFn
+  yellow: ColorFn
+  red: ColorFn
+}
+
+const identity: ColorFn = (s) => s
+const NO_PALETTE: Palette = { bold: identity, dim: identity, cyan: identity, yellow: identity, red: identity }
+const COLOR_PALETTE: Palette = {
+  bold: (s) => styleText('bold', s),
+  dim: (s) => styleText('dim', s),
+  cyan: (s) => styleText('cyan', s),
+  yellow: (s) => styleText('yellow', s),
+  red: (s) => styleText('red', s),
+}
+
+export function formatComposeUsage(result: ComposeUsageResult, opts: FormatComposeUsageOptions = {}): string {
+  const p: Palette = opts.useColor ? COLOR_PALETTE : NO_PALETTE
+
+  if (result.agents.length === 0) {
+    return p.dim(`No typeclaw agents in ${result.rootCwd}.`)
+  }
+
+  const sections: string[] = []
+  sections.push(`${p.bold('USAGE')} ${p.dim(`— ${result.rootCwd}`)}`)
+  sections.push(rangeLine(result.range, p))
+  sections.push('')
+  sections.push(renderTable(result, p))
+
+  const warnings = collectWarnings(result)
+  if (warnings.length > 0) {
+    sections.push('')
+    sections.push(p.yellow(`${warnings.length} warning(s):`))
+    for (const w of warnings) sections.push(`  - ${w}`)
+  }
+
+  return sections.join('\n')
+}
+
+export function formatComposeUsageJson(result: ComposeUsageResult): string {
+  return JSON.stringify(result, null, 2)
+}
+
+function rangeLine(range: ComposeUsageResult['range'], p: Palette): string {
+  if (range.since === null && range.until === null) return p.dim('Range: all time')
+  const since = range.since !== null ? new Date(range.since).toISOString() : '—'
+  const until = range.until !== null ? new Date(range.until).toISOString() : '—'
+  return p.dim(`Range: ${since} → ${until}`)
+}
+
+type Row = {
+  label: string
+  ok: boolean
+  reason: string | null
+  totals: UsageTotals
+}
+
+function renderTable(result: ComposeUsageResult, p: Palette): string {
+  const rows: Row[] = result.results.map((r) => {
+    if (!r.ok) {
+      return { label: r.name, ok: false, reason: r.reason, totals: emptyTotals() }
+    }
+    return { label: r.name, ok: true, reason: null, totals: totalsFrom(r.data) }
+  })
+
+  const total = sumTotals(rows.filter((r) => r.ok).map((r) => r.totals))
+  const headers = ['Agent', 'Sessions', 'Msgs', 'In', 'Out', 'Cache %', 'Cost']
+
+  const dataCells = rows.map((r) => {
+    if (!r.ok) {
+      return [p.red(r.label), p.red(`error: ${r.reason ?? 'unknown'}`), '', '', '', '', '']
+    }
+    return [
+      p.bold(r.label),
+      String(sessionCountFor(r, result)),
+      String(r.totals.messageCount),
+      formatTokens(r.totals.input),
+      formatTokens(r.totals.output),
+      formatCacheHitRate(r.totals.input, r.totals.cacheRead),
+      formatCost(r.totals.cost),
+    ]
+  })
+
+  const totalSessions = result.results.reduce((acc, r) => acc + (r.ok ? r.data.aggregation.bySession.length : 0), 0)
+  const totalCells = [
+    'Total',
+    String(totalSessions),
+    String(total.messageCount),
+    formatTokens(total.input),
+    formatTokens(total.output),
+    formatCacheHitRate(total.input, total.cacheRead),
+    formatCost(total.cost),
+  ]
+
+  return alignTable([headers, ...dataCells, totalCells], p, { totalRowIdx: dataCells.length + 1 })
+}
+
+function sessionCountFor(row: Row, result: ComposeUsageResult): number {
+  const match = result.results.find((r) => r.name === row.label)
+  if (match === undefined || !match.ok) return 0
+  return match.data.aggregation.bySession.length
+}
+
+function collectWarnings(result: ComposeUsageResult): string[] {
+  const out: string[] = []
+  for (const r of result.results) {
+    if (!r.ok) continue
+    for (const w of r.data.warnings) out.push(`[${r.name}] ${w}`)
+  }
+  return out
+}
+
+function totalsFrom(report: UsageReport): UsageTotals {
+  return report.aggregation.total
+}
+
+function emptyTotals(): UsageTotals {
+  return { messageCount: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: 0 }
+}
+
+function sumTotals(parts: UsageTotals[]): UsageTotals {
+  const acc = emptyTotals()
+  for (const t of parts) {
+    acc.messageCount += t.messageCount
+    acc.input += t.input
+    acc.output += t.output
+    acc.cacheRead += t.cacheRead
+    acc.cacheWrite += t.cacheWrite
+    acc.totalTokens += t.totalTokens
+    acc.cost += t.cost
+  }
+  return acc
+}
+
+function alignTable(table: string[][], p: Palette, opts: { totalRowIdx: number }): string {
+  const widths = computeNaturalWidths(table)
+  return table
+    .map((row, idx) => {
+      const cells = row.map((cell, c) => {
+        const pad = widths[c]! - stripAnsi(cell).length
+        return c === 0 ? cell + ' '.repeat(pad) : ' '.repeat(pad) + cell
+      })
+      const line = cells.join('  ')
+      if (idx === 0) return p.cyan(line)
+      if (idx === opts.totalRowIdx) return p.yellow(p.bold(line))
+      return line
+    })
+    .join('\n')
+}
+
+function computeNaturalWidths(table: string[][]): number[] {
+  const cols = table[0]?.length ?? 0
+  const widths: number[] = []
+  for (let c = 0; c < cols; c++) {
+    let w = 0
+    for (const row of table) {
+      const cell = row[c] ?? ''
+      const visible = stripAnsi(cell).length
+      if (visible > w) w = visible
+    }
+    widths.push(w)
+  }
+  return widths
+}
+
+function stripAnsi(s: string): string {
+  // eslint-disable-next-line no-control-regex
+  return s.replace(/\u001b\[[0-9;]*m/g, '')
+}

package/src/cli/compose.ts

@@ -7,6 +7,7 @@ import {
   composeStart,
   composeStatus,
   composeStop,
+  composeUsage,
   type AgentResult,
   type ComposeDoctorReport,
 } from '@/compose'
@@ -14,7 +15,9 @@ import { config } from '@/config'
 import { formatJson, formatReport } from '@/doctor'
 
 import { formatComposeStatus } from './compose-status'
+import { formatComposeUsage, formatComposeUsageJson } from './compose-usage'
 import { c, spinner } from './ui'
+import { parseSince, parseUntil } from './usage-args'
 
 const startSub = defineCommand({
   meta: { name: 'start', description: 'start every agent in immediate subdirectories of cwd' },
@@ -166,6 +169,35 @@ const logsSub = defineCommand({
   },
 })
 
+const usageSub = defineCommand({
+  meta: {
+    name: 'usage',
+    description: 'report LLM token usage and cost across every agent in immediate subdirectories of cwd',
+  },
+  args: {
+    json: { type: 'boolean', description: 'emit the usage report as JSON', default: false },
+    since: { type: 'string', description: "ISO date or relative duration ('today', '7d', '30d')" },
+    until: { type: 'string', description: 'ISO date upper bound (exclusive)' },
+  },
+  async run({ args }) {
+    const since = parseSince(args.since, 'typeclaw compose usage')
+    const until = parseUntil(args.until, 'typeclaw compose usage')
+    const result = await composeUsage({
+      rootCwd: process.cwd(),
+      ...(since !== undefined ? { since } : {}),
+      ...(until !== undefined ? { until } : {}),
+    })
+    if (args.json) {
+      process.stdout.write(`${formatComposeUsageJson(result)}\n`)
+      return
+    }
+    const useColor = Boolean(process.stdout.isTTY) && process.env.NO_COLOR === undefined
+    process.stdout.write(`${formatComposeUsage(result, { useColor })}\n`)
+    const anyFailed = result.results.some((r) => !r.ok)
+    if (anyFailed) process.exit(1)
+  },
+})
+
 const doctorSub = defineCommand({
   meta: { name: 'doctor', description: 'diagnose every agent in immediate subdirectories of cwd' },
   args: {
@@ -212,6 +244,7 @@ export const composeCommand = defineCommand({
     restart: restartSub,
     status: statusSub,
     logs: logsSub,
+    usage: usageSub,
     doctor: doctorSub,
   },
 })