@zapier/kitcore 0.10.0 → 0.11.0

package/dist/index.d.mts

@@ -78,26 +78,67 @@ type PaginatedSdkFunction<TOptions, TItem> = (options: TOptions) => PaginatedSdk
  * unforgeability the `INTERNAL_CALL` sentinel relies on.
  */
 declare const CALL_CONTEXT_BRAND: unique symbol;
+/**
+ * The per-invocation annotation bag: an open string-keyed map a head fills with
+ * telemetry-shaping fields (via the boundary annotator, a method's pre-run
+ * `annotator`, or the run bag's mid-`run` `annotate`) and reads back on the
+ * method-lifecycle hook context. Framework-neutral: kitcore does not know or
+ * constrain the keys.
+ */
+type Annotations = Record<string, unknown>;
+/**
+ * Origin of a call's root. `"surface"` = entered through the SDK surface, or a
+ * parent-less runtime delegation that still represents real user work;
+ * `"internal"` = a framework-internal root minted by kitcore's own machinery,
+ * which a head can suppress from telemetry.
+ */
+type CallOrigin = "surface" | "internal";
 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;
+    /**
+     * Minted once at the root call; copied verbatim to every nested (child) call.
+     * `readonly`: method code owns only the `annotations` bag. A child copies this
+     * off the live parent when the delegated call fires, so mutating it mid-run
+     * would corrupt the child's correlation id.
+     */
+    readonly callId: string | null;
+    /**
+     * 0 at the outermost call; `parent.depth + 1` for a delegated call. `readonly`
+     * for the same reason as `callId` — a mutated depth would mis-nest children
+     * and, where ALS can't correct it (browsers), duplicate telemetry.
+     */
+    readonly 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.
+     * Method `run` code contributes through the run bag's `annotate` function
+     * rather than writing here directly; the bag reference is fixed, only its
+     * contents change.
+     */
+    readonly annotations: Annotations;
+    /**
+     * Origin of the call's root, copied verbatim to every child. `"surface"`
+     * (the default) marks a surface-origin root — a call that entered through the
+     * SDK surface, or a parent-less runtime delegation that still represents real
+     * user work (e.g. a delegation proxy reaching another method). `"internal"`
+     * marks a framework-internal root minted by kitcore's own build-time machinery
+     * (resolver/formatter/dispose/observer twins, `resolvePlugin`), which a head
+     * can suppress from telemetry. Orthogonal to `depth`: an internal root is
+     * still `depth 0`. `readonly` so a child can't inherit a mutated origin.
      */
-    annotations: Record<string, unknown>;
+    readonly callOrigin: CallOrigin;
     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.
+ * `onMethodEnd` observers, plus an optional pre-run `annotator` that returns
+ * fields merged into the call's annotation bag; `buildHooks` composes each
+ * across plugins so multiple contributors coexist. Composition is right-additive
+ * (newer plugins fire — and `annotator` fields win — after earlier ones); only
+ * opt-in methods built through `createPluginMethod` /
+ * `createPaginatedPluginMethod` trigger the hooks.
  */
