@salesforce/sfdx-agent-sdk 0.20.0 → 0.22.0

package/dist/models/gpt-5-5.js

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { Model, ModelName } from './model.js';
+import { MimeType } from './types.js';
+/**
+ * GPT-5.5 is BETA on the gateway and gated behind the `AIModelBetaEnabled` org preference plus the
+ * `enableBetaModels` perm. Orgs without the gate active will receive a gateway error at request time.
+ */
+export class GPT55 extends Model {
+    name = ModelName.GPT_5_5;
+    displayId = 'GPT-5.5';
+    maxInputTokens = 1050000;
+    maxOutputTokens = 128000;
+    contextWindow = 1050000;
+    supportsPromptCache = false;
+    supportedFormats = [
+        { name: 'png', mimeType: MimeType.Png },
+        { name: 'jpeg', mimeType: MimeType.Jpeg },
+        { name: 'pdf', mimeType: MimeType.Pdf },
+    ];
+}
+//# sourceMappingURL=gpt-5-5.js.map

package/dist/models/gpt-5.d.ts

@@ -0,0 +1,11 @@
+import { Model, ModelName } from './model.js';
+import { type SupportedFileFormat } from './types.js';
+export declare class GPT5 extends Model {
+    readonly name: ModelName;
+    readonly displayId: string;
+    readonly maxInputTokens: number;
+    readonly maxOutputTokens: number;
+    readonly contextWindow: number;
+    readonly supportsPromptCache: boolean;
+    readonly supportedFormats: readonly SupportedFileFormat[];
+}

package/dist/models/gpt-5.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { Model, ModelName } from './model.js';
+import { MimeType } from './types.js';
+export class GPT5 extends Model {
+    name = ModelName.GPT_5;
+    displayId = 'GPT-5';
+    // Reference: https://help.salesforce.com/s/articleView?id=ai.generative_ai_llm_limits.htm&type=5
+    maxInputTokens = 272000;
+    maxOutputTokens = 128000;
+    contextWindow = 272000;
+    supportsPromptCache = false;
+    // Multimodal limits: 15 MiB total, 10 files / request (the global SDK caps bind).
+    // No per-format caps are set for OpenAI models — only the global caps apply.
+    supportedFormats = [
+        { name: 'png', mimeType: MimeType.Png },
+        { name: 'jpeg', mimeType: MimeType.Jpeg },
+        { name: 'pdf', mimeType: MimeType.Pdf },
+    ];
+}
+//# sourceMappingURL=gpt-5.js.map

package/dist/models/index.d.ts

@@ -0,0 +1,19 @@
+import { Model, ModelName } from './model.js';
+export { Model, ModelName } from './model.js';
+export { MimeType, type SupportedFileFormat, type MultimodalFile } from './types.js';
+export { validateMultimodalFiles, MAX_FILES_PER_REQUEST, MAX_TOTAL_FILE_BYTES } from './multimodal.js';
+export { GPT5 } from './gpt-5.js';
+export { GPT54 } from './gpt-5-4.js';
+export { GPT55 } from './gpt-5-5.js';
+export { ClaudeSonnet45 } from './claude-sonnet-4-5.js';
+export { ClaudeSonnet46 } from './claude-sonnet-4-6.js';
+export { ClaudeOpus45 } from './claude-opus-4-5.js';
+export { ClaudeOpus46 } from './claude-opus-4-6.js';
+export { ClaudeOpus47 } from './claude-opus-4-7.js';
+export { createClaudeModel, type ClaudeModelOverrides } from './create-claude-model.js';
+export declare function getDefault(): Model;
+export declare function getByName(modelName: ModelName): Model;
+export declare const Models: {
+    readonly getDefault: typeof getDefault;
+    readonly getByName: typeof getByName;
+};

