threadwire 0.1.13 → 0.1.15

package/src/provider-capacity-codex.js

@@ -0,0 +1,176 @@
+// @ts-check
+
+import {spawn} from "node:child_process"
+import {providerExecutable} from "./providers/executable.js"
+import {CapacityProbeError, DEFAULT_CAPACITY_TIMEOUT_MS, normalizeCodexRateLimits} from "./provider-capacity.js"
+
+const DEFAULT_EXECUTABLE = "/opt/data/libexec/threadwire/codex"
+const MAX_LINE_BYTES = 65_536
+const MAX_LINES = 1_024
+
+/**
+ * Probe live Codex account capacity through `codex app-server` JSON-RPC over
+ * stdio: `initialize` followed by `account/rateLimits/read`. The child is
+ * always killed, its stderr is consumed but never forwarded, and server error
+ * detail (which can carry account or credential material) is never propagated —
+ * failures classify with fixed, credential-free messages.
+ * @param {{
+ *   env?: NodeJS.ProcessEnv,
+ *   spawnImplementation?: typeof spawn | undefined,
+ *   timeoutMs?: number
+ * }} options
+ * @returns {Promise<import("./provider-capacity.js").CapacityWindows>}
+ */
+export async function probeCodexCapacity(options) {
+  const environment = options.env ?? process.env
+  const spawnImplementation = options.spawnImplementation ?? spawn
+  const timeoutMs = options.timeoutMs ?? DEFAULT_CAPACITY_TIMEOUT_MS
+  const executable = providerExecutable("THREADWIRE_CODEX_BIN", DEFAULT_EXECUTABLE, environment)
+  const result = await appServerExchange(spawnImplementation, executable, environment, timeoutMs)
+  return normalizeCodexRateLimits(result)
+}
+
+/**
+ * Run the bounded two-request JSON-RPC exchange and resolve with the raw
+ * `account/rateLimits/read` result for fail-closed normalization.
+ * @param {typeof spawn} spawnImplementation
+ * @param {string} executable
+ * @param {NodeJS.ProcessEnv} environment
+ * @param {number} timeoutMs
+ * @returns {Promise<unknown>}
+ */
+function appServerExchange(spawnImplementation, executable, environment, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    /** @type {ReturnType<typeof spawn>} */
+    let child
+    try {
+      child = spawnImplementation(executable, ["app-server"], {env: environment, stdio: ["pipe", "pipe", "pipe"]})
+    } catch {
+      reject(new CapacityProbeError("unavailable", "Codex app-server is unavailable"))
+      return
+    }
+    let settled = false
+    let buffer = ""
+    let lines = 0
+    let phase = "initialize"
+    // The timer is always cleared by finish, so it never outlives the exchange.
+    const timer = setTimeout(() => {
+      fail(new CapacityProbeError("unavailable", "Codex app-server capacity probe timed out"))
+    }, timeoutMs)
+
+    /**
+     * @param {(value: unknown) => void} settle
+     * @param {unknown} value
+     */
+    function finish(settle, value) {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      child.kill()
+      settle(value)
+    }
+
+    /** @param {CapacityProbeError} error */
+    function fail(error) {
+      finish(reject, error)
+    }
+
+    /** @param {Record<string, unknown>} request */
+    function write(request) {
+      try {
+        child.stdin?.write(`${JSON.stringify(request)}\n`)
+      } catch {
+        fail(new CapacityProbeError("unavailable", "Codex app-server is unavailable"))
+      }
+    }
+
+    /** @param {string} line */
+    function handleLine(line) {
+      if (line.trim().length === 0) return
+      /** @type {unknown} */
+      let message
+      try {
+        message = JSON.parse(line)
+      } catch {
+        fail(new CapacityProbeError("protocol", "Codex app-server emitted a malformed record"))
+        return
+      }
+      if (!isRecord(message) || (message.id !== 1 && message.id !== 2)) return
+      if (message.error !== undefined) {
+        if (message.id === 1 || phase === "initialize") {
+          fail(new CapacityProbeError("protocol", "Codex app-server initialize failed"))
+        } else if (isAuthRejection(message.error)) {
+          fail(new CapacityProbeError("auth", "Codex rate-limits credential was rejected"))
+        } else {
+          fail(new CapacityProbeError("protocol", "Codex rate-limits request failed"))
+        }
+        return
+      }
+      if (message.id === 1) {
+        if (phase !== "initialize") {
+          fail(new CapacityProbeError("protocol", "Codex app-server answered out of order"))
+          return
+        }
+        phase = "read"
+        write({jsonrpc: "2.0", id: 2, method: "account/rateLimits/read"})
+        return
+      }
+      if (phase !== "read") {
+        fail(new CapacityProbeError("protocol", "Codex app-server answered out of order"))
+        return
+      }
+      finish(resolve, message.result)
+    }
+
+    child.on("error", () => fail(new CapacityProbeError("unavailable", "Codex app-server is unavailable")))
+    child.on("close", () => fail(new CapacityProbeError("unavailable", "Codex app-server exited before answering")))
+    child.stdin?.on("error", () => {})
+    child.stderr?.on("data", () => {})
+    child.stdout?.on("data", (chunk) => {
+      if (settled) return
+      buffer += /** @type {Buffer} */ (chunk).toString("utf8")
+      let index = buffer.indexOf("\n")
+      while (index >= 0 && !settled) {
+        const line = buffer.slice(0, index)
+        buffer = buffer.slice(index + 1)
+        lines += 1
+        if (line.length > MAX_LINE_BYTES || lines > MAX_LINES) {
+          fail(new CapacityProbeError("protocol", "Codex app-server exceeded the bounded exchange"))
+          return
+        }
+        handleLine(line)
+        index = buffer.indexOf("\n")
+      }
+      if (!settled && buffer.length > MAX_LINE_BYTES) {
+        fail(new CapacityProbeError("protocol", "Codex app-server exceeded the bounded exchange"))
+      }
+    })
+
+    write({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {clientInfo: {name: "threadwire-capacity", version: "1"}}
+    })
+  })
+}
+
+/**
+ * A JSON-RPC error whose server message indicates an authentication or login
+ * failure classifies as `auth`; everything else stays `protocol`. The server
+ * message itself is only inspected, never propagated.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isAuthRejection(value) {
+  if (!isRecord(value) || typeof value.message !== "string") return false
+  return /auth|login|unauthorized|token/iu.test(value.message)
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}

package/src/provider-capacity-kimi.js

@@ -0,0 +1,105 @@
+// @ts-check
+
+import {isAbsolute, join} from "node:path"
+import {readResponseCapped} from "./absolute-deadline.js"
+import {openKimiOAuthStore} from "./kimi-oauth-store.js"
+import {CapacityProbeError, DEFAULT_CAPACITY_TIMEOUT_MS, normalizeKimiUsages} from "./provider-capacity.js"
+
+const USAGES_URL = "https://api.kimi.com/coding/v1/usages"
+const MAX_USAGES_BYTES = 65_536
+const RE_LOGIN_MESSAGE = "Kimi OAuth credential was rejected; re-login required"
+const REFRESH_REQUIRED_MESSAGE = "Kimi OAuth credential requires refresh"
+
+/**
+ * Probe live Kimi account capacity through the official usages endpoint. The
+ * OAuth bearer is loaded through the hardened credential store's non-mutating
+ * `getCurrentAccessToken` and used in-process only: the probe never refreshes,
+ * persists, or tombstones credentials, and the token is never printed or
+ * embedded in errors. All failures are classified with fixed, credential-free
+ * messages.
+ * @param {{
+ *   env?: NodeJS.ProcessEnv,
+ *   fetchImplementation?: typeof fetch | undefined,
+ *   timeoutMs?: number
+ * }} options
+ * @returns {Promise<import("./provider-capacity.js").CapacityWindows>}
+ */
+export async function probeKimiCapacity(options) {
+  const environment = options.env ?? process.env
+  const fetchImplementation = options.fetchImplementation ?? fetch
+  const timeoutMs = options.timeoutMs ?? DEFAULT_CAPACITY_TIMEOUT_MS
+  const file = resolveCredentialFile(environment)
+  const signal = AbortSignal.timeout(timeoutMs)
+  /** @type {string} */
+  let token
+  try {
+    const store = await openKimiOAuthStore({file})
+    token = await store.getCurrentAccessToken()
+  } catch (error) {
+    if (error instanceof Error && error.message === RE_LOGIN_MESSAGE) {
+      throw new CapacityProbeError("auth", RE_LOGIN_MESSAGE)
+    }
+    if (error instanceof Error && error.message === REFRESH_REQUIRED_MESSAGE) {
+      throw new CapacityProbeError("unavailable", REFRESH_REQUIRED_MESSAGE)
+    }
+    throw new CapacityProbeError("auth", "Kimi OAuth credential file is unavailable")
+  }
+  /** @type {Response} */
+  let response
+  try {
+    response = await fetchImplementation(USAGES_URL, {
+      method: "GET",
+      redirect: "error",
+      headers: {accept: "application/json", authorization: `Bearer ${token}`},
+      signal
+    })
+  } catch {
+    throw new CapacityProbeError("unavailable", "Kimi usages request is unavailable")
+  }
+  if (response.status === 401 || response.status === 403) {
+    throw new CapacityProbeError("auth", "Kimi usages credential was rejected")
+  }
+  if (!response.ok) throw new CapacityProbeError("unavailable", "Kimi usages endpoint is unavailable")
+  const contentType = response.headers.get("content-type")
+  if (contentType === null || !contentType.toLowerCase().includes("application/json")) {
+    throw new CapacityProbeError("protocol", "Kimi usages response has an unexpected content type")
+  }
+  /** @type {unknown} */
+  let parsed
+  try {
+    const bytes = await readResponseCapped(response, MAX_USAGES_BYTES, signal)
+    parsed = JSON.parse(bytes.toString("utf8"))
+  } catch {
+    throw new CapacityProbeError("protocol", "Kimi usages response is not valid bounded JSON")
+  }
+  return normalizeKimiUsages(parsed)
+}
+
+/**
+ * Resolve the Kimi credential file: a non-empty absolute
+ * `THREADWIRE_KIMI_OAUTH_FILE` explicitly overrides; otherwise the installed
+ * Kimi CLI's canonical `${KIMI_CODE_HOME}/credentials/kimi-code.json` store;
+ * otherwise the vendor default `${HOME}/.kimi-code/credentials/kimi-code.json`.
+ * Missing, relative, or NUL-containing candidates never qualify, and with no
+ * usable candidate the probe fails closed without logging any path.
+ * @param {NodeJS.ProcessEnv} environment
+ * @returns {string}
+ */
+function resolveCredentialFile(environment) {
+  const override = usablePath(environment.THREADWIRE_KIMI_OAUTH_FILE)
+  if (override !== undefined) return override
+  const codeHome = usablePath(environment.KIMI_CODE_HOME)
+  if (codeHome !== undefined) return join(codeHome, "credentials", "kimi-code.json")
+  const home = usablePath(environment.HOME)
+  if (home !== undefined) return join(home, ".kimi-code", "credentials", "kimi-code.json")
+  throw new CapacityProbeError("auth", "Kimi OAuth credential file is not configured")
+}
+
+/**
+ * @param {string | undefined} value
+ * @returns {string | undefined}
+ */
+function usablePath(value) {
+  if (value === undefined || value.length === 0 || value.includes("\0") || !isAbsolute(value)) return undefined
+  return value
+}

