typeclaw 0.3.0 → 0.3.1

package/src/usage/aggregate.ts

@@ -1,4 +1,5 @@
-import type { AssistantRow } from './scan'
+import type { AssistantRow, OriginKind } from './scan'
+import { ORIGIN_KINDS } from './scan'
 
 export type UsageTotals = {
   messageCount: number
@@ -18,13 +19,16 @@ export type SessionUsage = UsageTotals & {
   firstAt: number
   lastAt: number
   models: string[]
+  originKind: OriginKind
 }
+export type OriginUsage = UsageTotals & { originKind: OriginKind; sessionCount: number }
 
 export type Aggregation = {
   total: UsageTotals
   byDay: DailyUsage[]
   byModel: ModelUsage[]
   bySession: SessionUsage[]
+  byOrigin: OriginUsage[]
 }
 
 export async function aggregate(rows: AsyncIterable<AssistantRow>): Promise<Aggregation> {
@@ -32,6 +36,7 @@ export async function aggregate(rows: AsyncIterable<AssistantRow>): Promise<Aggr
   const byDay = new Map<string, DailyUsage & { _sessionIds: Set<string> }>()
   const byModel = new Map<string, ModelUsage>()
   const bySession = new Map<string, SessionUsage & { _modelSet: Set<string> }>()
+  const byOrigin = new Map<OriginKind, OriginUsage & { _sessionIds: Set<string> }>()
 
   for await (const row of rows) {
     addInto(total, row)
@@ -66,6 +71,7 @@ export async function aggregate(rows: AsyncIterable<AssistantRow>): Promise<Aggr
       lastAt: row.timestamp,
       models: [],
       _modelSet: new Set<string>(),
+      originKind: row.originKind,
     }
     addInto(sessionBucket, row)
     sessionBucket.firstAt = Math.min(sessionBucket.firstAt, row.timestamp)
@@ -73,6 +79,17 @@ export async function aggregate(rows: AsyncIterable<AssistantRow>): Promise<Aggr
     sessionBucket._modelSet.add(modelKey)
     sessionBucket.models = [...sessionBucket._modelSet]
     bySession.set(sessionKey, sessionBucket)
+
+    const originBucket = byOrigin.get(row.originKind) ?? {
+      ...emptyTotals(),
+      originKind: row.originKind,
+      sessionCount: 0,
+      _sessionIds: new Set<string>(),
+    }
+    addInto(originBucket, row)
+    originBucket._sessionIds.add(sessionKey)
+    originBucket.sessionCount = originBucket._sessionIds.size
+    byOrigin.set(row.originKind, originBucket)
   }
 
   return {
@@ -80,9 +97,21 @@ export async function aggregate(rows: AsyncIterable<AssistantRow>): Promise<Aggr
     byDay: [...byDay.values()].map(({ _sessionIds: _, ...rest }) => rest).sort((a, b) => a.date.localeCompare(b.date)),
     byModel: [...byModel.values()].sort((a, b) => b.cost - a.cost),
     bySession: [...bySession.values()].map(({ _modelSet: _, ...rest }) => rest).sort((a, b) => b.cost - a.cost),
+    byOrigin: [...byOrigin.values()]
+      .map(({ _sessionIds: _, ...rest }) => rest)
+      .sort((a, b) => originSortIndex(a.originKind) - originSortIndex(b.originKind)),
   }
 }
 
+// Stable presentation order for the byOrigin table. Matches ORIGIN_KINDS so
+// the renderer doesn't need to know about ordering. 'unknown' is pinned last
+// because it represents legacy/malformed data the user probably cares about
+// least.
+function originSortIndex(kind: OriginKind): number {
+  const idx = (ORIGIN_KINDS as readonly OriginKind[]).indexOf(kind)
+  return idx === -1 ? Number.MAX_SAFE_INTEGER : idx
+}
+
 function emptyTotals(): UsageTotals {
   return { messageCount: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: 0 }
 }

package/src/usage/index.ts

@@ -4,8 +4,9 @@ import type { Aggregation } from './aggregate'
 import { aggregate } from './aggregate'
 import { scanAssistantRows } from './scan'
 