package/dist/models/index.js

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { Model, ModelName } from './model.js';
+import { GPT5 } from './gpt-5.js';
+import { GPT54 } from './gpt-5-4.js';
+import { GPT55 } from './gpt-5-5.js';
+import { ClaudeSonnet45 } from './claude-sonnet-4-5.js';
+import { ClaudeSonnet46 } from './claude-sonnet-4-6.js';
+import { ClaudeOpus45 } from './claude-opus-4-5.js';
+import { ClaudeOpus46 } from './claude-opus-4-6.js';
+import { ClaudeOpus47 } from './claude-opus-4-7.js';
+export { Model, ModelName } from './model.js';
+export { MimeType } from './types.js';
+export { validateMultimodalFiles, MAX_FILES_PER_REQUEST, MAX_TOTAL_FILE_BYTES } from './multimodal.js';
+export { GPT5 } from './gpt-5.js';
+export { GPT54 } from './gpt-5-4.js';
+export { GPT55 } from './gpt-5-5.js';
+export { ClaudeSonnet45 } from './claude-sonnet-4-5.js';
+export { ClaudeSonnet46 } from './claude-sonnet-4-6.js';
+export { ClaudeOpus45 } from './claude-opus-4-5.js';
+export { ClaudeOpus46 } from './claude-opus-4-6.js';
+export { ClaudeOpus47 } from './claude-opus-4-7.js';
+export { createClaudeModel } from './create-claude-model.js';
+export function getDefault() {
+    return new ClaudeSonnet46();
+}
+export function getByName(modelName) {
+    if (modelName === ModelName.GPT_5)
+        return new GPT5();
+    if (modelName === ModelName.GPT_5_4)
+        return new GPT54();
+    if (modelName === ModelName.GPT_5_5)
+        return new GPT55();
+    if (modelName === ModelName.CLAUDE_SONNET_4_5)
+        return new ClaudeSonnet45();
+    if (modelName === ModelName.CLAUDE_SONNET_4_6)
+        return new ClaudeSonnet46();
+    if (modelName === ModelName.CLAUDE_OPUS_4_5)
+        return new ClaudeOpus45();
+    if (modelName === ModelName.CLAUDE_OPUS_4_6)
+        return new ClaudeOpus46();
+    if (modelName === ModelName.CLAUDE_OPUS_4_7)
+        return new ClaudeOpus47();
+    throw new Error(`No model mapping exists for "${modelName}".`);
+}
+export const Models = { getDefault, getByName };
+//# sourceMappingURL=index.js.map

package/dist/models/model.d.ts

