typeclaw 0.3.0 → 0.4.0

package/src/tunnels/log-ring.ts

@@ -0,0 +1,54 @@
+import type { Unsubscribe } from '@/stream'
+
+export const DEFAULT_LOG_RING_MAX_BYTES = 1024 * 1024
+
+export type LogLineSubscriber = (line: string) => void
+
+export type LogRingOptions = {
+  maxBytes?: number
+}
+
+export type LogRing = {
+  append: (line: string) => void
+  snapshot: () => string[]
+  subscribe: (cb: LogLineSubscriber) => Unsubscribe
+}
+
+const encoder = new TextEncoder()
+
+export function createLogRing(options: LogRingOptions = {}): LogRing {
+  const maxBytes = options.maxBytes ?? DEFAULT_LOG_RING_MAX_BYTES
+  if (!Number.isInteger(maxBytes) || maxBytes < 1) {
+    throw new Error('LogRing maxBytes must be a positive integer')
+  }
+
+  const lines: string[] = []
+  const sizes: number[] = []
+  const subscribers = new Set<LogLineSubscriber>()
+  let bytes = 0
+
+  return {
+    append(line: string): void {
+      const size = encoder.encode(line).byteLength
+      lines.push(line)
+      sizes.push(size)
+      bytes += size
+
+      while (bytes > maxBytes && lines.length > 1) {
+        lines.shift()
+        bytes -= sizes.shift() ?? 0
+      }
+
+      for (const subscriber of subscribers) subscriber(line)
+    },
+    snapshot(): string[] {
+      return [...lines]
+    },
+    subscribe(cb: LogLineSubscriber): Unsubscribe {
+      subscribers.add(cb)
+      return () => {
+        subscribers.delete(cb)
+      }
+    },
+  }
+}

package/src/tunnels/manager.ts

