typeclaw 0.3.0 → 0.4.0

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'

package/typeclaw.schema.json

@@ -231,6 +231,179 @@
             }
           }
         },
+        "github": {
+          "type": "object",
+          "properties": {
+            "engagement": {
+              "default": {
+                "trigger": [
+                  "mention",
+                  "reply",
+                  "dm"
+                ],
+                "stickiness": {
+                  "perReply": {
+                    "window": 300000
+                  }
+                }
+              },
+              "type": "object",
+              "properties": {
+                "trigger": {
+                  "default": [
+                    "mention",
+                    "reply",
+                    "dm"
+                  ],
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": [
+                      "mention",
+                      "reply",
+                      "dm"
+                    ]
+                  }
+                },
+                "stickiness": {
+                  "default": {
+                    "perReply": {
+                      "window": 300000
+                    }
+                  },
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "const": "off"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "perReply": {
+                          "type": "object",
+                          "properties": {
+                            "window": {
+                              "type": "integer",
+                              "minimum": 1,
+                              "maximum": 86400000
+                            }
+                          },
+                          "required": [
+                            "window"
+                          ]
+                        }
+                      },
+                      "required": [
+                        "perReply"
+                      ]
+                    }
+                  ]
+                }
+              }
+            },
+            "history": {
+              "default": {
+                "prefetch": {
+                  "thread": {
+                    "head": 3,
+                    "tail": 10
+                  },
+                  "channel": {
+                    "tail": 10
+                  }
+                }
+              },
+              "type": "object",
+              "properties": {
+                "prefetch": {
+                  "default": {
+                    "thread": {
+                      "head": 3,
+                      "tail": 10
+                    },
+                    "channel": {
+                      "tail": 10
+                    }
+                  },
+                  "type": "object",
+                  "properties": {
+                    "thread": {
+                      "default": {
+                        "head": 3,
+                        "tail": 10
+                      },
+                      "type": "object",
+                      "properties": {
+                        "head": {
+                          "default": 3,
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 200
+                        },
+                        "tail": {
+                          "default": 10,
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 200
+                        }
+                      }
+                    },
+                    "channel": {
+                      "default": {
+                        "tail": 10
+                      },
+                      "type": "object",
+                      "properties": {
+                        "tail": {
+                          "default": 10,
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 200
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            },
+            "enabled": {
+              "default": true,
+              "type": "boolean"
+            },
+            "webhookUrl": {
+              "type": "string",
+              "format": "uri"
+            },
+            "webhookPort": {
+              "default": 8975,
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            "eventAllowlist": {
+              "default": [
+                "issue_comment.created",
+                "pull_request_review_comment.created",
+                "discussion_comment.created",
+                "issues.opened",
+                "pull_request.opened",
+                "discussion.created",
+                "pull_request_review.submitted"
+              ],
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "repos": {
+              "default": [],
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
         "kakaotalk": {
           "type": "object",
           "properties": {
@@ -723,6 +896,8 @@
           "gh": true,
           "python": true,
           "tmux": true,
+          "cjkFonts": true,
+          "cloudflared": true,
           "append": []
         }
       },
@@ -734,6 +909,8 @@
             "gh": true,
             "python": true,
             "tmux": true,
+            "cjkFonts": true,
+            "cloudflared": true,
             "append": []
           },
           "type": "object",
@@ -778,6 +955,14 @@
                 }
               ]
             },
+            "cjkFonts": {
+              "default": true,
+              "type": "boolean"
+            },
+            "cloudflared": {
+              "default": true,
+              "type": "boolean"
+            },
             "append": {
               "default": [],
               "type": "array",
@@ -826,7 +1011,7 @@
             "type": "array",
             "items": {
               "type": "string",
-              "pattern": "^(tui|cron|subagent(:[a-z][a-z0-9-]*)?|\\*|(slack|discord|telegram|kakao):[^\\s]+)(\\s+[a-zA-Z][a-zA-Z0-9_]*:[^\\s]+)*$"
+              "pattern": "^(tui|cron|subagent(:[a-z][a-z0-9-]*)?|\\*|(slack|discord|telegram|kakao|github):[^\\s]+)(\\s+[a-zA-Z][a-zA-Z0-9_]*:[^\\s]+)*$"
             }
           },
           "permissions": {
@@ -841,6 +1026,74 @@
         "additionalProperties": false
       }
     },
+    "tunnels": {
+      "default": [],
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[a-z0-9][a-z0-9-_]*$"
+          },
+          "provider": {
+            "type": "string",
+            "enum": [
+              "external",
+              "cloudflare-quick"
+            ]
+          },
+          "for": {
+            "oneOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "kind": {
+                    "type": "string",
+                    "const": "channel"
+                  },
+                  "name": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "required": [
+                  "kind",
+                  "name"
+                ]
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "kind": {
+                    "type": "string",
+                    "const": "manual"
+                  }
+                },
+                "required": [
+                  "kind"
+                ]
+              }
+            ]
+          },
+          "externalUrl": {
+            "type": "string",
+            "format": "uri"
+          },
+          "upstreamPort": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 65535
+          }
+        },
+        "required": [
+          "name",
+          "provider",
+          "for"
+        ]
+      }
+    },
     "tool-result-cap": {
       "default": {
         "enabled": true,