@ericsanchezok/synergy-workbench 0.0.0-stage → 3.1.1

package/src/stats/routes/usage.ts

@@ -0,0 +1,103 @@
+import { Hono } from "hono"
+import { describeRoute, resolver, validator } from "hono-openapi"
+import { z } from "zod"
+import { Usage, UsageSchema } from "@ericsanchezok/synergy-harness/usage"
+import { errors } from "@ericsanchezok/synergy-server/server/error"
+
+const Query = UsageSchema.Filter.extend({
+  includeDescendants: z
+    .enum(["true", "false"])
+    .default("true")
+    .transform((value) => value === "true"),
+  from: z.coerce.number().int().nonnegative().safe().optional(),
+  to: z.coerce.number().int().nonnegative().safe().optional(),
+})
+const PageQuery = Query.extend({
+  cursor: z.string().max(4096).optional(),
+  limit: z.coerce.number().int().min(1).max(500).default(100),
+})
+const Clear = z.object({ scope: UsageSchema.Filter, throughRevision: z.number().int().nonnegative() }).strict()
+const Cleared = z.object({
+  removed: z.number(),
+  activeRetained: z.number(),
+  newerRetained: z.number(),
+  unattributedRetained: z.number().describe("Owner-level gaps retained because the clear selects a specific run"),
+  revision: z.number(),
+})
+const response = (schema: z.ZodType, description: string) => ({
+  200: { description, content: { "application/json": { schema: resolver(schema) } } },
+  ...errors(400),
+})
+
+export const UsageRoute = () =>
+  new Hono()
+    .get(
+      "/",
+      describeRoute({
+        operationId: "global.stats.usage",
+        summary: "Get canonical usage statistics",
+        description:
+          "Read retained usage facts with explicit unknowns, billing bases, transport timing, attribution and migration coverage. Time ranges are half-open; request days use the sent timestamp in the returned timezone.",
+        responses: response(Usage.Summary, "Canonical usage summary"),
+      }),
+      validator("query", Query),
+      async (c) => {
+        try {
+          return c.json(await Usage.summary(c.req.valid("query")))
+        } catch (error) {
+          if (UsageSchema.InvalidQuery.isInstance(error)) return c.json({ message: error.data.message }, 400)
+          throw error
+        }
+      },
+    )
+    .get(
+      "/records",
+      describeRoute({
+        operationId: "global.stats.usageRecords",
+        summary: "Page through retained usage records",
+        description:
+          "Read compact records without prompts, tool arguments or raw response content. Cursor filters must match the initial request. Each record has a revision; reconnect through the summary endpoint.",
+        responses: response(Usage.Page, "Usage records"),
+      }),
+      validator("query", PageQuery),
+      async (c) => {
+        const { cursor, limit, ...scope } = c.req.valid("query")
+        try {
+          return c.json(await Usage.records(scope, { cursor, limit }))
+        } catch (error) {
+          if (UsageSchema.InvalidQuery.isInstance(error)) return c.json({ message: error.data.message }, 400)
+          throw error
+        }
+      },
+    )
+    .post(
+      "/rebuild",
+      describeRoute({
+        operationId: "global.stats.usageRebuild",
+        summary: "Schedule or resume historical usage capture",
+        description:
+          "Returns the durable background job. Rebuilding preserves existing facts, original pricing and explicit deletion markers.",
+        responses: response(UsageSchema.Rebuild, "Durable rebuild job"),
+      }),
+      async (c) => c.json(await Usage.rebuild()),
+    )
+    .delete(
+      "/records",
+      describeRoute({
+        operationId: "global.stats.usageClear",
+        summary: "Clear explicitly scoped terminal usage records",
+        description:
+          "Requires an explicit Scope, session or time range and the summary revision to clear through. Active and newer records are retained. Run-filtered clears also retain unattributed owner-level gaps. Cleared identities cannot be restored by a rebuild.",
+        responses: response(Cleared, "Cleared and retained record counts"),
+      }),
+      validator("json", Clear),
+      async (c) => {
+        const { scope, throughRevision } = c.req.valid("json")
+        try {
+          return c.json(await Usage.clear(scope, throughRevision))
+        } catch (error) {
+          if (UsageSchema.InvalidQuery.isInstance(error)) return c.json({ message: error.data.message }, 400)
+          throw error
+        }
+      },
+    )

