@theokit/sdk 0.0.0-compat-580-20260905204608

package/dist/internal/agent-loop/tool-dispatch.d.ts

@@ -0,0 +1,27 @@
+import type { SDKMessage } from "../../types/messages.js";
+import type { LlmContentPart, LlmToolCallPart } from "../llm/types.js";
+import type { AgentLoopInputs, ResolvedTool } from "./types.js";
+export type { ResolvedTool } from "./types.js";
+/**
+ * T2.4 — Parallel tool dispatch with bounded concurrency (DR2 finding #4).
+ *
+ * Pre-T2.4 this was a serial `for...of` loop — each tool call awaited
+ * before the next. With N independent tools each taking Tms, total
+ * wall-clock was N×Tms. T2.4 switches to `Promise.all` with bounded
+ * concurrency via an inline semaphore (ADR D135 — in-house, no
+ * `p-limit` dep). Default cap is 4 concurrent tools; consumer
+ * overrides via `AgentLoopInputs.maxConcurrentTools`.
+ *
+ * Order preservation: `Promise.all` preserves input order in the
+ * resolved array regardless of which promise settles first — the
+ * LLM expects tool results in call order and this contract holds.
+ *
+ * Event array safety: `events` is append-only. In single-threaded
+ * JS (Node event loop), concurrent `.push()` calls from different
+ * microtask continuations do NOT interleave — each push is atomic.
+ * The order of events across tools becomes non-deterministic, but
+ * each individual tool's events are internally ordered.
+ */
+export declare function dispatchTools(inputs: AgentLoopInputs, tools: ResolvedTool[], toolCalls: LlmToolCallPart[], events: SDKMessage[], parentSpan?: ToolSpan): Promise<LlmContentPart[]>;
+/** M3 #64 — the OTel span type threaded for tool-span nesting. */
+type ToolSpan = ReturnType<NonNullable<AgentLoopInputs["telemetry"]>["startSpan"]> | undefined;

package/dist/internal/agent-loop/tool-executors.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/agent-loop/tool-result-guard.d.ts

@@ -0,0 +1,20 @@
+/**
+ * #57 — content-level defense for tool results before they reach the LLM.
+ *
+ * Two opt-in behaviors, applied at the `transform_tool_result` seam (#65):
+ *  - `delimit`: wrap untrusted tool output in explicit data boundaries
+ *    ("spotlighting") so the model treats it as DATA, not instructions — the
+ *    primary mitigation against tool-result prompt injection. Non-destructive:
+ *    the content is preserved, only framed. A boundary marker appearing inside
+ *    the content is neutralized so it cannot break out of the frame.
+ *  - `redactPii`: replace common PII patterns (email, phone) with `[REDACTED]`.
+ *
+ * @internal
+ */
+import type { LlmContentPart } from "../llm/types.js";
+export type { ToolResultGuardOptions } from "../../types/run.js";
+/**
+ * Apply the tool-result guard to the tool_result parts of a content array. When
+ * neither behavior is enabled the array is returned unchanged (zero overhead).
+ */
+export declare function applyToolResultGuard(parts: readonly LlmContentPart[], opts: ToolResultGuardOptions): LlmContentPart[];

package/dist/internal/agent-loop/tool-timeout.d.ts

@@ -0,0 +1,23 @@
+/**
+ * #58 — bound a single tool execution by the run's cancellation signal and an
+ * optional per-tool timeout, so a hung tool cannot wedge the agent loop and a
+ * cancelled run interrupts an in-flight tool.
+ *
+ * Stdlib only (`AbortSignal.any` / `AbortSignal.timeout`, Node ≥22.12).
+ *
+ * @internal
+ */
+export interface ToolRaceOptions {
+    /** The run's cancellation signal (`AgentLoopInputs.signal`). */
+    signal?: AbortSignal;
+    /** Per-tool timeout in ms. Omit for no timeout. */
+    timeoutMs?: number;
+}
+/**
+ * Race a tool execution against cancellation + an optional timeout. Returns the
+ * tool's result if it finishes first, or a typed aborted/timed-out `ToolResult`
+ * (exit 124) if the run is cancelled or the per-tool deadline elapses. When
+ * neither a signal nor a timeout is supplied, the execution is returned as-is
+ * (zero overhead, backward-compatible).
+ */
+export declare function raceToolExecution(exec: Promise<ToolResult>, opts: ToolRaceOptions): Promise<ToolResult>;

