@retinue/agentkit 0.1.0 → 0.3.0

package/dist/toolkit/vendor.js

@@ -0,0 +1,153 @@
+/**
+ * The transport every sibling toolkit needs, once — REQ-052 (#224), task #225.
+ *
+ * `tools-github` grew one of these in #223 and it turned out to be four-fifths vendor-neutral: resolve the
+ * credential *per call*, pin the auth header to one validated host, parse JSON with an empty body tolerated,
+ * and map a failure onto the platform's closed error union. Only the last part is really vendor-specific, and
+ * only in its wording.
+ *
+ * Writing it twice more for Jira and Confluence — with nineteen toolkits after them — would mean copying four
+ * bugs along with it. #223 found two of them the hard way:
+ *
+ * - `JSON.parse("")` on a `204`. Two endpoints returned empty bodies on success and both tools failed outright
+ *   while reporting a parse error about a correct response.
+ * - A plain-text body handled by catching the parse failure, which discarded the text and returned a
+ *   placeholder. The tool typechecked and was entirely non-functional.
+ *
+ * Both are fixed here, so a toolkit gets them right by not writing them.
+ *
+ * **What stays with the vendor**: the failure vocabulary (`classify`), the base URL, and the fixed headers.
+ * A vendor that answers `200` with an error envelope — Slack's `ok: false`, GraphQL's `errors` — reads that
+ * envelope in its own module, because only it knows the shape.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import { credentialHeader } from "../tools/credentials.js";
+import { createHttpClient } from "./http.js";
+/**
+ * The default classification, and why each arm is what it is.
+ *
+ * A model reads these to decide whether trying again is sensible, so the distinction that matters is
+ * *retryable*, not how precisely the words describe the HTTP status. `unauthorized` on a `403` is the important
+ * one: told "forbidden", a model retries with different arguments, which is never the fix for a missing scope.
+ */
+const defaultClassification = (failure, vendor) => {
+    const transport = failure.kind === "timeout" || failure.kind === "unreachable";
+    if (transport) {
+        return {
+            code: "provider_unavailable",
+            message: `${vendor} request failed (${failure.kind}): ${failure.reason}`,
+            retryable: true,
+        };
+    }
+    if (failure.status === 429) {
+        /**
+         * `Retry-After` is honoured when the vendor sent one — the default backoff is a guess, and a vendor that
+         * told you the number has removed the need to guess. Meta, X and Reddit all send it.
+         */
+        return {
+            code: "rate_limited",
+            message: `${vendor} rate limit reached: ${failure.reason}` +
+                (failure.retryAfterMs === undefined ? "" : ` Retry after ${Math.ceil(failure.retryAfterMs / 1000)}s.`),
+            retryable: true,
+            ...(failure.retryAfterMs === undefined ? {} : { retryAfterMs: failure.retryAfterMs }),
+        };
+    }
+    if (failure.status === 401 || failure.status === 403) {
+        return {
+            code: "unauthorized",
+            message: `${vendor} refused the credential (${failure.status}): ${failure.reason}. The credential may lack the permission this tool needs.`,
+            retryable: false,
+        };
+    }
+    return { code: "provider_error", message: `${vendor} request failed (${failure.kind}): ${failure.reason}`, retryable: false };
+};
+export const createVendorTransport = (config) => {
+    const base = config.baseUrl.replace(/\/$/, "");
+    const host = new URL(base).host;
+    /**
+     * One request, with the credential resolved now rather than at construction.
+     *
+     * Per call so a rotated token takes effect without a restart — a credential read once at startup is one that
+     * survives its own rotation, and the failure looks like the vendor rejecting a token that "has not changed".
+     *
+     * The header goes in through `headersFor`, which the runtime calls with the **validated** hostname only: a
+     * credential issued for one host cannot be sent to another by asking for a URL that merely mentions it.
+     */
+    const request = async (context, path, init = {}) => {
+        const credential = await config.resolver.resolve({ ref: config.credentialRef, context });
+        // One helper, so twenty toolkits do not each write their own base64 and get the padding wrong — #260.
+        const [headerName, headerValue] = credentialHeader(credential);
+        const client = createHttpClient({
+            ...(config.fetchImpl === undefined ? {} : { fetchImpl: config.fetchImpl }),
+            headersFor: (requested) => requested === host
+                ? {
+                    [headerName.toLowerCase()]: headerValue,
+                    ...(config.headers ?? {}),
+                    // Overrides the vendor's default, which is JSON for every other call this transport makes.
+                    ...(init.contentType === undefined ? {} : { "content-type": init.contentType }),
+                }
+                : undefined,
+        });
+        const outcome = await client.request({
+            url: `${base}${path}`,
+            ...(init.method === undefined ? {} : { method: init.method }),
+            ...(init.rawBody !== undefined
+                ? { body: init.rawBody }
+                : init.body === undefined
+                    ? {}
+                    : { body: JSON.stringify(init.body) }),
+            // Parsed here and never shown to the model verbatim, so the untrusted-content envelope would only corrupt
+            // the JSON. Anything rendered as prose keeps the default fence.
+            fence: false,
+        });
+        if (outcome.ok)
+            return outcome.body;
+        const failure = outcome;
+        const described = config.classify?.(failure) ?? defaultClassification(failure, config.vendor);
+        /**
+         * `Retry-After`, carried through — and it was being dropped.
+         *
+         * `HttpFailure` parses the header and `PlatformError` has a field for it, and this transport joined them by
+         * building an error that mentioned neither. Every toolkit on it therefore ignored a vendor that had said
+         * *exactly* how long to wait, and fell back to a generic backoff — which is both slower than necessary and,
+         * against a service that counts requests during the window, a way to stay throttled.
+         *
+         * A classifier may override it; otherwise the server's own number wins over any default, because the server
+         * is the only party that knows.
+         */
+        const retryAfterMs = described.retryAfterMs ?? failure.retryAfterMs;
+        /**
+         * `AgentPlatformError`, not a decorated `Error`.
+         *
+         * `toPlatformError` maps anything else to `{ code: "internal", retryable: false }` — so a rate limit thrown
+         * as `Object.assign(new Error(…), { retryable: true })` arrives at the model as permanently broken. The
+         * extra properties simply vanish and nothing warns you.
+         */
+        throw new AgentPlatformError(retryAfterMs === undefined ? described : { ...described, retryAfterMs });
+    };
+    return {
+        async json(context, path, init) {
+            const body = await request(context, path, init);
+            // **An empty body is a success.** A `204` from a delete, or a `201` from a fire-and-forget POST, has
+            // nothing to parse — and `JSON.parse("")` throws, which reported two correct responses as parse failures.
+            if (body.trim() === "")
+                return undefined;
+            try {
+                return JSON.parse(body);
+            }
+            catch {
+                throw new AgentPlatformError({
+                    code: "provider_error",
+                    message: `${config.vendor} returned a body that is not JSON`,
+                    retryable: false,
+                });
+            }
+        },
+        text(context, path, init) {
+            // Not `json` with the parse failure caught: that discards the body, which is how a log-reading tool
+            // shipped returning a placeholder on every success.
+            return request(context, path, init ?? {});
+        },
+    };
+};
+//# sourceMappingURL=vendor.js.map

