@yanzc/claude-pro 0.0.0-stage → 0.4.1

package/src/cache.js

@@ -0,0 +1,150 @@
+// Prompt caching, the way Claude Code does it (https://code.claude.com/docs/en/prompt-caching):
+//   - cache_control markers go on the tools, the system prompt and the newest message (see api.js);
+//   - there are two TTL buckets: "main" is the conversation itself, "other" is everything else
+//     (sub-agents, compaction, side queries). Each is 5 minutes by default, or 1 hour when asked for;
+//   - the whole thing can be switched off;
+//   - what the API reports (cache_read_input_tokens, cache_creation_input_tokens) is tracked here, so
+//     that /cost can say how much of the input came from the cache and why a request missed it.
+
+import crypto from 'node:crypto';
+
+export const TTL_MS = { '5m': 5 * 60_000, '1h': 60 * 60_000 };
+
+// A TTL setting is "5m" or "1h"; Claude Code ignores any other value, and so does this.
+export function normalizeTtl(value) {
+  const v = String(value ?? '').trim().toLowerCase();
+  return v === '5m' || v === '1h' ? v : null;
+}
+
+// The 5-minute TTL is the API's default, so it is sent without a ttl field: the request is then the same as
+// it always was, and endpoints that do not know the field are not bothered by it.
+export function cacheControl(ttl) {
+  return ttl === '1h' ? { type: 'ephemeral', ttl: '1h' } : { type: 'ephemeral' };
+}
+
+const sha = (text) => crypto.createHash('sha1').update(text).digest('hex').slice(0, 16);
+
+// What decides whether two requests can share a cache: the model, the system prompt, the tool definitions and
+// the parameters that are part of the key. (The messages are compared by the caller's own notes: see noteRewrite.)
+export function fingerprint(params) {
+  const system = (params.system || []).map((b) => b.text).join('\n');
+  const tools = JSON.stringify((params.tools || []).map(({ cache_control, ...rest }) => rest));
+  return {
+    model: params.model,
+    system: sha(system),
+    tools: sha(tools),
+    effort: params.output_config?.effort || null,
+    thinking: JSON.stringify(params.thinking || null),
+  };
+}
+
+// The TTL a request ended up with, and whether it carries any marker at all.
+export function cachePlanOf(params) {
+  const marks = [
+    ...(params.system || []).map((b) => b.cache_control),
+    ...(params.tools || []).map((t) => t.cache_control),
+    ...(params.messages || []).flatMap((m) => (Array.isArray(m.content) ? m.content.map((b) => b.cache_control) : [])),
+  ].filter(Boolean);
+  return { caching: marks.length > 0, ttl: marks.some((m) => m.ttl === '1h') ? '1h' : '5m' };
+}
+
+// Below this size the API does not cache anything (the smallest minimum of any model).
+const MIN_CACHED = 1024;
+// A request that read less than this share of what the previous one left in the cache missed.
+const MISS_BELOW = 0.5;
+
+const human = (ms) => {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  return m < 60 ? `${m}m ${s % 60}s` : `${Math.floor(m / 60)}h ${m % 60}m`;
+};
+
+export class CacheStats {
+  constructor() {
+    this.requests = 0; // requests recorded (compaction included)
+    this.input = 0; // input tokens that were not cached
+    this.read = 0; // input tokens read from the cache
+    this.write = 0; // input tokens written to the cache
+    this.write1h = 0; // ... of which with the 1-hour TTL
+    this.misses = 0;
+    this.lastMiss = null; // {n, cause, expected, read}
+    this.newConversation();
+  }
+
+  // The next request starts a conversation: there is nothing that it should find in the cache.
+  newConversation() {
+    this.expected = null; // tokens the previous request left cached; the next one should read about that many
+    this.prev = null; // fingerprint of the previous request
+    this.expiresAt = 0; // when what the previous request left in the cache runs out
+    this.ttl = '5m';
+    this.model = null; // the model that answered the last request
+    this.effort = null;
+  }
+
+  // The history was cut or replaced (compaction, /rewind, /resume): the next request will not find the old
+  // one in the cache, and that is expected, not a miss.
+  noteRewrite() {
+    this.expected = null;
+  }
+
+  // One finished request. `at` is when it started: the TTL counts from there, not from the end of the reply.
+  record({ usage, fingerprint: fp = null, ttl = '5m', caching = true, at = Date.now() }) {
+    const u = usage || {};
+    const input = u.input_tokens || 0;
+    const read = u.cache_read_input_tokens || 0;
+    const write = u.cache_creation_input_tokens || 0;
+    this.requests++;
+    this.input += input;
+    this.read += read;
+    this.write += write;
+    this.write1h += u.cache_creation?.ephemeral_1h_input_tokens || 0;
+    if (caching && this.expected != null && this.expected >= MIN_CACHED && read < this.expected * MISS_BELOW) {
+      this.misses++;
+      this.lastMiss = { n: this.requests, cause: this.causeOf(fp, at), expected: this.expected, read };
+    }
+    // Whatever this request read or wrote is a prefix of the next one.
+    this.expected = caching ? read + write : null;
+    this.expiresAt = at + TTL_MS[ttl];
+    this.ttl = ttl;
+    if (fp) {
+      this.prev = fp;
+      this.model = fp.model;
+      this.effort = fp.effort;
+    }
+  }
+
+  causeOf(fp, at) {
+    const p = this.prev;
+    if (p && fp) {
+      if (p.model !== fp.model) return `the model changed (${p.model} → ${fp.model})`;
+      if (p.system !== fp.system) return 'the system prompt changed';
+      if (p.tools !== fp.tools) return 'the tool definitions changed';
+      if (p.effort !== fp.effort) return `the effort changed (${p.effort || 'auto'} → ${fp.effort || 'auto'})`;
+      if (p.thinking !== fp.thinking) return 'the thinking settings changed';
+    }
+    if (at >= this.expiresAt) return `the cache had expired (${human(at - (this.expiresAt - TTL_MS[this.ttl]))} since the previous request, TTL ${this.ttl})`;
+    return 'earlier messages changed, or the endpoint does not cache';
+  }
+
+  // Is there something worth keeping in the cache right now? Not when nothing was cached, or it has expired.
+  isWarm(now = Date.now()) {
+    return this.expected != null && this.expected >= MIN_CACHED && now < this.expiresAt;
+  }
+
+  get hitRatio() {
+    const total = this.input + this.read + this.write;
+    return total > 0 ? this.read / total : null;
+  }
+
+  // The lines /cost shows for this conversation's cache.
+  describe(now = Date.now()) {
+    if (!this.requests) return [];
+    if (!this.read && !this.write) return ['Prompt cache:  nothing reported (the endpoint does not report cache use, or does not cache)'];
+    const pct = this.hitRatio == null ? '–' : `${Math.round(this.hitRatio * 100)}%`;
+    const state = this.isWarm(now) ? `warm for ${human(this.expiresAt - now)} more` : 'cold';
+    const lines = [`Prompt cache:  ${pct} of the input came from the cache · ${this.misses} miss${this.misses === 1 ? '' : 'es'} · ${state} (TTL ${this.ttl})`];
+    if (this.lastMiss) lines.push(`  last miss: request ${this.lastMiss.n}, probably because ${this.lastMiss.cause}`);
+    return lines;
+  }
+}