-export type { Aggregation, DailyUsage, ModelUsage, SessionUsage, UsageTotals } from './aggregate'
-export type { AssistantRow } from './scan'
+export type { Aggregation, DailyUsage, ModelUsage, OriginUsage, SessionUsage, UsageTotals } from './aggregate'
+export type { AssistantRow, OriginKind } from './scan'
+export { ORIGIN_KINDS } from './scan'
 
 export type UsageReport = {
   generatedAt: number

package/src/usage/report.ts

@@ -1,12 +1,13 @@
 import { styleText } from 'node:util'
 
-import type { ModelUsage, UsageTotals } from './aggregate'
+import type { ModelUsage, OriginUsage, UsageTotals } from './aggregate'
 import { formatCacheHitRate, formatCost, formatTokens, isoDay } from './format'
 import type { UsageReport } from './index'
+import type { OriginKind } from './scan'
 
 export type FormatOptions = {
   useColor?: boolean
-  view?: 'summary' | 'daily' | 'session' | 'models'
+  view?: 'summary' | 'daily' | 'session' | 'models' | 'origin'
   limit?: number
   // Terminal width hint used to size the elastic Item column. Omit to render
   // without truncation (tests, piped output where columns is undefined).
@@ -26,6 +27,8 @@ export function formatReport(report: UsageReport, opts: FormatOptions = {}): str
       return renderSessions(report, ctx, opts.limit ?? 20)
     case 'models':
       return renderModels(report, ctx, opts.limit)
+    case 'origin':
+      return renderOrigin(report, ctx)
   }
 }
 
