@ai-projector/ide 0.0.0-stage → 0.11.1

package/packages/core/modules/os-posix/agent-process.js

@@ -0,0 +1,105 @@
+import { execFile, spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+/** How long a tree gets to exit on SIGTERM before SIGKILL. */
+const TERM_GRACE_MS = 3000;
+/**
+ * A separate process group per turn (`detached`), so the whole tree — the agent plus everything
+ * its shell started — can be stopped with one signal to the group. The trade-off is that a
+ * Projector crash mid-turn leaves the group orphaned; turns are short-lived, so no accounting yet.
+ */
+export function agentLaunch(spec) {
+    return { command: spec.command, args: spec.args, shell: false };
+}
+export function spawnAgentProcess(spec) {
+    const child = spawn(spec.command, spec.args, {
+        cwd: spec.cwd,
+        env: spec.env,
+        stdio: ["pipe", "pipe", "pipe"],
+        detached: true,
+    });
+    child.terminate = () => terminateTree(child);
+    return child;
+}
+function signalTree(child, signal) {
+    try {
+        if (child.pid)
+            process.kill(-child.pid, signal);
+        else
+            child.kill(signal);
+    }
+    catch {
+        /* The group is already gone. */
+    }
+}
+async function terminateTree(child) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    const closed = new Promise((resolve) => child.once("close", () => resolve()));
+    signalTree(child, "SIGTERM");
+    const timer = setTimeout(() => signalTree(child, "SIGKILL"), TERM_GRACE_MS);
+    timer.unref();
+    await closed;
+    clearTimeout(timer);
+}
+const PATH_MARK = "__PROJECTOR_PATH__";
+let userPath;
+/**
+ * The PATH an interactive terminal would have. The server often starts from a desktop launcher
+ * or a service manager whose PATH lacks what `.bashrc`/`.zshrc` add (`~/.local/bin` and similar),
+ * while terminal sessions run `$SHELL -i -c exec <program>`. The result is cached for the process.
+ */
+function interactiveShellPath() {
+    userPath ??= new Promise((resolve) => {
+        execFile(process.env.SHELL || "/bin/bash", ["-i", "-c", `printf '${PATH_MARK}%s${PATH_MARK}' "$PATH"`], { timeout: 5000, env: process.env }, (error, stdout) => {
+            const match = new RegExp(`${PATH_MARK}(.*)${PATH_MARK}`, "s").exec(String(stdout));
+            resolve(error && !match ? undefined : match?.[1] || undefined);
+        });
+    });
+    return userPath;
+}
+/** `base` with the user's interactive-shell PATH entries added after the server's own. */
+export async function agentEnv(base) {
+    const extra = await interactiveShellPath();
+    if (!extra)
+        return base;
+    const seen = new Set();
+    const merged = [...(base.PATH ?? "").split(":"), ...extra.split(":")].filter((entry) => entry && !seen.has(entry) && !!seen.add(entry));
+    return { ...base, PATH: merged.join(":") };
+}
+/** A unix socket path is limited to about 108 bytes, so a deep data directory falls back to /tmp. */
+export function agentHostAddress(dir) {
+    const path = join(dir, "host.sock");
+    return path.length < 100 ? path : join(tmpdir(), `projector-agent-${basename(dir)}.sock`);
+}
+/**
+ * Starts the script that holds an agent process outside the server's own life: its own session,
+ * no inherited stdio, so a server restart or crash leaves it (and the answer in progress) running.
+ */
+export function spawnAgentHost(spec) {
+    const child = spawn(process.execPath, [spec.script, spec.dir, spec.address], {
+        env: spec.env,
+        stdio: ["ignore", spec.log, spec.log],
+        detached: true,
+    });
+    child.on("error", () => { });
+    child.unref();
+    return child.pid;
+}
+/** Stops a hosted agent and everything it started: SIGTERM to the group, SIGKILL after a grace period. */
+export function killAgentTree(pid) {
+    try {
+        process.kill(-pid, "SIGTERM");
+    }
+    catch {
+        return;
+    }
+    setTimeout(() => {
+        try {
+            process.kill(-pid, "SIGKILL");
+        }
+        catch {
+            /* The group is already gone. */
+        }
+    }, TERM_GRACE_MS).unref();
+}

package/packages/core/modules/os-posix/contract.js