+
 interface OnMethodStartContext {
     methodName: string;
     args: unknown[];
@@ -109,20 +150,48 @@ interface OnMethodStartContext {
      * top-level events.
      */
     depth: number;
+    /** The call's correlation id, copied from the per-call context; `null` where
+     * id minting was unavailable. */
+    callId: string | null;
+    /**
+     * Origin of the call's root, copied from the per-call context. `"surface"` =
+     * surface-origin (an SDK-surface call or a runtime delegation — real user
+     * work); `"internal"` = a framework-internal call minted by kitcore's own
+     * machinery (resolver/formatter/dispose/observer twins, `resolvePlugin`).
+     * Orthogonal to `depth` (an internal call is still `depth 0`); a head can drop
+     * internal-origin calls from telemetry.
+     */
+    callOrigin: CallOrigin;
+    /**
+     * The call's annotation bag, carried live from the per-call context. At
+     * `onMethodStart` it holds the early-knowable fields (boundary annotator +
+     * a method's pre-run `annotator`); by `onMethodEnd` any mid-`run` writes
+     * are visible too (same object reference throughout the call).
+     */
+    annotations: Annotations;
 }
 type OnMethodStart = (ctx: OnMethodStartContext) => void;
-interface OnMethodEndContext {
-    methodName: string;
-    args: unknown[];
-    isPaginated: boolean;
-    depth: number;
+interface OnMethodEndContext extends OnMethodStartContext {
     durationMs: number;
     error?: Error;
 }
 type OnMethodEnd = (ctx: OnMethodEndContext) => void;
+/**
+ * A composed pre-run annotator: given a call's method name and (normalized,
+ * pre-validation) input, it returns {@link Annotations} the boundary merges into
+ * the call's bag before `onMethodStart`. Unlike the `void` lifecycle observers,
+ * this one returns a value; composition merges the returned bags rather than
+ * chaining side effects. A contributor with nothing to add returns an empty bag,
+ * so absence is modelled by no annotator rather than an `undefined` return.
+ */
+type ComposedAnnotator = (ctx: {
+    methodName: string;
+    input: unknown;
+}) => Annotations;
 interface MethodHooks {
     onMethodStart?: OnMethodStart;
     onMethodEnd?: OnMethodEnd;
+    annotator?: ComposedAnnotator;
 }
 
 /**
@@ -536,13 +605,42 @@ type ImportsOf<TImports extends ImportsInput> = TImports extends readonly [] ? R
 /**
  * The bag a method body receives. `imports` is the dependency-narrowed reach;
  * `state` is the plugin's private constructor result (undefined when none);
- * `input` is the canonical call argument.
+ * `input` is the canonical call argument; `callContext` is the live per-call
+ * context (call identity plus the annotation bag the boundary reads back on the
+ * lifecycle hooks); `annotate` merges mid-run-derived telemetry fields into that
+ * bag. Prefer `annotate` over writing `callContext.annotations` directly.
  */
 interface MethodRunBag<TImports, TInput, TState = unknown> {
     imports: TImports;
     state: TState;
     input: TInput;
+    callContext: CallContext;
+    /** Merge mid-run-derived telemetry fields into the call's annotation bag. The
+     * declarative pre-run sibling is the method's `annotator` config; both add
+     * to the same bag, one during `run`, one before it. */
+    annotate: (metadata: Annotations) => void;
 }
+/**
+ * A method's declarative pre-`run` annotator: given the method's raw,
+ * pre-validation `input`, it returns {@link Annotations} the boundary merges
+ * into the call's bag before `onMethodStart`. The input is `unknown` because
+ * schema coercion/transformation has not run; an annotator must narrow it before
+ * reading fields. A provider with nothing to add returns an empty bag, so absence
+ * is modelled by no provider rather than an `undefined` return.
+ */
+type MethodAnnotator = (bag: {
+    input: unknown;
+}) => Annotations;
+/**
+ * A hook's declarative pre-`run` annotator: like {@link MethodAnnotator} but
+ * cross-cutting, so it also receives the `methodName` and the hook's `state`.
+ * Many hooks' annotators coexist; the boundary composes them.
+ */
+type HookAnnotator<TState = unknown> = (bag: {
+    methodName: string;
+    input: unknown;
+    state: TState;
+}) => Annotations;
 /** Shared plumbing for the method attachments: each declares its own
  * dependencies. Resolvers and formatters are otherwise separate concepts. */
 interface MethodAttachment {
@@ -943,6 +1041,14 @@ interface MethodPlugin<TName extends string = string, TInput = unknown, TOutput
     resolvers?: Record<string, Resolver>;
     /** Output formatter (method attachment). Bound into the entry at createSdk. */
     formatter?: Formatter;
+    /** Declarative pre-`run` annotator: the boundary invokes it before
+     * `onMethodStart` with the (pre-validation) `input`, and merges its returned
+     * `Annotations` into the call's bag. Runs synchronously and receives only
+     * `input` — the per-method sibling of the run bag's mid-`run` `annotate`,
+     * which is where fields needing imports or async work are written. For
+     * telemetry fields knowable before the method's own work; never passed to
+     * `run`. */
+    annotator?: MethodAnnotator;
     run: (bag: MethodRunBag<any, TInput, any>) => TOutput;
     /** How `run`'s result is shaped into the public surface (see Output in the
      * design doc). Omitted is "raw". Stored loosely; the precise per-mode typing
@@ -1218,6 +1324,9 @@ interface HookPlugin<TName extends string = string> {
             state: unknown;
         }) => void;
     };
+    /** Composable pre-run annotator: returns `Annotations` merged into the call's
+     * bag before `onMethodStart`. Coexists with other hooks' annotators. */
+    annotator?: HookAnnotator;
 }
 type AnyPlugin = AnyLeafPlugin | AnyAggregatePlugin | AnyLegacyPlugin | HookPlugin | MethodOverridePlugin;
 /**
@@ -1263,10 +1372,16 @@ interface MethodEntry {
      * 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;
+     * the twin mints a fresh child per invocation (callee inherits `callId`, its
+     * origin, and sits one level deeper); without one it is parent-less — the
+     * surface-origin `internalValue` by default, or a framework-internal root when
+     * `frameworkOrigin` is set (kitcore's own build-time passes request it, so
+     * their delegated calls can be dropped from telemetry). `buildImports` binds
+     * this. Absent on legacy graph entries. */
+    bindInternal?: (opts: {
+        ctx?: CallContext;
+        frameworkOrigin?: boolean;
+    }) => (...args: any[]) => any;
     chain: MiddlewareWrap[];
     /** Carried from the descriptor for the registry / CLI / MCP / docs. */
     inputSchema?: z.ZodType;
@@ -2077,6 +2192,7 @@ declare function defineMethod<const TName extends string, TInput, TOutput, const
     skipInputValidation?: boolean;
     resolvers?: Record<string, Resolver>;
     formatter?: Formatter;
+    annotator?: MethodAnnotator;
     output?: "raw" | {
         type: "raw";
     };
@@ -2098,6 +2214,7 @@ declare function defineMethod<const TName extends string, TInput, TResponse exte
     inputSchema?: z.ZodType<TInput>;
     resolvers?: Record<string, Resolver>;
     formatter?: Formatter;
+    annotator?: MethodAnnotator;
     output: "item" | {
         type: "item";
     };
@@ -2120,6 +2237,7 @@ declare function defineMethod<const TName extends string, TInput, TResponse exte
     inputSchema?: z.ZodType<TInput>;
     resolvers?: Record<string, Resolver>;
     formatter?: Formatter;
+    annotator?: MethodAnnotator;
     output: "list" | {
         type: "list";
         adaptPage?: undefined;
@@ -2142,6 +2260,7 @@ declare function defineMethod<const TName extends string, TInput, TResponse, TIt
     inputSchema?: z.ZodType<TInput>;
     resolvers?: Record<string, Resolver>;
     formatter?: Formatter;
+    annotator?: MethodAnnotator;
     output: {
         type: "list";
         adaptPage: (response: TResponse) => SdkPage<TItem>;
@@ -2433,6 +2552,14 @@ declare function defineHook<const TImports extends ImportsInput = readonly [], T
             state: TState;
         }) => void;
     };
+    /** Cross-cutting pre-run annotation. The boundary composes hook annotators
+     * right-additively (a later hook's fields win on collision) ahead of the
+     * method's own `annotator`, invokes them best-effort for the outermost
+     * surface-origin call only, and merges their returned `Annotations` into the
+     * call's bag. Synchronous and import-less; fields needing imports or async
+     * work are written mid-`run` via the run bag's `annotate`. Returns a value
+     * (unlike `observe`) and never reaches `run`. */
+    annotator?: HookAnnotator<TState>;
 }): HookPlugin;
 /**
  * Declare a stand-in for a whole aggregate (module) registered elsewhere: the
@@ -3280,6 +3407,10 @@ declare function createFunction<TOptions, TResult, TSchemaOptions extends TOptio
     sdk: FunctionSdk;
     schema?: z.ZodSchema<TSchemaOptions>;
     name?: string;
+    /** Pre-run per-method annotator (see applyAnnotations): invoked before
+     * onMethodStart with the normalized input, its result merged into the
+     * call's annotation bag. */
+    annotator?: (input: unknown) => Annotations;
     /** Live read of the method's deprecation meta (see signalDeprecation). */
     getDeprecation?: () => FunctionDeprecation | undefined;
 }): (callOptions?: TOptions) => Promise<TResult>;
