@clawdbuilder/jig-bedrock 0.0.0-stage → 0.1.1

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,173 @@
-# 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 discovers the application inference profiles your account can use, sends
+Claude through Bedrock's Anthropic Messages route where possible, 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 has 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, and the AWS CLI v2 for discovery. You need an AWS profile the CLI can
+use; **SSO is one option, not a requirement**. Linux, WSL2 and macOS are supported; Windows is not, for the reason below.
+
+Run `/bedrock-doctor` after installing; it checks Node, the AWS CLI, `bash`, `jq` and the optional usage program without
+calling AWS.
+
+## Minimum settings
+
+With Jig, add a `bedrock` section to `jig.json` (or use the environment):
+
+```json
+{ "bedrock": { "team": "my-team" } }
+```
+
+A plain Pi install has no `jig.json`: put the same keys in `~/.pi/agent/bedrock.json` (or in a `bedrock` object in that
+file). With Jig, that file is read first and Jig's `bedrock` section is merged over it. A project's `jig.json` may set the
+catalog keys, but `ssoLoginCommand`, `usageDir` and `browser` are read only from the user's file or the environment.
+
+`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`                                                          |
+
+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.
+
+## How it works
+
+`jig-bedrock` reads the `bedrock` settings once at Pi start. Discovery and requests happen later: on the first request,
+when Pi starts an SSO check, or when you run a command.
+
+### Discovery
+
+Discovery runs the AWS CLI with the configured `profile` and `regions`:
+
+- `aws sts get-caller-identity` learns the 12-digit account.
+- `aws resourcegroupstaggingapi get-resources --resource-type-filters bedrock:application-inference-profile` asks for the
+  profiles in each region. `--tag-filters` keeps the profile's `Team` tag (or `tagKey`) and its `Active=true` tag (or
+  `activeTagKey`/`activeTagValue`).
+- `aws bedrock get-inference-profile --inference-profile-identifier <arn>` reads each profile's name, status and model.
+
+Only `ACTIVE` profiles are listed. Their foundation model is read from the profile's model ARN; the provider does not call
+`GetFoundationModel`. A successful catalog is cached for **24 hours** in `~/.cache/jig-bedrock/catalog.json`, with private
+permissions and an atomic rename. A changed account or settings discards it; `/bedrock-refresh` forces a new run.
+
+### Routes
+
+There are two routes to the same Claude models:
+
+- **Messages.** Pi's Anthropic Messages client calls
+  `https://bedrock-runtime.<region>.amazonaws.com/anthropic/v1/messages`. `bedrock-fetch.ts` removes the client's API-key
+  headers and signs each request with SigV4 (`sigv4.ts`). The signature uses the credentials the AWS SDK resolves for the
+  configured profile.
+- **Converse.** Pi's Bedrock provider uses the AWS SDK's `ConverseStream` operation at the bedrock-runtime endpoint.
+
+A profile is put on Messages only when `api` is `messages` (the default) and its foundation model is an Anthropic model.
+Every other model uses Converse. `api: "converse"` puts every model on Converse. Both routes stream. On Messages the tools array stays
+stable, so the prompt cache survives a tool change; on Converse a changed tool list rewrites it. The footer and usage
+figures are the same.
+
+A child agent (a Pi session with `PI_SUBAGENT_ID`, or the older `PI_SUBAGENT_CHILD=1`) skips the catalog refresh, the
+usage program and its events, and the sign-in at start. The parent does those; the child still sends requests and reads
+the parent's cached catalog.
+
+## Credentials
+
+Requests use the AWS SDK's default credential chain, loaded from Pi's install (`pi-host.ts` loads
+`@aws-sdk/credential-provider-node`). Discovery is different: it runs the AWS CLI with `--profile`, so the configured
+profile must be usable by the CLI as well as by the SDK.
+
+| What you have                                | Requests       | Discovery                              | Sign-in repair                                       |
+| -------------------------------------------- | -------------- | -------------------------------------- | ---------------------------------------------------- |
+| SSO / IAM Identity Center                    | yes, SDK chain | yes, `--profile`                       | yes: checked at start, one retry before any response |
+| Access keys in a profile                     | yes            | yes, `--profile`                       | no                                                   |
+| Assume role in a profile                     | yes            | yes, `--profile`                       | no                                                   |
+| `credential_process` in a profile            | yes            | yes, `--profile`                       | no                                                   |
+| Web identity or instance role                | yes            | only through a profile the CLI can use | no                                                   |
+| Bedrock API key (`AWS_BEARER_TOKEN_BEDROCK`) | not supported  | no                                     | no                                                   |
+
+Only the SSO path has been tested against real AWS. The other rows are supported by the SDK and CLI, but not by a real
+run in this package.
+
+For a Bedrock API key: `sso.ts`'s `profileFor` declines to choose an SSO profile when the bearer variable is set, so no
+repair is attempted. With a configured profile, the request path clears that variable and refuses an explicit API key or
+bearer token with `Unapproved Bedrock authentication scope`. The package does not fall back to API-key auth.
+
+## AWS permissions
+
+The profile used for discovery needs these actions:
+
+- `sts:GetCallerIdentity` for the account id;
+- `tag:GetResources` for the tagged inference profiles;
+- `bedrock:GetInferenceProfile` for each profile.
+
+The provider always streams: Messages uses Bedrock's Anthropic Messages route, and Converse uses the SDK's
+`ConverseStream` operation. The request therefore needs:
+
+- `bedrock:InvokeModelWithResponseStream` for both routes. The SDK's `ConverseStream` is authorized by this action, not by
+  an action named after Converse.
+
+`bedrock:InvokeModel` is not needed: this provider has no non-streaming call. If a future call adds one, it needs that
+action too.
+
+For an application inference profile, the policy must allow the action on the profile's ARN **and** on every foundation
+model ARN the profile routes to.
+
+No `List` or `GetFoundationModel` permission is needed: the code gets the foundation model from the profile's ARN.
+
+## Why not Windows
+
+The SSO lock needs a POSIX owner and private `0700` directory (`ssoRuntime` in `src/login.ts` checks `process.getuid` and
+mode bits), and the no-browser fallback is the WSL-only `bin/windows-browser` shell script. Native Windows has neither.
+
+## 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 and `/bedrock-usage` read an executable named `usage` in `usageDir`; it is called with `--daily`,
+`--weekly` or `--monthly` and `--output json`, and prints the spend as JSON.
+
+## 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.
+
+Real-AWS tests are manual and need the user's approval; unit tests use recorded 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.1",
+    "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 });
+    };
+}