@clawdbuilder/jig-bedrock 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Jig contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,125 @@
-# Temporary Holding Version
+# jig-bedrock: Claude on AWS Bedrock for Pi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Pi provider for Claude on AWS Bedrock. It finds the application inference profiles your account can use, keeps the
+Anthropic Messages route (where the prompt cache survives tool changes), and falls back to Converse per model.
+
+## The gap it fills
+
+Pi's built-in Bedrock provider uses Converse only, has a fixed model list and no profile discovery, SSO repair or budget
+footer. This package adds the Messages route with SigV4, discovery by an AWS tag, repair through `aws sso login`, and an
+optional spend line. It works in plain Pi; when [Jig](https://github.com/ClawdBuilder/jig) is installed it also uses Jig's
+records and footer, but Jig is not required.
+
+## Install
+
+```sh
+pi install npm:@clawdbuilder/jig-bedrock
+```
+
+Requirements: Node 22.19 or later, Pi 1.5 or later, AWS CLI v2, and an AWS profile whose SSO session the CLI can refresh.
+Linux, WSL2 and macOS are supported; Windows is not.
+
+## Minimum settings
+
+Add a `bedrock` section to `jig.json` (or the same keys through the environment):
+
+```json
+{ "bedrock": { "team": "my-team" } }
+```
+
+`team` is the value of the AWS tag on your inference profiles. The package discovers active profiles with that value.
+
+| Setting                           | Default                                         | Meaning                                                                                            |
+| --------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `team`                            | required                                        | The exact AWS tag value on your application inference profiles                                     |
+| `tagKey`                          | `Team`                                          | The AWS tag that names your team on the inference profiles                                         |
+| `tagValue`                        | the value of `team`                             | The tag value to discover; `team` is kept for compatibility                                        |
+| `activeTagKey` / `activeTagValue` | `Active` / `true`                               | The tag that marks a profile as usable                                                             |
+| `profile`                         | `my-bedrock-profile`                            | The AWS profile for discovery, requests and sign-in                                                |
+| `regions`                         | `["us-east-1"]`                                 | Where to look for profiles                                                                         |
+| `usageDir`                        | `~/.local/share/usage-tool`                     | Optional directory holding an executable `usage` that prints the usage JSON; omit if you have none |
+| `monthlyBudgetUsd`                | none                                            | A figure for the footer, not an AWS limit                                                          |
+| `ssoLoginCommand`                 | `["aws","sso","login","--profile","{profile}"]` | The owning tool starts the sign-in; this package never handles a password or token                 |
+| `signInAtStart`                   | `true`                                          | Refresh an expired SSO session when Pi starts                                                      |
+| `browser`                         | WSL's Windows browser                           | Program that opens the sign-in address                                                             |
+| `api`                             | `messages`                                      | `messages` (cache-friendly) or `converse`                                                          |
+
+Plain Pi reads the same keys from `~/.pi/agent/bedrock.json` (or a `bedrock` object in it). With Jig, that file is read
+first and Jig's `bedrock` section is merged on top; Jig must load before the provider, as in Jig's normal order. A project's `jig.json` may set
+the catalog keys, but `ssoLoginCommand`, `usageDir` and `browser` are ignored there: programs run only from the user's file or the
+environment.
+
+Environment: `JIG_BEDROCK_TEAM`, `JIG_BEDROCK_PROFILE`, `JIG_BEDROCK_REGIONS`, `JIG_BEDROCK_USAGE_DIR`,
+`JIG_BEDROCK_TAG_KEY`, `JIG_BEDROCK_TAG_VALUE`. `PI_HOST_DIR` points at the Pi install when it is not beside `node`.
+`PI_CACHE_RETENTION` sets Pi's own cache retention; the provider does not change it.
+
+## Commands
+
+| Command                   | What it does                                                                       |
+| ------------------------- | ---------------------------------------------------------------------------------- |
+| `/bedrock-refresh`        | Refresh the discovered profiles                                                    |
+| `/bedrock-usage [period]` | Show the usage program's daily, weekly or monthly figures                          |
+| `/bedrock-stats`          | Show the same cached figures as a short line                                       |
+| `/bedrock-profiles`       | List the discovered profiles and why any are unavailable                           |
+| `/aws-login`              | Start the owning AWS CLI's `sso login` for the configured profile                  |
+| `/bedrock-doctor`         | Probe Node, AWS CLI, bash, jq and the optional usage program; it does not call AWS |
+
+The footer shows the month's spend when a usage program and budget are configured. That program is an executable named
+`usage` in `usageDir`; it is called as `usage --daily|--weekly|--monthly --output json` with `AWS_PROFILE` set, and it must
+print one JSON object:
+
+```json
+{
+    "schema_version": 1,
+    "command": "usage",
+    "user": "me",
+    "period": "Current Month",
+    "summary": {
+        "total_requests": 2,
+        "total_input_tokens_fresh": 100,
+        "total_cache_read_tokens": 20,
+        "total_cache_write_tokens": 10,
+        "total_input_tokens": 130,
+        "total_output_tokens": 40,
+        "total_estimated_cost_usd": 0.42
+    },
+    "profiles": [
+        {
+            "model_slug": "claude-sonnet-5-5",
+            "profile_name": "my-profile",
+            "requests": 2,
+            "input_tokens_fresh": 100,
+            "cache_read_tokens": 20,
+            "cache_write_tokens": 10,
+            "total_input_tokens": 130,
+            "output_tokens": 40,
+            "estimated_cost_usd": 0.42
+        }
+    ]
+}
+```
+
+The 2.x shape may omit `schema_version`/`command` and each row's `user`; extra keys are ignored. A missing or unpriced row
+leaves the spend unknown, not zero.
+
+## Cache
+
+On the Messages route, the tools array stays stable and the prompt cache survives a tool change. On Converse, a changed
+tool list rewrites the cache; choose `api: "converse"` only for a model that needs it.
+
+## Tests
+
+```sh
+npm test
+npm run check
+npm run scan
+```
+
+WSL uses `bin/windows-browser` when `browser` is unset, so the sign-in opens on Windows.
+
+The real-AWS tests are manual: they cost money and need the user's approval. Unit tests use recorded AWS shapes and a fake
+CLI.
+
+## Licence
+
+MIT.

package/bin/windows-browser

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Opens the address in $1 in the Windows default browser, from WSL. jig-bedrock gives this to `aws sso login` as its BROWSER when
+# Pi runs under WSL and nobody set one (src/wsl.ts). rundll32 passes the whole address on, `&` included; cmd.exe would split it there.
+exec /mnt/c/Windows/System32/rundll32.exe url.dll,FileProtocolHandler "$1"

package/index.ts

@@ -0,0 +1,3 @@
+// The provider's extension entry, the second of the two in package.json's `pi.extensions`. It sits at bedrock/ so Pi loads the
+// folder as its own extension, and the rest of the provider stays under bedrock/ with it. The code is in src/.
+export { default } from "./src/index.ts";

package/package.json

@@ -1,6 +1,52 @@
 {
-  "name": "@clawdbuilder/jig-bedrock",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@clawdbuilder/jig-bedrock",
+    "version": "0.1.0",
+    "description": "Claude on AWS Bedrock for Pi: inference-profile discovery, the Messages route with cache-friendly tools, Converse fallback, SSO repair and a budget footer.",
+    "type": "module",
+    "license": "MIT",
+    "keywords": [
+        "pi-package",
+        "pi",
+        "bedrock",
+        "aws",
+        "claude",
+        "anthropic"
+    ],
+    "files": [
+        "index.ts",
+        "src/**",
+        "bin/**",
+        "README.md",
+        "LICENSE"
+    ],
+    "pi": {
+        "extensions": [
+            "index.ts"
+        ]
+    },
+    "scripts": {
+        "check": "tsc -p tsconfig.json && biome ci .",
+        "test": "node --import ./test/support/host.mjs --test \"test/*.test.ts\"",
+        "scan": "node scripts/scan-company-strings.mjs"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "2.6.4",
+        "@types/node": "26.6.6",
+        "typescript": "7.0.2",
+        "@earendil-works/pi-ai": "1.5.0",
+        "@earendil-works/pi-coding-agent": "1.5.0"
+    },
+    "publishConfig": {
+        "provenance": true,
+        "access": "public"
+    },
+    "repository": "git+https://github.com/ClawdBuilder/jig-bedrock.git",
+    "homepage": "https://github.com/ClawdBuilder/jig-bedrock#readme",
+    "engines": {
+        "node": ">=22.19.0"
+    },
+    "peerDependencies": {
+        "@earendil-works/pi-ai": "1.5.0",
+        "@earendil-works/pi-coding-agent": "1.5.0"
+    }
+}

package/src/aws-discovery.ts

@@ -0,0 +1,226 @@
+import { execFile } from "node:child_process";
+import { rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { atomicCache } from "./cache.ts";
+import { type Catalog, type Profile, readCatalog, validArn } from "./catalog.ts";
+import type { ResolvedConfig } from "./config.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: parsed JSON from the AWS CLI or usage program, checked field by field where it is used
+type Json = any;
+export type Status =
+    | "ok"
+    | "sso_expired"
+    | "permission_denied"
+    | "configuration"
+    | "network"
+    | "timeout"
+    | "unavailable";
+export interface CatalogSource {
+    load(): Catalog | undefined;
+    refresh(force?: boolean): Promise<Status>;
+}
+export type Runner = (
+    program: string,
+    args: string[],
+    options: { timeout: number; maxBuffer: number },
+) => Promise<string>;
+export const runFile: Runner = (program, args, options) =>
+    new Promise((resolve, reject) => {
+        execFile(
+            program,
+            args,
+            { ...options, encoding: "utf8", env: { ...process.env, AWS_CLI_AUTO_PROMPT: "off", AWS_PAGER: "" } },
+            (error, stdout, stderr) =>
+                error ? reject(new Error(error.killed ? "timeout" : stderr || error.message)) : resolve(stdout),
+        );
+    });
+export function category(error: unknown): Status {
+    const m = String(error).toLowerCase();
+    return /access.?denied|not authorized to perform|unauthorizedoperation/.test(m)
+        ? "permission_denied"
+        : /could not be found|config profile|profile.*not found|missing.*(?:sso|region)|enoent/.test(m)
+          ? "configuration"
+          : /sso|token/.test(m) && /expired|invalid|login|unauthorized|does not exist/.test(m)
+            ? "sso_expired"
+            : /timeout|timed out/.test(m)
+              ? "timeout"
+              : /network|connect|dns|resolve|unreachable|proxy/.test(m)
+                ? "network"
+                : "unavailable";
+}
+export function discoveryHelp(status: Status): string {
+    switch (status) {
+        case "sso_expired":
+            return "Run /aws-login, finish browser sign-in, then /bedrock-refresh.";
+        case "permission_denied":
+            return "Ask your AWS administrator to check catalog read permissions for the configured profile; then /bedrock-refresh.";
+        case "configuration":
+            return "Check AWS CLI v2 on PATH and the configured AWS profile and regions; then /bedrock-refresh.";
+        case "network":
+            return "Check network access to AWS, then /bedrock-refresh.";
+        case "timeout":
+            return "AWS discovery timed out; check network access, then /bedrock-refresh.";
+        default:
+            return "Check AWS access and the configuration in README.md, then /bedrock-refresh.";
+    }
+}
+export function createAwsDiscovery(
+    config: ResolvedConfig,
+    runner: Runner = runFile,
+    file = join(homedir(), ".cache/jig-bedrock/catalog.json"),
+    now = Date.now,
+): CatalogSource {
+    let flight: Promise<Status> | undefined,
+        invalidAccount = false;
+    const load = () => (invalidAccount ? undefined : readCatalog(file, config, now()));
+    const perform = async (force = false): Promise<Status> => {
+        let remaining = 8 * 1_048_576,
+            pages = 0,
+            deadline = now() + 90_000;
+        const aws = async (args: string[]) => {
+            const timeout = Math.min(20_000, deadline - now());
+            if (timeout <= 0) throw new Error("timeout");
+            const output = await runner(
+                "aws",
+                [...args, "--profile", config.profile, "--output", "json", "--no-cli-pager"],
+                { timeout, maxBuffer: Math.min(remaining, 1_048_576) },
+            );
+            remaining -= Buffer.byteLength(output);
+            if (remaining < 0 || Buffer.byteLength(output) > 1_048_576) throw new Error("byte limit");
+            if (now() > deadline) throw new Error("timeout");
+            return JSON.parse(output);
+        };
+        try {
+            // A catalog younger than the TTL needs no AWS call at all, not even to learn who the caller is; /bedrock-refresh forces one.
+            if (!force && !invalidAccount) {
+                const cached = readCatalog(file, config, now());
+                if (cached && now() / 1000 - cached.fetched_at < 86_400) return "ok";
+            }
+            const account = (await aws(["sts", "get-caller-identity"])).Account;
+            if (typeof account !== "string" || !/^\d{12}$/.test(account)) throw new Error("identity");
+            const old = readCatalog(file, config, now());
+            if (old && old.account_id !== account) {
+                invalidAccount = true;
+                rmSync(file, { force: true });
+            } else invalidAccount = false;
+            const profiles: Profile[] = [],
+                seen = new Set<string>();
+            const info = (arn: string, region: string) =>
+                aws(["bedrock", "get-inference-profile", "--inference-profile-identifier", arn, "--region", region]);
+            const foundation = async (value: Json, depth = 0): Promise<string> => {
+                if (!Array.isArray(value.models) || !value.models.length || value.models.length > 32)
+                    throw new Error("models");
+                const ids = new Set<string>();
+                for (const row of value.models) {
+                    const match =
+                        typeof row.modelArn === "string" &&
+                        row.modelArn.match(/^arn:(aws|aws-cn|aws-us-gov):bedrock:([^:]+):([^:]*):(.+)$/);
+                    if (!match) throw new Error("model ARN");
+                    const resource = match[4];
+                    if (resource.startsWith("foundation-model/")) {
+                        const id = resource.slice(17);
+                        // biome-ignore lint/suspicious/noControlCharactersInRegex: reject control characters in an AWS model id
+                        if (!id || id.length > 256 || /[\x00-\x1f]/.test(id)) throw new Error("model ID");
+                        ids.add(id);
+                    } else if (
+                        resource.startsWith("inference-profile/") &&
+                        depth < 2 &&
+                        (!match[3] || match[3] === account)
+                    )
+                        ids.add(await foundation(await info(row.modelArn, match[2]), depth + 1));
+                    else throw new Error("model scope");
+                }
+                if (ids.size !== 1) throw new Error("ambiguous model");
+                return [...ids][0] as string;
+            };
+            for (const region of config.regions) {
+                let token = "";
+                const tokens = new Set<string>();
+                for (let page = 0; page < 32; page++) {
+                    if (++pages > 64) throw new Error("pagination");
+                    const result = await aws([
+                        "resourcegroupstaggingapi",
+                        "get-resources",
+                        "--region",
+                        region,
+                        "--resource-type-filters",
+                        "bedrock:application-inference-profile",
+                        "--tag-filters",
+                        JSON.stringify([
+                            { Key: config.tagKey ?? "Team", Values: [config.tagValue ?? config.team] },
+                            { Key: config.activeTagKey ?? "Active", Values: [config.activeTagValue ?? "true"] },
+                        ]),
+                        "--no-paginate",
+                        ...(token ? ["--pagination-token", token] : []),
+                    ]);
+                    if (!Array.isArray(result.ResourceTagMappingList) || result.ResourceTagMappingList.length > 256)
+                        throw new Error("resources");
+                    for (const row of result.ResourceTagMappingList) {
+                        const arn = row.ResourceARN;
+                        if (
+                            typeof arn !== "string" ||
+                            !validArn(arn, region, account) ||
+                            seen.has(arn) ||
+                            seen.size >= 256
+                        )
+                            throw new Error("profile scope");
+                        if (
+                            !Array.isArray(row.Tags) ||
+                            ![
+                                [config.tagKey ?? "Team", config.tagValue ?? config.team],
+                                [config.activeTagKey ?? "Active", config.activeTagValue ?? "true"],
+                            ].every(
+                                ([key, value]) =>
+                                    row.Tags.filter((tag: Json) => tag?.Key === key).length === 1 &&
+                                    row.Tags.some((tag: Json) => tag?.Key === key && tag.Value === value),
+                            )
+                        )
+                            throw new Error("profile tags");
+                        seen.add(arn);
+                        const value = await info(arn, region);
+                        if (value.inferenceProfileArn !== undefined && value.inferenceProfileArn !== arn)
+                            throw new Error("profile mismatch");
+                        if (value.status !== "ACTIVE") continue;
+                        const name = value.inferenceProfileName;
+                        // biome-ignore lint/suspicious/noControlCharactersInRegex: reject control characters in an AWS profile name
+                        if (typeof name !== "string" || !name || name.length > 256 || /[\x00-\x1f\x7f]/.test(name))
+                            throw new Error("profile name");
+                        profiles.push({
+                            arn,
+                            profile_name: name,
+                            foundation_model_id: await foundation(value),
+                            region,
+                        });
+                    }
+                    token = result.PaginationToken ?? "";
+                    if (!token) break;
+                    if (typeof token !== "string" || token.length > 2048 || tokens.has(token) || page === 31)
+                        throw new Error("pagination");
+                    tokens.add(token);
+                }
+            }
+            profiles.sort((a, b) => (a.arn < b.arn ? -1 : a.arn > b.arn ? 1 : 0));
+            atomicCache(file, {
+                schema: 1,
+                team: config.team,
+                aws_profile: config.profile,
+                account_id: account,
+                regions: config.regions,
+                fetched_at: Math.floor(now() / 1000),
+                profiles,
+            });
+            invalidAccount = false;
+            return "ok";
+        } catch (e) {
+            return category(e);
+        }
+    };
+    return {
+        load,
+        refresh: (force = false) =>
+            (flight ??= perform(force).finally(() => {
+                flight = undefined;
+            })),
+    };
+}

package/src/bedrock-fetch.ts

@@ -0,0 +1,77 @@
+// A fetch for Pi's Anthropic Messages client that signs every request with the configured AWS profile's SSO credentials. The
+// provider's route is Bedrock's Anthropic endpoint, which authenticates with SigV4 and not with an Anthropic key, so the client's
+// own auth headers are removed before signing. Credentials stay in the credential chain's memory and are never written by this
+// module.
+import type { AwsCredentials } from "./sigv4.ts";
+import { signRequest } from "./sigv4.ts";
+
+/** The region in a Bedrock runtime host, or undefined when the URL is not one. */
+export function regionOf(url: string): string | undefined {
+    return /^bedrock-runtime(?:-fips)?\.([a-z0-9-]+)\.amazonaws\.com(?:\.cn)?$/.exec(new URL(url).host)?.[1];
+}
+
+/** A body this signer can hash as one buffer: what the Anthropic SDK sends for a JSON request. */
+function bodyOf(body: RequestInit["body"]): string | Uint8Array {
+    if (body === undefined || body === null) return "";
+    if (typeof body === "string") return body;
+    if (body instanceof Uint8Array) return body;
+    if (body instanceof ArrayBuffer) return new Uint8Array(body);
+    throw new Error("Bedrock signing needs the whole request body, not a stream");
+}
+
+export interface SignedFetchOptions {
+    /** Resolves the profile's credentials; the AWS SDK's default provider in production. */
+    credentials: () => Promise<AwsCredentials>;
+    /** The fetch requests go through, so a test can watch them. */
+    fetch?: typeof globalThis.fetch;
+    now?: () => Date;
+    /** A credential failure that means the SSO session must be restored: the message has to reach Pi in one piece. */
+    signInHint?: string;
+}
+
+const SSO_FAILURE = /aws sso login|sso session|token is expired|expired or is otherwise invalid/i;
+
+/** `fetch` with the SigV4 headers of the profile's credentials, and without the client's own auth headers. */
+export function createSignedFetch(options: SignedFetchOptions): typeof globalThis.fetch {
+    const inner = options.fetch ?? globalThis.fetch;
+    const now = options.now ?? (() => new Date());
+    return async (input, init) => {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+        const method = init?.method ?? (typeof input === "string" || input instanceof URL ? "GET" : input.method);
+        const region = regionOf(url);
+        if (region === undefined) throw new Error(`Not a Bedrock runtime URL: ${new URL(url).host}`);
+
+        const headers = new Headers(init?.headers);
+        // The Anthropic SDK always sends one of these because it is constructed with a key; neither may reach Bedrock.
+        headers.delete("x-api-key");
+        headers.delete("authorization");
+        const given: Record<string, string> = {};
+        headers.forEach((value, name) => {
+            given[name] = value;
+        });
+
+        let credentials: AwsCredentials;
+        try {
+            credentials = await options.credentials();
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (SSO_FAILURE.test(message)) {
+                throw new Error(
+                    `SSO session for the configured AWS profile is expired or invalid; run aws sso login with the configured profile. ${message}`,
+                );
+            }
+            throw error;
+        }
+        const signed = signRequest({
+            method,
+            url,
+            headers: given,
+            body: bodyOf(init?.body),
+            region,
+            credentials,
+            now: now(),
+        });
+        for (const [name, value] of Object.entries(signed)) headers.set(name, value);
+        return inner(url, { ...init, headers });
+    };
+}

package/src/budget.ts

@@ -0,0 +1,129 @@
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { atomicCache } from "./cache.ts";
+import { boundedRegular } from "./catalog.ts";
+import type { ResolvedConfig } from "./config.ts";
+import { createStatistics, parseUsage, pricedSpend, type StatisticsSource } from "./statistics.ts";
+import { runUsage, type UsageRunner } from "./usage.ts";
+/** spentUsd sums the priced rows; unpriced says some usage had no price, so the real spend is higher. */
+export interface Budget {
+    monthUtc: string;
+    spentUsd: number;
+    unpriced: boolean;
+    limitUsd?: number;
+    remainingUsd?: number;
+    observedAt: number;
+    refreshFailed: boolean;
+}
+export interface BudgetSource {
+    load(): Budget | undefined;
+    refresh(options?: { force?: boolean; signal?: AbortSignal }): Promise<void>;
+}
+export function parseBudget(output: string, monthUtc: string, observedAt: number, limitUsd?: number): Budget {
+    if (new Date(observedAt).toISOString().slice(0, 7) !== monthUtc)
+        throw new Error("usage program monthly result unavailable");
+    const { spentUsd, unpriced } = pricedSpend(parseUsage(output, "monthly"));
+    return {
+        monthUtc,
+        spentUsd,
+        unpriced,
+        observedAt,
+        refreshFailed: false,
+        ...(limitUsd === undefined ? {} : { limitUsd, remainingUsd: limitUsd - spentUsd }),
+    };
+}
+export function createBudget(
+    config: ResolvedConfig,
+    runner: UsageRunner = runUsage,
+    file = join(homedir(), ".cache/jig-bedrock/budget.json"),
+    now = Date.now,
+    statistics: StatisticsSource = createStatistics(config, runner, dirname(file), now),
+): BudgetSource {
+    const scope = JSON.stringify({
+        profile: config.profile,
+        team: config.team,
+        regions: [...config.regions].sort(),
+        usageDir: config.usageDir,
+    });
+    let flight: Promise<void> | undefined,
+        lastAttempt = -Infinity;
+    const raw = () => {
+        try {
+            return JSON.parse(boundedRegular(file, 32768, true) || "{}");
+        } catch {
+            return {};
+        }
+    };
+    const load = (): Budget | undefined => {
+        const c = raw();
+        if (
+            c.schema !== 1 ||
+            c.profile !== config.profile ||
+            c.scope !== scope ||
+            c.monthUtc !== new Date(now()).toISOString().slice(0, 7) ||
+            !Number.isFinite(c.spentUsd) ||
+            c.spentUsd < 0 ||
+            !Number.isSafeInteger(c.observedAt) ||
+            c.observedAt < 0 ||
+            c.observedAt > now()
+        )
+            return;
+        return {
+            monthUtc: c.monthUtc,
+            spentUsd: c.spentUsd,
+            unpriced: c.unpriced === true,
+            observedAt: c.observedAt,
+            refreshFailed: c.refreshFailed === true,
+            ...(config.monthlyBudgetUsd === undefined
+                ? {}
+                : { limitUsd: config.monthlyBudgetUsd, remainingUsd: config.monthlyBudgetUsd - c.spentUsd }),
+        };
+    };
+    const fromSnapshot = (snapshot: ReturnType<StatisticsSource["load"]>) =>
+        snapshot && { ...pricedSpend(snapshot.report), observedAt: snapshot.observedAt };
+    const perform = async (options: { force?: boolean; signal?: AbortSignal } = {}) => {
+        const old = raw(),
+            started = now(),
+            monthUtc = new Date(started).toISOString().slice(0, 7);
+        if (
+            !options.force &&
+            started - Math.max(lastAttempt, old.scope === scope ? old.lastAttemptAt || 0 : 0) < 300_000
+        )
+            return;
+        lastAttempt = started;
+        try {
+            const snapshot = await statistics.refresh("monthly", { signal: options.signal });
+            atomicCache(file, {
+                schema: 1,
+                scope,
+                profile: config.profile,
+                monthUtc,
+                lastAttemptAt: started,
+                observedAt: snapshot.observedAt,
+                refreshFailed: false,
+                ...pricedSpend(snapshot.report),
+            });
+        } catch {
+            // Keep the last known figure: this file's own, or else the last valid usage program report the statistics cache still holds.
+            const known = load() ?? fromSnapshot(statistics.load("monthly"));
+            try {
+                atomicCache(file, {
+                    schema: 1,
+                    scope,
+                    profile: config.profile,
+                    monthUtc,
+                    lastAttemptAt: started,
+                    refreshFailed: true,
+                    ...(known && { spentUsd: known.spentUsd, unpriced: known.unpriced, observedAt: known.observedAt }),
+                });
+            } catch {}
+        }
+    };
+    return {
+        load,
+        refresh: (options) =>
+            (flight ??= perform(options).finally(() => {
+                flight = undefined;
+            })),
+    };
+}

package/src/cache.ts

@@ -0,0 +1,22 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+export function atomicCache(file: string, value: unknown): void {
+    const data = JSON.stringify(value);
+    if (Buffer.byteLength(data) > 1_048_576) throw new Error("Cache too large");
+    for (let p = dirname(file); dirname(p) !== p; p = dirname(p)) {
+        try {
+            if (lstatSync(p).isSymbolicLink()) throw new Error("Unsafe cache directory");
+        } catch (e) {
+            if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
+        }
+    }
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    const temp = `${file}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temp, data, { flag: "wx", mode: 0o600 });
+        renameSync(temp, file);
+    } finally {
+        rmSync(temp, { force: true });
+    }
+}