@pleach/transport-vertex

@pleach/transport-vertex is the Google Vertex AI route for a Pleach session whose buyer reaches Gemini through their GCP project. createVertexProvider(config) returns an AgentProvider that streams from Vertex's streamGenerateContent endpoint. Cascade behavior and audit shape stay consistent with every other provider; only the transport and the credential binding change.

What it provides

• An AgentProvider (execute + abort + capabilities) for Gemini on Vertex (gemini-1.5-*, gemini-2.0-*, gemini-2.5-*). Anthropic-on-Vertex and other families throw "family not yet supported" at invoke time.
• Auth through google-auth-library: Application Default Credentials (including workload identity) or an explicit service-account key.
• Region pinning at the provider instance (location), plus createResolveRegion(config) for AgentAdapter.resolveRegion.
• Generic auth errors: the stream never carries the underlying credential error or an HTTP 401/403 body.
• Per-call abort: each execute() owns its own AbortController. abort() cancels every in-flight call.

Where it fits

@pleach/transport-vertex plugs into the same provider slot on SessionRuntime that the direct-API providers fill — it satisfies the AgentProvider contract documented in Providers. For the architectural shape of a Vertex-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-vertex": "workspace:*"
  }
}

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

google-auth-library (^9.0.0 || ^10.0.0) is an optional peer dependency, loaded with a dynamic import() on first use. Importing the package without it is safe. The first execute() then yields an error event naming the missing google-auth-library peer.

Credentials

With no credentials, the provider uses Application Default Credentials: GOOGLE_APPLICATION_CREDENTIALS (a service-account key or a workload-identity-federation config), the gcloud SDK, or the metadata server (GKE Workload Identity, attached service accounts on GCE and Cloud Run).

import { createVertexProvider } from "@pleach/transport-vertex";

const provider = createVertexProvider({
  project: "my-project-123",
  location: "us-central1",
  defaultModelId: "gemini-2.5-flash",
});

Pass credentials (keyFilename, an inline credentials object, scopes, projectId) to use a specific service account. The default scope is https://www.googleapis.com/auth/cloud-platform.

Each provider builds one GoogleAuth client on first use and reuses it, so credential discovery runs once and the library refreshes the short-lived access token before it expires.

location

location must match /^[a-z0-9-]+$/ (for example "us-central1" or "europe-west4"). It becomes part of the hostname that receives the token, so anything else throws at construction. project and location are both required.

Auth errors

A credential failure yields one error event with the fixed text "vertex: authentication failed", or a fixed message naming a missing google-auth-library. The underlying error goes only to the optional onAuthError(error) hook, and a throwing hook is ignored. An HTTP 401/403 from Vertex is handled the same way: its body isn't echoed, and the provider drops its GoogleAuth client so the next request re-resolves credentials.

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