package/src/stats/storage.ts

@@ -0,0 +1,78 @@
+import { Storage } from "@ericsanchezok/synergy-harness/storage/storage"
+import { StoragePath } from "@ericsanchezok/synergy-harness/storage/path"
+import { Identifier } from "@ericsanchezok/synergy-harness/id/id"
+import type { StatsWatermark, SessionDigest, DailyBucket, StatsSnapshot } from "./types"
+
+export namespace StatsStorage {
+  export async function getWatermark(): Promise<StatsWatermark | undefined> {
+    try {
+      return await Storage.read<StatsWatermark>(StoragePath.statsWatermark())
+    } catch (e) {
+      if (e instanceof Storage.NotFoundError) return undefined
+      throw e
+    }
+  }
+
+  export async function setWatermark(watermark: StatsWatermark): Promise<void> {
+    await Storage.write(StoragePath.statsWatermark(), watermark)
+  }
+
+  export async function getDigest(sessionID: string): Promise<SessionDigest | undefined> {
+    try {
+      return await Storage.read<SessionDigest>(StoragePath.statsDigest(sessionID as Identifier.SessionID))
+    } catch (e) {
+      if (e instanceof Storage.NotFoundError) return undefined
+      throw e
+    }
+  }
+
+  export async function setDigest(digest: SessionDigest): Promise<void> {
+    await Storage.write(StoragePath.statsDigest(digest.sessionID as Identifier.SessionID), digest)
+  }
+
+  export async function removeDigest(sessionID: string): Promise<void> {
+    await Storage.remove(StoragePath.statsDigest(sessionID as Identifier.SessionID))
+  }
+
+  export async function listDigestIDs(): Promise<string[]> {
+    return Storage.scan(StoragePath.statsDigestsRoot())
+  }
+
+  export async function getAllDigests(): Promise<SessionDigest[]> {
+    const ids = await listDigestIDs()
+    if (ids.length === 0) return []
+    const keys = ids.map((id) => StoragePath.statsDigest(id as Identifier.SessionID))
+    const results = await Storage.readMany<SessionDigest>(keys)
+    return results.filter((d): d is SessionDigest => d !== undefined)
+  }
+
+  export async function getDailyBucket(day: string): Promise<DailyBucket | undefined> {
+    try {
+      return await Storage.read<DailyBucket>(StoragePath.statsDaily(day))
+    } catch (e) {
+      if (e instanceof Storage.NotFoundError) return undefined
+      throw e
+    }
+  }
+
+  export async function setDailyBucket(day: string, bucket: DailyBucket): Promise<void> {
+    await Storage.write(StoragePath.statsDaily(day), bucket)
+  }
+
+  export async function listDailyKeys(): Promise<string[]> {
+    return Storage.scan(StoragePath.statsDailyRoot())
+  }
+
+  export async function getSnapshot(): Promise<StatsSnapshot | undefined> {
+    try {
+      return await Storage.read<StatsSnapshot>(StoragePath.statsSnapshot())
+    } catch (e) {
+      if (e instanceof Storage.NotFoundError) return undefined
+      throw e
+    }
+  }
+
+  export async function setSnapshot(snapshot: StatsSnapshot): Promise<void> {
+    await Storage.write(StoragePath.statsSnapshot(), snapshot)
+  }
+}

package/src/stats/types.ts