package/src/checkpoints.js

@@ -0,0 +1,184 @@
+// Checkpoints: before the agent edits a file (Write / Edit / NotebookEdit), the file's
+// previous content is saved, grouped by the user prompt that led to the edit. /rewind can
+// then put files back, rewind the conversation, or both. Changes made by shell commands
+// (Bash) are not tracked.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { estimateTokens } from './agent.js';
+
+const MAX_SNAPSHOT_BYTES = 200 * 1024 * 1024;
+const keyOf = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
+
+export class CheckpointStore {
+  // dir: where snapshot files are kept (created lazily).
+  constructor(dir) {
+    this.dir = dir;
+    // {id, label, time, messageIndex, conversationValid, orphaned, files: [{path, existed, snap, skipped}]}
+    this.entries = [];
+    this.counter = 0;
+    this.current = null;
+  }
+
+  // Start a checkpoint for a new user prompt. messageIndex is where its message will sit in
+  // the conversation, so rewinding the conversation can cut it off there.
+  beginTurn({ label, messageIndex }) {
+    const entry = {
+      id: ++this.counter,
+      label: String(label || '').replace(/\s+/g, ' ').trim().slice(0, 200),
+      time: Date.now(),
+      messageIndex,
+      conversationValid: true,
+      orphaned: false,
+      files: [],
+    };
+    this.entries.push(entry);
+    this.current = entry;
+    return entry;
+  }
+
+  // Record `file` as it is now, once per checkpoint. Call before the file is changed.
+  track(file) {
+    const entry = this.current;
+    if (!entry) return;
+    const abs = path.resolve(file);
+    if (entry.files.some((f) => keyOf(f.path) === keyOf(abs))) return;
+    let stat = null;
+    try { stat = fs.statSync(abs); } catch { /* does not exist yet */ }
+    if (!stat) { entry.files.push({ path: abs, existed: false }); this.writeIndex(); return; }
+    if (!stat.isFile()) return;
+    if (stat.size > MAX_SNAPSHOT_BYTES) { entry.files.push({ path: abs, existed: true, skipped: true }); return; }
+    const snap = `${entry.id}-${crypto.createHash('sha1').update(abs).digest('hex').slice(0, 12)}`;
+    try {
+      fs.mkdirSync(this.dir, { recursive: true });
+      fs.copyFileSync(abs, path.join(this.dir, snap));
+      entry.files.push({ path: abs, existed: true, snap });
+      this.writeIndex();
+    } catch {
+      entry.files.push({ path: abs, existed: true, skipped: true });
+    }
+  }
+
+  // The state to hand to the next process of a restarted session (see adopt).
+  snapshot() { return { dir: this.dir, entries: this.entries, counter: this.counter }; }
+
+  // Take over what the process before a restart had: its snapshots stay where they are on disk.
+  adopt({ dir, entries, counter } = {}) {
+    if (!dir || !Array.isArray(entries)) return false;
+    this.dir = dir;
+    this.entries = entries;
+    this.counter = Math.max(Number(counter) || 0, ...entries.map((e) => e.id || 0));
+    this.current = entries[entries.length - 1] || null;
+    return true;
+  }
+
+  // Checkpoints that are part of the current conversation, newest first.
+  list() { return this.entries.filter((e) => !e.orphaned).reverse(); }
+  get(id) { return this.entries.find((e) => e.id === id); }
+
+  // Files that rewinding to `id` would put back: every file touched by that checkpoint or a later one.
+  filesSince(id) {
+    const seen = new Map();
+    for (const e of this.entries) {
+      if (e.id < id) continue;
+      for (const f of e.files) if (!seen.has(keyOf(f.path))) seen.set(keyOf(f.path), f.path);
+    }
+    return [...seen.values()];
+  }
+
+  // Put every file touched since `id` back to how it was before that checkpoint.
+  // The oldest snapshot of each file decides its final state. Returns {restored, removed, skipped}.
+  restoreCode(id) {
+    const idx = this.entries.findIndex((e) => e.id === id);
+    if (idx < 0) throw new Error(`No checkpoint ${id}`);
+    const oldest = new Map();
+    for (let i = idx; i < this.entries.length; i++) {
+      for (const f of this.entries[i].files) if (!oldest.has(keyOf(f.path))) oldest.set(keyOf(f.path), f);
+    }
+    const result = { restored: [], removed: [], skipped: [] };
+    for (const f of oldest.values()) {
+      try {
+        if (f.skipped) { result.skipped.push(f.path); continue; }
+        if (f.existed) {
+          fs.mkdirSync(path.dirname(f.path), { recursive: true });
+          fs.copyFileSync(path.join(this.dir, f.snap), f.path);
+          result.restored.push(f.path);
+        } else {
+          fs.rmSync(f.path, { force: true });
+          result.removed.push(f.path);
+        }
+      } catch (e) {
+        result.skipped.push(`${f.path} (${e.message})`);
+      }
+    }
+    // Those changes no longer exist on disk, so later checkpoints have nothing left to undo.
+    for (let i = idx; i < this.entries.length; i++) this.entries[i].files = [];
+    this.writeIndex();
+    return result;
+  }
+
+  // Forget checkpoint `id` and everything after it (their turns were removed from the conversation).
+  discardFrom(id) {
+    this.entries = this.entries.filter((e) => e.id < id);
+    this.current = this.entries[this.entries.length - 1] || null;
+    this.writeIndex();
+  }
+
+  // The conversation was rewound to before `id` but the files were left alone: keep the
+  // snapshots (the edits are still on disk) but stop listing those turns.
+  orphanFrom(id) {
+    for (const e of this.entries) if (e.id >= id) e.orphaned = true;
+    this.writeIndex();
+  }
+
+  // The conversation was compacted or replaced: it can no longer be rewound to older points,
+  // but file snapshots remain valid.
+  markConversationStale() {
+    for (const e of this.entries) e.conversationValid = false;
+  }
+
+  reset() {
+    this.entries = [];
+    this.current = null;
+    this.writeIndex();
+  }
+
+  writeIndex() {
+    try {
+      fs.mkdirSync(this.dir, { recursive: true });
+      fs.writeFileSync(path.join(this.dir, 'index.json'), JSON.stringify(this.entries, null, 1));
+    } catch { /* best effort: the index only helps manual recovery */ }
+  }
+}
+
+// Apply a rewind to a running agent. mode: 'both' | 'code' | 'conversation'.
+// Returns {restore, prompt, conversation}: what was restored, the prompt text (so the UI can put it
+// back in the input box) and whether the conversation was cut.
+export function rewind(agent, store, id, mode = 'both') {
+  const entry = store.get(id);
+  if (!entry) throw new Error(`No checkpoint ${id}`);
+  if (mode !== 'code' && !entry.conversationValid) {
+    throw new Error('The conversation was compacted after this point, so it can no longer be rewound to it. You can still restore the code.');
+  }
+  const out = { restore: null, prompt: entry.label, conversation: false };
+  if (mode !== 'conversation') {
+    out.restore = store.restoreCode(id);
+    // Files changed behind the agent's back: make it read them again before editing.
+    agent.fileState.clear();
+  }
+  if (mode !== 'code') {
+    agent.replaceMessages(agent.messages.slice(0, entry.messageIndex));
+    agent.todos = [];
+    agent.lastContextTokens = estimateTokens(agent.messages);
+    agent.tokensSinceUsage = 0;
+    if (mode === 'both') store.discardFrom(id); else store.orphanFrom(id);
+    out.conversation = true;
+  } else {
+    agent.pushMessage({
+      role: 'user',
+      content: [{ type: 'text', text: `<system-reminder>The user rewound the code: ${out.restore.restored.length} file(s) were restored to their state before the prompt "${entry.label}" and ${out.restore.removed.length} file(s) created since then were deleted. Files may differ from what you last read; read them again before editing.</system-reminder>` }],
+    });
+  }
+  return out;
+}

