ai-spend-agent 0.9.10 → 0.9.12

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).
@@ -1098,14 +1098,17 @@ async function workspaceCommand(args, runtime) {
                     : fail("Pairing outcome is unknown. Do not replay this response bundle; inspect and revoke the enrollment in Settings before starting another.");
         }
         if (action === "disconnect") {
-            const result = await disconnectWorkspace({ home: runtime.homeDirectory, transport: runtime.workspaceDisconnectTransport,
+            const result = await disconnectWorkspace({ home: runtime.homeDirectory, retry: args.workspaceDisconnectRetry, transport: runtime.workspaceDisconnectTransport,
                 confirm: action => consent(action === "abandon_unexchanged"
                     ? "This native request has never attempted exchange. Destroy its unused private pairing key so it can no longer complete enrollment? Cancel any browser challenge in Settings as well. [y/N] "
-                    : "Revoke this machine's Workspace grant and remove its local pairing after the accepted receipt? [y/N] ") });
-            return result.state === "revoked" ? ok("Workspace revoked this machine grant. Local pairing was removed.")
-                : result.state === "abandoned" ? ok("Unused native pairing key removed. No remote revocation was claimed. Run npx aibill workspace connect to start a new request.")
-                    : result.state === "cancelled" ? fail("Pairing kept. Disconnect was not confirmed; no request or key was removed.") : result.state === "not_paired" ? ok("No completed local pairing exists.")
-                        : fail(`Disconnect outcome is unknown. Local keys remain; no retry was sent. Reconcile this machine at ${WORKSPACE_ORIGIN}/settings/machines.`);
+                    : action === "retry_revoke"
+                        ? "Repeat the identical retained disconnect request once? If already revoked, Tilden returns that outcome; otherwise this revokes the same grant. No session facts are sent. Local pairing is removed only after a matching receipt. [y/N] "
+                        : "Revoke this machine's Workspace grant and remove its local pairing after the accepted receipt? [y/N] ") });
+            return result.state === "retry_not_pending" ? fail("No uncertain disconnect is retained. Run workspace disconnect without --retry to start a new disconnect.")
+                : result.state === "revoked" ? ok("Workspace revoked this machine grant. Local pairing was removed.")
+                    : result.state === "abandoned" ? ok("Unused native pairing key removed. No remote revocation was claimed. Run npx aibill workspace connect to start a new request.")
+                        : result.state === "cancelled" ? fail("Pairing kept. Disconnect was not confirmed; no request or key was removed.") : result.state === "not_paired" ? ok("No completed local pairing exists.")
+                            : fail(`Disconnect outcome is unknown. Local keys remain and uploads are blocked. Run npx aibill@latest workspace disconnect --retry to review and explicitly repeat the identical retained request once, or inspect this machine at ${WORKSPACE_ORIGIN}/settings/machines.`);
         }
         const status = await workspaceStatus(runtime.homeDirectory);
         if (status.state !== "connected")
@@ -1253,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).
  */