@@ -0,0 +1,139 @@
+import type { Stream } from '@/stream'
+
+import { createCloudflareQuickProvider } from './providers/cloudflare-quick'
+import { createExternalProvider } from './providers/external'
+import type { TunnelConfig, TunnelProviderHandle, TunnelState, TunnelUrlChangedPayload } from './types'
+
+export type TunnelManagerLogger = {
+  info: (m: string) => void
+  warn: (m: string) => void
+  error: (m: string) => void
+}
+
+export type TunnelManagerOptions = {
+  tunnels: TunnelConfig[]
+  stream: Stream
+  resolveChannelUpstreamPort?: (channelName: string) => number | null
+  cloudflareQuickBinary?: string
+  logger?: TunnelManagerLogger
+}
+
+export type TunnelManager = {
+  start: () => Promise<void>
+  stop: () => Promise<void>
+  snapshot: () => TunnelState[]
+  urlFor: (tunnelName: string) => string | null
+  tail: (tunnelName: string) => string[]
+  subscribeToLogs: (tunnelName: string, cb: (line: string) => void) => () => void
+}
+
+const consoleLogger: TunnelManagerLogger = {
+  info: (m) => console.log(m),
+  warn: (m) => console.warn(m),
+  error: (m) => console.error(m),
+}
+
+export function createTunnelManager(options: TunnelManagerOptions): TunnelManager {
+  const logger = options.logger ?? consoleLogger
+  const handles = new Map<string, TunnelProviderHandle>()
+
+  for (const config of options.tunnels) {
+    const handle = buildProvider(
+      config,
+      options.resolveChannelUpstreamPort,
+      (url) => publishUrlChange(options.stream, config, url, logger),
+      options.cloudflareQuickBinary,
+    )
+    handles.set(config.name, handle)
+  }
+
+  return {
+    async start(): Promise<void> {
+      await Promise.all(
+        Array.from(handles.values()).map(async (h) => {
+          try {
+            await h.start()
+          } catch (err) {
+            logger.error(
+              `[tunnels] ${h.snapshot().name}: start failed: ${err instanceof Error ? err.message : String(err)}`,
+            )
+          }
+        }),
+      )
+    },
+    async stop(): Promise<void> {
+      await Promise.all(
+        Array.from(handles.values()).map((h) =>
+          h.stop().catch((err: unknown) => {
+            logger.warn(
+              `[tunnels] ${h.snapshot().name}: stop failed: ${err instanceof Error ? err.message : String(err)}`,
+            )
+          }),
+        ),
+      )
+    },
+    snapshot(): TunnelState[] {
+      return Array.from(handles.values()).map((h) => h.snapshot())
+    },
+    urlFor(tunnelName: string): string | null {
+      return handles.get(tunnelName)?.snapshot().url ?? null
+    },
+    tail(tunnelName: string): string[] {
+      return handles.get(tunnelName)?.tail() ?? []
+    },
+    subscribeToLogs(tunnelName: string, cb: (line: string) => void): () => void {
+      return handles.get(tunnelName)?.subscribeToLogs(cb) ?? (() => {})
+    },
+  }
+}
+
+function buildProvider(
+  config: TunnelConfig,
+  resolveChannelUpstreamPort: TunnelManagerOptions['resolveChannelUpstreamPort'],
+  onUrlChange: (url: string) => void,
+  cloudflareQuickBinary: string | undefined,
+): TunnelProviderHandle {
+  switch (config.provider) {
+    case 'external':
+      return createExternalProvider({ config, onUrlChange })
+    case 'cloudflare-quick':
+      return createCloudflareQuickProvider({
+        config,
+        upstreamPort: resolveUpstreamPort(config, resolveChannelUpstreamPort),
+        onUrlChange,
+        binary: cloudflareQuickBinary,
+      })
+  }
+}
+
+function resolveUpstreamPort(
+  config: TunnelConfig,
+  resolveChannelUpstreamPort: TunnelManagerOptions['resolveChannelUpstreamPort'],
+): number {
+  if (config.for.kind === 'manual') {
+    if (config.upstreamPort === undefined) {
+      throw new Error(`tunnel '${config.name}' (cloudflare-quick): upstreamPort is required for manual tunnels`)
+    }
+    return config.upstreamPort
+  }
+
+  const upstreamPort = resolveChannelUpstreamPort?.(config.for.name) ?? null
+  if (upstreamPort === null) {
+    throw new Error(
+      `tunnel '${config.name}' (cloudflare-quick): no upstream port resolved for channel '${config.for.name}'`,
+    )
+  }
+  return upstreamPort
+}
+
+function publishUrlChange(stream: Stream, config: TunnelConfig, url: string, logger: TunnelManagerLogger): void {
+  const payload: TunnelUrlChangedPayload = {
+    kind: 'tunnel-url-changed',
+    tunnelName: config.name,
+    url,
+    for: config.for,
+    rotatedAt: new Date().toISOString(),
+  }
+  stream.publish({ target: { kind: 'broadcast' }, payload })
+  logger.info(`[tunnels] ${config.name}: URL set to ${url}`)
+}

package/src/tunnels/providers/cloudflare-quick.ts

