# How it works

Routes, model names, discovery, sign-in repair and spend.

## The words

| Word                              | Meaning                                                                                                |
| --------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **AWS profile**                   | A named sign-in in your AWS CLI configuration, such as `my-profile`. It is who you are to AWS.         |
| **Inference profile**             | One entry AWS lets you call. It has an ARN and points at one foundation model.                         |
| **AWS-defined inference profile** | Made by AWS for everyone; routes within a geography, so its id starts `us.` or `global.`; the default. |
| **Application inference profile** | Made by your team in your account; can carry tags.                                                     |
| **Model**                         | What you pick in `/model`; one inference profile, named by a short id.                                 |
| **Route**                         | How a request travels: Messages is Bedrock's Anthropic interface; Converse is its general interface.   |
| **Catalog**                       | The saved list of inference profiles found in your account.                                            |

## Which route a model gets

![A question chooses the route: if Pi says tool changes work, the model uses Messages and keeps the cache; otherwise it uses Converse like Pi's built-in provider.](https://raw.githubusercontent.com/ClawdBuilder/jig-bedrock/main/docs/img/routes.svg)

_Pi's answer decides; details in [Which route a model gets](#which-route-a-model-gets) and [Prompt cache by model](#prompt-cache-by-model)._

The rule asks in order; the first answer wins:

1. Not a Claude model? Converse.
2. `api` is `converse`, or the model is in `converseModels`? Converse.
3. The model is in `messagesModels`? Messages.
4. A known exception, today Opus 5? Converse.
5. Pi lists the model and its entry says mid-session tool changes work? Messages. Otherwise Converse.

A model newer than the installed Pi uses Converse until Pi is updated or the model is added to `messagesModels`. `/bedrock models` shows the reason: `Pi lists tool changes`, `not on the Messages route`, `Pi has no Messages entry`, `your setting`, `known exception` or `not a Claude model`.

| Model                                               | Route    | Result                  |
| --------------------------------------------------- | -------- | ----------------------- |
| Haiku 5.5, Sonnet 5.5, Opus 5.5, Opus 4.8           | Messages | Works; cache kept       |
| Fable models                                        | Messages | Not tested; AWS refused |
| Opus 5                                              | Converse | 400 with thinking high  |
| Sonnet 5, Opus 4.7, Opus 4.6, Sonnet 4.6, Haiku 4.5 | Converse | 400 after a tool load   |
| Opus 4.5, Sonnet 4.5, Opus 4.1                      | Converse | 404 on Messages         |

### Prompt cache by model

| Model                                     | Route    | Cache        | After a tool load    |
| ----------------------------------------- | -------- | ------------ | -------------------- |
| Haiku 5.5, Sonnet 5.5, Opus 5.5, Opus 4.8 | Messages | 5 min        | Cache kept           |
| Other Claude 4.5 and later                | Converse | 5 min or 1 h | Prompt written again |
| Older Claude                              | Converse | 5 min        | Prompt written again |
| Amazon Nova Micro, Lite, Pro              | Converse | 5 min        | Not measured         |
| Any other model                           | Converse | None         | —                    |

Both routes stream the reply. Messages declares only the 5-minute cache lifetime, so `PI_CACHE_RETENTION=long` does nothing there; Converse keeps both lifetimes.

## How models are found

![Three sources ask the AWS API: AWS-defined, by tag, or listed by hand. It only reads, fills the catalog, kept for 24 hours, which fills /model.](https://raw.githubusercontent.com/ClawdBuilder/jig-bedrock/main/docs/img/discovery.svg)

_Three sources; details in [How models are found](#how-models-are-found), [What runs when](#what-runs-when), and [Settings](settings.md#the-three-ways-models-are-found)._

The settings choose one way; there is no fallback.

- **AWS-defined (default):** lists the AWS-defined inference profiles in each region. Only Claude entries with status `ACTIVE` are kept.
- **By tag:** reads application inference profiles with `tagKey` and `tagValue`; any model Pi knows is allowed.
- **Listed by hand:** reads each ARN or id in `profiles`; application inference profiles may hold any model Pi knows, while an AWS-defined one is Claude only.

Each way starts with an STS account check, then reads Bedrock over HTTPS with the AWS profile's credentials; no `aws` program runs for discovery. (`aws sso login` and the AWS profile list still use the AWS CLI.) A call may take 20 seconds; a run stops at 90 seconds. At most 256 inference profiles are kept. An inference profile that points at another is followed up to two levels. `GetFoundationModel` is never called.

The catalog is private, written by atomic rename, and records the AWS profile and settings. The top level and each preset's scope keep one file, and identical scopes share it, so one preset's discovery does not overwrite another's; one spare is kept for a scope whose settings just changed, and at most 32 files are kept. A changed setting discards its catalog. A read that fails in one region keeps the other regions' models and says `N models loaded from X of Y regions`; the failed region is tried again at the next start or `/bedrock refresh`. A failed read says what went wrong — AWS throttled the call, AWS had a problem on its side, the credentials expired or are not valid, or AWS could not be reached — and gives its own next step. If the catalog cannot be written, the models still load for this session and the warning names the folder. An inference profile whose foundation model Pi does not know is not listed; `/bedrock refresh`, `/bedrock status` and `/bedrock models` say how many and name `update Pi`. A model with no price is listed as `no price`, and its replies count as unpriced. `/bedrock models` names up to three rejected entries, with `update Pi` when that is the cause.

## Model ids

The short id is the Claude name and version, such as `claude-sonnet-5-5`. The plain id goes to the AWS-defined inference profile of your first region's geography, then `global`, then other regions in order. Another inference profile for the same model gets a longer id, such as `-global`; two application inference profiles for one model both get the longer form. An older id still selects it.

A reply is recorded under the provider that answered it, `jig-bedrock/<short id>` or `jig-bedrock-<preset>/<short id>`; the ARN stays off the session list.

## Sign-in repair

![A request asks whether the SSO sign-in expired; if so an aws sso login with a browser runs, then the request is sent once more.](https://raw.githubusercontent.com/ClawdBuilder/jig-bedrock/main/docs/img/sign-in-repair.svg)

_One retry, never a third time; details in [Sign-in repair](#sign-in-repair) and [Settings](settings.md#sign-in-methods)._

1. At a real Pi start in a TUI or RPC session (not on `/reload`, `/new` or `/resume`), the saved SSO token's expiry is checked. An expired one gets a notice that says whether the saved models are loaded. With `signInAtStart: true` the sign-in starts at once; the default is false.
2. If a request fails before any reply because the SSO session expired, `ssoLoginCommand` (`aws sso login --profile <name>`) runs, then the request is sent once more. Never a third time.
3. `/bedrock login` runs the same sign-in. A role profile renews its SSO `source_profile`; a keys profile is not sent to `aws sso login`. One login runs at a time; a lock file separates two Pi processes.

A browser opens for the sign-in. On WSL the package opens the Windows browser through `bin/windows-browser`; `browser` names another program. The package never stores a password or token; `/login` stores only the AWS profile name.

An SSO profile and a role over an SSO `source_profile` are repaired; keys, and a role over keys, are not. `/bedrock doctor` and `/bedrock login` give those the AWS CLI check (`aws sts get-caller-identity --profile <name>`) instead of the same command again. Other sign-in methods: [Settings](settings.md#sign-in-methods).

## Menus

`/bedrock` with no arguments opens a menu in a TUI. Back returns one level up (a sub-menu to the main menu), and Escape closes everything. With no presets the Presets menu says so and offers save and Back. The Models menu lists the models this Pi cannot use, with the reason, and says `price unknown` for a model Pi has no price for; choosing a model says which one is in use for the session or why Pi did not switch. The typed commands stay for scripts and agents.

## What runs when

| When                                 | What happens                                                                     | Calls AWS?       |
| ------------------------------------ | -------------------------------------------------------------------------------- | ---------------- |
| Pi starts the package                | Settings are read; commands and one provider per preset are registered.          | No               |
| A session starts                     | Each provider's AWS profile and cache; stale caches refresh in the background.   | Only the refresh |
| A request                            | The route is chosen; credentials are built; an expired sign-in is repaired once. | Yes              |
| A reply ends                         | Spend is recorded; the footer updates; a budget notice may appear.               | No               |
| You open `/model`                    | Every provider's saved list shows; stale caches refresh in the background.       | Only the refresh |
| `/bedrock refresh`, `/bedrock login` | Discovery runs now, whatever the cache age, or the sign-in runs.                 | Yes              |
| `/bedrock doctor`                    | Local checks, then free AWS calls; `offline` makes none.                         | Yes, free        |

Nothing waits for AWS at start.

## Spend and the footer

- A reply that reports usage adds one line to `${XDG_STATE_HOME:-~/.local/state}/jig-bedrock/spend/`; no prompt, ARN, account id or AWS profile name. A reply that ended in error or was aborted is counted when Pi reports tokens for it; a message with no usage adds nothing.
- The first reply of a month imports earlier sessions from this agent folder once.
- The footer follows the model in use. With a preset its line starts with the preset's name: `work · Nov $12.40 / $200`. A preset's figure includes this month's spend from before presets existed. `preset add` selects the new preset's model from the same cached list, so the footer moves at once; while that list is still loading it says the footer switches when a model of the new preset is used, and the footer stays on the model in use.
- The footer shows `Nov $12.40`, or `Nov $12.40 / $200` with a budget. A `+` means an unpriced reply.
- Warning colour starts at 80%, error at 100%; the footer clears when another provider's model is selected. Each warning is announced once a month for one preset and budget amount; a raised budget or `/bedrock budget` can announce again.
- `/bedrock usage week` counts the last 7 days, reading the previous month's file when they cross a month.
- A `spendCommand` supplies the figure instead: [Spend command](spend-command.md).

[Back to the README](../README.md).