@@ -0,0 +1 @@
+export {};

package/packages/core/modules/os-posix/git.js

@@ -0,0 +1,26 @@
+import { mkdir, rename, rmdir } from "node:fs/promises";
+export function gitAskpass({ username, tokenEnv }) {
+    if (!/^[\w.-]+$/.test(username) || !/^[A-Za-z_]\w*$/.test(tokenEnv))
+        throw new Error("Недопустимые параметры askpass");
+    return {
+        filename: "askpass",
+        contents: `#!/bin/sh\ncase "$1" in *Username*) printf "%s\\n" "${username}" ;; *) printf "%s\\n" "$${tokenEnv}" ;; esac\n`,
+    };
+}
+/** POSIX rename replaces an empty directory, so the destination is claimed with mkdir first. */
+export async function publishDirectory(source, destination) {
+    await mkdir(destination);
+    try {
+        await rename(source, destination);
+    }
+    catch (error) {
+        await rmdir(destination).catch(() => { });
+        throw error;
+    }
+}
+/** The socket lives outside the run directory when the directory is too deep for a socket path. */
+export async function removeAgentHostAddress(dir, address) {
+    const { rm } = await import("node:fs/promises");
+    if (!address.startsWith(dir))
+        await rm(address, { force: true });
+}

package/packages/core/modules/os-posix/index.js

@@ -0,0 +1,4 @@
+export * from "./tools.js";
+export { gitAskpass, publishDirectory, removeAgentHostAddress } from "./git.js";
+export { agentEnv, agentLaunch, agentHostAddress, killAgentTree, spawnAgentHost, spawnAgentProcess, } from "./agent-process.js";
+export { xdgDataHome, configHome } from "./xdg.js";

package/packages/core/modules/os-posix/tools.js