@@ -0,0 +1,189 @@
+import type { Unsubscribe } from '@/stream'
+
+import { createLogRing, type LogLineSubscriber, type LogRing } from '../log-ring'
+import { extractQuickTunnelUrl } from '../quick-url-parser'
+import type { TunnelConfig, TunnelProviderHandle, TunnelState } from '../types'
+
+const DEFAULT_BINARY = 'cloudflared'
+const DEFAULT_RESTART_BACKOFF_MS = [1_000, 2_000, 4_000, 10_000, 30_000]
+const DEFAULT_MAX_FAILURES_WITHOUT_URL = 10
+const DEFAULT_STOP_GRACE_MS = 5_000
+
+export type CloudflareQuickProviderOptions = {
+  config: TunnelConfig
+  upstreamPort: number
+  onUrlChange: (url: string) => void
+  binary?: string
+  restartBackoffMs?: number[]
+  maxConsecutiveFailuresWithoutUrl?: number
+  stopGraceMs?: number
+}
+
+export type CloudflareQuickProviderHandle = TunnelProviderHandle & {
+  tail: () => string[]
+  subscribeToLogs: (cb: LogLineSubscriber) => Unsubscribe
+}
+
+export function createCloudflareQuickProvider(options: CloudflareQuickProviderOptions): CloudflareQuickProviderHandle {
+  const { config, upstreamPort, onUrlChange } = options
+  if (config.provider !== 'cloudflare-quick') {
+    throw new Error(`createCloudflareQuickProvider: provider must be 'cloudflare-quick', got '${config.provider}'`)
+  }
+  if (!Number.isInteger(upstreamPort) || upstreamPort < 1 || upstreamPort > 65535) {
+    throw new Error(`tunnel '${config.name}' (cloudflare-quick): upstreamPort must be a valid TCP port`)
+  }
+
+  const binary = options.binary ?? DEFAULT_BINARY
+  const restartBackoffMs = options.restartBackoffMs ?? DEFAULT_RESTART_BACKOFF_MS
+  const maxConsecutiveFailuresWithoutUrl = options.maxConsecutiveFailuresWithoutUrl ?? DEFAULT_MAX_FAILURES_WITHOUT_URL
+  const stopGraceMs = options.stopGraceMs ?? DEFAULT_STOP_GRACE_MS
+  const logs = createLogRing()
+  const state: TunnelState = {
+    name: config.name,
+    provider: 'cloudflare-quick',
+    for: config.for,
+    url: null,
+    status: 'stopped',
+    lastUrlAt: null,
+    detail: '',
+  }
+
+  let started = false
+  let stopping = false
+  let proc: ReturnType<typeof Bun.spawn> | null = null
+  let retryTimer: ReturnType<typeof setTimeout> | null = null
+  let restartFailuresWithoutUrl = 0
+  let attemptEmittedUrl = false
+
+  async function launch(): Promise<void> {
+    if (!started || stopping) return
+
+    attemptEmittedUrl = false
+    state.status = 'starting'
+    state.detail = 'starting cloudflared'
+    const spawned = Bun.spawn(
+      [binary, 'tunnel', '--url', `http://127.0.0.1:${upstreamPort}`, '--no-autoupdate', '--metrics', '127.0.0.1:0'],
+      { stdout: 'ignore', stderr: 'pipe' },
+    )
+    proc = spawned
+
+    void pumpStderr(spawned.stderr, logs, (line) => {
+      const url = extractQuickTunnelUrl(line)
+      if (url === null) return
+      attemptEmittedUrl = true
+      restartFailuresWithoutUrl = 0
+      state.url = url
+      state.status = 'healthy'
+      state.lastUrlAt = Date.now()
+      state.detail = 'quick tunnel URL emitted'
+      onUrlChange(url)
+    })
+
+    void spawned.exited.then((code) => {
+      if (proc !== spawned) return
+      proc = null
+      if (!started || stopping) return
+      handleExit(code)
+    })
+  }
+
+  function handleExit(code: number): void {
+    if (!attemptEmittedUrl) restartFailuresWithoutUrl += 1
+    if (restartFailuresWithoutUrl >= maxConsecutiveFailuresWithoutUrl) {
+      state.status = 'permanently-failed'
+      state.detail = `cloudflared exited ${code}; retry cap reached before URL emission`
+      return
+    }
+
+    state.status = 'unhealthy'
+    state.detail = `cloudflared exited ${code}; restarting`
+    const delay = restartBackoffMs[Math.min(restartFailuresWithoutUrl - 1, restartBackoffMs.length - 1)] ?? 30_000
+    retryTimer = setTimeout(() => {
+      retryTimer = null
+      void launch()
+    }, delay)
+  }
+
+  return {
+    async start(): Promise<void> {
+      if (started) return
+      started = true
+      stopping = false
+      restartFailuresWithoutUrl = 0
+      await launch()
+    },
+    async stop(): Promise<void> {
+      if (!started && proc === null) return
+      started = false
+      stopping = true
+      if (retryTimer !== null) {
+        clearTimeout(retryTimer)
+        retryTimer = null
+      }
+
+      const running = proc
+      proc = null
+      if (running !== null) {
+        running.kill('SIGTERM')
+        await Promise.race([
+          running.exited,
+          sleep(stopGraceMs).then(() => {
+            running.kill('SIGKILL')
+            return running.exited
+          }),
+        ])
+      }
+
+      stopping = false
+      state.status = 'stopped'
+      state.detail = ''
+    },
+    snapshot(): TunnelState {
+      return { ...state }
+    },
+    tail(): string[] {
+      return logs.snapshot()
+    },
+    subscribeToLogs(cb: LogLineSubscriber): Unsubscribe {
+      return logs.subscribe(cb)
+    },
+  }
+}
+
+async function pumpStderr(
+  stream: ReadableStream<Uint8Array> | null,
+  logs: LogRing,
+  onLine: (line: string) => void,
+): Promise<void> {
+  if (stream === null) return
+  const reader = stream.getReader()
+  const decoder = new TextDecoder()
+  let buffered = ''
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      buffered += decoder.decode(value, { stream: true })
+      let newlineIndex = buffered.indexOf('\n')
+      while (newlineIndex !== -1) {
+        const line = buffered.slice(0, newlineIndex).replace(/\r$/, '')
+        logs.append(line)
+        onLine(line)
+        buffered = buffered.slice(newlineIndex + 1)
+        newlineIndex = buffered.indexOf('\n')
+      }
+    }
+    buffered += decoder.decode()
+    if (buffered !== '') {
+      const line = buffered.replace(/\r$/, '')
+      logs.append(line)
+      onLine(line)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}

