ai-spend-agent 0.9.11 → 0.9.13

package/README.md

@@ -1,58 +1,80 @@
-# ai-spend-agent
+# ai-spend-agent — Tilden’s free AI spend CLI
 
-The full [aibill](https://github.com/futurastudio/ai-spend-agent) CLI.
+Inspect Claude Code and Codex activity locally, see its estimated value at
+published API rates, and identify what deserves a closer look. Optional provider
+reports add billing evidence; estimates and reported costs stay separate.
 
 ```bash
-npx aibill init
-npx aibill statusline install # optional Claude Code cache-only status line
-npx ai-spend-agent
-# short alias
-npx aibill
+npx aibill@latest init
+npx aibill@latest --full
 ```
 
-Run `npx aibill init` from a project to detect machine-wide Claude Code, Codex,
-and experimental Gemini CLI financial evidence, print the first
-evidence-labeled personal receipt, and seed a private Claude/Codex aggregate
-cache under `~/.aibill/cache/`. Gemini financial rows come only from
-`~/.gemini/tmp/<opaque-project-id>/chats/**/*.{json,jsonl}`; `logs.json` is a
-presence signal and never a financial source. Init never replaces missing personal
-evidence with the bundled sample and never overwrites existing connected
-source or audit state.
-
-The optional status line is explicit and reversible. It installs a standalone
-Node-builtins-only runner at Claude user scope, rereads only the private
-aggregate cache, and never scans transcripts or contacts a provider from the
-hook. Subscription runway appears only when it was transcript-reported; `~`
-means API-equivalent value, and untilded `billed` money requires verified
-provider evidence. Remove it with `npx aibill statusline uninstall`.
-
-It reads supported local Claude Code, Codex, and Gemini CLI financial metadata,
-labels API-equivalent estimates, and can optionally add official OpenAI or
-Anthropic provider-reported cost
-through an environment-variable reference.
+Requires Node.js 22+. Free and MIT-licensed; no account or provider key is
+needed for local analysis. `aibill` and `ai-spend-agent` run the same CLI.
+Run from a project directory: `init` reviews the last 30 days of supported
+machine-wide records, uses that project for local state, and seeds the private
+Claude Code/Codex status cache. It does not change Claude settings or connect
+Workspace. Missing evidence stays missing; `--sample` explicitly selects a demo.
+
+Local values are API-equivalent estimates, not subscription charges or invoices.
+Claude Code/Codex readers are live-verified; Gemini CLI is experimental and
+fixture-verified, supported only in financial CLI/report/local MCP surfaces.
+Gemini does not feed statusline, Glance, Context Health, Apply or plan/runway.
+`npx aibill@latest doctor --sources` shows reader validation separately from
+each number’s financial label and coverage.
+
+## Choose a next step
+
+- `npx aibill@latest context`: inspect context evidence.
+- `npx aibill@latest improve`: guide one reversible token experiment; a result
+  requires matched completed sessions and user-declared quality, not a claim
+  of cash savings or ROI.
+- `npx aibill@latest statusline install`: optionally install the cache-only
+  Claude Code status line. Remove it with `statusline uninstall`.
+- `npx aibill@latest connect openai` or `connect anthropic`: register local
+  provider setup and print the separate `sync-provider` command. Only an
+  explicit sync reads the provider, using the required admin environment
+  credential reference. Cursor/Copilot connectors remain fixture-verified beta
+  pending real-account acceptance.
+
+## Use standalone or connect to Workspace
+
+Use the free CLI on its own, or keep working locally and connect it to your
+invited [Tilden Workspace](https://asktilden.com/docs/workspace) for a shared
+spending review. Start with `npx aibill@latest workspace connect`, complete the
+browser enrollment and sharing consent, then run
+`npx aibill@latest workspace push` to preview and approve a share. The browser
+does not need to stay open for later pushes while the machine’s grant and
+sharing consent remain valid. Shared facts include eligible
+Claude Code/Codex sessions, tokens and project labels where available, plus
+hashed identities; they exclude raw prompts, transcript contents, full paths,
+raw session IDs and dollar amounts. Local provider records are not uploaded.
+Hosted provider connections are set up separately.
+
+Read [Workspace setup and limits](https://github.com/futurastudio/ai-spend-agent/blob/main/docs/WORKSPACE.md)
+before pairing. [Join the Tilden waitlist](https://asktilden.com/?ref=npm-cli#beta)
+for updates and access invitations; joining does not grant immediate access.
+
+## Privacy
+
+Default transcript analysis runs locally. Reports remain local until shared.
+Explicit Workspace pushes send only the approved facts. Local MCP results go
+to the AI client you configure and follow its data policy. Explicit provider
+sync uses the referenced credential only with that provider’s read-only API;
 aibill never sits in the inference path and never stores, prints, or proxies provider credentials.
+Workspace pairing uses separate private local device credentials.
+
+**Telemetry: command counts, disclosed at first run.** Events begin
+only after the first interactive notice. They include a random installation ID
+and operational fields. Events can be linked to the same installation, but do
+not include your arguments, paths, prompts, project names,
+dollar amounts or email. `npx aibill telemetry off` disables them; so do
+`DO_NOT_TRACK`, `CI` or `AI_SPEND_NO_TELEMETRY` when non-empty.
+`npx aibill telemetry` shows the exact last payload.
+[Full telemetry disclosure](https://github.com/futurastudio/ai-spend-agent/blob/main/docs/TELEMETRY.md).
+The optional signup command sends its displayed email/ref payload only after
+confirmation; `outcome github` explicitly uses the installed `gh` CLI.
 
-**Telemetry: anonymous command counts, disclosed at first run.** Terminal
-analysis stays on your machine — transcripts, prompts, file names, and dollar
-amounts are never uploaded. Separately, the CLI counts *which* commands run:
-anonymous, never your arguments, paths, content, dollars, or your email.
-Nothing is sent before a one-time notice has been printed on an interactive
-run, so a machine that has never seen that notice (CI, scripts, pipes) never
-sends anything. One command turns it off — `aibill telemetry off` (or
-`DO_NOT_TRACK`, `CI`, or `AI_SPEND_NO_TELEMETRY`) — `aibill telemetry` prints
-the exact last payload verbatim, and while it is on every receipt says so in
-place of "nothing uploaded". Full scope and the never-list:
-[`docs/TELEMETRY.md`](https://github.com/futurastudio/ai-spend-agent/blob/main/docs/TELEMETRY.md).
-
-Connector validation (`live_verified`, `fixture_verified`, `untested`, or
-`failed`) and each number's financial evidence (`verified`, `estimated`,
-`detected_unverified`, or `missing`) are separate status axes. Run `npx aibill
-doctor --sources` to see both with freshness and the last sanitized error.
-The source registry also records read-boundary approval separately; an approved
-local folder is permission to scan, not verified financial evidence.
-
-See the repository
-[README](https://github.com/futurastudio/ai-spend-agent#readme) for commands,
-privacy boundaries, supported sources, and public-beta limitations.
-
-MIT licensed.
+[Full guide](https://github.com/futurastudio/ai-spend-agent#readme) ·
+[Source coverage](https://asktilden.com/docs/sources) ·
+[Command reference](https://github.com/futurastudio/ai-spend-agent/blob/main/docs/CLI_REFERENCE.md)

package/dist/index.js

@@ -592,7 +592,7 @@ function quickstartNextSteps(mode, detected) {
         command: "npx aibill --group-by project",
         description: "see which project has the most observed activity"
     });
-    steps.push("Need team reconciliation, allocation, budgets, and approvals? Workspace design partners: https://asktilden.com");
+    steps.push("Review supported AI spend in Tilden Workspace with our team’s help. The pilot has one owner seat. CLI sharing is optional and explicit; register interest: https://asktilden.com/?ref=aibill-workspace#beta");
     if (mode === "demo") {
         // Static pointer only — sample output is built for recordings and
         // screenshots, so it never prompts (capture design moments map).
@@ -1256,7 +1256,7 @@ async function signupCommand(args, runtime) {
     };
 }
 /**
- * `aibill telemetry [on|off]` — inspect or switch anonymous command-count
+ * `aibill telemetry [on|off]` — inspect or switch installation-linked command-count
  * telemetry. Status shows the EXACT last payload verbatim; state is
  * fail-closed (corrupt/readonly ⇒ off).
  */
@@ -1315,8 +1315,8 @@ async function telemetryCommand(args, runtime) {
             };
         }
         return ok([
-            "telemetry on · anonymous command counts only",
-            `counted: command name, version, os, arch, ci flag, duration bucket, ok flag, timestamp`,
+            "telemetry on · installation-linked command counts only",
+            `counted: random installation ID, command name, version, os, arch, ci flag, duration bucket, ok flag, timestamp`,
             "never: arguments, paths, file contents, project names, or your email",
             "events start with your next run · see payloads anytime: npx aibill telemetry"
         ].join("\n"));
@@ -1338,12 +1338,12 @@ async function telemetryCommand(args, runtime) {
     else {
         lines.push(`status: on · noticed ${read.state.noticedAt}`);
     }
-    lines.push("counted: command name, version, os, arch, ci flag, duration bucket, ok flag, timestamp", "never: arguments, paths, file contents, project names, or your email");
+    lines.push("counted: random installation ID, command name, version, os, arch, ci flag, duration bucket, ok flag, timestamp", "never: arguments, paths, file contents, project names, or your email");
     if (read.kind === "ok" && read.state.lastPayload !== undefined) {
-        lines.push("last payload sent (verbatim):", read.state.lastPayload);
+        lines.push("last attempted payload (verbatim; delivery unconfirmed):", read.state.lastPayload);
     }
     else {
-        lines.push("last payload sent: none");
+        lines.push("last attempted payload: none");
     }
     lines.push("switch: npx aibill telemetry on · npx aibill telemetry off");
     return ok(lines.join("\n"));
@@ -3401,10 +3401,10 @@ const providerAdminEnvHint = {
 };
 function providerSyncSetupCommand(provider, adminRef) {
     if (provider === "cursor") {
-        return `npx aibill sync-provider --provider cursor --auth-reference ${adminRef} --account-id <team-label>`;
+        return `npx aibill sync-provider --provider cursor --auth-reference ${adminRef} --account-id '<team-label>'`;
     }
     if (provider === "github-copilot") {
-        return `npx aibill sync-provider --provider github-copilot --auth-reference ${adminRef} --org <organization>`;
+        return `npx aibill sync-provider --provider github-copilot --auth-reference ${adminRef} --org '<organization>'`;
     }
     const thirtyDaysAgoUnix = Math.floor(Date.now() / 1_000) - 30 * 24 * 60 * 60;
     return `npx aibill sync-provider --provider ${provider} --auth-reference ${adminRef} --start-time ${thirtyDaysAgoUnix}`;
@@ -7461,7 +7461,7 @@ function helpText(telemetryDisclosure) {
         "  statusline expand       Print every subscription with committed price, runways, and 7d API-equivalent",
         "  signup <email> [--ref <token>]  Join the launch list · email only · the exact payload is shown before send",
         "    [--never]             Never ask again (nothing is sent)   [--forget]  Clear local signup state",
-        "  telemetry [on|off]      Show anonymous command-count status + the exact last payload · switch it",
+        "  telemetry [on|off]      Show installation-linked command-count status + the exact last payload · switch it",
         "  doctor [--sources]      Launch diagnostics; --sources shows validation, evidence, freshness, and errors",
         "  reset [--path <dir>]    Clear persisted spend state (so sample state can't mask real logs)",
         "  --ignore-state          On the default/quickstart run, ignore persisted spend.json for this run",

package/dist/telemetry.d.ts

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 /**
- * CLI telemetry — anonymous command counts, notice-before-first-byte.
+ * CLI telemetry — installation-linked command counts, notice-before-first-byte.
  *
  * Consent model (founder decision 2026-08-24, disclosed opt-out):
  * - Run 1 (interactive) prints a three-line notice AFTER the output and
@@ -55,7 +55,7 @@ export type TelemetryEvent = {
  * incident — "command not found").
  */
 export declare const telemetryDisclosureLine: string;
-export declare const telemetryNoticeLines: readonly ["aibill counts which commands run — anonymous, never your data or content", `turn off: ${string}`, `see payloads: ${string}`];
+export declare const telemetryNoticeLines: readonly ["aibill counts commands by random installation ID — no arguments, paths or content", `turn off: ${string}`, `see payloads: ${string}`];
 export declare function telemetryOsLabel(platform?: string): TelemetryOs;
 export declare function telemetryArchLabel(arch?: string): TelemetryArch;
 export declare function telemetryDurationBucket(durationMs: number): TelemetryDurationBucket;

package/dist/telemetry.js

@@ -5,7 +5,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { aibillCommandV0 } from "@agent-finops/core";
 /**
- * CLI telemetry — anonymous command counts, notice-before-first-byte.
+ * CLI telemetry — installation-linked command counts, notice-before-first-byte.
  *
  * Consent model (founder decision 2026-08-24, disclosed opt-out):
  * - Run 1 (interactive) prints a three-line notice AFTER the output and
@@ -69,9 +69,9 @@ export const telemetryCommands = [
  * npx form): npx users have no bare `aibill` on PATH (0.9.2 founder
  * incident — "command not found").
  */
-export const telemetryDisclosureLine = `anonymous command counts shared · ${aibillCommandV0("telemetry off")}`;
+export const telemetryDisclosureLine = `installation-linked command counts shared · ${aibillCommandV0("telemetry off")}`;
 export const telemetryNoticeLines = [
-    "aibill counts which commands run — anonymous, never your data or content",
+    "aibill counts commands by random installation ID — no arguments, paths or content",
     `turn off: ${aibillCommandV0("telemetry off")}`,
     `see payloads: ${aibillCommandV0("telemetry")}`
 ];
@@ -318,7 +318,7 @@ export async function openCliTelemetry(options = {}) {
                     return;
                 // `glance` is a machine-invoked poll (the Glance menu-bar app spawns
                 // it every ~30s), not a human command — counting it is noise by
-                // definition and would flood the anonymous command counts (~2,880
+                // definition and would flood the installation-linked command counts (~2,880
                 // events/day/user). Never emit for it, notice or not; the label
                 // still exists in the map so any stray event is at least honest.
                 if (telemetryCommandForArgv(input.argv) === "glance")

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "ai-spend-agent",
-  "version": "0.9.11",
+  "version": "0.9.13",
   "funding": "https://asktilden.com",
-  "description": "Local-first financial accountability CLI: Claude Code/Codex attribution, provenance, and next actions, plus experimental Gemini CLI cost evidence.",
+  "description": "Tilden\u2019s free CLI for local coding-agent usage and optional provider cost reports. Estimates, reported costs and missing coverage stay separate.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -55,8 +55,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@agent-finops/core": "0.9.11",
-    "@agent-finops/report": "0.9.11",
+    "@agent-finops/core": "0.9.13",
+    "@agent-finops/report": "0.9.13",
     "yocto-spinner": "^1.2.0"
   }
 }