agentfootprint 9.64.0 → 9.66.0

package/dist/esm/adapters/hosting/responsesWire.js

@@ -0,0 +1,316 @@
+/**
+ * adapters/hosting/responsesWire — the Responses protocol, as an `HttpWire`.
+ *
+ * ── What this is, and what it deliberately is not ────────────────────────────
+ * This file speaks the **Responses** wire protocol: a request carries `input`
+ * as text or as message items, a reply is a `response` object with an id and a
+ * status, and a stream is a LIFECYCLE of named events that open the response,
+ * announce output, carry deltas, and close each part before closing the
+ * response itself.
+ *
+ * That protocol is nobody's product. It is the shape a Responses-speaking
+ * client sends and expects, and several hosted runtimes speak it. So it lives
+ * here as a dialect on its own, and the runtimes that CONFIGURE it — their
+ * paths, their ports, their probe bodies, their session aliases — live in their
+ * own files beside this one. Keeping the split means the next runtime that
+ * speaks Responses is a configuration rather than a copy, and it means no
+ * vendor's spelling ends up in the protocol.
+ *
+ * ── The subset ───────────────────────────────────────────────────────────────
+ * A text turn, streamed or not, with a session. Deliberately not the whole
+ * Responses API: tool calls, reasoning items, image/file input, structured
+ * output and function-call output are NOT carried, and each is REFUSED by name
+ * rather than dropped — a request whose content this dialect cannot represent
+ * is answered 400 before a turn is paid for, never answered 200 with the parts
+ * it happened to understand.
+ *
+ * @example  A host that speaks Responses on paths of its own choosing
+ *   httpHost({
+ *     name: 'myResponsesHost',
+ *     wire: responsesWire({ defaultModel: 'my-agent' }),
+ *     invokePath: '/responses',
+ *     healthPath: '/health',
+ *   });
+ */
+import { randomUUID } from 'node:crypto';
+import { WireRequestRefusal } from '../../hosting/errors.js';
+/** Body fields that may carry a session id, in the order they are consulted. */
+export const DEFAULT_SESSION_FIELDS = ['conversation', 'session_id'];
+/**
+ * What a caller is told when a handler THREW.
+ *
+ * A thrown error's message is the author's note to their own logs — a query, a
+ * path, a token in a connection string — and none of it is the caller's. A
+ * handler that CHOSE to fail chose its words for the caller, so those travel
+ * unchanged. The host tells this dialect which happened; it never guesses from
+ * the message.
+ */
+export const PUBLIC_FAILURE_MESSAGE = 'The agent could not complete this request.';
+const DEFAULT_MODEL = 'agentfootprint';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+/**
+ * The text of one message's content, or a refusal naming what was in it.
+ *
+ * Every non-text part is refused rather than skipped: a resume with an attached
+ * image, silently reduced to the text around it, is a wrong answer delivered
+ * confidently.
+ */
+function inputTextFromContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content)) {
+        throw new WireRequestRefusal('unsupported_input', 'message content must be text or an array of input_text parts');
+    }
+    const text = [];
+    for (const part of content) {
+        if (!isRecord(part) || part.type !== 'input_text' || typeof part.text !== 'string') {
+            const kind = isRecord(part) && typeof part.type === 'string' ? part.type : 'unknown';
+            throw new WireRequestRefusal('unsupported_input', `this dialect carries text input only; '${kind}' input is not supported`);
+        }
+        text.push(part.text);
+    }
+    return text.join('');
+}
+/** The turn's text: a bare string, or the user message items that carry it. */
+export function readResponsesInput(input) {
+    if (typeof input === 'string')
+        return input;
+    if (input === undefined || input === null) {
+        throw new WireRequestRefusal('invalid_input', 'input is required');
+    }
+    if (!Array.isArray(input)) {
+        throw new WireRequestRefusal('invalid_input', 'input must be text or an array of Responses message items');
+    }
+    const messages = [];
+    for (const item of input) {
+        if (!isRecord(item)) {
+            throw new WireRequestRefusal('invalid_input', 'each input item must be an object');
+        }
+        // `type` is optional in the Responses grammar for a plain message.
+        if (item.type !== undefined && item.type !== 'message') {
+            throw new WireRequestRefusal('unsupported_input', `this dialect carries message items only; '${String(item.type)}' items are not supported`);
+        }
+        if (item.role !== 'user') {
+            throw new WireRequestRefusal('unsupported_input', `this dialect carries user messages only; role '${String(item.role)}' is not supported`);
+        }
+        messages.push(inputTextFromContent(item.content));
+    }
+    return messages.join('\n\n');
+}
+/** The session this request claims, by whichever of its aliases it used. */
+export function readResponsesSession(body, fields) {
+    for (const field of fields) {
+        const value = body[field];
+        // `conversation` is an object in the Responses grammar and a bare string in
+        // several dialects of it. Both are read, because refusing the spelling a
+        // client already sends teaches nothing.
+        const found = isRecord(value) ? nonEmptyString(value.id) : nonEmptyString(value);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+function identityFor(facts, options) {
+    const body = facts?.body ?? {};
+    const nonce = randomUUID().replaceAll('-', '');
+    return {
+        responseId: `resp_${nonce}`,
+        messageId: `msg_${nonce}`,
+        createdAt: Math.floor(Date.now() / 1000),
+        model: nonEmptyString(body.model) ?? options.defaultModel,
+        sessionId: readResponsesSession(body, options.sessionFields),
+    };
+}
+function outputPart(text) {
+    return { type: 'output_text', text, annotations: [], logprobs: [] };
+}
+function outputItem(identity, text, status) {
+    return {
+        id: identity.messageId,
+        type: 'message',
+        status,
+        role: 'assistant',
+        content: status === 'completed' ? [outputPart(text)] : [],
+    };
+}
+function responseObject(identity, status, text = '', error = null) {
+    return {
+        id: identity.responseId,
+        object: 'response',
+        created_at: identity.createdAt,
+        status,
+        error,
+        incomplete_details: null,
+        instructions: null,
+        parallel_tool_calls: true,
+        model: identity.model,
+        output: status === 'completed' ? [outputItem(identity, text, 'completed')] : [],
+        conversation: identity.sessionId === undefined ? null : { id: identity.sessionId },
+        usage: null,
+    };
+}
+/**
+ * What a caller may be told about a failure.
+ *
+ * A refusal this library authored carries a `code` and says what it says. A
+ * handler that threw carries none, and its words do not travel.
+ */
+function errorBody(message, code, origin) {
+    if (origin === 'threw') {
+        return { code: 'server_error', message: PUBLIC_FAILURE_MESSAGE, type: 'server_error' };
+    }
+    return code === undefined
+        ? { code: 'server_error', message, type: 'server_error' }
+        : { code, message, type: 'invalid_request_error' };
+}
+/**
+ * The nine-event lifecycle one streamed response is made of.
+ *
+ * Holds this response's identity and its sequence counter, which is why it is
+ * built per request: two callers sharing a counter would each see a stream that
+ * skips numbers, and two sharing an id would see each other's response.
+ */
+function responsesFraming(identity) {
+    let sequence = 0;
+    let outputStarted = false;
+    let streamed = '';
+    let sawDelta = false;
+    const frame = (event, fields) => ({
+        event,
+        data: { type: event, sequence_number: sequence++, ...fields },
+    });
+    /**
+     * The two frames that must precede any text. Emitted on the first delta
+     * rather than at open, because a response that fails before producing a word
+     * never opened an output item and should not claim it did.
+     */
+    const begin = () => {
+        if (outputStarted)
+            return [];
+        outputStarted = true;
+        return [
+            frame('response.output_item.added', {
+                output_index: 0,
+                item: outputItem(identity, '', 'in_progress'),
+            }),
+            frame('response.content_part.added', {
+                item_id: identity.messageId,
+                output_index: 0,
+                content_index: 0,
+                part: outputPart(''),
+            }),
+        ];
+    };
+    const delta = (text) => {
+        if (text === '')
+            return [];
+        const frames = begin();
+        sawDelta = true;
+        streamed += text;
+        frames.push(frame('response.output_text.delta', {
+            item_id: identity.messageId,
+            output_index: 0,
+            content_index: 0,
+            delta: text,
+            logprobs: [],
+        }));
+        return frames;
+    };
+    return {
+        open: () => [
+            frame('response.created', { response: responseObject(identity, 'in_progress') }),
+            frame('response.in_progress', { response: responseObject(identity, 'in_progress') }),
+        ],
+        chunk: (text) => delta(text),
+        complete: (output) => {
+            const frames = [];
+            // A handler that streamed nothing still owes the caller its text, and one
+            // that streamed a PREFIX of it owes the rest. Anything else — a final
+            // output that contradicts what was streamed — is left as it was streamed:
+            // frames already on the wire cannot be taken back, and re-sending the
+            // whole text would duplicate what the caller already rendered.
+            if (!sawDelta)
+                frames.push(...delta(output));
+            else if (output.startsWith(streamed) && output.length > streamed.length) {
+                frames.push(...delta(output.slice(streamed.length)));
+            }
+            frames.push(...begin());
+            // THE COMPLETION IS AUTHORITATIVE — this library's law, and it outranks
+            // the protocol's own tidiness. When a handler's chunks were a preview of
+            // different final text rather than a prefix of it, the deltas already on
+            // the wire cannot be recalled, and this reports the ANSWER rather than
+            // the preview. The two then disagree, which is a documented limit of
+            // streaming a preview; reporting the preview as the answer would be a
+            // wrong answer, which is not.
+            const text = output;
+            frames.push(frame('response.output_text.done', {
+                item_id: identity.messageId,
+                output_index: 0,
+                content_index: 0,
+                text,
+                logprobs: [],
+            }), frame('response.content_part.done', {
+                item_id: identity.messageId,
+                output_index: 0,
+                content_index: 0,
+                part: outputPart(text),
+            }), frame('response.output_item.done', {
+                output_index: 0,
+                item: outputItem(identity, text, 'completed'),
+            }), frame('response.completed', { response: responseObject(identity, 'completed', text) }));
+            return frames;
+        },
+        failure: (message, code, origin) => [
+            frame('response.failed', {
+                response: responseObject(identity, 'failed', '', errorBody(message, code, origin)),
+            }),
+        ],
+    };
+}
+/**
+ * An `HttpWire` speaking the Responses protocol.
+ *
+ * Pair it with `httpHost` and the paths your deployment contract names. The
+ * host keeps its own promises — draining, aborting on disconnect, failing a
+ * handler that throws or answers nothing — and this supplies only the dialect.
+ */
+export function responsesWire(options = {}) {
+    const resolved = {
+        defaultModel: options.defaultModel ?? DEFAULT_MODEL,
+        sessionFields: options.sessionFields ?? DEFAULT_SESSION_FIELDS,
+    };
+    const health = options.health ?? { status: 'ok' };
+    return {
+        readRequest(facts) {
+            const input = readResponsesInput(facts.body.input);
+            if (input.trim() === '') {
+                throw new WireRequestRefusal('invalid_input', 'input text must not be empty');
+            }
+            const sessionId = readResponsesSession(facts.body, resolved.sessionFields);
+            return { input, ...(sessionId === undefined ? {} : { sessionId }) };
+        },
+        // This dialect's callers choose in the body and never touch `Accept`.
+        wantsStream: (facts) => facts.body.stream === true,
+        stream: (facts) => responsesFraming(identityFor(facts, resolved)),
+        health: () => health,
+        output: (output, facts) => responseObject(identityFor(facts, resolved), 'completed', output),
+        chunk: (text) => ({ type: 'response.output_text.delta', delta: text }),
+        failure: (message, code, facts, origin) => {
+            // A terminal that ended an ACCEPTED response is reported as a failed
+            // response object — that is what the protocol says a response that got
+            // as far as running and then stopped looks like. A coded refusal ended
+            // the REQUEST before any of that, and gets the error envelope a client
+            // reads off a 4xx.
+            if (code === undefined) {
+                return responseObject(identityFor(facts, resolved), 'failed', '', errorBody(message, undefined, origin));
+            }
+            return { error: errorBody(message, code, origin) };
+        },
+    };
+}
+//# sourceMappingURL=responsesWire.js.map

package/dist/esm/adapters/hosting/responsesWire.js.map

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

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

@@ -103,7 +103,7 @@ export interface AgentCoreIdentityClientLike {
     getResourceOauth2Token(input: {
         readonly resourceCredentialProviderName: string;
         readonly scopes: readonly string[];
-        readonly oauth2Flow: 'M2M' | 'USER_FEDERATION';
+        readonly oauth2Flow: 'M2M' | 'USER_FEDERATION' | 'ON_BEHALF_OF_TOKEN_EXCHANGE';
         readonly forceAuthentication: boolean;
         readonly workloadIdentityToken?: string;
     }): Promise<AgentCoreOauthResponse>;
@@ -126,6 +126,25 @@ export interface AgentCoreIdentityClientLike {
     }): Promise<{
         readonly workloadAccessToken?: string;
     }>;
+    /** Optional — required only for services named in `apiKeyServices`. AgentCore
+     *  keeps API keys in the same vault as OAuth tokens, behind a different
+     *  operation, so this is a sibling of `getResourceOauth2Token` rather than a
+     *  mode of it. */
+    getResourceApiKey?(input: {
+        readonly resourceCredentialProviderName: string;
+        /** REQUIRED on the wire — `GetResourceApiKeyRequest` declares it non-optional. */
+        readonly workloadIdentityToken: string;
+    }): Promise<{
+        readonly apiKey?: string;
+    }>;
+    /** Optional — required only by {@link completeAgentCoreAuthorization}. Tells
+     *  AgentCore that the person behind `sessionId` finished consenting, which is
+     *  what releases the token into the vault for the next vend. */
+    completeResourceTokenAuth?(input: {
+        readonly sessionId: string;
+        readonly userToken?: string;
+        readonly userId?: string;
+    }): Promise<void>;
 }
 export interface AgentCoreIdentityOptions {
     readonly region?: string;
@@ -165,6 +184,42 @@ export interface AgentCoreIdentityOptions {
         readonly principal?: string;
         readonly tenant?: string;
     }) => string | undefined;
+    /**
+     * How a `mode: 'user'` request gets its token (9.66.0). Default `'consent'`.
+     *
+     *   `'consent'`  — AgentCore's `USER_FEDERATION`. If the vault has no grant
+     *                  for this (workload, user), the result is an
+     *                  `authorization-required` with a URL to send the person to.
+     *                  They approve once; later calls return a token directly.
+     *   `'exchange'` — AgentCore's `ON_BEHALF_OF_TOKEN_EXCHANGE`. The person's
+     *                  own login is TRADED for a scoped downstream token, with no
+     *                  consent screen at any point.
+     *
+     * `'exchange'` is not simply the nicer one. It works only where the
+     * downstream provider was configured for it (an on-behalf-of exchange grant
+     * on the credential provider) and where trading the user's session for
+     * downstream access is a decision your organisation has already made — the
+     * consent screen is what asks the person, and this flow is the deployment
+     * saying it does not need to. Choose it deliberately.
+     *
+     * `mode: 'machine'` is unaffected: M2M has no user to act for.
+     */
+    readonly userFlow?: 'consent' | 'exchange';
+    /**
+     * Services whose credential is an API KEY, not an OAuth token (9.66.0).
+     *
+     * AgentCore's vault holds both kinds behind two different operations, and the
+     * provider NAME alone does not say which — so a request for a service named
+     * here is vended with `GetResourceApiKey` and comes back as an
+     * {@link apiKey} credential. Everything else takes the OAuth path.
+     *
+     * There is no auto-detection on purpose: guessing would mean calling one
+     * operation, catching a failure, and retrying with the other, which turns a
+     * configuration mistake into two round-trips and an ambiguous error.
+     */
+    readonly apiKeyServices?: readonly string[];
+    /** Header an API-key credential is sent in. Default `'x-api-key'`. */
+    readonly apiKeyHeader?: string;
     /** Stable provider id (default 'agentcore-identity'). */
     readonly id?: string;
     /** Test seam — inject a client implementing {@link AgentCoreIdentityClientLike}.
@@ -184,6 +239,65 @@ export interface BedrockAgentCoreIdentitySdkModule {
     readonly GetResourceOauth2TokenCommand?: new (input: unknown) => unknown;
     readonly GetWorkloadAccessTokenForUserIdCommand?: new (input: unknown) => unknown;
     readonly GetWorkloadAccessTokenForJWTCommand?: new (input: unknown) => unknown;
+    readonly GetResourceApiKeyCommand?: new (input: unknown) => unknown;
+    readonly CompleteResourceTokenAuthCommand?: new (input: unknown) => unknown;
 }
 /** Build a {@link CredentialProvider} backed by AWS Bedrock AgentCore Identity. */
 export declare function agentCoreIdentity(options?: AgentCoreIdentityOptions): CredentialProvider;
+/** Connection options for {@link completeAgentCoreAuthorization}. */
+export interface CompleteAgentCoreAuthorizationOptions {
+    /** The 3LO round-trip this completes — the `sessionId` from the
+     *  `authorization-required` result the agent returned. */
+    readonly sessionId: string;
+    /** The person's own IdP-issued JWT, if your callback has it. Preferred: it is
+     *  the artifact their provider signed. */
+    readonly userToken?: string;
+    /** The user id you asserted for them, when no JWT is available. Exactly one
+     *  of `userToken` / `userId` is required. */
+    readonly userId?: string;
+    readonly region?: string;
+    /** Test seam — same client surface the provider uses. */
+    readonly _client?: AgentCoreIdentityClientLike;
+    /** @internal Test injection — the AWS SDK module. */
+    readonly _sdk?: BedrockAgentCoreIdentitySdkModule;
+}
+/**
+ * Tell AgentCore the person finished consenting, so the token lands in the vault.
+ *
+ * ── Where this runs, and why it is not a provider method ─────────────────────
+ * A 3LO consent has three actors and two processes. The agent asks for a
+ * credential and gets back `authorization-required` with a URL and a session
+ * id; the PERSON opens that URL in their browser and approves; AgentCore then
+ * redirects their browser to a callback route **your web app** owns. That route
+ * is where this belongs — a different process from the agent run, often a
+ * different service — so it takes its own connection options rather than
+ * pretending to be a method on a provider that route has never seen.
+ *
+ * Your route's job before calling this is the part nobody else can do: confirm
+ * the browser session really belongs to the user you are about to name. This
+ * function is the handshake, not the authentication.
+ *
+ * ── After it returns ─────────────────────────────────────────────────────────
+ * Nothing is handed back — success is an empty acknowledgement. The token now
+ * exists in the vault for that (workload, user), and the way to obtain it is to
+ * run the agent's request again: the next `getCredential` for that service
+ * returns `issued` where the last one returned `authorization-required`. In
+ * agentfootprint terms the consent is a PAUSE, and this is what makes the
+ * resume succeed.
+ *
+ * The authorization URL and its session are short-lived (AWS documents ten
+ * minutes) — a person who wanders off has to start the consent again, and the
+ * refusal you get is AgentCore's, not this adapter's.
+ *
+ * @example  An Express-style callback route
+ *   app.get('/oauth/callback', async (req, res) => {
+ *     const user = await requireSignedInUser(req);   // yours, and load-bearing
+ *     await completeAgentCoreAuthorization({
+ *       sessionId: String(req.query.session),
+ *       userId: user.id,
+ *       region: 'us-east-1',
+ *     });
+ *     res.send('Approved — you can return to the assistant.');
+ *   });
+ */
+export declare function completeAgentCoreAuthorization(options: CompleteAgentCoreAuthorizationOptions): Promise<void>;

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

@@ -83,7 +83,7 @@
  * `getCredential` first runs (or never, if you inject `_client` / `_sdk`).
  */
 import { lazyRequire } from '../../lib/lazyRequire.js';
-import { bearer } from '../../identity/kinds.js';
+import { apiKey, bearer } from '../../identity/kinds.js';
 /**
  * Re-raise a failed SDK call **without its text** (9.12.0).
  *
@@ -220,6 +220,20 @@ function createIdentityClient(options) {
         async getWorkloadAccessTokenForUserId(input) {
             return ((await send(mod.GetWorkloadAccessTokenForUserIdCommand, 'GetWorkloadAccessTokenForUserIdCommand', input)) ?? {});
         },
+        async getResourceApiKey(input) {
+            const r = (await send(mod.GetResourceApiKeyCommand, 'GetResourceApiKeyCommand', input));
+            return { ...(r?.apiKey !== undefined && { apiKey: r.apiKey }) };
+        },
+        async completeResourceTokenAuth(input) {
+            // `CompleteResourceTokenAuthRequest` is `{ sessionUri, userIdentifier }`,
+            // where userIdentifier is a UNION with exactly one member set — the
+            // person's own token, or the id the agent asserts for them. Success is an
+            // empty 200, so there is nothing to map back.
+            await send(mod.CompleteResourceTokenAuthCommand, 'CompleteResourceTokenAuthCommand', {
+                sessionUri: input.sessionId,
+                userIdentifier: input.userToken !== undefined ? { userToken: input.userToken } : { userId: input.userId },
+            });
+        },
         async getWorkloadAccessTokenForJWT(input) {
             // `GetWorkloadAccessTokenForJWTRequest` is `{ workloadName, userToken }`,
             // both required, and the response is `{ workloadAccessToken }` — verified
@@ -307,14 +321,50 @@ export function agentCoreIdentity(options = {}) {
         }
         return requireWorkloadAccessToken(await c.getWorkloadAccessTokenForUserId({ workloadName: options.workloadName, userId }), 'GetWorkloadAccessTokenForUserId');
     };
+    const userFlow = options.userFlow ?? 'consent';
+    const apiKeyServices = new Set(options.apiKeyServices ?? []);
+    const apiKeyHeader = options.apiKeyHeader ?? 'x-api-key';
     return {
         id: options.id ?? 'agentcore-identity',
         async getCredential(req) {
             const workloadIdentityToken = await resolveWorkloadToken(req);
+            // An API-key service never touches the OAuth path: different operation,
+            // different credential kind, and no consent round-trip exists for it.
+            if (apiKeyServices.has(req.service)) {
+                const c = getClient();
+                if (!c.getResourceApiKey) {
+                    throw new Error(`agentCoreIdentity: '${req.service}' is listed in \`apiKeyServices\` but the ` +
+                        'injected `_client` has no getResourceApiKey. Implement it, or drop the service ' +
+                        'from the list to vend it as OAuth.');
+                }
+                if (!workloadIdentityToken) {
+                    // Required on `GetResourceApiKeyRequest`, exactly as on the OAuth
+                    // call — verified against the real SDK's types, not assumed. Sending
+                    // without one buys an opaque ValidationException; this names the two
+                    // ways to supply it instead.
+                    throw new Error(`agentCoreIdentity: GetResourceApiKey for '${req.service}' requires a workload ` +
+                        'identity token, and none was available for this request.\n' +
+                        '  Inside AgentCore Runtime the container is given one — pass it as ' +
+                        '`workloadIdentityToken`.\n' +
+                        '  Elsewhere, configure `workloadName` so a per-user token is resolved first.');
+                }
+                const keyRes = await c.getResourceApiKey({
+                    resourceCredentialProviderName: req.service,
+                    workloadIdentityToken,
+                });
+                if (!keyRes.apiKey) {
+                    throw new Error(`agentCoreIdentity: GetResourceApiKey for '${req.service}' returned no key.`);
+                }
+                return { status: 'issued', credential: apiKey(keyRes.apiKey, apiKeyHeader) };
+            }
             const res = await getClient().getResourceOauth2Token({
                 resourceCredentialProviderName: req.service,
                 scopes: req.scopes ?? [],
-                oauth2Flow: req.mode === 'user' ? 'USER_FEDERATION' : 'M2M',
+                oauth2Flow: req.mode === 'user'
+                    ? userFlow === 'exchange'
+                        ? 'ON_BEHALF_OF_TOKEN_EXCHANGE'
+                        : 'USER_FEDERATION'
+                    : 'M2M',
                 forceAuthentication: req.forceReauth ?? false,
                 ...(workloadIdentityToken && { workloadIdentityToken }),
             });
@@ -338,4 +388,69 @@ export function agentCoreIdentity(options = {}) {
         },
     };
 }
+/**
+ * Tell AgentCore the person finished consenting, so the token lands in the vault.
+ *
+ * ── Where this runs, and why it is not a provider method ─────────────────────
+ * A 3LO consent has three actors and two processes. The agent asks for a
+ * credential and gets back `authorization-required` with a URL and a session
+ * id; the PERSON opens that URL in their browser and approves; AgentCore then
+ * redirects their browser to a callback route **your web app** owns. That route
+ * is where this belongs — a different process from the agent run, often a
+ * different service — so it takes its own connection options rather than
+ * pretending to be a method on a provider that route has never seen.
+ *
+ * Your route's job before calling this is the part nobody else can do: confirm
+ * the browser session really belongs to the user you are about to name. This
+ * function is the handshake, not the authentication.
+ *
+ * ── After it returns ─────────────────────────────────────────────────────────
+ * Nothing is handed back — success is an empty acknowledgement. The token now
+ * exists in the vault for that (workload, user), and the way to obtain it is to
+ * run the agent's request again: the next `getCredential` for that service
+ * returns `issued` where the last one returned `authorization-required`. In
+ * agentfootprint terms the consent is a PAUSE, and this is what makes the
+ * resume succeed.
+ *
+ * The authorization URL and its session are short-lived (AWS documents ten
+ * minutes) — a person who wanders off has to start the consent again, and the
+ * refusal you get is AgentCore's, not this adapter's.
+ *
+ * @example  An Express-style callback route
+ *   app.get('/oauth/callback', async (req, res) => {
+ *     const user = await requireSignedInUser(req);   // yours, and load-bearing
+ *     await completeAgentCoreAuthorization({
+ *       sessionId: String(req.query.session),
+ *       userId: user.id,
+ *       region: 'us-east-1',
+ *     });
+ *     res.send('Approved — you can return to the assistant.');
+ *   });
+ */
+export async function completeAgentCoreAuthorization(options) {
+    if (!options.sessionId) {
+        throw new Error('completeAgentCoreAuthorization: `sessionId` is required — it is the `sessionId` from ' +
+            'the `authorization-required` result that started this consent.');
+    }
+    if ((options.userToken === undefined) === (options.userId === undefined)) {
+        // Both or neither. Naming a person twice is ambiguous; naming them zero
+        // times completes a consent for nobody.
+        throw new Error('completeAgentCoreAuthorization: pass exactly one of `userToken` (the person’s own JWT, ' +
+            'preferred) or `userId` (an id you assert for them).');
+    }
+    const client = options._client ??
+        createIdentityClient({
+            ...(options.region !== undefined && { region: options.region }),
+            ...(options._sdk !== undefined && { _sdk: options._sdk }),
+        });
+    if (!client.completeResourceTokenAuth) {
+        throw new Error('completeAgentCoreAuthorization: the injected `_client` has no ' +
+            'completeResourceTokenAuth. Implement it, or omit `_client` to use the SDK.');
+    }
+    await client.completeResourceTokenAuth({
+        sessionId: options.sessionId,
+        ...(options.userToken !== undefined && { userToken: options.userToken }),
+        ...(options.userId !== undefined && { userId: options.userId }),
+    });
+}
 //# sourceMappingURL=agentcore.js.map