@agent-native/core 0.12.4 → 0.12.6

package/dist/usage/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/usage/store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Token usage tracking and cost monitoring.\n *\n * Every LLM call made by the framework records a row here so users can\n * see where their spend is going — chat vs automations vs background jobs\n * vs whatever else a template labels its prompts as.\n *\n * Cost is stored as \"centicents\" (1/100th of a cent) for integer precision.\n */\nimport { getDbExec, intType, isPostgres } from \"../db/client.js\";\n\n/**\n * Per-million-token pricing in cents. Cache read is typically ~10% of\n * input; cache write (5m TTL) is ~125%. Pricing is best-effort — keep\n * this table in sync with Anthropic's published prices.\n */\ninterface ModelPricing {\n  input: number;\n  output: number;\n  cacheRead: number;\n  cacheWrite: number;\n}\n\nconst PRICING: Array<{ match: RegExp; pricing: ModelPricing }> = [\n  {\n    match: /opus/i,\n    pricing: { input: 1500, output: 7500, cacheRead: 150, cacheWrite: 1875 },\n  },\n  {\n    match: /haiku/i,\n    pricing: { input: 100, output: 500, cacheRead: 10, cacheWrite: 125 },\n  },\n  // default → sonnet pricing\n  {\n    match: /.*/,\n    pricing: { input: 300, output: 1500, cacheRead: 30, cacheWrite: 375 },\n  },\n];\n\nfunction pricingFor(model: string): ModelPricing {\n  for (const entry of PRICING) {\n    if (entry.match.test(model)) return entry.pricing;\n  }\n  return PRICING[PRICING.length - 1]!.pricing;\n}\n\nexport interface UsageRecord {\n  ownerEmail: string;\n  inputTokens: number;\n  outputTokens: number;\n  cacheReadTokens?: number;\n  cacheWriteTokens?: number;\n  model: string;\n  /** Category for this call — e.g. \"chat\", \"automation\", \"job\", \"custom-agent\". */\n  label?: string;\n  /** Optional template/app name (e.g. \"mail\"). Falls back to AGENT_APP / APP_NAME env. */\n  app?: string;\n}\n\nlet _initPromise: Promise<void> | undefined;\n\nasync function ensureUsageTable(): Promise<void> {\n  if (!_initPromise) {\n    _initPromise = (async () => {\n      const client = getDbExec();\n      await client.execute(`\n        CREATE TABLE IF NOT EXISTS token_usage (\n          id ${intType()} PRIMARY KEY,\n          owner_email TEXT NOT NULL,\n          input_tokens ${intType()} NOT NULL DEFAULT 0,\n          output_tokens ${intType()} NOT NULL DEFAULT 0,\n          cache_read_tokens ${intType()} NOT NULL DEFAULT 0,\n          cache_write_tokens ${intType()} NOT NULL DEFAULT 0,\n          cost_cents_x100 ${intType()} NOT NULL DEFAULT 0,\n          model TEXT NOT NULL DEFAULT '',\n          label TEXT NOT NULL DEFAULT 'chat',\n          app TEXT NOT NULL DEFAULT '',\n          created_at ${intType()} NOT NULL\n        )\n      `);\n\n      // Add columns on older deployments that pre-date the label/cache\n      // fields. Each ALTER is wrapped so a dialect without IF NOT EXISTS\n      // (SQLite) still makes progress if only some columns are missing.\n      const additions: Array<[string, string]> = [\n        [\"cache_read_tokens\", `${intType()} NOT NULL DEFAULT 0`],\n        [\"cache_write_tokens\", `${intType()} NOT NULL DEFAULT 0`],\n        [\"label\", `TEXT NOT NULL DEFAULT 'chat'`],\n        [\"app\", `TEXT NOT NULL DEFAULT ''`],\n      ];\n      for (const [col, def] of additions) {\n        try {\n          if (isPostgres()) {\n            await client.execute(\n              `ALTER TABLE token_usage ADD COLUMN IF NOT EXISTS ${col} ${def}`,\n            );\n          } else {\n            await client.execute(\n              `ALTER TABLE token_usage ADD COLUMN ${col} ${def}`,\n            );\n          }\n        } catch {\n          // Column already exists — ignore\n        }\n      }\n\n      try {\n        await client.execute(\n          `CREATE INDEX IF NOT EXISTS idx_token_usage_owner_created ON token_usage (owner_email, created_at)`,\n        );\n      } catch {}\n    })();\n  }\n  return _initPromise;\n}\n\n/**\n * Calculate cost in centicents (1/100th of a cent).\n * Accepts cache tokens so callers that use prompt caching are priced\n * correctly. Non-cache-aware callers can pass 0 for the cache fields.\n */\nexport function calculateCost(\n  inputTokens: number,\n  outputTokens: number,\n  model: string,\n  cacheReadTokens = 0,\n  cacheWriteTokens = 0,\n): number {\n  const p = pricingFor(model);\n  const toX100 = (tokens: number, costPerM: number) =>\n    Math.round((tokens / 1_000_000) * costPerM * 100);\n  return (\n    toX100(inputTokens, p.input) +\n    toX100(outputTokens, p.output) +\n    toX100(cacheReadTokens, p.cacheRead) +\n    toX100(cacheWriteTokens, p.cacheWrite)\n  );\n}\n\n/**\n * Record token usage from an LLM call.\n *\n * Accepts an object with the full set of fields. A positional overload\n * remains for backward compatibility with the older 4-arg signature.\n */\nexport async function recordUsage(record: UsageRecord): Promise<void>;\nexport async function recordUsage(\n  ownerEmail: string,\n  inputTokens: number,\n  outputTokens: number,\n  model: string,\n): Promise<void>;\nexport async function recordUsage(\n  recordOrOwner: UsageRecord | string,\n  inputTokens?: number,\n  outputTokens?: number,\n  model?: string,\n): Promise<void> {\n  const record: UsageRecord =\n    typeof recordOrOwner === \"string\"\n      ? {\n          ownerEmail: recordOrOwner,\n          inputTokens: inputTokens ?? 0,\n          outputTokens: outputTokens ?? 0,\n          model: model ?? \"\",\n        }\n      : recordOrOwner;\n\n  const {\n    ownerEmail,\n    inputTokens: inTok,\n    outputTokens: outTok,\n    cacheReadTokens = 0,\n    cacheWriteTokens = 0,\n    model: modelName,\n    label,\n    app,\n  } = record;\n\n  // Skip no-op writes (e.g. a stream aborted before any tokens flowed)\n  if (!inTok && !outTok && !cacheReadTokens && !cacheWriteTokens) return;\n\n  await ensureUsageTable();\n  const client = getDbExec();\n  const costX100 = calculateCost(\n    inTok,\n    outTok,\n    modelName,\n    cacheReadTokens,\n    cacheWriteTokens,\n  );\n  const id = Date.now() * 1000 + Math.floor(Math.random() * 1000);\n  const resolvedApp =\n    app ?? process.env.AGENT_APP ?? process.env.APP_NAME ?? \"\";\n  const resolvedLabel = label ?? \"chat\";\n  await client.execute({\n    sql: `INSERT INTO token_usage\n      (id, owner_email, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cost_cents_x100, model, label, app, created_at)\n      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,\n    args: [\n      id,\n      ownerEmail,\n      inTok,\n      outTok,\n      cacheReadTokens,\n      cacheWriteTokens,\n      costX100,\n      modelName,\n      resolvedLabel,\n      resolvedApp,\n      Date.now(),\n    ],\n  });\n}\n\n/** Total cost (in cents) charged against a user, across all time. */\nexport async function getUserUsageCents(ownerEmail: string): Promise<number> {\n  await ensureUsageTable();\n  const client = getDbExec();\n  const { rows } = await client.execute({\n    sql: `SELECT COALESCE(SUM(cost_cents_x100), 0) as total FROM token_usage WHERE owner_email = ?`,\n    args: [ownerEmail],\n  });\n  const total = Number((rows[0] as { total?: number })?.total ?? 0);\n  return total / 100;\n}\n\n// ─── Admin / UI queries ─────────────────────────────────────────────────\n\nexport interface UsageSummaryOptions {\n  ownerEmail: string;\n  /** Inclusive lower bound (ms since epoch). Defaults to 30 days ago. */\n  sinceMs?: number;\n}\n\nexport interface UsageBucket {\n  key: string;\n  inputTokens: number;\n  outputTokens: number;\n  cacheReadTokens: number;\n  cacheWriteTokens: number;\n  cents: number;\n  calls: number;\n}\n\nexport interface DailyBucket {\n  /** YYYY-MM-DD (UTC) */\n  date: string;\n  cents: number;\n  calls: number;\n}\n\nexport interface UsageRecentEntry {\n  id: number;\n  createdAt: number;\n  label: string;\n  app: string;\n  model: string;\n  inputTokens: number;\n  outputTokens: number;\n  cacheReadTokens: number;\n  cacheWriteTokens: number;\n  cents: number;\n}\n\nexport interface UsageSummary {\n  totalCents: number;\n  totalCalls: number;\n  totalInputTokens: number;\n  totalOutputTokens: number;\n  totalCacheReadTokens: number;\n  totalCacheWriteTokens: number;\n  sinceMs: number;\n  byLabel: UsageBucket[];\n  byModel: UsageBucket[];\n  byApp: UsageBucket[];\n  byDay: DailyBucket[];\n  recent: UsageRecentEntry[];\n}\n\nconst DAY_MS = 86_400_000;\n\n/**\n * Produce an aggregated spend view for the Usage admin panel.\n * Scoped to the passed owner email; the UI always passes the session user.\n */\nexport async function getUsageSummary(\n  options: UsageSummaryOptions,\n): Promise<UsageSummary> {\n  await ensureUsageTable();\n  const client = getDbExec();\n  const sinceMs = options.sinceMs ?? Date.now() - 30 * DAY_MS;\n\n  const totalRow = await client.execute({\n    sql: `SELECT\n      COALESCE(SUM(cost_cents_x100), 0) AS cents,\n      COUNT(*) AS calls,\n      COALESCE(SUM(input_tokens), 0) AS in_tok,\n      COALESCE(SUM(output_tokens), 0) AS out_tok,\n      COALESCE(SUM(cache_read_tokens), 0) AS cr_tok,\n      COALESCE(SUM(cache_write_tokens), 0) AS cw_tok\n      FROM token_usage WHERE owner_email = ? AND created_at >= ?`,\n    args: [options.ownerEmail, sinceMs],\n  });\n  const t = (totalRow.rows[0] ?? {}) as Record<string, number | null>;\n\n  const bucketSql = (col: string) => ({\n    sql: `SELECT ${col} AS k,\n        COALESCE(SUM(cost_cents_x100), 0) AS cents,\n        COUNT(*) AS calls,\n        COALESCE(SUM(input_tokens), 0) AS in_tok,\n        COALESCE(SUM(output_tokens), 0) AS out_tok,\n        COALESCE(SUM(cache_read_tokens), 0) AS cr_tok,\n        COALESCE(SUM(cache_write_tokens), 0) AS cw_tok\n      FROM token_usage\n      WHERE owner_email = ? AND created_at >= ?\n      GROUP BY ${col}\n      ORDER BY cents DESC`,\n    args: [options.ownerEmail, sinceMs],\n  });\n\n  const mapBuckets = (rows: unknown[]): UsageBucket[] =>\n    rows.map((r) => {\n      const row = r as Record<string, number | string | null>;\n      return {\n        key: String(row.k ?? \"\"),\n        cents: Number(row.cents ?? 0) / 100,\n        calls: Number(row.calls ?? 0),\n        inputTokens: Number(row.in_tok ?? 0),\n        outputTokens: Number(row.out_tok ?? 0),\n        cacheReadTokens: Number(row.cr_tok ?? 0),\n        cacheWriteTokens: Number(row.cw_tok ?? 0),\n      };\n    });\n\n  const [byLabelR, byModelR, byAppR] = await Promise.all([\n    client.execute(bucketSql(\"label\")),\n    client.execute(bucketSql(\"model\")),\n    client.execute(bucketSql(\"app\")),\n  ]);\n\n  // By-day aggregation — done in JS so we don't depend on dialect-specific\n  // date functions (SQLite `strftime`, Postgres `to_char`). Cheap enough\n  // for a 30-day window; if this grows, swap for a dialect-aware query.\n  const dayRows = await client.execute({\n    sql: `SELECT created_at, cost_cents_x100 FROM token_usage\n      WHERE owner_email = ? AND created_at >= ?`,\n    args: [options.ownerEmail, sinceMs],\n  });\n  const dayMap = new Map<string, { cents: number; calls: number }>();\n  for (const row of dayRows.rows as Array<Record<string, number>>) {\n    const date = new Date(Number(row.created_at)).toISOString().slice(0, 10);\n    const prev = dayMap.get(date) ?? { cents: 0, calls: 0 };\n    prev.cents += Number(row.cost_cents_x100 ?? 0);\n    prev.calls += 1;\n    dayMap.set(date, prev);\n  }\n  const byDay: DailyBucket[] = [...dayMap.entries()]\n    .map(([date, v]) => ({\n      date,\n      cents: v.cents / 100,\n      calls: v.calls,\n    }))\n    .sort((a, b) => a.date.localeCompare(b.date));\n\n  const recentRows = await client.execute({\n    sql: `SELECT id, created_at, label, app, model,\n        input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,\n        cost_cents_x100\n      FROM token_usage\n      WHERE owner_email = ?\n      ORDER BY created_at DESC\n      LIMIT 50`,\n    args: [options.ownerEmail],\n  });\n  const recent: UsageRecentEntry[] = (\n    recentRows.rows as Array<Record<string, number | string | null>>\n  ).map((row) => ({\n    id: Number(row.id),\n    createdAt: Number(row.created_at),\n    label: String(row.label ?? \"chat\"),\n    app: String(row.app ?? \"\"),\n    model: String(row.model ?? \"\"),\n    inputTokens: Number(row.input_tokens ?? 0),\n    outputTokens: Number(row.output_tokens ?? 0),\n    cacheReadTokens: Number(row.cache_read_tokens ?? 0),\n    cacheWriteTokens: Number(row.cache_write_tokens ?? 0),\n    cents: Number(row.cost_cents_x100 ?? 0) / 100,\n  }));\n\n  return {\n    totalCents: Number(t.cents ?? 0) / 100,\n    totalCalls: Number(t.calls ?? 0),\n    totalInputTokens: Number(t.in_tok ?? 0),\n    totalOutputTokens: Number(t.out_tok ?? 0),\n    totalCacheReadTokens: Number(t.cr_tok ?? 0),\n    totalCacheWriteTokens: Number(t.cw_tok ?? 0),\n    sinceMs,\n    byLabel: mapBuckets(byLabelR.rows),\n    byModel: mapBuckets(byModelR.rows),\n    byApp: mapBuckets(byAppR.rows),\n    byDay,\n    recent,\n  };\n}\n"]}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/usage/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAcjE,MAAM,CAAC,MAAM,sCAAsC,GAAG,IAAI,CAAC;AAC3D,MAAM,CAAC,MAAM,6BAA6B,GAAG,EAAE,CAAC;AAahD,MAAM,CAAC,MAAM,iBAAiB,GAAqB;IACjD,IAAI,EAAE,KAAK;IACX,KAAK,EAAE,iBAAiB;IACxB,UAAU,EAAE,MAAM;IAClB,MAAM,EAAE,yBAAyB;CAClC,CAAC;AAEF,MAAM,CAAC,MAAM,4BAA4B,GAAqB;IAC5D,IAAI,EAAE,iBAAiB;IACvB,KAAK,EAAE,yBAAyB;IAChC,UAAU,EAAE,SAAS;IACrB,MAAM,EAAE,uBAAuB;IAC/B,wBAAwB,EAAE,sCAAsC;IAChE,aAAa,EAAE,6BAA6B;CAC7C,CAAC;AAEF,MAAM,UAAU,qBAAqB,CACnC,UAAqC;IAErC,OAAO,UAAU,KAAK,SAAS;QAC7B,CAAC,CAAC,4BAA4B;QAC9B,CAAC,CAAC,iBAAiB,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,KAAa;IACvD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACpD,MAAM,OAAO,GAAG,KAAK,GAAG,GAAG,CAAC;IAC5B,MAAM,OAAO,GACX,OAAO;QACP,sCAAsC;QACtC,6BAA6B,CAAC;IAChC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;AAC1C,CAAC;AAED,MAAM,OAAO,GAAoD;IAC/D;QACE,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE;KACzE;IACD;QACE,KAAK,EAAE,QAAQ;QACf,OAAO,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE;KACrE;IACD,2BAA2B;IAC3B;QACE,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE;KACtE;CACF,CAAC;AAEF,SAAS,UAAU,CAAC,KAAa;IAC/B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,OAAO,CAAC;IACpD,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,OAAO,CAAC;AAC9C,CAAC;AAeD,IAAI,YAAuC,CAAC;AAE5C,KAAK,UAAU,gBAAgB;IAC7B,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,YAAY,GAAG,CAAC,KAAK,IAAI,EAAE;YACzB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;YAC3B,MAAM,MAAM,CAAC,OAAO,CAAC;;eAEZ,OAAO,EAAE;;yBAEC,OAAO,EAAE;0BACR,OAAO,EAAE;8BACL,OAAO,EAAE;+BACR,OAAO,EAAE;4BACZ,OAAO,EAAE;;;;uBAId,OAAO,EAAE;;OAEzB,CAAC,CAAC;YAEH,iEAAiE;YACjE,mEAAmE;YACnE,kEAAkE;YAClE,MAAM,SAAS,GAA4B;gBACzC,CAAC,mBAAmB,EAAE,GAAG,OAAO,EAAE,qBAAqB,CAAC;gBACxD,CAAC,oBAAoB,EAAE,GAAG,OAAO,EAAE,qBAAqB,CAAC;gBACzD,CAAC,OAAO,EAAE,8BAA8B,CAAC;gBACzC,CAAC,KAAK,EAAE,0BAA0B,CAAC;aACpC,CAAC;YACF,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,SAAS,EAAE,CAAC;gBACnC,IAAI,CAAC;oBACH,IAAI,UAAU,EAAE,EAAE,CAAC;wBACjB,MAAM,MAAM,CAAC,OAAO,CAClB,oDAAoD,GAAG,IAAI,GAAG,EAAE,CACjE,CAAC;oBACJ,CAAC;yBAAM,CAAC;wBACN,MAAM,MAAM,CAAC,OAAO,CAClB,sCAAsC,GAAG,IAAI,GAAG,EAAE,CACnD,CAAC;oBACJ,CAAC;gBACH,CAAC;gBAAC,MAAM,CAAC;oBACP,iCAAiC;gBACnC,CAAC;YACH,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,OAAO,CAClB,mGAAmG,CACpG,CAAC;YACJ,CAAC;YAAC,MAAM,CAAC,CAAA,CAAC;QACZ,CAAC,CAAC,EAAE,CAAC;IACP,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,WAAmB,EACnB,YAAoB,EACpB,KAAa,EACb,eAAe,GAAG,CAAC,EACnB,gBAAgB,GAAG,CAAC;IAEpB,MAAM,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAC5B,MAAM,MAAM,GAAG,CAAC,MAAc,EAAE,QAAgB,EAAE,EAAE,CAClD,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,SAAS,CAAC,GAAG,QAAQ,GAAG,GAAG,CAAC,CAAC;IACpD,OAAO,CACL,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC;QAC5B,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC;QAC9B,MAAM,CAAC,eAAe,EAAE,CAAC,CAAC,SAAS,CAAC;QACpC,MAAM,CAAC,gBAAgB,EAAE,CAAC,CAAC,UAAU,CAAC,CACvC,CAAC;AACJ,CAAC;AAeD,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,aAAmC,EACnC,WAAoB,EACpB,YAAqB,EACrB,KAAc;IAEd,MAAM,MAAM,GACV,OAAO,aAAa,KAAK,QAAQ;QAC/B,CAAC,CAAC;YACE,UAAU,EAAE,aAAa;YACzB,WAAW,EAAE,WAAW,IAAI,CAAC;YAC7B,YAAY,EAAE,YAAY,IAAI,CAAC;YAC/B,KAAK,EAAE,KAAK,IAAI,EAAE;SACnB;QACH,CAAC,CAAC,aAAa,CAAC;IAEpB,MAAM,EACJ,UAAU,EACV,WAAW,EAAE,KAAK,EAClB,YAAY,EAAE,MAAM,EACpB,eAAe,GAAG,CAAC,EACnB,gBAAgB,GAAG,CAAC,EACpB,KAAK,EAAE,SAAS,EAChB,KAAK,EACL,GAAG,GACJ,GAAG,MAAM,CAAC;IAEX,qEAAqE;IACrE,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,eAAe,IAAI,CAAC,gBAAgB;QAAE,OAAO;IAEvE,MAAM,gBAAgB,EAAE,CAAC;IACzB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,QAAQ,GAAG,aAAa,CAC5B,KAAK,EACL,MAAM,EACN,SAAS,EACT,eAAe,EACf,gBAAgB,CACjB,CAAC;IACF,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;IAChE,MAAM,WAAW,GACf,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC;IAC7D,MAAM,aAAa,GAAG,KAAK,IAAI,MAAM,CAAC;IACtC,MAAM,MAAM,CAAC,OAAO,CAAC;QACnB,GAAG,EAAE;;+CAEsC;QAC3C,IAAI,EAAE;YACJ,EAAE;YACF,UAAU;YACV,KAAK;YACL,MAAM;YACN,eAAe;YACf,gBAAgB;YAChB,QAAQ;YACR,SAAS;YACT,aAAa;YACb,WAAW;YACX,IAAI,CAAC,GAAG,EAAE;SACX;KACF,CAAC,CAAC;AACL,CAAC;AAED,qEAAqE;AACrE,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,UAAkB;IACxD,MAAM,gBAAgB,EAAE,CAAC;IACzB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC;QACpC,GAAG,EAAE,0FAA0F;QAC/F,IAAI,EAAE,CAAC,UAAU,CAAC;KACnB,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,MAAM,CAAE,IAAI,CAAC,CAAC,CAAwB,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC;IAClE,OAAO,KAAK,GAAG,GAAG,CAAC;AACrB,CAAC;AAwDD,MAAM,MAAM,GAAG,UAAU,CAAC;AAE1B;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAA4B;IAE5B,MAAM,gBAAgB,EAAE,CAAC;IACzB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC;IAE5D,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC;QACpC,GAAG,EAAE;;;;;;;iEAOwD;QAC7D,IAAI,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC;KACpC,CAAC,CAAC;IACH,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAkC,CAAC;IAEpE,MAAM,SAAS,GAAG,CAAC,GAAW,EAAE,EAAE,CAAC,CAAC;QAClC,GAAG,EAAE,UAAU,GAAG;;;;;;;;;iBASL,GAAG;0BACM;QACtB,IAAI,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC;KACpC,CAAC,CAAC;IAEH,MAAM,UAAU,GAAG,CAAC,IAAe,EAAiB,EAAE,CACpD,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACb,MAAM,GAAG,GAAG,CAA2C,CAAC;QACxD,OAAO;YACL,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;YACxB,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,GAAG;YACnC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC;YAC7B,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC;YACpC,YAAY,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC;YACtC,eAAe,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC;YACxC,gBAAgB,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC;SAC1C,CAAC;IACJ,CAAC,CAAC,CAAC;IAEL,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACrD,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAClC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAClC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;KACjC,CAAC,CAAC;IAEH,yEAAyE;IACzE,uEAAuE;IACvE,sEAAsE;IACtE,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC;QACnC,GAAG,EAAE;gDACuC;QAC5C,IAAI,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC;KACpC,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,IAAI,GAAG,EAA4C,CAAC;IACnE,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,IAAqC,EAAE,CAAC;QAChE,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACzE,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QACxD,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,GAAG,CAAC,eAAe,IAAI,CAAC,CAAC,CAAC;QAC/C,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;QAChB,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACzB,CAAC;IACD,MAAM,KAAK,GAAkB,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;SAC/C,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACnB,IAAI;QACJ,KAAK,EAAE,CAAC,CAAC,KAAK,GAAG,GAAG;QACpB,KAAK,EAAE,CAAC,CAAC,KAAK;KACf,CAAC,CAAC;SACF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAEhD,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC;QACtC,GAAG,EAAE;;;;;;eAMM;QACX,IAAI,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC;KAC3B,CAAC,CAAC;IACH,MAAM,MAAM,GACV,UAAU,CAAC,IACZ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACd,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC;QACjC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,MAAM,CAAC;QAClC,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC;QAC1B,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;QAC9B,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,CAAC;QAC1C,YAAY,EAAE,MAAM,CAAC,GAAG,CAAC,aAAa,IAAI,CAAC,CAAC;QAC5C,eAAe,EAAE,MAAM,CAAC,GAAG,CAAC,iBAAiB,IAAI,CAAC,CAAC;QACnD,gBAAgB,EAAE,MAAM,CAAC,GAAG,CAAC,kBAAkB,IAAI,CAAC,CAAC;QACrD,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,eAAe,IAAI,CAAC,CAAC,GAAG,GAAG;KAC9C,CAAC,CAAC,CAAC;IAEJ,OAAO;QACL,OAAO,EAAE,iBAAiB;QAC1B,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,GAAG;QACtC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;QAChC,gBAAgB,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;QACvC,iBAAiB,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC;QACzC,oBAAoB,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;QAC3C,qBAAqB,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;QAC5C,OAAO;QACP,OAAO,EAAE,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC;QAClC,OAAO,EAAE,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC;QAClC,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC;QAC9B,KAAK;QACL,MAAM;KACP,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Token usage tracking and cost monitoring.\n *\n * Every LLM call made by the framework records a row here so users can\n * see where their spend is going — chat vs automations vs background jobs\n * vs whatever else a template labels its prompts as.\n *\n * Cost is stored as \"centicents\" (1/100th of a cent) for integer precision.\n */\nimport { getDbExec, intType, isPostgres } from \"../db/client.js\";\n\n/**\n * Per-million-token pricing in cents. Cache read is typically ~10% of\n * input; cache write (5m TTL) is ~125%. Pricing is best-effort — keep\n * this table in sync with Anthropic's published prices.\n */\ninterface ModelPricing {\n  input: number;\n  output: number;\n  cacheRead: number;\n  cacheWrite: number;\n}\n\nexport const BUILDER_AGENT_CREDIT_MARGIN_MULTIPLIER = 1.25;\nexport const BUILDER_AGENT_CREDITS_PER_USD = 20;\n\nexport type UsageBillingUnit = \"usd\" | \"builder-credits\";\n\nexport interface UsageBillingMode {\n  unit: UsageBillingUnit;\n  label: string;\n  shortLabel: string;\n  source: \"estimated-provider-cost\" | \"builder-agent-credits\";\n  hardCostMarginMultiplier?: number;\n  creditsPerUsd?: number;\n}\n\nexport const USD_USAGE_BILLING: UsageBillingMode = {\n  unit: \"usd\",\n  label: \"Estimated spend\",\n  shortLabel: \"Cost\",\n  source: \"estimated-provider-cost\",\n};\n\nexport const BUILDER_CREDIT_USAGE_BILLING: UsageBillingMode = {\n  unit: \"builder-credits\",\n  label: \"Builder.io credit spend\",\n  shortLabel: \"Credits\",\n  source: \"builder-agent-credits\",\n  hardCostMarginMultiplier: BUILDER_AGENT_CREDIT_MARGIN_MULTIPLIER,\n  creditsPerUsd: BUILDER_AGENT_CREDITS_PER_USD,\n};\n\nexport function usageBillingForEngine(\n  engineName: string | null | undefined,\n): UsageBillingMode {\n  return engineName === \"builder\"\n    ? BUILDER_CREDIT_USAGE_BILLING\n    : USD_USAGE_BILLING;\n}\n\nexport function builderCreditsFromCostCents(cents: number): number {\n  if (!Number.isFinite(cents) || cents <= 0) return 0;\n  const dollars = cents / 100;\n  const credits =\n    dollars *\n    BUILDER_AGENT_CREDIT_MARGIN_MULTIPLIER *\n    BUILDER_AGENT_CREDITS_PER_USD;\n  return Math.ceil(credits * 1000) / 1000;\n}\n\nconst PRICING: Array<{ match: RegExp; pricing: ModelPricing }> = [\n  {\n    match: /opus/i,\n    pricing: { input: 1500, output: 7500, cacheRead: 150, cacheWrite: 1875 },\n  },\n  {\n    match: /haiku/i,\n    pricing: { input: 100, output: 500, cacheRead: 10, cacheWrite: 125 },\n  },\n  // default → sonnet pricing\n  {\n    match: /.*/,\n    pricing: { input: 300, output: 1500, cacheRead: 30, cacheWrite: 375 },\n  },\n];\n\nfunction pricingFor(model: string): ModelPricing {\n  for (const entry of PRICING) {\n    if (entry.match.test(model)) return entry.pricing;\n  }\n  return PRICING[PRICING.length - 1]!.pricing;\n}\n\nexport interface UsageRecord {\n  ownerEmail: string;\n  inputTokens: number;\n  outputTokens: number;\n  cacheReadTokens?: number;\n  cacheWriteTokens?: number;\n  model: string;\n  /** Category for this call — e.g. \"chat\", \"automation\", \"job\", \"custom-agent\". */\n  label?: string;\n  /** Optional template/app name (e.g. \"mail\"). Falls back to AGENT_APP / APP_NAME env. */\n  app?: string;\n}\n\nlet _initPromise: Promise<void> | undefined;\n\nasync function ensureUsageTable(): Promise<void> {\n  if (!_initPromise) {\n    _initPromise = (async () => {\n      const client = getDbExec();\n      await client.execute(`\n        CREATE TABLE IF NOT EXISTS token_usage (\n          id ${intType()} PRIMARY KEY,\n          owner_email TEXT NOT NULL,\n          input_tokens ${intType()} NOT NULL DEFAULT 0,\n          output_tokens ${intType()} NOT NULL DEFAULT 0,\n          cache_read_tokens ${intType()} NOT NULL DEFAULT 0,\n          cache_write_tokens ${intType()} NOT NULL DEFAULT 0,\n          cost_cents_x100 ${intType()} NOT NULL DEFAULT 0,\n          model TEXT NOT NULL DEFAULT '',\n          label TEXT NOT NULL DEFAULT 'chat',\n          app TEXT NOT NULL DEFAULT '',\n          created_at ${intType()} NOT NULL\n        )\n      `);\n\n      // Add columns on older deployments that pre-date the label/cache\n      // fields. Each ALTER is wrapped so a dialect without IF NOT EXISTS\n      // (SQLite) still makes progress if only some columns are missing.\n      const additions: Array<[string, string]> = [\n        [\"cache_read_tokens\", `${intType()} NOT NULL DEFAULT 0`],\n        [\"cache_write_tokens\", `${intType()} NOT NULL DEFAULT 0`],\n        [\"label\", `TEXT NOT NULL DEFAULT 'chat'`],\n        [\"app\", `TEXT NOT NULL DEFAULT ''`],\n      ];\n      for (const [col, def] of additions) {\n        try {\n          if (isPostgres()) {\n            await client.execute(\n              `ALTER TABLE token_usage ADD COLUMN IF NOT EXISTS ${col} ${def}`,\n            );\n          } else {\n            await client.execute(\n              `ALTER TABLE token_usage ADD COLUMN ${col} ${def}`,\n            );\n          }\n        } catch {\n          // Column already exists — ignore\n        }\n      }\n\n      try {\n        await client.execute(\n          `CREATE INDEX IF NOT EXISTS idx_token_usage_owner_created ON token_usage (owner_email, created_at)`,\n        );\n      } catch {}\n    })();\n  }\n  return _initPromise;\n}\n\n/**\n * Calculate cost in centicents (1/100th of a cent).\n * Accepts cache tokens so callers that use prompt caching are priced\n * correctly. Non-cache-aware callers can pass 0 for the cache fields.\n */\nexport function calculateCost(\n  inputTokens: number,\n  outputTokens: number,\n  model: string,\n  cacheReadTokens = 0,\n  cacheWriteTokens = 0,\n): number {\n  const p = pricingFor(model);\n  const toX100 = (tokens: number, costPerM: number) =>\n    Math.round((tokens / 1_000_000) * costPerM * 100);\n  return (\n    toX100(inputTokens, p.input) +\n    toX100(outputTokens, p.output) +\n    toX100(cacheReadTokens, p.cacheRead) +\n    toX100(cacheWriteTokens, p.cacheWrite)\n  );\n}\n\n/**\n * Record token usage from an LLM call.\n *\n * Accepts an object with the full set of fields. A positional overload\n * remains for backward compatibility with the older 4-arg signature.\n */\nexport async function recordUsage(record: UsageRecord): Promise<void>;\nexport async function recordUsage(\n  ownerEmail: string,\n  inputTokens: number,\n  outputTokens: number,\n  model: string,\n): Promise<void>;\nexport async function recordUsage(\n  recordOrOwner: UsageRecord | string,\n  inputTokens?: number,\n  outputTokens?: number,\n  model?: string,\n): Promise<void> {\n  const record: UsageRecord =\n    typeof recordOrOwner === \"string\"\n      ? {\n          ownerEmail: recordOrOwner,\n          inputTokens: inputTokens ?? 0,\n          outputTokens: outputTokens ?? 0,\n          model: model ?? \"\",\n        }\n      : recordOrOwner;\n\n  const {\n    ownerEmail,\n    inputTokens: inTok,\n    outputTokens: outTok,\n    cacheReadTokens = 0,\n    cacheWriteTokens = 0,\n    model: modelName,\n    label,\n    app,\n  } = record;\n\n  // Skip no-op writes (e.g. a stream aborted before any tokens flowed)\n  if (!inTok && !outTok && !cacheReadTokens && !cacheWriteTokens) return;\n\n  await ensureUsageTable();\n  const client = getDbExec();\n  const costX100 = calculateCost(\n    inTok,\n    outTok,\n    modelName,\n    cacheReadTokens,\n    cacheWriteTokens,\n  );\n  const id = Date.now() * 1000 + Math.floor(Math.random() * 1000);\n  const resolvedApp =\n    app ?? process.env.AGENT_APP ?? process.env.APP_NAME ?? \"\";\n  const resolvedLabel = label ?? \"chat\";\n  await client.execute({\n    sql: `INSERT INTO token_usage\n      (id, owner_email, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cost_cents_x100, model, label, app, created_at)\n      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,\n    args: [\n      id,\n      ownerEmail,\n      inTok,\n      outTok,\n      cacheReadTokens,\n      cacheWriteTokens,\n      costX100,\n      modelName,\n      resolvedLabel,\n      resolvedApp,\n      Date.now(),\n    ],\n  });\n}\n\n/** Total cost (in cents) charged against a user, across all time. */\nexport async function getUserUsageCents(ownerEmail: string): Promise<number> {\n  await ensureUsageTable();\n  const client = getDbExec();\n  const { rows } = await client.execute({\n    sql: `SELECT COALESCE(SUM(cost_cents_x100), 0) as total FROM token_usage WHERE owner_email = ?`,\n    args: [ownerEmail],\n  });\n  const total = Number((rows[0] as { total?: number })?.total ?? 0);\n  return total / 100;\n}\n\n// ─── Admin / UI queries ─────────────────────────────────────────────────\n\nexport interface UsageSummaryOptions {\n  ownerEmail: string;\n  /** Inclusive lower bound (ms since epoch). Defaults to 30 days ago. */\n  sinceMs?: number;\n}\n\nexport interface UsageBucket {\n  key: string;\n  inputTokens: number;\n  outputTokens: number;\n  cacheReadTokens: number;\n  cacheWriteTokens: number;\n  cents: number;\n  calls: number;\n}\n\nexport interface DailyBucket {\n  /** YYYY-MM-DD (UTC) */\n  date: string;\n  cents: number;\n  calls: number;\n}\n\nexport interface UsageRecentEntry {\n  id: number;\n  createdAt: number;\n  label: string;\n  app: string;\n  model: string;\n  inputTokens: number;\n  outputTokens: number;\n  cacheReadTokens: number;\n  cacheWriteTokens: number;\n  cents: number;\n}\n\nexport interface UsageSummary {\n  billing?: UsageBillingMode;\n  totalCents: number;\n  totalCalls: number;\n  totalInputTokens: number;\n  totalOutputTokens: number;\n  totalCacheReadTokens: number;\n  totalCacheWriteTokens: number;\n  sinceMs: number;\n  byLabel: UsageBucket[];\n  byModel: UsageBucket[];\n  byApp: UsageBucket[];\n  byDay: DailyBucket[];\n  recent: UsageRecentEntry[];\n}\n\nconst DAY_MS = 86_400_000;\n\n/**\n * Produce an aggregated spend view for the Usage admin panel.\n * Scoped to the passed owner email; the UI always passes the session user.\n */\nexport async function getUsageSummary(\n  options: UsageSummaryOptions,\n): Promise<UsageSummary> {\n  await ensureUsageTable();\n  const client = getDbExec();\n  const sinceMs = options.sinceMs ?? Date.now() - 30 * DAY_MS;\n\n  const totalRow = await client.execute({\n    sql: `SELECT\n      COALESCE(SUM(cost_cents_x100), 0) AS cents,\n      COUNT(*) AS calls,\n      COALESCE(SUM(input_tokens), 0) AS in_tok,\n      COALESCE(SUM(output_tokens), 0) AS out_tok,\n      COALESCE(SUM(cache_read_tokens), 0) AS cr_tok,\n      COALESCE(SUM(cache_write_tokens), 0) AS cw_tok\n      FROM token_usage WHERE owner_email = ? AND created_at >= ?`,\n    args: [options.ownerEmail, sinceMs],\n  });\n  const t = (totalRow.rows[0] ?? {}) as Record<string, number | null>;\n\n  const bucketSql = (col: string) => ({\n    sql: `SELECT ${col} AS k,\n        COALESCE(SUM(cost_cents_x100), 0) AS cents,\n        COUNT(*) AS calls,\n        COALESCE(SUM(input_tokens), 0) AS in_tok,\n        COALESCE(SUM(output_tokens), 0) AS out_tok,\n        COALESCE(SUM(cache_read_tokens), 0) AS cr_tok,\n        COALESCE(SUM(cache_write_tokens), 0) AS cw_tok\n      FROM token_usage\n      WHERE owner_email = ? AND created_at >= ?\n      GROUP BY ${col}\n      ORDER BY cents DESC`,\n    args: [options.ownerEmail, sinceMs],\n  });\n\n  const mapBuckets = (rows: unknown[]): UsageBucket[] =>\n    rows.map((r) => {\n      const row = r as Record<string, number | string | null>;\n      return {\n        key: String(row.k ?? \"\"),\n        cents: Number(row.cents ?? 0) / 100,\n        calls: Number(row.calls ?? 0),\n        inputTokens: Number(row.in_tok ?? 0),\n        outputTokens: Number(row.out_tok ?? 0),\n        cacheReadTokens: Number(row.cr_tok ?? 0),\n        cacheWriteTokens: Number(row.cw_tok ?? 0),\n      };\n    });\n\n  const [byLabelR, byModelR, byAppR] = await Promise.all([\n    client.execute(bucketSql(\"label\")),\n    client.execute(bucketSql(\"model\")),\n    client.execute(bucketSql(\"app\")),\n  ]);\n\n  // By-day aggregation — done in JS so we don't depend on dialect-specific\n  // date functions (SQLite `strftime`, Postgres `to_char`). Cheap enough\n  // for a 30-day window; if this grows, swap for a dialect-aware query.\n  const dayRows = await client.execute({\n    sql: `SELECT created_at, cost_cents_x100 FROM token_usage\n      WHERE owner_email = ? AND created_at >= ?`,\n    args: [options.ownerEmail, sinceMs],\n  });\n  const dayMap = new Map<string, { cents: number; calls: number }>();\n  for (const row of dayRows.rows as Array<Record<string, number>>) {\n    const date = new Date(Number(row.created_at)).toISOString().slice(0, 10);\n    const prev = dayMap.get(date) ?? { cents: 0, calls: 0 };\n    prev.cents += Number(row.cost_cents_x100 ?? 0);\n    prev.calls += 1;\n    dayMap.set(date, prev);\n  }\n  const byDay: DailyBucket[] = [...dayMap.entries()]\n    .map(([date, v]) => ({\n      date,\n      cents: v.cents / 100,\n      calls: v.calls,\n    }))\n    .sort((a, b) => a.date.localeCompare(b.date));\n\n  const recentRows = await client.execute({\n    sql: `SELECT id, created_at, label, app, model,\n        input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,\n        cost_cents_x100\n      FROM token_usage\n      WHERE owner_email = ?\n      ORDER BY created_at DESC\n      LIMIT 50`,\n    args: [options.ownerEmail],\n  });\n  const recent: UsageRecentEntry[] = (\n    recentRows.rows as Array<Record<string, number | string | null>>\n  ).map((row) => ({\n    id: Number(row.id),\n    createdAt: Number(row.created_at),\n    label: String(row.label ?? \"chat\"),\n    app: String(row.app ?? \"\"),\n    model: String(row.model ?? \"\"),\n    inputTokens: Number(row.input_tokens ?? 0),\n    outputTokens: Number(row.output_tokens ?? 0),\n    cacheReadTokens: Number(row.cache_read_tokens ?? 0),\n    cacheWriteTokens: Number(row.cache_write_tokens ?? 0),\n    cents: Number(row.cost_cents_x100 ?? 0) / 100,\n  }));\n\n  return {\n    billing: USD_USAGE_BILLING,\n    totalCents: Number(t.cents ?? 0) / 100,\n    totalCalls: Number(t.calls ?? 0),\n    totalInputTokens: Number(t.in_tok ?? 0),\n    totalOutputTokens: Number(t.out_tok ?? 0),\n    totalCacheReadTokens: Number(t.cr_tok ?? 0),\n    totalCacheWriteTokens: Number(t.cw_tok ?? 0),\n    sinceMs,\n    byLabel: mapBuckets(byLabelR.rows),\n    byModel: mapBuckets(byModelR.rows),\n    byApp: mapBuckets(byAppR.rows),\n    byDay,\n    recent,\n  };\n}\n"]}