@@ -0,0 +1,69 @@
+import type { SupportedFileFormat } from './types.js';
+/**
+ * The canonical Salesforce LLM-Gateway model ids the SDK ships in-tree.
+ * Consumer-built variants via {@link createClaudeModel} carry an arbitrary
+ * gateway id string (the escape hatch for Bedrock-Anthropic Claude
+ * variants the SDK has not released yet); cross-harness code that
+ * branches on `model.name` MUST guard with
+ * `Object.values(ModelName).includes(model.name)` before treating it as
+ * an enum-typed value — an exhaustive `switch` over `ModelName` will
+ * silently miss escape-hatch ids.
+ */
+export declare enum ModelName {
+    GPT_5 = "llmgateway__OpenAIGPT5",
+    GPT_5_4 = "llmgateway__OpenAIGPT54",
+    GPT_5_5 = "llmgateway__OpenAIGPT55",
+    CLAUDE_SONNET_4_5 = "llmgateway__BedrockAnthropicClaude45Sonnet",
+    CLAUDE_SONNET_4_6 = "llmgateway__BedrockAnthropicClaude46Sonnet",
+    CLAUDE_OPUS_4_5 = "llmgateway__BedrockAnthropicClaude45Opus",
+    CLAUDE_OPUS_4_6 = "llmgateway__BedrockAnthropicClaude46Opus",
+    CLAUDE_OPUS_4_7 = "llmgateway__BedrockAnthropicClaude47Opus"
+}
+/**
+ * Abstract description of a model the SDK / harness can talk to. Used for:
+ *
+ * - **Pre-flight multimodal validation.** `supportedFormats` is the
+ *   single source of truth for which file types this model accepts and
+ *   the per-format caps (`maxBytesPerFile`, `maxFilesPerRequest`).
+ * - **Context-window tracking.** `ChatSession.getContextUsage()` reads
+ *   `contextWindow` to compute "% of context used".
+ * - **Prompt-cache routing.** Anthropic-Claude-family models declare
+ *   `supportsPromptCache: true`; harnesses use the flag to enable cache
+ *   write/read on the wire.
+ *
+ * In-tree subclasses pin `name` to a {@link ModelName} enum member;
+ * instances built via {@link createClaudeModel} (the consumer-facing
+ * escape hatch for forward-compat with unreleased Bedrock-Claude
+ * variants) carry an arbitrary gateway id string.
+ *
+ * Reference: https://docs.internal.salesforce.com/ai/einstein/gateway/models-and-providers/
+ */
+export declare abstract class Model {
+    abstract readonly name: ModelName | string;
+    abstract readonly displayId: string;
+    abstract readonly maxInputTokens: number;
+    abstract readonly maxOutputTokens: number;
+    abstract readonly contextWindow: number;
+    abstract readonly supportsPromptCache: boolean;
+    /**
+     * The file formats this model accepts, with per-format limits. An
+     * empty array means the model is text-only.
+     */
+    abstract readonly supportedFormats: readonly SupportedFileFormat[];
+    readonly permittedParameters?: string[];
+    /**
+     * Vendor-specific HTTP headers to add to every outbound request for this model
+     * (e.g. `anthropic-version`, model-tag opt-in headers). Merged with the
+     * resolver-built header set before the request is sent.
+     *
+     * **Reserved headers cannot be overridden.** Both bundled connectivity
+     * resolvers (`DefaultAgentConnectivityResolver`, `ApiKeyConnectivityResolver`)
+     * spread `customHeaders` FIRST and resolver-set fields last, so any
+     * `Authorization`, `Content-Type`, `x-client-feature-id`, `x-sfdc-app-context`,
+     * or `x-sfdc-core-tenant-id` keys here are silently shadowed by the
+     * resolver's freshly-built values. Use `customHeaders` for vendor labels
+     * only — never for auth or tenancy. Custom resolvers should follow the
+     * same convention.
+     */
+    readonly customHeaders?: Record<string, string>;
+}

package/dist/models/model.js

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * The canonical Salesforce LLM-Gateway model ids the SDK ships in-tree.
+ * Consumer-built variants via {@link createClaudeModel} carry an arbitrary
+ * gateway id string (the escape hatch for Bedrock-Anthropic Claude
+ * variants the SDK has not released yet); cross-harness code that
+ * branches on `model.name` MUST guard with
+ * `Object.values(ModelName).includes(model.name)` before treating it as
+ * an enum-typed value — an exhaustive `switch` over `ModelName` will
+ * silently miss escape-hatch ids.
+ */
+export var ModelName;
+(function (ModelName) {
+    ModelName["GPT_5"] = "llmgateway__OpenAIGPT5";
+    ModelName["GPT_5_4"] = "llmgateway__OpenAIGPT54";
+    ModelName["GPT_5_5"] = "llmgateway__OpenAIGPT55";
+    ModelName["CLAUDE_SONNET_4_5"] = "llmgateway__BedrockAnthropicClaude45Sonnet";
+    ModelName["CLAUDE_SONNET_4_6"] = "llmgateway__BedrockAnthropicClaude46Sonnet";
+    ModelName["CLAUDE_OPUS_4_5"] = "llmgateway__BedrockAnthropicClaude45Opus";
+    ModelName["CLAUDE_OPUS_4_6"] = "llmgateway__BedrockAnthropicClaude46Opus";
+    ModelName["CLAUDE_OPUS_4_7"] = "llmgateway__BedrockAnthropicClaude47Opus";
+})(ModelName || (ModelName = {}));
+/**
+ * Abstract description of a model the SDK / harness can talk to. Used for:
+ *
+ * - **Pre-flight multimodal validation.** `supportedFormats` is the
+ *   single source of truth for which file types this model accepts and
+ *   the per-format caps (`maxBytesPerFile`, `maxFilesPerRequest`).
+ * - **Context-window tracking.** `ChatSession.getContextUsage()` reads
+ *   `contextWindow` to compute "% of context used".
+ * - **Prompt-cache routing.** Anthropic-Claude-family models declare
+ *   `supportsPromptCache: true`; harnesses use the flag to enable cache
+ *   write/read on the wire.
+ *
+ * In-tree subclasses pin `name` to a {@link ModelName} enum member;
+ * instances built via {@link createClaudeModel} (the consumer-facing
+ * escape hatch for forward-compat with unreleased Bedrock-Claude
+ * variants) carry an arbitrary gateway id string.
+ *
+ * Reference: https://docs.internal.salesforce.com/ai/einstein/gateway/models-and-providers/
+ */
+export class Model {
+    permittedParameters;
+    /**
+     * Vendor-specific HTTP headers to add to every outbound request for this model
+     * (e.g. `anthropic-version`, model-tag opt-in headers). Merged with the
+     * resolver-built header set before the request is sent.
+     *
+     * **Reserved headers cannot be overridden.** Both bundled connectivity
+     * resolvers (`DefaultAgentConnectivityResolver`, `ApiKeyConnectivityResolver`)
+     * spread `customHeaders` FIRST and resolver-set fields last, so any
+     * `Authorization`, `Content-Type`, `x-client-feature-id`, `x-sfdc-app-context`,
+     * or `x-sfdc-core-tenant-id` keys here are silently shadowed by the
+     * resolver's freshly-built values. Use `customHeaders` for vendor labels
+     * only — never for auth or tenancy. Custom resolvers should follow the
+     * same convention.
+     */
+    customHeaders;
+}
+//# sourceMappingURL=model.js.map

