@robota-sdk/agent-core 3.0.0-beta.83 → 3.0.0-beta.84

package/dist/browser/index.d.ts

@@ -61,146 +61,37 @@ declare const TypeUtils: {
   isUniversalValue: (value: TUniversalValue) => value is TUniversalValue;
 };
 //#endregion
-//#region src/interfaces/cache.d.ts
-/**
- * Cache key identifying a unique LLM execution request
- */
-interface ICacheKey {
-  /** SHA-256 hash of the serialized request */
-  hash: string;
-  /** Model identifier */
-  model: string;
-  /** Provider name */
-  provider: string;
-}
-/**
- * Cached LLM response entry
- */
-interface ICacheEntry {
-  /** Cache key that produced this entry */
-  key: ICacheKey;
-  /** Cached response content */
-  response: string;
-  /** When the entry was cached */
-  timestamp: number;
-  /** SHA-256 integrity hash of the response */
-  integrityHash: string;
-}
-/**
- * Cache storage interface for pluggable backends
- */
-interface ICacheStorage {
-  /** Retrieve a cached entry by key hash */
-  get(hash: string): ICacheEntry | undefined;
-  /** Store a cache entry */
-  set(entry: ICacheEntry): void;
-  /** Delete a cached entry by key hash */
-  delete(hash: string): boolean;
-  /** Clear all cached entries */
-  clear(): void;
-  /** Get cache statistics */
-  getStats(): ICacheStats;
-}
-/**
- * Cache performance statistics
- */
-interface ICacheStats {
-  /** Number of cache hits */
-  hits: number;
-  /** Number of cache misses */
-  misses: number;
-  /** Current number of cached entries */
-  entries: number;
-  /** Hit rate (hits / (hits + misses)), 0 if no lookups */
-  hitRate: number;
+//#region src/interfaces/tool-continuation.d.ts
+/** Core-owned identity, independent of a provider's reusable tool-call identifier. */
+interface IToolActionIdentity {
+  executionId: string;
+  actionId: string;
+  parentCallId: string;
+  toolCallId: string;
+  toolName: string;
 }
-/**
- * Configuration options for execution caching
- */
-interface ICacheOptions {
-  /** Whether caching is enabled */
-  enabled: boolean;
-  /** Maximum number of cached entries */
-  maxEntries: number;
-  /** Time-to-live in milliseconds */
-  ttlMs: number;
+interface IToolContinuationPrompt {
+  kind: string;
+  data: TToolParameters;
 }
-//#endregion
-//#region src/interfaces/interaction.d.ts
-/**
- * UI-agnostic "ask the user" contract (CMD-004).
- *
- * The SSOT for the interaction action lives in agent-core so every interaction *source* can reach it:
- * command execution (`ICommandHostContext`, agent-framework) AND tool execution
- * (`IToolExecutionContext`, agent-core, for model-issued questions — CMD-005). These are pure types
- * with no runtime dependency, so the contract crosses a serialization/transport boundary unchanged
- * (no function-valued fields).
- *
- * A single shape covers every interaction kind, parameterised by fields rather than split into
- * variants:
- * - confirm    → two options, `maxSelect` 1
- * - single     → options, `maxSelect` 1
- * - multi      → options, `maxSelect` > 1
- * - free text  → no options, `allowFreeText` true
- * - secret     → free text with `masked` true
- */
-/** One predefined option the user can choose. */
-interface IActionOption {
-  value: string;
-  label: string;
-  description?: string;
+interface IToolWaitRequest extends IToolActionIdentity, IToolContinuationPrompt {
+  requestId: string;
 }
-/** Pre-selected option values and/or prefilled free text for an action request. */
-interface IActionDefault {
-  values?: readonly string[];
-  text?: string;
+interface IToolWaitResponse {
+  requestId: string;
+  responseId: string;
+  response: TToolParameters;
 }
-/** One request for the user to answer. See the module doc for how the fields encode each kind. */
-interface IActionRequest {
-  /** Correlation key; the ask port resolves a given id exactly once (idempotent, first-answer wins). */
-  id: string;
-  title: string;
-  description?: string;
-  /** Predefined options. Empty/omitted ⇒ pure free-text entry. */
-  options?: readonly IActionOption[];
-  /** Minimum selections required (default 1). */
-  minSelect?: number;
-  /** Maximum selections allowed (default 1 ⇒ single; > 1 ⇒ multi). */
-  maxSelect?: number;
-  /** Allow a typed custom answer in addition to / instead of the options. */
-  allowFreeText?: boolean;
-  /** Free-text entry is masked (secret entry such as an API key); the renderer hides input. */
-  masked?: boolean;
-  /** Allow submitting empty free text. */
-  allowEmpty?: boolean;
-  /** Placeholder shown in the free-text field. */
-  placeholder?: string;
-  /** Maximum options shown before scrolling (renderer hint). */
-  maxVisible?: number;
-  /** Pre-selected option values and/or prefilled free text. */
-  default?: IActionDefault;
+interface IToolWaitState {
+  request: IToolWaitRequest;
+  response?: IToolWaitResponse;
 }
-/**
- * The user's answer to an {@link IActionRequest}. `answer` carries the selected option values and/or
- * the typed text; `cancelled` means the user dismissed the request, or no interactive renderer was
- * available to answer it.
- */
-type TActionResponse = {
-  type: 'answer';
-  values: readonly string[];
-  text?: string;
-} | {
-  type: 'cancelled';
-};
-/**
- * The injected "ask the user" port — a single seam reachable by every interaction source (command
- * execution now; tool execution for model-issued questions later) and rendered per-environment by each
- * transport. The concurrency model (broadcast to attached interactive channels, first answer wins,
- * later answers for an already-resolved `id` ignored) is owned by the port implementation, not the
- * contract.
- */
-interface IUserInteraction {
-  ask(request: IActionRequest): Promise<TActionResponse>;
+/** Available before effect admission. The runtime owns interpretation and authorization. */
+interface IToolContinuation {
+  readonly action: IToolActionIdentity;
+  readonly waits: readonly IToolWaitState[];
+  /** Return a saved response or persist a request and suspend this execution. */
+  request(prompt: IToolContinuationPrompt): Promise<TToolParameters>;
 }
 //#endregion
 //#region src/interfaces/messages.d.ts
@@ -552,10 +443,14 @@ declare class RateLimitError extends RobotaError {
  */
 declare class NetworkError extends RobotaError {
   readonly originalError?: Error | undefined;
+  /** `undefined` for a network failure with no provider context (e.g. a generic timeout). */
+  readonly provider?: string | undefined;
   readonly code = "NETWORK_ERROR";
   readonly category: "system";
   readonly recoverable = true;
-  constructor(message: string, originalError?: Error | undefined, context?: TErrorContextData);
+  constructor(message: string, originalError?: Error | undefined, context?: TErrorContextData,
+  /** `undefined` for a network failure with no provider context (e.g. a generic timeout). */
+  provider?: string | undefined);
 }
 /**
  * Tool execution errors
@@ -596,11 +491,24 @@ declare class SameToolInputLoopError extends RobotaError {
  * Model not available errors
  */
 declare class ModelNotAvailableError extends RobotaError {
+  /** `undefined` when the failure names no model — a provider adapter classifying a raw HTTP
+   *  response by status alone does not always know which model the vendor meant. */
+  readonly model: string | undefined;
+  readonly provider: string;
   readonly availableModels?: string[] | undefined;
   readonly code = "MODEL_NOT_AVAILABLE";
   readonly category: "user";
   readonly recoverable = false;
-  constructor(model: string, provider: string, availableModels?: string[] | undefined, context?: TErrorContextData);
+  constructor(
+  /** `undefined` when the failure names no model — a provider adapter classifying a raw HTTP
+   *  response by status alone does not always know which model the vendor meant. */
+  model: string | undefined, provider: string, availableModels?: string[] | undefined,
+  /**
+   * `context.originalMessage`, when given, is the vendor's own text (already scrubbed of any
+   * credential by the caller) — folded into `message` so a "Details" disclosure built from
+   * `message` alone still shows the real cause instead of just this class's fixed sentence.
+   */
+  context?: TErrorContextData);
 }
 /**
  * Circuit breaker open error
@@ -641,6 +549,25 @@ declare class CacheIntegrityError extends RobotaError {
 }
 //#endregion
 //#region src/utils/provider-failure.d.ts
+/**
+ * Strip anything that reads like a credential out of vendor text before it is kept on a typed error.
+ * A vendor's error body is not supposed to echo request headers, but a misconfigured self-hosted
+ * gateway can bounce the raw request back (an `Authorization` header, a `Bearer` token, an `api_key=`
+ * query parameter, or the whole request re-serialized as JSON) — this runs once, ahead of every
+ * classification below, so nothing built from `message` (the wire frame's `message`, a GUI "Details"
+ * disclosure) can leak one.
+ *
+ * Each pattern gets its own fixed replacement, bounded to the credential token — never a shared
+ * callback keyed on "does this match have a capture group", which for a pattern with none receives
+ * the match's numeric offset instead of `undefined` and silently prints that number.
+ *
+ * The key-name and value quotes are each optional and captured (`(")?`) rather than matched and
+ * dropped: JSON re-serializes a header as `"Authorization": "Bearer sk-..."`, and the closing quote
+ * right after the key name breaks a match that only expects `\s*[:=]` next — capturing it lets the
+ * replacement echo it back (`Authorization$1: $2[REDACTED]`) so quoted and unquoted text both read
+ * naturally, and `SECRET_VALUE` excluding `"` leaves a closing value quote alone to survive untouched.
+ */
+declare function scrubSecrets(text: string): string;
 /** Why a provider call failed, as far as switching models is concerned. */
 type TProviderFailureReason = 'overloaded' | 'service-unavailable' | 'server-error' | 'model-unavailable' | 'authentication' | 'billing' | 'rate-limit' | 'invalid-request' | 'network' | 'aborted' | 'unknown';
 interface IProviderFailureClassification {
@@ -660,9 +587,15 @@ declare function readProviderFailureDetails(error: unknown): IProviderFailureDet
 /**
  * Turn whatever an adapter caught into a typed provider failure.
  *
- * Aborts and errors already in the taxonomy pass through unchanged, a rate limit becomes a
- * `RateLimitError`, and anything else becomes a `ProviderError` carrying the status and type the
- * vendor reported, with the original kept as `originalError`.
+ * Aborts and errors already in the taxonomy pass through unchanged. Everything else is classified by
+ * the same status/type rules `classifyLayer` uses to decide switchability — a rate limit, an
+ * authentication failure, a model the vendor does not serve, and a transport failure each become
+ * their own typed error (so `AuthenticationError`/`ModelNotAvailableError`/`NetworkError` are actually
+ * thrown, not just recognized after the fact); anything left over becomes a `ProviderError` carrying
+ * the status and type the vendor reported, with the original kept as `originalError`. Every branch
+ * keeps the vendor's own (scrubbed) message and status/type — as the text baked into `message` for
+ * the types that already carry a free-form one, and as `context` alongside it — so a "Details"
+ * disclosure built from `message` downstream never has less to say than the vendor did.
  */
 declare function toProviderError(error: unknown, provider: string, operation: string): Error;
 /**
@@ -1271,227 +1204,306 @@ type TProviderOptionValueBase = string | number | boolean | undefined | null | T
   [key: string]: TProviderOptionValueBase;
 };
 //#endregion
-//#region src/interfaces/response-format.d.ts
+//#region src/event-service/interfaces.d.ts
 /**
- * Response format configuration
+ * @fileoverview Event service interface definitions.
+ *
+ * These interfaces are the single source of truth for event-related contracts
+ * within @robota-sdk/agent-core.
  */
-interface IResponseFormatConfig {
-  type?: 'text' | 'json_object' | 'json_schema';
-  /** JSON schema payload; required when `type` is `'json_schema'` (CORE-015). */
-  schema?: Record<string, TConfigValue>;
-  /** Schema name forwarded to provider native structured-output surfaces. */
-  name?: string;
-}
 /**
- * Safety setting configuration
+ * Primitive value types for event payloads.
  */
-interface ISafetySetting {
-  category: string;
-  threshold: string;
-  [key: string]: TConfigValue;
-}
-//#endregion
-//#region src/schema/zod-schema-types.d.ts
-interface IZodParseResult {
-  success: boolean;
-  data?: unknown;
-  error?: unknown;
-}
-interface IZodSchemaDef {
-  typeName?: string;
-  innerType?: IZodSchema;
-  valueType?: IZodSchema;
-  checks?: Array<{
-    kind: string;
-    value?: TUniversalValue;
-  }>;
-  shape?: () => Record<string, IZodSchema>;
-  type?: IZodSchema;
-  /**
-   * `ZodEnum` holds an ARRAY here; `ZodNativeEnum` holds the enum OBJECT itself (CORE-041). One Zod
-   * field name, two shapes — the converter narrows before reading it.
-   */
-  values?: TUniversalValue[] | Record<string, TUniversalValue>;
-  description?: string;
-  unknownKeys?: 'passthrough' | 'strip' | 'strict';
-  /** `ZodEffects` (`.refine()` / `.transform()`) holds the schema it wraps here. */
-  schema?: IZodSchema;
-  /** `ZodUnion` / `ZodDiscriminatedUnion` members. */
-  options?: IZodSchema[];
-  /** `ZodLiteral` value. */
-  value?: TUniversalValue;
-}
-interface IZodSchema {
-  parse(value: unknown): unknown;
-  safeParse(value: unknown): IZodParseResult;
-  _def?: IZodSchemaDef;
-}
+type TEventPrimitiveValue = string | number | boolean | null | undefined;
 /**
- * Schema conversion options
+ * Recursive universal value type for event payloads (JSON-like + Date).
  */
-interface ISchemaConversionOptions {
-  includeDescription?: boolean;
-  strictTypes?: boolean;
-  allowAdditionalProperties?: boolean;
-}
-//#endregion
-//#region src/schema/structured-output.d.ts
-/** Explicit raw-JSON-schema form of `IRunOptions.output`. */
-interface IJsonSchemaOutput {
-  /** JSON Schema (object root, universal subset) the response must match. */
-  jsonSchema: IToolSchema['parameters'];
-  /** Optional schema name forwarded to provider native surfaces. */
-  name?: string;
-}
-/** Accepted `IRunOptions.output` values: a Zod schema or an explicit JSON-schema wrapper. */
-type TStructuredOutputSchema = IZodSchema | IJsonSchemaOutput;
-type TStructuredOutputValidation = {
-  success: true;
-  value: unknown;
-} | {
-  success: false;
-  issues: string[];
-};
-/** Internal SSOT representation every `output` value normalizes to. */
-interface IStructuredOutputSpec {
-  name: string;
-  jsonSchema: IToolSchema['parameters'];
-  validate(value: unknown): TStructuredOutputValidation;
+type TEventUniversalValue = TEventPrimitiveValue | Date | TEventUniversalValue[] | IEventObjectValue;
+interface IEventObjectValue {
+  [key: string]: TEventUniversalValue;
 }
-/** Normalize an accepted `output` value into the internal spec. */
-declare function normalizeStructuredOutput(output: TStructuredOutputSchema): IStructuredOutputSpec;
 /**
- * Validate a value against the universal JSON-schema subset (`IParameterSchema`). Covers type,
- * required, enum, items, nested properties, unions and numeric bounds — the full expressible
- * surface of the subset, at every level.
- *
- * CORE-039: this is the ONE complete walk. `parameter-validator` delegates its depth here rather
- * than keeping a second, shallower copy, and the two must therefore agree by construction.
+ * Logger data type for event metadata.
  */
-declare function validateAgainstJsonSchema(schema: IParameterSchema, value: unknown, path: string): string[];
+type TEventLoggerData = Record<string, TEventUniversalValue | Date | Error>;
 /**
- * Parse the model's final text into a JSON value. Tolerates a fenced
- * ```json code block wrapper (providers without native enforcement commonly
- * emit one); the parsed value is still strictly schema-validated afterwards.
+ * A single segment in an explicit ownerPath.
+ *
+ * Path-only rule:
+ * - Relationships must be derived from these explicit segments, not from parsing IDs.
  */
-declare function parseStructuredResponseText(text: string): {
-  success: true;
-  value: unknown;
-} | {
-  success: false;
-  issue: string;
+interface IOwnerPathSegment {
+  type: string;
+  id: string;
+}
+/**
+ * Event context that accompanies an emitted event.
+ * This is the single source of truth for deterministic linking in subscribers.
+ */
+interface IEventContext {
+  ownerType: string;
+  ownerId: string;
+  ownerPath: IOwnerPathSegment[];
+  /** Depth of the current execution in the hierarchy (0 = root) */
+  depth?: number;
+  /** Unique span identifier for distributed tracing correlation */
+  spanId?: string;
+  /** Optional structured metadata for debugging/observability */
+  metadata?: TEventLoggerData;
+}
+/**
+ * Allowed extension values for event payloads.
+ */
+type TEventExtensionValue = TEventUniversalValue | TEventLoggerData | Error | IEventContext | IOwnerPathSegment[];
+/**
+ * Base event payload shape.
+ * Emitters may add additional fields, but MUST keep linkage information explicit.
+ */
+interface IBaseEventData {
+  /** Timestamp when the event was emitted. This is required for deterministic ordering. */
+  timestamp: Date;
+  /** Optional structured metadata */
+  metadata?: TEventLoggerData;
+  /** Extensible fields for event-specific payloads */
+  [key: string]: TEventExtensionValue | undefined;
+}
+/**
+ * Execution-related event payload.
+ */
+interface IExecutionEventData extends IBaseEventData {}
+/**
+ * Tool-related event payload.
+ */
+interface IToolEventData extends IBaseEventData {
+  toolName?: string;
+  parameters?: Record<string, TEventUniversalValue>;
+}
+/**
+ * Agent-related event payload.
+ */
+interface IAgentEventData extends IBaseEventData {
+  agentId?: string;
+}
+type TEventListener = (eventType: string, data: IBaseEventData, context?: IEventContext) => void;
+/**
+ * Minimal EventService contract for emitting events.
+ */
+interface IEventService {
+  emit(eventType: string, data: IBaseEventData, context?: IEventContext): void;
+  subscribe(listener: TEventListener): void;
+  unsubscribe(listener: TEventListener): void;
+}
+/**
+ * Explicit owner binding information used for scoped event emission.
+ */
+interface IEventServiceOwnerBinding {
+  ownerType: string;
+  ownerId: string;
+  ownerPath: IOwnerPathSegment[];
+}
+//#endregion
+//#region src/event-service/event-service.d.ts
+/**
+ * Abstract base for event services.
+ * Concrete implementations decide how events are delivered.
+ */
+declare abstract class AbstractEventService implements IEventService {
+  private listeners;
+  abstract emit(eventType: string, data: IBaseEventData, context?: IEventContext): void;
+  subscribe(listener: TEventListener): void;
+  unsubscribe(listener: TEventListener): void;
+  protected notifyListeners(eventType: string, data: IBaseEventData, context?: IEventContext): void;
+}
+/**
+ * Default no-op event service (production-safe).
+ * When injected, emit() intentionally does nothing.
+ */
+declare class DefaultEventService extends AbstractEventService {
+  emit(_eventType: string, _data: IBaseEventData, _context?: IEventContext): void;
+}
+/**
+ * Singleton default event service instance.
+ */
+declare const DEFAULT_ABSTRACT_EVENT_SERVICE: IEventService;
+/**
+ * Check if a given service is the default no-op implementation.
+ */
+declare function isDefaultEventService(service: IEventService): boolean;
+/**
+ * Compose a full event name from owner prefix and local name.
+ * Local names must not contain dots.
+ */
+declare function composeEventName(ownerType: string, localName: string): string;
+/**
+ * Generate a unique span ID for distributed tracing correlation. Exported so a per-operation timing
+ * source (SELFHOST-004) can mint a span id it puts on BOTH the event payload and the event context.
+ */
+declare function generateSpanId(): string;
+/**
+ * A scoped event service that always emits with an owner binding applied.
+ */
+declare class StructuredEventService extends AbstractEventService {
+  private readonly base;
+  private readonly binding;
+  constructor(base: IEventService, binding: IEventServiceOwnerBinding);
+  emit(eventType: string, data: IBaseEventData, context?: IEventContext): void;
+  subscribe(listener: TEventListener): void;
+  unsubscribe(listener: TEventListener): void;
+}
+/**
+ * Bind an EventService to an explicit owner path.
+ * This is the standard entry point for scoped emission (path-only architecture).
+ */
+declare function bindWithOwnerPath(base: IEventService, binding: IEventServiceOwnerBinding): IEventService;
+/**
+ * Alias for bindWithOwnerPath for historical call sites.
+ * Intentionally forwards to the single authoritative implementation.
+ */
+declare function bindEventServiceOwner(base: IEventService, binding: IEventServiceOwnerBinding): IEventService;
+/**
+ * Observable EventService that notifies subscribed listeners.
+ */
+declare class ObservableEventService extends AbstractEventService {
+  emit(eventType: string, data: IBaseEventData, context?: IEventContext): void;
+}
+//#endregion
+//#region src/event-service/task-events.d.ts
+declare const TASK_EVENTS: {
+  readonly ASSIGNED: "assigned";
+  readonly COMPLETED: "completed";
 };
+declare const TASK_EVENT_PREFIX: "task";
 //#endregion
-//#region src/interfaces/run-options.d.ts
+//#region src/event-service/user-events.d.ts
+declare const USER_EVENTS: {
+  readonly MESSAGE: "message";
+  readonly INPUT: "input";
+};
+declare const USER_EVENT_PREFIX: "user";
+type TUserEvent = (typeof USER_EVENTS)[keyof typeof USER_EVENTS];
+//#endregion
+//#region src/event-service/span-events.d.ts
 /**
- * The per-RUN contract: what one `run()` may override or observe, as distinct from the agent's
- * standing configuration in `IAgentConfig`.
- *
- * Split out of `agent.ts` when PEER-007 added `driverId`. That file sits at a frozen size baseline,
- * and the anti-monolith rule asks for a split rather than one more field on a file already at its
- * limit. The two execution-event types come along because `onExecutionEvent` is their only consumer
- * — leaving them behind would have made this module import back from `agent.ts`.
+ * SELFHOST-004: per-operation span lifecycle event names. Mirrors the `TASK_EVENTS`/`USER_EVENTS`
+ * pattern (a const name set + a prefix). The local name is distinctive (`span_completed`, not a bare
+ * `completed`) so a consumer can identify a span-completion regardless of the emitting owner's prefix.
  */
-type TExecutionEventData = Record<string, unknown>;
-type TExecutionEventCallback = (event: string, data: TExecutionEventData) => void;
+declare const SPAN_EVENTS: {
+  readonly COMPLETED: "span_completed";
+};
+/** Content-free completion of one provider round, separate from legacy tool timing events. */
+declare const PROVIDER_CALL_EVENTS: {
+  readonly COMPLETED: "provider_call_completed";
+};
+/** A provider request moved to another model after the one it was on failed. */
+declare const PROVIDER_FALLBACK_EVENTS: {
+  readonly SWITCHED: "provider_fallback";
+};
+/** The notice a `provider_fallback` event carries, or `undefined` when the payload is malformed. */
+declare function readModelFallbackNotice(data: Readonly<Record<string, unknown>>): IModelFallbackNotice | undefined;
+/** Content-free completion of the body actually awaited by one permitted tool call. */
+declare const TOOL_BODY_EVENTS: {
+  readonly COMPLETED: "tool_body_completed";
+};
+/** Content-free decision reached for one tool call before any body runs. */
+declare const TOOL_PERMISSION_EVENTS: {
+  readonly DECIDED: "tool_permission_decided";
+};
+declare const SPAN_EVENT_PREFIX: "span";
+type TSpanEvent = (typeof SPAN_EVENTS)[keyof typeof SPAN_EVENTS];
 /**
- * Agent run options - type-safe interface for all agent execution options
+ * SELFHOST-004: span-completion event payload — JOINS the span id with its measured duration and the
+ * operation name (raw scalars ONLY; references no transport type). Emitted by the per-operation timing
+ * source (e.g. `FunctionTool`) so a consuming layer (`agent-framework`) can build a record span entry
+ * WITHOUT `agent-core` depending on `agent-interface-transport` (no cycle). The payload `spanId` is the
+ * AUTHORITATIVE id a consumer reads; owner/turn correlation is applied by the event service's binding
+ * (`ownerPath` on the emitted `IEventContext`). Note the context's own auto-minted `spanId` is a
+ * separate scope tag and need not equal this payload id — always read the payload id for the span.
  */
-interface IRunOptions {
-  /** Run-scoped temperature override — wins over `defaultModel.temperature` (CORE-016). */
-  temperature?: number;
-  /** Run-scoped max output tokens override — wins over `defaultModel.maxTokens` (CORE-016). */
-  maxTokens?: number;
-  /**
-   * Run-scoped tool-invocation directive — wins over `defaultModel.toolChoice` (CORE-017).
-   * `'auto'` (model decides), `'none'` (suppress tool calls), `'required'` (must call some
-   * tool), or `{ tool: name }` (must call the named tool; the name is validated against the
-   * run's tool list and a miss throws). Forcing applies to the run's first model call only;
-   * rounds after tool results revert to `'auto'` (see `TToolChoice`).
-   */
-  toolChoice?: TToolChoice;
-  /**
-   * Leave a provider's own hosted tools (a vendor-run web search) out of this run's requests. They
-   * run at the vendor and never pass the permission gate, so a run whose tools a policy restricts
-   * must not reach them.
-   */
-  withholdHostedTools?: boolean;
-  sessionId?: string;
-  userId?: string;
-  /**
-   * PEER-007 (issue #1915): who this run is attributed to, for display. Per-run because it changes
-   * per turn — one session serves the operator and any peer addressing it. Never authorization.
-   */
-  driverId?: string;
-  /**
-   * Where this run's turn came from (a peer's message, an external event, an agent wake-up), stored
-   * beside `driverId` on the user message so a transcript carried elsewhere still says it. Display
-   * only, like `driverId`; absent for the operator's own turn.
-   */
-  turnSource?: string;
-  metadata?: TMetadata;
-  /**
-   * Run-scoped EPHEMERAL system context (SELFHOST-008 P3). A transient system-role block included in THIS
-   * run's provider request(s) only — it is **never written to the conversation store** and never persisted,
-   * so it does not bloat history or force a static-system-prompt rebuild. Content-free neutral channel: the
-   * caller decides what to put here (e.g. per-turn recalled memory). Absent ⇒ no change.
-   */
-  ephemeralSystemContext?: string;
-  /**
-   * Host-owned trace context for this run's provider calls. Each invoked call — forced summary
-   * included, cache hits excluded — gets a `traceparent` whose parent is that call's own span, and
-   * only an adapter whose origin is listed sends it. Never recorded in execution events.
-   */
-  traceContext?: IRunTraceContext;
-  /**
-   * AbortSignal for cancelling execution. Aborting an in-flight run does not throw: `run()` resolves
-   * (and `runStream()` returns) the last assistant text the turn committed before the abort, possibly
-   * `''`; a reply cut off mid-stream is kept in history with `state: 'interrupted'`. Read
-   * `signal.aborted` to tell an interrupted run from a completed one.
-   */
-  signal?: AbortSignal;
-  /** Join an aborted/timed-out provider call before completing; an uncooperative call may remain pending. */
-  awaitProviderSettlement?: boolean;
-  /** Per-run streaming text callback. Prefer this over mutating provider callback state. */
-  onTextDelta?: TTextDeltaCallback;
-  /** Per-run replay event callback for provider/tool execution boundaries. */
-  onExecutionEvent?: TExecutionEventCallback;
-  /**
-   * Maximum execution rounds for this run. A **round** is one provider (model) call plus the
-   * execution of every tool call that reply requested; a reply with no tool calls ends the loop,
-   * so a plain Q&A turn is exactly 1 round. This caps model/tool cycles within ONE `run()` — it is
-   * not a tool-count limit and not a multi-turn conversation limit. When the cap is hit the run
-   * stops after the current round. Use 0 for no core round cap. Defaults to
-   * `IAgentConfig.maxExecutionRounds`.
-   */
-  maxExecutionRounds?: number;
-  /** Max times the same tool may be called with identical input before aborting. Unset = no limit. */
-  maxSameToolInputs?: number;
-  /**
-   * Treat a turn that ends in tool calls (no trailing text) as a valid completion instead of
-   * forcing one extra provider call to generate a summary (CORE-011). For decision-agent patterns
-   * (router/orchestrator/classifier) the tool call IS the answer — this removes the one-call tax.
-   * The summary call is the one made when the round cap ends the loop on a tool round; before the cap
-   * the model is called again after tool results as usual, so a decision agent sets
-   * `maxExecutionRounds` too (e.g. `1`). The run resolves with the turn's text, or `''` when it
-   * produced none; consumers read the outcome from the tool results.
-   */
-  allowToolOnlyCompletion?: boolean;
-  /**
-   * Schema-enforced structured output (CORE-015). Accepts a Zod schema or an explicit
-   * `{ jsonSchema }` wrapper. `run` then resolves to the validated, typed object instead of a
-   * string: the schema is forwarded to the provider's native structured-output surface where one
-   * exists, and the final response is always parsed and validated core-side; a violation triggers
-   * a bounded retry with the validation issues fed back as the next turn's input. Every attempt is
-   * a real conversation turn (history stays append-only). Exhausted retries throw
-   * `StructuredOutputError`.
-   */
-  output?: TStructuredOutputSchema;
-  /**
-   * Retry budget for structured output validation failures — the number of additional attempts
-   * after the first (default 2). Only meaningful with `output` set.
-   */
-  outputRetries?: number;
+interface ISpanCompletionEventData extends IBaseEventData {
+  /** The span id (equals the emitted event's context `spanId`). */
+  spanId: string;
+  /** Measured wall-clock duration of the operation, in milliseconds. */
+  durationMs: number;
+  /** The operation name (e.g. the tool name). */
+  op: string;
+}
+//#endregion
+//#region src/interfaces/interaction.d.ts
+/**
+ * UI-agnostic "ask the user" contract (CMD-004).
+ *
+ * The SSOT for the interaction action lives in agent-core so every interaction *source* can reach it:
+ * command execution (`ICommandHostContext`, agent-framework) AND tool execution
+ * (`IToolExecutionContext`, agent-core, for model-issued questions — CMD-005). These are pure types
+ * with no runtime dependency, so the contract crosses a serialization/transport boundary unchanged
+ * (no function-valued fields).
+ *
+ * A single shape covers every interaction kind, parameterised by fields rather than split into
+ * variants:
+ * - confirm    → two options, `maxSelect` 1
+ * - single     → options, `maxSelect` 1
+ * - multi      → options, `maxSelect` > 1
+ * - free text  → no options, `allowFreeText` true
+ * - secret     → free text with `masked` true
+ */
+/** One predefined option the user can choose. */
+interface IActionOption {
+  value: string;
+  label: string;
+  description?: string;
+}
+/** Pre-selected option values and/or prefilled free text for an action request. */
+interface IActionDefault {
+  values?: readonly string[];
+  text?: string;
+}
+/** One request for the user to answer. See the module doc for how the fields encode each kind. */
+interface IActionRequest {
+  /** Correlation key; the ask port resolves a given id exactly once (idempotent, first-answer wins). */
+  id: string;
+  title: string;
+  description?: string;
+  /** Predefined options. Empty/omitted ⇒ pure free-text entry. */
+  options?: readonly IActionOption[];
+  /** Minimum selections required (default 1). */
+  minSelect?: number;
+  /** Maximum selections allowed (default 1 ⇒ single; > 1 ⇒ multi). */
+  maxSelect?: number;
+  /** Allow a typed custom answer in addition to / instead of the options. */
+  allowFreeText?: boolean;
+  /** Free-text entry is masked (secret entry such as an API key); the renderer hides input. */
+  masked?: boolean;
+  /** Allow submitting empty free text. */
+  allowEmpty?: boolean;
+  /** Placeholder shown in the free-text field. */
+  placeholder?: string;
+  /** Maximum options shown before scrolling (renderer hint). */
+  maxVisible?: number;
+  /** Pre-selected option values and/or prefilled free text. */
+  default?: IActionDefault;
+}
+/**
+ * The user's answer to an {@link IActionRequest}. `answer` carries the selected option values and/or
+ * the typed text; `cancelled` means the user dismissed the request, or no interactive renderer was
+ * available to answer it.
+ */
+type TActionResponse = {
+  type: 'answer';
+  values: readonly string[];
+  text?: string;
+} | {
+  type: 'cancelled';
+};
+/**
+ * The injected "ask the user" port — a single seam reachable by every interaction source (command
+ * execution now; tool execution for model-issued questions later) and rendered per-environment by each
+ * transport. The concurrency model (broadcast to attached interactive channels, first answer wins,
+ * later answers for an already-resolved `id` ignored) is owned by the port implementation, not the
+ * contract.
+ */
+interface IUserInteraction {
+  ask(request: IActionRequest): Promise<TActionResponse>;
 }
 //#endregion
 //#region src/interfaces/tool-search.d.ts
@@ -1529,654 +1541,884 @@ interface IDeferredToolCatalog {
   loadDeferredTools(names: readonly string[]): IToolSchema[];
 }
 //#endregion
-//#region src/plugins/event-emitter/types.d.ts
-declare const EXECUTION_EVENT_NAMES: {
-  readonly START: "execution.start";
-  readonly COMPLETE: "execution.complete";
-  readonly ERROR: "execution.error";
-};
-declare const TOOL_EVENT_NAMES: {
-  readonly CALL_START: "tool.call_start";
-  readonly CALL_COMPLETE: "tool.call_complete";
-  readonly CALL_ERROR: "tool.call_error";
-};
-declare const AGENT_EVENT_NAMES: {
-  readonly EXECUTION_START: "agent.execution_start";
-  readonly EXECUTION_COMPLETE: "agent.execution_complete";
-  readonly EXECUTION_ERROR: "agent.execution_error";
-  readonly CREATED: "agent.created";
-};
-type TExecutionEventName = (typeof EXECUTION_EVENT_NAMES)[keyof typeof EXECUTION_EVENT_NAMES];
-type TToolEventName = (typeof TOOL_EVENT_NAMES)[keyof typeof TOOL_EVENT_NAMES];
-type TAgentEventName = (typeof AGENT_EVENT_NAMES)[keyof typeof AGENT_EVENT_NAMES];
-/**
- * Event types that can be emitted.
- *
- * IMPORTANT:
- * - Do not use string literals for event names outside this module.
- * - Import and use EVENT_EMITTER_EVENTS instead.
- */
-declare const EVENT_EMITTER_EVENTS: {
-  readonly EXECUTION_START: "execution.start";
-  readonly EXECUTION_COMPLETE: "execution.complete";
-  readonly EXECUTION_ERROR: "execution.error";
-  readonly TOOL_BEFORE_EXECUTE: "tool.beforeExecute";
-  readonly TOOL_AFTER_EXECUTE: "tool.afterExecute";
-  readonly TOOL_SUCCESS: "tool.success";
-  readonly TOOL_ERROR: "tool.call_error";
-  readonly CONVERSATION_START: "conversation.start";
-  readonly CONVERSATION_COMPLETE: "conversation.complete";
-  readonly CONVERSATION_ERROR: "conversation.error";
-  readonly AGENT_EXECUTION_START: "agent.execution_start";
-  readonly AGENT_EXECUTION_COMPLETE: "agent.execution_complete";
-  readonly AGENT_EXECUTION_ERROR: "agent.execution_error";
-  readonly AGENT_CREATED: "agent.created";
-  readonly AGENT_DESTROYED: "agent.destroyed";
-  readonly PLUGIN_LOADED: "plugin.loaded";
-  readonly PLUGIN_UNLOADED: "plugin.unloaded";
-  readonly PLUGIN_ERROR: "plugin.error";
-  readonly ERROR_OCCURRED: "error.occurred";
-  readonly WARNING_OCCURRED: "warning.occurred";
-  readonly MODULE_INITIALIZE_START: "module.initialize.start";
-  readonly MODULE_INITIALIZE_COMPLETE: "module.initialize.complete";
-  readonly MODULE_INITIALIZE_ERROR: "module.initialize.error";
-  readonly MODULE_EXECUTION_START: "module.execution.start";
-  readonly MODULE_EXECUTION_COMPLETE: "module.execution.complete";
-  readonly MODULE_EXECUTION_ERROR: "module.execution.error";
-  readonly MODULE_DISPOSE_START: "module.dispose.start";
-  readonly MODULE_DISPOSE_COMPLETE: "module.dispose.complete";
-  readonly MODULE_DISPOSE_ERROR: "module.dispose.error";
-  readonly MODULE_REGISTERED: "module.registered";
-  readonly MODULE_UNREGISTERED: "module.unregistered";
-  readonly EXECUTION_HIERARCHY: "execution.hierarchy";
-  readonly EXECUTION_REALTIME: "execution.realtime";
-  readonly TOOL_REALTIME: "tool.realtime";
-  readonly CUSTOM: "custom";
-};
-type TEventName = TExecutionEventName | TToolEventName | TAgentEventName | 'tool.beforeExecute' | 'tool.afterExecute' | 'tool.success' | 'conversation.start' | 'conversation.complete' | 'conversation.error' | 'agent.destroyed' | 'plugin.loaded' | 'plugin.unloaded' | 'plugin.error' | 'error.occurred' | 'warning.occurred' | 'module.initialize.start' | 'module.initialize.complete' | 'module.initialize.error' | 'module.execution.start' | 'module.execution.complete' | 'module.execution.error' | 'module.dispose.start' | 'module.dispose.complete' | 'module.dispose.error' | 'module.registered' | 'module.unregistered' | 'execution.hierarchy' | 'execution.realtime' | 'tool.realtime' | 'custom';
-/**
- * Valid event data value types
- */
-type TEventDataValue = string | number | boolean | Date | null | undefined | TEventDataValue[] | {
-  [key: string]: TEventDataValue;
-};
-/**
- * Event data structure
- */
-interface IEventEmitterEventData {
-  type: TEventName;
-  timestamp: Date;
-  executionId?: string;
-  sessionId?: string;
-  userId?: string;
-  data?: Record<string, TEventDataValue>;
-  error?: Error;
-  metadata?: Record<string, TEventDataValue>;
-}
-/**
- * Event listener function
- */
-type TEventEmitterListener = (event: IEventEmitterEventData) => void | Promise<void>;
-/**
- * Console-like interface for the EventEmitterPlugin.
- *
- * Use this interface for typing instead of the concrete EventEmitterPlugin class.
- */
-interface IEventEmitterPlugin {
-  on(eventType: TEventName, listener: TEventEmitterListener, options?: {
-    once?: boolean;
-    filter?: (event: IEventEmitterEventData) => boolean;
-  }): string;
-  once(eventType: TEventName, listener: TEventEmitterListener, filter?: (event: IEventEmitterEventData) => boolean): string;
-  off(eventType: TEventName, handlerIdOrListener: string | TEventEmitterListener): boolean;
-  emit(eventType: TEventName, eventData?: Partial<IEventEmitterEventData>): Promise<void>;
-}
-//#endregion
-//#region src/abstracts/abstract-module-types.d.ts
-/** Module execution context */
-interface IModuleExecutionContext {
-  executionId?: string;
-  sessionId?: string;
-  userId?: string;
-  agentName?: string;
-  metadata?: Record<string, string | number | boolean | Date>;
-  [key: string]: string | number | boolean | Date | Record<string, string | number | boolean | Date> | undefined;
-}
-/** Module execution result */
-interface IModuleExecutionResult {
-  success: boolean;
-  data?: IModuleResultData;
-  error?: Error;
-  duration?: number;
-  metadata?: Record<string, string | number | boolean | Date>;
-}
-/** Module result data */
-interface IModuleResultData {
-  [key: string]: string | number | boolean | Record<string, string | number | boolean> | undefined;
-}
-/** Base module options */
-interface IBaseModuleOptions {
-  enabled?: boolean;
-  config?: Record<string, string | number | boolean>;
-}
-/** Module capabilities */
-interface IModuleCapabilities {
-  capabilities: string[];
-  dependencies?: string[];
-  optionalDependencies?: string[];
-}
-/** Module type descriptor */
-interface IModuleDescriptor {
-  type: string;
-  category: ModuleCategory;
-  layer: ModuleLayer;
-  dependencies?: string[];
-  capabilities?: string[];
-}
-/** Module categories */
-declare enum ModuleCategory {
-  CORE = "core",
-  STORAGE = "storage",
-  PROCESSING = "processing",
-  INTEGRATION = "integration",
-  INTERFACE = "interface",
-  CAPABILITY = "capability"
-}
-/** Module layers */
-declare enum ModuleLayer {
-  INFRASTRUCTURE = "infrastructure",
-  CORE = "core",
-  APPLICATION = "application",
-  DOMAIN = "domain",
-  PRESENTATION = "presentation"
-}
-/** Module data for introspection */
-interface IModuleData {
-  name: string;
-  version: string;
-  type: string;
-  enabled: boolean;
-  initialized: boolean;
-  capabilities: IModuleCapabilities;
-  metadata?: Record<string, string | number | boolean>;
-}
-/** Module statistics */
-interface IModuleStats {
-  enabled: boolean;
-  initialized: boolean;
-  executionCount: number;
-  errorCount: number;
-  lastActivity?: Date;
-  averageExecutionTime?: number;
-  [key: string]: string | number | boolean | Date | undefined;
-}
-/** Type-safe module interface */
-interface IModule<TOptions extends IBaseModuleOptions = IBaseModuleOptions, TStats = IModuleStats> {
-  name: string;
-  version: string;
-  enabled: boolean;
-  initialize(options?: TOptions, eventEmitter?: IEventEmitterPlugin): Promise<void>;
-  dispose?(): Promise<void>;
-  execute?(context: IModuleExecutionContext): Promise<IModuleExecutionResult>;
-  getModuleType(): IModuleDescriptor;
-  getCapabilities(): IModuleCapabilities;
-  getData?(): IModuleData;
-  getStats?(): TStats;
-  isEnabled(): boolean;
-  isInitialized(): boolean;
-}
-//#endregion
-//#region src/event-service/interfaces.d.ts
+//#region src/interfaces/tool.d.ts
+/** Awaited host admission for effective parameters, immediately before a tool body. */
+type TToolEffectAdmission<TParameters = TToolParameters> = (parameters: TParameters) => Promise<void>;
+type TToolContextExtensionValue = TUniversalValue | Date | Error | TLoggerData | TContextData | TToolParameters | TToolMetadata;
 /**
- * @fileoverview Event service interface definitions.
+ * Tool metadata structure - specific type definition
+ */
+type TToolMetadata = Record<string, string | number | boolean | string[] | number[] | boolean[] | TToolParameters>;
+/**
+ * Tool execution data - domain payload for tool results.
  *
- * These interfaces are the single source of truth for event-related contracts
- * within @robota-sdk/agent-core.
+ * IMPORTANT:
+ * - This must support structured tool outputs without resorting to `any`.
+ * - Prefer `ToolResultData` (derived from the canonical `UniversalValue` axis).
  */
 /**
- * Primitive value types for event payloads.
+ * Tool execution result - extended for ToolExecutionData compatibility
  */
-type TEventPrimitiveValue = string | number | boolean | null | undefined;
+interface IToolResult {
+  success: boolean;
+  data?: TUniversalValue;
+  error?: string;
+  metadata?: TToolMetadata;
+  [key: string]: TToolContextExtensionValue | undefined;
+}
 /**
- * Recursive universal value type for event payloads (JSON-like + Date).
+ * Enhanced tool execution result with additional metadata
  */
-type TEventUniversalValue = TEventPrimitiveValue | Date | TEventUniversalValue[] | IEventObjectValue;
-interface IEventObjectValue {
-  [key: string]: TEventUniversalValue;
+interface IToolExecutionResult {
+  /** Whether execution was successful */
+  success: boolean;
+  /** Tool name that was executed */
+  toolName?: string;
+  /** Execution result or data */
+  result?: TUniversalValue;
+  /** Error message if execution failed */
+  error?: string;
+  /** Execution duration in milliseconds */
+  duration?: number;
+  /** Unique execution ID */
+  executionId?: string;
+  /** Additional metadata */
+  metadata?: TToolMetadata;
 }
 /**
- * Logger data type for event metadata.
+ * Tool execution context - type-safe context for tool execution
+ * Enhanced with hierarchical execution tracking support
  */
-type TEventLoggerData = Record<string, TEventUniversalValue | Date | Error>;
+interface IToolExecutionContext {
+  toolName: string;
+  parameters: TToolParameters;
+  /** Runtime-owned barrier, consumed after permission and before entering the tool. */
+  beforeToolEffect?: TToolEffectAdmission;
+  /** Journaled pre-effect request/response port for admission-aware runtime wrappers. */
+  continuation?: IToolContinuation;
+  /**
+   * Run-scoped cancellation signal (CORE-018). Long-running tools MUST honor it: terminate
+   * the underlying work (kill the child process, abort the network request) and return an
+   * interrupted/failed result. Completing silently after an abort is a contract violation.
+   */
+  signal?: AbortSignal;
+  /** Direct remote calls deny decisions that would require human interaction. */
+  permissionInteraction?: 'interactive' | 'deny';
+  executionId?: string;
+  userId?: string;
+  sessionId?: string;
+  metadata?: TToolMetadata;
+  /** Parent execution ID for hierarchical tool execution tracking */
+  parentExecutionId?: string;
+  /** Root execution ID (Team/Agent level) for complete execution tree tracking */
+  rootExecutionId?: string;
+  /** Execution depth level (0: Team, 1: Agent, 2: Tool, etc.) */
+  executionLevel?: number;
+  /** Execution path array showing the complete execution hierarchy */
+  executionPath?: string[];
+  /** Real-time execution data for accurate tracking (no simulation) */
+  realTimeData?: {
+    /** Actual execution start time */
+    startTime: Date;
+    /** Actual input parameters passed to the tool */
+    actualParameters: TToolParameters;
+    /** Tool-provided estimated duration (optional) */
+    estimatedDuration?: number;
+  };
+  /**
+   * Additional tool execution context extensions.
+   *
+   * IMPORTANT:
+   * - Avoid ad-hoc top-level fields to keep the contract stable.
+   * - Use this map for forward-compatible extra data with constrained value types.
+   */
+  extensions?: Record<string, TToolContextExtensionValue>;
+  /** Owner context propagated from EventService */
+  ownerType?: string;
+  ownerId?: string;
+  ownerPath?: IOwnerPathSegment[];
+  sourceId?: string;
+  /**
+   * Tool-call scoped EventService instance.
+   * Caller (ExecutionService/ToolExecutionService) is responsible for providing
+   * an ownerPath-bound EventService for this tool call.
+   */
+  eventService?: IEventService;
+  /**
+   * Unbound base EventService instance.
+   *
+   * Required when a tool needs to create another owner-bound EventService
+   * for a different owner (e.g., creating an agent from a tool call).
+   *
+   * NOTE: Do not wrap an already owner-bound EventService to bind a different owner.
+   * Owner-bound instances must not be layered across different owners.
+   */
+  baseEventService?: IEventService;
+  /**
+   * The service this call's caller would give the tool with `setEventService`, carried with the
+   * call instead. One tool instance can serve several agents, and the service set on it is
+   * whichever agent set one last; a tool that emits events of its own (the `FunctionTool` span)
+   * emits them here when present, so they reach the agent that made the call. The no-op default
+   * service means that caller wants none.
+   */
+  instanceEventService?: IEventService;
+  /**
+   * Injected "ask the user" port (CMD-004). Present when an interactive renderer is attached, letting
+   * a tool solicit a structured answer from the user (the model-issued question seam consumed by
+   * CMD-005). Absent in non-interactive contexts; a tool that asks must treat absence as "no human
+   * available" (never a silent guess).
+   */
+  ask?: IUserInteraction['ask'];
+  /**
+   * CLI-1990: the deferred-tool catalog the runtime injects (`ToolExecutionService`), so a search
+   * tool can list what is withheld and load it for the rest of the session. Present on every tool
+   * call the execution loop issues; a tool other than the search tool has no reason to read it.
+   */
+  deferredTools?: IDeferredToolCatalog;
+  /**
+   * The ID core mints for this one tool body, unique even when a vendor reuses its tool call ID.
+   * The body's exported span is derived from it, so it is also what a propagated parent names.
+   */
+  toolBodyId?: string;
+  /**
+   * Present only when the run carries trusted trace context: the `traceparent` naming this body's
+   * span and the exact origins it may be sent to. A tool that makes outbound requests sends it only
+   * to a listed origin.
+   */
+  outboundTraceContext?: IOutboundTraceContext;
+  /**
+   * Present only when the host lets shell children inherit the trace: the environment naming this
+   * body's span. Only the foreground shell tool applies it, to its own child.
+   */
+  shellTraceEnv?: ISubprocessTraceEnv;
+  /**
+   * Present only when the host lets command hooks inherit the trace: the environment naming the
+   * prompt root, for the hooks fired around this body. Separate from {@link shellTraceEnv}, whose
+   * span is the body's own.
+   */
+  hookTraceEnv?: ISubprocessTraceEnv;
+}
 /**
- * A single segment in an explicit ownerPath.
- *
- * Path-only rule:
- * - Relationships must be derived from these explicit segments, not from parsing IDs.
+ * Parameter validation result
  */
-interface IOwnerPathSegment {
-  type: string;
-  id: string;
+interface IParameterValidationResult {
+  /** Whether parameters are valid */
+  isValid: boolean;
+  /** Validation error messages */
+  errors: string[];
 }
 /**
- * Event context that accompanies an emitted event.
- * This is the single source of truth for deterministic linking in subscribers.
+ * Generic tool executor function
  */
-interface IEventContext {
-  ownerType: string;
-  ownerId: string;
-  ownerPath: IOwnerPathSegment[];
-  /** Depth of the current execution in the hierarchy (0 = root) */
-  depth?: number;
-  /** Unique span identifier for distributed tracing correlation */
-  spanId?: string;
-  /** Optional structured metadata for debugging/observability */
-  metadata?: TEventLoggerData;
+type TToolExecutor<TParams = TToolParameters, TResult = TUniversalValue> = (parameters: TParams, context?: IToolExecutionContext) => Promise<TResult>;
+/**
+ * Base tool interface
+ */
+interface ITool {
+  /** Tool schema */
+  schema: IToolSchema;
+  /**
+   * Execute the tool with given parameters
+   */
+  execute(parameters: TToolParameters, context?: IToolExecutionContext): Promise<IToolResult>;
+  /**
+   * Validate tool parameters
+   */
+  validate(parameters: TToolParameters): boolean;
+  /**
+   * Validate tool parameters with detailed result
+   */
+  validateParameters(parameters: TToolParameters): IParameterValidationResult;
+  /**
+   * Get tool description
+   */
+  getDescription(): string;
 }
 /**
- * Allowed extension values for event payloads.
+ * Function tool implementation
  */
-type TEventExtensionValue = TEventUniversalValue | TEventLoggerData | Error | IEventContext | IOwnerPathSegment[];
+interface IFunctionTool extends ITool {
+  /** Function to execute */
+  fn: TToolExecutor;
+}
 /**
- * Base event payload shape.
- * Emitters may add additional fields, but MUST keep linkage information explicit.
+ * Tool registry interface
  */
-interface IBaseEventData {
-  /** Timestamp when the event was emitted. This is required for deterministic ordering. */
-  timestamp: Date;
-  /** Optional structured metadata */
-  metadata?: TEventLoggerData;
-  /** Extensible fields for event-specific payloads */
-  [key: string]: TEventExtensionValue | undefined;
+interface IToolRegistry {
+  /**
+   * Register a tool
+   */
+  register(tool: ITool): void;
+  /**
+   * Unregister a tool
+   */
+  unregister(name: string): void;
+  /**
+   * Get tool by name
+   */
+  get(name: string): ITool | undefined;
+  /**
+   * Get all registered tools
+   */
+  getAll(): ITool[];
+  /**
+   * Get tool schemas
+   */
+  getSchemas(): IToolSchema[];
+  /**
+   * Check if tool exists
+   */
+  has(name: string): boolean;
+  /**
+   * Clear all tools
+   */
+  clear(): void;
+}
+//#endregion
+//#region src/interfaces/execution-journal.d.ts
+/** Data-only provider options; callbacks, signals, tracing and adapter credentials are excluded. */
+type TJournalModelOptions = Pick<IChatOptions, 'model' | 'tools' | 'maxTokens' | 'temperature' | 'effort' | 'toolChoice' | 'nativeWebTools' | 'responseFormat'>;
+interface IJournalIdentity {
+  recordId: string;
+  executionId: string;
+}
+interface IJournalModelIdentity {
+  callId: string;
+  providerId: string;
+  modelId: string;
+}
+interface IJournalActionIdentity {
+  actionId: string;
+  parentCallId: string;
+  toolCallId: string;
+  toolName: string;
+}
+interface IExecutionContinuationState {
+  version: 1;
+  kind: 'round' | 'summary';
+  startedAt: string;
+  turnMessageId: string;
+  model: Pick<IChatOptions, 'maxTokens' | 'temperature' | 'effort' | 'toolChoice'> & {
+    provider: string;
+    model: string;
+    topP?: number;
+  };
+  timeout?: number;
+  toolSearch?: TToolSearchSetting;
+  structuredOutput: boolean;
+  /** Versioned data contract; runtime callbacks and signals are supplied by the recovering host. */
+  options: Pick<IChatOptions, 'maxTokens' | 'temperature' | 'toolChoice'> & {
+    maxExecutionRounds: number;
+    maxSameToolInputs?: number;
+    allowToolOnlyCompletion: boolean;
+    withholdHostedTools: boolean;
+    ephemeralSystemContext?: string;
+    sessionId?: string;
+    userId?: string;
+    metadata?: TMetadata;
+  };
+  toolsExecuted: string[];
+  consecutiveUnknownToolFailureRounds: number;
+  forcedSummaryInstruction?: string;
+  loadedDeferredTools?: string[];
+}
+/** Canonical private history, separate from transformed/ephemeral provider input. */
+interface IExecutionRoundCheckpoint {
+  version: 1;
+  effectAdmission: 'required';
+  messages: TUniversalMessage[];
+  round: number;
+  contextLimit: number;
+  cumulativeInputTokens: number;
+  sameToolInputCounts: Array<[string, number]>;
+  maxSameToolInputs?: number;
+  continuation?: IExecutionContinuationState;
+  /** Versioned state belonging to a runtime wrapper, never inferred from transcript text. */
+  owner?: {
+    kind: string;
+    version: number;
+    state: TToolParameters;
+  };
 }
-/**
- * Execution-related event payload.
- */
-interface IExecutionEventData extends IBaseEventData {}
-/**
- * Tool-related event payload.
- */
-interface IToolEventData extends IBaseEventData {
-  toolName?: string;
-  parameters?: Record<string, TEventUniversalValue>;
+type TExecutionJournalRecord = IJournalIdentity & ((IJournalModelIdentity & {
+  kind: 'model-request';
+  messages: TUniversalMessage[];
+  options: TJournalModelOptions;
+  checkpoint?: IExecutionRoundCheckpoint;
+}) | (IJournalModelIdentity & {
+  kind: 'model-response';
+  response: TUniversalMessage;
+}) | (IJournalModelIdentity & {
+  kind: 'model-cache-hit';
+  response: TUniversalMessage;
+  checkpoint?: IExecutionRoundCheckpoint;
+}) | (IJournalModelIdentity & {
+  kind: 'model-failure';
+  error: {
+    name: string;
+    message: string;
+  };
+}) | (IJournalActionIdentity & {
+  kind: 'tool-intent';
+  parameters: TToolParameters;
+}) | (IJournalActionIdentity & {
+  kind: 'tool-dispatch';
+}) | (IJournalActionIdentity & {
+  kind: 'tool-effect-start';
+  parameters: TToolParameters;
+}) | (IJournalActionIdentity & {
+  kind: 'tool-wait';
+  request: IToolContinuationPrompt & {
+    requestId: string;
+  };
+}) | (IJournalActionIdentity & {
+  kind: 'tool-response';
+  response: IToolWaitResponse;
+}) | (IJournalActionIdentity & {
+  kind: 'tool-result';
+  result: IToolExecutionResult;
+  loadedDeferredTools?: string[];
+}));
+/**
+ * Awaited, fail-closed execution boundary. Rejection stops this run before further dispatch.
+ * The host owns storage, serialization of message dates, idempotency and recovery decisions.
+ * Model records describe an adapter invocation, not its opaque retries or network requests.
+ * Only a supported mandatory-effect checkpoint can prove an unstarted action; an intent alone cannot.
+ */
+interface IExecutionJournal {
+  append(record: TExecutionJournalRecord): Promise<void>;
+}
+/**
+ * Reads the complete, ordered, current prefix from the same authority used for append.
+ * The host must hold exclusive fenced ownership and drain the old runtime before recovery.
+ * Appending an identical recordId is idempotent; conflicting content must be rejected.
+ */
+interface IRecoverableExecutionJournal extends IExecutionJournal {
+  read(executionId: string): Promise<readonly TExecutionJournalRecord[]>;
+}
+interface IResumeToolCallsOptions {
+  executionId: string;
+  callId: string;
+  journal: IRecoverableExecutionJournal;
+  /** Exact replies to saved requests; receipts are persisted before further execution. */
+  toolResponses?: readonly IToolWaitResponse[];
+  signal?: AbortSignal;
+  /** Observe newly committed recovery history using the ordinary history-mutation contract. */
+  onExecutionEvent?: (event: string, data: Record<string, unknown>) => void;
 }
 /**
- * Agent-related event payload.
+ * Continue the latest settled invocation on the original provider/model under exclusive host ownership.
+ * Structured-output validators and unknown effects require reconciliation rather than automatic replay.
+ * Turn-level lifecycle hooks are omitted because their effects have no durable receipts;
+ * hosts requiring those effects must settle them separately. Recovered history remains available.
  */
-interface IAgentEventData extends IBaseEventData {
-  agentId?: string;
+interface IResumeExecutionOptions extends Omit<IResumeToolCallsOptions, 'callId'> {
+  onTextDelta?: IChatOptions['onTextDelta'];
+  traceContext?: IRunTraceContext;
 }
-type TEventListener = (eventType: string, data: IBaseEventData, context?: IEventContext) => void;
-/**
- * Minimal EventService contract for emitting events.
- */
-interface IEventService {
-  emit(eventType: string, data: IBaseEventData, context?: IEventContext): void;
-  subscribe(listener: TEventListener): void;
-  unsubscribe(listener: TEventListener): void;
+interface IResumeToolCallsResult {
+  executionId: string;
+  callId: string;
+  messages: TUniversalMessage[];
 }
-/**
- * Explicit owner binding information used for scoped event emission.
- */
-interface IEventServiceOwnerBinding {
-  ownerType: string;
-  ownerId: string;
-  ownerPath: IOwnerPathSegment[];
+/** Host-owned identity for a journaled provider invocation, including routing changes. */
+interface IModelJournalContext {
+  journal: IExecutionJournal;
+  executionId: string;
+  callId: string;
+  checkpoint?: IExecutionRoundCheckpoint;
+  route(): {
+    providerId: string;
+    modelId: string;
+  };
 }
 //#endregion
-//#region src/event-service/event-service.d.ts
+//#region src/interfaces/cache.d.ts
 /**
- * Abstract base for event services.
- * Concrete implementations decide how events are delivered.
+ * Cache key identifying a unique LLM execution request
  */
-declare abstract class AbstractEventService implements IEventService {
-  private listeners;
-  abstract emit(eventType: string, data: IBaseEventData, context?: IEventContext): void;
-  subscribe(listener: TEventListener): void;
-  unsubscribe(listener: TEventListener): void;
-  protected notifyListeners(eventType: string, data: IBaseEventData, context?: IEventContext): void;
+interface ICacheKey {
+  /** SHA-256 hash of the serialized request */
+  hash: string;
+  /** Model identifier */
+  model: string;
+  /** Provider name */
+  provider: string;
 }
 /**
- * Default no-op event service (production-safe).
- * When injected, emit() intentionally does nothing.
+ * Cached LLM response entry
  */
-declare class DefaultEventService extends AbstractEventService {
-  emit(_eventType: string, _data: IBaseEventData, _context?: IEventContext): void;
+interface ICacheEntry {
+  /** Cache key that produced this entry */
+  key: ICacheKey;
+  /** Cached response content */
+  response: string;
+  /** When the entry was cached */
+  timestamp: number;
+  /** SHA-256 integrity hash of the response */
+  integrityHash: string;
 }
 /**
- * Singleton default event service instance.
- */
-declare const DEFAULT_ABSTRACT_EVENT_SERVICE: IEventService;
-/**
- * Check if a given service is the default no-op implementation.
- */
-declare function isDefaultEventService(service: IEventService): boolean;
-/**
- * Compose a full event name from owner prefix and local name.
- * Local names must not contain dots.
- */
-declare function composeEventName(ownerType: string, localName: string): string;
-/**
- * Generate a unique span ID for distributed tracing correlation. Exported so a per-operation timing
- * source (SELFHOST-004) can mint a span id it puts on BOTH the event payload and the event context.
+ * Cache storage interface for pluggable backends
  */
-declare function generateSpanId(): string;
+interface ICacheStorage {
+  /** Retrieve a cached entry by key hash */
+  get(hash: string): ICacheEntry | undefined;
+  /** Store a cache entry */
+  set(entry: ICacheEntry): void;
+  /** Delete a cached entry by key hash */
+  delete(hash: string): boolean;
+  /** Clear all cached entries */
+  clear(): void;
+  /** Get cache statistics */
+  getStats(): ICacheStats;
+}
 /**
- * A scoped event service that always emits with an owner binding applied.
+ * Cache performance statistics
  */
-declare class StructuredEventService extends AbstractEventService {
-  private readonly base;
-  private readonly binding;
-  constructor(base: IEventService, binding: IEventServiceOwnerBinding);
-  emit(eventType: string, data: IBaseEventData, context?: IEventContext): void;
-  subscribe(listener: TEventListener): void;
-  unsubscribe(listener: TEventListener): void;
+interface ICacheStats {
+  /** Number of cache hits */
+  hits: number;
+  /** Number of cache misses */
+  misses: number;
+  /** Current number of cached entries */
+  entries: number;
+  /** Hit rate (hits / (hits + misses)), 0 if no lookups */
+  hitRate: number;
 }
 /**
- * Bind an EventService to an explicit owner path.
- * This is the standard entry point for scoped emission (path-only architecture).
+ * Configuration options for execution caching
  */
-declare function bindWithOwnerPath(base: IEventService, binding: IEventServiceOwnerBinding): IEventService;
+interface ICacheOptions {
+  /** Whether caching is enabled */
+  enabled: boolean;
+  /** Maximum number of cached entries */
+  maxEntries: number;
+  /** Time-to-live in milliseconds */
+  ttlMs: number;
+}
+//#endregion
+//#region src/interfaces/response-format.d.ts
 /**
- * Alias for bindWithOwnerPath for historical call sites.
- * Intentionally forwards to the single authoritative implementation.
+ * Response format configuration
  */
-declare function bindEventServiceOwner(base: IEventService, binding: IEventServiceOwnerBinding): IEventService;
+interface IResponseFormatConfig {
+  type?: 'text' | 'json_object' | 'json_schema';
+  /** JSON schema payload; required when `type` is `'json_schema'` (CORE-015). */
+  schema?: Record<string, TConfigValue>;
+  /** Schema name forwarded to provider native structured-output surfaces. */
+  name?: string;
+}
 /**
- * Observable EventService that notifies subscribed listeners.
+ * Safety setting configuration
  */
-declare class ObservableEventService extends AbstractEventService {
-  emit(eventType: string, data: IBaseEventData, context?: IEventContext): void;
+interface ISafetySetting {
+  category: string;
+  threshold: string;
+  [key: string]: TConfigValue;
 }
 //#endregion
-//#region src/event-service/task-events.d.ts
-declare const TASK_EVENTS: {
-  readonly ASSIGNED: "assigned";
-  readonly COMPLETED: "completed";
-};
-declare const TASK_EVENT_PREFIX: "task";
-//#endregion
-//#region src/event-service/user-events.d.ts
-declare const USER_EVENTS: {
-  readonly MESSAGE: "message";
-  readonly INPUT: "input";
-};
-declare const USER_EVENT_PREFIX: "user";
-type TUserEvent = (typeof USER_EVENTS)[keyof typeof USER_EVENTS];
-//#endregion
-//#region src/event-service/span-events.d.ts
-/**
- * SELFHOST-004: per-operation span lifecycle event names. Mirrors the `TASK_EVENTS`/`USER_EVENTS`
- * pattern (a const name set + a prefix). The local name is distinctive (`span_completed`, not a bare
- * `completed`) so a consumer can identify a span-completion regardless of the emitting owner's prefix.
- */
-declare const SPAN_EVENTS: {
-  readonly COMPLETED: "span_completed";
-};
-/** Content-free completion of one provider round, separate from legacy tool timing events. */
-declare const PROVIDER_CALL_EVENTS: {
-  readonly COMPLETED: "provider_call_completed";
-};
-/** A provider request moved to another model after the one it was on failed. */
-declare const PROVIDER_FALLBACK_EVENTS: {
-  readonly SWITCHED: "provider_fallback";
-};
-/** The notice a `provider_fallback` event carries, or `undefined` when the payload is malformed. */
-declare function readModelFallbackNotice(data: Readonly<Record<string, unknown>>): IModelFallbackNotice | undefined;
-/** Content-free completion of the body actually awaited by one permitted tool call. */
-declare const TOOL_BODY_EVENTS: {
-  readonly COMPLETED: "tool_body_completed";
-};
-/** Content-free decision reached for one tool call before any body runs. */
-declare const TOOL_PERMISSION_EVENTS: {
-  readonly DECIDED: "tool_permission_decided";
-};
-declare const SPAN_EVENT_PREFIX: "span";
-type TSpanEvent = (typeof SPAN_EVENTS)[keyof typeof SPAN_EVENTS];
+//#region src/schema/zod-schema-types.d.ts
+interface IZodParseResult {
+  success: boolean;
+  data?: unknown;
+  error?: unknown;
+}
+interface IZodSchemaDef {
+  typeName?: string;
+  innerType?: IZodSchema;
+  valueType?: IZodSchema;
+  checks?: Array<{
+    kind: string;
+    value?: TUniversalValue;
+  }>;
+  shape?: () => Record<string, IZodSchema>;
+  type?: IZodSchema;
+  /**
+   * `ZodEnum` holds an ARRAY here; `ZodNativeEnum` holds the enum OBJECT itself (CORE-041). One Zod
+   * field name, two shapes — the converter narrows before reading it.
+   */
+  values?: TUniversalValue[] | Record<string, TUniversalValue>;
+  description?: string;
+  unknownKeys?: 'passthrough' | 'strip' | 'strict';
+  /** `ZodEffects` (`.refine()` / `.transform()`) holds the schema it wraps here. */
+  schema?: IZodSchema;
+  /** `ZodUnion` / `ZodDiscriminatedUnion` members. */
+  options?: IZodSchema[];
+  /** `ZodLiteral` value. */
+  value?: TUniversalValue;
+}
+interface IZodSchema {
+  parse(value: unknown): unknown;
+  safeParse(value: unknown): IZodParseResult;
+  _def?: IZodSchemaDef;
+}
 /**
- * SELFHOST-004: span-completion event payload — JOINS the span id with its measured duration and the
- * operation name (raw scalars ONLY; references no transport type). Emitted by the per-operation timing
- * source (e.g. `FunctionTool`) so a consuming layer (`agent-framework`) can build a record span entry
- * WITHOUT `agent-core` depending on `agent-interface-transport` (no cycle). The payload `spanId` is the
- * AUTHORITATIVE id a consumer reads; owner/turn correlation is applied by the event service's binding
- * (`ownerPath` on the emitted `IEventContext`). Note the context's own auto-minted `spanId` is a
- * separate scope tag and need not equal this payload id — always read the payload id for the span.
+ * Schema conversion options
  */
-interface ISpanCompletionEventData extends IBaseEventData {
-  /** The span id (equals the emitted event's context `spanId`). */
-  spanId: string;
-  /** Measured wall-clock duration of the operation, in milliseconds. */
-  durationMs: number;
-  /** The operation name (e.g. the tool name). */
-  op: string;
+interface ISchemaConversionOptions {
+  includeDescription?: boolean;
+  strictTypes?: boolean;
+  allowAdditionalProperties?: boolean;
 }
 //#endregion
-//#region src/interfaces/tool.d.ts
-type TToolContextExtensionValue = TUniversalValue | Date | Error | TLoggerData | TContextData | TToolParameters | TToolMetadata;
-/**
- * Tool metadata structure - specific type definition
- */
-type TToolMetadata = Record<string, string | number | boolean | string[] | number[] | boolean[] | TToolParameters>;
+//#region src/schema/structured-output.d.ts
+/** Explicit raw-JSON-schema form of `IRunOptions.output`. */
+interface IJsonSchemaOutput {
+  /** JSON Schema (object root, universal subset) the response must match. */
+  jsonSchema: IToolSchema['parameters'];
+  /** Optional schema name forwarded to provider native surfaces. */
+  name?: string;
+}
+/** Accepted `IRunOptions.output` values: a Zod schema or an explicit JSON-schema wrapper. */
+type TStructuredOutputSchema = IZodSchema | IJsonSchemaOutput;
+type TStructuredOutputValidation = {
+  success: true;
+  value: unknown;
+} | {
+  success: false;
+  issues: string[];
+};
+/** Internal SSOT representation every `output` value normalizes to. */
+interface IStructuredOutputSpec {
+  name: string;
+  jsonSchema: IToolSchema['parameters'];
+  validate(value: unknown): TStructuredOutputValidation;
+}
+/** Normalize an accepted `output` value into the internal spec. */
+declare function normalizeStructuredOutput(output: TStructuredOutputSchema): IStructuredOutputSpec;
 /**
- * Tool execution data - domain payload for tool results.
+ * Validate a value against the universal JSON-schema subset (`IParameterSchema`). Covers type,
+ * required, enum, items, nested properties, unions and numeric bounds — the full expressible
+ * surface of the subset, at every level.
  *
- * IMPORTANT:
- * - This must support structured tool outputs without resorting to `any`.
- * - Prefer `ToolResultData` (derived from the canonical `UniversalValue` axis).
+ * CORE-039: this is the ONE complete walk. `parameter-validator` delegates its depth here rather
+ * than keeping a second, shallower copy, and the two must therefore agree by construction.
  */
+declare function validateAgainstJsonSchema(schema: IParameterSchema, value: unknown, path: string): string[];
 /**
- * Tool execution result - extended for ToolExecutionData compatibility
+ * Parse the model's final text into a JSON value. Tolerates a fenced
+ * ```json code block wrapper (providers without native enforcement commonly
+ * emit one); the parsed value is still strictly schema-validated afterwards.
  */
-interface IToolResult {
-  success: boolean;
-  data?: TUniversalValue;
-  error?: string;
-  metadata?: TToolMetadata;
-  [key: string]: TToolContextExtensionValue | undefined;
-}
+declare function parseStructuredResponseText(text: string): {
+  success: true;
+  value: unknown;
+} | {
+  success: false;
+  issue: string;
+};
+//#endregion
+//#region src/interfaces/run-options.d.ts
 /**
- * Enhanced tool execution result with additional metadata
+ * The per-RUN contract: what one `run()` may override or observe, as distinct from the agent's
+ * standing configuration in `IAgentConfig`.
+ *
+ * Split out of `agent.ts` when PEER-007 added `driverId`. That file sits at a frozen size baseline,
+ * and the anti-monolith rule asks for a split rather than one more field on a file already at its
+ * limit. The two execution-event types come along because `onExecutionEvent` is their only consumer
+ * — leaving them behind would have made this module import back from `agent.ts`.
  */
-interface IToolExecutionResult {
-  /** Whether execution was successful */
-  success: boolean;
-  /** Tool name that was executed */
-  toolName?: string;
-  /** Execution result or data */
-  result?: TUniversalValue;
-  /** Error message if execution failed */
-  error?: string;
-  /** Execution duration in milliseconds */
-  duration?: number;
-  /** Unique execution ID */
-  executionId?: string;
-  /** Additional metadata */
-  metadata?: TToolMetadata;
-}
+type TExecutionEventData = Record<string, unknown>;
+type TExecutionEventCallback = (event: string, data: TExecutionEventData) => void;
 /**
- * Tool execution context - type-safe context for tool execution
- * Enhanced with hierarchical execution tracking support
+ * Agent run options - type-safe interface for all agent execution options
  */
-interface IToolExecutionContext {
-  toolName: string;
-  parameters: TToolParameters;
+interface IRunOptions {
+  /** Run-scoped temperature override — wins over `defaultModel.temperature` (CORE-016). */
+  temperature?: number;
+  /** Run-scoped max output tokens override — wins over `defaultModel.maxTokens` (CORE-016). */
+  maxTokens?: number;
   /**
-   * Run-scoped cancellation signal (CORE-018). Long-running tools MUST honor it: terminate
-   * the underlying work (kill the child process, abort the network request) and return an
-   * interrupted/failed result. Completing silently after an abort is a contract violation.
+   * Run-scoped tool-invocation directive — wins over `defaultModel.toolChoice` (CORE-017).
+   * `'auto'` (model decides), `'none'` (suppress tool calls), `'required'` (must call some
+   * tool), or `{ tool: name }` (must call the named tool; the name is validated against the
+   * run's tool list and a miss throws). Forcing applies to the run's first model call only;
+   * rounds after tool results revert to `'auto'` (see `TToolChoice`).
    */
-  signal?: AbortSignal;
-  /** Direct remote calls deny decisions that would require human interaction. */
-  permissionInteraction?: 'interactive' | 'deny';
-  executionId?: string;
-  userId?: string;
-  sessionId?: string;
-  metadata?: TToolMetadata;
-  /** Parent execution ID for hierarchical tool execution tracking */
-  parentExecutionId?: string;
-  /** Root execution ID (Team/Agent level) for complete execution tree tracking */
-  rootExecutionId?: string;
-  /** Execution depth level (0: Team, 1: Agent, 2: Tool, etc.) */
-  executionLevel?: number;
-  /** Execution path array showing the complete execution hierarchy */
-  executionPath?: string[];
-  /** Real-time execution data for accurate tracking (no simulation) */
-  realTimeData?: {
-    /** Actual execution start time */
-    startTime: Date;
-    /** Actual input parameters passed to the tool */
-    actualParameters: TToolParameters;
-    /** Tool-provided estimated duration (optional) */
-    estimatedDuration?: number;
-  };
+  toolChoice?: TToolChoice;
   /**
-   * Additional tool execution context extensions.
-   *
-   * IMPORTANT:
-   * - Avoid ad-hoc top-level fields to keep the contract stable.
-   * - Use this map for forward-compatible extra data with constrained value types.
+   * Leave a provider's own hosted tools (a vendor-run web search) out of this run's requests. They
+   * run at the vendor and never pass the permission gate, so a run whose tools a policy restricts
+   * must not reach them.
    */
-  extensions?: Record<string, TToolContextExtensionValue>;
-  /** Owner context propagated from EventService */
-  ownerType?: string;
-  ownerId?: string;
-  ownerPath?: IOwnerPathSegment[];
-  sourceId?: string;
+  withholdHostedTools?: boolean;
+  sessionId?: string;
+  userId?: string;
   /**
-   * Tool-call scoped EventService instance.
-   * Caller (ExecutionService/ToolExecutionService) is responsible for providing
-   * an ownerPath-bound EventService for this tool call.
+   * PEER-007 (issue #1915): who this run is attributed to, for display. Per-run because it changes
+   * per turn — one session serves the operator and any peer addressing it. Never authorization.
    */
-  eventService?: IEventService;
+  driverId?: string;
   /**
-   * Unbound base EventService instance.
-   *
-   * Required when a tool needs to create another owner-bound EventService
-   * for a different owner (e.g., creating an agent from a tool call).
-   *
-   * NOTE: Do not wrap an already owner-bound EventService to bind a different owner.
-   * Owner-bound instances must not be layered across different owners.
+   * Where this run's turn came from (a peer's message, an external event, an agent wake-up), stored
+   * beside `driverId` on the user message so a transcript carried elsewhere still says it. Display
+   * only, like `driverId`; absent for the operator's own turn.
    */
-  baseEventService?: IEventService;
+  turnSource?: string;
+  metadata?: TMetadata;
   /**
-   * The service this call's caller would give the tool with `setEventService`, carried with the
-   * call instead. One tool instance can serve several agents, and the service set on it is
-   * whichever agent set one last; a tool that emits events of its own (the `FunctionTool` span)
-   * emits them here when present, so they reach the agent that made the call. The no-op default
-   * service means that caller wants none.
+   * Run-scoped EPHEMERAL system context (SELFHOST-008 P3). A transient system-role block included in THIS
+   * run's provider request(s) only — it is **never written to the conversation store**. An explicitly
+   * configured execution journal records it as request/recovery state. It does not bloat conversation
+   * history or force a static-system-prompt rebuild. Content-free neutral channel: the
+   * caller decides what to put here (e.g. per-turn recalled memory). Absent ⇒ no change.
    */
-  instanceEventService?: IEventService;
+  ephemeralSystemContext?: string;
   /**
-   * Injected "ask the user" port (CMD-004). Present when an interactive renderer is attached, letting
-   * a tool solicit a structured answer from the user (the model-issued question seam consumed by
-   * CMD-005). Absent in non-interactive contexts; a tool that asks must treat absence as "no human
-   * available" (never a silent guess).
+   * Host-owned trace context for this run's provider calls. Each invoked call — forced summary
+   * included, cache hits excluded — gets a `traceparent` whose parent is that call's own span, and
+   * only an adapter whose origin is listed sends it. Never recorded in execution events.
    */
-  ask?: IUserInteraction['ask'];
+  traceContext?: IRunTraceContext;
   /**
-   * CLI-1990: the deferred-tool catalog the runtime injects (`ToolExecutionService`), so a search
-   * tool can list what is withheld and load it for the rest of the session. Present on every tool
-   * call the execution loop issues; a tool other than the search tool has no reason to read it.
+   * AbortSignal for cancelling execution. Aborting an in-flight run does not throw: `run()` resolves
+   * (and `runStream()` returns) the last assistant text the turn committed before the abort, possibly
+   * `''`; a reply cut off mid-stream is kept in history with `state: 'interrupted'`. Read
+   * `signal.aborted` to tell an interrupted run from a completed one.
    */
-  deferredTools?: IDeferredToolCatalog;
+  signal?: AbortSignal;
+  /** Join an aborted/timed-out provider call before completing; an uncooperative call may remain pending. */
+  awaitProviderSettlement?: boolean;
+  /** Per-run streaming text callback. Prefer this over mutating provider callback state. */
+  onTextDelta?: TTextDeltaCallback;
+  /** Per-run replay event callback for provider/tool execution boundaries. */
+  onExecutionEvent?: TExecutionEventCallback;
+  /** Awaited model/tool admission and result records. Failures terminate this run. */
+  executionJournal?: IExecutionJournal;
   /**
-   * The ID core mints for this one tool body, unique even when a vendor reuses its tool call ID.
-   * The body's exported span is derived from it, so it is also what a propagated parent names.
+   * Maximum execution rounds for this run. A **round** is one provider (model) call plus the
+   * execution of every tool call that reply requested; a reply with no tool calls ends the loop,
+   * so a plain Q&A turn is exactly 1 round. This caps model/tool cycles within ONE `run()` — it is
+   * not a tool-count limit and not a multi-turn conversation limit. When the cap is hit the run
+   * stops after the current round. Use 0 for no core round cap. Defaults to
+   * `IAgentConfig.maxExecutionRounds`.
    */
-  toolBodyId?: string;
+  maxExecutionRounds?: number;
+  /** Max times the same tool may be called with identical input before aborting. Unset = no limit. */
+  maxSameToolInputs?: number;
   /**
-   * Present only when the run carries trusted trace context: the `traceparent` naming this body's
-   * span and the exact origins it may be sent to. A tool that makes outbound requests sends it only
-   * to a listed origin.
+   * Treat a turn that ends in tool calls (no trailing text) as a valid completion instead of
+   * forcing one extra provider call to generate a summary (CORE-011). For decision-agent patterns
+   * (router/orchestrator/classifier) the tool call IS the answer — this removes the one-call tax.
+   * The summary call is the one made when the round cap ends the loop on a tool round; before the cap
+   * the model is called again after tool results as usual, so a decision agent sets
+   * `maxExecutionRounds` too (e.g. `1`). The run resolves with the turn's text, or `''` when it
+   * produced none; consumers read the outcome from the tool results.
    */
-  outboundTraceContext?: IOutboundTraceContext;
+  allowToolOnlyCompletion?: boolean;
   /**
-   * Present only when the host lets shell children inherit the trace: the environment naming this
-   * body's span. Only the foreground shell tool applies it, to its own child.
+   * Schema-enforced structured output (CORE-015). Accepts a Zod schema or an explicit
+   * `{ jsonSchema }` wrapper. `run` then resolves to the validated, typed object instead of a
+   * string: the schema is forwarded to the provider's native structured-output surface where one
+   * exists, and the final response is always parsed and validated core-side; a violation triggers
+   * a bounded retry with the validation issues fed back as the next turn's input. Every attempt is
+   * a real conversation turn (history stays append-only). Exhausted retries throw
+   * `StructuredOutputError`.
    */
-  shellTraceEnv?: ISubprocessTraceEnv;
+  output?: TStructuredOutputSchema;
   /**
-   * Present only when the host lets command hooks inherit the trace: the environment naming the
-   * prompt root, for the hooks fired around this body. Separate from {@link shellTraceEnv}, whose
-   * span is the body's own.
+   * Retry budget for structured output validation failures — the number of additional attempts
+   * after the first (default 2). Only meaningful with `output` set.
    */
-  hookTraceEnv?: ISubprocessTraceEnv;
+  outputRetries?: number;
 }
+//#endregion
+//#region src/plugins/event-emitter/types.d.ts
+declare const EXECUTION_EVENT_NAMES: {
+  readonly START: "execution.start";
+  readonly COMPLETE: "execution.complete";
+  readonly ERROR: "execution.error";
+};
+declare const TOOL_EVENT_NAMES: {
+  readonly CALL_START: "tool.call_start";
+  readonly CALL_COMPLETE: "tool.call_complete";
+  readonly CALL_ERROR: "tool.call_error";
+};
+declare const AGENT_EVENT_NAMES: {
+  readonly EXECUTION_START: "agent.execution_start";
+  readonly EXECUTION_COMPLETE: "agent.execution_complete";
+  readonly EXECUTION_ERROR: "agent.execution_error";
+  readonly CREATED: "agent.created";
+};
+type TExecutionEventName = (typeof EXECUTION_EVENT_NAMES)[keyof typeof EXECUTION_EVENT_NAMES];
+type TToolEventName = (typeof TOOL_EVENT_NAMES)[keyof typeof TOOL_EVENT_NAMES];
+type TAgentEventName = (typeof AGENT_EVENT_NAMES)[keyof typeof AGENT_EVENT_NAMES];
 /**
- * Parameter validation result
+ * Event types that can be emitted.
+ *
+ * IMPORTANT:
+ * - Do not use string literals for event names outside this module.
+ * - Import and use EVENT_EMITTER_EVENTS instead.
  */
-interface IParameterValidationResult {
-  /** Whether parameters are valid */
-  isValid: boolean;
-  /** Validation error messages */
-  errors: string[];
-}
+declare const EVENT_EMITTER_EVENTS: {
+  readonly EXECUTION_START: "execution.start";
+  readonly EXECUTION_COMPLETE: "execution.complete";
+  readonly EXECUTION_ERROR: "execution.error";
+  readonly TOOL_BEFORE_EXECUTE: "tool.beforeExecute";
+  readonly TOOL_AFTER_EXECUTE: "tool.afterExecute";
+  readonly TOOL_SUCCESS: "tool.success";
+  readonly TOOL_ERROR: "tool.call_error";
+  readonly CONVERSATION_START: "conversation.start";
+  readonly CONVERSATION_COMPLETE: "conversation.complete";
+  readonly CONVERSATION_ERROR: "conversation.error";
+  readonly AGENT_EXECUTION_START: "agent.execution_start";
+  readonly AGENT_EXECUTION_COMPLETE: "agent.execution_complete";
+  readonly AGENT_EXECUTION_ERROR: "agent.execution_error";
+  readonly AGENT_CREATED: "agent.created";
+  readonly AGENT_DESTROYED: "agent.destroyed";
+  readonly PLUGIN_LOADED: "plugin.loaded";
+  readonly PLUGIN_UNLOADED: "plugin.unloaded";
+  readonly PLUGIN_ERROR: "plugin.error";
+  readonly ERROR_OCCURRED: "error.occurred";
+  readonly WARNING_OCCURRED: "warning.occurred";
+  readonly MODULE_INITIALIZE_START: "module.initialize.start";
+  readonly MODULE_INITIALIZE_COMPLETE: "module.initialize.complete";
+  readonly MODULE_INITIALIZE_ERROR: "module.initialize.error";
+  readonly MODULE_EXECUTION_START: "module.execution.start";
+  readonly MODULE_EXECUTION_COMPLETE: "module.execution.complete";
+  readonly MODULE_EXECUTION_ERROR: "module.execution.error";
+  readonly MODULE_DISPOSE_START: "module.dispose.start";
+  readonly MODULE_DISPOSE_COMPLETE: "module.dispose.complete";
+  readonly MODULE_DISPOSE_ERROR: "module.dispose.error";
+  readonly MODULE_REGISTERED: "module.registered";
+  readonly MODULE_UNREGISTERED: "module.unregistered";
+  readonly EXECUTION_HIERARCHY: "execution.hierarchy";
+  readonly EXECUTION_REALTIME: "execution.realtime";
+  readonly TOOL_REALTIME: "tool.realtime";
+  readonly CUSTOM: "custom";
+};
+type TEventName = TExecutionEventName | TToolEventName | TAgentEventName | 'tool.beforeExecute' | 'tool.afterExecute' | 'tool.success' | 'conversation.start' | 'conversation.complete' | 'conversation.error' | 'agent.destroyed' | 'plugin.loaded' | 'plugin.unloaded' | 'plugin.error' | 'error.occurred' | 'warning.occurred' | 'module.initialize.start' | 'module.initialize.complete' | 'module.initialize.error' | 'module.execution.start' | 'module.execution.complete' | 'module.execution.error' | 'module.dispose.start' | 'module.dispose.complete' | 'module.dispose.error' | 'module.registered' | 'module.unregistered' | 'execution.hierarchy' | 'execution.realtime' | 'tool.realtime' | 'custom';
 /**
- * Generic tool executor function
+ * Valid event data value types
  */
-type TToolExecutor<TParams = TToolParameters, TResult = TUniversalValue> = (parameters: TParams, context?: IToolExecutionContext) => Promise<TResult>;
+type TEventDataValue = string | number | boolean | Date | null | undefined | TEventDataValue[] | {
+  [key: string]: TEventDataValue;
+};
 /**
- * Base tool interface
+ * Event data structure
  */
-interface ITool {
-  /** Tool schema */
-  schema: IToolSchema;
-  /**
-   * Execute the tool with given parameters
-   */
-  execute(parameters: TToolParameters, context?: IToolExecutionContext): Promise<IToolResult>;
-  /**
-   * Validate tool parameters
-   */
-  validate(parameters: TToolParameters): boolean;
-  /**
-   * Validate tool parameters with detailed result
-   */
-  validateParameters(parameters: TToolParameters): IParameterValidationResult;
-  /**
-   * Get tool description
-   */
-  getDescription(): string;
+interface IEventEmitterEventData {
+  type: TEventName;
+  timestamp: Date;
+  executionId?: string;
+  sessionId?: string;
+  userId?: string;
+  data?: Record<string, TEventDataValue>;
+  error?: Error;
+  metadata?: Record<string, TEventDataValue>;
 }
 /**
- * Function tool implementation
+ * Event listener function
  */
-interface IFunctionTool extends ITool {
-  /** Function to execute */
-  fn: TToolExecutor;
-}
+type TEventEmitterListener = (event: IEventEmitterEventData) => void | Promise<void>;
 /**
- * Tool registry interface
+ * Console-like interface for the EventEmitterPlugin.
+ *
+ * Use this interface for typing instead of the concrete EventEmitterPlugin class.
  */
-interface IToolRegistry {
-  /**
-   * Register a tool
-   */
-  register(tool: ITool): void;
-  /**
-   * Unregister a tool
-   */
-  unregister(name: string): void;
-  /**
-   * Get tool by name
-   */
-  get(name: string): ITool | undefined;
-  /**
-   * Get all registered tools
-   */
-  getAll(): ITool[];
-  /**
-   * Get tool schemas
-   */
-  getSchemas(): IToolSchema[];
-  /**
-   * Check if tool exists
-   */
-  has(name: string): boolean;
-  /**
-   * Clear all tools
-   */
-  clear(): void;
+interface IEventEmitterPlugin {
+  on(eventType: TEventName, listener: TEventEmitterListener, options?: {
+    once?: boolean;
+    filter?: (event: IEventEmitterEventData) => boolean;
+  }): string;
+  once(eventType: TEventName, listener: TEventEmitterListener, filter?: (event: IEventEmitterEventData) => boolean): string;
+  off(eventType: TEventName, handlerIdOrListener: string | TEventEmitterListener): boolean;
+  emit(eventType: TEventName, eventData?: Partial<IEventEmitterEventData>): Promise<void>;
+}
+//#endregion
+//#region src/abstracts/abstract-module-types.d.ts
+/** Module execution context */
+interface IModuleExecutionContext {
+  executionId?: string;
+  sessionId?: string;
+  userId?: string;
+  agentName?: string;
+  metadata?: Record<string, string | number | boolean | Date>;
+  [key: string]: string | number | boolean | Date | Record<string, string | number | boolean | Date> | undefined;
+}
+/** Module execution result */
+interface IModuleExecutionResult {
+  success: boolean;
+  data?: IModuleResultData;
+  error?: Error;
+  duration?: number;
+  metadata?: Record<string, string | number | boolean | Date>;
+}
+/** Module result data */
+interface IModuleResultData {
+  [key: string]: string | number | boolean | Record<string, string | number | boolean> | undefined;
+}
+/** Base module options */
+interface IBaseModuleOptions {
+  enabled?: boolean;
+  config?: Record<string, string | number | boolean>;
+}
+/** Module capabilities */
+interface IModuleCapabilities {
+  capabilities: string[];
+  dependencies?: string[];
+  optionalDependencies?: string[];
+}
+/** Module type descriptor */
+interface IModuleDescriptor {
+  type: string;
+  category: ModuleCategory;
+  layer: ModuleLayer;
+  dependencies?: string[];
+  capabilities?: string[];
+}
+/** Module categories */
+declare enum ModuleCategory {
+  CORE = "core",
+  STORAGE = "storage",
+  PROCESSING = "processing",
+  INTEGRATION = "integration",
+  INTERFACE = "interface",
+  CAPABILITY = "capability"
+}
+/** Module layers */
+declare enum ModuleLayer {
+  INFRASTRUCTURE = "infrastructure",
+  CORE = "core",
+  APPLICATION = "application",
+  DOMAIN = "domain",
+  PRESENTATION = "presentation"
+}
+/** Module data for introspection */
+interface IModuleData {
+  name: string;
+  version: string;
+  type: string;
+  enabled: boolean;
+  initialized: boolean;
+  capabilities: IModuleCapabilities;
+  metadata?: Record<string, string | number | boolean>;
+}
+/** Module statistics */
+interface IModuleStats {
+  enabled: boolean;
+  initialized: boolean;
+  executionCount: number;
+  errorCount: number;
+  lastActivity?: Date;
+  averageExecutionTime?: number;
+  [key: string]: string | number | boolean | Date | undefined;
+}
+/** Type-safe module interface */
+interface IModule<TOptions extends IBaseModuleOptions = IBaseModuleOptions, TStats = IModuleStats> {
+  name: string;
+  version: string;
+  enabled: boolean;
+  initialize(options?: TOptions, eventEmitter?: IEventEmitterPlugin): Promise<void>;
+  dispose?(): Promise<void>;
+  execute?(context: IModuleExecutionContext): Promise<IModuleExecutionResult>;
+  getModuleType(): IModuleDescriptor;
+  getCapabilities(): IModuleCapabilities;
+  getData?(): IModuleData;
+  getStats?(): TStats;
+  isEnabled(): boolean;
+  isInitialized(): boolean;
 }
 //#endregion
 //#region src/abstracts/abstract-plugin-types.d.ts
@@ -2510,6 +2752,11 @@ interface IAbstractTool<TParams = TToolParameters, TResult = IToolResult> {
 interface IToolContract<TParameters = TToolParameters, TResult = IToolResult> {
   readonly schema: IToolSchema;
   execute(parameters: TParameters, context: IToolExecutionContext): Promise<TResult>;
+  /**
+   * Wrappers await admission exactly once with final canonical arguments after preconditions and before
+   * the body. Denial returns without admission. Admission failures propagate unchanged.
+   */
+  executeWithAdmission?(parameters: TParameters, context: IToolExecutionContext, admit: TToolEffectAdmission<TParameters>): Promise<TResult>;
   validate(parameters: TParameters): boolean;
   validateParameters(parameters: TParameters): IParameterValidationResult;
   getDescription(): string;
@@ -3120,6 +3367,8 @@ interface IToolManager {
    * deferral is not engaged. The same member `IDeferredToolCatalog` declares.
    */
   listDeferredTools(): IToolSchema[];
+  /** Loaded residency for compatible execution checkpoints. */
+  getLoadedDeferredTools?(): string[];
   /**
    * CLI-1990: mark deferred tools loaded for the rest of the session and return their schemas; an
    * unknown name throws, naming it, before anything is loaded. The same member
@@ -4444,6 +4693,35 @@ declare class ErrorUtils {
   static wrapProviderError(error: TErrorExternalInput, provider: string, operation: string): ProviderError;
 }
 //#endregion
+//#region src/utils/execution-journal-error.d.ts
+/** A persistence/admission failure must never become a model-visible, retryable tool failure. */
+declare class ExecutionJournalError extends Error {
+  readonly code = "EXECUTION_JOURNAL_FAILED";
+  readonly recordId: string;
+  readonly kind: TExecutionJournalRecord['kind'];
+  constructor(record: TExecutionJournalRecord, cause: unknown);
+}
+//#endregion
+//#region src/utils/execution-suspended-error.d.ts
+/** A persisted wait is control flow, never a failed tool result or semantic completion. */
+declare class ExecutionSuspendedError extends Error {
+  readonly code = "EXECUTION_SUSPENDED";
+  readonly requests: readonly IToolWaitRequest[];
+  constructor(requests: readonly IToolWaitRequest[]);
+}
+//#endregion
+//#region src/utils/execution-recovery-error.d.ts
+type TExecutionRecoveryErrorCode = 'EXECUTION_RECOVERY_INVALID' | 'EXECUTION_RECOVERY_REQUIRED' | 'EXECUTION_RECOVERY_CONFLICT';
+/** Recovery refuses unproven effects or history instead of guessing whether to replay them. */
+declare class ExecutionRecoveryError extends Error {
+  readonly code: TExecutionRecoveryErrorCode;
+  readonly actionIds: readonly string[];
+  constructor(code: TExecutionRecoveryErrorCode, message: string, actionIds?: readonly string[]);
+}
+//#endregion
+//#region src/utils/execution-control-error.d.ts
+declare function isExecutionControlError(error: unknown): error is ExecutionJournalError | ExecutionRecoveryError | ExecutionSuspendedError;
+//#endregion
 //#region src/utils/timer-types.d.ts
 /**
  * Cross-platform timer identifier type.
@@ -4551,6 +4829,9 @@ declare function subprocessTraceEnvironment(base: Readonly<Record<string, string
  */
 declare function traceHeadersFor(baseUrl: string | undefined, traceContext: IOutboundTraceContext | undefined): Readonly<Record<string, string>>;
 //#endregion
+//#region src/services/execution-journal.d.ts
+declare function callJournaledProvider(chat: (messages: TUniversalMessage[], options: IChatOptions) => Promise<TUniversalMessage>, messages: TUniversalMessage[], options: IChatOptions, context?: IModelJournalContext): Promise<TUniversalMessage>;
+//#endregion
 //#region src/schema/zod-to-json-schema.d.ts
 /**
  * Convert a Zod schema to the universal JSON-schema subset.
@@ -5481,6 +5762,7 @@ declare class Tools extends AbstractManager implements IToolManager {
   /** Whether a call to this tool would execute now: registered, and offered by the projection. */
   isToolOffered(name: string): boolean;
   /** Deferred tools not yet loaded — the population a search discovers. Empty while deferral is off. */
+  getLoadedDeferredTools(): string[];
   listDeferredTools(): IToolSchema[];
   /**
    * Mark deferred tools loaded for the rest of the session. Every name is resolved before any is
@@ -5620,6 +5902,16 @@ declare class Robota extends RobotaBase implements IAgent<IAgentConfig, IRunOpti
   listRuntimeTools(): Promise<IToolSchema[]>;
   /** Explicit tool invocation through the same executor used by model turns. */
   invokeRuntimeTool(name: string, parameters: TToolParameters, context: IToolExecutionContext): Promise<IToolExecutionResult>;
+  /**
+   * Resume a compatible journaled execution without adding input or repeating settled calls.
+   * Retain restored history for the host to checkpoint or discard, including on interruption.
+   */
+  resume(value: IResumeExecutionOptions): Promise<string>;
+  /**
+   * Restore the latest journaled tool batch without a model call or new user input.
+   * The host must own the journal exclusively and settle the previous runtime first.
+   */
+  resumeToolCalls(value: IResumeToolCallsOptions): Promise<IResumeToolCallsResult>;
   /**
    * Concurrency contract (CORE-012): a Robota instance owns ONE conversation history, so
    * concurrent `run`/`runStream` calls on the same instance are serialized on an internal queue —
@@ -6000,6 +6292,19 @@ declare function isRegistryTransactionError(error: unknown): error is IRegistryT
  */
 declare function runRegistryTransaction(steps: readonly IRegistryTransactionStep[]): Promise<void>;
 //#endregion
+//#region src/services/provider-call-usage.d.ts
+type TProviderUsageProvenance = 'complete' | 'partial' | 'absent';
+interface IVerifiedProviderCallUsage {
+  readonly provenance: TProviderUsageProvenance;
+  readonly promptTokens?: number;
+  readonly completionTokens?: number;
+  readonly totalTokens?: number;
+  /** The part of `promptTokens` served from the provider's prompt cache, when it was reported. */
+  readonly cacheReadTokens?: number;
+}
+/** Keep billing/telemetry stricter than context-window heuristics: only adapter-attested totals count. */
+declare function verifiedProviderCallUsage(message: TUniversalMessage | undefined): IVerifiedProviderCallUsage;
+//#endregion
 //#region src/services/execution-usage.d.ts
 /**
  * Aggregate token totals over a whole session/sub-session history.
@@ -7016,8 +7321,7 @@ declare function estimateBlendedCostPer1000(modelId: string): number | undefined
  * `packages/agent-core/docs/HOOK-CATALOG.md` § "Blocking semantics" — cited here rather than
  * recounted, because two different groupings of the same set were in circulation and a second copy
  * is what let them drift. Which events enforce is recorded in `HOOK_ENFORCEMENT_POLICY`
- * (`./enforcement-policy.ts`); see the catalog SSOT `packages/agent-core/docs/HOOK-CATALOG.md` for
- * per-event timing, fire-site, and blocking semantics.
+ * (`./enforcement-policy.ts`); the catalog also gives per-event timing and fire sites.
  */
 type THookEvent = 'PreToolUse' | 'PostToolUse' | 'SessionStart' | 'SessionEnd' | 'Stop' | 'StopFailure' | 'PreCompact' | 'PostCompact' | 'UserPromptSubmit' | 'SubagentStart' | 'SubagentStop' | 'WorktreeCreate' | 'WorktreeRemove' | 'PreModelCall' | 'PostModelCall' | 'PermissionDecision';
 /** Claude Code compatible session end reasons. */
@@ -7118,7 +7422,7 @@ interface IHookInput {
   agent_type?: string;
   /** Subagent transcript path when available (SubagentStop only) */
   agent_transcript_path?: string;
-  /** Claude Code permission mode at time of event (e.g. "default", "plan", "acceptEdits", "bypassPermissions") */
+  /** Permission mode at the time of the event (e.g. "default", "plan", "acceptEdits", "bypassPermissions", "auto") */
   permission_mode?: string;
   /**
    * Provider model identifier for the model call (PreModelCall/PostModelCall only).
@@ -7295,5 +7599,5 @@ declare function decodeHookVerdict(raw: string, source: THookDefinition['type'],
 /** Does a hook that reached no verdict block at this event? */
 declare function isEnforcing(event: THookEvent): boolean;
 //#endregion
-export { AGENT_EVENTS, AGENT_EVENT_PREFIX, AbstractAIProvider, AbstractAgent, AbstractEventService, AbstractExecutor, AbstractManager, AbstractPlugin, AbstractTool, AgentFactory, AgentTemplates, AuthenticationError, CONFIRM_NO, CONFIRM_YES, CONTEXT_ESTIMATE_CHARS_PER_TOKEN, CacheIntegrityError, CircuitBreakerOpenError, ConfigurationError, ConsoleLogger, ConversationHistory, ConversationStore, DEFAULT_ABSTRACT_EVENT_SERVICE, DEFAULT_BACKGROUND_PERMISSION_POLICY, DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_OUTPUT, DEFAULT_TOOL_RESULT_HARD_CHARS, DEFAULT_TOOL_RESULT_WARNING_CHARS, DEFERRED_WITHOUT_LOADER_MESSAGE, DefaultEventService, ENV_REFERENCE_PREFIX, EVENT_EMITTER_EVENTS, EXECUTION_EVENTS, EXECUTION_EVENT_PREFIX, ErrorUtils, EventEmitterPlugin, EventHistoryModule, ExecutionProxy, FunctionTool, GuardrailExecutor, type IAIProvider, type IAIProviderInstance, type IAIProviderManager, type IAbstractTool, type IAbstractToolOptions, type IActionDefault, type IActionOption, type IActionRequest, type IAgent, type IAgentConfig, type IAgentCreationStats, type IAgentEventData, type IAgentFactoryOptions, type IAgentHookDefinition, type IAgentLifecycleEvents, type IAgentTemplate, type IAssistantMessage, type IAssistantUsageMetadata, type IBaseEventData, type IBaseMessage, type IBoundedOutput, type IBoundedOutputOptions, type ICacheEntry, type ICacheKey, type ICacheOptions, type ICacheStats, type ICacheStorage, type IChatExecutionRequest, type IChatOptions, type ICommandHookDefinition, type IContextOptions, type IContextTokenEstimate, type IContextTokenEstimateOptions, type IContextTokenUsage, type IContextWindowState, type IConversationContext, type IConversationResponse, type IConversationService, type IConversationServiceOptions, type ICredentialKey, type ICredentialStore, type ICriticalPathContext, type IDeferredToolCatalog, type IDestroyResult, type IDirent, type IEventContext, type IEventEmitterEventData, type IEventEmitterHierarchicalEventData, type IEventEmitterMetrics, type IEventEmitterMetricsSnapshot, type IEventEmitterPlugin, type IEventEmitterPluginOptions, type IEventHistoryModule, type IEventHistoryRecord, type IEventHistorySnapshot, type IEventObjectValue, type IEventService, type IEventServiceOwnerBinding, type IExecutionEventData, type IExecutionProxyConfig, type IExecutor, IExecutorAwareProviderConfig, type IExecutorChatResult, type IExecutorStreamMessageEvent, type IExecutorStreamTerminalEvent, type IFileSystem, type IFileSystemAsync, type IFunctionTool, type IGroupChatOrchestrationSpec, type IGuardrailHookDefinition, type IGuardrailResult, type IHandoffOrchestrationSpec, type IHierarchicalOrchestrationSpec, type IHistoryEntry, type IHookGroup, type IHookInput, type IHookTypeExecutor, type IHttpHookDefinition, type IImageComposeRequest, type IImageEditRequest, type IImageGenerationProvider, type IImageGenerationRequest, type IImageGenerationResult, type IInlineImageInputSource, type IInlineImageMessagePart, type IJsonSchemaOutput, type ILocalExecutorConfig, ILogger, ILoggerOptions, IManagerLifecycleOptions, type IMediaOutputRef, type IMediaProviderConfig, type IMediaProviderCredentialRequirement, type IMediaProviderDefinition, type IMediaProviderOverrides, type IMessageTokenUsage, type IModelCapabilityDeviation, type IModelDefinition, type IModelEffortCapability, type IModelEffortOutcome, type IModelEffortResolution, type IModelFallbackNotice, type IModelPrice, type IModelRef, type IObjectParameterSchema, type IOpenAPIToolConfig, type IOrchestrationDelegation, type IOrchestrationEventData, type IOrchestrationRunResult, type IOrchestrationStep, type IOrchestrationStepResult, type IOutboundTraceContext, type IOwnerPathSegment, type IParallelOrchestrationSpec, type IParameterRule, type IParameterSchema, type IParameterValidationResult, type IPermissionEvaluationContext, type IPermissionLists, type IPermissionPatternProblem, type IPermissionPolicyContext, type IPermissionPolicyProjection, IPlatformShell, IPlatformShellResolutionRequest, type IPlugin, type IPluginConfig, type IPluginContext, type IPluginContract, type IPluginData, type IPluginErrorContext, type IPluginExecutionContext, type IPluginExecutionResult, type IPluginHooks, type IPluginOptions, type IPluginStats, type IProgressReportingTool, type IPromptHookDefinition, type IProviderCapabilities, type IProviderCapabilityTable, type IProviderCredentialRequirement, type IProviderDefinition, type IProviderDefinitionConfig, type IProviderEndpoint, type IProviderFailureClassification, IProviderFailureDetails, type IProviderFunctionCallingCapability, type IProviderMediaError, type IProviderModelCatalog, type IProviderModelCatalogEntry, type IProviderModelEffortTable, type IProviderNativeRawPayloadEvent, type IProviderNativeWebToolCapabilities, type IProviderNativeWebToolCapability, type IProviderNativeWebToolRequest, type IProviderOptions, type IProviderProbeResult, type IProviderProfileConfig, type IProviderProfileDefaults, type IProviderRequest, IProviderRuntimeConfig, type IProviderSetupHelpLink, type IProviderSetupStepDefinition, type IProviderSpecificOptions, type IProviderStructuredOutputCapability, type IRawProviderResponse, type IReadOnlyCommandContext, type IRegistryOwnedLifecycle, type IRegistryTransactionError, type IRegistryTransactionStep, type IRemoteExecutorConfig, type IResponseFormatConfig, type IRunOptions, type IRunTraceContext, type ISchemaClosureChange, type ISchemaClosureOptions, type ISchemaConversionOptions, type ISequentialOrchestrationSpec, type ISession, type ISessionUsageTotals, ISimpleValidationResult, type ISpanCompletionEventData, type ISpinner, type IStats, type IStreamExecutionRequest, type IStreamingChunk, type IStructuredOutputResolutionInput, type IStructuredOutputSpec, type ISubprocessTraceEnv, type ISystemMessage, type ITemplateApplicationResult, type ITerminalOutput, type ITextMessagePart, type ITokenUsage, type ITokenUsageWithCacheRead, type ITool, type IToolCall, type IToolContract, type IToolEventData, type IToolExecutionContext, type IToolExecutionRequest, type IToolExecutionResult, type IToolExecutionStep, type IToolFactory, type IToolManager, type IToolMessage, type IToolPermissionArgument, type IToolPermissionProfile, type IToolRegistry, type IToolResult, type IToolResultAdmissionOptions, type IToolResultSpillStore, type IToolSchema, type IToolSchemaProjection, type IToolSchemaProjectionChange, type IToolSchemaProjectionProfile, type IToolWithEventService, type IUniversalObjectValue, type IUriImageInputSource, type IUriImageMessagePart, type IUserInteraction, type IUserMessage, IUtilLogEntry, type IVideoGenerationProvider, type IVideoGenerationRequest, type IVideoJobAccepted, type IVideoJobSnapshot, type IZodParseResult, type IZodSchema, type IZodSchemaDef, InMemoryEventEmitterMetrics, LocalExecutor, MAX_TOOL_RESULT_CHARS, MODEL_EFFORT_VALUES, MODEL_PRICES, MessageConverter, ModelNotAvailableError, NetworkError, ORCHESTRATION_EVENTS, ORCHESTRATION_EVENT_PREFIX, ObservableEventService, PARAMETER_SCHEMA_KEYWORDS, PERMISSIVE_TOOL_SCHEMA_PROFILE, PROTECTED_DIRECTORY_NAMES, PROTECTED_FILE_NAMES, PROVIDER_CALL_EVENTS, PROVIDER_FALLBACK_EVENTS, PluginCategory, PluginError, PluginPriority, ProviderError, RISK_CLASS_POLICY, RateLimitError, Robota, RobotaError, SPAN_EVENTS, SPAN_EVENT_PREFIX, STRICT_TOOL_SCHEMA_PROFILE, SameToolInputLoopError, SilentLogger, StorageError, StructuredEventService, StructuredOutputError, TASK_EVENTS, TASK_EVENT_PREFIX, type TActionResponse, type TArgumentKind, type TBackgroundPermissionPolicy, TComplexConfigValue, TConfigData, TConfigValue, TContextData, type TConversationContextMetadata, type TEnvResolver, TErrorContextData, TErrorExternalInput, type TEventEmitterListener, type TEventExtensionValue, type TEventListener, type TEventLoggerData, type TEventName, type TEventUniversalValue, type TExecutionEventCallback, type TExecutionEventData, type TExecutionEventName, type TExecutorStreamEvent, type TGuardrail, type THookDefinition, type THookEvent, type THookOutcome, type THooksConfig, type TImageInputSource, type TJSONSchemaEnum, type TJSONSchemaKind, TLoggerData, type TManagerToolParameters, type TMatchDirection, TMessageConverterRegistry, TMessageFormatConverter, type TMessageState, TMetadata, TMetadataValue, type TModelEffort, type TModelEffortDisposition, type TModelEffortNativeControl, type TModelEffortOutcomeCallback, type TModelEffortProviderDispatch, type TModelEffortSelection, type TModelFallbackCallback, TOOL_BODY_EVENTS, TOOL_EVENTS, TOOL_EVENT_PREFIX, TOOL_PERMISSION_EVENTS, TOOL_SCHEMA_PROJECTION_MAX_DEPTH, TOOL_SCHEMA_PROJECTION_MAX_NODES, TOOL_SEARCH_TOOL_NAME, type TOrchestrationEvent, type TOrchestrationPrimitive, type TOutputRetention, type TParameterDefaultValue, type TPermissionDecision, type TPermissionMode, type TPrimitiveValue, type TProviderConfigValue, type TProviderCredentialField, type TProviderFailureReason, TProviderLoggingData, type TProviderMediaResult, TProviderMessage, type TProviderModelCapability, type TProviderModelCatalogStatus, type TProviderModelLifecycle, type TProviderNativeRawPayload, type TProviderNativeRawPayloadCallback, type TProviderNativeRawPayloadKind, type TProviderOptionValueBase, type TProviderSetupField, type TProviderSetupHelpLinkKind, TRUST_TO_MODE, type TResolveInWorkspace, type TResponseMetadata, type TRoleModelMap, type TSessionEndReason, TShellKind, type TSpanEvent, type TStructuredOutputMechanism, type TStructuredOutputProvenance, type TStructuredOutputSchema, type TStructuredOutputValidation, type TSubprocessTraceClass, type TTextDeltaCallback, type TTimerId, type TToolArgs, type TToolChoice, type TToolExecutionFunction, type TToolExecutionParameters, type TToolExecutor, type TToolMetadata, TToolParameters, type TToolProgressCallback, type TToolResultAdmissionErrorCode, type TToolRiskClass, type TToolSchemaProjectionOutcome, type TToolSchemaProjectionProfileBase, type TToolSearchMode, type TToolSearchSetting, type TTrustLevel, type TUniversalArrayValue, type TUniversalMessage, type TUniversalMessageMetadata, type TUniversalMessagePart, type TUniversalMessageRole, type TUniversalValue, type TUserEvent, TUtilLogLevel, ToolExecutionError, ToolRegistry, ToolResultAdmissionError, TypeUtils, UNCLASSIFIED_TOOL_FALLBACK, USER_EVENTS, USER_EVENT_PREFIX, UnsupportedShellError, ValidationError, Validator, admitToolResult, allowRulesForAutoMode, applyPresetToolLists, assertProviderNativeWebToolsAvailable, assertResidentToolRemains, bindEventServiceOwner, bindWithOwnerPath, buildTraceparent, calculateModelCost, chatEntryToMessage, classifyProviderFailure, clearRegisteredToolProfiles, closeObjectSchemas, collectAssistantUsageMetadata, composeEventName, confirmAction, createAssistantMessage, createBoundedOutput, createDefaultProviderCapabilities, createExecutionProxy, createImageProviderFromDefinition, createLogger, createModelEffortOutcome, createProviderFromConfig, createRecordEnvResolver, createSystemMessage, createToolMessage, createUserMessage, createVideoProviderFromDefinition, decodeHookVerdict, estimateBlendedCostPer1000, estimateContextTokensFromMessages, estimateSerializedContextTokens, estimateToolSchemaTokens, evaluatePermission, extractEnumValues, findInvalidPermissionPatterns, findMediaProviderDefinition, findModelDefinition, findPermissionPatternWarnings, findProviderDefinition, formatEnvReference, formatSupportedProviderTypes, formatTokenCount, generateSpanId, getGlobalLogLevel, getGlobalLoggerSink, getMessagesForAPI, getModelContextWindow, getModelMaxOutput, getModelName, getProviderCapabilities, getProviderCredentialRequirement, getSchemaTypeName, getToolEstimatedDuration, getToolExecutionSteps, getToolPermissionProfile, hasUsableSecretReference, hasValidationConstraints, hashToolSchema, isAbortFailure, isAssistantMessage, isBroadExecutionAllowRule, isChatEntry, isConfirmed, isDefaultEventService, isEnforcing, isEnvReference, isImageGenerationProvider, isMediaProviderDefinition, isMintedSpanId, isModelEffort, isProgressReportingTool, isProtectedPath, isReadOnlyCommandLine, isRegistryTransactionError, isSystemMessage, isToolDeniedOutright, isToolMessage, isUserMessage, isVideoGenerationProvider, lifecycleOf, logger, lookupModelPrice, matchesAnyPattern, messageToHistoryEntry, modelDeclaresCapability, multiSelectAction, normalizeProviderConfig, normalizeStructuredOutput, outboundTraceContextFor, parseParameterRule, parseStructuredResponseText, peerDriverOf, printablePeerDriver, processEnvResolver, projectPermissionPolicy, projectToolSchema, providerCallSpanId, readModelFallbackNotice, readProviderFailureDetails, readTokenUsageFromMessage, readTokenUsageFromMetadata, registerModelMetadata, registerToolPermissionProfile, removesCriticalPath, requiresFreshApproval, resolveEnvReference, resolveMediaProviderConfig, resolveModelCapabilities, resolveModelCapability, resolveModelEffort, resolvePlatformShell, resolveStructuredOutputCapability, runHooks, runRegistryTransaction, selectAction, setGlobalLogLevel, setGlobalLoggerSink, setToolProgressCallback, shellArgumentForDisplay, spanIdFromMintedId, splitCommandSegments, startPeriodicTask, stopPeriodicTask, subprocessTraceEnvironment, sumHistoryUsage, sumMessagesUsage, textAction, toProviderError, toolNameMatches, toolNamesToPatterns, toolTraceContextFor, traceEnvFor, traceHeadersFor, validateAgainstJsonSchema, validateAgentConfig, validateApiKey, validateModelName, validatePermissionPattern, validateProviderName, validateUserInput, wasToolResultAdmitted, withEventEmission, zodToJsonSchema };
+export { AGENT_EVENTS, AGENT_EVENT_PREFIX, AbstractAIProvider, AbstractAgent, AbstractEventService, AbstractExecutor, AbstractManager, AbstractPlugin, AbstractTool, AgentFactory, AgentTemplates, AuthenticationError, CONFIRM_NO, CONFIRM_YES, CONTEXT_ESTIMATE_CHARS_PER_TOKEN, CacheIntegrityError, CircuitBreakerOpenError, ConfigurationError, ConsoleLogger, ConversationHistory, ConversationStore, DEFAULT_ABSTRACT_EVENT_SERVICE, DEFAULT_BACKGROUND_PERMISSION_POLICY, DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_OUTPUT, DEFAULT_TOOL_RESULT_HARD_CHARS, DEFAULT_TOOL_RESULT_WARNING_CHARS, DEFERRED_WITHOUT_LOADER_MESSAGE, DefaultEventService, ENV_REFERENCE_PREFIX, EVENT_EMITTER_EVENTS, EXECUTION_EVENTS, EXECUTION_EVENT_PREFIX, ErrorUtils, EventEmitterPlugin, EventHistoryModule, ExecutionJournalError, ExecutionProxy, ExecutionRecoveryError, ExecutionSuspendedError, FunctionTool, GuardrailExecutor, type IAIProvider, type IAIProviderInstance, type IAIProviderManager, type IAbstractTool, type IAbstractToolOptions, type IActionDefault, type IActionOption, type IActionRequest, type IAgent, type IAgentConfig, type IAgentCreationStats, type IAgentEventData, type IAgentFactoryOptions, type IAgentHookDefinition, type IAgentLifecycleEvents, type IAgentTemplate, type IAssistantMessage, type IAssistantUsageMetadata, type IBaseEventData, type IBaseMessage, type IBoundedOutput, type IBoundedOutputOptions, type ICacheEntry, type ICacheKey, type ICacheOptions, type ICacheStats, type ICacheStorage, type IChatExecutionRequest, type IChatOptions, type ICommandHookDefinition, type IContextOptions, type IContextTokenEstimate, type IContextTokenEstimateOptions, type IContextTokenUsage, type IContextWindowState, type IConversationContext, type IConversationResponse, type IConversationService, type IConversationServiceOptions, type ICredentialKey, type ICredentialStore, type ICriticalPathContext, type IDeferredToolCatalog, type IDestroyResult, type IDirent, type IEventContext, type IEventEmitterEventData, type IEventEmitterHierarchicalEventData, type IEventEmitterMetrics, type IEventEmitterMetricsSnapshot, type IEventEmitterPlugin, type IEventEmitterPluginOptions, type IEventHistoryModule, type IEventHistoryRecord, type IEventHistorySnapshot, type IEventObjectValue, type IEventService, type IEventServiceOwnerBinding, type IExecutionContinuationState, type IExecutionEventData, type IExecutionJournal, type IExecutionProxyConfig, type IExecutionRoundCheckpoint, type IExecutor, IExecutorAwareProviderConfig, type IExecutorChatResult, type IExecutorStreamMessageEvent, type IExecutorStreamTerminalEvent, type IFileSystem, type IFileSystemAsync, type IFunctionTool, type IGroupChatOrchestrationSpec, type IGuardrailHookDefinition, type IGuardrailResult, type IHandoffOrchestrationSpec, type IHierarchicalOrchestrationSpec, type IHistoryEntry, type IHookGroup, type IHookInput, type IHookTypeExecutor, type IHttpHookDefinition, type IImageComposeRequest, type IImageEditRequest, type IImageGenerationProvider, type IImageGenerationRequest, type IImageGenerationResult, type IInlineImageInputSource, type IInlineImageMessagePart, type IJsonSchemaOutput, type ILocalExecutorConfig, ILogger, ILoggerOptions, IManagerLifecycleOptions, type IMediaOutputRef, type IMediaProviderConfig, type IMediaProviderCredentialRequirement, type IMediaProviderDefinition, type IMediaProviderOverrides, type IMessageTokenUsage, type IModelCapabilityDeviation, type IModelDefinition, type IModelEffortCapability, type IModelEffortOutcome, type IModelEffortResolution, type IModelFallbackNotice, type IModelJournalContext, type IModelPrice, type IModelRef, type IObjectParameterSchema, type IOpenAPIToolConfig, type IOrchestrationDelegation, type IOrchestrationEventData, type IOrchestrationRunResult, type IOrchestrationStep, type IOrchestrationStepResult, type IOutboundTraceContext, type IOwnerPathSegment, type IParallelOrchestrationSpec, type IParameterRule, type IParameterSchema, type IParameterValidationResult, type IPermissionEvaluationContext, type IPermissionLists, type IPermissionPatternProblem, type IPermissionPolicyContext, type IPermissionPolicyProjection, IPlatformShell, IPlatformShellResolutionRequest, type IPlugin, type IPluginConfig, type IPluginContext, type IPluginContract, type IPluginData, type IPluginErrorContext, type IPluginExecutionContext, type IPluginExecutionResult, type IPluginHooks, type IPluginOptions, type IPluginStats, type IProgressReportingTool, type IPromptHookDefinition, type IProviderCapabilities, type IProviderCapabilityTable, type IProviderCredentialRequirement, type IProviderDefinition, type IProviderDefinitionConfig, type IProviderEndpoint, type IProviderFailureClassification, IProviderFailureDetails, type IProviderFunctionCallingCapability, type IProviderMediaError, type IProviderModelCatalog, type IProviderModelCatalogEntry, type IProviderModelEffortTable, type IProviderNativeRawPayloadEvent, type IProviderNativeWebToolCapabilities, type IProviderNativeWebToolCapability, type IProviderNativeWebToolRequest, type IProviderOptions, type IProviderProbeResult, type IProviderProfileConfig, type IProviderProfileDefaults, type IProviderRequest, IProviderRuntimeConfig, type IProviderSetupHelpLink, type IProviderSetupStepDefinition, type IProviderSpecificOptions, type IProviderStructuredOutputCapability, type IRawProviderResponse, type IReadOnlyCommandContext, type IRecoverableExecutionJournal, type IRegistryOwnedLifecycle, type IRegistryTransactionError, type IRegistryTransactionStep, type IRemoteExecutorConfig, type IResponseFormatConfig, type IResumeExecutionOptions, type IResumeToolCallsOptions, type IResumeToolCallsResult, type IRunOptions, type IRunTraceContext, type ISchemaClosureChange, type ISchemaClosureOptions, type ISchemaConversionOptions, type ISequentialOrchestrationSpec, type ISession, type ISessionUsageTotals, ISimpleValidationResult, type ISpanCompletionEventData, type ISpinner, type IStats, type IStreamExecutionRequest, type IStreamingChunk, type IStructuredOutputResolutionInput, type IStructuredOutputSpec, type ISubprocessTraceEnv, type ISystemMessage, type ITemplateApplicationResult, type ITerminalOutput, type ITextMessagePart, type ITokenUsage, type ITokenUsageWithCacheRead, type ITool, type IToolActionIdentity, type IToolCall, type IToolContinuation, type IToolContinuationPrompt, type IToolContract, type IToolEventData, type IToolExecutionContext, type IToolExecutionRequest, type IToolExecutionResult, type IToolExecutionStep, type IToolFactory, type IToolManager, type IToolMessage, type IToolPermissionArgument, type IToolPermissionProfile, type IToolRegistry, type IToolResult, type IToolResultAdmissionOptions, type IToolResultSpillStore, type IToolSchema, type IToolSchemaProjection, type IToolSchemaProjectionChange, type IToolSchemaProjectionProfile, type IToolWaitRequest, type IToolWaitResponse, type IToolWaitState, type IToolWithEventService, type IUniversalObjectValue, type IUriImageInputSource, type IUriImageMessagePart, type IUserInteraction, type IUserMessage, IUtilLogEntry, type IVerifiedProviderCallUsage, type IVideoGenerationProvider, type IVideoGenerationRequest, type IVideoJobAccepted, type IVideoJobSnapshot, type IZodParseResult, type IZodSchema, type IZodSchemaDef, InMemoryEventEmitterMetrics, LocalExecutor, MAX_TOOL_RESULT_CHARS, MODEL_EFFORT_VALUES, MODEL_PRICES, MessageConverter, ModelNotAvailableError, NetworkError, ORCHESTRATION_EVENTS, ORCHESTRATION_EVENT_PREFIX, ObservableEventService, PARAMETER_SCHEMA_KEYWORDS, PERMISSIVE_TOOL_SCHEMA_PROFILE, PROTECTED_DIRECTORY_NAMES, PROTECTED_FILE_NAMES, PROVIDER_CALL_EVENTS, PROVIDER_FALLBACK_EVENTS, PluginCategory, PluginError, PluginPriority, ProviderError, RISK_CLASS_POLICY, RateLimitError, Robota, RobotaError, SPAN_EVENTS, SPAN_EVENT_PREFIX, STRICT_TOOL_SCHEMA_PROFILE, SameToolInputLoopError, SilentLogger, StorageError, StructuredEventService, StructuredOutputError, TASK_EVENTS, TASK_EVENT_PREFIX, type TActionResponse, type TArgumentKind, type TBackgroundPermissionPolicy, TComplexConfigValue, TConfigData, TConfigValue, TContextData, type TConversationContextMetadata, type TEnvResolver, TErrorContextData, TErrorExternalInput, type TEventEmitterListener, type TEventExtensionValue, type TEventListener, type TEventLoggerData, type TEventName, type TEventUniversalValue, type TExecutionEventCallback, type TExecutionEventData, type TExecutionEventName, type TExecutionJournalRecord, type TExecutionRecoveryErrorCode, type TExecutorStreamEvent, type TGuardrail, type THookDefinition, type THookEvent, type THookOutcome, type THooksConfig, type TImageInputSource, type TJSONSchemaEnum, type TJSONSchemaKind, type TJournalModelOptions, TLoggerData, type TManagerToolParameters, type TMatchDirection, TMessageConverterRegistry, TMessageFormatConverter, type TMessageState, TMetadata, TMetadataValue, type TModelEffort, type TModelEffortDisposition, type TModelEffortNativeControl, type TModelEffortOutcomeCallback, type TModelEffortProviderDispatch, type TModelEffortSelection, type TModelFallbackCallback, TOOL_BODY_EVENTS, TOOL_EVENTS, TOOL_EVENT_PREFIX, TOOL_PERMISSION_EVENTS, TOOL_SCHEMA_PROJECTION_MAX_DEPTH, TOOL_SCHEMA_PROJECTION_MAX_NODES, TOOL_SEARCH_TOOL_NAME, type TOrchestrationEvent, type TOrchestrationPrimitive, type TOutputRetention, type TParameterDefaultValue, type TPermissionDecision, type TPermissionMode, type TPrimitiveValue, type TProviderConfigValue, type TProviderCredentialField, type TProviderFailureReason, TProviderLoggingData, type TProviderMediaResult, TProviderMessage, type TProviderModelCapability, type TProviderModelCatalogStatus, type TProviderModelLifecycle, type TProviderNativeRawPayload, type TProviderNativeRawPayloadCallback, type TProviderNativeRawPayloadKind, type TProviderOptionValueBase, type TProviderSetupField, type TProviderSetupHelpLinkKind, type TProviderUsageProvenance, TRUST_TO_MODE, type TResolveInWorkspace, type TResponseMetadata, type TRoleModelMap, type TSessionEndReason, TShellKind, type TSpanEvent, type TStructuredOutputMechanism, type TStructuredOutputProvenance, type TStructuredOutputSchema, type TStructuredOutputValidation, type TSubprocessTraceClass, type TTextDeltaCallback, type TTimerId, type TToolArgs, type TToolChoice, type TToolEffectAdmission, type TToolExecutionFunction, type TToolExecutionParameters, type TToolExecutor, type TToolMetadata, TToolParameters, type TToolProgressCallback, type TToolResultAdmissionErrorCode, type TToolRiskClass, type TToolSchemaProjectionOutcome, type TToolSchemaProjectionProfileBase, type TToolSearchMode, type TToolSearchSetting, type TTrustLevel, type TUniversalArrayValue, type TUniversalMessage, type TUniversalMessageMetadata, type TUniversalMessagePart, type TUniversalMessageRole, type TUniversalValue, type TUserEvent, TUtilLogLevel, ToolExecutionError, ToolRegistry, ToolResultAdmissionError, TypeUtils, UNCLASSIFIED_TOOL_FALLBACK, USER_EVENTS, USER_EVENT_PREFIX, UnsupportedShellError, ValidationError, Validator, admitToolResult, allowRulesForAutoMode, applyPresetToolLists, assertProviderNativeWebToolsAvailable, assertResidentToolRemains, bindEventServiceOwner, bindWithOwnerPath, buildTraceparent, calculateModelCost, callJournaledProvider, chatEntryToMessage, classifyProviderFailure, clearRegisteredToolProfiles, closeObjectSchemas, collectAssistantUsageMetadata, composeEventName, confirmAction, createAssistantMessage, createBoundedOutput, createDefaultProviderCapabilities, createExecutionProxy, createImageProviderFromDefinition, createLogger, createModelEffortOutcome, createProviderFromConfig, createRecordEnvResolver, createSystemMessage, createToolMessage, createUserMessage, createVideoProviderFromDefinition, decodeHookVerdict, estimateBlendedCostPer1000, estimateContextTokensFromMessages, estimateSerializedContextTokens, estimateToolSchemaTokens, evaluatePermission, extractEnumValues, findInvalidPermissionPatterns, findMediaProviderDefinition, findModelDefinition, findPermissionPatternWarnings, findProviderDefinition, formatEnvReference, formatSupportedProviderTypes, formatTokenCount, generateSpanId, getGlobalLogLevel, getGlobalLoggerSink, getMessagesForAPI, getModelContextWindow, getModelMaxOutput, getModelName, getProviderCapabilities, getProviderCredentialRequirement, getSchemaTypeName, getToolEstimatedDuration, getToolExecutionSteps, getToolPermissionProfile, hasUsableSecretReference, hasValidationConstraints, hashToolSchema, isAbortFailure, isAssistantMessage, isBroadExecutionAllowRule, isChatEntry, isConfirmed, isDefaultEventService, isEnforcing, isEnvReference, isExecutionControlError, isImageGenerationProvider, isMediaProviderDefinition, isMintedSpanId, isModelEffort, isProgressReportingTool, isProtectedPath, isReadOnlyCommandLine, isRegistryTransactionError, isSystemMessage, isToolDeniedOutright, isToolMessage, isUserMessage, isVideoGenerationProvider, lifecycleOf, logger, lookupModelPrice, matchesAnyPattern, messageToHistoryEntry, modelDeclaresCapability, multiSelectAction, normalizeProviderConfig, normalizeStructuredOutput, outboundTraceContextFor, parseParameterRule, parseStructuredResponseText, peerDriverOf, printablePeerDriver, processEnvResolver, projectPermissionPolicy, projectToolSchema, providerCallSpanId, readModelFallbackNotice, readProviderFailureDetails, readTokenUsageFromMessage, readTokenUsageFromMetadata, registerModelMetadata, registerToolPermissionProfile, removesCriticalPath, requiresFreshApproval, resolveEnvReference, resolveMediaProviderConfig, resolveModelCapabilities, resolveModelCapability, resolveModelEffort, resolvePlatformShell, resolveStructuredOutputCapability, runHooks, runRegistryTransaction, scrubSecrets, selectAction, setGlobalLogLevel, setGlobalLoggerSink, setToolProgressCallback, shellArgumentForDisplay, spanIdFromMintedId, splitCommandSegments, startPeriodicTask, stopPeriodicTask, subprocessTraceEnvironment, sumHistoryUsage, sumMessagesUsage, textAction, toProviderError, toolNameMatches, toolNamesToPatterns, toolTraceContextFor, traceEnvFor, traceHeadersFor, validateAgainstJsonSchema, validateAgentConfig, validateApiKey, validateModelName, validatePermissionPattern, validateProviderName, validateUserInput, verifiedProviderCallUsage, wasToolResultAdmitted, withEventEmission, zodToJsonSchema };
 //# sourceMappingURL=index.d.ts.map