package/dist/toolkit/web.d.ts

@@ -87,6 +87,19 @@ export type SearchProvider = {
     /** Build the request URL for a query. The key belongs in `headers`, not here, wherever the provider allows it. */
     readonly endpoint: (query: string, limit: number) => string;
     readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * `POST`, for the providers that require it.
+     *
+     * Added when the first real adapters were written (#214): this contract was GET-only, and three of the four
+     * most-used providers — Tavily, Serper, Exa — are POST with a JSON body. A GET-only seam would have limited the
+     * catalogue to Brave and self-hosted SearXNG, which is not a "one contract, several providers" rule so much as
+     * a rule with two providers.
+     *
+     * Optional, so every existing GET provider is unchanged.
+     */
+    readonly method?: "GET" | "POST";
+    /** The request body for a `POST` provider. Ignored for `GET`. */
+    readonly body?: (query: string, limit: number) => unknown;
     /** Read the provider's JSON into hits. Returning `[]` means "searched, found nothing". */
     readonly parse: (payload: unknown) => readonly SearchHit[];
 };

package/dist/toolkit/web.js

@@ -97,10 +97,16 @@ export const createWebSearch = (config = {}) => {
                     "directly.",
             };
         }
+        const method = provider.method ?? "GET";
         const outcome = await client.request({
             url: provider.endpoint(query, limit),
-            headers: provider.headers,
+            ...(provider.headers === undefined ? {} : { headers: provider.headers }),
+            ...(method === "POST"
+                ? { method, body: JSON.stringify(provider.body?.(query, limit) ?? { query }) }
+                : {}),
             accept: "application/json",
+            // Parsed by the provider's own `parse` and never shown to the model verbatim, so the untrusted-content
+            // envelope would only corrupt the JSON. The *hits* are fenced downstream, where they are read as prose.
             fence: false,
         });
         if (!outcome.ok) {

package/dist/tools/budget.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What a tool costs a catalogue — REQ-045 (#204), task #210, AC-3.
+ *
+ * The budget itself is in `core/budget.ts`, shared with the skill catalogue. What is here is the part that knows
+ * about tools: how many tokens one entry is, which is the only thing the generic algorithm cannot know.
+ */
+import type { ToolCatalogEntry, ToolDescriptor } from "./index.js";
+/**
+ * Deliberately **not** re-exported here.
+ *
+ * `applyTokenBudget`, `TokenBudget` and `BudgetOutcome` live in `core/` and reach consumers through
+ * `@retinue/agentkit/runtime`. Re-exporting them from `./tools` as well gave one name two homes, which
+ * `public-surface.test.ts` fails on — and it is right to: a consumer reading two import paths for one function
+ * has to guess which is canonical, and the two will not stay in step.
+ */
+/**
+ * What a compact catalogue entry costs.
+ *
+ * The fields a model actually reads, plus a small per-entry allowance for the JSON or Markdown scaffolding the
+ * assembler wraps them in — measured at ~35 tokens per entry in #221's harness, which is what this reproduces.
+ * An estimate rather than a tokenizer call: the point is a stable ceiling, and a budget that shifted with the
+ * model's tokenizer would make one deployment's 4,000 tokens another's 4,600.
+ */
+export declare const ENTRY_OVERHEAD_TOKENS = 6;
+export declare const entryTokens: (entry: ToolCatalogEntry) => number;
+/** A preloaded tool carries its schemas, which is usually most of its cost. */
+export declare const descriptorTokens: (descriptor: ToolDescriptor) => number;
+//# sourceMappingURL=budget.d.ts.map

package/dist/tools/budget.js

@@ -0,0 +1,35 @@
+/**
+ * What a tool costs a catalogue — REQ-045 (#204), task #210, AC-3.
+ *
+ * The budget itself is in `core/budget.ts`, shared with the skill catalogue. What is here is the part that knows
+ * about tools: how many tokens one entry is, which is the only thing the generic algorithm cannot know.
+ */
+import { estimateTokens } from "../core/tokens.js";
+/**
+ * Deliberately **not** re-exported here.
+ *
+ * `applyTokenBudget`, `TokenBudget` and `BudgetOutcome` live in `core/` and reach consumers through
+ * `@retinue/agentkit/runtime`. Re-exporting them from `./tools` as well gave one name two homes, which
+ * `public-surface.test.ts` fails on — and it is right to: a consumer reading two import paths for one function
+ * has to guess which is canonical, and the two will not stay in step.
+ */
+/**
+ * What a compact catalogue entry costs.
+ *
+ * The fields a model actually reads, plus a small per-entry allowance for the JSON or Markdown scaffolding the
+ * assembler wraps them in — measured at ~35 tokens per entry in #221's harness, which is what this reproduces.
+ * An estimate rather than a tokenizer call: the point is a stable ceiling, and a budget that shifted with the
+ * model's tokenizer would make one deployment's 4,000 tokens another's 4,600.
+ */
+export const ENTRY_OVERHEAD_TOKENS = 6;
+export const entryTokens = (entry) => estimateTokens(`${entry.name} ${entry.label} ${entry.category} ${entry.effect} ${entry.description}`) +
+    ENTRY_OVERHEAD_TOKENS;
+/** A preloaded tool carries its schemas, which is usually most of its cost. */
+export const descriptorTokens = (descriptor) => entryTokens({
+    name: descriptor.name,
+    label: descriptor.label,
+    description: descriptor.description,
+    category: descriptor.category,
+    effect: descriptor.effect,
+}) + estimateTokens(JSON.stringify(descriptor.inputSchema ?? {}));
+//# sourceMappingURL=budget.js.map

package/dist/tools/credentials.d.ts

@@ -0,0 +1,316 @@
+/**
+ * Credentials, referenced rather than held — REQ-047 (#206), task #214, AC-5; widened by REQ-063 (#259), #260.
+ *
+ * A toolkit needs a secret. The question is who holds it and when it is read, and getting that wrong is the
+ * decision that makes a multi-tenant deployment a rewrite of every package rather than a configuration change.
+ *
+ * ## Why a tool must not read the environment
+ *
+ * `process.env.GITHUB_TOKEN` inside a tool works perfectly for exactly one tenant. It is also the shape that
+ * twenty more toolkits will copy, because the first one did — and each of them then has to be rewritten when a
+ * second customer arrives, with their own token, for the same tool.
+ *
+ * So a tool takes a **reference** and the host resolves it. What the reference means — a row in a credential
+ * table, a secret manager path, an env var name in a single-tenant deployment — is the host's business and
+ * changes nothing about the tool.
+ *
+ * ## Why resolution happens at the point of use
+ *
+ * Not at construction. A credential read once at startup is a credential that survives its own rotation: the
+ * secret changes, every request keeps sending the old one, and the failure looks like the vendor rejecting a
+ * token that "has not changed". Resolving per call costs a lookup — cacheable by the host, which knows its own
+ * rotation window — and means a rotated secret takes effect without a restart.
+ *
+ * The corollary: **a resolved secret is never stored on the tool.** It lives in the local scope of one call.
+ *
+ * ## Why a miss throws
+ *
+ * Returning an empty string would send an unauthenticated request and surface as a vendor 401 several layers
+ * away, where the actual problem — nobody wired the credential — is invisible. A typed failure names the ref.
+ *
+ * ## Why a string was not enough — #260
+ *
+ * `resolve()` returned `Promise<string>`, which covers a bearer token and nothing else. Jira and Confluence
+ * want an account email *and* an API token as Basic auth; Atlassian's OAuth needs an access token *and* a cloud
+ * id discovered after consent; WhatsApp needs a token *and* a phone number id; a vendor using `X-Api-Key` needs
+ * a header name. Four of the fourteen integrations specified in `docs/23` cannot be expressed as a string, and
+ * every one of them would have grown its own side-channel.
+ *
+ * Two axes, deliberately kept apart, because they are answered by different people:
+ *
+ * - **`CredentialScheme`** — how the secret is presented on the wire. The toolkit knows this.
+ * - **`AuthMode`** — how the tenant *obtained* it: pasted a token, or completed an OAuth flow. The deployment
+ *   knows this, and it is what decides whether an unconnected tool can pause a run for consent (#264) or must
+ *   simply fail, since a token has no login URL to redirect to.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import { type PlatformError } from "../core/errors.js";
+/** An opaque handle. Its meaning belongs to the resolver, and no tool interprets it. */
+export type CredentialRef = string;
+/** How a secret is presented on the wire. */
+export declare const CREDENTIAL_SCHEMES: readonly ["bearer", "basic", "custom-header"];
+export type CredentialScheme = (typeof CREDENTIAL_SCHEMES)[number];
+/**
+ * How a tenant supplied the credential.
+ *
+ * Not the same question as the scheme: an OAuth access token is presented as a bearer, so the two would collapse
+ * if they shared a type — and the collapse would lose exactly the fact #264 needs, which is whether there is a
+ * login URL to send someone to.
+ */
+export declare const AUTH_MODES: readonly ["token", "oauth2"];
+export type AuthMode = (typeof AUTH_MODES)[number];
+/**
+ * Non-secret vendor identifiers that travel with the credential.
+ *
+ * Atlassian's cloud id, WhatsApp's phone number id, Slack's team id — discovered at connection time, needed on
+ * every request, and **not secrets**. They live here rather than in a toolkit's configuration because they are
+ * per *connection*: two tenants using the same toolkit have different ones, which is the same reason the token
+ * is not configuration either.
+ */
+export type CredentialMetadata = Readonly<Record<string, string>>;
+type WithMetadata = {
+    readonly metadata?: CredentialMetadata;
+    readonly mode?: AuthMode;
+};
+export type Credential = (WithMetadata & {
+    readonly scheme: "bearer";
+    readonly token: string;
+}) | (WithMetadata & {
+    readonly scheme: "basic";
+    readonly username: string;
+    readonly password: string;
+}) | (WithMetadata & {
+    readonly scheme: "custom-header";
+    readonly header: string;
+    readonly value: string;
+});
+/**
+ * Builds a credential whose secret is **not enumerable** — AC-7.
+ *
+ * A typed object is far more likely to reach a log line than a bare string was: it gets spread into an error's
+ * `details`, passed to a structured logger, or serialised into an audit row, and every one of those uses
+ * `JSON.stringify` or an object spread. So the secret is defined non-enumerably and `toJSON`/`toString`/
+ * `util.inspect` are overridden. `credential.token` still reads normally; `{ ...credential }`,
+ * `JSON.stringify(credential)` and `console.log(credential)` do not.
+ *
+ * This is defence in depth, not a licence: a caller that reads `.token` and logs *that* is still logging a
+ * secret, and no type can stop it.
+ */
+export declare const createCredential: (input: Credential) => Credential;
+/** A bearer credential, which is what most vendors want and what a plain string used to mean. */
+export declare const bearer: (token: string, metadata?: CredentialMetadata, mode?: AuthMode) => Credential;
+export interface CredentialResolver {
+    /**
+     * The credential behind a reference, for this caller.
+     *
+     * Takes the context because a reference is resolved *per tenant*: two tenants using the same toolkit name the
+     * same credential and mean different secrets, and a resolver that ignored the caller would hand one tenant
+     * another's token.
+     */
+    resolve(input: {
+        readonly ref: CredentialRef;
+        readonly context: ExecutionContext;
+    }): Promise<Credential>;
+}
+/**
+ * Told about every resolution — `docs/21`'s Connections section, "an audit record of every resolution".
+ *
+ * A sink rather than a return value, so a toolkit cannot forget to report and a host cannot be surprised by
+ * one. **Both outcomes are reported**: a refused resolution is the more interesting audit event, because a
+ * successful one is the normal case and a refused one is somebody asking for something they do not have.
+ *
+ * It never receives the credential. An audit trail that carries the secret is a second copy of the secret in a
+ * place designed to be kept for a long time.
+ */
+export interface CredentialAudit {
+    onResolved(input: {
+        readonly ref: CredentialRef;
+        readonly context: ExecutionContext;
+        readonly scheme: CredentialScheme;
+    }): Promise<void> | void;
+    onRefused(input: {
+        readonly ref: CredentialRef;
+        readonly context: ExecutionContext;
+        readonly reason: string;
+    }): Promise<void> | void;
+}
+export declare const credentialMissing: (ref: CredentialRef, detail?: string) => PlatformError;
+/**
+ * The credential resolved is not the shape this toolkit can present — #260 AC-2.
+ *
+ * Raised at **construction** where possible, and at resolution otherwise. A misconfiguration discovered as a
+ * vendor 401 an hour later is the failure this exists to prevent: the vendor's message says the token is
+ * invalid, which sends an operator to rotate a token that was never the problem.
+ */
+export declare const credentialSchemeMismatch: (ref: CredentialRef, expected: readonly CredentialScheme[], got: CredentialScheme) => PlatformError;
+/**
+ * A resolver over a plain map, for a single-tenant deployment and for tests.
+ *
+ * Shipped because the alternative is every host writing the same six lines, and the sixth one writing it with a
+ * fallback to `process.env` — which is the thing this module exists to prevent. Explicitly *not* environment
+ * backed: a host that wants that passes `{ github: process.env.GITHUB_TOKEN ?? "" }` and can see it doing so.
+ *
+ * **A bare string still works**, and stays the common case: it means a bearer token, which is what it meant
+ * before #260. The single-tenant path must not get harder because multi-tenant got possible.
+ */
+export declare const createStaticCredentialResolver: (secrets: Readonly<Record<string, string | Credential>>) => CredentialResolver;
+/**
+ * Wraps a resolver so every resolution is audited, and so a scheme mismatch is caught here rather than by the
+ * vendor — #260 AC-2 and AC-8.
+ *
+ * A wrapper rather than a change to every resolver: a host's own resolver stays a four-line object, and the
+ * cross-cutting obligations are added once, where they cannot be forgotten per toolkit.
+ */
+export declare const withCredentialAudit: (resolver: CredentialResolver, audit: CredentialAudit, expected?: readonly CredentialScheme[]) => CredentialResolver;
+/**
+ * The `Authorization`-style header a credential presents as.
+ *
+ * One function, so twenty toolkits do not each write their own base64 and get the padding wrong. Returns the
+ * header **name and value**, because `custom-header` does not use `Authorization`.
+ */
+export declare const credentialHeader: (credential: Credential) => readonly [string, string];
+/**
+ * What a toolkit accepts — #260 AC-2.
+ *
+ * Declared by the toolkit and checked at **construction**, so wiring a Basic-auth vendor with a bearer token is
+ * a startup error naming both, rather than a vendor 401 an hour later whose message says the token is invalid.
+ *
+ * `modes` is the other axis and is not the platform's business to validate — it is a fact about the vendor that
+ * a deployment reads: "GitHub takes a PAT or OAuth", "Google is OAuth only". #262 uses it to decide which
+ * connection flows to offer, and #264 uses it to decide whether an unconnected tool can pause a run for consent
+ * or must simply fail, since a token has no login URL.
+ */
+export type ToolkitAuth = {
+    /** How a tenant may obtain the credential. */
+    readonly modes: readonly AuthMode[];
+    /** The scheme(s) this toolkit can present. A credential of any other scheme is refused. */
+    readonly schemes: readonly CredentialScheme[];
+};
+/**
+ * Refuses a toolkit configuration whose credential cannot be presented — at construction.
+ *
+ * Takes the *declared* scheme rather than resolving, because resolution needs a context and construction has
+ * none. A host that wires a static map can therefore be told immediately; a host whose resolver is dynamic is
+ * caught by `withCredentialAudit` at the first call instead. Both are before the vendor sees anything.
+ */
+export declare const assertToolkitAuth: (ref: CredentialRef, auth: ToolkitAuth, declared: CredentialScheme | undefined) => void;
+/**
+ * A credential that stops working at a known time.
+ *
+ * Additive by construction: `RefreshableCredential` is a `Credential` with one more field, so a resolver that
+ * returns a plain one is unchanged and the eight shipped toolkits compile untouched. That is AC-1, and it is a
+ * property of the *type* rather than a claim about the code.
+ *
+ * The refresh token is deliberately **not here.** It lives wherever the host keeps it — `ConnectionStore` seals
+ * it (#261) — and only the refresher ever sees it. Putting it on the credential would mean the longest-lived
+ * secret in an OAuth grant travelling through every toolkit that only needed the short-lived one.
+ */
+export type RefreshableCredential = Credential & {
+    /** ISO 8601. When the vendor stops accepting this. */
+    readonly expiresAt: string;
+};
+/**
+ * Adds an expiry to a credential **without losing its secret protection** — AC-6.
+ *
+ * This exists because the obvious way to build one is wrong, and wrong invisibly. A host writing a
+ * `CredentialRefresher` reaches for:
+ *
+ * ```ts
+ * return { ...bearer(accessToken), expiresAt };   // ← the secret is now enumerable
+ * ```
+ *
+ * `createCredential` defines the secret **non-enumerably**, which is precisely what makes it survive a
+ * `JSON.stringify` into a log line — and precisely what a spread drops. The result looks identical, works
+ * identically, and serialises the token into the first structured log that touches it.
+ *
+ * Found by the AC-6 test failing against this repository's own test helper, which had made exactly that
+ * mistake. If the helper made it, a host will.
+ */
+export declare const refreshable: (credential: Credential, expiresAt: string) => RefreshableCredential;
+export declare const isRefreshable: (credential: Credential) => credential is RefreshableCredential;
+/**
+ * How early a token is replaced.
+ *
+ * Sixty seconds, and the number is a *commitment* rather than a guess: a tool call can take tens of seconds —
+ * a slow vendor, a large upload, a retry — and a token that was valid when the call started must still be
+ * valid when it arrives. Refreshing exactly at expiry makes "expired mid-flight" the common case rather than
+ * the rare one, and that failure looks like an intermittent authentication bug.
+ *
+ * AC-5. Configurable because a deployment whose calls are slower than this needs more.
+ */
+export declare const DEFAULT_REFRESH_SKEW_MS = 60000;
+/** Whether a credential is expired, or close enough that it should be replaced before use. */
+export declare const isExpiring: (credential: Credential, skewMs: number, now: number) => boolean;
+/**
+ * Obtains a fresh credential for a reference.
+ *
+ * A port, because how a token is renewed differs entirely by vendor and by where the grant is stored. The
+ * host's implementation reads its own `ConnectionStore`, calls the vendor's token endpoint, re-seals the new
+ * refresh token and returns the new access credential — none of which the runtime should know about.
+ *
+ * It is given the ref and the context, and **not** the expired credential: it has to look the grant up anyway,
+ * and handing it a dead secret would be one more copy of one for no purpose.
+ */
+export interface CredentialRefresher {
+    refresh(input: {
+        readonly ref: CredentialRef;
+        readonly context: ExecutionContext;
+    }): Promise<RefreshableCredential>;
+}
+/**
+ * A refresh that failed because the grant is gone, rather than because the network was.
+ *
+ * The distinction is the whole of AC-3, and it is not cosmetic: `invalid_grant` means a person must consent
+ * again and no amount of retrying will help, while a timeout means try again in a second. A runtime that
+ * conflates them either retries a dead grant forever or asks a user to re-authorise because of a blip.
+ */
+export declare const REFRESH_GRANT_ERRORS: readonly ["invalid_grant", "invalid_client", "unauthorized_client", "access_denied"];
+export declare const isGrantError: (error: unknown) => boolean;
+export type RefreshingResolverOptions = {
+    readonly skewMs?: number;
+    /** Injectable so a test can move time without waiting for it. */
+    readonly now?: () => number;
+    /**
+     * Told that a refresh happened. Never told the token — see `CredentialAudit`, same reasoning.
+     *
+     * `expiresAt` is included because it is not a secret and it is the one thing an operator debugging a
+     * refresh loop actually needs.
+     */
+    readonly onRefreshed?: (input: {
+        readonly ref: CredentialRef;
+        readonly tenantId: string;
+        readonly expiresAt: string;
+    }) => void;
+};
+/**
+ * Wraps a resolver so an expiring credential is renewed before it is handed out.
+ *
+ * A wrapper, like `withCredentialAudit`, and for the same reason: the eight shipped toolkits already resolve
+ * **per call**, so they pick this up without a line changing. A toolkit that cached a credential at
+ * construction would defeat it, which is why `createGitHubToolkit` and every sibling resolve inside `call()`.
+ *
+ * ## Time-driven, never 401-driven — AC-7
+ *
+ * The obvious design is to refresh when the vendor returns 401. It is wrong, and worth stating plainly because
+ * it is what most integrations do:
+ *
+ * A 401 is what a vendor returns for an expired token, a **revoked** grant, a token for the wrong tenant, and a
+ * scope the grant never had. Refreshing on 401 therefore turns a revoked grant into an infinite refresh loop
+ * against the vendor's token endpoint, and turns a missing scope into a refresh that succeeds and a call that
+ * fails again identically. Neither is diagnosable from the outside.
+ *
+ * Time is the only signal that means what it says: a token with an expiry in the past is expired, and nothing
+ * else is inferred from it. A 401 on a freshly-refreshed token is a real error and is surfaced as one.
+ *
+ * ## One refresh, not N — AC-2
+ *
+ * Twenty concurrent tool calls hitting an expired token must produce **one** refresh. Refresh endpoints rate
+ * limit, and — worse — several vendors invalidate the previous refresh token when one is used, so N concurrent
+ * refreshes race to invalidate each other and log the deployment out permanently.
+ *
+ * The in-flight promise is stored *before* the first await, so a second caller entering the function
+ * synchronously after the first still finds it.
+ */
+export declare const withRefreshingCredentials: (resolver: CredentialResolver, refresher: CredentialRefresher, options?: RefreshingResolverOptions) => CredentialResolver;
+export {};
+//# sourceMappingURL=credentials.d.ts.map