agentix-cli 0.116.0 → 0.118.0

package/dist/chunk-4FU4BFCH.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/observability/surface-usage.ts"],"sourcesContent":["import { existsSync } from \"fs\"\nimport { resolve } from \"path\"\nimport { openDb } from \"@/storage/sqlite\"\n\n// --- Which operator surfaces actually get used ---\n//\n// `task_history` answers \"which agents ran\". It says nothing about which of\n// the ~46 CLI commands or 16 dashboard pages anyone ever opens — and those are\n// the two biggest surfaces by count, so they are exactly what the\n// surface-reduction work needs evidence for.\n//\n// See docs/architecture/surface-reduction.md for the bar a surface has to\n// clear to survive. This module is the missing measurement.\n//\n// Three rules, all of them about being unobtrusive:\n//\n//   1. Names only. `agentx guard log --limit 5` records \"guard log\". A page\n//      view records \"/live\". Never arguments, never query strings, never\n//      payloads. This counts which door was opened, not what went through it.\n//   2. Never create state. If there is no `.agentx` here, we are being run\n//      from someone's home directory or a random repo — recording would\n//      litter a stray database. Do nothing instead.\n//   3. Never throw, never block. A telemetry bug must not break the CLI or a\n//      dashboard request. Every failure is swallowed.\n\n/**\n * True while a test runner is driving us.\n *\n * Three suites (trace-cli, process-cli, intent-ledger-cli) shell out to the\n * real CLI, so a full `pnpm test` recorded dozens of invocations of exactly\n * the commands that happen to have CLI tests — `trace list` showed 72 uses\n * against a human total of zero. That is worse than no data: it inverts the\n * ranking, making well-tested commands look popular and untested ones look\n * dead, which is precisely backwards for deciding what to remove.\n */\nfunction underTest(): boolean {\n  return Boolean(process.env.VITEST || process.env.NODE_ENV === \"test\" || process.env.AGENTX_NO_TELEMETRY)\n}\n\n/** Where the install lives, or null when we're not inside one. Never creates\n *  anything — the check IS the guard against writing stray databases. */\nfunction installRoot(): string | null {\n  let dir = process.cwd()\n  for (let i = 0; i < 5; i++) {\n    if (existsSync(resolve(dir, \".agentx\")) || existsSync(resolve(dir, \"agentx.json\"))) return dir\n    const parent = resolve(dir, \"..\")\n    if (parent === dir) break\n    dir = parent\n  }\n  return null\n}\n\nfunction today(now = new Date()): string {\n  return now.toISOString().slice(0, 10)\n}\n\nexport type SurfaceKind = \"cli\" | \"page\"\n\n/**\n * Record one use of a surface. Silent no-op when we're outside an install,\n * when SQLite is unavailable, or on any error.\n */\nexport function recordSurfaceUse(kind: SurfaceKind, name: string, now = new Date()): void {\n  try {\n    if (!name) return\n    if (underTest()) return\n    if (!installRoot()) return\n    const db = openDb({ quiet: true })\n    if (!db) return\n    db.prepare(\n      `INSERT INTO surface_usage (kind, name, day, count, last_at)\n       VALUES (?, ?, ?, 1, ?)\n       ON CONFLICT(kind, name, day)\n       DO UPDATE SET count = count + 1, last_at = excluded.last_at`,\n    ).run(kind, name, today(now), now.toISOString())\n  } catch {\n    /* telemetry must never break the thing it measures */\n  }\n}\n\nexport interface SurfaceRow {\n  kind: string\n  name: string\n  count: number\n  days: number\n  last_at: string | null\n}\n\n/** Usage totals over a window, busiest first. Powers `agentx usage surfaces`. */\nexport function listSurfaceUse(opts: { kind?: SurfaceKind; sinceDays?: number } = {}): SurfaceRow[] {\n  try {\n    const db = openDb({ quiet: true })\n    if (!db) return []\n    const since = new Date(Date.now() - (opts.sinceDays ?? 30) * 86_400_000)\n      .toISOString()\n      .slice(0, 10)\n    const where = [\"day >= ?\"]\n    const params: unknown[] = [since]\n    if (opts.kind) {\n      where.push(\"kind = ?\")\n      params.push(opts.kind)\n    }\n    return db\n      .prepare(\n        `SELECT kind, name, SUM(count) AS count, COUNT(DISTINCT day) AS days, MAX(last_at) AS last_at\n         FROM surface_usage\n         WHERE ${where.join(\" AND \")}\n         GROUP BY kind, name\n         ORDER BY count DESC`,\n      )\n      .all(...params) as SurfaceRow[]\n  } catch {\n    return []\n  }\n}\n\n/**\n * The command path a commander invocation resolved to — \"guard log\", not\n * \"guard log --limit 5\". Walks up from the deepest matched subcommand so\n * nesting is preserved without ever touching argv.\n */\nexport function commandPath(cmd: { name(): string; parent?: unknown } | null | undefined): string {\n  const parts: string[] = []\n  let node: any = cmd\n  while (node && typeof node.name === \"function\") {\n    const n = node.name()\n    // The root program is \"agentx\" itself — not a surface worth counting.\n    if (node.parent) parts.unshift(n)\n    node = node.parent\n  }\n  return parts.join(\" \")\n}\n\n/** Hook entrypoints fire per tool call, not per human decision. Counting them\n *  would swamp the table and tell us nothing about operator behaviour. */\nconst NOT_A_SURFACE = new Set([\"guard check\", \"completion\", \"serve\"])\n\nexport function shouldRecordCommand(path: string): boolean {\n  return Boolean(path) && !NOT_A_SURFACE.has(path)\n}\n"],"mappings":"+CAEAA,IAFA,OAAS,cAAAC,MAAkB,KAC3B,OAAS,WAAAC,MAAe,OAkCxB,SAASC,GAAqB,CAC5B,MAAO,GAAQ,QAAQ,IAAI,QAAU,QAAQ,IAAI,WAAa,QAAU,QAAQ,IAAI,oBACtF,CAIA,SAASC,GAA6B,CACpC,IAAIC,EAAM,QAAQ,IAAI,EACtB,QAASC,EAAI,EAAGA,EAAI,EAAGA,IAAK,CAC1B,GAAIL,EAAWC,EAAQG,EAAK,SAAS,CAAC,GAAKJ,EAAWC,EAAQG,EAAK,aAAa,CAAC,EAAG,OAAOA,EAC3F,IAAME,EAASL,EAAQG,EAAK,IAAI,EAChC,GAAIE,IAAWF,EAAK,MACpBA,EAAME,EAER,OAAO,IACT,CAEA,SAASC,EAAMC,EAAM,IAAI,KAAgB,CACvC,OAAOA,EAAI,YAAY,EAAE,MAAM,EAAG,EAAE,CACtC,CAQO,SAASC,EAAiBC,EAAmBC,EAAcH,EAAM,IAAI,KAAc,CACxF,GAAI,CAGF,GAFI,CAACG,GACDT,EAAU,GACV,CAACC,EAAY,EAAG,OACpB,IAAMS,EAAKC,EAAO,CAAE,MAAO,EAAK,CAAC,EACjC,GAAI,CAACD,EAAI,OACTA,EAAG,QACD;AAAA;AAAA;AAAA,mEAIF,EAAE,IAAIF,EAAMC,EAAMJ,EAAMC,CAAG,EAAGA,EAAI,YAAY,CAAC,CACjD,MAAE,CAEF,CACF,CAWO,SAASM,EAAeC,EAAmD,CAAC,EAAiB,CAClG,GAAI,CACF,IAAMH,EAAKC,EAAO,CAAE,MAAO,EAAK,CAAC,EACjC,GAAI,CAACD,EAAI,MAAO,CAAC,EACjB,IAAMI,EAAQ,IAAI,KAAK,KAAK,IAAI,GAAKD,EAAK,WAAa,IAAM,KAAU,EACpE,YAAY,EACZ,MAAM,EAAG,EAAE,EACRE,EAAQ,CAAC,UAAU,EACnBC,EAAoB,CAACF,CAAK,EAChC,OAAID,EAAK,OACPE,EAAM,KAAK,UAAU,EACrBC,EAAO,KAAKH,EAAK,IAAI,GAEhBH,EACJ,QACC;AAAA;AAAA,iBAESK,EAAM,KAAK,OAAO;AAAA;AAAA,6BAG7B,EACC,IAAI,GAAGC,CAAM,CAClB,MAAE,CACA,MAAO,CAAC,CACV,CACF,CAOO,SAASC,EAAYC,EAAsE,CAChG,IAAMC,EAAkB,CAAC,EACrBC,EAAYF,EAChB,KAAOE,GAAQ,OAAOA,EAAK,MAAS,YAAY,CAC9C,IAAMC,EAAID,EAAK,KAAK,EAEhBA,EAAK,QAAQD,EAAM,QAAQE,CAAC,EAChCD,EAAOA,EAAK,OAEd,OAAOD,EAAM,KAAK,GAAG,CACvB,CAIA,IAAMG,EAAgB,IAAI,IAAI,CAAC,cAAe,aAAc,OAAO,CAAC,EAE7D,SAASC,EAAoBC,EAAuB,CACzD,MAAO,EAAQA,GAAS,CAACF,EAAc,IAAIE,CAAI,CACjD","names":["init_sqlite","existsSync","resolve","underTest","installRoot","dir","i","parent","today","now","recordSurfaceUse","kind","name","db","openDb","listSurfaceUse","opts","since","where","params","commandPath","cmd","parts","node","n","NOT_A_SURFACE","shouldRecordCommand","path"]}