typeclaw 0.1.5 → 0.2.0

package/src/cli/role.ts

@@ -0,0 +1,156 @@
+import { intro, note, outro, spinner } from '@clack/prompts'
+import { defineCommand } from 'citty'
+
+import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
+import { findAgentDir } from '@/init'
+import { runClaimSession } from '@/role-claim'
+
+import { c, errorLine } from './ui'
+
+const claimSub = defineCommand({
+  meta: {
+    name: 'claim',
+    description:
+      'claim a channel identity (Slack/Discord/etc.) for a role on this agent. Sends a code via the host CLI; you DM that code back to the bot to prove control of the channel account.',
+  },
+  args: {
+    as: {
+      type: 'string',
+      description: 'which role to claim (owner | member | trusted | <custom>)',
+      default: 'owner',
+    },
+    channel: {
+      type: 'string',
+      description: 'restrict the claim to one channel adapter (slack-bot | discord-bot | telegram-bot | kakaotalk)',
+    },
+    ttl: {
+      type: 'string',
+      description: 'how long the code stays valid, in milliseconds',
+      default: '600000',
+    },
+    url: {
+      type: 'string',
+      description: 'agent websocket url (defaults to ws://127.0.0.1:<host port> discovered from the running container)',
+    },
+  },
+  async run({ args }) {
+    const url = args.url ?? (await defaultUrl())
+    const ttlMs = Number(args.ttl)
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+      console.error(errorLine(`--ttl must be a positive integer (milliseconds); got "${args.ttl}"`))
+      process.exit(1)
+    }
+
+    intro(`Claiming "${args.as}" role`)
+
+    const s = spinner()
+    s.start('Waiting for code...')
+
+    let started = false
+    const result = await runClaimSession({
+      url,
+      role: args.as,
+      ttlMs,
+      ...(args.channel !== undefined ? { channel: args.channel } : {}),
+      onStarted: (payload) => {
+        started = true
+        s.stop('Ready.')
+        const expiresInSec = Math.max(0, Math.round((payload.expiresAt - Date.now()) / 1000))
+        const lines = [
+          `Send this message to your bot as a DM:`,
+          '',
+          `  ${c.bold(payload.code)}`,
+          '',
+          `(expires in ${formatDuration(expiresInSec)})`,
+        ]
+        note(lines.join('\n'), 'Claim code')
+        const waitMsg =
+          payload.channel !== undefined ? `Listening on ${payload.channel}...` : 'Listening on all wired channels...'
+        s.start(waitMsg)
+      },
+    })
+
+    if (!started) {
+      s.stop('Failed to start claim session.')
+    }
+
+    if (result.kind === 'completed') {
+      s.stop(c.green(`Paired as ${result.payload.role}.`))
+      outro(`Match rule added: ${c.bold(result.payload.matchRule)}`)
+      return
+    }
+    if (result.kind === 'error') {
+      s.stop(c.red(`Claim failed: ${result.payload.reason}`))
+      process.exit(1)
+    }
+    s.stop(c.red(`Claim timed out. Run "typeclaw role claim" again to retry.`))
+    process.exit(1)
+  },
+})
+
+const listSub = defineCommand({
+  meta: {
+    name: 'list',
+    description: 'show the roles declared on this agent (typeclaw.json#roles)',
+  },
+  async run() {
+    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    const { loadConfigSync } = await import('@/config')
+    const config = loadConfigSync(cwd)
+    if (!config.roles || Object.keys(config.roles).length === 0) {
+      console.log(c.dim('No roles declared. Run `typeclaw role claim` to add one, or edit typeclaw.json by hand.'))
+      return
+    }
+    for (const [name, role] of Object.entries(config.roles)) {
+      console.log(c.bold(name))
+      if (role.match.length === 0) {
+        console.log(`  ${c.dim('(no match rules)')}`)
+      }
+      for (const rule of role.match) {
+        console.log(`  match: ${describeRule(rule)}`)
+      }
+      if (role.permissions !== undefined) {
+        for (const perm of role.permissions) {
+          console.log(`  permission: ${perm}`)
+        }
+      }
+    }
+  },
+})
+
+export const roleCommand = defineCommand({
+  meta: {
+    name: 'role',
+    description: 'manage role memberships on this agent',
+  },
+  subCommands: {
+    claim: () => Promise.resolve(claimSub),
+    list: () => Promise.resolve(listSub),
+  },
+})
+
+async function defaultUrl(): Promise<string> {
+  const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+  const precheck = await requireContainerRunning({ cwd })
+  if (!precheck.ok) {
+    console.error(errorLine(precheck.reason))
+    process.exit(1)
+  }
+  const port = await resolveHostPort({ cwd })
+  const token = await resolveTuiToken({ cwd })
+  const url = new URL(`ws://127.0.0.1:${port}`)
+  if (token !== null) url.searchParams.set('token', token)
+  return url.toString()
+}
+
+function formatDuration(sec: number): string {
+  if (sec < 60) return `${sec}s`
+  const m = Math.floor(sec / 60)
+  const s = sec % 60
+  if (s === 0) return `${m}m`
+  return `${m}m ${s}s`
+}
+
+function describeRule(rule: unknown): string {
+  return JSON.stringify(rule)
+}

