agentfootprint 9.11.0 → 9.13.0

package/dist/esm/adapters/identity/agentcore.d.ts

@@ -10,6 +10,8 @@
  *   - request.mode 'machine' → `M2M`; 'user' → `USER_FEDERATION`
  *   - request.service        → the configured OAuth2 credential-provider name
  *   - request.identity       → (per-request workload identity scoping; see below)
+ *   - request.userToken      → the user's own JWT, exchanged for a user-scoped
+ *                              workload token before vending (9.12.0; see below)
  *   - a returned access token → `{ status: 'issued', credential: bearer(token) }`
  *   - a returned auth URL     → `{ status: 'authorization-required' }` (3LO consent)
  *
@@ -18,21 +20,50 @@
  *
  * **Per-request identity forwarding (workload identity scoping).**
  * `GetResourceOauth2Token` carries NO user/tenant field — in AgentCore the
- * user identity is bound EARLIER, at workload-token acquisition:
- * `GetWorkloadAccessTokenForUserId(workloadName, userId)` returns a workload
- * access token scoped to that user, and AgentCore keys its token vault + 3LO
- * grants per (workload, user). So this adapter forwards `req.identity` (the
- * `runIdentity` that the agent threads through `getCredential`) by resolving a
- * per-user workload token first, then vending with it. Engages only when ALL of:
- *   - `req.mode === 'user'` (USER_FEDERATION — M2M is the workload's own identity),
- *   - a userId derives from `req.identity` (default `identity.principal`;
- *     override via `userIdFor`), and
- *   - `options.workloadName` is configured (the opt-in).
- * Otherwise the static `options.workloadIdentityToken` flows exactly as before.
+ * user identity is bound EARLIER, at workload-token acquisition. There are two
+ * ways to bind it, and this adapter dispatches both:
+ *
+ *   `GetWorkloadAccessTokenForUserId(workloadName, userId)` — the ASSERTION.
+ *     The agent says who the user is; AWS takes its word for it and returns a
+ *     workload token keyed to that (workload, user).
+ *   `GetWorkloadAccessTokenForJWT(workloadName, userToken)` — the PROOF (9.12.0).
+ *     The agent hands over the token the user's own identity provider signed,
+ *     and gets back "an opaque token representing the identity of both the
+ *     workload and the user" (the service's own words for the response).
+ *
+ * Either way the answer is a `workloadAccessToken`, and it flows into
+ * `GetResourceOauth2Token`'s `workloadIdentityToken` unchanged — which is why
+ * the second one needed no new credential path, no new result branch and no
+ * change to `toHeaders()`. AgentCore keys its token vault + 3LO grants per
+ * (workload, user), so the whole point of resolving either is that the vault
+ * entry belongs to the person rather than to the agent.
+ *
+ * **The JWT rides the REQUEST.** `req.userToken` is per call, because the
+ * person calling is per call; a JWT in this provider's construction options
+ * would be one user's session serving everybody. Presence is what selects the
+ * exchange — a proof that arrived is never downgraded to an assertion — and
+ * `requireUserToken` turns "no JWT on a `mode: 'user'` request" from a quiet
+ * fallback into a refusal, for a deployment where every user IS authenticated.
+ *
+ * The ladder, in order, for one `getCredential(req)`:
+ *   1. `req.userToken` present → exchange it (needs `workloadName`; `mode: 'user'`).
+ *   2. else a userId derives from `req.identity` (default `identity.principal`;
+ *      override via `userIdFor`) on a `mode: 'user'` request, and
+ *      `options.workloadName` is configured → the by-userId exchange.
+ *   3. else the static `options.workloadIdentityToken` flows exactly as before.
+ *
  * `tenant` has no native AgentCore field and is NOT forwarded by default —
  * tenant isolation derives from the workload identity itself (per-tenant
  * workloads), or encode it via `userIdFor` (e.g. `${tenant}:${principal}`).
  *
+ * **Secrecy.** The inbound JWT and the exchanged workload token are secrets of
+ * equal weight, and neither appears in anything this file throws. A failed
+ * exchange is described by the SHAPE of the response — how many fields it
+ * carried and what they are called — never by its content, because every field
+ * of a token-exchange response is a token. A thrown message reaches the LLM as
+ * a tool result AND rides `agentfootprint.credential.failed`, so an error that
+ * quotes the response has published the user's session to both at once.
+ *
  * ── How this talks to the SDK (9.4.0 — read this before editing) ────────────
  * Through **`client.send(new SomeCommand(input))`**, never through a method on
  * the client. A bare `@aws-sdk/client-*` **Client** is command-based: its
@@ -85,6 +116,16 @@ export interface AgentCoreIdentityClientLike {
     }): Promise<{
         readonly workloadAccessToken?: string;
     }>;