package/docs/content/getting-started.md

@@ -30,6 +30,32 @@ The `create` command defaults to a workspace monorepo. It shows a multi-select p
 
 Open the URL the dev server prints. Workspace apps use app-specific ports, often `http://localhost:8080` or another 808x port; standalone apps usually use `http://localhost:3000`.
 
+## Creating vs adding apps {#creating-vs-adding-apps}
+
+Run `create` from the folder where you want a brand-new workspace:
+
+```bash
+cd ~/projects
+npx @agent-native/core create my-platform
+```
+
+After a workspace exists, run app commands from the workspace root:
+
+```bash
+cd my-platform
+npx @agent-native/core add-app
+pnpm install
+pnpm dev
+```
+
+If your terminal is inside `apps/content` or another app folder, the CLI still detects the workspace and adds the new app as a sibling under `apps/`. Afterward, go back to the workspace root before running `pnpm install` or `pnpm dev`.
+
+To make a second app from the same template, give it a new app name:
+
+```bash
+npx @agent-native/core add-app design-lab --template design
+```
+
 ## What just happened? {#what-just-happened}
 
 You now have a real, full-featured app running on your machine. Open it in the browser and try it:

package/docs/content/sharing.md

@@ -69,6 +69,7 @@ Every shareable resource gets a share button in its header. Clicking it opens a
 
 - Visibility selector (`Private` / `Organization` / `Public link`).
 - "Add people or teams" autocomplete — search users in the org or paste an email.
