@zapier/kitcore 0.7.0 → 0.9.0

package/dist/index.d.mts

@@ -20,31 +20,124 @@ interface SdkPage<T = unknown> {
     nextCursor?: string;
 }
 /**
- * Return type of every paginated SDK method. The same value is both:
+ * Return type of every paginated SDK method. The documented surface is:
  *
- *   - a Promise that resolves to the first page (`SdkPage<TItem>`), and
- *   - an AsyncIterable that yields each page in turn,
+ *   - `await` the result for the first page (`SdkPage<TItem>`),
+ *   - `.pages()` for an AsyncIterable over pages, and
+ *   - `.items()` for an AsyncIterable over individual items across pages.
  *
- * with an `.items()` method that returns an AsyncIterable over individual
- * items across all pages. Named so paginated plugin signatures serialize
- * as `PaginatedSdkResult<AppItem>` in `.d.ts` rather than expanding the
- * full triple-intersection at every callsite.
+ * `.pages()` and `.items()` return plain iterables (not thenables), so they
+ * survive being returned from an `async` function; the result itself is a
+ * thenable, so an `async` boundary silently collapses it to the first page.
+ * Named so paginated plugin signatures serialize as
+ * `PaginatedSdkResult<AppItem>` in `.d.ts` rather than expanding the full
+ * intersection at every callsite.
  *
  * The faces share one underlying cursor, so a result is consumed once:
  *
  *   - `await` / `.then()` read the buffered first page without starting the
  *     stream, so awaiting is a repeatable peek and you can still iterate the
  *     result afterward.
- *   - The page-iterable and `.items()` are two views over one page stream, so
- *     consuming either drains the other: the second view yields nothing (it
- *     does not replay page 1). To read a result more than once, call the
- *     method again for a fresh result.
+ *   - `.pages()`, `.items()`, and the deprecated bare iteration are views
+ *     over one page stream, so consuming any view drains the others: the
+ *     second view yields nothing (it does not replay page 1). To read a
+ *     result more than once, call the method again for a fresh result.
  */