@@ -0,0 +1,351 @@
+import z from "zod"
+import { RolloutAccounting } from "@ericsanchezok/synergy-harness/session/rollout/accounting"
+import { ExecutionPresentation } from "../execution/presentation"
+
+// ---------------------------------------------------------------------------
+// Shared primitives
+// ---------------------------------------------------------------------------
+
+export const TokenBreakdown = z.object({
+  input: z.number(),
+  output: z.number(),
+  reasoning: z.number(),
+  cache: z.object({
+    read: z.number(),
+    write: z.number(),
+  }),
+})
+export type TokenBreakdown = z.infer<typeof TokenBreakdown>
+
+/** YYYY-MM-DD string */
+export type DayKey = string
+
+/** ISO week string like "2026-W17" */
+export type WeekKey = string
+
+/** YYYY-MM string */
+export type MonthKey = string
+
+// ---------------------------------------------------------------------------
+// Dimension 1 — Overview
+// ---------------------------------------------------------------------------
+
+export const OverviewStats = z.object({
+  totalSessions: z.number(),
+  activeSessions: z.number(),
+  archivedSessions: z.number(),
+  totalMessages: z.number(),
+  totalTurns: z.number(),
+  totalDays: z.number(),
+  longestStreak: z.number(),
+  currentStreak: z.number(),
+  projectCount: z.number(),
+})
+export type OverviewStats = z.infer<typeof OverviewStats>
+
+// ---------------------------------------------------------------------------
+// Dimension 2 — Tokens & Cost
+// ---------------------------------------------------------------------------
+
+export const TokenCostStats = z.object({
+  tokens: TokenBreakdown,
+  cost: z.number(),
+  accounting: RolloutAccounting.Summary.optional(),
+  costPresentation: ExecutionPresentation.Cost.optional(),
+  cacheHitRate: z.number(),
+  avgCostPerTurn: z.number(),
+  avgTokensPerTurn: z.number(),
+  dailyCost: z.number(),
+  dailyTokens: z.number(),
+})
+export type TokenCostStats = z.infer<typeof TokenCostStats>
+
+// ---------------------------------------------------------------------------
+// Dimension 3 — By Model  (providerID/modelID → usage)
+// ---------------------------------------------------------------------------
+
+export const ModelUsage = z.object({
+  providerID: z.string(),
+  modelID: z.string(),
+  messages: z.number(),
+  turns: z.number(),
+  tokens: TokenBreakdown,
+  cost: z.number(),
+  accounting: RolloutAccounting.Summary.optional(),
+  avgResponseMs: z.number(),
+})
+export type ModelUsage = z.infer<typeof ModelUsage>
+
+export const ModelStats = z.object({
+  models: z.array(ModelUsage),
+})
+export type ModelStats = z.infer<typeof ModelStats>
+
+// ---------------------------------------------------------------------------
+// Dimension 4 — By Agent
+// ---------------------------------------------------------------------------
+
+export const AgentUsage = z.object({
+  agent: z.string(),
+  messages: z.number(),
+  sessions: z.number(),
+  tokens: TokenBreakdown,
+  cost: z.number(),
+  accounting: RolloutAccounting.Summary.optional(),
+  subagentInvocations: z.number(),
+})
+export type AgentUsage = z.infer<typeof AgentUsage>
+
+export const AgentStats = z.object({
+  agents: z.array(AgentUsage),
+  totalSubagentCalls: z.number(),
+})
+export type AgentStats = z.infer<typeof AgentStats>
+
+// ---------------------------------------------------------------------------
+// Dimension 5 — By Tool
+// ---------------------------------------------------------------------------
+
+export const ToolUsage = z.object({
+  tool: z.string(),
+  calls: z.number(),
+  successes: z.number(),
+  errors: z.number(),
+  avgDurationMs: z.number(),
+})
+export type ToolUsage = z.infer<typeof ToolUsage>
+
+export const ToolStats = z.object({
+  tools: z.array(ToolUsage),
+})
+export type ToolStats = z.infer<typeof ToolStats>
+
+// ---------------------------------------------------------------------------
+// Dimension 6 — Code Changes
+// ---------------------------------------------------------------------------
+
+export const CodeChangeStats = z.object({
+  totalAdditions: z.number(),
+  totalDeletions: z.number(),
+  totalFiles: z.number(),
+  netLines: z.number(),
+  dailyAdditions: z.number(),
+  dailyDeletions: z.number(),
+})
+export type CodeChangeStats = z.infer<typeof CodeChangeStats>
+
+// ---------------------------------------------------------------------------
+// Dimension 7 — Session Lifecycle
+// ---------------------------------------------------------------------------
+
+export const SessionLifecycleStats = z.object({
+  pinnedCount: z.number(),
+  avgTurnsPerSession: z.number(),
+  medianTurnsPerSession: z.number(),
+  compactionCount: z.number(),
+  retryCount: z.number(),
+  errorCount: z.number(),
+  errorRate: z.number(),
+  /** Bucketed session duration: short (<5min), medium (5-30min), long (>30min) */
+  durationBuckets: z.object({
+    short: z.number(),
+    medium: z.number(),
+    long: z.number(),
+  }),
+})
+export type SessionLifecycleStats = z.infer<typeof SessionLifecycleStats>
+
+// ---------------------------------------------------------------------------
+// Dimension 8 — By Channel / Endpoint
+// ---------------------------------------------------------------------------
+
+export const ChannelUsage = z.object({
+  channel: z.string(),
+  sessions: z.number(),
+  messages: z.number(),
+})
+export type ChannelUsage = z.infer<typeof ChannelUsage>
+
+export const ChannelStats = z.object({
+  channels: z.array(ChannelUsage),
+  interactiveSessions: z.number(),
+  unattendedSessions: z.number(),
+})
+export type ChannelStats = z.infer<typeof ChannelStats>
+
+// ---------------------------------------------------------------------------
+// Dimension 9 — Time Series (per-day bucket)
+// ---------------------------------------------------------------------------
+
+export const DailyBucket = z.object({
+  day: z.string(),
+  sessions: z.number(),
+  turns: z.number(),
+  tokens: TokenBreakdown,
+  cost: z.number(),
+  accounting: RolloutAccounting.Summary.optional(),
+  additions: z.number(),
+  deletions: z.number(),
+  files: z.number(),
+  toolCalls: z.number(),
+  errors: z.number(),
+})
+export type DailyBucket = z.infer<typeof DailyBucket>
+
+export const HourlyBucket = z.object({
+  hour: z.string(),
+  turns: z.number(),
+})
+export type HourlyBucket = z.infer<typeof HourlyBucket>
+
+export const TimeSeriesStats = z.object({
+  days: z.array(DailyBucket),
+  hours: z.array(HourlyBucket),
+  /** Hour-of-day activity: 24-element array, each = turn count */
+  hourlyActivity: z.array(z.number()),
+})
+export type TimeSeriesStats = z.infer<typeof TimeSeriesStats>
+
+// ---------------------------------------------------------------------------
+// Composite — Full Stats Snapshot
+// ---------------------------------------------------------------------------
+
+export const StatsSnapshot = z.object({
+  overview: OverviewStats,
+  tokenCost: TokenCostStats,
+  models: ModelStats,
+  agents: AgentStats,
+  tools: ToolStats,
+  codeChanges: CodeChangeStats,
+  lifecycle: SessionLifecycleStats,
+  channels: ChannelStats,
+  timeSeries: TimeSeriesStats,
+  /** Timestamp when this snapshot was computed */
+  computedAt: z.number(),
+  /** Watermark: latest session.updated we scanned up to */
+  watermark: z.number(),
+})
+export type StatsSnapshot = z.infer<typeof StatsSnapshot>
+
+// ---------------------------------------------------------------------------
+// Per-Session Digest (intermediate product for incremental aggregation)
+// ---------------------------------------------------------------------------
+
+export const SessionDigest = z.object({
+  sessionID: z.string(),
+  scopeID: z.string(),
+  created: z.number(),
+  updated: z.number(),
+  rolloutRevision: z.number().int().nonnegative().optional(),
+  archived: z.number().optional(),
+  pinned: z.boolean(),
+  parentID: z.string().optional(),
+  endpoint: z
+    .object({
+      kind: z.string(),
+      type: z.string().optional(),
+    })
+    .optional(),
+  interaction: z
+    .object({
+      mode: z.string(),
+      source: z.string().optional(),
+    })
+    .optional(),
+
+  turns: z.number(),
+  messages: z.number(),
+  tokens: TokenBreakdown,
+  cost: z.number(),
+  accounting: RolloutAccounting.Summary.optional(),
+
+  /** model key (providerID/modelID) → { messages, tokens, cost, totalResponseMs } */
+  modelUsage: z.record(
+    z.string(),
+    z.object({
+      messages: z.number(),
+      tokens: TokenBreakdown,
+      cost: z.number(),
+      accounting: RolloutAccounting.Summary.optional(),
+      totalResponseMs: z.number(),
+    }),
+  ),
+
+  /** agent → { messages, tokens, cost } */
+  agentUsage: z.record(
+    z.string(),
+    z.object({
+      messages: z.number(),
+      tokens: TokenBreakdown,
+      cost: z.number(),
+      accounting: RolloutAccounting.Summary.optional(),
+    }),
+  ),
+
+  /** tool → { calls, successes, errors, totalDurationMs } */
+  toolUsage: z.record(
+    z.string(),
+    z.object({
+      calls: z.number(),
+      successes: z.number(),
+      errors: z.number(),
+      totalDurationMs: z.number(),
+      timedSamples: z.number().int().nonnegative().optional(),
+    }),
+  ),
+
+  /** YYYY-MM-DDTHH → turn count */
+  hourlyTurns: z.record(z.string(), z.number()),
+
+  additions: z.number(),
+  deletions: z.number(),
+  files: z.number(),
+
+  compactionCount: z.number(),
+  retryCount: z.number(),
+  errorCount: z.number(),
+
+  /** Duration in ms (updated - created) */
+  durationMs: z.number(),
+})
+export type SessionDigest = z.infer<typeof SessionDigest>
+
+export const OperationDigest = SessionDigest.pick({
+  scopeID: true,
+  created: true,
+  updated: true,
+  tokens: true,
+  cost: true,
+  accounting: true,
+  modelUsage: true,
+  agentUsage: true,
+}).extend({ operationID: z.string(), rolloutRevision: z.number().int().nonnegative(), turns: z.literal(0) })
+export type OperationDigest = z.infer<typeof OperationDigest>
+
+// ---------------------------------------------------------------------------
+// Watermark — tracks incremental scan progress
+// ---------------------------------------------------------------------------
+
+export const StatsWatermark = z.object({
+  /** Last session.updated timestamp we scanned */
+  lastUpdated: z.number(),
+  /** Set of sessionIDs already digested (to detect deletions) */
+  sessionIDs: z.array(z.string()),
+  /** Timestamp of last full scan */
+  lastFullScanAt: z.number(),
+})
+export type StatsWatermark = z.infer<typeof StatsWatermark>
+
+// ---------------------------------------------------------------------------
+// Progress callback
+// ---------------------------------------------------------------------------
+
+export const ProgressEvent = z.object({
+  phase: z.enum(["scan", "digest", "bucket", "snapshot"]),
+  current: z.number(),
+  total: z.number(),
+  message: z.string().optional(),
+})
+export type ProgressEvent = z.infer<typeof ProgressEvent>
+
+export type ProgressCallback = (event: ProgressEvent) => void

package/src/worker.ts

@@ -0,0 +1,7 @@
+import { version } from "../package.json" with { type: "json" }
+export const metadata = { id: "workbench", version, apiVersion: 1 }
+import { registerConfig } from "./config-schema"
+
+export function registerWorker() {
+  registerConfig()
+}