package/dist/internal/agent-loop/types.d.ts

@@ -0,0 +1,43 @@
+import type { ConversationTurn } from "../../types/conversation.js";
+import type { SDKMessage } from "../../types/messages.js";
+import type { RunStatus } from "../../types/run.js";
+/** SE7 — what a custom tool handler may return: a string or structured content blocks. */
+export type ToolHandlerResult = string | import("../../types/content-blocks.js").ToolResultContentBlock[];
+export interface AgentLoopOutput {
+    events: SDKMessage[];
+    finalStatus: RunStatus;
+    result: string;
+    conversation: ConversationTurn[];
+    /**
+     * Aggregated token usage across every LLM call in this loop (ADR D376).
+     * Populated whenever ≥1 LLM call completed — including partial-failure
+     * runs (EC-5). Undefined when zero LLM calls fired (e.g., abort before
+     * first send, or fixture-mode path that bypasses this loop).
+     */
+    usage?: import("../../types/usage.js").TokenUsage;
+    /**
+     * Inferred pricing-based cost matching `usage` (ADR D377). Set when the
+     * model has a pricing entry in the registry; `cost.status` is
+     * `"estimated"` / `"unknown"` / `"included"` per D377.
+     */
+    cost?: import("../../types/usage.js").CostBreakdown;
+    /**
+     * Structured error from transport / provider failure (Finding B fix).
+     * When set, `finalStatus === "error"`. Downstream surfaces (runtime,
+     * `RunResult.error`) copy this verbatim. NEVER leaks as an assistant
+     * message (the previous bug — sdk-error-packaging-fix-plan).
+     */
+    error?: AgentLoopErrorDetail;
+    /**
+     * M1-2 (T2.2): true when the loop stopped at its iteration ceiling with the
+     * model still wanting to call tools (silent truncation). Copied verbatim onto
+     * `RunResult.stoppedAtIterationLimit`.
+     */
+    stoppedAtIterationLimit?: boolean;
+    /**
+     * Doom-loop guard: true when the loop stopped because the model repeated IDENTICAL tool calls to
+     * the hard threshold. Copied verbatim onto `RunResult.stoppedByDoomLoop`; the continuation driver
+     * classifies it as a `no_progress` terminal (a controlled stop, not a truncation to re-send).
+     */
+    stoppedByDoomLoop?: boolean;
+}

package/dist/internal/agent-loop/usage-and-cost.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Usage + cost helpers extracted from `loop.ts` (ADRs D376/D377).
+ *
+ * - `accumulateUsage(usage, llmOutput)` — merge a single LLM turn's 5-bucket
+ *   token counts into the per-loop {@link UsageAccumulator}. Early-returns
+ *   when no bucket was populated (avoids spurious zero-step entries on
+ *   pure-error turns).
+ * - `computeUsageCost(inputs, usage)` — resolve provider+model from the
+ *   `model.id` prefix (with LlmClient.name fallback) and run the pricing
+ *   registry lookup to produce the matching `CostBreakdown`. Returns
+ *   `undefined` for the `auto` sentinel model.
+ *
+ * @internal
+ */
+import type { UsageAccumulator } from "../budget/usage-accumulator.js";
+import type { AgentLoopInputs } from "./types.js";
+export interface LlmTurnUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+}
+export declare function accumulateUsage(usage: UsageAccumulator, turn: LlmTurnUsage): void;
+export declare function computeUsageCost(inputs: AgentLoopInputs, usage: TokenUsage): CostBreakdown | undefined;

package/dist/internal/auth/api-key-prefix.d.ts