package/dist/models/multimodal.d.ts

@@ -0,0 +1,35 @@
+import type { Model } from './model.js';
+import type { MultimodalFile } from './types.js';
+/**
+ * Maximum total decoded byte size of all `files[]` in one request, across
+ * every model. Conservative SDK-side cap: the gateway's own raw-payload
+ * cap is ~30 MB which leaves room for envelope (headers, tool defs,
+ * prompt text), so 15 MiB of decoded files keeps every request inside
+ * the gateway's E30066 ceiling.
+ */
+export declare const MAX_TOTAL_FILE_BYTES: number;
+/**
+ * Maximum number of files in one request, across every model. Matches
+ * the gateway's E30065 cap.
+ */
+export declare const MAX_FILES_PER_REQUEST = 10;
+/**
+ * Pre-flight validation for multimodal `files[]` content. On failure
+ * throws {@link AgentSDKError} with type {@link AgentSDKErrorType.MULTIMODAL_NOT_SUPPORTED}
+ * and a message describing the specific cap or format violation. The
+ * single source of truth for multimodal caps and the MIME allowlist —
+ * both harnesses route their pre-stream `MessagePart[]` validation
+ * through this so the SDK guarantee "a file is accepted or rejected
+ * identically regardless of harness" holds.
+ *
+ * Fast return for text-only requests (no files).
+ *
+ * Validation order:
+ *   1. Global file count (≤ {@link MAX_FILES_PER_REQUEST}).
+ *   2. Per file: the model must declare the format, and the file must
+ *      fit its per-format byte cap.
+ *   3. Global total decoded size (≤ {@link MAX_TOTAL_FILE_BYTES}).
+ *   4. Per format: the file count for that format must fit its
+ *      per-format count cap.
+ */
+export declare function validateMultimodalFiles(files: readonly MultimodalFile[], model: Model): void;