package/src/tunnels/providers/external.ts

@@ -0,0 +1,53 @@
+import type { TunnelConfig, TunnelProviderHandle, TunnelState } from '../types'
+
+export type ExternalProviderOptions = {
+  config: TunnelConfig
+  onUrlChange: (url: string) => void
+}
+
+export function createExternalProvider(options: ExternalProviderOptions): TunnelProviderHandle {
+  const { config, onUrlChange } = options
+  if (config.provider !== 'external') {
+    throw new Error(`createExternalProvider: provider must be 'external', got '${config.provider}'`)
+  }
+  const url = config.externalUrl
+  if (url === undefined || url.trim() === '') {
+    throw new Error(`tunnel '${config.name}' (external): externalUrl is required`)
+  }
+
+  let started = false
+  const state: TunnelState = {
+    name: config.name,
+    provider: 'external',
+    for: config.for,
+    url: null,
+    status: 'stopped',
+    lastUrlAt: null,
+    detail: '',
+  }
+
+  return {
+    async start(): Promise<void> {
+      if (started) return
+      started = true
+      state.url = url
+      state.status = 'healthy'
+      state.lastUrlAt = Date.now()
+      onUrlChange(url)
+    },
+    async stop(): Promise<void> {
+      if (!started) return
+      started = false
+      state.status = 'stopped'
+    },
+    snapshot(): TunnelState {
+      return { ...state }
+    },
+    tail(): string[] {
+      return []
+    },
+    subscribeToLogs(): () => void {
+      return () => {}
+    },
+  }
+}

package/src/tunnels/quick-url-parser.ts

@@ -0,0 +1,5 @@
+const QUICK_TUNNEL_URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/
+
+export function extractQuickTunnelUrl(line: string): string | null {
+  return QUICK_TUNNEL_URL_PATTERN.exec(line)?.[0] ?? null
+}

package/src/tunnels/types.ts

@@ -0,0 +1,43 @@
+import type { Unsubscribe } from '@/stream'
+
+export type TunnelProvider = 'external' | 'cloudflare-quick'
+
+export type TunnelFor = { kind: 'channel'; name: string } | { kind: 'manual' }
+
+export type TunnelConfig = {
+  name: string
+  provider: TunnelProvider
+  for: TunnelFor
+  externalUrl?: string
+  upstreamPort?: number
+}
+
+export type TunnelStatus = 'stopped' | 'starting' | 'healthy' | 'unhealthy' | 'permanently-failed'
+
+export type TunnelState = {
+  name: string
+  provider: TunnelProvider
+  for: TunnelFor
+  url: string | null
+  status: TunnelStatus
+  lastUrlAt: number | null
+  detail: string
+}
+
+export type TunnelProviderHandle = {
+  start: () => Promise<void>
+  stop: () => Promise<void>
+  snapshot: () => TunnelState
+  tail: () => string[]
+  subscribeToLogs: (cb: TunnelLogSubscriber) => Unsubscribe
+}
+
+export type TunnelLogSubscriber = (line: string) => void
+
+export type TunnelUrlChangedPayload = {
+  kind: 'tunnel-url-changed'
+  tunnelName: string
+  url: string
+  for: TunnelFor
+  rotatedAt: string
+}

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