@@ -0,0 +1,23 @@
+/**
+ * "Which provider issued this key?" — the pure prefix answer.
+ *
+ * Lives in `auth/` and not beside the local-run helper that used to own it, because the question is
+ * an auth question. The local-run path additionally refuses a provider it has no profile for; that
+ * is its policy, not part of this answer, so it stays there and composes with this.
+ *
+ * Lives under `internal/` by FOLDER, and is PUBLIC by contract — re-exported from
+ * `@theokit/sdk/auth`.
+ *
+ * Deliberately NOT tagged `@internal`: `tsconfig.base.json` sets `stripInternal: true`, so that tag
+ * deletes the declaration from every emitted `.d.ts`. The symbol then exists at runtime and cannot
+ * be imported with types — which is the exact defect this module was published to fix, reintroduced
+ * one layer down by a docblock. Measured: usetheodev/theokit-sdk#283.
+ */
+/**
+ * The provider whose key prefix matches, or `undefined` when none does.
+ *
+ * `undefined` means "cannot tell" and never a guess: a wrong guess here routes a real credential to
+ * the wrong endpoint. Whitespace-only and empty inputs are "cannot tell" too — they are what an
+ * empty prompt submits, not a key.
+ */
+export declare function providerFromApiKeyPrefix(apiKey: string | undefined): string | undefined;

package/dist/internal/auth/api-key-validator.d.ts

@@ -0,0 +1,46 @@
+/**
+ * T1.3 — API key boundary validation.
+ *
+ * `validateApiKeyShape(key, provider?)` runs at the create-agent boundary
+ * and rejects malformed inputs early (whitespace-only strings, sub-16-char
+ * fragments, embedded whitespace, missing-prefix shapes for providers that
+ * stamp a known prefix). The check is shape-only — it does NOT make a
+ * round-trip to the provider; live validation still happens at the first
+ * `fetch` against the provider URL.
+ *
+ * Exempted from shape validation:
+ * - fixture keys (prefix `theo_test_`) — used by SDK consumers' fixture-mode tests.
+ * - local-runtime mock key `"local"` — used by Ollama / LMStudio / llama.cpp
+ *   sibling profiles (ADRs D182/D188/D189) whose `authType` is `"none"`.
+ *
+ * @internal
+ */
+export interface ApiKeyValidationFailure {
+    readonly malformed: true;
+    readonly reason: "empty" | "whitespace_only" | "too_short" | "embedded_whitespace" | "missing_known_prefix";
+    readonly message: string;
+}
+export interface ApiKeyValidationOk {
+    readonly malformed: false;
+}
+export type ApiKeyValidationResult = ApiKeyValidationOk | ApiKeyValidationFailure;
+export interface ValidateApiKeyOptions {
+    /** Provider name (lowercase) for prefix sanity check. */
+    provider?: string;
+    /**
+     * When `false`, only OBVIOUSLY-malformed inputs (empty, whitespace-only,
+     * < 4 chars) are rejected. Set when the caller knows the value is just an
+     * identifier (e.g., `shouldUseRealLocalRuntime` mode where the real HTTP
+     * call uses an env credential instead of this `apiKey`).
+     *
+     * When `true` (default), the full shape check applies: 16-char minimum,
+     * provider-prefix sanity, no embedded whitespace.
+     */
+    strict?: boolean;
+}
+/**
+ * Validate the shape of an API key. Returns a discriminated result; the
+ * boundary caller (`agent.ts createLocalAgent` / `createCloudAgent`) throws
+ * `AuthenticationError({code:"malformed_api_key"})` on failure.
+ */
+export declare function validateApiKeyShape(key: string | undefined, options?: ValidateApiKeyOptions | string): ApiKeyValidationResult;

package/dist/internal/auth/credential-availability.d.ts

