@pleach/transport-bedrock

@pleach/transport-bedrock is the AWS Bedrock route for a Pleach session whose contract clause forbids direct provider API keys. createBedrockProvider(config) returns an AgentProvider that streams through Bedrock's InvokeModelWithResponseStream API, so the family stays anthropic and only the transport changes. The canonical use case is a regulated buyer reaching Claude through their own AWS account, with the call recorded on the runtime ledger.

What it provides

• An AgentProvider (execute + abort + capabilities) for Anthropic models on Bedrock (anthropic.claude-* ids). Other families (meta.llama-*, amazon.titan-*, mistral.*, …) throw "family not yet supported" at first invoke.
• Static AWS keys or an STS session (credentials), or a per-request credentialProvider such as fromContainerMetadata(), refreshed before it expires.
• Generic auth errors: the stream never carries the underlying credential error, which can name role ARNs or account ids.
• Region pinning at the provider instance, plus createResolveRegion(config) for AgentAdapter.resolveRegion.
• Per-call abort: each execute() owns its own AbortController, so concurrent calls on one provider can't cancel each other. abort() cancels every in-flight call.

Where it fits

@pleach/transport-bedrock plugs into the same provider slot on SessionRuntime that AiSdkProvider and AnthropicSdkProvider fill — it satisfies the AgentProvider contract documented in Providers. For the architectural shape of a Bedrock-routed deployment — transport-vs-family, IAM federation, region as a hard constraint, cost reconciliation — see Cloud-routed agent.

Install

This package is not on npm yet, so there is no npm install step. Build it from the source repository and add it as a workspace dependency alongside @pleach/core:

{
  "dependencies": {
    "@pleach/core": "0.1.0",
    "@pleach/transport-bedrock": "workspace:*"
  }
}

Once the package publishes, this page will switch to a regular npm install.

@aws-sdk/client-bedrock-runtime (^3.0.0) is an optional peer dependency. It's loaded with a dynamic import() on first use, so importing the package without it is safe. The first execute() throws a "missing optional peer dependency @aws-sdk/client-bedrock-runtime" error if it's absent. @aws-sdk/credential-providers isn't declared at all; install it only if you build a credentialProvider from it.

Credentials

credentials and credentialProvider are mutually exclusive, and exactly one is required. Passing both, or neither, throws at construction and is a type error.

import { fromContainerMetadata } from "@aws-sdk/credential-providers";
import { createBedrockProvider } from "@pleach/transport-bedrock";

const provider = createBedrockProvider({
  region: "us-east-1",
  credentialProvider: fromContainerMetadata(),
  defaultModelId: "anthropic.claude-3-5-sonnet-20241022-v2:0",
});

credentialProvider takes the AWS SDK v3 credential-provider shape: fromContainerMetadata(), fromInstanceMetadata(), fromTemporaryCredentials(...), fromNodeProviderChain(), or your own () => Promise<{ accessKeyId, secretAccessKey, sessionToken?, expiration? }>. expiration may be a Date, an ISO-8601 string, or epoch milliseconds; anything unparseable counts as absent.

• The provider is called on the first request. Its result is cached until expiration minus credentialRefreshSkewMs, then re-resolved on the next request.
• credentialRefreshSkewMs must be a finite number >= 0. It defaults to 300000 (5 minutes).
• A result without expiration is re-resolved on every request; the provider owns its own caching then.
• Resolved credentials must carry a non-empty accessKeyId and secretAccessKey.

Auth errors

A failed credential resolution yields one error event with the fixed text "bedrock: authentication failed". The underlying error goes only to the optional onAuthError(error) hook, server side, and a throwing hook is ignored. The next request retries the provider.

Bedrock refusing the credentials is handled the same way: AccessDeniedException, ExpiredTokenException, UnrecognizedClientException and similar, or an HTTP 401/403. The event is generic, the error goes to onAuthError, and the cached credentials are dropped so the next request calls the provider again.

Configuration

The package's README and src/types.ts in the source repository are the reference. If a claim here disagrees with the source, the source wins.

Where to go next