@@ -0,0 +1,258 @@
+import { chmodSync } from "node:fs";
+import { execFile, execFileSync, spawn } from "node:child_process";
+import { promisify } from "node:util";
+const execute = promisify(execFile);
+/** Starts a caller-defined process with the stdio it asked for; no shell unless requested. */
+export function spawnProcess(spec) {
+    return spawn(spec.command, spec.args, {
+        cwd: spec.cwd,
+        env: spec.env,
+        stdio: spec.stdio,
+        shell: spec.shell === true,
+    });
+}
+export function commandExists(bin, env) {
+    try {
+        execFileSync("which", [bin], {
+            stdio: "ignore",
+            env: (env ?? process.env),
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Argument-vector Docker transport; never invoke a shell or inherit a host override. */
+export function runDocker(args, options = {}) {
+    const env = { ...process.env };
+    for (const key of Object.keys(env))
+        if (/^DOCKER_(HOST|CONTEXT|TLS_VERIFY|CERT_PATH|API_VERSION)$/.test(key))
+            delete env[key];
+    if (options.onOutput)
+        return runStreamingProcess("docker", args, {
+            cwd: options.cwd,
+            timeout: options.timeout ?? 15000,
+            signal: options.signal,
+            env,
+            onOutput: options.onOutput,
+        });
+    return execute("docker", args, {
+        cwd: options.cwd,
+        timeout: options.timeout ?? 15000,
+        signal: options.signal,
+        maxBuffer: 4 * 1024 * 1024,
+        env,
+    });
+}
+/** Runs a Node script with this server's Node; no shell, no secrets from the host environment. */
+export function runNodeScript(script, args, options = {}) {
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !/KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL/i.test(key) &&
+        !/^DOCKER_(HOST|CONTEXT|TLS_VERIFY|CERT_PATH|API_VERSION)$/.test(key)));
+    if (options.onOutput)
+        return runStreamingProcess(process.execPath, [script, ...args], {
+            cwd: options.cwd,
+            timeout: options.timeout ?? 30000,
+            signal: options.signal,
+            env,
+            onOutput: options.onOutput,
+        });
+    return execute(process.execPath, [script, ...args], {
+        cwd: options.cwd,
+        timeout: options.timeout ?? 30000,
+        signal: options.signal,
+        maxBuffer: 4 * 1024 * 1024,
+        env,
+    });
+}
+/**
+ * The streaming shape of `execFile`: same `{ stdout, stderr }` result and the same rejection
+ * (`code`, `stdout`, `stderr`) for a failed or timed-out process, but output is also reported as
+ * it arrives. Used for commands whose progress the chat shows live.
+ */
+export function runStreamingProcess(file, args, options = {}) {
+    const limit = options.maxBuffer ?? 4 * 1024 * 1024;
+    return new Promise((resolve, reject) => {
+        if (options.signal?.aborted)
+            return reject(new Error("Запрос остановлен"));
+        const child = spawn(file, args, {
+            cwd: options.cwd,
+            env: options.env ?? process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        const stdout = [];
+        const stderr = [];
+        let bytes = 0;
+        let failure;
+        const stop = (reason) => {
+            failure ??= reason;
+            try {
+                child.kill();
+            }
+            catch {
+                /* Already gone. */
+            }
+        };
+        const capture = (target, chunk, stream) => {
+            const available = limit - bytes;
+            if (available > 0)
+                target.push(chunk.subarray(0, available));
+            bytes += chunk.length;
+            if (bytes > limit) {
+                const error = Object.assign(new Error("Вывод команды превысил лимит"), {
+                    code: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER",
+                });
+                stop(error);
+            }
+            else
+                options.onOutput?.(chunk.toString("utf8"), stream);
+        };
+        child.stdout.on("data", (chunk) => capture(stdout, chunk, "stdout"));
+        child.stderr.on("data", (chunk) => capture(stderr, chunk, "stderr"));
+        const timer = options.timeout === undefined
+            ? undefined
+            : setTimeout(() => {
+                const error = Object.assign(new Error("Команда не завершилась вовремя"), {
+                    killed: true,
+                    code: null,
+                });
+                stop(error);
+            }, options.timeout);
+        const abort = () => {
+            if (options.signal?.aborted)
+                stop(new Error("Запрос остановлен"));
+        };
+        options.signal?.addEventListener("abort", abort, { once: true });
+        const cleanup = () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            options.signal?.removeEventListener("abort", abort);
+        };
+        child.on("error", (error) => {
+            cleanup();
+            reject(error);
+        });
+        child.on("close", (code) => {
+            cleanup();
+            const out = Buffer.concat(stdout).toString("utf8");
+            const err = Buffer.concat(stderr).toString("utf8");
+            if (failure)
+                return reject(Object.assign(failure, {
+                    code: failure.code ?? null,
+                    stdout: out,
+                    stderr: err,
+                }));
+            if (code === 0)
+                return resolve({ stdout: out, stderr: err });
+            reject(Object.assign(new Error(`Command failed: ${file} ${args.join(" ")}`), {
+                code,
+                stdout: out,
+                stderr: err,
+            }));
+        });
+    });
+}
+export function runDockerSync(args) {
+    const env = { ...process.env };
+    for (const key of Object.keys(env))
+        if (/^DOCKER_(HOST|CONTEXT|TLS_VERIFY|CERT_PATH|API_VERSION)$/.test(key))
+            delete env[key];
+    return execFileSync("docker", args, { env, timeout: 5000, stdio: "ignore" });
+}
+export function runBash(command, options) {
+    return new Promise((resolve, reject) => {
+        if (options.signal?.aborted)
+            return reject(new Error("Запрос остановлен"));
+        const child = spawn("/bin/bash", ["--noprofile", "--norc", "-c", command], {
+            cwd: options.cwd,
+            detached: true,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: Object.fromEntries(Object.entries(process.env).filter(([key]) => !/KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL/i.test(key))),
+        });
+        const stdout = [], stderr = [];
+        let bytes = 0, terminated = false;
+        const kill = () => {
+            terminated = true;
+            if (child.pid) {
+                try {
+                    process.kill(-child.pid, "SIGKILL");
+                }
+                catch {
+                    /* Already exited. */
+                }
+            }
+        };
+        const capture = (target, chunk) => {
+            const available = 256 * 1024 - bytes;
+            if (available > 0)
+                target.push(chunk.subarray(0, available));
+            bytes += chunk.length;
+            if (bytes > 256 * 1024)
+                kill();
+        };
+        child.stdout.on("data", (chunk) => {
+            capture(stdout, chunk);
+            options.onOutput?.(chunk.toString("utf8"), "stdout");
+        });
+        child.stderr.on("data", (chunk) => {
+            capture(stderr, chunk);
+            options.onOutput?.(chunk.toString("utf8"), "stderr");
+        });
+        const timer = setTimeout(kill, 30000);
+        options.signal?.addEventListener("abort", kill, { once: true });
+        const cleanup = () => {
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", kill);
+        };
+        child.on("error", (error) => {
+            cleanup();
+            reject(error);
+        });
+        child.on("close", (exitCode) => {
+            cleanup();
+            // Background descendants must not outlive an agent tool call.
+            if (child.pid) {
+                try {
+                    process.kill(-child.pid, "SIGKILL");
+                }
+                catch {
+                    /* Already exited. */
+                }
+            }
+            if (options.signal?.aborted)
+                return reject(new Error("Запрос остановлен"));
+            resolve({
+                stdout: Buffer.concat(stdout).toString("utf8"),
+                stderr: Buffer.concat(stderr).toString("utf8"),
+                exitCode,
+                terminated,
+            });
+        });
+    });
+}
+export function runPython(helper, args, options) {
+    return execute("python3", ["-I", helper, ...args], {
+        ...options,
+        env: { ...process.env, PYTHONNOUSERSITE: "1" },
+    });
+}
+export function searchFiles(args, options) {
+    return execute("rg", args, options);
+}
+/** POSIX resolves a bare name itself. */
+export function ptyCommand(file, args) {
+    return { file, args };
+}
+/** POSIX: any execute bit. */
+export function isExecutableFile(_name, mode) {
+    return !!(mode & 0o111);
+}
+/** 0600: readable and writable by the owner only. */
+export async function restrictToOwner(path) {
+    const { chmod } = await import("node:fs/promises");
+    await chmod(path, 0o600);
+}
+export function restrictToOwnerSync(path) {
+    chmodSync(path, 0o600);
+}

package/packages/core/modules/os-posix/xdg.js

@@ -0,0 +1,8 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function xdgDataHome() {
+    return process.env.XDG_DATA_HOME || join(homedir(), ".local/share");
+}
+export function configHome() {
+    return process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+}

package/packages/core/modules/project/contract.js

@@ -0,0 +1 @@
+export {};

package/packages/core/modules/project/index.js

@@ -0,0 +1 @@
+export { parseProjectRef, formatProjectRef, projectRefSegments, normalizeGithubRepository, isAbsoluteLocalPath, pathToUrlSegments, pathFromUrlSegments, } from "./ref.js";

package/packages/core/modules/project/ref.js

@@ -0,0 +1,126 @@
+import { GITLAB_PREFIX } from "../gitlab/index.js";
+const GITHUB_PREFIX = "gh:/";
+const REPOSITORY = /^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9_.-]+$/;
+/** Accepts `owner/repo`, `https://github.com/owner/repo[.git]`; throws on anything else. */
+export function normalizeGithubRepository(value) {
+    const name = value
+        .trim()
+        .replace(/^https:\/\/github\.com\//, "")
+        .replace(/\/$/, "")
+        .replace(/\.git$/, "");
+    if (!REPOSITORY.test(name) || [".", ".."].includes(name.split("/")[1]))
+        throw new Error("Укажите owner/repository");
+    return name;
+}
+export function parseProjectRef(path) {
+    if (path.startsWith(GITLAB_PREFIX)) {
+        const rest = path.slice(GITLAB_PREFIX.length);
+        const slash = rest.indexOf("/");
+        return slash < 0
+            ? { kind: "gitlab", instance: rest, path: "" }
+            : {
+                kind: "gitlab",
+                instance: rest.slice(0, slash),
+                path: rest.slice(slash + 1),
+            };
+    }
+    if (path.startsWith(GITHUB_PREFIX))
+        return { kind: "github", repository: path.slice(GITHUB_PREFIX.length) };
+    return { kind: "local", path };
+}
+/** Stable text form: also the project id inside the workspace. */
+export function formatProjectRef(ref) {
+    if (ref.kind === "github")
+        return `${GITHUB_PREFIX}${ref.repository}`;
+    if (ref.kind === "gitlab")
+        return `${GITLAB_PREFIX}${ref.instance}/${ref.path}`;
+    return ref.path;
+}
+const DRIVE = /^[A-Za-z]:$/;
+const UNC_SEGMENT = "unc:";
+/** Local absolute path: POSIX, a Windows drive, or a UNC share. */
+export function isAbsoluteLocalPath(path) {
+    return path.startsWith("/") || path.startsWith("\\\\") || /^[A-Za-z]:[\\/]/.test(path);
+}
+function isWindowsPath(path) {
+    return path.startsWith("\\\\") || /^[A-Za-z]:(?:[\\/]|$)/.test(path);
+}
+/**
+ * One URL segment per directory. Windows separators become `/`, so
+ * `C:\Users\repo` is `C:/Users/repo`. A UNC path starts with the `unc:` segment.
+ */
+export function pathToUrlSegments(path) {
+    if (!isWindowsPath(path))
+        return path === "/" ? [] : path.split("/").filter(Boolean);
+    const posix = path.replaceAll("\\", "/");
+    if (posix.startsWith("//"))
+        return [UNC_SEGMENT, ...posix.slice(2).split("/").filter(Boolean)];
+    return posix.split("/").filter(Boolean);
+}
+/** Inverse of {@link pathToUrlSegments}. Drive and UNC paths use Windows separators. */
+export function pathFromUrlSegments(segments) {
+    const parts = segments.flatMap((part) => part.split("/")).filter(Boolean);
+    const legacy = parts.length === 1 && parts[0]?.includes("\\") ? parts[0].split("\\").filter(Boolean) : parts;
+    const unc = parts[0] === UNC_SEGMENT || (parts.length === 1 && parts[0]?.startsWith("\\\\"));
+    if (unc) {
+        const rest = parts[0] === UNC_SEGMENT ? parts.slice(1) : legacy;
+        return `\\\\${rest.join("\\")}`;
+    }
+    if (DRIVE.test(legacy[0] ?? "")) {
+        const [root, ...rest] = legacy;
+        return rest.length ? `${root}\\${rest.join("\\")}` : `${root}\\`;
+    }
+    return `/${parts.join("/")}`;
+}
+function localPathSegments(filePath) {
+    const segments = pathToUrlSegments(filePath);
+    if (segments[0] === UNC_SEGMENT) {
+        const parts = segments.slice(1);
+        return parts.map((name, i) => ({
+            name,
+            path: `\\\\${parts.slice(0, i + 1).join("\\")}`,
+        }));
+    }
+    if (DRIVE.test(segments[0] ?? "")) {
+        const [drive, ...parts] = segments;
+        return [
+            { name: drive, path: `${drive}\\` },
+            ...parts.map((name, i) => ({
+                name,
+                path: `${drive}\\${parts.slice(0, i + 1).join("\\")}`,
+            })),
+        ];
+    }
+    return [
+        { name: "/", path: "/" },
+        ...segments.map((name, i) => ({
+            name,
+            path: `/${segments.slice(0, i + 1).join("/")}`,
+        })),
+    ];
+}
+export function projectRefSegments(ref) {
+    if (ref.kind === "gitlab") {
+        const parts = ref.path.split("/").filter(Boolean);
+        const authority = `${GITLAB_PREFIX}${ref.instance}`;
+        return [
+            { name: GITLAB_PREFIX, path: GITLAB_PREFIX },
+            ...(ref.instance ? [{ name: ref.instance, path: authority }] : []),
+            ...parts.map((name, i) => ({
+                name,
+                path: `${authority}/${parts.slice(0, i + 1).join("/")}`,
+            })),
+        ];
+    }
+    if (ref.kind === "github") {
+        const parts = ref.repository.split("/").filter(Boolean);
+        return [
+            { name: GITHUB_PREFIX, path: GITHUB_PREFIX },
+            ...parts.map((name, i) => ({
+                name,
+                path: `${GITHUB_PREFIX}${parts.slice(0, i + 1).join("/")}`,
+            })),
+        ];
+    }
+    return localPathSegments(ref.path);
+}

package/packages/core/modules/server-mode/index.js

@@ -0,0 +1,3 @@
+export { SERVER_MODES } from "./server-mode.js";
+export { isServerMode } from "./server-mode.js";
+export { serverCommand } from "./server-mode.js";

package/packages/core/modules/server-mode/server-mode.js

@@ -0,0 +1,13 @@
+export const SERVER_MODES = ["dev", "prod"];
+export function isServerMode(value) {
+    return value === "dev" || value === "prod";
+}
+/** Команда запуска сервера: dev — `vp dev`, prod — Node без `vp`. */
+export function serverCommand(mode, options) {
+    if (mode === "prod")
+        return {
+            command: options.node,
+            args: [`${options.root}/packages/server/app/standalone.${options.compiled ? "js" : "ts"}`],
+        };
+    return { command: options.vp, args: ["dev"] };
+}

package/packages/core/modules/terminal/contract.js

@@ -0,0 +1 @@
+export {};

package/packages/core/modules/terminal/index.js

@@ -0,0 +1 @@
+export {};

package/packages/core/modules/usage-analytics/index.js

@@ -0,0 +1,80 @@
+/**
+ * What the agent chats spent and how fast the subscription limits fill up. The server collects
+ * the numbers; this module keeps the shared contract and the pace rules that both the status bar
+ * and the analytics page use, so one limit cannot be judged two different ways.
+ */
+/** Ranges the analytics page offers, in days. */
+export const ANALYTICS_RANGES = [7, 30, 90];
+/** `input` counts the prompt tokens the cache did not serve, as in the usage tooltip of the chat. */
+export function modelTokens(usage) {
+    const details = usage?.inputTokenDetails;
+    const cacheRead = details?.cacheReadTokens ?? 0;
+    const cacheWrite = details?.cacheWriteTokens ?? 0;
+    const prompt = usage?.inputTokens ?? 0;
+    return {
+        input: details?.noCacheTokens ?? Math.max(0, prompt - cacheRead - cacheWrite),
+        output: usage?.outputTokens ?? 0,
+        cacheRead,
+        cacheWrite,
+    };
+}
+/** The cost of the tokens at the model's price, in the currency of its tariff. */
+export function modelCost(tokens, price) {
+    return ((tokens.input * price.input +
+        tokens.cacheRead * (price.cacheRead ?? price.input) +
+        tokens.cacheWrite * (price.cacheWrite ?? price.input) +
+        tokens.output * price.output) /
+        1_000_000);
+}
+/** Full cycle lengths: pace compares spent % to elapsed fraction of this maximum. */
+export const USAGE_PERIOD_SECONDS = {
+    hours5: 5 * 3600,
+    week: 7 * 86400,
+    month: 30 * 86400,
+    rolling: 5 * 3600,
+    weekly: 7 * 86400,
+    monthly: 30 * 86400,
+};
+/** Cycle length of a window name; adapters that expose other windows get no pace estimate. */
+export function limitPeriodSeconds(window) {
+    if (window === "rolling")
+        return USAGE_PERIOD_SECONDS.rolling;
+    if (window === "weekly")
+        return USAGE_PERIOD_SECONDS.weekly;
+    if (window === "monthly")
+        return USAGE_PERIOD_SECONDS.monthly;
+    return null;
+}
+/**
+ * Pace of limit spend vs time left until reset.
+ * `periodSeconds` is the maximum time-to-reset at cycle start (week/month/5h).
+ * Weekly and monthly windows are judged on a day-scale period; rolling uses hours.
+ */
+export function usagePaceTone(usedPercent, resetsAt, periodSeconds, now = Date.now(), limited = false) {
+    if (!Number.isFinite(usedPercent) || usedPercent < 0)
+        return null;
+    if (!Number.isFinite(periodSeconds) || (periodSeconds ?? 0) <= 0)
+        return null;
+    if (limited || usedPercent >= 100)
+        return "over";
+    if (!resetsAt || !Number.isFinite(resetsAt))
+        return null;
+    const remainingSeconds = Math.max(0, resetsAt - now / 1000);
+    const remainingFraction = Math.min(1, remainingSeconds / periodSeconds);
+    const expectedUsed = (1 - remainingFraction) * 100;
+    const delta = usedPercent - expectedUsed;
+    if (delta <= -15)
+        return "spare";
+    if (delta <= 8)
+        return "normal";
+    if (delta <= 22)
+        return "hot";
+    return "over";
+}
+/** Expected spend by now, from the window length and its reset time. */
+export function expectedUsagePercent(periodSeconds, resetsAt, now = Date.now()) {
+    if (!periodSeconds || !resetsAt)
+        return null;
+    const remainingSeconds = Math.max(0, resetsAt - now / 1000);
+    return Math.min(100, Math.max(0, (1 - remainingSeconds / periodSeconds) * 100));
+}