@@ -0,0 +1,61 @@
+/**
+ * "Does this process hold a REAL provider credential?" — one question, one home.
+ *
+ * It used to live in `runtime/fixtures/fixture-mode.ts`, a 229-line module answering three unrelated
+ * questions. This one spans AWS Bedrock (env var, access key, profile, `~/.aws/credentials` on
+ * disk), GCP Vertex (ADC), a stored OAuth credential read off disk, and three named provider env
+ * vars — a credential policy, filed under a name about test fixtures. Its dependency already pointed
+ * here: `internal/auth/credential-store.js`.
+ *
+ * Every predicate is SYNCHRONOUS and checks a signal, never a live endpoint. Probing would be async
+ * and would make a decision that belongs at request time — an unreachable Ollama or an expired token
+ * must surface as a typed error from the call, not as a silent fall-through to fixture data.
+ *
+ * @internal
+ */
+/**
+ * The provider credentials `shouldUseRealLocalRuntime` consults by name.
+ *
+ * Exported so the "Missing API key" refusal can name the ones the caller actually set (#338 item
+ * 5). The list used to live only inside the predicate below, which meant a caller with
+ * `OPENROUTER_API_KEY` set and `THEOKIT_API_KEY` unset was refused by a message naming neither —
+ * the SDK checks this exact variable a few lines down to decide the runtime, so the environment
+ * looks configured to the person who set it up. Reported as a three-hour diagnosis.
+ *
+ * One list, two readers: a variable added here is recognised by the predicate AND named by the
+ * error on the same commit, which is the only way the two stay in step.
+ */
+export declare const PROVIDER_CREDENTIAL_ENV_VARS: readonly string[];
+/** Those of {@link PROVIDER_CREDENTIAL_ENV_VARS} that are non-empty in this process. */
+export declare function presentProviderCredentialEnvVars(): readonly string[];
+/**
+ * ADRs D286-D287: Bedrock green-lights real runtime when EITHER
+ * `AWS_BEARER_TOKEN_BEDROCK` is set explicitly OR the standard AWS
+ * credential chain (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` /
+ * `AWS_PROFILE` / instance role) can mint a Bearer via
+ * `@aws/bedrock-token-generator`. We only check synchronous signals here;
+ * the actual token resolution happens lazily in
+ * `BedrockAnthropicClient.stream`.
+ */
+export declare function isAwsBedrockAuthAvailable(): boolean;
+/**
+ * ADR D288: Vertex green-lights real runtime when EITHER
+ * `GOOGLE_APPLICATION_CREDENTIALS` is set OR `GOOGLE_CLOUD_PROJECT` is set
+ * (ADC will use gcloud user creds / metadata server). The actual token
+ * resolution happens lazily in `VertexAnthropicClient.stream` /
+ * `VertexGeminiClient.stream`.
+ */
+export declare function isGcpVertexAuthAvailable(): boolean;
+/**
+ * ADR D182 / T1.2: **always `true`.** Zero-config local providers (`authType: "none"`) need no
+ * credential — Ollama defaults to localhost:11434, LM Studio to localhost:1234, llama.cpp to
+ * localhost:8080 — and the SDK ships Ollama as a builtin, so one is always nominally available.
+ * Nothing is probed here; probing would be async. If no daemon is up, the first real LLM call
+ * surfaces `ollama_unreachable` via the typed mapper.
+ *
+ * This used to say it returned true "when ANY of the documented local hosts is reachable in spirit",
+ * which reads as a probe and is not a testable statement. The body has always been `return true`.
+ * The distinction matters because of where this sits — see the note on the `||` chain in
+ * `shouldUseRealLocalRuntime`.
+ */
+export declare function isLocalNoAuthProviderAvailable(): boolean;

package/dist/internal/auth/credential-store.d.ts

