tokenoscopy 0.0.0-stage → 0.3.1

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+import { SessionSummary, SessionEvent } from '@tokenoscopy/shared';
+export { redactText, redactValue } from '@tokenoscopy/shared';
+
+/**
+ * How is this machine paying for tokens? It changes what the dollar figure
+ * MEANS, so guessing is worse than admitting we don't know.
+ *
+ *   api_key      — an API key or Console-billed OAuth account. Every token is
+ *                  marginal money. A runaway is a real invoice; a dollar cap
+ *                  is literally a dollar cap.
+ *   subscription — Pro/Max seat. The invoice is fixed, so our dollar figure
+ *                  is NOTIONAL (what this would have cost at API rates). The
+ *                  real scarce resource is the rolling usage limit: a retry
+ *                  loop doesn't cost extra money, it costs the developer
+ *                  their afternoon.
+ *
+ * Note that OAuth login does NOT imply either lane — Claude Code also signs
+ * in to Console accounts that bill per token. Each lane needs POSITIVE
+ * evidence; a signed-in account with nothing that says how it bills is
+ * `unknown`, not a guess.
+ *
+ * `hasAvailableSubscription` used to be the deciding field. It reads `false`
+ * on live Max accounts, which is how every seat in the fleet came to be
+ * labelled real money. The organisation fields on `oauthAccount` are what
+ * actually describe the plan.
+ */
+type AuthMode = "api_key" | "subscription" | "unknown";
+interface AuthVerdict {
+    mode: AuthMode;
+    /** Which fact decided it — shown by `doctor`, never uploaded. */
+    evidence: string;
+}
+/** The slice of ~/.claude.json we read. Every field is optional by design. */
+interface ClaudeJson {
+    hasAvailableSubscription?: boolean;
+    customApiKeyResponses?: {
+        approved?: string[];
+        rejected?: string[];
+    };
+    oauthAccount?: {
+        accountUuid?: string;
+        organizationType?: string | null;
+        billingType?: string | null;
+        organizationRateLimitTier?: string | null;
+        userRateLimitTier?: string | null;
+    };
+}
+type Env = Record<string, string | undefined>;
+declare function classifyAuth(env: Env, cfg: ClaudeJson | null): AuthVerdict;
+declare function readClaudeJson(): ClaudeJson | null;
+declare function detectAuth(): AuthVerdict;
+declare function detectAuthMode(): AuthMode;
+/** Is the dollar figure real money, or a notional list-price equivalent? */
+declare function costIsRealMoney(mode: AuthMode): boolean;
+
+/**
+ * Claude Code JSONL transcript parser.
+ *
+ * Format contract (empirically verified — docs/research/capture-surfaces.md §1.3):
+ * - Append-only, one JSON object per line, at ~/.claude/projects/<cwd-slug>/<session>.jsonl
+ * - Record types observed live: user / assistant / system / summary / attachment /
+ *   file-history-snapshot / last-prompt / mode / permission-mode / queue-operation
+ * - One LLM request can span MULTIPLE assistant records (one per content block),
+ *   each repeating the same `requestId` and the same `usage` — usage must be
+ *   counted exactly once per requestId (community-confirmed double-count trap).
+ * - Unknown record types are counted, preserved as warnings, never fatal —
+ *   the format is undocumented-but-stable and versioned per record.
+ */
+interface ParsedTranscript {
+    summary: SessionSummary;
+    events: SessionEvent[];
+    warnings: string[];
+}
+/** Derive a repo label from cwd WITHOUT leaking the full local path. */
+declare function repoLabelFromCwd(cwd: string | undefined): string | undefined;
+declare function parseTranscript(jsonl: string): ParsedTranscript;
+
+export { type AuthMode, type AuthVerdict, type ClaudeJson, type ParsedTranscript, classifyAuth, costIsRealMoney, detectAuth, detectAuthMode, parseTranscript, readClaudeJson, repoLabelFromCwd };

package/dist/index.js

@@ -0,0 +1,22 @@
+import {
+  classifyAuth,
+  costIsRealMoney,
+  detectAuth,
+  detectAuthMode,
+  parseTranscript,
+  readClaudeJson,
+  redactText,
+  redactValue,
+  repoLabelFromCwd
+} from "./chunk-AZYPMFOF.js";
+export {
+  classifyAuth,
+  costIsRealMoney,
+  detectAuth,
+  detectAuthMode,
+  parseTranscript,
+  readClaudeJson,
+  redactText,
+  redactValue,
+  repoLabelFromCwd
+};

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "tokenoscopy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.1",
+  "description": "Flight recorder & spend control for coding-agent fleets. Records Claude Code sessions (hooks + transcripts), replays them, and enforces budgets.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "tokenoscopy": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build && node ../../scripts/sdk-smoke.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsup": "^8.4.0",
+    "typescript": "^5",
+    "vitest": "^3.0.0",
+    "@tokenoscopy/shared": "0.0.1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getriff-ai/tokenoscopy.git",
+    "directory": "packages/sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://tokenoscopy.com",
+  "bugs": {
+    "url": "https://tokenoscopy.com/docs#support"
+  },
+  "keywords": [
+    "claude-code",
+    "ai-agents",
+    "observability",
+    "spend-control",
+    "session-replay",
+    "flight-recorder"
+  ]
+}