+- A Google Docs-style `Notify people` checkbox for individual email grants.
 - A list of current grants with role pickers and a remove control.
 - A copy-link button that respects the current visibility.
 
@@ -90,12 +91,12 @@ For lists, drop a `<VisibilityBadge visibility={row.visibility} />` next to each
 
 The framework auto-mounts these actions in every template — the agent calls them as tools, the UI calls them as HTTP endpoints:
 
-| Action                    | What it does                                      |
-| ------------------------- | ------------------------------------------------- |
-| `share-resource`          | Grant a user or org access at a specific role.    |
-| `unshare-resource`        | Revoke access for a user or org.                  |
-| `list-resource-shares`    | Show current visibility plus all explicit grants. |
-| `set-resource-visibility` | Change to `private`, `org`, or `public`.          |
+| Action                    | What it does                                                                                   |
+| ------------------------- | ---------------------------------------------------------------------------------------------- |
+| `share-resource`          | Grant a user or org access at a specific role. Optional `notify` controls email notifications. |
+| `unshare-resource`        | Revoke access for a user or org.                                                               |
+| `list-resource-shares`    | Show current visibility plus all explicit grants.                                              |
+| `set-resource-visibility` | Change to `private`, `org`, or `public`.                                                       |
 
 Tell the agent "share this design with the marketing team as editors" and it calls `share-resource` against the same endpoint the UI uses. The result shows up in the share dialog the next render.
 