@@ -3316,6 +3447,8 @@ declare function createPaginatedFunction<TUserOptions, TResponse, TItem = ItemTy
      * would collapse `TItem` to `unknown`.
      */
     adaptPage?: (response: TResponse) => SdkPage<NoInfer<TItem>>;
+    /** Pre-run per-method annotator (see applyAnnotations). */
+    annotator?: (input: unknown) => Annotations;
     /** Live read of the method's deprecation meta (see signalDeprecation). */
     getDeprecation?: () => FunctionDeprecation | undefined;
 }): (options?: TUserOptions & {
@@ -3344,9 +3477,8 @@ declare function createCorePlugin(options: CoreOptions): Plugin<object, {
  * runs in its own AsyncLocalStorage scope (via `runInMethodScope`), isolating
  * its depth counter and any plugin-specific state from concurrent calls.
  *
- * The toolkit reserves the `depth` field; anything else on the scope is
- * opaque key/value storage that plugins can use (e.g. eventEmission stores
- * its `MethodMetadata` under its own key).
+ * The toolkit reserves the `depth` field; additional fields remain available
+ * for plugin-specific scoped state.
  */
 /**
  * The per-call scope object held in ALS. Toolkit owns `depth`; everything
@@ -3617,4 +3749,4 @@ declare class CoreCancelledSignal extends CoreSignal {
  */
 declare function isCoreCancelledSignal(value: unknown): value is CoreCancelledSignal;
 
-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, isCoreCancelledSignal, 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 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 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, isCoreCancelledSignal, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, omitExports, openEnum, paginate, paginateBuffered, paginateMaxItems, resolvePlugin, runInMethodScope, runWithTelemetryContext, selectExports, splitPrefixedCursor, toIterable, toSnakeCase, toTitleCase, validateOptions, withOutputSchema, withPositional, withResolver };

package/dist/index.d.ts

@@ -78,26 +78,67 @@ type PaginatedSdkFunction<TOptions, TItem> = (options: TOptions) => PaginatedSdk
  * unforgeability the `INTERNAL_CALL` sentinel relies on.
  */
 declare const CALL_CONTEXT_BRAND: unique symbol;
+/**
+ * The per-invocation annotation bag: an open string-keyed map a head fills with
+ * telemetry-shaping fields (via the boundary annotator, a method's pre-run
+ * `annotator`, or the run bag's mid-`run` `annotate`) and reads back on the
+ * method-lifecycle hook context. Framework-neutral: kitcore does not know or
+ * constrain the keys.
+ */
+type Annotations = Record<string, unknown>;
+/**
+ * Origin of a call's root. `"surface"` = entered through the SDK surface, or a
+ * parent-less runtime delegation that still represents real user work;
+ * `"internal"` = a framework-internal root minted by kitcore's own machinery,
+ * which a head can suppress from telemetry.
+ */
+type CallOrigin = "surface" | "internal";
 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;
+    /**
+     * Minted once at the root call; copied verbatim to every nested (child) call.
+     * `readonly`: method code owns only the `annotations` bag. A child copies this
+     * off the live parent when the delegated call fires, so mutating it mid-run
+     * would corrupt the child's correlation id.
+     */
+    readonly callId: string | null;
+    /**
+     * 0 at the outermost call; `parent.depth + 1` for a delegated call. `readonly`
+     * for the same reason as `callId` — a mutated depth would mis-nest children
+     * and, where ALS can't correct it (browsers), duplicate telemetry.
+     */
+    readonly 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.
+     * Method `run` code contributes through the run bag's `annotate` function
+     * rather than writing here directly; the bag reference is fixed, only its
+     * contents change.
+     */
+    readonly annotations: Annotations;
+    /**
+     * Origin of the call's root, copied verbatim to every child. `"surface"`
+     * (the default) marks a surface-origin root — a call that entered through the
+     * SDK surface, or a parent-less runtime delegation that still represents real
+     * user work (e.g. a delegation proxy reaching another method). `"internal"`
+     * marks a framework-internal root minted by kitcore's own build-time machinery
+     * (resolver/formatter/dispose/observer twins, `resolvePlugin`), which a head
+     * can suppress from telemetry. Orthogonal to `depth`: an internal root is
+     * still `depth 0`. `readonly` so a child can't inherit a mutated origin.
      */
-    annotations: Record<string, unknown>;
+    readonly callOrigin: CallOrigin;
     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.
+ * `onMethodEnd` observers, plus an optional pre-run `annotator` that returns
+ * fields merged into the call's annotation bag; `buildHooks` composes each
+ * across plugins so multiple contributors coexist. Composition is right-additive
+ * (newer plugins fire — and `annotator` fields win — after earlier ones); only
+ * opt-in methods built through `createPluginMethod` /
+ * `createPaginatedPluginMethod` trigger the hooks.
  */
+
 interface OnMethodStartContext {
     methodName: string;
     args: unknown[];
@@ -109,20 +150,48 @@ interface OnMethodStartContext {
      * top-level events.
      */
     depth: number;
+    /** The call's correlation id, copied from the per-call context; `null` where
+     * id minting was unavailable. */
+    callId: string | null;
+    /**
+     * Origin of the call's root, copied from the per-call context. `"surface"` =
+     * surface-origin (an SDK-surface call or a runtime delegation — real user
+     * work); `"internal"` = a framework-internal call minted by kitcore's own
+     * machinery (resolver/formatter/dispose/observer twins, `resolvePlugin`).
+     * Orthogonal to `depth` (an internal call is still `depth 0`); a head can drop
+     * internal-origin calls from telemetry.
+     */
+    callOrigin: CallOrigin;
+    /**
+     * The call's annotation bag, carried live from the per-call context. At
+     * `onMethodStart` it holds the early-knowable fields (boundary annotator +
+     * a method's pre-run `annotator`); by `onMethodEnd` any mid-`run` writes
+     * are visible too (same object reference throughout the call).
+     */
+    annotations: Annotations;
 }
 type OnMethodStart = (ctx: OnMethodStartContext) => void;
-interface OnMethodEndContext {
-    methodName: string;
-    args: unknown[];
-    isPaginated: boolean;
-    depth: number;
+interface OnMethodEndContext extends OnMethodStartContext {
     durationMs: number;
     error?: Error;
 }
 type OnMethodEnd = (ctx: OnMethodEndContext) => void;
+/**
+ * A composed pre-run annotator: given a call's method name and (normalized,
+ * pre-validation) input, it returns {@link Annotations} the boundary merges into
+ * the call's bag before `onMethodStart`. Unlike the `void` lifecycle observers,
+ * this one returns a value; composition merges the returned bags rather than
+ * chaining side effects. A contributor with nothing to add returns an empty bag,
+ * so absence is modelled by no annotator rather than an `undefined` return.
+ */
+type ComposedAnnotator = (ctx: {
+    methodName: string;
+    input: unknown;
+}) => Annotations;
 interface MethodHooks {
     onMethodStart?: OnMethodStart;
     onMethodEnd?: OnMethodEnd;
+    annotator?: ComposedAnnotator;
 }
 
 /**
@@ -536,13 +605,42 @@ type ImportsOf<TImports extends ImportsInput> = TImports extends readonly [] ? R
 /**
  * The bag a method body receives. `imports` is the dependency-narrowed reach;
  * `state` is the plugin's private constructor result (undefined when none);
- * `input` is the canonical call argument.
+ * `input` is the canonical call argument; `callContext` is the live per-call
+ * context (call identity plus the annotation bag the boundary reads back on the
+ * lifecycle hooks); `annotate` merges mid-run-derived telemetry fields into that
+ * bag. Prefer `annotate` over writing `callContext.annotations` directly.
  */
 interface MethodRunBag<TImports, TInput, TState = unknown> {
     imports: TImports;
     state: TState;
     input: TInput;
+    callContext: CallContext;
+    /** Merge mid-run-derived telemetry fields into the call's annotation bag. The
+     * declarative pre-run sibling is the method's `annotator` config; both add
+     * to the same bag, one during `run`, one before it. */
+    annotate: (metadata: Annotations) => void;
 }
+/**
+ * A method's declarative pre-`run` annotator: given the method's raw,
+ * pre-validation `input`, it returns {@link Annotations} the boundary merges
+ * into the call's bag before `onMethodStart`. The input is `unknown` because
+ * schema coercion/transformation has not run; an annotator must narrow it before
+ * reading fields. A provider with nothing to add returns an empty bag, so absence
+ * is modelled by no provider rather than an `undefined` return.
+ */
+type MethodAnnotator = (bag: {
+    input: unknown;
+}) => Annotations;
+/**
+ * A hook's declarative pre-`run` annotator: like {@link MethodAnnotator} but
+ * cross-cutting, so it also receives the `methodName` and the hook's `state`.
+ * Many hooks' annotators coexist; the boundary composes them.
+ */
+type HookAnnotator<TState = unknown> = (bag: {
+    methodName: string;
+    input: unknown;
+    state: TState;
+}) => Annotations;
 /** Shared plumbing for the method attachments: each declares its own
  * dependencies. Resolvers and formatters are otherwise separate concepts. */
 interface MethodAttachment {
@@ -943,6 +1041,14 @@ interface MethodPlugin<TName extends string = string, TInput = unknown, TOutput
     resolvers?: Record<string, Resolver>;
     /** Output formatter (method attachment). Bound into the entry at createSdk. */
     formatter?: Formatter;
+    /** Declarative pre-`run` annotator: the boundary invokes it before
+     * `onMethodStart` with the (pre-validation) `input`, and merges its returned
+     * `Annotations` into the call's bag. Runs synchronously and receives only
+     * `input` — the per-method sibling of the run bag's mid-`run` `annotate`,
+     * which is where fields needing imports or async work are written. For
+     * telemetry fields knowable before the method's own work; never passed to
+     * `run`. */
+    annotator?: MethodAnnotator;
     run: (bag: MethodRunBag<any, TInput, any>) => TOutput;
     /** How `run`'s result is shaped into the public surface (see Output in the
      * design doc). Omitted is "raw". Stored loosely; the precise per-mode typing
@@ -1218,6 +1324,9 @@ interface HookPlugin<TName extends string = string> {
             state: unknown;
         }) => void;
     };
+    /** Composable pre-run annotator: returns `Annotations` merged into the call's
+     * bag before `onMethodStart`. Coexists with other hooks' annotators. */
+    annotator?: HookAnnotator;
 }
 type AnyPlugin = AnyLeafPlugin | AnyAggregatePlugin | AnyLegacyPlugin | HookPlugin | MethodOverridePlugin;
 /**
@@ -1263,10 +1372,16 @@ interface MethodEntry {
      * 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;
+     * the twin mints a fresh child per invocation (callee inherits `callId`, its
+     * origin, and sits one level deeper); without one it is parent-less — the
+     * surface-origin `internalValue` by default, or a framework-internal root when
+     * `frameworkOrigin` is set (kitcore's own build-time passes request it, so
+     * their delegated calls can be dropped from telemetry). `buildImports` binds
+     * this. Absent on legacy graph entries. */
+    bindInternal?: (opts: {
+        ctx?: CallContext;
+        frameworkOrigin?: boolean;
+    }) => (...args: any[]) => any;
     chain: MiddlewareWrap[];
     /** Carried from the descriptor for the registry / CLI / MCP / docs. */
     inputSchema?: z.ZodType;
@@ -2077,6 +2192,7 @@ declare function defineMethod<const TName extends string, TInput, TOutput, const
     skipInputValidation?: boolean;
     resolvers?: Record<string, Resolver>;
     formatter?: Formatter;
+    annotator?: MethodAnnotator;
     output?: "raw" | {
         type: "raw";
     };
@@ -2098,6 +2214,7 @@ declare function defineMethod<const TName extends string, TInput, TResponse exte
     inputSchema?: z.ZodType<TInput>;
     resolvers?: Record<string, Resolver>;
     formatter?: Formatter;
+    annotator?: MethodAnnotator;
     output: "item" | {
         type: "item";
     };
@@ -2120,6 +2237,7 @@ declare function defineMethod<const TName extends string, TInput, TResponse exte
     inputSchema?: z.ZodType<TInput>;
     resolvers?: Record<string, Resolver>;
     formatter?: Formatter;
+    annotator?: MethodAnnotator;
     output: "list" | {
         type: "list";
         adaptPage?: undefined;
@@ -2142,6 +2260,7 @@ declare function defineMethod<const TName extends string, TInput, TResponse, TIt
     inputSchema?: z.ZodType<TInput>;
     resolvers?: Record<string, Resolver>;
     formatter?: Formatter;
+    annotator?: MethodAnnotator;
     output: {
         type: "list";
         adaptPage: (response: TResponse) => SdkPage<TItem>;
@@ -2433,6 +2552,14 @@ declare function defineHook<const TImports extends ImportsInput = readonly [], T
             state: TState;
         }) => void;
     };
+    /** Cross-cutting pre-run annotation. The boundary composes hook annotators
+     * right-additively (a later hook's fields win on collision) ahead of the
+     * method's own `annotator`, invokes them best-effort for the outermost
+     * surface-origin call only, and merges their returned `Annotations` into the
+     * call's bag. Synchronous and import-less; fields needing imports or async
+     * work are written mid-`run` via the run bag's `annotate`. Returns a value
+     * (unlike `observe`) and never reaches `run`. */
+    annotator?: HookAnnotator<TState>;
 }): HookPlugin;
 /**
  * Declare a stand-in for a whole aggregate (module) registered elsewhere: the
@@ -3280,6 +3407,10 @@ declare function createFunction<TOptions, TResult, TSchemaOptions extends TOptio
     sdk: FunctionSdk;
     schema?: z.ZodSchema<TSchemaOptions>;
     name?: string;
+    /** Pre-run per-method annotator (see applyAnnotations): invoked before
+     * onMethodStart with the normalized input, its result merged into the
+     * call's annotation bag. */
+    annotator?: (input: unknown) => Annotations;
     /** Live read of the method's deprecation meta (see signalDeprecation). */
     getDeprecation?: () => FunctionDeprecation | undefined;
 }): (callOptions?: TOptions) => Promise<TResult>;
