@workit-dev/core 0.0.1 → 1.0.0

package/src/core/model-fallback.ts

@@ -0,0 +1,208 @@
+// Model fallback on a usage limit (#655): a subscription that hits its usage
+// limit (Anthropic 5-hour or weekly, OpenAI usage limit, a 429 quota) is
+// marked exhausted until its reset, per user, in `model-limits.json` under the
+// state dir. A role whose `models.roles` value is an ordered list then runs on
+// the first model whose provider is not exhausted (core/role-models.ts), and
+// on its primary again once the reset passes.
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { resolveStateDir } from "./logger";
+import { hostFamily, modelSources } from "./workspaces";
+
+export const LIMITS_FILE = "model-limits.json";
+export const DEFAULT_LIMIT_WINDOW_MS = 5 * 3_600_000;
+/** Entries older than this are dropped on the next write. */
+const KEEP_MS = 9 * 86_400_000;
+
+export type Exhaustion = { until: string; since: string; reason: string };
+type Store = {
+  exhausted: Record<string, Exhaustion>;
+  /** Limit evidence already counted (a transcript tail, an OpenCode call). */
+  seen: Record<string, string>;
+  /** Worker prompts already re-dispatched once after a limit. */
+  redispatched: Record<string, string>;
+};
+
+const FAMILIES = ["fable", "opus", "sonnet", "haiku"] as const;
+
+/** The Claude family a model name belongs to (`opus` for `claude-opus-5`), or null. */
+const modelFamily = (model: string): string | null =>
+  FAMILIES.find((family) => model.toLowerCase().includes(family)) ?? null;
+
+/**
+ * The subscription a model runs on: the `provider/` prefix when it has one
+ * (OpenCode's `providerID/modelID`, a gateway's `anthropic/claude-…`), else
+ * `anthropic` for a Claude name, `openai` for a GPT, o-series or Codex name,
+ * else the host's own provider (Claude Code: anthropic, Codex: openai), else null.
+ */
+export const providerOf = (model: string, host?: string | null): string | null => {
+  const trimmed = model.trim().toLowerCase();
+  const slash = trimmed.indexOf("/");
+  if (slash > 0) return trimmed.slice(0, slash);
+  if (/^(?:claude|sonnet|opus|haiku|fable)\b|(?:^|[.-])claude-/u.test(trimmed)) return "anthropic";
+  if (/^(?:gpt|o\d|codex|chatgpt)\b/u.test(trimmed)) return "openai";
+  const family = host ? hostFamily(host) : null;
+  if (family === "claude_code") return "anthropic";
+  if (family === "codex") return "openai";
+  return null;
+};
+
+const empty = (): Store => ({ exhausted: {}, seen: {}, redispatched: {} });
+
+const storePath = (stateDir?: string) => path.join(stateDir ?? resolveStateDir(), LIMITS_FILE);
+
+const readStore = (stateDir?: string): Store => {
+  try {
+    const parsed = JSON.parse(readFileSync(storePath(stateDir), "utf8")) as Partial<Store>;
+    const store = empty();
+    for (const key of ["exhausted", "seen", "redispatched"] as const)
+      if (parsed[key] && typeof parsed[key] === "object") Object.assign(store[key], parsed[key]);
+    return store;
+  } catch {
+    return empty();
+  }
+};
+
+/** Best effort: a read-only state dir never fails a hook. */
+const writeStore = (store: Store, now: Date, stateDir?: string): void => {
+  const cutoff = now.getTime() - KEEP_MS;
+  for (const key of ["seen", "redispatched"] as const)
+    for (const [id, at] of Object.entries(store[key]))
+      if (!(Date.parse(at) > cutoff)) delete store[key][id];
+  for (const [id, entry] of Object.entries(store.exhausted))
+    if (!(Date.parse(entry.until) > cutoff)) delete store.exhausted[id];
+  try {
+    const file = storePath(stateDir);
+    mkdirSync(path.dirname(file), { recursive: true });
+    const temp = `${file}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(store, null, 2)}\n`);
+    renameSync(temp, file);
+  } catch {
+    // The limit is noticed again next time.
+  }
+};
+
+/**
+ * Mark `key` (a provider, or `provider/family` for a per-model limit such as
+ * Claude's Opus limit) exhausted until `until`; a later reset already on
+ * record is kept.
+ */
+export const markExhausted = (
+  key: string,
+  until: Date,
+  reason: string,
+  now: Date = new Date(),
+  stateDir?: string,
+): Exhaustion => {
+  const store = readStore(stateDir);
+  const previous = store.exhausted[key];
+  const entry =
+    previous && Date.parse(previous.until) >= until.getTime()
+      ? previous
+      : {
+          until: until.toISOString(),
+          since: now.toISOString(),
+          reason: reason.slice(0, 200),
+        };
+  store.exhausted[key] = entry;
+  writeStore(store, now, stateDir);
+  return entry;
+};
+
+/** Providers (or `provider/family` keys) exhausted at `now`, soonest reset first. */
+export const exhaustedProviders = (
+  now: Date = new Date(),
+  stateDir?: string,
+): Array<Exhaustion & { provider: string }> =>
+  Object.entries(readStore(stateDir).exhausted)
+    .filter(([, entry]) => Date.parse(entry.until) > now.getTime())
+    .map(([provider, entry]) => ({ provider, ...entry }))
+    .toSorted((a, b) => Date.parse(a.until) - Date.parse(b.until));
+
+/** The exhaustion that blocks `model` on `host` at `now`, or null when it may run. */
+export const exhaustionFor = (
+  model: string,
+  host: string | null,
+  now: Date = new Date(),
+  stateDir?: string,
+): (Exhaustion & { provider: string }) | null => {
+  const provider = providerOf(model, host);
+  if (!provider) return null;
+  const family = modelFamily(model);
+  const keys = new Set([provider, ...(family ? [`${provider}/${family}`] : [])]);
+  return exhaustedProviders(now, stateDir).find((entry) => keys.has(entry.provider)) ?? null;
+};
+
+/** Record a piece of limit evidence once; false when it was already counted. */
+export const firstSighting = (id: string, now: Date = new Date(), stateDir?: string): boolean => {
+  const store = readStore(stateDir);
+  if (store.seen[id]) return false;
+  store.seen[id] = now.toISOString();
+  writeStore(store, now, stateDir);
+  return true;
+};
+
+/** A stable key for a worker's prompt. */
+export const promptKey = (prompt: string): string =>
+  createHash("sha256").update(prompt.trim()).digest("hex").slice(0, 16);
+
+/**
+ * Whether a worker whose prompt is `key` may be re-dispatched after dying on a
+ * limit: true the first time (and recorded), false once it was re-dispatched.
+ */
+export const claimRedispatch = (
+  key: string,
+  now: Date = new Date(),
+  stateDir?: string,
+): boolean => {
+  const store = readStore(stateDir);
+  if (store.redispatched[key]) return false;
+  store.redispatched[key] = now.toISOString();
+  writeStore(store, now, stateDir);
+  return true;
+};
+
+const UNITS: Record<string, number> = {
+  d: 86_400_000,
+  h: 3_600_000,
+  m: 60_000,
+  s: 1000,
+};
+
+/** `5h`, `90m`, `2d`, `1d 12h` or a number of hours as milliseconds; null when unreadable. */
+export const parseWindow = (value: unknown): number | null => {
+  if (typeof value === "number") return value > 0 ? value * 3_600_000 : null;
+  if (typeof value !== "string" || !value.trim()) return null;
+  let total = 0;
+  const rest = value
+    .trim()
+    .toLowerCase()
+    .replace(/(\d+(?:\.\d+)?)\s*([dhms])/gu, (_all, amount: string, unit: string) => {
+      total += Number(amount) * UNITS[unit];
+      return "";
+    });
+  return rest.trim() === "" && total > 0 ? total : null;
+};
+
+/**
+ * How long a provider stays exhausted when its limit text names no reset:
+ * `models.limitWindow` (nearest workspace, then the global default), else 5h.
+ */
+export const limitWindowMs = (cwd: string, dir?: string): number => {
+  for (const source of modelSources(cwd, dir)) {
+    const models = source.models as Record<string, unknown> | undefined;
+    if (models && typeof models === "object" && Object.hasOwn(models, "limitWindow")) {
+      const parsed = parseWindow(models.limitWindow);
+      if (parsed) return parsed;
+    }
+  }
+  return DEFAULT_LIMIT_WINDOW_MS;
+};
+
+/** `2026-11-03 19:00` in the local zone, for notes and `models show`. */
+export const shortTime = (iso: string): string => {
+  const at = new Date(iso);
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())} ${pad(at.getHours())}:${pad(at.getMinutes())}`;
+};

package/src/core/node-resolve.mjs

@@ -0,0 +1,249 @@
+// Finds a Node that can run a Workit hook when the PATH node is below the
+// package's engines floor (a repo pinned to Node 16/18/22 by a version
+// manager). Plain JavaScript with node: builtins only and no syntax newer than
+// Node 16 supports: the host launchers import it (or carry a byte-equal copy,
+// a test holds them equal) and must start on the very Node they are replacing.
+// Side-effect free: importing it runs nothing; no process is spawned here.
+//
+// Order: (1) $WORKIT_NODE; (2) the node `workit setup`/`upgrade` recorded in
+// <state dir>/node.json (workit-paths.mjs); (3) a scan of version-manager installs (fnm, nvm,
+// volta, mise, asdf and the Windows layouts), highest version >= the floor.
+import { spawnSync } from "node:child_process";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { stateDir } from "./workit-paths.mjs";
+
+/** The Node major the hooks need; a test holds it equal to every package's engines.node. */
+export const HOOK_NODE_FLOOR = [24, 0, 0];
+
+/** Set on the re-executed child so a launcher never re-executes twice. */
+export const HOOK_NODE_REEXEC_ENV = "WORKIT_HOOK_REEXEC";
+
+const MAX_ENTRIES_PER_ROOT = 200;
+
+/** @param {unknown} text @returns {number[] | null} */
+export const parseNodeVersion = (text) => {
+  const found = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(String(text).trim());
+  return found ? [Number(found[1]), Number(found[2] || 0), Number(found[3] || 0)] : null;
+};
+
+/** @param {number[]} a @param {number[]} b negative when a < b */
+export const compareVersions = (a, b) => {
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] - b[i];
+  return 0;
+};
+
+/** The `>=X[.Y[.Z]]` minimum of an engines.node range, or null. @param {unknown} range */
+export const floorOfRange = (range) => {
+  const min = /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(String(range === undefined ? "" : range));
+  return min ? [Number(min[1]), Number(min[2] || 0), Number(min[3] || 0)] : null;
+};
+
+/** Workit's state dir (workit-paths.mjs, the one resolver). @param {NodeJS.ProcessEnv} env */
+export const hookStateDir = (env) => stateDir(env);
+
+/** @param {string} file */
+const isFile = (file) => {
+  try {
+    return statSync(file).isFile();
+  } catch {
+    return false;
+  }
+};
+
+/** @param {string} file */
+const readJson = (file) => {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * The version-manager directories that hold one node per child directory:
+ * `{ dir, bin }` where the node is `<dir>/<child>/<bin>`.
+ * @param {NodeJS.ProcessEnv} env @param {string} platform
+ */
+const scanRoots = (env, platform) => {
+  const home = env.HOME || env.USERPROFILE || os.homedir();
+  const win = platform === "win32";
+  const exe = win ? "node.exe" : "node";
+  const bin = win ? exe : path.join("bin", exe);
+  /** @type {Array<{ dir: string, bin: string }>} */
+  const roots = [];
+  const add = (dir, rel) => {
+    if (dir) roots.push({ dir, bin: rel });
+  };
+  // fnm: <dir>/node-versions/<v>/installation/bin/node
+  const fnmDirs = [
+    env.FNM_DIR,
+    win ? path.join(env.APPDATA || path.join(home, "AppData", "Roaming"), "fnm") : "",
+    win ? path.join(env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "fnm") : "",
+    env.XDG_DATA_HOME ? path.join(env.XDG_DATA_HOME, "fnm") : "",
+    path.join(home, ".local", "share", "fnm"),
+    path.join(home, "Library", "Application Support", "fnm"),
+    path.join(home, ".fnm"),
+  ];
+  for (const dir of fnmDirs)
+    if (dir) add(path.join(dir, "node-versions"), path.join("installation", bin));
+  // nvm: <dir>/versions/node/<v>/bin/node; nvm-windows: <NVM_HOME>/<v>/node.exe
+  for (const dir of [env.NVM_DIR, path.join(home, ".nvm")])
+    if (dir) add(path.join(dir, "versions", "node"), bin);
+  if (env.NVM_HOME) add(env.NVM_HOME, exe);
+  // volta: <dir>/tools/image/node/<v>/bin/node
+  const volta = env.VOLTA_HOME || (win ? "" : path.join(home, ".volta"));
+  if (volta) add(path.join(volta, "tools", "image", "node"), bin);
+  if (win)
+    add(
+      path.join(
+        env.LOCALAPPDATA || path.join(home, "AppData", "Local"),
+        "Volta",
+        "tools",
+        "image",
+        "node",
+      ),
+      bin,
+    );
+  // mise and asdf: <dir>/installs/node[js]/<v>/bin/node
+  const mise = env.MISE_DATA_DIR || path.join(home, ".local", "share", "mise");
+  add(path.join(mise, "installs", "node"), bin);
+  const asdf = env.ASDF_DATA_DIR || path.join(home, ".asdf");
+  add(path.join(asdf, "installs", "nodejs"), bin);
+  return roots;
+};
+
+/**
+ * Every installed node a version manager lists, with its version: directory
+ * listings only, at most MAX_ENTRIES_PER_ROOT per root.
+ * @param {NodeJS.ProcessEnv} env @param {string} [platform]
+ * @returns {Array<{ path: string, version: number[], source: string }>}
+ */
+export const scanInstalledNodes = (env, platform = process.platform) => {
+  /** @type {Array<{ path: string, version: number[], source: string }>} */
+  const found = [];
+  for (const root of scanRoots(env, platform)) {
+    let names;
+    try {
+      names = readdirSync(root.dir).slice(0, MAX_ENTRIES_PER_ROOT);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      const version = parseNodeVersion(name);
+      if (!version || !/^v?\d/.test(name)) continue;
+      // volta's layout nests nothing; fnm's, nvm's, mise's and asdf's differ only in `bin`.
+      const candidate = path.join(root.dir, name, root.bin);
+      if (isFile(candidate)) found.push({ path: candidate, version, source: root.dir });
+    }
+  }
+  return found;
+};
+
+/**
+ * The node the hooks should run on, or null. `floor` is [major, minor, patch].
+ * @param {{ env: NodeJS.ProcessEnv, floor: number[], platform?: string }} options
+ * @returns {{ path: string, version: string | null, source: "env" | "recorded" | "scan" } | null}
+ */
+export const resolveHookNode = ({ env, floor, platform = process.platform }) => {
+  if (env.WORKIT_NODE && isFile(env.WORKIT_NODE))
+    return { path: env.WORKIT_NODE, version: null, source: "env" };
+  const recorded = readJson(path.join(hookStateDir(env), "node.json"));
+  if (recorded && typeof recorded.path === "string" && isFile(recorded.path)) {
+    const version = parseNodeVersion(recorded.version);
+    if (version && compareVersions(version, floor) >= 0)
+      return { path: recorded.path, version: String(recorded.version), source: "recorded" };
+  }
+  let best = null;
+  for (const entry of scanInstalledNodes(env, platform))
+    if (
+      compareVersions(entry.version, floor) >= 0 &&
+      (!best || compareVersions(entry.version, best.version) > 0)
+    )
+      best = entry;
+  return best ? { path: best.path, version: best.version.join("."), source: "scan" } : null;
+};
+
+/**
+ * The fail-open line for a node below the floor: null when `found` is at or
+ * above `floor`, or unparseable (an unreadable version never blocks).
+ * @param {string} found @param {number[] | null} floor @param {string} range
+ */
+export const floorMessage = (found, floor, range) => {
+  if (!floor) return null;
+  const have = parseNodeVersion(found);
+  if (!have || compareVersions(have, floor) >= 0) return null;
+  return `needs Node ${range}, found ${found}`;
+};
+
+/** What the agent is told once, at SessionStart, when no Node >= the floor resolves. */
+export const nodeFloorNotice = (found, range) =>
+  `Workit hooks are off: the Node on PATH is ${String(found).replace(/^v/, "")}, below the required ${range}, and no Node 24+ was found. ` +
+  "Install Node 24 (fnm install 24, nvm install 24) or run `workit setup` from a Node 24 shell so Workit can record it; " +
+  "`workit doctor` (check hook_node) shows what the hooks run on.";
+
+/**
+ * Where setup and upgrade record the Node they run on. A no-op for a non-node
+ * binary (bun) or a Node below the floor.
+ * @param {{ env: NodeJS.ProcessEnv, execPath: string, version: string, floor: number[] }} options
+ * @returns {string | null} the file written
+ */
+export const nodeRecord = ({ env, execPath, version, floor }) => {
+  const parsed = parseNodeVersion(version);
+  if (!parsed || compareVersions(parsed, floor) < 0) return null;
+  if (!/^node(?:\.exe)?$/i.test(path.basename(execPath))) return null;
+  return path.join(hookStateDir(env), "node.json");
+};
+
+/**
+ * Run `script args…` on `nodePath` with this process's stdin, stdout and
+ * stderr passed through. The child carries the re-exec guard and a real
+ * version (WORKIT_HOOK_NODE_VERSION, a test seam, is dropped).
+ * @returns {number | null} the child's exit code, or null when it could not start
+ */
+export const reexecOnNode = (nodePath, script, args, env) => {
+  const child = Object.assign({}, env, { [HOOK_NODE_REEXEC_ENV]: "1" });
+  delete child.WORKIT_HOOK_NODE_VERSION;
+  const run = spawnSync(nodePath, [script].concat(args), {
+    stdio: "inherit",
+    env: child,
+    windowsHide: true,
+  });
+  if (run.error) return null;
+  return run.status === null ? 1 : run.status;
+};
+
+/**
+ * What a launcher does on a Node below its floor: re-run itself on a resolved
+ * Node (the child's exit code is returned), else fail open: one stderr line,
+ * and `{}` on stdout, except that a start event answers with `notice(text)` so
+ * the agent is told the hooks are off. Resolves to the exit code.
+ * @param {{ host: string, range: string, floor: number[], found: string, script: string,
+ *   argv: string[], env: NodeJS.ProcessEnv, isStart: (event: unknown) => boolean,
+ *   notice: (text: string) => unknown }} options
+ */
+export const handleBelowFloor = async (options) => {
+  if (!options.env[HOOK_NODE_REEXEC_ENV]) {
+    const hit = resolveHookNode({ env: options.env, floor: options.floor });
+    const code = hit ? reexecOnNode(hit.path, options.script, options.argv, options.env) : null;
+    if (code !== null) return code;
+  }
+  process.stderr.write(
+    `[workit] ${options.host} hook unavailable: needs Node ${options.range}, found ${options.found}\n`,
+  );
+  let early = "";
+  for await (const chunk of process.stdin) early += String(chunk);
+  let event;
+  try {
+    event = JSON.parse(early).hook_event_name;
+  } catch {
+    event = undefined;
+  }
+  process.stdout.write(
+    options.isStart(event)
+      ? `${JSON.stringify(options.notice(nodeFloorNotice(options.found, options.range)))}\n`
+      : "{}\n",
+  );
+  return 0;
+};