@@ -132,11 +133,12 @@ registerShareableResource({
   sharesTable: schema.deckShares,
   displayName: "Deck",
   titleColumn: "title",
+  getResourcePath: (deck) => `/deck/${deck.id}`,
   getDb,
 });
 ```
 
-After that, list/read queries pass through `accessFilter()` and write actions use `assertAccess()` to enforce roles. The full pattern (including create-action ownership stamping and the migration recipe for existing tables) lives in the `sharing` agent skill — the agent reads it on demand when building a sharing-aware feature.
+After that, list/read queries pass through `accessFilter()` and write actions use `assertAccess()` to enforce roles. `getResourcePath` gives notification emails a direct fallback link when a share is created by the agent or another non-UI caller. The full pattern (including create-action ownership stamping and the migration recipe for existing tables) lives in the `sharing` agent skill — the agent reads it on demand when building a sharing-aware feature.
 
 ## Security guarantees {#security}
 

package/docs/content/template-dispatch.md

@@ -71,6 +71,23 @@ pnpm dlx @agent-native/core create my-platform
 
 Dispatch is usually scaffolded into a workspace alongside the apps it coordinates. For a workspace, Dispatch's shared auth, database, and brand are inherited from the workspace core — see [Multi-App Workspace](/docs/multi-app-workspace).
 
+## First local run {#first-local-run}
+
+From the workspace root:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Open the Dispatch URL printed by the dev server. Local development uses the same Better Auth sign-in flow as production. Create a local account with email + password; email verification is skipped in development, and the password is stored only in your local app database. There is no supported auth bypass in the default scaffold, because the agent, workspace resources, vault, and sharing model all rely on a real user session.
+
+You can click through the Dispatch UI after signing in. To use the chat composer or run agent tasks, connect an LLM provider first:
+
+1. Open **Settings**.
+2. In **LLM**, either connect Builder.io or add your own provider key such as `ANTHROPIC_API_KEY`.
+3. Return to **Overview** and try the composer.
+
 ## Customize it {#customize}
 
 Dispatch is a full template like any other — see [Templates](/docs/cloneable-saas). Ask the agent to "add a new integration for Datadog" or "route Slack DMs from channel X to the issues agent" and it'll edit the routing config, add the webhook handler, and wire it up.

package/docs/content/template-images.md

@@ -0,0 +1,54 @@
+---
+title: "Images"
+description: "An agent-native image library and cross-agent image service for brand-consistent AI imagery."
+---
+
+# Images
+
+Images is an agent-native workspace for creating brand-consistent AI imagery. It organizes references into flat Libraries, lets teams upload examples for blog heroes, diagrams, landing pages, product shots, and logos, then routes generation through the agent chat so every image can be reviewed and refined.
+
+Use it when your team needs reusable visual direction instead of one-off generic image prompts.
+
+## What You Can Do With It
+
+- **Create image libraries.** Group reference images, canonical logos, style notes, palettes, and generated output by brand, campaign, product, or image category.
+- **Generate through chat.** The home composer and library Generate controls send the prompt to the agent with `sendToAgentChat()`, so users can inspect variants, give feedback, and iterate.
+- **Upload references.** Add image examples from the library UI or the prompt composer attachment button, then tag them as hero, landing, product, logo, diagram, style-only, or other.
+- **Keep a generation audit log.** Every run records prompts, model, aspect ratio, references, source asset, lineage, generated assets, status, errors, and timestamps for later design review.
+- **Preserve logo accuracy.** The agent can generate a placeholder area and the server composites the uploaded canonical logo onto the final image instead of relying on the image model to redraw it.
+- **Serve other agents.** Slides, Design, Content, Mail, and Dispatch can call Images through A2A to list libraries, generate batches, refine an asset, fetch exports, and render inline previews where embedding is allowed.
+
+## Why It's Interesting
+
+Most AI image tools treat brand consistency as a prompt-writing problem. Images treats it as application state: references, collections, style briefs, run history, and saved assets live in SQL, while image bytes live in object storage or the local file-upload fallback during development.
+
+Because generation is an action and a chat workflow, the UI and the agent share the same operations. A user can start from the big prompt box, a library detail page, another app's chat, or an A2A request from Slides, and the same audit and lineage model is preserved.
+
+## For Developers
+
+The rest of this doc is for anyone forking the Images template or extending it.
+
+### Scaffolding
+
+```bash
+pnpm dlx @agent-native/core create my-images --template images --standalone
+```
+
+### Customize It
+
+Images is a complete, cloneable template. Some practical extension ideas:
+
+- "Add a product catalog connector so product reference shots can be selected by SKU."
+- "Add a strict approval queue before generated images are marked usable for marketing."
+- "Add a brand review dashboard that filters failed or low-rated generations by model."
+- "Create a workspace-wide default image library and route Slides image generation through it."
+- "Add a new provider behind the image generation interface after checking the latest provider docs."
+
+The agent edits routes, components, actions, skills, and SQL-backed models as needed. See [Templates](/docs/cloneable-saas) for the full clone, customize, deploy flow, and [A2A Protocol](/docs/a2a-protocol) for cross-app generation.
+
+## What's Next
+
+- [**Templates**](/docs/cloneable-saas) — the clone-and-own model
+- [**A2A Protocol**](/docs/a2a-protocol) — how other apps call Images
+- [**File Uploads**](/docs/file-uploads) — storage and authenticated asset serving
+- [**Sharing & Privacy**](/docs/sharing) — library-level access control

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.12.4",
+  "version": "0.12.6",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",