package/dist/models/multimodal.js

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { AgentSDKError, AgentSDKErrorType } from '../errors.js';
+/**
+ * Maximum total decoded byte size of all `files[]` in one request, across
+ * every model. Conservative SDK-side cap: the gateway's own raw-payload
+ * cap is ~30 MB which leaves room for envelope (headers, tool defs,
+ * prompt text), so 15 MiB of decoded files keeps every request inside
+ * the gateway's E30066 ceiling.
+ */
+export const MAX_TOTAL_FILE_BYTES = 15 * 1024 * 1024;
+/**
+ * Maximum number of files in one request, across every model. Matches
+ * the gateway's E30065 cap.
+ */
+export const MAX_FILES_PER_REQUEST = 10;
+/**
+ * Approximate the decoded byte length of a base64 string without actually
+ * decoding. O(1) and within ≤ 2 bytes of the exact length for any
+ * well-formed base64. The gateway is the authority on malformed base64.
+ */
+function approximateBase64Bytes(data) {
+    return Math.floor(data.length * 0.75);
+}
+/**
+ * Pre-flight validation for multimodal `files[]` content. On failure
+ * throws {@link AgentSDKError} with type {@link AgentSDKErrorType.MULTIMODAL_NOT_SUPPORTED}
+ * and a message describing the specific cap or format violation. The
+ * single source of truth for multimodal caps and the MIME allowlist —
+ * both harnesses route their pre-stream `MessagePart[]` validation
+ * through this so the SDK guarantee "a file is accepted or rejected
+ * identically regardless of harness" holds.
+ *
+ * Fast return for text-only requests (no files).
+ *
+ * Validation order:
+ *   1. Global file count (≤ {@link MAX_FILES_PER_REQUEST}).
+ *   2. Per file: the model must declare the format, and the file must
+ *      fit its per-format byte cap.
+ *   3. Global total decoded size (≤ {@link MAX_TOTAL_FILE_BYTES}).
+ *   4. Per format: the file count for that format must fit its
+ *      per-format count cap.
+ */
+export function validateMultimodalFiles(files, model) {
+    if (files.length === 0) {
+        return;
+    }
+    if (files.length > MAX_FILES_PER_REQUEST) {
+        throw new AgentSDKError(`Too many files in request: ${files.length} exceeds the gateway cap of ${MAX_FILES_PER_REQUEST}.`, AgentSDKErrorType.MULTIMODAL_NOT_SUPPORTED);
+    }
+    let totalBytes = 0;
+    for (const file of files) {
+        const bytes = approximateBase64Bytes(file.data);
+        totalBytes += bytes;
+        const format = model.supportedFormats.find((f) => f.mimeType === file.mimeType);
+        if (!format) {
+            throw new AgentSDKError(`Model ${model.name} does not support files of type "${file.mimeType}".`, AgentSDKErrorType.MULTIMODAL_NOT_SUPPORTED);
+        }
+        if (format.maxBytesPerFile !== undefined && bytes > format.maxBytesPerFile) {
+            throw new AgentSDKError(`File of type "${file.mimeType}" exceeds the per-format cap for model ${model.name}: ${bytes} bytes > ${format.maxBytesPerFile} bytes.`, AgentSDKErrorType.MULTIMODAL_NOT_SUPPORTED);
+        }
+    }
+    if (totalBytes > MAX_TOTAL_FILE_BYTES) {
+        throw new AgentSDKError(`Total file size ${totalBytes} bytes exceeds the gateway cap of ${MAX_TOTAL_FILE_BYTES} bytes.`, AgentSDKErrorType.MULTIMODAL_NOT_SUPPORTED);
+    }
+    for (const format of model.supportedFormats) {
+        if (format.maxFilesPerRequest === undefined) {
+            continue;
+        }
+        const count = files.filter((f) => f.mimeType === format.mimeType).length;
+        if (count > format.maxFilesPerRequest) {
+            throw new AgentSDKError(`Too many files of type "${format.mimeType}" for model ${model.name}: ${count} exceeds the per-format cap of ${format.maxFilesPerRequest}.`, AgentSDKErrorType.MULTIMODAL_NOT_SUPPORTED);
+        }
+    }
+}
+//# sourceMappingURL=multimodal.js.map