@@ -1312,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"));
@@ -1335,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"));
@@ -3398,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}`;
@@ -6756,8 +6759,12 @@ function parseArgs(argv) {
             parsed.workspaceRestart = true;
             rest.shift();
         }
+        if (parsed.workspaceAction === "disconnect" && rest.length === 1 && rest[0] === "--retry") {
+            parsed.workspaceDisconnectRetry = true;
+            rest.shift();
+        }
         if (rest.length)
-            parsed.parseErrors.push("workspace accepts only connect [response-bundle], connect --restart, push, status, or disconnect");
+            parsed.parseErrors.push("workspace accepts only connect [response-bundle], connect --restart, push, status, or disconnect [--retry]");
     }
     if (command === "statusline" && rest[0] && !rest[0].startsWith("--")) {
         parsed.statuslineAction = rest.shift();
@@ -7429,6 +7436,7 @@ function helpText(telemetryDisclosure) {
         "  npx aibill workspace push            Preview and send local session facts",
         "  npx aibill workspace status          Read local pairing/pending status only",
         "  npx aibill workspace disconnect      Revoke the grant or abandon an unused pairing key",
+        "  npx aibill workspace disconnect --retry  Confirm one identical uncertain disconnect attempt",
         "",
         "Add official provider-reported cost (ADMIN/owner-gated):",
         "  npx aibill connect openai            Requires an org-owner Admin credential reference",
@@ -7453,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/dist/workspaceConnect.d.ts

@@ -227,13 +227,14 @@ export declare function finishWorkspaceEnrollment(options: {
 }): Promise<{
     state: "connected" | "cancelled" | "unconfirmed";
 }>;
-/** Revocation is one native attempt. Unknown outcomes retain keys and block further writes. */
+/** One native attempt per confirmation. Explicit recovery repeats the retained proof; unknown outcomes keep writes blocked. */
 export declare function disconnectWorkspace(options: {
     home?: string;
-    confirm: (action: "revoke" | "abandon_unexchanged") => Promise<boolean>;
+    retry?: boolean;
+    confirm: (action: "revoke" | "retry_revoke" | "abandon_unexchanged") => Promise<boolean>;
     transport?: WorkspaceDisconnectTransport;
 }): Promise<{
-    state: "revoked" | "abandoned" | "cancelled" | "unconfirmed" | "not_paired";
+    state: "revoked" | "abandoned" | "cancelled" | "unconfirmed" | "not_paired" | "retry_not_pending";
 }>;
 export {};
 //# sourceMappingURL=workspaceConnect.d.ts.map

package/dist/workspaceConnect.js

@@ -668,9 +668,11 @@ export async function finishWorkspaceEnrollment(options) {
         }
     });
 }
-/** Revocation is one native attempt. Unknown outcomes retain keys and block further writes. */
+/** One native attempt per confirmation. Explicit recovery repeats the retained proof; unknown outcomes keep writes blocked. */
 export async function disconnectWorkspace(options) {
     return withState(options.home ?? homedir(), async (state, save, path) => {
+        if (options.retry && state?.disconnect?.state !== "uncertain")
+            return { state: "retry_not_pending" };
         if (!state) {
             const enrollment = await readEnrollment(path);
             if (!enrollment)
@@ -692,14 +694,14 @@ export async function disconnectWorkspace(options) {
             }
             return { state: "abandoned" };
         }
-        if (state.disconnect?.state === "uncertain")
+        if (state.disconnect?.state === "uncertain" && !options.retry)
             return { state: "unconfirmed" };
-        if (!await options.confirm("revoke"))
+        if (!await options.confirm(state.disconnect?.state === "uncertain" ? "retry_revoke" : "revoke"))
             return { state: "cancelled" };
-        if (!state.disconnect) {
+        if (state.disconnect?.state !== "revoked") {
             const proof = { purpose: "machine_disconnect_v1", grantId: state.device.grantId,
                 grantRevision: state.device.grantRevision, connectionEpoch: state.device.connectionEpoch,
-                requestId: `oref_${randomBytes(32).toString("base64url")}` };
+                requestId: state.disconnect?.requestId ?? `oref_${randomBytes(32).toString("base64url")}` };
             const body = { ...proof, publicKey: createPublicKey(state.device.privateKeyPem).export({ format: "jwk" }).x,
                 signature: sign(null, Buffer.from(workspaceCanonicalJson(proof)), state.device.privateKeyPem).toString("base64url") };
             const uncertain = { ...state, disconnect: { state: "uncertain", requestId: proof.requestId, revokedAt: null } };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "ai-spend-agent",
-  "version": "0.9.10",
+  "version": "0.9.12",
   "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.10",
-    "@agent-finops/report": "0.9.10",
+    "@agent-finops/core": "0.9.12",
+    "@agent-finops/report": "0.9.12",
     "yocto-spinner": "^1.2.0"
   }
 }