@@ -0,0 +1,77 @@
+import { AuthenticationError } from "../../errors.js";
+/**
+ * M42 — the SDK credential store. Promoted DOWN from agent-builder's hardened `agents/lib/credentials.ts`
+ * (M37), generalized from a closed `openrouter|anthropic|openai` union to an open `provider: string` and
+ * driven by a caller-supplied {@link CredentialStoreConfig} (no hardcoded `.agent-builder`/`auth.json` /
+ * `AGENT_BUILDER_HOME`). The security-critical file mechanics are ported VERBATIM (ADR D3 of the M42 plan):
+ * atomic O_EXCL + rename + fsync write, 0700/0600 mode gates, `env` is always a PARAMETER (never an ambient
+ * `process.env` read).
+ *
+ * The env-precedence + key-prefix-inference + declared-provider rungs of the agent-builder resolver are
+ * APP POLICY and deliberately stay UP in the consumer; this module owns only the on-disk store + the
+ * `api|oauth` discriminated union. See {@link resolveCredential} (SDK) for the store-read + refresh path.
+ *
+ * Re-exported from `@theokit/sdk/auth`, and therefore PUBLIC, under semver.
+ *
+ * NOTE — no internal-visibility tag in this block. `tsconfig.base.json` sets `stripInternal: true`,
+ * and TypeScript scans EVERY leading comment range of the declaration that follows, including the
+ * import right below this one. The tag that used to sit here deleted that import from the emitted
+ * `.d.ts`, leaving the types it binds unresolvable for any consumer running type-aware lint
+ * (usetheodev/theokit-sdk#283 records the same trap on a declaration).
+ */
+import type { CredentialStoreConfig, StoredCredential, StoredOAuthCredential } from "./types.js";
+/** The store directory, honoring an optional `homeEnvVar` override. */
+export declare function credentialHome(config: CredentialStoreConfig, env?: Record<string, string | undefined>): string;
+/** The credential file path inside the (possibly overridden) store directory. */
+export declare function authFilePath(config: CredentialStoreConfig, env?: Record<string, string | undefined>): string;
+/**
+ * A credential problem the caller can act on. Never carries the key value.
+ *
+ * M78 — this used to extend bare `Error`, which quietly disabled classification for the entire auth
+ * path: `isTransientError` is `err instanceof TheokitAgentError && err.isRetryable === true`
+ * (`errors.ts:443`), so a credential failure could never be judged transient OR permanent. The
+ * predicate was not "forgotten" downstream — it was unusable there by construction.
+ *
+ * Extending `AuthenticationError` is ADDITIVE: the class still exists, still reports
+ * `name: "CredentialError"`, and every existing `instanceof CredentialError` stays true. It only
+ * gains ancestors. `AuthenticationError` pins `isRetryable: false`, so gaining the ability to be
+ * classified does NOT turn a revoked credential into a retry loop.
+ *
+ * The single reference does the same thing with one root type: Codex routes every domain failure
+ * through `CodexErr` with `is_retryable()` as a method (`protocol/src/error.rs:176`), rather than
+ * parallel classes extending the language's `Error`.
+ */
+export declare class CredentialError extends AuthenticationError {
+    readonly name: string;
+}
+/**
+ * The 0700-dir / 0600-file mode gates (ported verbatim). The DIRECTORY matters as much as the file:
+ * `mkdirSync(mode)` applies only at creation, so a pre-existing store dir keeps whatever mode it had, and a
+ * writable dir lets an attacker replace the credential file with a symlink to their own 0600 file — the
+ * agent then runs on THEIR account.
+ */
+export declare function assertSecureModes(dirPath: string, path: string): void;
+/**
+ * Read the credential file. Absent ⇒ `undefined` (the normal case). Present-but-wrong is a typed error
+ * naming the file: a malformed credential store must not surface as a raw parse crash. Enforces the
+ * 0700 dir / 0600 file mode gates (ported verbatim — a writable dir lets an attacker swap the file for a
+ * symlink to their own account).
+ */
+export declare function readAuthFile(config: CredentialStoreConfig, env?: Record<string, string | undefined>): StoredCredential | undefined;
+/**
+ * Read the stored OAuth credential (with its refresh token), or `undefined` when the store is absent or
+ * holds an api credential. The oauth engine needs the refresh token, which the resolved bearer does not
+ * carry. Enforces the same 0600/0700 gates as every other read.
+ */
+export declare function readStoredOAuth(config: CredentialStoreConfig, env?: Record<string, string | undefined>): StoredOAuthCredential | undefined;
+/**
+ * Persist a credential atomically at mode `0600`. Ported VERBATIM (ADR D3): write to a random-named temp
+ * file in the same directory with `wx` (O_EXCL), fsync, close, chmod, then `rename` (atomic on POSIX) —
+ * so a crash mid-write leaves whatever was there untouched, and a pre-planted symlink cannot capture the
+ * key. The api variant persists the unchanged `{provider, api_key}` (back-compat, no `type` key); the
+ * oauth variant persists `{type:'oauth', provider, access, refresh, expires, account_id?}`.
+ */
+export declare function writeCredential(cred: {
+    provider: string;
+    apiKey: string;
+} | StoredOAuthCredential, config: CredentialStoreConfig, env?: Record<string, string | undefined>): string;