package/dist/models/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * IANA MIME types accepted on the multimodal path.
+ *
+ * A file with any other `mimeType` is rejected pre-stream by
+ * {@link validateMultimodalFiles}. The set is intentionally narrow —
+ * Salesforce gateway-routed models accept these three; consumer-built
+ * models via {@link createClaudeModel} can declare any subset.
+ */
+export declare const MimeType: {
+    readonly Png: "image/png";
+    readonly Jpeg: "image/jpeg";
+    readonly Pdf: "application/pdf";
+};
+export type MimeType = (typeof MimeType)[keyof typeof MimeType];
+/**
+ * A file format a model accepts, with the per-format limits sourced from
+ * the model registry.
+ *
+ * A model's {@link Model.supportedFormats} array is the single source of
+ * truth for which file types it accepts and the per-format caps applied
+ * during pre-flight validation. An empty array means the model is
+ * text-only.
+ */
+export type SupportedFileFormat = {
+    /** Short registry name for the format. */
+    name: 'png' | 'jpeg' | 'pdf';
+    /** IANA media type sent on the wire as `mimeType`. */
+    mimeType: MimeType;
+    /**
+     * Optional per-format cap on the decoded size of any single file of
+     * this format (in bytes). When unset, only the global 15 MiB total
+     * cap applies.
+     */
+    maxBytesPerFile?: number;
+    /**
+     * Optional per-format cap on the number of files of this format in
+     * one request. When unset, only the global 10-file cap applies.
+     */
+    maxFilesPerRequest?: number;
+};
+/**
+ * The minimal file shape multimodal validation needs: a MIME type and the
+ * base64-encoded bytes. Harness callers (which hold SDK message parts,
+ * not full provider request shapes) can satisfy this directly.
+ */
+export type MultimodalFile = {
+    mimeType: string;
+    data: string;
+};

package/dist/models/types.js

@@ -0,0 +1,18 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * IANA MIME types accepted on the multimodal path.
+ *
+ * A file with any other `mimeType` is rejected pre-stream by
+ * {@link validateMultimodalFiles}. The set is intentionally narrow —
+ * Salesforce gateway-routed models accept these three; consumer-built
+ * models via {@link createClaudeModel} can declare any subset.
+ */
+export const MimeType = {
+    Png: 'image/png',
+    Jpeg: 'image/jpeg',
+    Pdf: 'application/pdf',
+};
+//# sourceMappingURL=types.js.map

package/dist/types/index.d.ts