+    /** Optional — required only when a request carries `userToken`. Exchanges the
+     *  user's OWN IdP-issued JWT for a workload access token representing both the
+     *  workload and the user. Same answer shape as the by-userId exchange, which
+     *  is why both feed the same `workloadIdentityToken`. */
+    getWorkloadAccessTokenForJWT?(input: {
+        readonly workloadName: string;
+        readonly userToken: string;
+    }): Promise<{
+        readonly workloadAccessToken?: string;
+    }>;
 }
 export interface AgentCoreIdentityOptions {
     readonly region?: string;
@@ -93,11 +134,28 @@ export interface AgentCoreIdentityOptions {
      *  workload token is resolved (see `workloadName`). */
     readonly workloadIdentityToken?: string;
     /** The AgentCore workload identity name — the OPT-IN for per-request identity
-     *  scoping. When set, `mode: 'user'` requests carrying `req.identity` resolve a
-     *  per-user workload access token via `GetWorkloadAccessTokenForUserId(workloadName,
-     *  userId)` before vending, so AgentCore's token vault + 3LO grants are keyed per
-     *  (workload, user) instead of per workload. Omit → today's static-token behavior. */
+     *  scoping, and the one option BOTH exchanges need. When set, a `mode: 'user'`
+     *  request resolves a per-user workload access token before vending — from
+     *  `req.userToken` via `GetWorkloadAccessTokenForJWT` when the user's own JWT
+     *  arrived, otherwise from `req.identity` via `GetWorkloadAccessTokenForUserId`
+     *  — so AgentCore's token vault + 3LO grants are keyed per (workload, user)
+     *  instead of per workload. Omit → today's static-token behavior. */
     readonly workloadName?: string;
+    /**
+     * Refuse a `mode: 'user'` request that carries no `req.userToken` (9.12.0),
+     * instead of falling back to the by-userId exchange or the static token.
+     *
+     * The opt-in for a deployment where the front door really does authenticate
+     * every person — an AgentCore Runtime behind JWT inbound auth, an API gateway
+     * that validates a bearer token. There, a delegated request with no proof
+     * attached is a wiring bug, and the failure it causes without this flag is the
+     * quiet kind: a token gets vended, the call succeeds, and it was scoped to the
+     * agent (or to a user id the agent asserted) rather than to the person.
+     *
+     * `mode: 'machine'` is never affected — M2M is the workload's own identity and
+     * has no user to prove.
+     */
+    readonly requireUserToken?: boolean;
     /** Map `req.identity` → the AgentCore `userId`. Default: `identity.principal`.
      *  `tenant` has no native AgentCore field — encode it here if you need
      *  tenant-scoped vault entries (e.g. ``({ tenant, principal }) =>
@@ -125,6 +183,7 @@ export interface BedrockAgentCoreIdentitySdkModule {
     };
     readonly GetResourceOauth2TokenCommand?: new (input: unknown) => unknown;
     readonly GetWorkloadAccessTokenForUserIdCommand?: new (input: unknown) => unknown;
+    readonly GetWorkloadAccessTokenForJWTCommand?: new (input: unknown) => unknown;
 }
 /** Build a {@link CredentialProvider} backed by AWS Bedrock AgentCore Identity. */
 export declare function agentCoreIdentity(options?: AgentCoreIdentityOptions): CredentialProvider;

package/dist/esm/adapters/identity/agentcore.js

@@ -10,6 +10,8 @@
  *   - request.mode 'machine' → `M2M`; 'user' → `USER_FEDERATION`
  *   - request.service        → the configured OAuth2 credential-provider name
  *   - request.identity       → (per-request workload identity scoping; see below)
+ *   - request.userToken      → the user's own JWT, exchanged for a user-scoped
+ *                              workload token before vending (9.12.0; see below)
  *   - a returned access token → `{ status: 'issued', credential: bearer(token) }`
  *   - a returned auth URL     → `{ status: 'authorization-required' }` (3LO consent)
  *
@@ -18,21 +20,50 @@
  *
  * **Per-request identity forwarding (workload identity scoping).**
  * `GetResourceOauth2Token` carries NO user/tenant field — in AgentCore the
- * user identity is bound EARLIER, at workload-token acquisition:
- * `GetWorkloadAccessTokenForUserId(workloadName, userId)` returns a workload
- * access token scoped to that user, and AgentCore keys its token vault + 3LO
- * grants per (workload, user). So this adapter forwards `req.identity` (the
- * `runIdentity` that the agent threads through `getCredential`) by resolving a
- * per-user workload token first, then vending with it. Engages only when ALL of:
- *   - `req.mode === 'user'` (USER_FEDERATION — M2M is the workload's own identity),
- *   - a userId derives from `req.identity` (default `identity.principal`;
- *     override via `userIdFor`), and
- *   - `options.workloadName` is configured (the opt-in).
- * Otherwise the static `options.workloadIdentityToken` flows exactly as before.
+ * user identity is bound EARLIER, at workload-token acquisition. There are two
+ * ways to bind it, and this adapter dispatches both:
+ *
+ *   `GetWorkloadAccessTokenForUserId(workloadName, userId)` — the ASSERTION.
+ *     The agent says who the user is; AWS takes its word for it and returns a
+ *     workload token keyed to that (workload, user).
+ *   `GetWorkloadAccessTokenForJWT(workloadName, userToken)` — the PROOF (9.12.0).
+ *     The agent hands over the token the user's own identity provider signed,
+ *     and gets back "an opaque token representing the identity of both the
+ *     workload and the user" (the service's own words for the response).
+ *
+ * Either way the answer is a `workloadAccessToken`, and it flows into
+ * `GetResourceOauth2Token`'s `workloadIdentityToken` unchanged — which is why
+ * the second one needed no new credential path, no new result branch and no
+ * change to `toHeaders()`. AgentCore keys its token vault + 3LO grants per
+ * (workload, user), so the whole point of resolving either is that the vault
+ * entry belongs to the person rather than to the agent.
+ *
+ * **The JWT rides the REQUEST.** `req.userToken` is per call, because the
+ * person calling is per call; a JWT in this provider's construction options
+ * would be one user's session serving everybody. Presence is what selects the
+ * exchange — a proof that arrived is never downgraded to an assertion — and
+ * `requireUserToken` turns "no JWT on a `mode: 'user'` request" from a quiet
+ * fallback into a refusal, for a deployment where every user IS authenticated.
+ *
+ * The ladder, in order, for one `getCredential(req)`:
+ *   1. `req.userToken` present → exchange it (needs `workloadName`; `mode: 'user'`).
+ *   2. else a userId derives from `req.identity` (default `identity.principal`;
+ *      override via `userIdFor`) on a `mode: 'user'` request, and
+ *      `options.workloadName` is configured → the by-userId exchange.
+ *   3. else the static `options.workloadIdentityToken` flows exactly as before.
+ *
  * `tenant` has no native AgentCore field and is NOT forwarded by default —
  * tenant isolation derives from the workload identity itself (per-tenant
  * workloads), or encode it via `userIdFor` (e.g. `${tenant}:${principal}`).
  *
+ * **Secrecy.** The inbound JWT and the exchanged workload token are secrets of
+ * equal weight, and neither appears in anything this file throws. A failed
+ * exchange is described by the SHAPE of the response — how many fields it
+ * carried and what they are called — never by its content, because every field
+ * of a token-exchange response is a token. A thrown message reaches the LLM as
+ * a tool result AND rides `agentfootprint.credential.failed`, so an error that
+ * quotes the response has published the user's session to both at once.
+ *
  * ── How this talks to the SDK (9.4.0 — read this before editing) ────────────
  * Through **`client.send(new SomeCommand(input))`**, never through a method on
  * the client. A bare `@aws-sdk/client-*` **Client** is command-based: its
@@ -53,6 +84,62 @@
  */
 import { lazyRequire } from '../../lib/lazyRequire.js';
 import { bearer } from '../../identity/kinds.js';
+/**
+ * Re-raise a failed SDK call **without its text** (9.12.0).
+ *
+ * Every input this adapter sends is a secret: the user's JWT goes into
+ * `GetWorkloadAccessTokenForJWT`, a workload access token goes into
+ * `GetResourceOauth2Token`. AWS clients report transport and validation
+ * failures by echoing request detail into the message — which is how a live
+ * user session ends up in a string that this library then hands to the LLM as
+ * a tool result and emits on `agentfootprint.credential.failed`. One echo, and
+ * it is in the conversation, the commit log, the narrative and every sink.
+ *
+ * So the text does not come through. What does is the part that is both safe
+ * and actionable: which operation failed, the exception's NAME (AWS models
+ * them — `AccessDeniedException`, `ResourceNotFoundException`,
+ * `ThrottlingException`, `UnauthorizedException`, `ValidationException`) and
+ * the HTTP status. That is the same trade the Vault adapter makes, and it is
+ * the same reason.
+ *
+ * **The original is deliberately not attached as `cause`.** A cause travels
+ * with the error into every serializer that walks own properties, which would
+ * undo the whole of this in one `JSON.stringify`.
+ *
+ * An injected `_client` never reaches here: it owns its own mapping, and its
+ * own secrecy with it — the same law this file already states for field names.
+ */
+function sdkFailure(command, err) {
+    const e = err;
+    const name = typeof e?.name === 'string' && e.name.length > 0 ? e.name : 'an unnamed failure';
+    const status = e?.$metadata?.httpStatusCode;
+    return new Error(`agentCoreIdentity: ${command} failed — ${name}` +
+        (typeof status === 'number' ? ` (HTTP ${status})` : '') +
+        ".\n  The SDK's own message is withheld: this request carried a token, and AWS clients " +
+        'echo request detail into failure text. Check CloudWatch for the full exception.');
+}
+/**
+ * Read the exchanged workload token, or refuse **by shape**.
+ *
+ * Shared by both exchanges so there is one refusal to read and one rule about
+ * what may be said: field NAMES and a count, never a value. Every field of a
+ * token-exchange response is a token, and this message travels to the model, to
+ * `agentfootprint.credential.failed` and to every log sink attached to it. An
+ * operator debugging a malformed answer needs to know which fields came back,
+ * which is exactly the part that is safe to print.
+ */
+function requireWorkloadAccessToken(response, operation) {
+    const token = response?.workloadAccessToken;
+    if (typeof token === 'string' && token.length > 0)
+        return token;
+    const fields = response && typeof response === 'object' ? Object.keys(response) : [];
+    throw new Error(`agentCoreIdentity: ${operation} returned no usable workloadAccessToken, so there is no ` +
+        'user-scoped workload token to vend with — refusing rather than falling back to a ' +
+        'workload-level one.\n' +
+        `  The response carried ${fields.length} field(s)` +
+        (fields.length > 0 ? `: ${fields.join(', ')}.` : '.') +
+        '\n  Values are withheld on purpose: every field of a token-exchange response is a secret.');
+}
 /**
  * Map {@link AgentCoreIdentityClientLike} onto the real SDK commands.
  *
@@ -92,7 +179,12 @@ function createIdentityClient(options) {
             throw new Error(`agentCoreIdentity: \`@aws-sdk/client-bedrock-agentcore\` is missing ${name}. ` +
                 'Upgrade the SDK, or pass `_client` with your own mapping.');
         }
-        return sdk.send(new Ctor(input));
+        try {
+            return await sdk.send(new Ctor(input));
+        }
+        catch (err) {
+            throw sdkFailure(name, err);
+        }
     };
     return {
         async getResourceOauth2Token(input) {
@@ -115,13 +207,27 @@ function createIdentityClient(options) {
                 ...(r?.sessionUri !== undefined && { sessionId: r.sessionUri }),
             };
         },
+        // ── The two workload-token exchanges ──────────────────────────────
+        //
+        // Both answer `{ workloadAccessToken }` and nothing else, so unlike
+        // `getResourceOauth2Token` above there is no field to rename — and both
+        // hand the response back AS RECEIVED rather than narrowed to that one
+        // field. That is deliberate: when the field is missing,
+        // `requireWorkloadAccessToken` refuses by describing the response's SHAPE,
+        // and a shim that had already thrown the other field names away would leave
+        // it describing an empty object — the least useful message available, on
+        // the one path where the operator has nothing else to go on.
         async getWorkloadAccessTokenForUserId(input) {
-            const r = (await send(mod.GetWorkloadAccessTokenForUserIdCommand, 'GetWorkloadAccessTokenForUserIdCommand', input));
-            return {
-                ...(r?.workloadAccessToken !== undefined && {
-                    workloadAccessToken: r.workloadAccessToken,
-                }),
-            };
+            return ((await send(mod.GetWorkloadAccessTokenForUserIdCommand, 'GetWorkloadAccessTokenForUserIdCommand', input)) ?? {});
+        },
+        async getWorkloadAccessTokenForJWT(input) {
+            // `GetWorkloadAccessTokenForJWTRequest` is `{ workloadName, userToken }`,
+            // both required, and the response is `{ workloadAccessToken }` — verified
+            // against a real install of @aws-sdk/client-bedrock-agentcore before this
+            // shipped, the same way the code-interpreter shapes were. `userToken` is
+            // the SDK's own name for the user's IdP-issued OAuth2 token, so the
+            // adapter and the wire agree without a rename.
+            return ((await send(mod.GetWorkloadAccessTokenForJWTCommand, 'GetWorkloadAccessTokenForJWTCommand', input)) ?? {});
         },
     };
 }
@@ -139,13 +245,55 @@ export function agentCoreIdentity(options = {}) {
     const getClient = () => (client ??= resolveClient(options));
     const userIdFor = options.userIdFor ?? defaultUserIdFor;
     // Per-request identity forwarding (workload identity scoping) — see module
-    // header. `GetResourceOauth2Token` has no user field; the user is bound at
-    // workload-token acquisition, so a `mode: 'user'` request carrying an
-    // identity exchanges (workloadName, userId) for a USER-SCOPED workload token
-    // and vends with that. Requires `workloadName` (the opt-in); without it the
-    // static `workloadIdentityToken` flows unchanged (pre-forwarding behavior).
+    // header for the ladder and why both exchanges answer the same question.
+    // `GetResourceOauth2Token` has no user field; the user is bound at
+    // workload-token acquisition, so a `mode: 'user'` request resolves a
+    // USER-SCOPED workload token first and vends with that. Both exchanges
+    // require `workloadName` (the opt-in); with neither engaged the static
+    // `workloadIdentityToken` flows unchanged (pre-forwarding behavior).
     const resolveWorkloadToken = async (req) => {
-        const userId = req.mode === 'user' && req.identity !== undefined ? userIdFor(req.identity) : undefined;
+        const delegated = req.mode === 'user';
+        if (req.userToken !== undefined) {
+            if (!delegated) {
+                // A user's signed token on a request that asks for the WORKLOAD's own
+                // identity. Vending M2M while holding somebody's proof is the exact
+                // silent downgrade this whole path exists to close, so it is named
+                // rather than resolved one way or the other.
+                throw new Error("agentCoreIdentity: a `userToken` arrived on a `mode: 'machine'` request. M2M is the " +
+                    "workload's own identity — there is no user to act on behalf of, and the token " +
+                    "would be ignored.\n  Declare `mode: 'user'` to exchange it, or drop the token.");
+            }
+            if (!options.workloadName) {
+                throw new Error('agentCoreIdentity: a `userToken` arrived but no `workloadName` is configured, so ' +
+                    'there is nothing to exchange it against — and vending at workload level would ' +
+                    "hand back a token scoped to the AGENT while holding the user's proof.\n" +
+                    '  Configure `workloadName` (your AgentCore workload identity), or stop sending ' +
+                    '`userToken`.');
+            }
+            const c = getClient();
+            if (typeof c.getWorkloadAccessTokenForJWT !== 'function') {
+                // The SDK-backed client always implements this, so reaching here means
+                // an injected `_client` that does not.
+                throw new Error('agentCoreIdentity: a `userToken` arrived, but the injected `_client` has no ' +
+                    'getWorkloadAccessTokenForJWT. Implement it, or stop sending `userToken`.');
+            }
+            return requireWorkloadAccessToken(await c.getWorkloadAccessTokenForJWT({
+                workloadName: options.workloadName,
+                userToken: req.userToken,
+            }), 'GetWorkloadAccessTokenForJWT');
+        }
+        if (options.requireUserToken === true && delegated) {
+            // The deployment said every delegated request is authenticated. One that
+            // is not is a wiring bug, and the only alternative to saying so is to
+            // vend something weaker and let it succeed.
+            throw new Error("agentCoreIdentity: `requireUserToken` is set, but this `mode: 'user'` request for " +
+                `'${req.service}' carried no \`userToken\`.\n` +
+                "  Pass the caller's own IdP token as `getCredential({ …, userToken })` — inside " +
+                'AgentCore Runtime behind JWT inbound auth it is the bearer token the front door ' +
+                'validated.\n' +
+                '  Or drop `requireUserToken` to fall back to the by-userId exchange.');
+        }
+        const userId = delegated && req.identity !== undefined ? userIdFor(req.identity) : undefined;
         if (userId === undefined || !options.workloadName)
             return options.workloadIdentityToken;
         const c = getClient();
@@ -157,15 +305,7 @@ export function agentCoreIdentity(options = {}) {
                 'but the injected `_client` has no getWorkloadAccessTokenForUserId. Implement it, ' +
                 'or drop `workloadName` to vend with the static `workloadIdentityToken`.');
         }
-        const res = await c.getWorkloadAccessTokenForUserId({
-            workloadName: options.workloadName,
-            userId,
-        });
-        if (!res.workloadAccessToken) {
-            throw new Error('agentCoreIdentity: GetWorkloadAccessTokenForUserId returned no workloadAccessToken ' +
-                'for per-user scoped vending.');
-        }
-        return res.workloadAccessToken;
+        return requireWorkloadAccessToken(await c.getWorkloadAccessTokenForUserId({ workloadName: options.workloadName, userId }), 'GetWorkloadAccessTokenForUserId');
     };
     return {
         id: options.id ?? 'agentcore-identity',

package/dist/esm/adapters/identity/agentcore.js.map

@@ -1 +1 @@
-{"version":3,"file":"agentcore.js","sourceRoot":"","sources":["../../../../src/adapters/identity/agentcore.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agentcore.js","sourceRoot":"","sources":["../../../../src/adapters/identity/agentcore.ts"],"names":[],"mappings":"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"}

package/dist/esm/adapters/llm/GeminiProvider.d.ts

@@ -0,0 +1,204 @@
+/**
+ * GeminiProvider — wraps `@google/genai` as an `LLMProvider` (9.13.0).
+ *
+ * Pattern: Adapter (GoF) + Ports-and-Adapters (Cockburn 2005).
+ * Role:    Outer ring — translates `LLMRequest`/`LLMResponse` to/from Google's
+ *          `generateContent` API. Knows nothing about agents, recorders, or
+ *          compositions.
+ * Emits:   N/A — providers don't emit; recorders observe via Agent.
+ *
+ * ─── Two doors, one adapter ─────────────────────────────────────────
+ *
+ * The same SDK reaches two different services, and which one you get is a
+ * property of the OPTIONS, not of a separate factory:
+ *
+ *   • **Vertex** — `gemini({ project, location })` builds
+ *     `new GoogleGenAI({ vertexai: true, project, location, googleAuthOptions })`.
+ *     Auth is Application Default Credentials (env key file, gcloud user
+ *     credentials, or the metadata server on GCE / Cloud Run / Agent Runtime).
+ *     No API key exists on this path.
+ *   • **Gemini API (AI Studio)** — `gemini({ apiKey })` builds
+ *     `new GoogleGenAI({ apiKey })`. One key, no cloud project.
+ *
+ * Neither is guessed. The factory refuses at construction when it can resolve
+ * neither a project nor a key, naming both doors — because the SDK's own
+ * behaviour in that case is to WARN on stderr, construct anyway, and fail on
+ * the first call, which reads like a network problem rather than a missing
+ * setting.
+ *
+ * ─── Why native, and not `openai({ baseURL })` ──────────────────────
+ *
+ * Google publishes an OpenAI-compatible endpoint, and it does work — for about
+ * an hour. It authenticates with an OAuth access token that expires and has no
+ * refresh home in `OpenAIProviderOptions`; its `tools.function.parameters` is
+ * **OpenAPI**, not JSON Schema, so `$ref` / `oneOf` / `additionalProperties`
+ * diverge silently; unsupported parameters are ignored rather than refused; and
+ * its documented response carries no cached- or reasoning-token counts. This
+ * adapter exists because every one of those is answerable on the native SDK:
+ * ADC refreshes itself, tools go over as JSON Schema untranslated
+ * (`parametersJsonSchema`), a forced single tool is expressible, and
+ * `usageMetadata` reports cached and thinking tokens as separate numbers.
+ *
+ * ─── Limitations (stated, not discovered) ───────────────────────────
+ *
+ * • Multi-modal input/output NOT supported — `LLMMessage.content` is `string`,
+ *   so this adapter sends and reads text parts only. Inline data, files and
+ *   generated images are out of scope for the port as it stands.
+ * • **Thought summaries are not requested.** `usage.thinking` is reported
+ *   honestly from `thoughtsTokenCount`, and `req.thinking.budget` is threaded
+ *   to `thinkingConfig.thinkingBudget` — but `includeThoughts` is deliberately
+ *   left unset, so no `rawThinking` is produced. Gemini's thought parts carry a
+ *   `thoughtSignature` that has to be echoed byte-exact on the next turn, and
+ *   there is no Gemini `ThinkingHandler` in this release to normalize and
+ *   round-trip them. Asking for content nothing can carry would be a leak, not
+ *   a feature. `thinkingConfig.thinkingLevel` has no field on `LLMRequest` and
+ *   is likewise not sent.
+ * • `responseJsonSchema` (native structured output) is NOT exposed; use
+ *   `.outputSchema(...)`, which goes over as a forced tool — a shape this
+ *   adapter DOES carry.
+ * • Grounding tools (Google Search, code execution, URL context, MCP servers)
+ *   are not exposed. `tools` carries function declarations only.
+ */
+import type { LLMCallHooks, LLMChunk, LLMProvider, LLMRequest, LLMResponse, WireRole } from '../types.js';
+import { type GoogleGenAIConnectionOptions } from './googleGenAI.js';
+/** One `parts[]` entry. Only the members this adapter reads or writes. */
+export interface GeminiPart {
+    readonly text?: string;
+    /** `true` on a thought-summary part. Never joined into visible content. */
+    readonly thought?: boolean;
+    readonly functionCall?: {
+        readonly id?: string;
+        readonly name?: string;
+        readonly args?: Record<string, unknown>;
+    };
+    readonly functionResponse?: {
+        readonly id?: string;
+        readonly name?: string;
+        readonly response?: Record<string, unknown>;
+    };
+}
+/** One conversation turn. Gemini's assistant role is spelled `'model'`. */
+export interface GeminiContent {
+    readonly role: 'user' | 'model';
+    readonly parts: readonly GeminiPart[];
+}
+/** A `FunctionDeclaration`, JSON-Schema flavour. */
+export interface GeminiFunctionDeclaration {
+    readonly name: string;
+    readonly description: string;
+    /**
+     * JSON Schema, passed through UNCHANGED. The sibling `parameters` field
+     * takes OpenAPI instead and is never set here — sending both is what makes
+     * an adapter's tool schemas quietly disagree with the ones it was given.
+     */
+    readonly parametersJsonSchema: Record<string, unknown>;
+}
+export interface GeminiGenerateConfig {
+    systemInstruction?: string;
+    temperature?: number;
+    maxOutputTokens?: number;
+    stopSequences?: string[];
+    abortSignal?: AbortSignal;
+    tools?: {
+        functionDeclarations: GeminiFunctionDeclaration[];
+    }[];
+    toolConfig?: {
+        functionCallingConfig: {
+            mode: 'AUTO' | 'ANY' | 'NONE';
+            allowedFunctionNames?: string[];
+        };
+    };
+    thinkingConfig?: {
+        thinkingBudget: number;
+    };
+}
+export interface GeminiGenerateParams {
+    readonly model: string;
+    readonly contents: readonly GeminiContent[];
+    readonly config?: GeminiGenerateConfig;
+}
+export interface GeminiUsageMetadata {
+    readonly promptTokenCount?: number;
+    readonly candidatesTokenCount?: number;
+    readonly cachedContentTokenCount?: number;
+    readonly thoughtsTokenCount?: number;
+    readonly totalTokenCount?: number;
+}
+export interface GeminiCandidate {
+    readonly content?: {
+        readonly parts?: readonly GeminiPart[];
+    };
+    readonly finishReason?: string;
+}
+export interface GeminiGenerateResponse {
+    readonly candidates?: readonly GeminiCandidate[];
+    readonly usageMetadata?: GeminiUsageMetadata;
+    readonly responseId?: string;
+}
+/**
+ * The `models` namespace, narrowed to the two operations this adapter
+ * dispatches.
+ *
+ * `countTokens` is deliberately ABSENT. It exists on the real namespace and it
+ * would be an easy way to fill in a usage number the wire did not report —
+ * which is precisely why it is not here. A count we asked for separately is not
+ * what the call was billed for; see the streaming note on `stream()`.
+ */
+export interface GeminiModelsLike {
+    generateContent(params: GeminiGenerateParams): Promise<GeminiGenerateResponse>;
+    /** Note the double await: the SDK returns a PROMISE of an async generator. */
+    generateContentStream(params: GeminiGenerateParams): Promise<AsyncIterable<GeminiGenerateResponse>>;
+}
+/** What `new GoogleGenAI(...)` gives us, narrowed to what we use. */
+export interface GeminiClientLike {
+    readonly models: GeminiModelsLike;
+}
+export interface GeminiProviderOptions extends GoogleGenAIConnectionOptions {
+    /**
+     * Default model used when `LLMRequest.model` is `'gemini'` (the shorthand).
+     * A request naming a full model id wins.
+     */
+    readonly defaultModel?: string;
+    /** Default `maxOutputTokens` when the request doesn't set it. Optional. */
+    readonly defaultMaxTokens?: number;
+    /** @internal Pre-built client for testing. Skips the SDK import entirely. */
+    readonly _client?: GeminiClientLike;
+}
+/**
+ * Build an `LLMProvider` backed by Gemini — on Vertex or on the Gemini API.
+ *
+ * @example  Vertex (Application Default Credentials)
+ * ```ts
+ * import { Agent } from 'agentfootprint';
+ * import { gemini } from 'agentfootprint/providers';
+ *
+ * const agent = Agent.create({
+ *   provider: gemini({ project: 'my-project', location: 'us-central1' }),
+ *   model: 'gemini',
+ * })
+ *   .tool(weatherTool)
+ *   .build();
+ * ```
+ *
+ * @example  Gemini API (one key, no cloud project)
+ * ```ts
+ * const provider = gemini({ apiKey: process.env.GEMINI_API_KEY });
+ * ```
+ *
+ * @throws at construction when neither a project nor an API key is resolvable,
+ *         and when `@google/genai` is not installed.
+ */
+export declare function gemini(options?: GeminiProviderOptions): LLMProvider;
+/**
+ * Class form for consumers who prefer `new GeminiProvider(...)` over the
+ * `gemini(...)` factory. Identical behavior; trivial wrapper.
+ */
+export declare class GeminiProvider implements LLMProvider {
+    readonly name = "gemini";
+    readonly carriesInMessages: readonly WireRole[];
+    readonly carriesForcedToolChoice = true;
+    private readonly inner;
+    constructor(options?: GeminiProviderOptions);
+    complete(req: LLMRequest, hooks?: LLMCallHooks): Promise<LLMResponse>;
+    stream(req: LLMRequest, hooks?: LLMCallHooks): AsyncIterable<LLMChunk>;
+}