package/dist/internal/auth/oauth-device.d.ts

@@ -0,0 +1,54 @@
+import type { DeviceCodeGrant, DeviceDeps, DeviceOAuthConfig, OAuthTokens, OpenAIDeviceConfig } from "./types.js";
+/** Step 1 — request a device code. POSTs `{client_id, scope}` to the device endpoint. */
+export declare function requestDeviceCode(config: DeviceOAuthConfig, deps: Pick<DeviceDeps, "fetch">): Promise<DeviceCodeGrant>;
+/**
+ * Step 2 — poll the token endpoint until the user approves (or the code expires). Handles RFC 8628
+ * `authorization_pending` (keep waiting) and `slow_down` (back off), with an expiry deadline so it cannot
+ * spin forever.
+ */
+export declare function pollDeviceToken(config: DeviceOAuthConfig, grant: DeviceCodeGrant, deps: DeviceDeps): Promise<OAuthTokens>;
+/**
+ * The full device login: request a code, hand the user the verification URL + user code via `onPrompt`
+ * (never printed here — the caller renders it, keeping this module output-free), then poll to completion.
+ */
+export declare function deviceLogin(config: DeviceOAuthConfig, deps: DeviceDeps, hooks: {
+    onPrompt: (p: {
+        userCode: string;
+        verificationUri: string;
+        expiresIn: number;
+    }) => void;
+}): Promise<OAuthTokens>;
+/** Step 1 (OpenAI) — request the user code. */
+export declare function requestOpenAIUsercode(config: OpenAIDeviceConfig, deps: Pick<DeviceDeps, "fetch">): Promise<{
+    deviceAuthId: string;
+    userCode: string;
+    interval: number;
+}>;
+/**
+ * Step 2+3 (OpenAI) — poll for the authorization code (200 = ready; 403/404 = pending; else fail), then
+ * exchange it for tokens at the standard `/oauth/token` endpoint (reuses `exchangeCode`).
+ */
+export declare function openaiDeviceLogin(config: OpenAIDeviceConfig, deps: DeviceDeps, hooks: {
+    onPrompt: (p: {
+        userCode: string;
+        verificationUri: string;
+    }) => void;
+}): Promise<OAuthTokens>;
+/** JWT id/access-token claims we read to attribute an account. */
+interface IdTokenClaims {
+    chatgpt_account_id?: string;
+    organizations?: Array<{
+        id: string;
+    }>;
+    "https://api.openai.com/auth"?: {
+        chatgpt_account_id?: string;
+    };
+}
+/** Decode a JWT's claim set (no signature verification — used only to read a self-reported account id). */
+export declare function parseJwtClaims(token: string): IdTokenClaims | undefined;
+/** Best-effort account id from an id/access token's claims (OpenAI/ChatGPT shape). */
+export declare function extractAccountId(tokens: {
+    id_token?: string;
+    access_token?: string;
+}): string | undefined;
+export {};

package/dist/internal/auth/oauth-engine.d.ts

@@ -0,0 +1,21 @@
+import type { CredentialStoreConfig, HttpDeps, OAuthProviderConfig, OAuthTokens, ResolvedCredential } from "./types.js";
+/** Exchange an authorization `code` (+ PKCE verifier) for the token pair. */
+export declare function exchangeCode(config: OAuthProviderConfig, input: {
+    code: string;
+    verifier: string;
+}, deps: HttpDeps): Promise<OAuthTokens>;
+/** Swap a refresh token for a fresh access (and possibly rotated refresh) token. */
+export declare function refreshOAuthTokens(config: OAuthProviderConfig, refresh: string, deps: HttpDeps): Promise<OAuthTokens>;
+/** Persist a token triple to the store's oauth variant through the hardened 0600 writer. */
+export declare function persistOAuthTokens(provider: string, tokens: OAuthTokens, store: CredentialStoreConfig, env?: Record<string, string | undefined>): string;
+/**
+ * Return a credential guaranteed fresh enough to use. An `api` credential passes through untouched. An
+ * `oauth` credential still valid (beyond the skew window) passes through; an expired one is refreshed,
+ * re-persisted 0600, and returned with the new access token. Concurrent refreshes of the same store are
+ * coalesced (single-use refresh tokens); the rejected promise is evicted so a failure is not cached-poison.
+ */
+export declare function ensureFreshCredential(resolved: ResolvedCredential, opts: {
+    config: OAuthProviderConfig;
+    store: CredentialStoreConfig;
+    env?: Record<string, string | undefined>;
+}, deps: HttpDeps): Promise<ResolvedCredential>;