@@ -2,3 +2,4 @@ export type { Message, MessageRole, MessagePart, TextPart, ReasoningPart, ToolCa
 export type { ChatEvent, StartEvent, TextDeltaEvent, ReasoningDeltaEvent, ToolCallEvent, ToolApprovalRequestEvent, ToolResultEvent, StepStartEvent, StepFinishEvent, ErrorEvent, FinishEvent, ChatStreamResult, } from './events.js';
 export type { ToolDefinition, ToolCallInfo, ToolResultInfo } from './tools.js';
 export type { UsageMetadata, FinishReason } from './usage.js';
+export type { ModelConnectivityInfo, ProviderHint } from './model-connectivity-info.js';

package/dist/types/model-connectivity-info.d.ts

@@ -0,0 +1,87 @@
+import type { Model } from '../models/index.js';
+/**
+ * Wire shape the harness should speak.
+ *
+ * The literal-union members are the wire shapes the SDK and its bundled
+ * harnesses recognize today; the trailing `string` allows forward-compat —
+ * a resolver can return a hint for a future provider without a same-day
+ * type bump in the SDK. Harnesses that don't recognize the value MUST
+ * throw `AgentSDKError(MODEL_NOT_SUPPORTED_BY_HARNESS)` rather than
+ * default to a wrong-shape builder.
+ */
+export type ProviderHint = 
+/** Anthropic Messages API direct (e.g. api.anthropic.com). */
+'anthropic'
+/** Anthropic Messages API via AWS Bedrock invoke. The Salesforce LLM
+ *  Gateway's `/invoke-with-response-stream` is this shape. */
+ | 'bedrock-anthropic'
+/** OpenAI Responses API direct (api.openai.com). */
+ | 'openai'
+/** OpenAI Responses API via the Salesforce LLM Gateway's `/responses`
+ *  pass-through endpoint. */
+ | 'openai-responses'
+/** OpenAI-compatible `/v1/chat/completions` (LLMG-Express, third-party
+ *  OpenAI-shape gateways). */
+ | 'openai-compatible'
+/** Forward-compat tail. Harnesses must validate against
+ *  `HarnessFactory.supportedProviderHints` and reject unknowns. */
+ | (string & {});
+/**
+ * The connectivity facts a harness needs to make an LLM request.
+ *
+ * Returned from {@link AgentConnectivityResolver.resolve} as part of
+ * {@link ResolvedConnectivity}. Five fields. Auth-kind branching lives
+ * inside `getHeaders()` — the harness never inspects whether the auth is
+ * a JWT, an API key, or anything else.
+ *
+ * The harness reads this bag per stream (Mastra: per HTTP call via a
+ * fetch wrapper that closes over a getter; Claude: once per subprocess
+ * spawn). Resolvers MUST treat the bag as live: each call to
+ * `getHeaders()` produces a fresh header map suitable for the *next*
+ * outbound request.
+ */
+export interface ModelConnectivityInfo {
+    /**
+     * Capability descriptor for the requested model. Used by harnesses
+     * for pre-flight multimodal validation (file format, file size,
+     * caps) and by the SDK for context-usage reporting.
+     */
+    readonly model: Model;
+    /**
+     * Provider-native or gateway base URL, with no trailing slash and
+     * no path beyond the gateway/provider's API root. Harnesses concat
+     * the path the wire shape requires.
+     */
+    readonly baseUrl: string;
+    /**
+     * Wire id the provider SDK should set on the request body's
+     * `model` field. May differ from `model.name` when the resolver
+     * points at a non-gateway endpoint (e.g. Anthropic-direct expects
+     * `claude-sonnet-4-6`; Salesforce gateway expects
+     * `llmgateway__BedrockAnthropicClaude46Sonnet`).
+     */
+    readonly nativeModelId: string;
+    /**
+     * Wire shape the harness should speak. The manager validates this
+     * against the harness's `supportedProviderHints` before any harness
+     * work begins; a harness only sees hints it recognizes.
+     */
+    readonly providerHint: ProviderHint;
+    /**
+     * Returns the FULL set of headers (Authorization included) for the
+     * NEXT outbound request to `baseUrl`.
+     *
+     * **Per-call invocation contract.** Mastra harnesses MUST call this
+     * on every HTTP call (inside their fetch wrapper). Claude harnesses
+     * MUST call this once per subprocess spawn and serialize the result
+     * into the env. Caching the returned map across requests is a bug —
+     * the resolver re-evaluates rotating credentials (JWT freshness,
+     * api-key swap, premium-rate-limit feature-id flip) on every call,
+     * and a cached map will go stale silently.
+     *
+     * Harnesses MUST tolerate `getHeaders` throwing: a thrown error
+     * propagates to the caller as a stream-time failure, identical to
+     * any other transport error.
+     */
+    getHeaders(): Promise<Record<string, string>>;
+}

package/dist/types/model-connectivity-info.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export {};
+//# sourceMappingURL=model-connectivity-info.js.map

package/dist/types/usage.d.ts

@@ -57,7 +57,7 @@ export type UsageMetadata = {
  *   are all `undefined` — making "no reading yet" indistinguishable from
  *   "harness reported every field as undefined."
  * - `contextWindow` is always populated, contractually. Every `Model`
- *   reachable via `Agent.llmGatewayClient.getModel()` must publish a
+ *   bound to an `Agent` via `ModelConnectivityInfo.model` must publish a
  *   `contextWindow`; see the `sfdx-agent-sdk` ARCHITECTURE.md Critical
  *   Invariant on this and issue #507.
  * - `usedFraction` is `undefined` iff every input-bearing field on the
@@ -77,8 +77,8 @@ export type ContextUsage = {
     usage: UsageMetadata;
     /**
      * The model's total context-window size in tokens. Read live at call
-     * time from the agent's currently-bound `LLMGatewayClient`, so it stays
-     * correct across `Agent.updateAgentConfig()` model swaps.
+     * time from the agent's currently-bound `ModelConnectivityInfo.model`,
+     * so it stays correct across `Agent.updateAgentConfig()` model swaps.
      */
     contextWindow: number;
     /**