@jskit-ai/assistant-core 0.2.1 → 0.2.3

package/src/server/conversation/claudeProcess.js

@@ -9,7 +9,8 @@ import { createLocalConversationExecution } from "./localExecution.js";
 import { CLAUDE_APPLICATION_TOOL_SERVER } from "./claudeTools.js";
 import { nativeCommandHook, validateCommandWrapper } from "./commandWrapper.js";
 
-const statusReads = new WeakMap();
+const statusReads = new Map();
+const STATUS_RETRY_MS = 30_000;
 const CLAUDE_EXIT_WAIT_MS = 5_000;
 
 /** Person-facing cause for a Claude process that ended without being stopped. */
@@ -26,6 +27,17 @@ export function claudeUnexpectedExitMessage(processExit = {}) {
   return `Claude stopped unexpectedly. ${resume}`;
 }
 
+// A file's metadata, following links, or null when it is absent.
+async function fileRevision(file) {
+  try {
+    const value = await stat(file, { bigint: true });
+    return [value.dev, value.ino, value.size, value.mtimeNs].join(":");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
 export async function readClaudeCodeAuthStatus({
   env = process.env, credentialHome = { home: env.HOME || homedir() }, command = "claude", commandRunner, signal
 } = {}) {
@@ -33,29 +45,27 @@ export async function readClaudeCodeAuthStatus({
   if (typeof commandRunner !== "function") throw new TypeError("Claude account status requires its host capture runner.");
   const configRoot = env.CLAUDE_CONFIG_DIR || path.join(credentialHome.home, ".claude");
   // Inspect file metadata only. Claude still owns reading and validating credentials.
-  const revisions = await Promise.all([
-    path.join(configRoot, ".credentials.json"), path.join(configRoot, ".claude.json"),
-    path.join(credentialHome.home, ".claude.json")
-  ].map(async (file) => {
-    try {
-      const value = await stat(file, { bigint: true });
-      return [value.dev, value.ino, value.size, value.mtimeNs, value.ctimeNs].map(String);
-    } catch (error) {
-      if (error.code === "ENOENT") return null;
-      throw error;
-    }
-  }));
-  let reads = statusReads.get(commandRunner);
-  if (!reads) statusReads.set(commandRunner, reads = new Map());
-  const key = JSON.stringify([command, env, credentialHome]);
-  const revision = JSON.stringify(revisions);
-  const previous = reads.get(key);
+  // Sign-in writes .credentials.json and sign-out removes it. Claude Code also
+  // rewrites .claude.json during turns and after every status read, so that
+  // file is not watched.
+  const revision = await fileRevision(path.join(configRoot, ".credentials.json"));
+  // One entry per account, whichever command path or host runner reads it: only
+  // the account's location and its identity variables count.
+  const key = jsonHash([configRoot, credentialHome.home, Object.entries(env).filter(([name, value]) =>
+    value && (name === "CLAUDE_CODE_OAUTH_TOKEN" || name.startsWith("ANTHROPIC_"))).sort()]);
+  const previous = statusReads.get(key);
   if (previous?.revision === revision && (previous.pending || previous.expiresAt > Date.now())) return previous.value;
   const entry = { revision, pending: true, expiresAt: 0 };
-  reads.set(key, entry);
-  entry.value = readNativeClaudeCodeAuthStatus({ env, credentialHome, command, commandRunner, signal }).then((status) => {
+  statusReads.set(key, entry);
+  entry.value = readNativeClaudeCodeAuthStatus({ env, credentialHome, command, commandRunner, signal }).then(({ status, unfinished }) => {
     // Keychain changes cannot be observed with file metadata on macOS.
-    if (!status.error && process.platform !== "darwin") entry.expiresAt = Date.now() + 30_000;
+    if (process.platform !== "darwin") {
+      // Claude's answer holds until its credentials change. A read the host timed
+      // out or refused for now backs off, so a busy host is not probed again by
+      // every caller; a read that ran and failed is asked again next time.
+      if (!status.error) entry.expiresAt = Infinity;
+      else if (unfinished) entry.expiresAt = Date.now() + STATUS_RETRY_MS;
+    }
     return Object.freeze(status);
   }).finally(() => { entry.pending = false; });
   return entry.value;
@@ -67,6 +77,12 @@ async function readNativeClaudeCodeAuthStatus({ env, credentialHome, command, co
     credentialHome, cwd: credentialHome.home, mode: "capture",
     timeout: 30_000, maxBuffer: 64 * 1024, ...(signal ? { signal } : {})
   });
+  const status = claudeCodeAuthStatus(result);
+  return { status, unfinished: Boolean(status.error) && result.ok !== true &&
+    (result.timedOut === true || result.retryable === true) };
+}
+
+function claudeCodeAuthStatus(result) {
   const failure = result.error ? { loggedIn: false, error: result.error }
     : { loggedIn: false, error: "Claude Code is not connected.", messageCode: "assistant.claude.notConnected", messageParams: {} };
   if (!result.ok && (result.exitCode !== 1 || result.timedOut || result.signal)) return failure;
@@ -226,6 +242,37 @@ export function claudePlanUsage(value) {
     windows, checkedAt: Date.now() };
 }
 
+// Plan usage is read through a conversation's live process at most this often,
+// and otherwise through a one-shot Claude started only for the read.
+const PLAN_USAGE_LIVE_READ_MS = 60_000;
+const PLAN_USAGE_IDLE_READ_MS = 300_000;
+// A verified reading stays current until the next idle read, one client poll and
+// its read deadline could have replaced it.
+const PLAN_USAGE_CURRENT_MS = 420_000;
+// One plan-usage reading per Claude account in this server process, with its read
+// times and the read in flight. Every account-query owner, page and session asking
+// for the account shares it, so however many ask, the account's one-shot Claude
+// starts at most once per idle interval.
+const planUsageReads = new Map();
+
+/**
+ * Claude Code answers `get_usage` from the usage endpoint, or from its saved copy
+ * of that answer while under a minute old, including the endpoint's `limits` list.
+ * While that read fails or is held after a 429, it answers from the rate-limit
+ * headers of the answering process's last API response, which can be hours old,
+ * and omits `limits`. The answer has no age, so only one with `limits` is current.
+ */
+function claudePlanUsageVerified(value) {
+  return !value.rate_limits_available || Array.isArray(value.rate_limits?.limits);
+}
+
+function presentPlanUsage(reading) {
+  if (!reading) return { status: "unavailable", windows: [] };
+  if (reading.status !== "available") return reading;
+  const currentForMs = PLAN_USAGE_CURRENT_MS - (Date.now() - reading.checkedAt);
+  return currentForMs > 0 ? { ...reading, currentForMs } : { ...reading, status: "stale" };
+}
+
 export function claudeCatalogueModels(initialization) {
   return (initialization.models || []).map((model) => ({
     id: model.value, label: model.displayName || model.value, description: model.description || "",
@@ -235,15 +282,21 @@ export function claudeCatalogueModels(initialization) {
   }));
 }
 
-/** Native account queries share process reuse, caches and retryable cleanup. */
-export function createClaudeAccountQueries({ createProcess, accountIdentity, processes = () => [], isClosing = () => false }) {
+/**
+ * Native account queries share process reuse, caches and retryable cleanup. Plan
+ * usage is shared by `accountIdentity` with every other owner in the process, so
+ * that identity names exactly one Claude account. `configRoot` is the account's
+ * Claude configuration directory, whose credentials the model list follows.
+ */
+export function createClaudeAccountQueries({ createProcess, accountIdentity, configRoot, processes = () => [], isClosing = () => false }) {
   const error = message => Object.assign(new Error(message), { code: "claude_account_query_failed" });
   const accountProcessStops = new Set();
   const accountReads = new Set();
   let catalog;
   const catalogStarts = new Map();
-  let planUsage;
-  const planUsagePending = new Map();
+  // Accounts whose shared plan-usage reading this owner used, and the reads it started.
+  const usageAccounts = new Set();
+  const usageReads = new Set();
   let revision = 0;
 
   function assertCurrent(expectedRevision) {
@@ -257,12 +310,16 @@ export function createClaudeAccountQueries({ createProcess, accountIdentity, pro
     accountProcessStops.delete(native);
   }
 
-  async function readAccountProcess(identity, expectedRevision, purpose, read) {
+  function ownedProcess(identity) {
+    return [...processes()].find((entry) =>
+      entry.process && !entry.stopping && entry.accountIdentity === identity);
+  }
+
+  async function readAccountProcess(identity, expectedRevision, purpose, read, { borrow = false } = {}) {
     assertCurrent(expectedRevision);
     for (const native of accountProcessStops) await stopAccountProcess(native);
     assertCurrent(expectedRevision);
-    const owned = [...processes()].find((entry) =>
-      entry.process && !entry.stopping && entry.accountIdentity === identity);
+    const owned = borrow ? ownedProcess(identity) : null;
     const controller = new AbortController();
     accountReads.add(controller);
     const cancelled = Promise.withResolvers();
@@ -283,49 +340,110 @@ export function createClaudeAccountQueries({ createProcess, accountIdentity, pro
     }
   }
 
+  // The model list belongs to the account and the Claude Code version that gave
+  // it: the account's credentials file changes with sign-in, sign-out and each
+  // token refresh (which carries a plan change), and the executable with each
+  // Claude Code update. An executable given as a bare name has no metadata.
+  async function catalogueRevision(command) {
+    return JSON.stringify(await Promise.all([fileRevision(path.join(configRoot, ".credentials.json")),
+      fileRevision(command)]));
+  }
+
   return Object.freeze({
     async readCatalogue(context) {
       const expectedRevision = revision;
       assertCurrent(expectedRevision);
       const identity = await accountIdentity(context);
       assertCurrent(expectedRevision);
-      if (!catalog || catalog.identity !== identity || Date.now() - catalog.at > 600_000) {
-        if (!catalogStarts.has(identity)) catalogStarts.set(identity, (async () => {
-          const value = await readAccountProcess(identity, expectedRevision, "catalogue", (native) => native.initialization);
-          if (identity !== await accountIdentity(context)) throw error("The signed-in Claude account changed. Refresh the model list.");
-          assertCurrent(expectedRevision);
-          catalog = { at: Date.now(), identity, value };
-          return value;
-        })().finally(() => { catalogStarts.delete(identity); }));
-        return catalogStarts.get(identity);
+      // An answer is kept until its account, credentials or executable change, so
+      // reading it again starts no Claude.
+      const kept = catalog?.identity === identity ? catalog : null;
+      if (kept && kept.revision === await catalogueRevision(kept.command)) {
+        assertCurrent(expectedRevision);
+        return kept.value;
       }
-      return catalog.value;
+      if (!catalogStarts.has(identity)) catalogStarts.set(identity, (async () => {
+        // A conversation's process answers with what it knew when it started, so
+        // the list comes from a Claude started for this read.
+        const { value, command } = await readAccountProcess(identity, expectedRevision, "catalogue",
+          async (native) => ({ value: await native.initialization, command: native.command }));
+        const answered = await catalogueRevision(command);
+        if (identity !== await accountIdentity(context)) throw error("The signed-in Claude account changed. Refresh the model list.");
+        assertCurrent(expectedRevision);
+        catalog = { identity, command, revision: answered, value };
+        return value;
+      })().finally(() => { catalogStarts.delete(identity); }));
+      return catalogStarts.get(identity);
     },
     async readPlanUsage(context) {
       const expectedRevision = revision;
       assertCurrent(expectedRevision);
       const identity = await accountIdentity(context);
       assertCurrent(expectedRevision);
-      if (planUsage?.identity === identity && Date.now() - planUsage.checkedAt < 60_000) return planUsage;
-      if (planUsagePending.has(identity)) return planUsagePending.get(identity);
+      // One reading per account, whichever owner asks; a started process is stopped after its read.
+      let usage = planUsageReads.get(identity);
+      if (!usage) {
+        usage = { liveReadAt: -Infinity, temporaryReadAt: -Infinity, reading: null, pending: null };
+        planUsageReads.set(identity, usage);
+      }
+      usageAccounts.add(identity);
+      if (usage.pending) return usage.pending;
+      const live = Boolean(ownedProcess(identity));
+      const liveDue = live && Date.now() - usage.liveReadAt >= PLAN_USAGE_LIVE_READ_MS;
+      // A one-shot Claude starts only when neither a verified reading nor a one-shot
+      // read is from the last idle interval.
+      const temporaryDue = () => Date.now() - Math.max(usage.temporaryReadAt, usage.reading?.checkedAt ?? -Infinity) >=
+        PLAN_USAGE_IDLE_READ_MS;
+      if (!liveDue && (live || !temporaryDue())) return presentPlanUsage(usage.reading);
       const pending = (async () => {
-        const value = await readAccountProcess(identity, expectedRevision, "usage", (native) => native.client.request(
-          { subtype: "get_usage", skip_behaviors: true }));
-        if (identity !== await accountIdentity(context)) return { status: "unavailable", windows: [] };
-        assertCurrent(expectedRevision);
-        planUsage = { ...claudePlanUsage(value), identity };
-        return planUsage;
-      })().finally(() => { planUsagePending.delete(identity); });
-      planUsagePending.set(identity, pending);
+        // A live process's held endpoint read is its own, so a fresh one-shot Claude
+        // may still reach the endpoint when the live answer cannot prove it is current.
+        for (const borrow of liveDue ? [true, false] : [false]) {
+          if (!borrow && !temporaryDue()) break;
+          usage[borrow ? "liveReadAt" : "temporaryReadAt"] = Date.now();
+          let value;
+          try {
+            value = await readAccountProcess(identity, expectedRevision, "usage", (native) => native.client.request(
+              { subtype: "get_usage", skip_behaviors: true }), { borrow });
+          } catch (cause) {
+            if (borrow || !liveDue) throw cause;
+            assertCurrent(expectedRevision);
+            break;
+          }
+          if (identity !== await accountIdentity(context)) return { status: "unavailable", windows: [] };
+          assertCurrent(expectedRevision);
+          // An answer that cannot prove it is current keeps the last verified reading.
+          if (claudePlanUsageVerified(value)) {
+            usage.reading = { ...claudePlanUsage(value), identity };
+            break;
+          }
+        }
+        return presentPlanUsage(usage.reading);
+      })().finally(() => {
+        usageReads.delete(pending);
+        if (usage.pending === pending) usage.pending = null;
+      });
+      // Requests that arrive while the account is read share that read.
+      usage.pending = pending;
+      usageReads.add(pending);
       return pending;
     },
-    invalidateUsage() { planUsage = null; },
+    // A native usage change lets the next request read again without hiding the last reading.
+    invalidateUsage() {
+      for (const identity of usageAccounts) {
+        const usage = planUsageReads.get(identity);
+        if (usage) usage.liveReadAt = -Infinity;
+      }
+    },
     async invalidate() {
       revision++;
-      for (const controller of accountReads) controller.abort(error("Claude account query was cancelled for reconnection."));
-      await Promise.allSettled([...catalogStarts.values(), ...planUsagePending.values()]);
+      // Dropped at once: a read started before this cannot store its answer.
       catalog = null;
-      planUsage = null;
+      for (const controller of accountReads) controller.abort(error("Claude account query was cancelled for reconnection."));
+      await Promise.allSettled([...catalogStarts.values(), ...usageReads]);
+      // The account changed: the next request for an account this owner used reads again.
+      for (const identity of usageAccounts) planUsageReads.delete(identity);
+      usageAccounts.clear();
       for (const native of accountProcessStops) await stopAccountProcess(native);
     }
   });
@@ -407,7 +525,7 @@ export async function createClaudeCodeProcess({
     }, error => {
       if (!stopped && !stopping) stream.destroy(error);
     });
-    return { client, initialization, executionId: native.id, stop };
+    return { client, initialization, executionId: native.id, command, stop };
   } catch (error) {
     // A rejected start may already own an execution and its cleanup proof.
     // Only a returned native handle transfers that cleanup to this owner.