@zapier/kitcore 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -222,6 +222,72 @@ interface MethodHooks {
     annotator?: ComposedAnnotator;
 }
 
+/**
+ * API stability tiers.
+ *
+ * A plugin declares exactly one level via `PluginMeta.stability`; tier
+ * membership (which subpath aggregate exports the plugin) is structural,
+ * so nothing here compares levels ordinally. The array is the single
+ * source of truth: it derives the {@link StabilityLevel} type, gives the
+ * ladder tests their adjacent-tier iteration order, and gives docs a
+ * render order.
+ */
+declare const STABILITY_LEVELS: readonly ["stable", "beta", "experimental"];
+type StabilityLevel = (typeof STABILITY_LEVELS)[number];
+/**
+ * Title-case display names for each level, for section-level badges in
+ * generated docs (e.g. `Code Workflows (Beta)`). Inline description
+ * labels go through {@link applyStabilityLabel} instead.
+ */
+declare const STABILITY_TITLES: {
+    readonly stable: "Stable";
+    readonly beta: "Beta";
+    readonly experimental: "Experimental";
+};
+/**
+ * Normalize authored meta to a concrete level: absent means `"stable"`,
+ * and the deprecated `experimental: true` boolean means `"experimental"`.
+ * The registry projection runs every entry through this, so
+ * `FunctionRegistryEntry.stability` is always concrete and consumers
+ * never branch on `undefined`.
+ *
+ * The declared value can cross a JSON boundary from a hand-written
+ * plugin, so at runtime it may be any string. An unrecognized level
+ * clamps to `"experimental"` — the author declared the method not
+ * stable, and clamping keeps the raw string out of notices and labels.
+ * It doesn't throw because this also runs in the `getStability` live
+ * read on the call path, where a throw would break the observed call.
+ */
+declare function normalizeStability(meta: {
+    stability?: StabilityLevel;
+    experimental?: boolean;
+}): StabilityLevel;
+/**
+ * The shared label renderer: every consumer that renders a registry
+ * entry's description (CLI help, MCP tool descriptions) labels it
+ * through this function, so a new consumer cannot silently drop the
+ * label. `stability` stays structured data on the registry entry — the
+ * label is applied at render time, never baked into the stored
+ * description (docs badge at the section level, so baking it in would
+ * double-badge).
+ *
+ * The label follows the plugin's declared level, not the subpath that
+ * surfaced it: a beta method surfaced through an experimental-tier
+ * consumer still reads "(beta)".
+ */
+declare function applyStabilityLabel({ description, stability, placement, }: {
+    description: string;
+    /** Absent means stable (the value may arrive from outside the
+     * normalized registry projection, e.g. hand-built JSON). */
+    stability: StabilityLevel | undefined;
+    /**
+     * `"suffix"` renders `<description> (beta)` (CLI help);
+     * `"prefix"` renders `[Beta] <description>` (MCP tool descriptions,
+     * where the front of the string is what an LLM reads first).
+     */
+    placement?: "suffix" | "prefix";
+}): string;
+
 /**
  * Plugins with a required-parameter rename declare two schemas: a canonical one
  * (new names only, carrying `.meta({ aliases })`) and a `z.union([canonical,
@@ -562,6 +628,8 @@ interface LeafMetaFields {
      * off the registry / CLI / MCP surface, exactly like `skipInputValidation`. */
     skipOutputValidation?: boolean;
     packages?: string[];
+    stability?: StabilityLevel;
+    /** @deprecated Use `stability: "experimental"` instead. */
     experimental?: boolean;
     confirm?: "create-secret" | "delete";
     deprecation?: FunctionDeprecation;