@@ -3316,6 +3447,8 @@ declare function createPaginatedFunction<TUserOptions, TResponse, TItem = ItemTy
      * would collapse `TItem` to `unknown`.
      */
     adaptPage?: (response: TResponse) => SdkPage<NoInfer<TItem>>;
+    /** Pre-run per-method annotator (see applyAnnotations). */
+    annotator?: (input: unknown) => Annotations;
     /** Live read of the method's deprecation meta (see signalDeprecation). */
     getDeprecation?: () => FunctionDeprecation | undefined;
 }): (options?: TUserOptions & {
@@ -3344,9 +3477,8 @@ declare function createCorePlugin(options: CoreOptions): Plugin<object, {
  * runs in its own AsyncLocalStorage scope (via `runInMethodScope`), isolating
  * its depth counter and any plugin-specific state from concurrent calls.
  *
- * The toolkit reserves the `depth` field; anything else on the scope is
- * opaque key/value storage that plugins can use (e.g. eventEmission stores
- * its `MethodMetadata` under its own key).
+ * The toolkit reserves the `depth` field; additional fields remain available
+ * for plugin-specific scoped state.
  */
 /**
  * The per-call scope object held in ALS. Toolkit owns `depth`; everything
@@ -3617,4 +3749,4 @@ declare class CoreCancelledSignal extends CoreSignal {
  */
 declare function isCoreCancelledSignal(value: unknown): value is CoreCancelledSignal;
 
-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, isCoreCancelledSignal, 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 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 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, isCoreCancelledSignal, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, omitExports, openEnum, paginate, paginateBuffered, paginateMaxItems, resolvePlugin, runInMethodScope, runWithTelemetryContext, selectExports, splitPrefixedCursor, toIterable, toSnakeCase, toTitleCase, validateOptions, withOutputSchema, withPositional, withResolver };