@@ -58,12 +61,20 @@ function renderSummary(report: UsageReport, ctx: RenderCtx): string {
 
   if (aggregation.byDay.length > 0) {
     sections.push('')
+    const trend = renderDailyTrend(aggregation.byDay, ctx)
+    if (trend !== null) sections.push(trend, '')
     sections.push(header('By day (most recent first)', ctx))
     const recent = aggregation.byDay.slice(-7).reverse()
     const dayRows = recent.map((d) => ({ label: d.date, totals: d as UsageTotals }))
     sections.push(renderTotalsTable(dayRows, ctx, { total: totalOfRows(dayRows) }))
   }
 
+  if (aggregation.byOrigin.length > 0) {
+    sections.push('')
+    sections.push(header('By origin', ctx))
+    sections.push(renderOriginTable(aggregation.byOrigin, ctx))
+  }
+
   if (aggregation.byModel.length > 0) {
     sections.push('')
     sections.push(header('By model', ctx))
@@ -84,6 +95,79 @@ function renderSummary(report: UsageReport, ctx: RenderCtx): string {
   return sections.join('\n')
 }
 
+function renderOrigin(report: UsageReport, ctx: RenderCtx): string {
+  const sections: string[] = [sectionTitle('USAGE BY ORIGIN', report.agentDir, ctx)]
+  if (report.aggregation.byOrigin.length === 0) {
+    sections.push(dim('No assistant turns recorded yet.', ctx))
+    return sections.join('\n')
+  }
+  sections.push(renderOriginTable(report.aggregation.byOrigin, ctx))
+  return sections.join('\n')
+}
+
+// Single source of truth for the origin breakdown table used by both the
+// summary view and the dedicated `usage origin` subcommand. Matches the
+// column shape of renderTotalsTable's other callers (byDay, byModel) plus
+// one extra column for session count — deliberately plain numbers rather
+// than a proportional bar, since the Cost column already lets the eye sort
+// rows by spend and an extra "share of max" bar adds no information that
+// isn't already in the report.
+function renderOriginTable(byOrigin: readonly OriginUsage[], ctx: RenderCtx): string {
+  const rows = byOrigin.map((o) => ({
+    label: renderOriginLabel(o.originKind, ctx),
+    totals: o as UsageTotals,
+    extra: String(o.sessionCount),
+    extraTruncatable: false,
+  }))
+  return renderTotalsTable(rows, ctx, {
+    extraHeader: 'Sessions',
+    total: totalOfRows(rows),
+  })
+}
+
+// Glyph + colored label for each origin kind. The glyphs are chosen to be
+// instantly readable in a dense table: ▶ for TUI (interactive), ⏱ for cron
+// (time-triggered), # for channel (chat-room sigil), ↳ for subagent (child),
+// ? for unknown. ASCII fallbacks are not provided — the codebase already
+// requires unicode for `…` `●` `✓` etc. on other commands.
+function renderOriginLabel(kind: OriginKind, ctx: RenderCtx): string {
+  switch (kind) {
+    case 'tui':
+      return `${color('cyan', '▶', ctx)} ${'tui'}`
+    case 'cron':
+      return `${color('magenta', '⏱', ctx)} ${'cron'}`
+    case 'channel':
+      return `${color('green', '#', ctx)} ${'channel'}`
+    case 'subagent':
+      return `${color('yellow', '↳', ctx)} ${'subagent'}`
+    case 'unknown':
+      return `${dim('?', ctx)} ${dim('unknown', ctx)}`
+  }
+}
+
+// Sparkline trend across the full byDay range, scaled to the row's max cost.
+// Returns null when there are fewer than 2 days (a single point conveys no
+// trend information). The 8-level Unicode block scale `▁▂▃▄▅▆▇█` lets us
+// pack ~80 days into a one-line glance — wider than any table-based view
+// could fit at terminal widths under ~160 columns.
+const SPARK_GLYPHS = '▁▂▃▄▅▆▇█'
+
+function renderDailyTrend(byDay: readonly { date: string; cost: number }[], ctx: RenderCtx): string | null {
+  if (byDay.length < 2) return null
+  const costs = byDay.map((d) => d.cost)
+  const max = costs.reduce((m, c) => Math.max(m, c), 0)
+  if (max <= 0) return null
+  const spark = costs
+    .map((c) => {
+      const idx = Math.min(SPARK_GLYPHS.length - 1, Math.max(0, Math.round((c / max) * (SPARK_GLYPHS.length - 1))))
+      return SPARK_GLYPHS[idx]!
+    })
+    .join('')
+  const first = byDay[0]!.date
+  const last = byDay[byDay.length - 1]!.date
+  return `${dim('Trend (cost):', ctx)} ${color('cyan', spark, ctx)}  ${dim(`${first} → ${last}`, ctx)}`
+}
+
 function renderDaily(report: UsageReport, ctx: RenderCtx, limit: number | undefined): string {
   const days = limit !== undefined ? report.aggregation.byDay.slice(-limit) : report.aggregation.byDay
   if (days.length === 0) return dim('No usage in range.', ctx)
@@ -100,8 +184,9 @@ function renderSessions(report: UsageReport, ctx: RenderCtx, limit: number): str
   const rows = sessions.map((s) => {
     const firstModel = s.models[0]
     const extra = s.models.length > 1 ? `${s.models.length} models` : modelIdFromKey(firstModel)
+    const originGlyph = originGlyphOnly(s.originKind, ctx)
     return {
-      label: `${color('magenta', s.sessionId.slice(0, 12), ctx)}  ${dim(isoDay(s.firstAt), ctx)}`,
+      label: `${originGlyph}  ${color('magenta', s.sessionId.slice(0, 12), ctx)}  ${dim(isoDay(s.firstAt), ctx)}`,
       totals: s as UsageTotals,
       extra,
       extraTruncatable: s.models.length === 1,
@@ -113,6 +198,21 @@ function renderSessions(report: UsageReport, ctx: RenderCtx, limit: number): str
   ].join('\n')
 }
 
+function originGlyphOnly(kind: OriginKind, ctx: RenderCtx): string {
+  switch (kind) {
+    case 'tui':
+      return color('cyan', '▶', ctx)
+    case 'cron':
+      return color('magenta', '⏱', ctx)
+    case 'channel':
+      return color('green', '#', ctx)
+    case 'subagent':
+      return color('yellow', '↳', ctx)
+    case 'unknown':
+      return dim('?', ctx)
+  }
+}
+
 function renderModels(report: UsageReport, ctx: RenderCtx, limit: number | undefined): string {
   const models = limit !== undefined ? report.aggregation.byModel.slice(0, limit) : report.aggregation.byModel
   if (models.length === 0) return dim('No models in range.', ctx)

package/src/usage/scan.ts

@@ -1,6 +1,14 @@
 import { readdir } from 'node:fs/promises'
 import { join } from 'node:path'
 
+// Recognised origin kinds. Keep aligned with SessionOrigin's discriminator in
+// src/agent/session-origin.ts. The 'unknown' bucket catches sessions written
+// before origin stamping landed AND sessions whose session-meta line is
+// malformed or missing — surfacing them under one explicit label is more
+// honest than silently dropping them.
+export const ORIGIN_KINDS = ['tui', 'cron', 'channel', 'subagent', 'unknown'] as const
+export type OriginKind = (typeof ORIGIN_KINDS)[number]
+
 // Narrow projection: session files can grow into tens of MB on long-lived
 // agents, so we deliberately drop content/tool blocks before aggregation.
 export type AssistantRow = {
@@ -15,6 +23,7 @@ export type AssistantRow = {
   cacheWrite: number
   totalTokens: number
   cost: number
+  originKind: OriginKind
 }
 
 export type ScanOptions = {
@@ -66,6 +75,13 @@ async function* readSessionFile(file: string, opts: ScanOptions): AsyncGenerator
   }
   const decoder = new TextDecoder()
   let buf = ''
+  // First-stamp-wins per file. Once a `typeclaw.session-meta` custom entry
+  // pins the origin, later entries with the same customType are ignored —
+  // session-resume code paths may legitimately re-stamp on reopen, and the
+  // earliest one is the authoritative one for the session's first turn.
+  // Stays 'unknown' for legacy files (no stamp at all) so usage attribution
+  // surfaces them as a distinct bucket rather than dropping the rows.
+  const ctx: ParseCtx = { originKind: 'unknown', originPinned: false }
   try {
     for await (const chunk of stream) {
       buf += decoder.decode(chunk, { stream: true })
@@ -73,7 +89,7 @@ async function* readSessionFile(file: string, opts: ScanOptions): AsyncGenerator
       while (nl !== -1) {
         const line = buf.slice(0, nl)
         buf = buf.slice(nl + 1)
-        const row = parseLine(line, file, basename, opts)
+        const row = parseLine(line, file, basename, opts, ctx)
         if (row !== null) yield row
         nl = buf.indexOf('\n')
       }
@@ -86,17 +102,20 @@ async function* readSessionFile(file: string, opts: ScanOptions): AsyncGenerator
   // half-written record from a live writer is silently skipped (parseLine
   // returns null and does NOT warn for the tail).
   if (buf.length > 0) {
-    const row = parseLine(buf, file, basename, opts, { isTail: true })
+    const row = parseLine(buf, file, basename, opts, ctx, { isTail: true })
     if (row !== null) yield row
   }
 }
 
+type ParseCtx = { originKind: OriginKind; originPinned: boolean }
+
 function parseLine(
   line: string,
   file: string,
   basename: string,
   opts: ScanOptions,
-  ctx: { isTail?: boolean } = {},
+  ctx: ParseCtx,
+  flags: { isTail?: boolean } = {},
 ): AssistantRow | null {
   const trimmed = line.trim()
   if (trimmed === '') return null
@@ -106,7 +125,18 @@ function parseLine(
     entry = JSON.parse(trimmed)
   } catch {
     // Silently skip the trailing tail: a live writer may be mid-append.
-    if (ctx.isTail !== true) opts.onWarn?.(`skipping malformed JSONL line in ${basename}`)
+    if (flags.isTail !== true) opts.onWarn?.(`skipping malformed JSONL line in ${basename}`)
+    return null
+  }
+
+  if (isSessionMetaCustomEntry(entry)) {
+    if (!ctx.originPinned) {
+      const kind = entry.data.origin.kind
+      if ((ORIGIN_KINDS as readonly string[]).includes(kind)) {
+        ctx.originKind = kind as OriginKind
+        ctx.originPinned = true
+      }
+    }
     return null
   }
 
@@ -134,9 +164,34 @@ function parseLine(
     cacheWrite: numberOrZero(u.cacheWrite),
     totalTokens: numberOrZero(u.totalTokens),
     cost: numberOrZero(u.cost?.total),
+    originKind: ctx.originKind,
   }
 }
 
+// Pi-coding-agent persists `appendCustomEntry(customType, data)` calls as
+// `{type:"custom", customType, data, id, parentId, timestamp}` lines. We
+// stamp our origin block with customType `typeclaw.session-meta` (constant
+// kept in src/agent/session-meta.ts; duplicated as a literal here to keep
+// the usage subsystem free of agent-stack imports — a Grep across the repo
+// is the chosen drift guard).
+type SessionMetaCustomEntry = {
+  type: 'custom'
+  customType: 'typeclaw.session-meta'
+  data: { origin: { kind: string } }
+}
+
+function isSessionMetaCustomEntry(value: unknown): value is SessionMetaCustomEntry {
+  if (typeof value !== 'object' || value === null) return false
+  const v = value as Record<string, unknown>
+  if (v.type !== 'custom') return false
+  if (v.customType !== 'typeclaw.session-meta') return false
+  if (typeof v.data !== 'object' || v.data === null) return false
+  const d = v.data as Record<string, unknown>
+  if (typeof d.origin !== 'object' || d.origin === null) return false
+  const o = d.origin as Record<string, unknown>
+  return typeof o.kind === 'string'
+}
+
 type MessageEntry = { type: 'message'; message: { role: string; [k: string]: unknown } }
 type AssistantMessageShape = {
   role: 'assistant'