@@ -1748,8 +1816,17 @@ interface FunctionRegistryEntry {
     resolvers?: Record<string, BoundResolver>;
     packages?: string[];
     /**
-     * True if the plugin is registered only in the experimental SDK
-     * factory. See `PluginMeta.experimental`.
+     * API stability tier of the plugin, normalized from `PluginMeta.stability`
+     * (absent means `"stable"`; the legacy `experimental: true` boolean means
+     * `"experimental"`). Always concrete here, so consumers never branch on
+     * `undefined`.
+     */
+    stability: StabilityLevel;
+    /**
+     * @deprecated Read `stability` instead. Derived as
+     * `stability === "experimental"` — literal by name, so beta reads
+     * `false`; the not-stable warning duty lives in `stability` and the
+     * runtime stability notice.
      */
     experimental?: boolean;
     /** Confirmation prompt type - prompts user before executing */
@@ -1845,10 +1922,19 @@ interface PluginMeta<TSdk = unknown> {
     /** Confirmation prompt type - prompts user before executing */
     confirm?: "create-secret" | "delete";
     /**
-     * Marks this plugin as experimental — wrappers can keep it out of
-     * their stable build (typically by gating it behind an
-     * `experimental` subpath import) and the registry can badge it in
-     * generated docs / CLI help. No runtime capability check.
+     * API stability tier this plugin belongs to. Absent means `"stable"`;
+     * the registry projection normalizes it, so registry consumers always
+     * read a concrete {@link StabilityLevel}. Wrappers keep non-stable
+     * plugins out of their stable build (by gating them behind a `beta` /
+     * `experimental` subpath import) and consumers badge the level in
+     * generated docs, CLI help, and MCP tool descriptions. No runtime
+     * capability check.
+     */
+    stability?: StabilityLevel;
+    /**
+     * @deprecated Use `stability: "experimental"` instead. Kept as an
+     * input for external authors; `true` normalizes to
+     * `stability: "experimental"` in the registry projection.
      */
     experimental?: boolean;
     [key: string]: any;
@@ -2928,6 +3014,16 @@ interface DeprecationWarning {
  * once-per-process per message.
  */
 declare function defaultLogDeprecation({ methodName, deprecation, }: DeprecationWarning): void;
+/**
+ * What the boundary reports when a non-stable (beta / experimental) method
+ * is called: the method plus its declared level. `DeprecationWarning`'s
+ * sibling — same self-describing shape, same handler-not-observer contract.
+ */
+interface StabilityNotice {
+    type: "stability";
+    methodName: string;
+    stability: StabilityLevel;
+}
 /**
  * The well-known id for framework options: heads inject a `CoreOptions` bag
  * under it via `createSdk`'s `configuration` (or register a property plugin),
@@ -2964,6 +3060,16 @@ interface CoreOptions {
      * reserved for an `on*`-named observer when the unified event bus lands.
      */
     logDeprecation?: (warning: DeprecationWarning) => void;
+    /**
+     * `logDeprecation`'s sibling for API stability: the framework signals
+     * every surface call of a method declaring a non-stable `stability`
+     * level (beta / experimental), and this gate decides what happens.
+     * Exactly one: absent falls back to {@link defaultLogStabilityNotice}
+     * (once-per-process per message), supplied replaces it. Runs isolated,
+     * so a throwing handler never breaks the observed call. Internal
+     * delegation never signals, matching the deprecation contract.
+     */
+    logStabilityNotice?: (notice: StabilityNotice) => void;
     /**
      * Report what output validation stripped, on the response's
      * `meta.outputValidation.droppedPaths` (the name mirrors that path). Off by
@@ -3527,6 +3633,8 @@ declare function createFunction<TOptions, TResult, TSchemaOptions extends TOptio
     annotator?: (input: unknown) => Annotations;
     /** Live read of the method's deprecation meta (see signalDeprecation). */
     getDeprecation?: () => FunctionDeprecation | undefined;
+    /** Live read of the method's stability level (see signalStability). */
+    getStability?: () => StabilityLevel | undefined;
 }): (callOptions?: TOptions) => Promise<TResult>;
 /**
  * Higher-order function that creates a paginated function that wraps
@@ -3567,6 +3675,8 @@ declare function createPaginatedFunction<TUserOptions, TResponse, TItem = ItemTy
     finalizePage?: (page: SdkPage<TItem>) => SdkPage<TItem>;
     /** Live read of the method's deprecation meta (see signalDeprecation). */
     getDeprecation?: () => FunctionDeprecation | undefined;
+    /** Live read of the method's stability level (see signalStability). */
+    getStability?: () => StabilityLevel | undefined;
 }): (options?: TUserOptions & {
     cursor?: string;
     pageSize?: number;
@@ -3808,6 +3918,16 @@ interface DeprecationLogger {
  * channels while sharing the implementation.
  */
 declare function createDeprecationLogger(tag: string): DeprecationLogger;
+interface StabilityNoticeLogger {
+    logStabilityNotice(message: string): void;
+    resetStabilityNotices(): void;
+}
+/**
+ * Create a package-tagged stability-notice logger: the deprecation logger's
+ * sibling for non-stable (beta / experimental) API warnings, with the same
+ * once-per-process dedupe policy and its own independent message Set.
+ */
+declare function createStabilityNoticeLogger(tag: string): StabilityNoticeLogger;
 
 /**
  * Core signal machinery.
@@ -3865,4 +3985,374 @@ declare class CoreCancelledSignal extends CoreSignal {
  */
 declare function isCoreCancelledSignal(value: unknown): value is CoreCancelledSignal;
 
-export { type AdaptError, type AdaptErrorOptions, type AdaptPage, type AggregatePlugin, type Annotations, type ArrayResolver$1 as ArrayResolver, type AsyncContext, type BoundFormatter, type BoundResolver, CONTEXT, CORE_ERROR_SYMBOL, CORE_OPTIONS_ID, CORE_SIGNAL_SYMBOL, type CallContext, type CallOrigin, type CategoryDefinition, type ComposedAnnotator, type ConstantResolver$1 as ConstantResolver, type Controller, type ControllerAction, type ControllerAffordance, type ControllerAnswerFn, type ControllerChoice, type ControllerError, type ControllerIssue, type ControllerListingPage, type ControllerListingPosition, type ControllerMethodDescription, type ControllerMethodSummary, type ControllerPagination, type ControllerParameterDescription, type ControllerPath, type ControllerQuestion, type ControllerResult, type ControllerSdk, type ControllerSelectPage, type ControllerState, type CoreApiError, CoreCancelledSignal, CoreDisposeError, CoreError, CoreErrorCode, type CoreErrorOptions, type CoreOptions, CoreSignal, type CreateSdkOptions, type DeprecatedPromptConfigChoice, type DeprecationLogger, type DeprecationWarning, type DisposeFn, type DynamicListResolver, type DynamicMember, type DynamicResolver$1 as DynamicResolver, type DynamicSearchResolver, type FieldsResolver, type FormattedItem, type Formatter, type FunctionDeprecation, type FunctionRegistryEntry, type HookAnnotator, type HookPlugin, type LeafMeta, type LeafSummary, type LegacyMergePlugin, type LegacyPlugin, type ListItemsResult, type ListPromptConfig, type MethodAnnotator, type MethodAttachment, type MethodHooks, type MethodOverridePlugin, type MethodPlugin, type MethodScope, type Resolver as ModelResolver, type NegatableMetadata, type OnMethodEnd, type OnMethodEndContext, type OnMethodStart, type OnMethodStartContext, type OutputFormatter, type PaginatedSdkFunction, type PaginatedSdkResult, type Plugin, type PluginMeta, type PluginProvides, type PluginStack, type PluginSummary, type PluginSurface, type PositionalMetadata, type PromptConfig, type PromptConfigChoice, type PropertyPlugin, type RegistryResult, type RequiredSdkOf, type Resolver$1 as Resolver, type ResolverConfig, type ResolverFieldItem, type ResolverMetadata, type ResolverPromptConfig, type ResolverType, type ResponseMeta, type Sdk, type SdkContext, type SdkPage, type StaticResolver$1 as StaticResolver, type ValidResolvers, addPlugin, canonicalInputSchema, composePlugins, concatLists, concatPaginated, coreOptionsPluginRef, createAsyncContext, createController, createCoreError, createCorePlugin, createDeprecationLogger, createFunction, createPaginatedFunction, createPaginatedPluginMethod, createPluginMethod, createPluginStack, createPrefixedCursor, createSdk, createValidator, dangerousContextPlugin, declareDefault, declareMethod, declareOptionalMethod, declareOptionalProperty, declarePlugin, declareProperty, decodeIncomingCursor, defaultLogDeprecation, defineFormatter, defineHook, defineLegacyMerge, defineMethod, defineMethodOverride, definePlugin, defineProperty, defineResolver, disposeSdk, fromFunctionPlugin, getContext, getCoreErrorCause, getCoreErrorCode, getCurrentDepth, getCurrentScope, getFieldDescriptions, getNegatable, getOutputSchema, getRegistryPlugin, getSchemaDescription, isCoreCancelledSignal, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, omitExports, openEnum, paginate, paginateBuffered, paginateMaxItems, resolvePlugin, runInMethodScope, runWithTelemetryContext, selectExports, splitPrefixedCursor, toIterable, toSnakeCase, toTitleCase, validateOptions, withOutputSchema, withPositional, withResolver };
+/**
+ * Transport wire types.
+ *
+ * The request is fetch's `RequestInit` plus the smallest delta the SDK needs
+ * (see `docs/design/2026-08-03-kitcore-transport.md`): `url` (fetch's first
+ * argument, relocated onto the request so wraps can rewrite it) and an opaque
+ * `connection` reference. The response is the native `Response`.
+ *
+ * The fetch types are derived from the ambient `fetch` global rather than the
+ * named `RequestInit` / `Response`, which require the DOM lib. kitcore targets
+ * both Node and the browser and deliberately omits the DOM lib (so a white-label
+ * core can't reach for `window` / `document`), so we take whatever `fetch` the
+ * host provides — Node's global fetch, the browser's, or a polyfill.
+ */
+/** The `init` bag of the ambient `fetch` (i.e. `RequestInit`), lib-agnostic. */
+type HttpFetchInit = NonNullable<Parameters<typeof fetch>[1]>;
+/**
+ * A request over the transport: `RequestInit` plus two additions.
+ *
+ * - `url` — fetch's first argument, on the request so a routing wrap can rewrite
+ *   host/path.
+ * - `connection` — opaque credential reference; the credential-holding
+ *   transport resolves it (Relay server-side, or a local resolver).
+ *   Unresolvable throws.
+ *   Widen to `string | ConnectionRef` later; that is a non-breaking change.
+ *
+ * Everything else (`method`, `headers`, `body`, `signal`, `redirect`, `cache`,
+ * …) is inherited from `RequestInit` unchanged.
+ *
+ * A deadline is `signal` (`AbortSignal.timeout`), which is what a local dispatch
+ * can act on. A transport that dispatches to a remote service needs a number
+ * instead, because a signal does not serialize; that field arrives with the
+ * first transport that reads one, as a non-breaking addition.
+ */
+type HttpRequest = HttpFetchInit & {
+    url: string;
+    connection?: string;
+};
+/**
+ * What a CALLER may hand the transport, as opposed to what the pipeline passes
+ * around. The only difference is `url`, which may also be a `URL` here, because
+ * global `fetch` accepts one and building a url with `URLSearchParams` is
+ * ordinary.
+ *
+ * `initializeHttpRequest` is the seam that narrows this to {@link HttpRequest},
+ * so every stage below it, and every wrap on those stages, only ever sees a
+ * string url. Widening `HttpRequest.url` itself would push the `string | URL`
+ * check onto every wrap that rewrites a destination, which is the ceremony this
+ * exists to remove.
+ *
+ * `Request` is deliberately not accepted, though global `fetch` takes one: it
+ * carries its own body and headers, which would have to be merged with the
+ * additions above rather than normalized away.
+ */
+type HttpRequestInput = Omit<HttpRequest, "url"> & {
+    url: string | URL;
+};
+type HttpResponse = Awaited<ReturnType<typeof fetch>>;
+type HttpPipelineState = Record<PropertyKey, unknown>;
+/**
+ * What `sendHttpRequest` knows before any stage runs. `initializeHttpRequest`
+ * turns this into the full {@link HttpOperationContext}, so this narrower shape
+ * is what that one stage receives: it cannot be handed fields it exists to
+ * produce.
+ */
+interface HttpOperationStart {
+    operationId: string;
+    signal?: HttpFetchInit["signal"];
+}
+/**
+ * Facts true of the whole operation, built once by `initializeHttpRequest` and
+ * carried on every attempt. Retries share one of these, which is the point:
+ * `replayable` describes the caller's body, not an attempt.
+ *
+ * `request` is the caller's request as it entered the pipeline, normalized and
+ * otherwise untouched. Later stages rewrite their OWN request (routing rewrites
+ * the url, auth removes `connection` and adds headers), so this is the only
+ * place that still holds what was originally asked for. That is what lets
+ * `dispatchHttpRequest` and `receiveHttpResponse` name the connection behind a
+ * failure, long after auth consumed it.
+ *
+ * Treat it as read-only. A stage that mutated a request in place instead of
+ * returning a new one would corrupt this snapshot, and `initializeHttpRequest`
+ * copies only when it must, so `request` is often the caller's own object.
+ *
+ * None of it is wire data. `dispatchHttpRequest` builds its fetch input from
+ * the stage request alone; a dispatch replacement must not serialize this.
+ */
+interface HttpOperationContext extends HttpOperationStart {
+    /** The caller's request, normalized, before any stage rewrote it. */
+    request: HttpRequest;
+    /** Whether the body can be sent again. A `ReadableStream` cannot, so anything
+     * re-issuing a request must refuse it. Inferred from the body rather than
+     * declared, so retry is correct without the caller remembering to say so. */
+    replayable: boolean;
+}
+interface HttpAttemptContext {
+    attemptNumber: number;
+    operation: HttpOperationContext;
+    signal?: HttpFetchInit["signal"];
+    /** Per-attempt scratch for cross-stage handoffs, keyed by `PropertyKey`; use a
+     * symbol for a private one. Reset for each attempt, because a handoff from a
+     * previous attempt describes a request that is no longer in flight. Operation
+     * facts belong on {@link HttpOperationContext} instead. */
+    state: HttpPipelineState;
+}
+interface InitializeHttpRequestInput {
+    request: HttpRequestInput;
+    operation: HttpOperationStart;
+}
+/**
+ * One physical attempt at a request: prepare, authorize, dispatch, receive.
+ *
+ * A distinct stage from `sendHttpRequest` because the transport has two
+ * lifecycle scopes, not one. `sendHttpRequest` is the OPERATION (once per
+ * caller request, where `initializeHttpRequest` and `operationId` live);
+ * `attemptHttpRequest` is the ATTEMPT (once per physical request). Anything
+ * that re-issues a request wraps here, so it inherits one `operationId` for the
+ * whole operation, sets each attempt's `attemptNumber`, and can read
+ * `attempt.operation.replayable` before deciding to resend. Wrapping
+ * `sendHttpRequest` instead would re-run initialize and mint a new operation
+ * per attempt.
+ */
+interface AttemptHttpRequestInput {
+    request: HttpRequest;
+    attempt: HttpAttemptContext;
+}
+interface PrepareHttpRequestInput {
+    request: HttpRequest;
+    attempt: HttpAttemptContext;
+}
+/**
+ * Removing `connection` from the returned request is how a wrap CLAIMS it. The
+ * default stage at the end of the chain throws on a reference that is still
+ * set, so a reference nothing claimed stops the request instead of sending it
+ * unauthenticated.
+ *
+ * Claiming is not lossy: the reference stays readable at every stage on
+ * `attempt.operation.request.connection`, so a wrap that needs it later reads
+ * it there rather than stashing a copy in `attempt.state`.
+ */
+interface AuthorizeHttpRequestInput {
+    request: HttpRequest;
+    attempt: HttpAttemptContext;
+}
+interface DispatchHttpRequestInput {
+    request: HttpRequest;
+    attempt: HttpAttemptContext;
+}
+interface ReceiveHttpResponseInput {
+    request: HttpRequest;
+    response: HttpResponse;
+    attempt: HttpAttemptContext;
+}
+/**
+ * The transport method: a request in, a native `Response` out (exactly what
+ * `fetch` returns). Wraps around this method are contract-preserving over it.
+ */
+type SendHttpRequest = (request: HttpRequest) => ReturnType<typeof fetch>;
+
+/**
+ * One physical attempt: prepare, authorize, dispatch, receive.
+ *
+ * This exists as its own stage to give the ATTEMPT scope a seam. See
+ * {@link AttemptHttpRequestInput} for why the operation and the attempt are
+ * different lifecycles, and why re-issuing a request has to wrap here rather
+ * than around `sendHttpRequest`.
+ *
+ * Do not fold this back into `sendHttpRequest` to save an indirection: doing so
+ * removes the only boundary below `initializeHttpRequest`, and a retry wrap
+ * would then re-initialize and mint a fresh `operationId` per attempt.
+ */
+declare const attemptHttpRequestPlugin: MethodPlugin<"attemptHttpRequest", AttemptHttpRequestInput, Promise<Response>, readonly []> & LeafSummary<"kitcore", "attemptHttpRequest", readonly [MethodPlugin<"prepareHttpRequest", PrepareHttpRequestInput, Promise<HttpRequest>, readonly []> & LeafSummary<"kitcore", "prepareHttpRequest", readonly []>, MethodPlugin<"authorizeHttpRequest", AuthorizeHttpRequestInput, Promise<HttpRequest>, readonly []> & LeafSummary<"kitcore", "authorizeHttpRequest", readonly []>, MethodPlugin<"dispatchHttpRequest", DispatchHttpRequestInput, Promise<Response>, readonly []> & LeafSummary<"kitcore", "dispatchHttpRequest", readonly []>, MethodPlugin<"receiveHttpResponse", ReceiveHttpResponseInput, Promise<Response>, readonly []> & LeafSummary<"kitcore", "receiveHttpResponse", readonly []>]>;
+
+/**
+ * Completes the operation context: normalizes the caller's request and records
+ * whether its body can be sent again. Everything below this stage reads those
+ * two facts off `attempt.operation`, and neither changes across retries.
+ */
+declare const initializeHttpRequestPlugin: MethodPlugin<"initializeHttpRequest", InitializeHttpRequestInput, Promise<HttpOperationContext>, readonly []> & LeafSummary<"kitcore", "initializeHttpRequest", readonly []>;
+
+/**
+ * Options for {@link retryHttpRequestPlugin}, supplied by id like every other
+ * kitcore configuration value. Absent means the defaults below.
+ */
+interface RetryHttpRequestOptions {
+    /** Total attempts including the first. Default 3. */
+    maxAttempts?: number;
+    /** Refuse a delay longer than this and give up instead. Default 60 seconds. */
+    maxDelayMilliseconds?: number;
+    /** Statuses to retry on an idempotent method. Default 429, 500, 502, 503, 504. */
+    retryStatuses?: readonly number[];
+    /**
+     * Statuses to retry on a NON-idempotent method. Default 429 only: a rate
+     * limit rejects the request before the server does any work, so it is known
+     * not to have executed. A 502 or 504 carries no such promise.
+     */
+    nonIdempotentRetryStatuses?: readonly number[];
+    /** Methods safe to resend. Default the RFC 9110 idempotent set. */
+    idempotentMethods?: readonly string[];
+    /**
+     * Retry when an attempt THROWS (a network failure) rather than answering.
+     * Default false. A thrown request may still have reached the server, and
+     * turning this on silently widens what gets resent, so it is a deliberate
+     * choice rather than a default.
+     */
+    retryOnError?: boolean;
+}
+declare const RETRY_HTTP_REQUEST_OPTIONS_ID = "kitcore/retryHttpRequestOptions";
+declare const retryHttpRequestOptionsPluginRef: PropertyPlugin<"retryHttpRequestOptions", RetryHttpRequestOptions | undefined> & PluginSummary<never, never>;
+/**
+ * Re-issue a failed attempt, opt-in by composition.
+ *
+ * Wraps `attemptHttpRequest` rather than `sendHttpRequest`, which is what makes
+ * the retry correct rather than merely present: `initializeHttpRequest` has
+ * already run, so every attempt shares one `operationId`, and this can read
+ * `attempt.operation.replayable` before resending.
+ *
+ * Three independent gates, each answering a different question:
+ *
+ *   replayable  CAN we resend?    a consumed stream body cannot go out again
+ *   idempotent  is it SAFE?       a 504 may mean the server DID process it
+ *   status      SHOULD we?        policy, configurable
+ *
+ * The idempotency gate is the subtle one. A 429 is DIRECTED: the server told us
+ * when to return, and a rate limit rejects before doing work, so it is known not
+ * to have executed and any method may be resent. A 5xx is SPECULATIVE: no
+ * instruction, and the request may have succeeded with the response lost, so
+ * resending a POST would double-execute it.
+ *
+ * Exhausting the retries RETURNS the last response rather than throwing.
+ * Deciding what counts as a failure belongs to `receiveHttpResponse` and a
+ * head's error mapping; this decides only whether to try again.
+ *
+ * Cancellation is the one exception, and it throws. A caller who aborts wants
+ * the operation to stop, not to receive whichever response the last attempt
+ * happened to produce, so an abort during the wait ends the loop with the
+ * caller's own reason.
+ */
+declare const retryHttpRequestPlugin: HookPlugin<string>;
+
+declare const prepareHttpRequestPlugin: MethodPlugin<"prepareHttpRequest", PrepareHttpRequestInput, Promise<HttpRequest>, readonly []> & LeafSummary<"kitcore", "prepareHttpRequest", readonly []>;
+
+declare const authorizeHttpRequestPlugin: MethodPlugin<"authorizeHttpRequest", AuthorizeHttpRequestInput, Promise<HttpRequest>, readonly []> & LeafSummary<"kitcore", "authorizeHttpRequest", readonly []>;
+
+declare const dispatchHttpRequestPlugin: MethodPlugin<"dispatchHttpRequest", DispatchHttpRequestInput, Promise<Response>, readonly []> & LeafSummary<"kitcore", "dispatchHttpRequest", readonly []>;
+
+declare const receiveHttpResponsePlugin: MethodPlugin<"receiveHttpResponse", ReceiveHttpResponseInput, Promise<Response>, readonly []> & LeafSummary<"kitcore", "receiveHttpResponse", readonly []>;
+
+/**
+ * The transport orchestrator: turn an {@link HttpRequestInput} into a native
+ * `Response`. It owns the OPERATION, the things that happen once per caller
+ * request, and delegates the per-attempt work to `attemptHttpRequest`:
+ *
+ *   initialize once  ->  attempt (prepare, authorize, dispatch, receive)
+ *
+ * The split is the seam that makes re-issuing a request possible. A wrap here
+ * sees the whole operation (a concurrency permit, an overall deadline); a wrap
+ * on `attemptHttpRequest` sees one attempt and may run it more than once
+ * (retry, an approval re-issue). Cross-cutting behavior should still wrap the
+ * narrowest stage it owns.
+ *
+ * A caller's `url` may be a `URL`; initialize normalizes it, so every stage
+ * from prepare onward receives a plain string.
+ *
+ * A raw method: it owns its input (the fetch-shaped `HttpRequest`), so
+ * `skipInputValidation` keeps the caller's object identity intact: no parse, no
+ * coercion, no clone. The `inputSchema` is projection-only (never run as a
+ * validator) and exists so the registry has a shape to describe.
+ *
+ * An unresolved `connection` fails in the default authorize stage: no auth wrap
+ * consumed it, so the request would otherwise go out unauthenticated.
+ *
+ * No retry by default: with nothing composed this runs exactly one attempt.
+ * `retryHttpRequestPlugin` is opt-in.
+ */
+declare const sendHttpRequestPlugin: MethodPlugin<"sendHttpRequest", HttpRequestInput, Promise<Response>, readonly []> & LeafSummary<"kitcore", "sendHttpRequest", readonly [MethodPlugin<"initializeHttpRequest", InitializeHttpRequestInput, Promise<HttpOperationContext>, readonly []> & LeafSummary<"kitcore", "initializeHttpRequest", readonly []>, MethodPlugin<"attemptHttpRequest", AttemptHttpRequestInput, Promise<Response>, readonly []> & LeafSummary<"kitcore", "attemptHttpRequest", readonly [MethodPlugin<"prepareHttpRequest", PrepareHttpRequestInput, Promise<HttpRequest>, readonly []> & LeafSummary<"kitcore", "prepareHttpRequest", readonly []>, MethodPlugin<"authorizeHttpRequest", AuthorizeHttpRequestInput, Promise<HttpRequest>, readonly []> & LeafSummary<"kitcore", "authorizeHttpRequest", readonly []>, MethodPlugin<"dispatchHttpRequest", DispatchHttpRequestInput, Promise<Response>, readonly []> & LeafSummary<"kitcore", "dispatchHttpRequest", readonly []>, MethodPlugin<"receiveHttpResponse", ReceiveHttpResponseInput, Promise<Response>, readonly []> & LeafSummary<"kitcore", "receiveHttpResponse", readonly []>]>]>;
+
+/**
+ * `fetch` — native `fetch(url, init)` ergonomics over the transport. It
+ * delegates to `sendHttpRequest`, inheriting its stage pipeline and any wraps
+ * composed around those stages.
+ *
+ * It imports the transport as a DEFAULT (`declareDefault`), so `fetchPlugin`
+ * works alone: with nothing else composed, the default pipeline dispatches
+ * through `globalThis.fetch`. A composed transport provider of the same id
+ * preempts the default, so hello-world is just `fetchPlugin`.
+ *
+ * `fetch` is branch-free and never inspects `connection` — it just delegates, and
+ * the default authorizer fails loud on an unresolved reference. A raw method
+ * (`skipInputValidation`): the caller's `init` passes through untouched, so this
+ * is global `fetch` plus the `url` / `connection` shape. Content-type inference
+ * for non-standard bodies (a plain object → JSON) is a head ergonomic, not
+ * kitcore-generic.
+ *
+ * `url` takes a `URL` as well as a string, matching global `fetch`. A `Request`
+ * is the one first argument global `fetch` takes that this does not; see
+ * {@link HttpRequestInput}.
+ */
+declare const fetchPlugin: MethodPlugin<"fetch", {
+    url: string | URL;
+    init?: Omit<HttpRequestInput, "url">;
+}, Promise<Response>, readonly ["url", "init"]> & LeafSummary<"kitcore", "fetch", readonly [MethodPlugin<"sendHttpRequest", HttpRequestInput, Promise<Response>, readonly []> & LeafSummary<"kitcore", "sendHttpRequest", readonly [MethodPlugin<"initializeHttpRequest", InitializeHttpRequestInput, Promise<HttpOperationContext>, readonly []> & LeafSummary<"kitcore", "initializeHttpRequest", readonly []>, MethodPlugin<"attemptHttpRequest", AttemptHttpRequestInput, Promise<Response>, readonly []> & LeafSummary<"kitcore", "attemptHttpRequest", readonly [MethodPlugin<"prepareHttpRequest", PrepareHttpRequestInput, Promise<HttpRequest>, readonly []> & LeafSummary<"kitcore", "prepareHttpRequest", readonly []>, MethodPlugin<"authorizeHttpRequest", AuthorizeHttpRequestInput, Promise<HttpRequest>, readonly []> & LeafSummary<"kitcore", "authorizeHttpRequest", readonly []>, MethodPlugin<"dispatchHttpRequest", DispatchHttpRequestInput, Promise<Response>, readonly []> & LeafSummary<"kitcore", "dispatchHttpRequest", readonly []>, MethodPlugin<"receiveHttpResponse", ReceiveHttpResponseInput, Promise<Response>, readonly []> & LeafSummary<"kitcore", "receiveHttpResponse", readonly []>]>]>]>;
+
+/**
+ * Headers with every credential value masked, as a plain object a logger can
+ * print. Header names come back lowercased, because `Headers` normalizes them.
+ */
+declare function redactHeaders(headers?: HeadersInit): Record<string, string> | undefined;
+/**
+ * A log-safe view of a request: credential headers masked, and `connection`
+ * masked with it.
+ *
+ * `connection` is the half a head cannot redact for itself. The transport
+ * treats it as an opaque string, so its value is whatever a caller passed,
+ * including a raw credential (see {@link HttpRequest}). A hook printing a
+ * stage's `args` would put it on the terminal.
+ *
+ * The url and the body are NOT redacted. A token can ride either, in a query
+ * parameter or a form field, but kitcore does not know which one, and masking
+ * by guessed name would hide the wrong thing while claiming the rest is safe.
+ * A head that puts credentials there has to redact them itself.
+ *
+ * Returns a new object. The pipeline treats `HttpOperationContext.request` as
+ * read-only, and a logger must not be the thing that breaks that.
+ */
+declare function redactHttpRequest(request: HttpRequest): HttpRequest;
+
+interface DefaultConnectionSchemeInput {
+    connection: string;
+}
+interface NormalizeConnectionInput {
+    connection?: string;
+}
+interface ResolveConnectionInput {
+    /** The explicit connection reference the caller passed, if any. */
+    connection?: string;
+    /** The connection type the tool declared (`connection: "<type>"`). kitcore
+     * never reads it; it is the key a head's discovery wrap routes on, and the key
+     * the connection-route registry is looked up by. */
+    connectionType: string;
+}
+interface NormalizedConnection {
+    connection: string;
+    scheme?: string;
+    value: string;
+}
+
+declare const defaultConnectionSchemePlugin: MethodPlugin<"defaultConnectionScheme", DefaultConnectionSchemeInput, string | undefined, readonly []> & LeafSummary<"kitcore", "defaultConnectionScheme", readonly []>;
+
+declare const normalizeConnectionPlugin: MethodPlugin<"normalizeConnection", NormalizeConnectionInput, NormalizedConnection | undefined, readonly []> & LeafSummary<"kitcore", "normalizeConnection", readonly [MethodPlugin<"defaultConnectionScheme", DefaultConnectionSchemeInput, string | undefined, readonly []> & LeafSummary<"kitcore", "defaultConnectionScheme", readonly []>]>;
+
+/**
+ * SELECT which connection REFERENCE a call should use: the explicit one if the
+ * caller passed it, else `undefined`. It deals only in references, never a
+ * secret. Turning a reference into a credential is `authorizeHttpRequest`.
+ *
+ * The default is a pass-through, so this exists to be wrapped. A head adds
+ * discovery or defaulting with a `defineHook` over `resolveConnection`, keyed by
+ * `input.connectionType` (reading a connection id from an env var, say). Because
+ * it is an ordinary method rather than an interactive prompt, a caller in plain
+ * code gets the head's defaulting too, not only a caller driven by the
+ * controller.
+ *
+ * Returning `undefined` is not an error here. Whether a missing connection is
+ * fatal depends on what the caller declared it needs, which this stage cannot
+ * see, so this stays policy-free.
+ */
+declare const resolveConnectionPlugin: MethodPlugin<"resolveConnection", ResolveConnectionInput, string | undefined, readonly []> & LeafSummary<"kitcore", "resolveConnection", readonly []>;
+
+export { type AdaptError, type AdaptErrorOptions, type AdaptPage, type AggregatePlugin, type Annotations, type ArrayResolver$1 as ArrayResolver, type AsyncContext, type AttemptHttpRequestInput, type AuthorizeHttpRequestInput, type BoundFormatter, type BoundResolver, CONTEXT, CORE_ERROR_SYMBOL, CORE_OPTIONS_ID, CORE_SIGNAL_SYMBOL, type CallContext, type CallOrigin, type CategoryDefinition, type ComposedAnnotator, type ConstantResolver$1 as ConstantResolver, type Controller, type ControllerAction, type ControllerAffordance, type ControllerAnswerFn, type ControllerChoice, type ControllerError, type ControllerIssue, type ControllerListingPage, type ControllerListingPosition, type ControllerMethodDescription, type ControllerMethodSummary, type ControllerPagination, type ControllerParameterDescription, type ControllerPath, type ControllerQuestion, type ControllerResult, type ControllerSdk, type ControllerSelectPage, type ControllerState, type CoreApiError, CoreCancelledSignal, CoreDisposeError, CoreError, CoreErrorCode, type CoreErrorOptions, type CoreOptions, CoreSignal, type CreateSdkOptions, type DefaultConnectionSchemeInput, type DeprecatedPromptConfigChoice, type DeprecationLogger, type DeprecationWarning, type DispatchHttpRequestInput, type DisposeFn, type DynamicListResolver, type DynamicMember, type DynamicResolver$1 as DynamicResolver, type DynamicSearchResolver, type FieldsResolver, type FormattedItem, type Formatter, type FunctionDeprecation, type FunctionRegistryEntry, type HookAnnotator, type HookPlugin, type HttpAttemptContext, type HttpFetchInit, type HttpOperationContext, type HttpOperationStart, type HttpPipelineState, type HttpRequest, type HttpRequestInput, type HttpResponse, type InitializeHttpRequestInput, type LeafMeta, type LeafSummary, type LegacyMergePlugin, type LegacyPlugin, type ListItemsResult, type ListPromptConfig, type MethodAnnotator, type MethodAttachment, type MethodHooks, type MethodOverridePlugin, type MethodPlugin, type MethodScope, type Resolver as ModelResolver, type NegatableMetadata, type NormalizeConnectionInput, type NormalizedConnection, type OnMethodEnd, type OnMethodEndContext, type OnMethodStart, type OnMethodStartContext, type OutputFormatter, type PaginatedSdkFunction, type PaginatedSdkResult, type Plugin, type PluginMeta, type PluginProvides, type PluginStack, type PluginSummary, type PluginSurface, type PositionalMetadata, type PrepareHttpRequestInput, type PromptConfig, type PromptConfigChoice, type PropertyPlugin, RETRY_HTTP_REQUEST_OPTIONS_ID, type ReceiveHttpResponseInput, type RegistryResult, type RequiredSdkOf, type ResolveConnectionInput, type Resolver$1 as Resolver, type ResolverConfig, type ResolverFieldItem, type ResolverMetadata, type ResolverPromptConfig, type ResolverType, type ResponseMeta, type RetryHttpRequestOptions, STABILITY_LEVELS, STABILITY_TITLES, type Sdk, type SdkContext, type SdkPage, type SendHttpRequest, type StabilityLevel, type StabilityNotice, type StabilityNoticeLogger, type StaticResolver$1 as StaticResolver, type ValidResolvers, addPlugin, applyStabilityLabel, attemptHttpRequestPlugin, authorizeHttpRequestPlugin, canonicalInputSchema, composePlugins, concatLists, concatPaginated, coreOptionsPluginRef, createAsyncContext, createController, createCoreError, createCorePlugin, createDeprecationLogger, createFunction, createPaginatedFunction, createPaginatedPluginMethod, createPluginMethod, createPluginStack, createPrefixedCursor, createSdk, createStabilityNoticeLogger, createValidator, dangerousContextPlugin, declareDefault, declareMethod, declareOptionalMethod, declareOptionalProperty, declarePlugin, declareProperty, decodeIncomingCursor, defaultConnectionSchemePlugin, defaultLogDeprecation, defineFormatter, defineHook, defineLegacyMerge, defineMethod, defineMethodOverride, definePlugin, defineProperty, defineResolver, dispatchHttpRequestPlugin, disposeSdk, fetchPlugin, fromFunctionPlugin, getContext, getCoreErrorCause, getCoreErrorCode, getCurrentDepth, getCurrentScope, getFieldDescriptions, getNegatable, getOutputSchema, getRegistryPlugin, getSchemaDescription, initializeHttpRequestPlugin, isCoreCancelledSignal, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, normalizeConnectionPlugin, normalizeStability, omitExports, openEnum, paginate, paginateBuffered, paginateMaxItems, prepareHttpRequestPlugin, receiveHttpResponsePlugin, redactHeaders, redactHttpRequest, resolveConnectionPlugin, resolvePlugin, retryHttpRequestOptionsPluginRef, retryHttpRequestPlugin, runInMethodScope, runWithTelemetryContext, selectExports, sendHttpRequestPlugin, splitPrefixedCursor, toIterable, toSnakeCase, toTitleCase, validateOptions, withOutputSchema, withPositional, withResolver };