-interface PaginatedSdkResult<TItem> extends Promise<SdkPage<TItem>>, AsyncIterable<SdkPage<TItem>> {
+interface PaginatedSdkResult<TItem> extends Promise<SdkPage<TItem>> {
+    /**
+     * @deprecated Iterate `.pages()` instead. Bare iteration works but is easy
+     * to break: because the result is also a thenable, an `async` boundary
+     * collapses it to its first page and the iterable is silently lost.
+     *
+     * Deliberately no runtime deprecation warning: this face is not scheduled
+     * for deletion (removing it is a breaking change deferred to a separate
+     * decision), and structural consumers such as the CLI's page streaming
+     * detect pagination via `Symbol.asyncIterator`, so a warning would fire on
+     * the SDK's own machinery.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<SdkPage<TItem>>;
+    pages(): AsyncIterable<SdkPage<TItem>>;
     items(): AsyncIterable<TItem>;
 }
 type PaginatedSdkFunction<TOptions, TItem> = (options: TOptions) => PaginatedSdkResult<TItem>;
 
+/**
+ * Per-call context threaded explicitly through the method boundary in place of
+ * ambient AsyncLocalStorage. It carries call identity, nesting depth, and a
+ * per-invocation annotation bag. Because it travels as data, correlation and
+ * nested-call dedup work without `async_hooks` — including in browsers, where
+ * the old ALS store was inert and nested calls all looked top-level.
+ *
+ * Framework-neutral: heads surface `callId` under their own name (e.g. a
+ * correlation id) and own their annotation field names.
+ */
+/**
+ * A private brand (a fresh `Symbol()`, never `Symbol.for`) makes a CallContext
+ * unforgeable: no outside code can name the symbol to synthesize an id-bearing
+ * context, and the brand never collides across bundled copies. This is the same
+ * unforgeability the `INTERNAL_CALL` sentinel relies on.
+ */
+declare const CALL_CONTEXT_BRAND: unique symbol;
+interface CallContext {
+    /** Minted once at the root call; copied verbatim to every nested (child) call. */
+    callId: string | null;
+    /** 0 at the outermost call; `parent.depth + 1` for a delegated call. */
+    depth: number;
+    /**
+     * Per-invocation scratch space. Never forwarded to callees — a child call
+     * gets a fresh bag — so annotations describe one method's own invocation.
+     */
+    annotations: Record<string, unknown>;
+    readonly [CALL_CONTEXT_BRAND]: true;
+}
+
+/**
+ * Method-call lifecycle hooks. Plugins contribute `onMethodStart` and/or
+ * `onMethodEnd` on their context; `buildHooks` composes contributions across
+ * plugins so multiple observers can coexist. Composition is right-additive
+ * (newer plugins fire after earlier ones); only opt-in methods built through
+ * `createPluginMethod` / `createPaginatedPluginMethod` trigger the hooks.
+ */
+interface OnMethodStartContext {
+    methodName: string;
+    args: unknown[];
+    isPaginated: boolean;
+    /**
+     * Depth of this method invocation in the SDK call tree. 0 = outermost
+     * (user-initiated) call; 1+ = called from inside another SDK method.
+     * Observers can use this to ignore nested calls if they only want
+     * top-level events.
+     */
+    depth: number;
+}
+type OnMethodStart = (ctx: OnMethodStartContext) => void;
+interface OnMethodEndContext {
+    methodName: string;
+    args: unknown[];
+    isPaginated: boolean;
+    depth: number;
+    durationMs: number;
+    error?: Error;
+}
+type OnMethodEnd = (ctx: OnMethodEndContext) => void;
+interface MethodHooks {
+    onMethodStart?: OnMethodStart;
+    onMethodEnd?: OnMethodEnd;
+}
+
+/**
+ * Plugins with a required-parameter rename declare two schemas: a canonical one
+ * (new names only, carrying `.meta({ aliases })`) and a `z.union([canonical,
+ * deprecated])` for runtime input parsing (so callers passing old names still
+ * validate). The union has no object shape, so everything that reads parameter
+ * shape/requiredness — the registry projection, generated docs, and the
+ * resolution planner — must read the canonical variant, not the union.
+ *
+ * Convention: the FIRST union variant is the canonical schema. Every plugin
+ * that uses unions follows this; it's explicit and needs no extra metadata.
+ * Runtime validation still uses the full union; only shape reading canonicalizes.
+ */
+declare function canonicalInputSchema(schema: z.ZodSchema | undefined): z.ZodSchema | undefined;
 interface FormattedItem {
     title: string;
     /**
@@ -141,8 +234,6 @@ type ListPromptConfig = PromptConfig & {
  *  - `filter`  — no resolver uses it; transform values in `listItems` instead.
  *  - `validate`— validation is the resolver's top-level `validate`, which
  *    never routes through rendering (and gets `imports`).
- * (The legacy `SchemaParameterResolver` still honors `default`/`filter`/
- * `validate`, so the full `PromptConfig` stays for that path.)
  */
 type ResolverPromptConfig = Omit<PromptConfig, "name" | "default" | "filter" | "validate">;
 interface Resolver$1 {
@@ -322,40 +413,6 @@ declare function withPositional<T extends z.ZodType>(schema: T): T & {
 declare function isPositional(schema: z.ZodType): boolean;
 declare function openEnum<const T extends readonly [string, ...string[]]>(values: T, description: string): z.ZodUnion<readonly [z.ZodEnum<{ [k_1 in T[number]]: k_1; } extends infer T_1 ? { [k in keyof T_1]: { [k_1 in T[number]]: k_1; }[k]; } : never>, z.ZodString]>;
 
-/**
- * Method-call lifecycle hooks. Plugins contribute `onMethodStart` and/or
- * `onMethodEnd` on their context; `buildHooks` composes contributions across
- * plugins so multiple observers can coexist. Composition is right-additive
- * (newer plugins fire after earlier ones); only opt-in methods built through
- * `createPluginMethod` / `createPaginatedPluginMethod` trigger the hooks.
- */
-interface OnMethodStartContext {
-    methodName: string;
-    args: unknown[];
-    isPaginated: boolean;
-    /**
-     * Depth of this method invocation in the SDK call tree. 0 = outermost
-     * (user-initiated) call; 1+ = called from inside another SDK method.
-     * Observers can use this to ignore nested calls if they only want
-     * top-level events.
-     */
-    depth: number;
-}
-type OnMethodStart = (ctx: OnMethodStartContext) => void;
-interface OnMethodEndContext {
-    methodName: string;
-    args: unknown[];
-    isPaginated: boolean;
-    depth: number;
-    durationMs: number;
-    error?: Error;
-}
-type OnMethodEnd = (ctx: OnMethodEndContext) => void;
-interface MethodHooks {
-    onMethodStart?: OnMethodStart;
-    onMethodEnd?: OnMethodEnd;
-}
-
 /**
  * Descriptive metadata a leaf carries for the registry / CLI / MCP / docs:
  * description, categories, type, formatter, resolvers, etc.
@@ -378,10 +435,6 @@ interface LeafMetaFields {
     itemType?: string;
     returnType?: string;
     outputSchema?: z.ZodSchema;
-    inputParameters?: Array<{
-        name: string;
-        schema: z.ZodSchema;
-    }>;
     packages?: string[];
     experimental?: boolean;
     confirm?: "create-secret" | "delete";
@@ -555,12 +608,11 @@ interface DynamicResolver extends ResolverBase {
         input: Record<string, unknown>;
     }) => PromiseLike<unknown>;
     /** Produce the candidate list. Behaves like an SDK list method: returns a
-     * paginated result (await for the first page + `nextCursor`, or iterate pages),
-     * never a bare array. `cursor` is the stateless re-entry hook for "load more":
-     * an in-process host iterates the result; a distributed host awaits one page,
-     * carries `nextCursor`, and calls again with `cursor`. Required: a dynamic
-     * resolver IS a candidate-lister; a free-text field (with or without
-     * auto-resolution someday) is the `static` kind's job. */
+     * paginated result (the engine awaits the first page + `nextCursor`), never a
+     * bare array. `cursor` is the stateless re-entry hook for "load more": the
+     * engine awaits one page, carries `nextCursor`, and calls again with `cursor`.
+     * Required: a dynamic resolver IS a candidate-lister; a free-text field (with
+     * or without auto-resolution someday) is the `static` kind's job. */
     listItems: (bag: {
         imports: Record<string, unknown>;
         input: Record<string, unknown>;
@@ -644,6 +696,27 @@ interface ObjectResolver extends ResolverBase {
         input: Record<string, unknown>;
     }) => PromiseLike<Record<string, Field>>;
     definitions?: Record<string, Resolver>;
+    /** Open-ended entries whose keys aren't known up front (a `z.record`): the
+     * walk collects entries in an add/done loop, asking each entry's key (via
+     * `keys`, default a free-text string) then its value (via `values`), and
+     * assembling them onto the object alongside any fixed `properties`. The
+     * JSON-Schema `additionalProperties` analog. */
+    additionalKeys?: AdditionalKeys;
+}
+/** The open-keyed-entry spec for an {@link ObjectResolver.additionalKeys}. */
+interface AdditionalKeys {
+    /** Resolver for each entry's key; defaults to a free-text string prompt. A
+     * `{ ref }` resolves against the object's `definitions`. */
+    keys?: Resolver | ResolverRef;
+    /** Resolver for each entry's value. A `{ ref }` resolves against the
+     * object's `definitions`. */
+    values: Resolver | ResolverRef;
+    minEntries?: number;
+    maxEntries?: number;
+    /** Coarse value types so a free-text key/value answer coerces (usually
+     * `"string"` for the key), the way `Field.valueType` does. */
+    keyValueType?: string;
+    valueValueType?: string;
 }
 /** A homogeneous list: each element resolves through `items`. */
 interface ArrayResolver extends ResolverBase {
@@ -689,9 +762,9 @@ interface Formatter extends MethodAttachment {
     }) => FormattedItem;
 }
 /** What a dynamic resolver's `listItems` yields: an SDK list-method result
- * (`await` for the first page + `nextCursor`, or iterate pages in-process), or a
- * plain page / promise of one. No bare array and no scalar: it behaves like any
- * other list method, and exact-match short-circuits live on `tryResolveFromSearch`. */
+ * (the engine awaits the first page + `nextCursor`), or a plain page / promise
+ * of one. No bare array and no scalar: it behaves like any other list method,
+ * and exact-match short-circuits live on `tryResolveFromSearch`. */
 type ListItemsResult<TItem> = PaginatedSdkResult<TItem> | SdkPage<TItem> | Promise<SdkPage<TItem>>;
 /** A bound object resolver's literal property: its resolver is already bound
  * (or a `{ ref }` the CLI resolves against `definitions` at runtime). */
@@ -762,7 +835,8 @@ interface BoundDynamicResolver extends BoundResolverBase {
     } | null>;
 }
 /** Keyed members: static `properties` (bound) or a `getProperties`-built
- * (unbound) field map; `definitions` holds ref targets. */
+ * (unbound) field map; `definitions` holds ref targets. `additionalKeys`
+ * carries open-ended entries (a `z.record`). */
 interface BoundObjectResolver extends BoundResolverBase {
     type: "object";
     properties?: Record<string, BoundField>;
@@ -770,6 +844,17 @@ interface BoundObjectResolver extends BoundResolverBase {
     getProperties?: (bag: {
         input: Record<string, unknown>;
     }) => PromiseLike<Record<string, Field>>;
+    additionalKeys?: BoundAdditionalKeys;
+}
+/** The bound form of {@link AdditionalKeys}: `keys`/`values` are bound (or a
+ * `{ ref }` into the object's `definitions`). */
+interface BoundAdditionalKeys {
+    keys?: BoundResolver | ResolverRef;
+    values: BoundResolver | ResolverRef;
+    minEntries?: number;
+    maxEntries?: number;
+    keyValueType?: string;
+    valueValueType?: string;
 }
 /** A homogeneous list resolved through `items` (bound, or a ref into
  * `definitions`). */
@@ -1177,9 +1262,18 @@ interface MethodEntry {
      * `resolvePlugin` bind this; the surface and registry bind `value`. Absent
      * on legacy graph entries (they bind `value`). */
     internalValue?: (input: any) => any;
+    /** Produce the import-facing twin for a given call context: with a context,
+     * the twin mints a fresh child per invocation (callee inherits `callId`, sits
+     * one level deeper); without one it is the parent-less `internalValue`.
+     * `buildImports` binds this. Absent on legacy graph entries. */
+    bindInternal?: (ctx?: CallContext) => (...args: any[]) => any;
     chain: MiddlewareWrap[];
     /** Carried from the descriptor for the registry / CLI / MCP / docs. */
     inputSchema?: z.ZodType;
+    /** When true, the method owns its input validation and the boundary passes it
+     * through unparsed; carried so the controller skips its final `safeParse` too
+     * (it still uses `inputSchema` to plan/prompt parameters). */
+    skipInputValidation?: boolean;
     meta?: LeafMeta;
     /** Resolved output mode; the registry derives presentation from it. */
     output?: NormalizedOutput;
@@ -1424,7 +1518,7 @@ interface CategoryDefinition {
     /** Plural form of `title`. Auto-derived from the resolved title if omitted. */
     titlePlural?: string;
 }
-interface FunctionRegistryEntry<TSdk = any> {
+interface FunctionRegistryEntry {
     name: string;
     /**
      * Human-readable description of the function. Surfaced wherever the
@@ -1437,29 +1531,30 @@ interface FunctionRegistryEntry<TSdk = any> {
     itemType?: string;
     returnType?: string;
     inputSchema?: z.ZodSchema;
-    inputParameters?: Array<{
-        name: string;
-        schema: z.ZodSchema;
-    }>;
+    /**
+     * When true, the method owns its input validation and its boundary passes the
+     * input through unparsed. The resolution controller reads this to skip its
+     * final `safeParse` (it still uses `inputSchema` to plan/prompt parameters),
+     * so a method routed through the controller isn't re-validated against a
+     * schema it deliberately opts out of. Lifted off the materialized entry.
+     */
+    skipInputValidation?: boolean;
     outputSchema?: z.ZodSchema;
     /**
      * Ordered input keys the public surface projects onto positional arguments
      * (the method's `positional` declaration). Absent when the method takes only
      * the canonical single bag. Lifted off the materialized method entry by the
-     * surface builder, like `boundResolvers` — a runtime projection, not
+     * surface builder, like `resolvers` — a runtime projection, not
      * descriptive meta.
      */
     positional?: readonly string[];
     categories: string[];
-    resolvers?: Record<string, ResolverMetadata<TSdk, any, any>>;
     /**
-     * Per-parameter bound resolvers from the new model (imports already captured,
-     * called with `input` only, no sdk). Parallel to the legacy `resolvers` field
-     * and `formatter`: the surface builder lifts these off the materialized method
-     * entry. Additive bridge — populated for migrated `defineMethod` plugins; the
-     * legacy `resolvers` field above stays the source for unmigrated ones.
+     * Per-parameter bound resolvers (imports already captured, called with
+     * `input` only, no sdk). Lifted off the materialized method entry by the
+     * surface builder.
      */
-    boundResolvers?: Record<string, BoundResolver>;
+    resolvers?: Record<string, BoundResolver>;
     packages?: string[];
     /**
      * True if the plugin is registered only in the experimental SDK
@@ -1493,8 +1588,8 @@ interface FunctionDeprecation {
     /** User-facing deprecation message for why/how to migrate */
     message: string;
 }
-interface RegistryResult<TSdk = any> {
-    functions: FunctionRegistryEntry<TSdk>[];
+interface RegistryResult {
+    functions: FunctionRegistryEntry[];
     categories: {
         key: string;
         title: string;
@@ -1599,7 +1694,7 @@ type Sdk<T = {
 }> = T & {
     getRegistry(options?: {
         package?: string;
-    }): RegistryResult<T>;
+    }): RegistryResult;
 };
 
 /**
@@ -2187,6 +2282,8 @@ declare function defineResolver<const TImports extends ImportsInput = readonly [
         input: TInput;
     }) => PromiseLike<Record<string, Field>>;
     definitions?: Record<string, Resolver>;
+    /** Open-ended entries whose keys aren't known up front (a `z.record`). */
+    additionalKeys?: AdditionalKeys;
 }): ObjectResolver;
 declare function defineResolver(config: {
     type: "array";
@@ -2667,7 +2764,7 @@ declare const dangerousContextPlugin: PropertyPlugin<"context", SdkContext>;
  */
 declare const getRegistryPlugin: MethodPlugin<"getRegistry", {
     package?: string | undefined;
-} | undefined, RegistryResult<any>, readonly []> & LeafSummary<"kitcore", "getRegistry", readonly [PropertyPlugin<"context", SdkContext>]>;
+} | undefined, RegistryResult, readonly []> & LeafSummary<"kitcore", "getRegistry", readonly [PropertyPlugin<"context", SdkContext>]>;
 
 /**
  * The external escape-hatch key for an SDK's context. A Symbol,
@@ -2828,13 +2925,13 @@ type ControllerQuestion = {
     path: ControllerPath;
     message: string;
     description?: string;
-    /** Which container kind this decision gates. `array` is the add-another
-     * loop; `object` is the entry gate on an optional object, fired BEFORE
-     * its fields are fetched (`add` descends into the fields, `done` skips
-     * the container). A host that renders `message` + `actions` generically
-     * needs nothing else; this is additive metadata for hosts that render
-     * containers specially. */
-    container: "array" | "object";
+    /** Which container type this decision is about. `array`/`record` are the
+     * add-another loops; `object` covers both the optional-object gate (fired
+     * BEFORE its fields are fetched: `add` descends, `done` skips it) and the
+     * optional-fields gate. A host that renders `message` + `actions`
+     * generically needs nothing else; this is additive metadata for hosts
+     * that render containers specially. */
+    container: "array" | "object" | "record";
     /** Object optionals gate only: the fields the `add` action would walk
      * (key + display label + coarse value type), so a smart host can render
      * them (or a form section) instead of a blind yes/no. Dumb hosts keep
@@ -2943,11 +3040,16 @@ interface ControllerState {
     /** The path of the parameter (or nested field) currently being asked. */
     current?: ControllerPath;
     /** Which container decision the outstanding `collection` question is, when
-     * `current` points at one: the array add/done loop, an optional object's
-     * entry gate, or an object's optionals gate. Recorded explicitly so `step`'s
-     * add/done handling never infers the decision from value presence or
-     * resolver shape. Absent when `current` is a plain leaf question. */
-    gate?: "array" | "entry" | "optionals";
+     * `current` points at one, named `<container>_<subject>`: `array_items` and
+     * `record_entries` are the add/done loops; `object_optional` is whether to
+     * provide an optional object at all (fired before its fields are fetched);
+     * `object_optional_properties` is whether to fill that object's optional
+     * fields. `record_key` marks the one bespoke record step (collecting an
+     * entry's key); the value that follows is an ordinary leaf question with no
+     * gate. Recorded explicitly so `step`'s handling never infers the decision
+     * from value presence or resolver shape. Absent when `current` is a plain
+     * leaf question. */
+    gate?: "array_items" | "record_entries" | "record_key" | "object_optional" | "object_optional_properties";
     /** Where pagination stands for the current dynamic leaf: coordinates only
      * (cursor trail, generation), never items or live iterators — the page's
      * items ride the ask's question. */
@@ -3174,7 +3276,7 @@ type FunctionSdk = {
  *                      and `context.core`
  * @param options.schema - optional Zod schema for input validation
  */
-declare function createFunction<TOptions, TResult, TSchemaOptions extends TOptions = TOptions>(coreFn: (options: TOptions) => Promise<TResult>, options: {
+declare function createFunction<TOptions, TResult, TSchemaOptions extends TOptions = TOptions>(coreFn: (options: TOptions, context?: CallContext) => Promise<TResult>, options: {
     sdk: FunctionSdk;
     schema?: z.ZodSchema<TSchemaOptions>;
     name?: string;
@@ -3200,7 +3302,7 @@ type ItemType<TResult> = TResult extends {
 declare function createPaginatedFunction<TUserOptions, TResponse, TItem = ItemType<TResponse>>(coreFn: (options: TUserOptions & {
     cursor?: string;
     pageSize?: number;
-}) => Promise<TResponse>, options: {
+}, context?: CallContext) => Promise<TResponse>, options: {
     sdk: FunctionSdk;
     schema?: z.ZodSchema<TUserOptions>;
     name?: string;
@@ -3376,41 +3478,54 @@ interface PaginatedResult<TItem> {
     nextCursor?: string;
 }
 /**
- * One page-at-a-time source for `concatPaginated`: called with that source's
- * own cursor, resolves one page. An SDK paginated method fits directly
- * (`({ cursor }) => sdk.listThings({ cursor })` — awaiting a paginated
+ * Supplies one list to `concatLists`: called with that list's own cursor,
+ * resolves one page. An SDK paginated method fits directly
+ * (`({ cursor }) => sdk.listThings({ cursor })`; awaiting a paginated
  * result yields the requested page).
  */
-type PaginatedSource<TItem> = (options: {
+type ListSource<TItem> = (options: {
     cursor?: string;
 }) => PromiseLike<PaginatedResult<TItem>>;
 /**
- * Concatenate multiple paginated sources into a single paginated stream.
- * Sources are drained in order, one page per underlying call.
+ * List one page of several paginated lists joined end to end. Lists are
+ * drained in order; pass a page's `nextCursor` back in to get the next page.
  *
- * Pagination is stateless: every outgoing cursor encodes which source to
- * resume plus that source's own cursor, so a fresh `concatPaginated` call
- * with `cursor` continues exactly where the previous page left off. Sources
- * must therefore produce disjoint items themselves; there is no cross-source
- * dedupe (an in-memory seen-set could not survive the cursor round-trip).
+ * Pagination is stateless: every outgoing cursor encodes which list to
+ * resume plus that list's own cursor, so a fresh `concatLists` call
+ * continues exactly where the previous page left off. A cursor stores its
+ * position by list index, so it is only valid while `sources` keeps the
+ * same lists in the same order. Lists must produce disjoint items
+ * themselves; there is no cross-list dedupe (an in-memory seen-set could
+ * not survive the cursor round-trip).
  *
- * Uses paginateBuffered internally to normalize page sizes across source
- * boundaries — e.g. if the first source only has 2 items, they'll be
- * buffered with items from the next source into a full page.
- *
- * The result is a thenable for the first page that also async-iterates
- * pages in-process.
+ * Uses paginateBuffered internally to normalize page sizes across list
+ * boundaries: if the first list only has 2 items, they'll be buffered with
+ * items from the next list into a full page.
+ */
+declare function concatLists<TItem>({ sources, pageSize, cursor, }: {
+    /** The lists to concatenate, each supplied as a page-fetching source. */
+    sources: ListSource<TItem>[];
+    pageSize?: number;
+    /** Cursor from a previous `concatLists` page; resumes there. */
+    cursor?: string;
+}): Promise<PaginatedResult<TItem>>;
+/**
+ * @deprecated Use {@link concatLists}; awaiting either yields the same one
+ * page. The page-iterable half of the old return shape is gone; to walk
+ * pages, pass each page's `nextCursor` to a fresh call.
  */
 declare function concatPaginated<TItem>({ sources, pageSize, cursor, }: {
-    sources: PaginatedSource<TItem>[];
+    sources: ListSource<TItem>[];
     pageSize?: number;
-    /** Cursor from a previous `concatPaginated` page; resumes the stream. */
     cursor?: string;
-}): PromiseLike<PaginatedResult<TItem>> & AsyncIterable<PaginatedResult<TItem>>;
+}): Promise<PaginatedResult<TItem>>;
 /**
  * Strip the PromiseLike from an async iterable, returning a plain
  * AsyncIterable. This prevents async functions from unwrapping the
  * iterable (since async only unwraps PromiseLike, not AsyncIterable).
+ *
+ * @deprecated Call `.pages()` on the paginated result instead; it returns a
+ * plain AsyncIterable over pages with no wrapper needed.
  */
 declare function toIterable<T>(source: AsyncIterable<T>): AsyncIterable<T>;
 
@@ -3495,4 +3610,4 @@ declare class CoreCancelledSignal extends CoreSignal {
     constructor(message?: string);
 }
 
-export { type AdaptError, type AdaptErrorOptions, type AdaptPage, type AggregatePlugin, type ArrayResolver$1 as ArrayResolver, type AsyncContext, type BoundFormatter, type BoundResolver, CONTEXT, CORE_ERROR_SYMBOL, CORE_OPTIONS_ID, CORE_SIGNAL_SYMBOL, type CategoryDefinition, 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 HookPlugin, type LeafMeta, type LeafSummary, type LegacyMergePlugin, type LegacyPlugin, type ListItemsResult, type ListPromptConfig, type MethodAttachment, type MethodHooks, type MethodOverridePlugin, type MethodPlugin, type MethodScope, type Resolver as ModelResolver, 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 Sdk, type SdkContext, type SdkPage, type StaticResolver$1 as StaticResolver, type ValidResolvers, addPlugin, composePlugins, concatPaginated, coreOptionsPluginRef, createAsyncContext, createController, createCoreError, createCorePlugin, createDeprecationLogger, createFunction, createPaginatedFunction, createPaginatedPluginMethod, createPluginMethod, createPluginStack, createPrefixedCursor, createSdk, createValidator, dangerousContextPlugin, declareMethod, declareOptionalProperty, declarePlugin, declareProperty, decodeIncomingCursor, defaultLogDeprecation, defineFormatter, defineHook, defineLegacyMerge, defineMethod, defineMethodOverride, definePlugin, defineProperty, defineResolver, disposeSdk, fromFunctionPlugin, getContext, getCoreErrorCause, getCoreErrorCode, getCurrentDepth, getCurrentScope, getFieldDescriptions, getOutputSchema, getRegistryPlugin, getSchemaDescription, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, omitExports, openEnum, paginate, paginateBuffered, paginateMaxItems, resolvePlugin, runInMethodScope, runWithTelemetryContext, selectExports, splitPrefixedCursor, toIterable, toSnakeCase, toTitleCase, validateOptions, withOutputSchema, withPositional, withResolver };
+export { type AdaptError, type AdaptErrorOptions, type AdaptPage, type AggregatePlugin, type ArrayResolver$1 as ArrayResolver, type AsyncContext, type BoundFormatter, type BoundResolver, CONTEXT, CORE_ERROR_SYMBOL, CORE_OPTIONS_ID, CORE_SIGNAL_SYMBOL, type CategoryDefinition, 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 HookPlugin, type LeafMeta, type LeafSummary, type LegacyMergePlugin, type LegacyPlugin, type ListItemsResult, type ListPromptConfig, type MethodAttachment, type MethodHooks, type MethodOverridePlugin, type MethodPlugin, type MethodScope, type Resolver as ModelResolver, 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 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, declareMethod, declareOptionalProperty, declarePlugin, declareProperty, decodeIncomingCursor, defaultLogDeprecation, defineFormatter, defineHook, defineLegacyMerge, defineMethod, defineMethodOverride, definePlugin, defineProperty, defineResolver, disposeSdk, fromFunctionPlugin, getContext, getCoreErrorCause, getCoreErrorCode, getCurrentDepth, getCurrentScope, getFieldDescriptions, getOutputSchema, getRegistryPlugin, getSchemaDescription, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, omitExports, openEnum, paginate, paginateBuffered, paginateMaxItems, resolvePlugin, runInMethodScope, runWithTelemetryContext, selectExports, splitPrefixedCursor, toIterable, toSnakeCase, toTitleCase, validateOptions, withOutputSchema, withPositional, withResolver };