claude-usage-limits 1.9.2 → 1.11.2

package/skills/usage-limits/scripts/pulse.js

@@ -24,6 +24,8 @@ const path = require('path');
 const usage = require('./usage.js');
 const brief = require('./brief.js');
 const host = require('./host.js');
+const activity = require('./activity.js');
+const live = require('./live.js');
 
 const SECOND = 1000;
 const DEFAULT_INTERVAL_SECONDS = 120;
@@ -116,6 +118,10 @@ async function run(now, hookInput) {
   usage.setHost(host.detect(process.argv.slice(2), process.env));
 
   const sessionId = hookInput && hookInput.session_id ? hookInput.session_id : null;
+  // A tool call just finished, so the turn is still running. A few bytes, so
+  // the panel beside the chat keeps animating through a long turn.
+  activity.mark('working', sessionId, null, now);
+
   const all = readState();
   const every = intervalMs();
   // The cheap path, and the one taken almost every time.
@@ -125,6 +131,24 @@ async function run(now, hookInput) {
   // second tool call start another one.
   writeState(trim(all, sessionId, now));
 
+  // A reading as old as the interval is replaced with the one Claude Code
+  // would take for /usage, so a turn that runs for an hour is measured
+  // against the account rather than against a guess from its own transcript.
+  if (!usage.isCodex()) {
+    try {
+      const cached = usage.collect(now);
+      await live.refreshIfStale({
+        now,
+        maxAgeMs: every,
+        cacheFetchedAtMs: cached.snapshotFetchedAt,
+        accountUuid: usage.accountUuid(),
+        timeoutMs: 4000,
+      });
+    } catch (err) {
+      // The reading on disk is still there.
+    }
+  }
+
   const data = await usage.report(now, { sessionId });
   const binding = data.binding;
   if (!binding) return '';

package/skills/usage-limits/scripts/recommend.js

@@ -32,15 +32,56 @@ const TIGHT_TURNS = 25;
 
 const HOUR = 60 * 60 * 1000;
 
-// Where the mechanical bulk should go when it is delegated. One tier down
-// from whatever is doing the judgement; haiku is already the floor.
-function delegateModel(model) {
+// Where the mechanical bulk should go when it is delegated.
+//
+// The ladder below is an assumption: one tier down from whatever is doing the
+// judgement, haiku being the floor. It is a reasonable assumption and it is
+// still the fallback, but this account has measured the answer - what a call to
+// each model has really cost here - and a measurement beats a ladder. On one
+// machine the ladder said sonnet while the record said sonnet calls had cost
+// $0.012 against Opus turns at $0.211, which is the same advice with a number
+// behind it, and would have said haiku had haiku been the cheaper one.
+function ladderModel(model) {
   const name = String(model || '').toLowerCase();
   if (name.indexOf('haiku') !== -1) return 'haiku';
   if (name.indexOf('sonnet') !== -1) return 'haiku';
   return 'sonnet';
 }
 
+// Whose family a model setting names, without requiring usage.js back: that
+// would make these two modules a cycle.
+function familyName(model) {
+  const name = String(model || '').toLowerCase();
+  for (const family of ['fable', 'mythos', 'opus', 'sonnet', 'haiku']) {
+    if (name.indexOf(family) !== -1) return family === 'mythos' ? 'fable' : family;
+  }
+  return null;
+}
+
+function delegateModel(model, headroom) {
+  const mine = familyName(model);
+  const measured = (headroom || []).filter(
+    (row) =>
+      row &&
+      row.family &&
+      row.family !== mine &&
+      Number.isFinite(row.usdPerTurn) &&
+      row.usdPerTurn > 0 &&
+      // A model whose own weekly is spent is not somewhere to send work.
+      !(row.ownWindow && row.turnsLeft === 0)
+  );
+  if (!measured.length) return ladderModel(model);
+
+  const cheapest = measured.reduce((best, row) => (row.usdPerTurn < best.usdPerTurn ? row : best));
+  // Never up the ladder. If everything measured is dearer than what is already
+  // running, delegating buys nothing and the assumption is the better answer.
+  const here = (headroom || []).find((row) => row && row.family === mine);
+  if (here && Number.isFinite(here.usdPerTurn) && cheapest.usdPerTurn >= here.usdPerTurn) {
+    return ladderModel(model);
+  }
+  return cheapest.family;
+}
+
 // The effort actually in force. settings.json says 'default' when nothing is
 // set, and the measured dominant effort of recent turns is better evidence
 // than a guess; xhigh is what Claude Code defaults to when neither knows.
@@ -163,10 +204,17 @@ function decide(inputs) {
   // then it lands in settings.json for the next session: switching the running
   // session's model mid-task invalidates the prompt cache, so the change
   // belongs at a session boundary.
-  base.model.delegate = delegateModel(modelNow);
+  base.model.delegate = delegateModel(modelNow, inputs.headroom);
+  const mine = (inputs.headroom || []).find((row) => row && row.family === familyName(modelNow));
+  const there = (inputs.headroom || []).find((row) => row && row.family === base.model.delegate);
+  // With both prices measured, say the saving rather than asserting one.
+  const saving =
+    mine && there && Number.isFinite(mine.usdPerTurn) && Number.isFinite(there.usdPerTurn) && there.usdPerTurn > 0
+      ? ', measured here at ' + Math.round(mine.usdPerTurn / there.usdPerTurn) + 'x cheaper'
+      : '';
   base.model.why =
     'keep ' + (modelNow === 'default' ? 'the current model' : modelNow) +
-    ' for the judgement; the saving is in where the mechanical bulk runs';
+    ' for the judgement; the saving is in where the mechanical bulk runs' + saving;
   if (base.posture === 'critical' && base.model.delegate !== 'haiku') {
     base.model.nextSession = 'sonnet';
   }
@@ -213,6 +261,7 @@ function decide(inputs) {
 function fromReport(data, turns) {
   return {
     binding: (data && data.binding) || null,
+    headroom: (data && data.modelHeadroom) || null,
     rates: (data && data.rates) || null,
     settings: (data && data.settings) || {},
     recentEffort: data && data.recent ? data.recent.effort : null,
@@ -285,6 +334,8 @@ function renderRecommend(data, turns) {
 module.exports = {
   decide,
   fromReport,
+  familyName,
+  ladderModel,
   renderRecommend,
   delegateModel,
   currentEffort,

package/skills/usage-limits/scripts/sessionend.js

@@ -11,12 +11,16 @@
 const usage = require('./usage.js');
 const host = require('./host.js');
 const tally = require('./tally.js');
+const activity = require('./activity.js');
 
 async function run(now, hookInput) {
+  const sessionId = hookInput && hookInput.session_id ? hookInput.session_id : null;
+  // The session is over, so as far as the panel is concerned it is idle.
+  activity.mark('idle', sessionId, null, now);
+
   if (String(process.env.USAGE_LIMITS_TALLY || '').toLowerCase() === 'off') return '';
   usage.setHost(host.detect(process.argv.slice(2), process.env));
 
-  const sessionId = hookInput && hookInput.session_id ? hookInput.session_id : null;
   const transcript = hookInput && hookInput.transcript_path ? hookInput.transcript_path : null;
   if (!sessionId || !transcript) return '';
 

package/skills/usage-limits/scripts/statusline.js

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+'use strict';
+
+// Puts the bars under the Claude Code prompt, and takes them out again.
+//
+//   node scripts/statusline.js status
+//   node scripts/statusline.js on [--refresh N] [--no-chain] [--dry-run]
+//   node scripts/statusline.js off
+//
+// `on` points Claude Code's statusLine setting at a small launcher written into
+// the config directory. The launcher finds wherever this plugin is currently
+// installed and runs feed.js from there, so a plugin update that moves the
+// install directory does not leave the status line pointing at a folder that
+// no longer exists.
+//
+// A status line that was already there is kept: it is recorded, and feed.js
+// runs it first and prints its output above ours, unless --no-chain. `off`
+// puts back exactly what was there, including nothing.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function configDir() {
+  return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+}
+
+function settingsFile() {
+  return path.join(configDir(), 'settings.json');
+}
+
+function stateFile() {
+  return path.join(configDir(), 'usage-limits-statusline.json');
+}
+
+function launcherFile() {
+  return path.join(configDir(), 'usage-limits-statusline.js');
+}
+
+function feedFile() {
+  return path.join(__dirname, 'feed.js');
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+function readState() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(stateFile(), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch (err) {
+    return null;
+  }
+}
+
+// Replace through a temporary file so an interrupted run cannot leave
+// settings.json half written.
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = file + '.usage-limits-tmp';
+  fs.writeFileSync(temp, JSON.stringify(value, null, 2) + '\n', 'utf8');
+  fs.renameSync(temp, file);
+}
+
+// The launcher. It is deliberately dumb: find feed.js, hand over, and if that
+// is not possible print nothing and exit 0, because a status line that shows
+// an error every 300ms is worse than one that is blank.
+function launcherSource(recordedFeed) {
+  return [
+    '#!/usr/bin/env node',
+    "'use strict';",
+    '// Written by claude-usage-limits (statusline on). Finds the current install and',
+    '// runs its status line. Remove with: claude-usage-limits statusline off',
+    "const fs = require('fs');",
+    "const os = require('os');",
+    "const path = require('path');",
+    "const configDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');",
+    'const candidates = [];',
+    'try {',
+    "  const installed = JSON.parse(fs.readFileSync(path.join(configDir, 'plugins', 'installed_plugins.json'), 'utf8'));",
+    '  for (const key of Object.keys((installed && installed.plugins) || {})) {',
+    "    if (key.indexOf('usage-limits@') !== 0) continue;",
+    '    for (const entry of installed.plugins[key] || []) {',
+    "      if (entry && entry.installPath) candidates.push(path.join(entry.installPath, 'skills', 'usage-limits', 'scripts', 'feed.js'));",
+    '    }',
+    '  }',
+    '} catch (err) {}',
+    "candidates.push(path.join(configDir, 'skills', 'usage-limits', 'scripts', 'feed.js'));",
+    'candidates.push(' + JSON.stringify(recordedFeed) + ');',
+    'let feed = null;',
+    'for (const file of candidates) {',
+    '  try {',
+    '    if (fs.statSync(file).isFile()) {',
+    '      feed = file;',
+    '      break;',
+    '    }',
+    '  } catch (err) {}',
+    '}',
+    'if (!feed) process.exit(0);',
+    'try {',
+    '  Promise.resolve(require(feed).main(process.argv.slice(2))).then(',
+    '    (code) => process.exit(code || 0),',
+    '    () => process.exit(0)',
+    '  );',
+    '} catch (err) {',
+    '  process.exit(0);',
+    '}',
+    '',
+  ].join('\n');
+}
+
+function parseArgs(argv) {
+  const args = { command: null, refresh: null, chain: true, dryRun: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--dry-run') args.dryRun = true;
+    else if (arg === '--no-chain') args.chain = false;
+    else if (arg === '--refresh') args.refresh = Number(argv[++i]);
+    else if (arg.indexOf('--refresh=') === 0) args.refresh = Number(arg.slice('--refresh='.length));
+    else if (!args.command) args.command = arg;
+  }
+  if (!args.command) args.command = 'status';
+  return args;
+}
+
+function isOurs(statusLine, launcher) {
+  return Boolean(
+    statusLine &&
+      statusLine.type === 'command' &&
+      typeof statusLine.command === 'string' &&
+      statusLine.command.indexOf(path.basename(launcher)) !== -1
+  );
+}
+
+// Work out the settings to write without touching disk.
+function planOn(settings, state, options) {
+  const current = settings || {};
+  const opts = options || {};
+  const launcher = opts.launcher || launcherFile();
+  const existing = current.statusLine === undefined ? null : current.statusLine;
+  // A second "on" must not record our own launcher as the thing to restore.
+  const previous =
+    state && Object.prototype.hasOwnProperty.call(state, 'previous')
+      ? state.previous
+      : isOurs(existing, launcher)
+        ? null
+        : existing;
+  const command = 'node ' + JSON.stringify(launcher);
+  const statusLine = { type: 'command', command };
+  if (Number.isFinite(opts.refresh) && opts.refresh >= 1) statusLine.refreshInterval = Math.floor(opts.refresh);
+  const chain =
+    opts.chain !== false &&
+    Boolean(previous && previous.type === 'command' && typeof previous.command === 'string' && previous.command);
+  const next = Object.assign({}, current, { statusLine });
+  const changes = [];
+  if (JSON.stringify(existing) !== JSON.stringify(statusLine)) {
+    changes.push('statusLine: ' + (existing ? JSON.stringify(existing) : '(unset)') + ' -> ' + JSON.stringify(statusLine));
+  }
+  return {
+    settings: next,
+    state: {
+      installedAt: new Date().toISOString(),
+      previous,
+      chain,
+      launcher,
+      feed: opts.feed || feedFile(),
+    },
+    changes,
+  };
+}
+
+function planOff(settings, state) {
+  const current = settings || {};
+  const next = Object.assign({}, current);
+  const previous = state && Object.prototype.hasOwnProperty.call(state, 'previous') ? state.previous : null;
+  const changes = [];
+  if (previous === null || previous === undefined) {
+    if (next.statusLine !== undefined) {
+      changes.push('statusLine: removed');
+      delete next.statusLine;
+    }
+  } else {
+    changes.push('statusLine: restored');
+    next.statusLine = previous;
+  }
+  return { settings: next, changes };
+}
+
+function backupOnce(file) {
+  const backup = file + '.usage-limits-backup';
+  if (fs.existsSync(file) && !fs.existsSync(backup)) fs.copyFileSync(file, backup);
+}
+
+function describeStatus(settings, state) {
+  const current = (settings && settings.statusLine) || null;
+  const launcher = launcherFile();
+  const ours = isOurs(current, launcher);
+  const lines = [];
+  if (ours) {
+    lines.push('status line: on');
+    lines.push('  command  ' + current.command);
+    if (current.refreshInterval) lines.push('  refresh  every ' + current.refreshInterval + 's');
+    if (state && state.chain && state.previous && state.previous.command) {
+      lines.push('  chained  ' + state.previous.command);
+    } else if (state && state.previous) {
+      lines.push('  replaced ' + JSON.stringify(state.previous) + ' (restored by "off")');
+    }
+  } else if (current) {
+    lines.push('status line: another command is set');
+    lines.push('  command  ' + (current.command || JSON.stringify(current)));
+    lines.push('  "on" keeps it and prints its output above ours; --no-chain replaces it');
+  } else {
+    lines.push('status line: off');
+    lines.push('  "on" installs it; settings.json is edited through a temporary file and backed up once');
+  }
+  return lines.join('\n');
+}
+
+function main(argv) {
+  const args = parseArgs(argv || []);
+  const file = settingsFile();
+  let settings;
+  try {
+    settings = readJson(file) || {};
+  } catch (err) {
+    process.stderr.write('statusline: could not read ' + file + ': ' + err.message + '\n');
+    return 1;
+  }
+  const state = readState();
+
+  if (args.command === 'status') {
+    process.stdout.write(describeStatus(settings, state) + '\n');
+    return 0;
+  }
+
+  if (args.command === 'on') {
+    if (args.refresh !== null && (!Number.isFinite(args.refresh) || args.refresh < 1)) {
+      process.stderr.write('statusline: --refresh takes a whole number of seconds, 1 or more\n');
+      return 2;
+    }
+    const planned = planOn(settings, state, { refresh: args.refresh, chain: args.chain });
+    if (args.dryRun) {
+      process.stdout.write((planned.changes.length ? planned.changes.join('\n') : 'no change') + '\n');
+      return 0;
+    }
+    backupOnce(file);
+    fs.mkdirSync(path.dirname(planned.state.launcher), { recursive: true });
+    fs.writeFileSync(planned.state.launcher, launcherSource(planned.state.feed), 'utf8');
+    writeJson(file, planned.settings);
+    writeJson(stateFile(), planned.state);
+    process.stdout.write(
+      (planned.changes.length ? planned.changes.join('\n') : 'already on') +
+        '\nThe bars appear under the prompt in new Claude Code sessions' +
+        (planned.state.chain ? ', above the status line that was already there' : '') +
+        '.\n'
+    );
+    return 0;
+  }
+
+  if (args.command === 'off') {
+    const planned = planOff(settings, state);
+    if (args.dryRun) {
+      process.stdout.write((planned.changes.length ? planned.changes.join('\n') : 'no change') + '\n');
+      return 0;
+    }
+    if (planned.changes.length) writeJson(file, planned.settings);
+    for (const stale of [stateFile(), launcherFile()]) {
+      try {
+        fs.unlinkSync(stale);
+      } catch (err) {
+        // Already gone is the state we want.
+      }
+    }
+    process.stdout.write((planned.changes.length ? planned.changes.join('\n') : 'already off') + '\n');
+    return 0;
+  }
+
+  process.stderr.write('statusline: unknown command "' + args.command + '". Use status, on or off.\n');
+  return 2;
+}
+
+module.exports = {
+  settingsFile,
+  stateFile,
+  launcherFile,
+  feedFile,
+  readState,
+  launcherSource,
+  parseArgs,
+  isOurs,
+  planOn,
+  planOff,
+  describeStatus,
+  main,
+};
+
+if (require.main === module) {
+  process.exitCode = main(process.argv.slice(2));
+}

package/skills/usage-limits/scripts/stop.js

@@ -15,12 +15,16 @@
 const usage = require('./usage.js');
 const host = require('./host.js');
 const tally = require('./tally.js');
+const activity = require('./activity.js');
 
 async function run(now, hookInput) {
+  const sessionId = hookInput && hookInput.session_id ? hookInput.session_id : null;
+  // The reply is finished: the panel beside the chat can stop animating.
+  activity.mark('idle', sessionId, null, now);
+
   if (String(process.env.USAGE_LIMITS_TALLY || '').toLowerCase() === 'off') return '';
   usage.setHost(host.detect(process.argv.slice(2), process.env));
 
-  const sessionId = hookInput && hookInput.session_id ? hookInput.session_id : null;
   const transcript = hookInput && hookInput.transcript_path ? hookInput.transcript_path : null;
   if (!sessionId || !transcript) return '';
 

package/skills/usage-limits/scripts/tally.js

@@ -123,18 +123,12 @@ function readNewLines(file, from) {
 }
 
 // Where Claude Code writes the transcripts of the subagents a session spawned.
+// Plain subagents write straight into <session>/subagents/; the agents a
+// Workflow runs write under subagents/workflows/<run id>/. Both spend this
+// session's budget.
 function subagentFiles(transcriptPath, sessionId) {
   const dir = path.join(path.dirname(transcriptPath), sessionId, 'subagents');
-  let names;
-  try {
-    names = fs.readdirSync(dir);
-  } catch (err) {
-    return [];
-  }
-  return names
-    .filter((name) => name.endsWith('.jsonl'))
-    .sort()
-    .map((name) => path.join(dir, name));
+  return usage.subagentTranscripts(dir, 0).sort();
 }
 
 function apply(session, event, sidechain, delta) {