package/dist/internal/auth/resolve-credential.d.ts

@@ -0,0 +1,56 @@
+/**
+ * M42 — `resolveCredential`: the public composition entrypoint over the credential store + oauth engine.
+ * Given a provider name + a {@link CredentialStoreConfig} (and, for oauth, an {@link OAuthProviderConfig}),
+ * read the store and return a FRESH `ResolvedCredential` — an api credential passes through by identity; an
+ * oauth credential is transparently refreshed when its access token is within the skew window. Returns
+ * `undefined` when the store holds no credential for `provider` (the caller then falls back to env / apiKeys).
+ *
+ * Mirrors agent-builder's `resolveFreshCredential` composition (store read → oauth → ensureFreshCredential),
+ * defaulting `fetch`/`now` to globals. This is the async surface an oauth provider's M41 `transform.fetch`
+ * calls at stream time, so a mid-turn token expiry refreshes without rebuilding the agent.
+ *
+ * Re-exported from `@theokit/sdk/auth`, and therefore PUBLIC, under semver.
+ *
+ * NOTE — no internal-visibility tag in this block. `tsconfig.base.json` sets `stripInternal: true`,
+ * and TypeScript scans EVERY leading comment range of the declaration that follows, including the
+ * import right below this one. The tag that used to sit here deleted that import from the emitted
+ * `.d.ts`, leaving the types it binds unresolvable for any consumer running type-aware lint
+ * (usetheodev/theokit-sdk#283 records the same trap on a declaration).
+ */
+import type { CredentialStoreConfig, OAuthProviderConfig, ResolvedCredential } from "./types.js";
+/**
+ * Input to `resolveCredential`: which provider, which store, and what to inject.
+ *
+ * `env` and `deps` exist so nothing here reads ambient state. Omitting `env` does NOT fall back to
+ * `process.env` — the store's `homeEnvVar` override simply goes unread, so a credential written
+ * under a relocated home resolves as absent rather than as an error.
+ *
+ * `oauth` is required only to REFRESH an oauth credential. Without it an expired oauth entry cannot
+ * be renewed, and an api-key-only store needs it never.
+ *
+ * PUBLIC and under semver, despite the `internal/` directory: `src/auth/index.ts` re-exports this
+ * type, and `package.json` publishes that barrel as the '@theokit/sdk/auth' subpath. The directory
+ * name is not the authority — the `exports` map is. The semver-exempt class is the sub-paths
+ * declared under '@theokit/sdk/internal/*' ('internal/persistence', 'internal/security',
+ * 'internal/memory-adapters'); no `exports` entry reaches this file that way.
+ */
+export interface ResolveCredentialOptions {
+    /** The provider whose stored credential to resolve. */
+    provider: string;
+    /** Where the credential store lives. */
+    store: CredentialStoreConfig;
+    /** Env for the store's optional `homeEnvVar` override. Never an ambient read. */
+    env?: Record<string, string | undefined>;
+    /** Required to refresh an oauth credential; omit for an api-only store. */
+    oauth?: OAuthProviderConfig;
+    /** Injected HTTP + clock for deterministic tests; default globals. */
+    deps?: {
+        fetch?: typeof fetch;
+        now?: () => number;
+    };
+}
+/**
+ * Resolve a fresh credential for `provider` from the store, or `undefined` if the store holds none for it.
+ * oauth credentials are auto-refreshed when `opts.oauth` is supplied; api credentials pass through.
+ */
+export declare function resolveCredential(opts: ResolveCredentialOptions): Promise<ResolvedCredential | undefined>;