package/src/claude-code.js

@@ -0,0 +1,60 @@
+// Read an existing Claude Code subscription login. There is no login flow here and no subprocess: signing
+// in is the official application's. Renewing the access token with the refresh token stored beside it is
+// done by oauth.js, which is the only code that writes the credentials file; this reads it.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const CLAUDE_CODE_API_URL = 'https://api.anthropic.com';
+export const CLAUDE_CODE_SYSTEM = "You are Claude Code, Anthropic's official CLI for Claude.";
+export const CLAUDE_CODE_BETAS = 'claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14';
+const sessionIds = new WeakMap();
+let installedVersion;
+
+function readJson(file, label) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); }
+  catch { throw new Error(`Could not read existing Claude Code ${label}: ${file}. Select the existing login with CLAUDE_PRO_CLAUDE_CONFIG_FILE / CLAUDE_PRO_CLAUDE_CREDENTIALS_FILE.`); }
+  // JSON.parse errors can contain an excerpt of the token. Never echo them.
+  try { return JSON.parse(text.replace(/^\uFEFF/, '')); }
+  catch { throw new Error(`Invalid JSON in Claude Code ${label}: ${file}.`); }
+}
+
+function clientVersion(config, metadata) {
+  if (config.env.CLAUDE_PRO_CLAUDE_CODE_VERSION) return config.env.CLAUDE_PRO_CLAUDE_CODE_VERSION;
+  if (installedVersion) return installedVersion;
+  for (const dir of (process.env.PATH || process.env.Path || '').split(path.delimiter).filter(Boolean)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(dir.replace(/^"|"$/g, ''), 'node_modules', '@anthropic-ai', 'claude-code', 'package.json'), 'utf8'));
+      if (/^\d+\.\d+\.\d+$/.test(pkg.version)) return (installedVersion = pkg.version);
+    } catch { /* native installs do not have an npm package */ }
+  }
+  return /^\d+\.\d+\.\d+$/.test(metadata.lastOnboardingVersion || '') ? metadata.lastOnboardingVersion : '2.1.289';
+}
+
+export function readClaudeCodeLogin(config) {
+  const metadata = readJson(config.claudeCodeConfigFile, 'account configuration');
+  const credentials = readJson(config.claudeCodeCredentialsFile, 'credentials');
+  const oauth = credentials?.claudeAiOauth;
+  if (!oauth || typeof oauth.accessToken !== 'string' || !oauth.accessToken.trim()) {
+    throw new Error(`No existing Claude Code subscription access token in ${config.claudeCodeCredentialsFile}. The .claude.json file contains account metadata; the token is in .claude/.credentials.json.`);
+  }
+  if (oauth.expiresAt && Number(oauth.expiresAt) <= Date.now()) {
+    throw new Error('The existing Claude Code access token has expired and cannot be renewed from here (the credentials file has no refresh token, or CLAUDE_PRO_DISABLE_TOKEN_REFRESH is set). Run `claude` and use /login to sign in again; this project will read the updated file automatically.');
+  }
+  if (!sessionIds.has(config)) sessionIds.set(config, crypto.randomUUID());
+  return {
+    accessToken: oauth.accessToken,
+    expiresAt: Number(oauth.expiresAt) || null, // ms since epoch; the token lives 8 hours
+    userId: JSON.stringify({ device_id: metadata.userID || '', account_uuid: metadata.oauthAccount?.accountUuid || '', session_id: sessionIds.get(config) }),
+    version: clientVersion(config, metadata),
+  };
+}
+
+export function claudeCodeHeaders(login) {
+  return {
+    'anthropic-beta': CLAUDE_CODE_BETAS,
+    'user-agent': `claude-cli/${login.version} (external, cli)`,
+    'x-app': 'cli',
+  };
+}