package/src/cli/run.ts

@@ -4,6 +4,8 @@ import { CONTAINER_PORT } from '@/container'
 import { isInitialized } from '@/init'
 import { startAgent } from '@/run'
 
+import { errorLine } from './ui'
+
 export const run = defineCommand({
   meta: {
     name: 'run',
@@ -31,7 +33,7 @@ export const run = defineCommand({
   },
   async run({ args }) {
     if (!isInitialized(process.cwd())) {
-      console.error('TypeClaw config file not found. Run `typeclaw init` first.')
+      console.error(errorLine('TypeClaw config file not found. Run `typeclaw init` first.'))
       process.exit(1)
     }
 

package/src/cli/tui.ts

@@ -1,9 +1,11 @@
 import { defineCommand } from 'citty'
 
-import { resolveHostPort, resolveTuiToken } from '@/container'
+import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
 import { findAgentDir } from '@/init'
 import { createTui } from '@/tui'
 
+import { errorLine } from './ui'
+
 export const tui = defineCommand({
   meta: {
     name: 'tui',
@@ -30,6 +32,11 @@ export const tui = defineCommand({
 
 async function defaultUrl(): Promise<string> {
   const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+  const precheck = await requireContainerRunning({ cwd })
+  if (!precheck.ok) {
+    console.error(errorLine(precheck.reason))
+    process.exit(1)
+  }
   const port = await resolveHostPort({ cwd })
   const token = await resolveTuiToken({ cwd })
   const url = new URL(`ws://127.0.0.1:${port}`)

package/src/cli/usage-args.ts

@@ -0,0 +1,47 @@
+import { startOfDaysAgo, startOfToday } from '@/usage'
+
+export const USAGE_COMMON_ARGS = {
+  json: {
+    type: 'boolean' as const,
+    description: 'emit the usage report as JSON',
+    default: false,
+  },
+  since: {
+    type: 'string' as const,
+    description: "ISO date or relative duration ('today', '7d', '30d')",
+  },
+  until: {
+    type: 'string' as const,
+    description: 'ISO date upper bound (exclusive)',
+  },
+}
+
+export function parseSince(value: unknown, command: string): number | undefined {
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== 'string' || value.length === 0) return undefined
+  if (value === 'today') return startOfToday()
+  const days = /^(\d+)d$/.exec(value)
+  if (days) {
+    const n = Number(days[1])
+    if (n <= 0) exitInvalid(command, 'since', value, "duration must be at least 1 day (e.g. '1d', '7d')")
+    // `Nd` means "last N calendar days INCLUDING today" → window starts
+    // midnight (N-1) days before today.
+    return startOfDaysAgo(n - 1)
+  }
+  const ms = Date.parse(value)
+  if (Number.isFinite(ms)) return ms
+  exitInvalid(command, 'since', value, "expected ISO date, 'today', or '<n>d' (e.g. 7d)")
+}
+
+export function parseUntil(value: unknown, command: string): number | undefined {
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== 'string' || value.length === 0) return undefined
+  const ms = Date.parse(value)
+  if (Number.isFinite(ms)) return ms
+  exitInvalid(command, 'until', value, 'expected ISO date (e.g. 2026-05-01)')
+}
+
+export function exitInvalid(command: string, flag: string, value: string, hint: string): never {
+  process.stderr.write(`${command}: invalid --${flag} value "${value}"; ${hint}\n`)
+  process.exit(2)
+}

package/src/cli/usage.ts

@@ -0,0 +1,97 @@
+import { defineCommand } from 'citty'
+
+import { findAgentDir } from '@/init'
+import { runUsage } from '@/usage'
+import { formatJson, formatReport } from '@/usage/report'
+
+import { parseSince, parseUntil, USAGE_COMMON_ARGS } from './usage-args'
+
+const SUBCOMMANDS = ['daily', 'session', 'models'] as const
+type Subcommand = (typeof SUBCOMMANDS)[number]
+type View = 'summary' | Subcommand
+
+const COMMON_ARGS = {
+  ...USAGE_COMMON_ARGS,
+  cwd: {
+    type: 'string' as const,
+    description: 'override the agent folder',
+  },
+}
+
+const subcommand = (view: View, description: string) =>
+  defineCommand({
+    meta: { name: view, description },
+    args: {
+      ...COMMON_ARGS,
+      ...(view === 'session' ? { limit: { type: 'string' as const, description: 'max sessions (default 20)' } } : {}),
+    },
+    async run({ args }) {
+      await emit(view, args)
+    },
+  })
+
+export const usageCommand = defineCommand({
+  meta: {
+    name: 'usage',
+    description: 'report LLM token usage and cost for this agent folder',
+  },
+  args: COMMON_ARGS,
+  subCommands: {
+    daily: subcommand('daily', 'one row per calendar day'),
+    session: subcommand('session', 'top sessions by cost'),
+    models: subcommand('models', 'one row per provider/model'),
+  },
+  async run({ args }) {
+    // citty invokes both the matched subcommand's `run` and the parent's
+    // `run`. Suppress the summary when a subcommand was dispatched.
+    const first = args._?.[0]
+    if (typeof first === 'string' && (SUBCOMMANDS as readonly string[]).includes(first)) return
+    await emit('summary', args)
+  },
+})
+
+async function emit(view: View, args: Record<string, unknown>): Promise<void> {
+  const cwdArg = typeof args.cwd === 'string' && args.cwd.length > 0 ? args.cwd : process.cwd()
+  const agentDir = findAgentDir(cwdArg) ?? cwdArg
+  const since = parseSince(args.since, 'typeclaw usage')
+  const until = parseUntil(args.until, 'typeclaw usage')
+  const limit = parseLimit(args.limit)
+
+  const report = await runUsage({
+    agentDir,
+    ...(since !== undefined ? { since } : {}),
+    ...(until !== undefined ? { until } : {}),
+  })
+
+  if (args.json === true) {
+    process.stdout.write(`${formatJson(report)}\n`)
+    return
+  }
+
+  const useColor = Boolean(process.stdout.isTTY) && process.env.NO_COLOR === undefined
+  const terminalWidth = resolveTerminalWidth()
+  const text = formatReport(report, {
+    useColor,
+    view,
+    ...(terminalWidth !== undefined ? { terminalWidth } : {}),
+    ...(limit !== undefined ? { limit } : {}),
+  })
+  process.stdout.write(`${text}\n`)
+}
+
+function resolveTerminalWidth(): number | undefined {
+  // process.stdout.columns is undefined when stdout is not a TTY (piped to
+  // less/grep/file). Fall back to $COLUMNS so users can force a width when
+  // piping, and so tests with an inherited COLUMNS env var see the override.
+  if (process.stdout.columns !== undefined) return process.stdout.columns
+  const env = process.env.COLUMNS
+  if (env === undefined || env === '') return undefined
+  const n = Number(env)
+  return Number.isFinite(n) && n > 0 ? n : undefined
+}
+
+function parseLimit(value: unknown): number | undefined {
+  if (typeof value !== 'string') return undefined
+  const n = Number(value)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : undefined
+}

package/src/compose/index.ts

@@ -31,3 +31,4 @@ export {
   type ComposeStopResult,
   type StopSuccess,
 } from './stop'
+export { composeUsage, type ComposeUsageEvent, type ComposeUsageOptions, type ComposeUsageResult } from './usage'

package/src/compose/usage.ts

@@ -0,0 +1,65 @@
+import { runUsage, type UsageReport } from '@/usage'
+
+import { discoverAgents, type AgentEntry } from './discover'
+import type { AgentResult } from './start'
+
+export type ComposeUsageEvent =
+  | { kind: 'agent-start'; name: string }
+  | { kind: 'agent-done'; name: string; result: AgentResult<UsageReport> }
+
+export type ComposeUsageOptions = {
+  rootCwd: string
+  since?: number
+  until?: number
+  onProgress?: (event: ComposeUsageEvent) => void
+}
+
+export type ComposeUsageResult = {
+  rootCwd: string
+  range: { since: number | null; until: number | null }
+  agents: AgentEntry[]
+  results: AgentResult<UsageReport>[]
+}
+
+// Fans out `runUsage` across every typeclaw agent in `rootCwd`'s immediate
+// subdirectories. Per-agent failures are captured as `AgentResult` rather than
+// thrown — one corrupt sessions/ dir shouldn't blank out the whole report.
+export async function composeUsage({
+  rootCwd,
+  since,
+  until,
+  onProgress,
+}: ComposeUsageOptions): Promise<ComposeUsageResult> {
+  const agents = discoverAgents(rootCwd)
+  const results = await Promise.all(
+    agents.map(async (agent): Promise<AgentResult<UsageReport>> => {
+      onProgress?.({ kind: 'agent-start', name: agent.name })
+      const result = await runOne(agent, since, until)
+      onProgress?.({ kind: 'agent-done', name: agent.name, result })
+      return result
+    }),
+  )
+  return {
+    rootCwd,
+    range: { since: since ?? null, until: until ?? null },
+    agents,
+    results,
+  }
+}
+
+async function runOne(
+  agent: AgentEntry,
+  since: number | undefined,
+  until: number | undefined,
+): Promise<AgentResult<UsageReport>> {
+  try {
+    const report = await runUsage({
+      agentDir: agent.cwd,
+      ...(since !== undefined ? { since } : {}),
+      ...(until !== undefined ? { until } : {}),
+    })
+    return { name: agent.name, ok: true, data: report }
+  } catch (error) {
+    return { name: agent.name, ok: false, reason: error instanceof Error ? error.message : String(error) }
+  }
+}