package/src/provider-capacity.js

@@ -0,0 +1,292 @@
+// @ts-check
+
+/** @type {CapacityProvider[]} */
+export const CAPACITY_PROVIDERS = ["codex", "kimi"]
+export const DEFAULT_SHORT_RESERVE_PERCENT = 20
+export const DEFAULT_LONG_RESERVE_PERCENT = 10
+export const DEFAULT_CAPACITY_TIMEOUT_MS = 15_000
+
+const MAX_EPOCH_SECONDS = 4_102_444_800
+const MAX_WINDOW_MINUTES = 525_600
+const KIMI_LONG_WINDOW_SECONDS = 604_800
+const MAX_KIMI_LIMIT_WINDOWS = 8
+const MAX_QUOTA_DIGITS = 15
+const MAX_RESET_TIME_LENGTH = 64
+const ISO_RESET_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})$/u
+
+/** @typedef {"codex" | "kimi"} CapacityProvider */
+/** @typedef {"unavailable" | "auth" | "protocol"} CapacityFailureKind */
+/** @typedef {{usedPercent: number, remainingPercent: number, resetAt: string, windowDurationSeconds: number}} CapacityWindow */
+/** @typedef {{short: CapacityWindow, long?: CapacityWindow}} CapacityWindows */
+/** @typedef {{provider: CapacityProvider, status: "ok", windows: CapacityWindows} | {provider: CapacityProvider, status: CapacityFailureKind, error: string}} CapacityCandidate */
+/** @typedef {{provider: CapacityProvider, reason: string}} RejectedCandidate */
+/** @typedef {{provider: CapacityProvider, score: number}} CapacitySelection */
+/** @typedef {{shortReservePercent: number, longReservePercent: number}} CapacityReserves */
+/** @typedef {(request: {env: NodeJS.ProcessEnv, timeoutMs: number}) => Promise<CapacityWindows>} CapacityProbeFunction */
+
+/** A fixed-message, credential-free probe failure classified for the caller. */
+export class CapacityProbeError extends Error {
+  /**
+   * @param {CapacityFailureKind} kind
+   * @param {string} message
+   */
+  constructor(kind, message) {
+    super(message)
+    this.name = "CapacityProbeError"
+    this.kind = kind
+  }
+}
+
+/**
+ * Normalize a Codex `account/rateLimits/read` JSON-RPC result into the canonical
+ * short/long window form. Only the quota projection is parsed: `rateLimits`
+ * must carry a `primary` window and a nullable `secondary`; unrelated result or
+ * `rateLimits` metadata (limit identifiers/names, credits, plan type) is
+ * neither read nor propagated. Any quota shape drift fails closed as a protocol
+ * error; raw response content is never carried into the error.
+ * @param {unknown} value
+ * @returns {CapacityWindows}
+ */
+export function normalizeCodexRateLimits(value) {
+  if (!isRecord(value) || !isRecord(value.rateLimits)) throw codexProtocolError()
+  const rateLimits = value.rateLimits
+  const primary = rateLimits.primary
+  if (!isRecord(primary)) throw codexProtocolError()
+  const short = codexWindow(primary)
+  const secondary = rateLimits.secondary
+  if (secondary === null) return {short}
+  if (!isRecord(secondary)) throw codexProtocolError()
+  const long = codexWindow(secondary)
+  if (long.windowDurationSeconds < short.windowDurationSeconds) throw codexProtocolError()
+  return {short, long}
+}
+
+/**
+ * Normalize a Kimi `GET /coding/v1/usages` body into the canonical short/long
+ * window form. Only the quota projection is parsed: top-level `usage` is the
+ * long (weekly) account quota and the shortest `limits[]` window is `short`;
+ * every returned window is validated but intermediate windows are ignored.
+ * Unrelated top-level fields are neither read nor propagated. Quota numbers
+ * are strict non-negative decimal strings with `used + remaining === limit`;
+ * remaining percent is floored so normalization never overstates capacity.
+ * @param {unknown} value
+ * @returns {CapacityWindows}
+ */
+export function normalizeKimiUsages(value) {
+  if (!isRecord(value) || !Array.isArray(value.limits)
+    || value.limits.length < 1 || value.limits.length > MAX_KIMI_LIMIT_WINDOWS) {
+    throw kimiProtocolError()
+  }
+  const windows = value.limits.map(kimiLimitsWindow)
+  const long = kimiQuotaWindow(value.usage, KIMI_LONG_WINDOW_SECONDS)
+  const [first, ...rest] = windows
+  if (first === undefined) throw kimiProtocolError()
+  let short = first
+  for (const window of rest) {
+    if (window.windowDurationSeconds < short.windowDurationSeconds) short = window
+  }
+  if (long.windowDurationSeconds <= short.windowDurationSeconds) throw kimiProtocolError()
+  return {short, long}
+}
+
+/**
+ * Deterministically select one admission candidate: reject candidates below the
+ * short/long reserves, score survivors by their most constrained window, and
+ * order by score descending, long-window remaining descending, then provider
+ * name ascending. Pure: no I/O, no clock.
+ * @param {CapacityCandidate[]} candidates
+ * @param {CapacityReserves} reserves
+ * @returns {{selection: CapacitySelection | null, rejected: RejectedCandidate[]}}
+ */
+export function selectProvider(candidates, reserves) {
+  /** @type {RejectedCandidate[]} */
+  const rejected = []
+  /** @type {{provider: CapacityProvider, score: number, longRemaining: number}[]} */
+  const survivors = []
+  for (const candidate of candidates) {
+    if (candidate.status !== "ok") {
+      rejected.push({provider: candidate.provider, reason: candidate.status})
+      continue
+    }
+    const shortRemaining = candidate.windows.short.remainingPercent
+    const longRemaining = candidate.windows.long?.remainingPercent ?? 100
+    if (shortRemaining < reserves.shortReservePercent) {
+      rejected.push({provider: candidate.provider, reason: "short-reserve"})
+      continue
+    }
+    if (longRemaining < reserves.longReservePercent) {
+      rejected.push({provider: candidate.provider, reason: "long-reserve"})
+      continue
+    }
+    survivors.push({provider: candidate.provider, score: Math.min(shortRemaining, longRemaining), longRemaining})
+  }
+  survivors.sort((a, b) => (
+    b.score - a.score
+    || b.longRemaining - a.longRemaining
+    || (a.provider < b.provider ? -1 : 1)
+  ))
+  const winner = survivors[0]
+  return {
+    selection: winner === undefined ? null : {provider: winner.provider, score: winner.score},
+    rejected
+  }
+}
+
+/**
+ * Create the live capacity probe. The per-provider probe functions are wired by
+ * the caller (keeping this module import-cycle-free); failures are converted
+ * into per-provider candidates with fixed, credential-free messages and never
+ * mask the other provider.
+ * @param {{
+ *   env?: NodeJS.ProcessEnv,
+ *   probes: Record<CapacityProvider, CapacityProbeFunction>
+ * }} options
+ * @returns {{probe: (provider: CapacityProvider, timeoutMs?: number) => Promise<CapacityCandidate>}}
+ */
+export function createCapacityProbe(options) {
+  const environment = options.env ?? process.env
+  return {
+    async probe(provider, timeoutMs = DEFAULT_CAPACITY_TIMEOUT_MS) {
+      try {
+        const windows = await options.probes[provider]({env: environment, timeoutMs})
+        return {provider, status: "ok", windows}
+      } catch (error) {
+        if (error instanceof CapacityProbeError) return {provider, status: error.kind, error: error.message}
+        return {provider, status: "unavailable", error: "Capacity probe failed"}
+      }
+    }
+  }
+}
+
+/**
+ * Validate one quota window: exactly `usedPercent`, `windowDurationMins`, and
+ * `resetsAt` (epoch seconds, normalized to the canonical `resetAt` output
+ * field); any missing, obsolete, or extra key fails closed.
+ * @param {Record<string, unknown>} value
+ * @returns {CapacityWindow}
+ */
+function codexWindow(value) {
+  if (!exactKeys(value, ["usedPercent", "windowDurationMins", "resetsAt"])
+    || typeof value.usedPercent !== "number" || !Number.isFinite(value.usedPercent)
+    || value.usedPercent < 0 || value.usedPercent > 100
+    || typeof value.windowDurationMins !== "number" || !Number.isSafeInteger(value.windowDurationMins)
+    || value.windowDurationMins < 1 || value.windowDurationMins > MAX_WINDOW_MINUTES) {
+    throw codexProtocolError()
+  }
+  return {
+    usedPercent: value.usedPercent,
+    remainingPercent: 100 - value.usedPercent,
+    resetAt: isoResetAt(value.resetsAt, codexProtocolError),
+    windowDurationSeconds: value.windowDurationMins * 60
+  }
+}
+
+/**
+ * Validate one `limits[]` entry: exact `window`/`detail` keys, minute-unit
+ * duration, and a fully validated quota detail.
+ * @param {unknown} value
+ * @returns {CapacityWindow}
+ */
+function kimiLimitsWindow(value) {
+  if (!isRecord(value) || !exactKeys(value, ["window", "detail"]) || !isRecord(value.window)
+    || !exactKeys(value.window, ["duration", "timeUnit"]) || value.window.timeUnit !== "TIME_UNIT_MINUTE"
+    || typeof value.window.duration !== "number" || !Number.isSafeInteger(value.window.duration)
+    || value.window.duration < 1 || value.window.duration > MAX_WINDOW_MINUTES) {
+    throw kimiProtocolError()
+  }
+  return kimiQuotaWindow(value.detail, value.window.duration * 60)
+}
+
+/**
+ * Validate one quota object (`usage` or `detail`): exact keys, strict
+ * non-negative decimal-string integers with `used + remaining === limit`, a
+ * positive limit, and a bounded ISO-8601 reset time.
+ * @param {unknown} value
+ * @param {number} windowDurationSeconds
+ * @returns {CapacityWindow}
+ */
+function kimiQuotaWindow(value, windowDurationSeconds) {
+  if (!isRecord(value) || !exactKeys(value, ["limit", "used", "remaining", "resetTime"])) {
+    throw kimiProtocolError()
+  }
+  const limit = quotaValue(value.limit)
+  const used = quotaValue(value.used)
+  const remaining = quotaValue(value.remaining)
+  if (limit < 1 || used + remaining !== limit) throw kimiProtocolError()
+  const remainingPercent = Math.floor((remaining / limit) * 100)
+  return {
+    usedPercent: 100 - remainingPercent,
+    remainingPercent,
+    resetAt: isoResetTime(value.resetTime),
+    windowDurationSeconds
+  }
+}
+
+/**
+ * A strict non-negative decimal-string integer, digit-bounded so the sum of
+ * two values always stays a safe integer.
+ * @param {unknown} value
+ * @returns {number}
+ */
+function quotaValue(value) {
+  if (typeof value !== "string" || !/^\d+$/u.test(value) || value.length > MAX_QUOTA_DIGITS) {
+    throw kimiProtocolError()
+  }
+  return Number(value)
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function isoResetTime(value) {
+  if (typeof value !== "string" || value.length < 1 || value.length > MAX_RESET_TIME_LENGTH || !ISO_RESET_TIME.test(value)) {
+    throw kimiProtocolError()
+  }
+  const milliseconds = Date.parse(value)
+  if (!Number.isFinite(milliseconds) || milliseconds < 1 || milliseconds > MAX_EPOCH_SECONDS * 1000) {
+    throw kimiProtocolError()
+  }
+  return new Date(milliseconds).toISOString()
+}
+
+/**
+ * @param {unknown} value
+ * @param {() => CapacityProbeError} errorFactory
+ * @returns {string}
+ */
+function isoResetAt(value, errorFactory) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 || value > MAX_EPOCH_SECONDS) {
+    throw errorFactory()
+  }
+  return new Date(value * 1000).toISOString()
+}
+
+/** @returns {CapacityProbeError} */
+function codexProtocolError() {
+  return new CapacityProbeError("protocol", "Codex rate-limits response has an unexpected shape")
+}
+
+/** @returns {CapacityProbeError} */
+function kimiProtocolError() {
+  return new CapacityProbeError("protocol", "Kimi usages response has an unexpected shape")
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+/**
+ * @param {Record<string, unknown>} value
+ * @param {readonly string[]} expected
+ * @returns {boolean}
+ */
+function exactKeys(value, expected) {
+  const actual = Object.keys(value).sort()
+  const wanted = [...expected].sort()
+  return actual.length === wanted.length && actual.every((key, index) => key === wanted[index])
+}