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

package/dist/node/{index-D4iJ5IsN.d.ts → index-DQrmrFn9.d.ts}

@@ -1,4 +1,4 @@
-import { C as IModelEffortResolution, F as IUniversalObjectValue, I as TPrimitiveValue, L as TUniversalArrayValue, R as TUniversalValue, S as IModelEffortOutcome, _ as IOutboundTraceContext, a as IHookErrorOutcome, b as TSubprocessTraceClass, c as IHookTypeExecutor, d as TGuardrail, f as THookDefinition, h as THooksConfig, j as TModelEffortSelection, k as TModelEffortOutcomeCallback, m as THookOutcome, p as THookEvent, s as IHookInput, v as IRunTraceContext, w as IProviderModelEffortTable, y as ISubprocessTraceEnv } from "./types-gNrckgFE.js";
+import { C as IModelEffortResolution, F as IUniversalObjectValue, I as TPrimitiveValue, L as TUniversalArrayValue, R as TUniversalValue, S as IModelEffortOutcome, _ as IOutboundTraceContext, a as IHookErrorOutcome, b as TSubprocessTraceClass, c as IHookTypeExecutor, d as TGuardrail, f as THookDefinition, h as THooksConfig, j as TModelEffortSelection, k as TModelEffortOutcomeCallback, m as THookOutcome, p as THookEvent, s as IHookInput, v as IRunTraceContext, w as IProviderModelEffortTable, y as ISubprocessTraceEnv } from "./types-Ge2XB-y-.js";
 import { TypeOf, ZodType } from "zod";
 //#region src/interfaces/types.d.ts
 /**
@@ -38,146 +38,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
@@ -529,10 +420,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
@@ -569,15 +464,50 @@ declare class SameToolInputLoopError extends RobotaError {
   readonly recoverable = true;
   constructor(toolName: string, callCount: number, maxSameToolInputs: number, context?: TErrorContextData);
 }
+/**
+ * A turn ended with neither a tool result nor a final text response while `allowToolOnlyCompletion`
+ * was set.
+ *
+ * `allowToolOnlyCompletion` only WIDENS what counts as a valid finish (a tool call alone, with no
+ * final text after it); it never narrows the ordinary case. Without the flag, a round that produces
+ * neither is recovered by one more provider call asking for a summary (`forceSummaryCall`). Setting
+ * the flag is what turns that rescue off — a decision agent wants exactly one provider call, never a
+ * follow-up — so a round that produces neither has nothing left to recover it. That is a genuinely
+ * unanswered turn, not the internal `[STRICT-POLICY]` result-shape violation an actually malformed
+ * execution result trips; a caller must be able to catch this by type instead of parsing that message.
+ *
+ * `recoverable` is TRUE: like `SameToolInputLoopError`, this is a property of this turn's prompt and
+ * model response, not of the system, and a caller that varies either can reasonably try again.
+ */
+declare class EmptyCompletionError extends RobotaError {
+  readonly round: number;
+  readonly code = "EMPTY_COMPLETION";
+  readonly category: "provider";
+  readonly recoverable = true;
+  constructor(round: number, context?: TErrorContextData);
+}
 /**
  * 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
@@ -618,6 +548,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 {
@@ -637,9 +586,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;
 /**
@@ -1146,227 +1101,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
@@ -1404,654 +1438,888 @@ 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>;
+//#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;
 /**
- * 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
+ * Tool metadata structure - specific type definition
+ */
+type TToolMetadata = Record<string, string | number | boolean | string[] | number[] | boolean[] | TToolParameters>;
 /**
- * @fileoverview Event service interface definitions.
+ * 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/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;
 }
-//#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>;
+/** 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
+   * ended in tool results (consumers read the outcome from those results), and rejects with
+   * `EmptyCompletionError` when it produced neither text nor a tool result.
    */
-  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: {
+  /** @deprecated Not emitted by a run; a run emits `AGENT_EXECUTION_START`. */
+  readonly EXECUTION_START: "execution.start";
+  /** @deprecated Not emitted by a run; a run emits `AGENT_EXECUTION_COMPLETE`. */
+  readonly EXECUTION_COMPLETE: "execution.complete";
+  /** @deprecated Not emitted by a run; a run emits `AGENT_EXECUTION_ERROR`. */
+  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
@@ -2117,6 +2385,8 @@ interface IPluginExecutionResult {
  * above, which lives at this abstracts layer.
  */
 interface IPluginContext {
+  toolData?: IToolExecutionContext;
+  toolResult?: IToolExecutionResult;
   input?: string;
   response?: string;
   messages?: TUniversalMessage[];
@@ -2126,7 +2396,10 @@ interface IPluginContext {
   executionContext?: TContextData;
   /** PLG-020 (issue #2460): the run's result, for `afterExecution` / `afterConversation` / `afterToolExecution`. */
   executionResult?: IPluginExecutionResult;
-  /** PLG-020 (issue #2460): the message just appended to the conversation, for `onMessageAdded`. */
+  /**
+   * The message just appended to the conversation, for `onMessageAdded`, or the streamed text
+   * chunk, for `onStreamingChunk`.
+   */
   message?: TUniversalMessage;
 }
 /** Error context for plugin error handling */
@@ -2206,7 +2479,7 @@ interface IPluginHooks {
   afterExecution?(context: IPluginExecutionContext, result: IPluginExecutionResult): Promise<void> | void;
   beforeConversation?(context: IPluginExecutionContext): Promise<void> | void;
   afterConversation?(context: IPluginExecutionContext, result: IPluginExecutionResult): Promise<void> | void;
-  beforeToolCall?(toolName: string, parameters: TToolParameters): Promise<void> | void;
+  beforeToolCall?(toolName: string, parameters: TToolParameters, context?: IToolExecutionContext): Promise<void> | void;
   beforeToolExecution?(context: IPluginExecutionContext, toolData: IToolExecutionContext): Promise<void> | void;
   afterToolCall?(toolName: string, parameters: TToolParameters, result: IToolExecutionResult): Promise<void> | void;
   afterToolExecution?(context: IPluginExecutionContext, toolResults: IPluginExecutionResult): Promise<void> | void;
@@ -2385,6 +2658,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;
@@ -2716,7 +2994,7 @@ interface IProviderDefinition {
    * LLM nodes' single `COST_PER_TOKEN_USD` scalar. The correct long-term home is the per-model
    * {@link IProviderModelCatalogEntry.costPerInputToken}/`costPerOutputToken`; this flat scalar is a
    * fidelity-preserving interim used only while model catalogs are `status:'unavailable'` (no per-model
-   * entries to attach cost to). Consumed by the collapsed `llm-text` node's `maxCostUsd` estimation. Absent
+   * entries to attach cost to). Consumed by the collapsed `llm-text` node's cost estimate. Absent
    * means cost is unknown for this provider and estimators must degrade explicitly.
    */
   costPerTokenUsd?: number;
@@ -2995,6 +3273,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
@@ -3384,14 +3664,9 @@ type TExecutorStreamEvent = IExecutorStreamMessageEvent | IExecutorStreamTermina
 /**
  * Interface for executing AI provider operations
  *
- * Executors abstract the execution mechanism, allowing providers to work
- * with either local API calls or remote server calls transparently.
- *
- * Implementation patterns:
- * - LocalExecutor: Direct API calls using provider SDKs
- * - RemoteExecutor: HTTP/WebSocket calls to remote server
- * - CacheExecutor: Cached responses with explicit error propagation
- * - HybridExecutor: Conditional local/remote execution
+ * Executors abstract the execution mechanism, so a provider can call its API directly or hand the
+ * call to something else (a server of your own, a cache). `LocalExecutor` is the in-process one;
+ * any other is yours to implement.
  */
 interface IExecutor {
   /**
@@ -3469,7 +3744,10 @@ interface ILocalExecutorConfig {
   enableLogging?: boolean;
 }
 /**
- * Configuration options for remote executor
+ * Configuration options for a remote executor.
+ *
+ * @deprecated Robota ships no remote executor, so nothing reads this type. It stays exported only
+ * so existing imports keep compiling; describe your own executor's options instead.
  */
 interface IRemoteExecutorConfig {
   /** Remote server URL */
@@ -4017,7 +4295,7 @@ declare abstract class AbstractPlugin<TOptions extends IPluginOptions = IPluginO
   afterExecution?(context: IPluginExecutionContext, result: IPluginExecutionResult): Promise<void>;
   beforeConversation?(context: IPluginExecutionContext): Promise<void>;
   afterConversation?(context: IPluginExecutionContext, result: IPluginExecutionResult): Promise<void>;
-  beforeToolCall?(toolName: string, parameters: TToolParameters): Promise<void>;
+  beforeToolCall?(toolName: string, parameters: TToolParameters, context?: IToolExecutionContext): Promise<void>;
   beforeToolExecution?(context: IPluginExecutionContext, toolData: IToolExecutionContext): Promise<void>;
   afterToolCall?(toolName: string, parameters: TToolParameters, result: IToolExecutionResult): Promise<void>;
   afterToolExecution?(context: IPluginExecutionContext, toolResults: IPluginExecutionResult): Promise<void>;
@@ -4319,6 +4597,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.
@@ -4426,6 +4733,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.
@@ -5356,6 +5666,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
@@ -5495,6 +5806,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 —
@@ -5875,6 +6196,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.
@@ -6109,9 +6443,9 @@ interface IOrchestrationStepResult {
   output: string;
   /**
    * Optional token usage of the step's subagent run (the {@link ITokenUsage} SSOT triple;
-   * TYPE-003). Present only when the underlying runner/manager surfaces usage through its
-   * result — the default `SubagentManager.wait` does not yet thread it, so this is
-   * `undefined` there until that port is extended.
+   * TYPE-003). Present when the underlying runner reported it — `SubagentManager.wait` already
+   * threads a completed job's `usage` straight through its result; this is `undefined` only when
+   * the runner itself never reported any.
    */
   usage?: ITokenUsage;
 }
@@ -6963,5 +7297,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 { parseParameterRule as $, IAgent as $a, IProviderCapabilityTable as $c, confirmAction as $i, IMediaProviderOverrides as $n, TASK_EVENTS as $o, IToolSchemaProjectionChange as $r, IProviderRequest as $s, isRegistryTransactionError as $t, allowRulesForAutoMode as A, isVideoGenerationProvider as Aa, readProviderFailureDetails as Ac, ILocalExecutorConfig as Ai, IUserInteraction as Al, IEventEmitterMetrics as An, PluginCategory as Ao, stopPeriodicTask as Ar, IDeferredToolCatalog as As, IHandoffOrchestrationSpec as At, IPermissionPolicyProjection as B, IProviderProbeResult as Ba, ProviderError as Bc, IToolExecutionRequest as Bi, TContextData as Bl, hasUsableSecretReference as Bn, TToolMetadata as Bo, MessageConverter as Br, TStructuredOutputValidation as Bs, AGENT_EVENTS as Bt, IContextTokenEstimate as C, IVideoGenerationProvider as Ca, assertProviderNativeWebToolsAvailable as Cc, IEventHistoryRecord as Ci, isSystemMessage as Cl, DEFERRED_WITHOUT_LOADER_MESSAGE as Cn, IPluginData as Co, traceHeadersFor as Cr, TEventUniversalValue as Cs, createExecutionProxy as Ct, estimateToolSchemaTokens as D, TImageInputSource as Da, IProviderFailureClassification as Dc, IExecutorChatResult as Di, IActionDefault as Dl, EventEmitterPlugin as Dn, IPluginHooks as Do, UnsupportedShellError as Dr, TEventEmitterListener as Ds, ORCHESTRATION_EVENT_PREFIX as Dt, estimateSerializedContextTokens as E, IVideoJobSnapshot as Ea, TModelFallbackCallback as Ec, IExecutor as Ei, messageToHistoryEntry as El, ToolRegistry as En, IPluginExecutionResult as Eo, TShellKind as Er, IEventEmitterPlugin as Es, ORCHESTRATION_EVENTS as Et, IPermissionPatternProblem as F, IProviderDefinition as Fa, ConfigurationError as Fc, IConversationContext as Fi, ICacheStats as Fl, IBoundedOutputOptions as Fn, IToolExecutionContext as Fo, validateAgentConfig as Fr, TExecutionEventCallback as Fs, IOrchestrationStep as Ft, IToolPermissionArgument as G, TProviderCredentialField as Ga, StructuredOutputError as Gc, IToolExecutionStep as Gi, TypeUtils as Gl, ConversationHistory as Gn, SPAN_EVENT_PREFIX as Go, AbstractTool as Gr, IZodParseResult as Gs, IAssistantUsageMetadata as Gt, IParameterRule as H, IProviderProfileDefaults as Ha, RobotaError as Hc, TResponseMetadata as Hi, TMetadata as Hl, resolveEnvReference as Hn, PROVIDER_CALL_EVENTS as Ho, TMessageFormatConverter as Hr, parseStructuredResponseText as Hs, peerDriverOf as Ht, findInvalidPermissionPatterns as I, IProviderDefinitionConfig as Ia, IProviderFailureDetails as Ic, IConversationResponse as Ii, ICacheStorage as Il, TOutputRetention as In, IToolExecutionResult as Io, validateApiKey as Ir, TExecutionEventData as Is, IOrchestrationStepResult as It, clearRegisteredToolProfiles as J, TProviderSetupField as Ja, ToolExecutionError as Jc, getToolExecutionSteps as Ji, createToolMessage as Jn, TSpanEvent as Jo, AbstractAIProvider as Jr, IResponseFormatConfig as Js, sumHistoryUsage as Jt, IToolPermissionProfile as K, TProviderModelCatalogStatus as Ka, TErrorContextData as Kc, TToolProgressCallback as Ki, createAssistantMessage as Kn, TOOL_BODY_EVENTS as Ko, AbstractExecutor as Kr, IZodSchema as Ks, ISessionUsageTotals as Kt, findPermissionPatternWarnings as L, IProviderEndpoint as La, ModelNotAvailableError as Lc, IConversationService as Li, TComplexConfigValue as Ll, createBoundedOutput as Ln, IToolRegistry as Lo, validateModelName as Lr, IJsonSchemaOutput as Ls, IParallelOrchestrationSpec as Lt, splitCommandSegments as M, TStructuredOutputMechanism as Ma, AuthenticationError as Mc, IStreamExecutionRequest as Mi, ICacheEntry as Ml, InMemoryEventEmitterMetrics as Mn, IFunctionTool as Mo, ErrorUtils as Mr, TToolSearchMode as Ms, IOrchestrationDelegation as Mt, applyPresetToolLists as N, TStructuredOutputProvenance as Na, CacheIntegrityError as Nc, TExecutorStreamEvent as Ni, ICacheKey as Nl, shellArgumentForDisplay as Nn, IParameterValidationResult as No, ISimpleValidationResult as Nr, TToolSearchSetting as Ns, IOrchestrationEventData as Nt, IContextTokenUsage as O, TProviderMediaResult as Oa, TProviderFailureReason as Oc, IExecutorStreamMessageEvent as Oi, IActionOption as Ol, IEventEmitterHierarchicalEventData as On, IPluginOptions as Oo, resolvePlatformShell as Or, TEventName as Os, TOrchestrationEvent as Ot, toolNamesToPatterns as P, IProviderCredentialRequirement as Pa, CircuitBreakerOpenError as Pc, IContextOptions as Pi, ICacheOptions as Pl, IBoundedOutput as Pn, ITool as Po, Validator as Pr, IRunOptions as Ps, IOrchestrationRunResult as Pt, matchesAnyPattern as Q, getProviderCredentialRequirement as Qa, IModelCapabilityDeviation as Qc, CONFIRM_YES as Qi, normalizeProviderConfig as Qn, USER_EVENT_PREFIX as Qo, IToolSchemaProjection as Qr, IProviderOptions as Qs, IRegistryTransactionStep as Qt, validatePermissionPattern as R, IProviderModelCatalog as Ra, NetworkError as Rc, IConversationServiceOptions as Ri, TConfigData as Rl, ENV_REFERENCE_PREFIX as Rn, IToolResult as Ro, validateProviderName as Rr, IStructuredOutputSpec as Rs, ISequentialOrchestrationSpec as Rt, CONTEXT_ESTIMATE_CHARS_PER_TOKEN as S, IUriImageInputSource as Sa, IProviderNativeWebToolRequest as Sc, IEventHistoryModule as Si, isChatEntry as Sl, TOOL_EVENT_PREFIX as Sn, IPluginContract as So, traceEnvFor as Sr, TEventLoggerData as Ss, ExecutionProxy as St, estimateContextTokensFromMessages as T, IVideoJobAccepted as Ta, IModelFallbackNotice as Tc, IChatExecutionRequest as Ti, isUserMessage as Tl, FunctionTool as Tn, IPluginExecutionContext as To, IPlatformShellResolutionRequest as Tr, IEventEmitterEventData as Ts, IExecutionProxyConfig as Tt, IPermissionEvaluationContext as U, IProviderSetupHelpLink as Ua, SameToolInputLoopError as Uc, TToolExecutionParameters as Ui, TMetadataValue as Ul, IAIProviderInstance as Un, PROVIDER_FALLBACK_EVENTS as Uo, TProviderMessage as Ur, validateAgainstJsonSchema as Us, printablePeerDriver as Ut, projectPermissionPolicy as V, IProviderProfileConfig as Va, RateLimitError as Vc, TConversationContextMetadata as Vi, TLoggerData as Vl, isEnvReference as Vn, ISpanCompletionEventData as Vo, TMessageConverterRegistry as Vr, normalizeStructuredOutput as Vs, AGENT_EVENT_PREFIX as Vt, IPermissionLists as W, IProviderSetupStepDefinition as Wa, StorageError as Wc, IProgressReportingTool as Wi, TToolParameters as Wl, LocalExecutor as Wn, SPAN_EVENTS as Wo, isAbortFailure as Wr, ISchemaConversionOptions as Ws, EventHistoryModule as Wt, getToolPermissionProfile as X, findProviderDefinition as Xa, IModelRef as Xc, setToolProgressCallback as Xi, ConversationStore as Xn, TUserEvent as Xo, IProviderRuntimeConfig as Xr, IChatOptions as Xs, IRegistryOwnedLifecycle as Xt, evaluatePermission as Y, TProviderSetupHelpLinkKind as Ya, ValidationError as Yc, isProgressReportingTool as Yi, createUserMessage as Yn, readModelFallbackNotice as Yo, IExecutorAwareProviderConfig as Yr, IAIProvider as Ys, sumMessagesUsage as Yt, isToolDeniedOutright as Z, formatSupportedProviderTypes as Za, TRoleModelMap as Zc, CONFIRM_NO as Zi, createProviderFromConfig as Zn, USER_EVENTS as Zo, TProviderLoggingData as Zr, IProviderNativeRawPayloadEvent as Zs, IRegistryTransactionError as Zt, getModelName as _, IImageGenerationRequest as _a, IProviderSpecificOptions as _c, IFileSystemAsync as _i, TUniversalMessagePart as _l, Robota as _n, setGlobalLogLevel as _o, outboundTraceContextFor as _r, IExecutionEventData as _s, TBackgroundPermissionPolicy as _t, IModelPrice as a, IToolFactory as aa, TProviderNativeRawPayloadCallback as ac, TOOL_SCHEMA_PROJECTION_MAX_NODES as ai, IBaseMessage as al, IAgentCreationStats as an, IToolWithEventService as ao, processEnvResolver as ar, StructuredEventService as as, PROTECTED_FILE_NAMES as at, readTokenUsageFromMessage as b, IMediaOutputRef as ba, IProviderNativeWebToolCapabilities as bc, ISpinner as bi, getMessagesForAPI as bl, EXECUTION_EVENT_PREFIX as bn, IPluginConfig as bo, subprocessTraceEnvironment as br, TEventExtensionValue as bs, TRUST_TO_MODE as bt, estimateBlendedCostPer1000 as c, TManagerToolParameters as ca, TTextDeltaCallback as cc, hashToolSchema as ci, ISystemMessage as cl, DEFAULT_TOOL_RESULT_HARD_CHARS as cn, ILogger as co, extractEnumValues as cr, composeEventName as cs, RISK_CLASS_POLICY as ct, DEFAULT_MAX_OUTPUT as d, IMediaProviderDefinition as da, IObjectParameterSchema as dc, IManagerLifecycleOptions as di, IToolMessage as dl, IToolResultSpillStore as dn, SilentLogger as do, ISchemaClosureChange as dr, IAgentEventData as ds, TArgumentKind as dt, isConfirmed as ea, IRawProviderResponse as ec, IToolSchemaProjectionProfile as ei, modelDeclaresCapability as el, lifecycleOf as en, IAgentConfig as eo, createImageProviderFromDefinition as er, TASK_EVENT_PREFIX as es, registerToolPermissionProfile as et, IModelDefinition as f, findMediaProviderDefinition as fa, IParameterSchema as fc, AbstractAgent as fi, IUriImageMessagePart as fl, MAX_TOOL_RESULT_CHARS as fn, TUtilLogLevel as fo, ISchemaClosureOptions as fr, IBaseEventData as fs, TMatchDirection as ft, getModelMaxOutput as g, IImageGenerationProvider as ga, TParameterDefaultValue as gc, IFileSystem as gi, TUniversalMessageMetadata as gl, wasToolResultAdmitted as gn, logger as go, isMintedSpanId as gr, IEventServiceOwnerBinding as gs, DEFAULT_BACKGROUND_PERMISSION_POLICY as gt, getModelContextWindow as h, IImageEditRequest as ha, TJSONSchemaKind as hc, IDirent as hi, TUniversalMessage as hl, admitToolResult as hn, getGlobalLoggerSink as ho, buildTraceparent as hr, IEventService as hs, isReadOnlyCommandLine as ht, runHooks as i, IOpenAPIToolConfig as ia, TProviderNativeRawPayload as ic, TOOL_SCHEMA_PROJECTION_MAX_DEPTH as ii, IAssistantMessage as il, ITemplateApplicationResult as in, IToolContract as io, createRecordEnvResolver as ir, ObservableEventService as is, PROTECTED_DIRECTORY_NAMES as it, isBroadExecutionAllowRule as j, IProviderStructuredOutputCapability as ja, toProviderError as jc, IRemoteExecutorConfig as ji, TActionResponse as jl, IEventEmitterMetricsSnapshot as jn, PluginPriority as jo, TTimerId as jr, TOOL_SEARCH_TOOL_NAME as js, IHierarchicalOrchestrationSpec as jt, IContextWindowState as k, isImageGenerationProvider as ka, classifyProviderFailure as kc, IExecutorStreamTerminalEvent as ki, IActionRequest as kl, IEventEmitterPluginOptions as kn, IPluginStats as ko, startPeriodicTask as kr, TExecutionEventName as ks, IGroupChatOrchestrationSpec as kt, lookupModelPrice as l, IMediaProviderConfig as la, TToolChoice as lc, projectToolSchema as li, ITextMessagePart as ll, DEFAULT_TOOL_RESULT_WARNING_CHARS as ln, ILoggerOptions as lo, getSchemaTypeName as lr, generateSpanId as ls, TToolRiskClass as lt, formatTokenCount as m, IImageComposeRequest as ma, TJSONSchemaEnum as mc, ICredentialStore as mi, TMessageState as ml, ToolResultAdmissionError as mn, getGlobalLogLevel as mo, zodToJsonSchema as mr, IEventObjectValue as ms, TResolveInWorkspace as mt, decodeHookVerdict as n, selectAction as na, ITokenUsageWithCacheRead as nc, PERMISSIVE_TOOL_SCHEMA_PROFILE as ni, resolveModelCapability as nl, AgentFactory as nn, IAbstractTool as no, resolveMediaProviderConfig as nr, DEFAULT_ABSTRACT_EVENT_SERVICE as ns, toolNameMatches as nt, MODEL_PRICES as o, IAIProviderManager as oa, TProviderNativeRawPayloadKind as oc, TToolSchemaProjectionOutcome as oi, IHistoryEntry as ol, IAgentFactoryOptions as on, TToolExecutionFunction as oo, IStructuredOutputResolutionInput as or, bindEventServiceOwner as os, isProtectedPath as ot, findModelDefinition as p, isMediaProviderDefinition as pa, IToolSchema as pc, ICredentialKey as pi, IUserMessage as pl, TToolResultAdmissionErrorCode as pn, createLogger as po, closeObjectSchemas as pr, IEventContext as ps, IReadOnlyCommandContext as pt, TToolArgs as q, TProviderModelLifecycle as qa, TErrorExternalInput as qc, getToolEstimatedDuration as qi, createSystemMessage as qn, TOOL_PERMISSION_EVENTS as qo, AbstractPlugin as qr, IZodSchemaDef as qs, collectAssistantUsageMetadata as qt, GuardrailExecutor as r, textAction as ra, TProviderConfigValue as rc, STRICT_TOOL_SCHEMA_PROFILE as ri, TProviderModelCapability as rl, AgentTemplates as rn, IAbstractToolOptions as ro, TEnvResolver as rr, DefaultEventService as rs, ICriticalPathContext as rt, calculateModelCost as s, IToolManager as sa, TProviderOptionValueBase as sc, TToolSchemaProjectionProfileBase as si, IInlineImageMessagePart as sl, IAgentLifecycleEvents as sn, ConsoleLogger as so, resolveStructuredOutputCapability as sr, bindWithOwnerPath as ss, removesCriticalPath as st, isEnforcing as t, multiSelectAction as ta, ITokenUsage as tc, PARAMETER_SCHEMA_KEYWORDS as ti, resolveModelCapabilities as tl, runRegistryTransaction as tn, IAgentTemplate as to, createVideoProviderFromDefinition as tr, AbstractEventService as ts, requiresFreshApproval as tt, DEFAULT_CONTEXT_WINDOW as u, IMediaProviderCredentialRequirement as ua, getProviderCapabilities as uc, AbstractManager as ui, IToolCall as ul, IToolResultAdmissionOptions as un, IUtilLogEntry as uo, hasValidationConstraints as ur, isDefaultEventService as us, UNCLASSIFIED_TOOL_FALLBACK as ut, registerModelMetadata as v, IImageGenerationResult as va, IProviderCapabilities as vc, IStats as vi, TUniversalMessageRole as vl, IDestroyResult as vn, setGlobalLoggerSink as vo, providerCallSpanId as vr, IOwnerPathSegment as vs, TPermissionDecision$1 as vt, IContextTokenEstimateOptions as w, IVideoGenerationRequest as wa, createDefaultProviderCapabilities as wc, IEventHistorySnapshot as wi, isToolMessage as wl, assertResidentToolRemains as wn, IPluginErrorContext as wo, IPlatformShell as wr, EVENT_EMITTER_EVENTS as ws, withEventEmission as wt, readTokenUsageFromMetadata as x, IProviderMediaError as xa, IProviderNativeWebToolCapability as xc, ITerminalOutput as xi, isAssistantMessage as xl, TOOL_EVENTS as xn, IPluginContext as xo, toolTraceContextFor as xr, TEventListener as xs, TTrustLevel as xt, IMessageTokenUsage as y, IInlineImageInputSource as ya, IProviderFunctionCallingCapability as yc, ISession as yi, chatEntryToMessage as yl, EXECUTION_EVENTS as yn, IPlugin as yo, spanIdFromMintedId as yr, IToolEventData as ys, TPermissionMode as yt, IPermissionPolicyContext as z, IProviderModelCatalogEntry as za, PluginError as zc, IStreamingChunk as zi, TConfigValue as zl, formatEnvReference as zn, TToolExecutor as zo, validateUserInput as zr, TStructuredOutputSchema as zs, TOrchestrationPrimitive as zt };
-//# sourceMappingURL=index-D4iJ5IsN.d.ts.map
+export { parseParameterRule as $, IProviderSetupStepDefinition as $a, assertProviderNativeWebToolsAvailable as $c, IProgressReportingTool as $i, isAssistantMessage as $l, ConversationStore as $n, TStructuredOutputValidation as $o, isAbortFailure as $r, USER_EVENT_PREFIX as $s, IRegistryOwnedLifecycle as $t, allowRulesForAutoMode as A, IProviderMediaError as Aa, IRawProviderResponse as Ac, ITerminalOutput as Ai, IModelCapabilityDeviation as Al, EventEmitterPlugin as An, IPluginContext as Ao, TShellKind as Ar, TToolEffectAdmission as As, IHandoffOrchestrationSpec as At, IPermissionPolicyProjection as B, IProviderStructuredOutputCapability as Ba, getProviderCapabilities as Bc, IRemoteExecutorConfig as Bi, ISystemMessage as Bl, createBoundedOutput as Bn, PluginPriority as Bo, ExecutionJournalError as Br, IUserInteraction as Bs, AGENT_EVENTS as Bt, IContextTokenEstimate as C, IImageComposeRequest as Ca, TEventLoggerData as Cc, ICredentialStore as Ci, StructuredOutputError as Cl, EXECUTION_EVENT_PREFIX as Cn, getGlobalLogLevel as Co, spanIdFromMintedId as Cr, IFunctionTool as Cs, createExecutionProxy as Ct, estimateToolSchemaTokens as D, IImageGenerationResult as Da, IProviderNativeRawPayloadEvent as Dc, IStats as Di, ValidationError as Dl, assertResidentToolRemains as Dn, setGlobalLoggerSink as Do, traceHeadersFor as Dr, IToolExecutionResult as Ds, ORCHESTRATION_EVENT_PREFIX as Dt, estimateSerializedContextTokens as E, IImageGenerationRequest as Ea, IChatOptions as Ec, IFileSystemAsync as Ei, ToolExecutionError as El, DEFERRED_WITHOUT_LOADER_MESSAGE as En, setGlobalLogLevel as Eo, traceEnvFor as Er, IToolExecutionContext as Es, ORCHESTRATION_EVENTS as Et, IPermissionPatternProblem as F, IVideoJobSnapshot as Fa, TProviderNativeRawPayloadCallback as Fc, IExecutor as Fi, TProviderModelCapability as Fl, InMemoryEventEmitterMetrics as Fn, IPluginExecutionResult as Fo, TTimerId as Fr, TToolSearchMode as Fs, IOrchestrationStep as Ft, IToolPermissionArgument as G, IProviderDefinitionConfig as Ga, TJSONSchemaKind as Gc, IConversationResponse as Gi, IUserMessage as Gl, resolveEnvReference as Gn, TEventName as Go, validateApiKey as Gr, SPAN_EVENTS as Gs, IAssistantUsageMetadata as Gt, IParameterRule as H, TStructuredOutputProvenance as Ha, IParameterSchema as Hc, TExecutorStreamEvent as Hi, IToolCall as Hl, formatEnvReference as Hn, IEventEmitterEventData as Ho, ISimpleValidationResult as Hr, ISpanCompletionEventData as Hs, peerDriverOf as Ht, findInvalidPermissionPatterns as I, TImageInputSource as Ia, TProviderNativeRawPayloadKind as Ic, IExecutorChatResult as Ii, IAssistantMessage as Il, shellArgumentForDisplay as In, IPluginHooks as Io, isExecutionControlError as Ir, TToolSearchSetting as Is, IOrchestrationStepResult as It, clearRegisteredToolProfiles as J, IProviderModelCatalogEntry as Ja, IProviderCapabilities as Jc, IStreamingChunk as Ji, TUniversalMessageMetadata as Jl, ConversationHistory as Jn, TExecutionEventCallback as Jo, validateUserInput as Jr, TOOL_PERMISSION_EVENTS as Js, sumHistoryUsage as Jt, IToolPermissionProfile as K, IProviderEndpoint as Ka, TParameterDefaultValue as Kc, IConversationService as Ki, TMessageState as Kl, IAIProviderInstance as Kn, TExecutionEventName as Ko, validateModelName as Kr, SPAN_EVENT_PREFIX as Ks, ISessionUsageTotals as Kt, findPermissionPatternWarnings as L, TProviderMediaResult as La, TProviderOptionValueBase as Lc, IExecutorStreamMessageEvent as Li, IBaseMessage as Ll, IBoundedOutput as Ln, IPluginOptions as Lo, ExecutionRecoveryError as Lr, IActionDefault as Ls, IParallelOrchestrationSpec as Lt, splitCommandSegments as M, IVideoGenerationProvider as Ma, ITokenUsageWithCacheRead as Mc, IEventHistoryRecord as Mi, modelDeclaresCapability as Ml, IEventEmitterPluginOptions as Mn, IPluginData as Mo, resolvePlatformShell as Mr, TToolMetadata as Ms, IOrchestrationDelegation as Mt, applyPresetToolLists as N, IVideoGenerationRequest as Na, TProviderConfigValue as Nc, IEventHistorySnapshot as Ni, resolveModelCapabilities as Nl, IEventEmitterMetrics as Nn, IPluginErrorContext as No, startPeriodicTask as Nr, IDeferredToolCatalog as Ns, IOrchestrationEventData as Nt, IContextTokenUsage as O, IInlineImageInputSource as Oa, IProviderOptions as Oc, ISession as Oi, IModelRef as Ol, FunctionTool as On, IPlugin as Oo, IPlatformShell as Or, IToolRegistry as Os, TOrchestrationEvent as Ot, toolNamesToPatterns as P, IVideoJobAccepted as Pa, TProviderNativeRawPayload as Pc, IChatExecutionRequest as Pi, resolveModelCapability as Pl, IEventEmitterMetricsSnapshot as Pn, IPluginExecutionContext as Po, stopPeriodicTask as Pr, TOOL_SEARCH_TOOL_NAME as Ps, IOrchestrationRunResult as Pt, matchesAnyPattern as Q, IProviderSetupHelpLink as Qa, IProviderNativeWebToolRequest as Qc, TToolExecutionParameters as Qi, getMessagesForAPI as Ql, createUserMessage as Qn, TStructuredOutputSchema as Qo, TProviderMessage as Qr, USER_EVENTS as Qs, verifiedProviderCallUsage as Qt, validatePermissionPattern as R, isImageGenerationProvider as Ra, TTextDeltaCallback as Rc, IExecutorStreamTerminalEvent as Ri, IHistoryEntry as Rl, IBoundedOutputOptions as Rn, IPluginStats as Ro, TExecutionRecoveryErrorCode as Rr, IActionOption as Rs, ISequentialOrchestrationSpec as Rt, CONTEXT_ESTIMATE_CHARS_PER_TOKEN as S, isMediaProviderDefinition as Sa, TEventListener as Sc, ICredentialKey as Si, StorageError as Sl, EXECUTION_EVENTS as Sn, createLogger as So, providerCallSpanId as Sr, TJournalModelOptions as Ss, ExecutionProxy as St, estimateContextTokensFromMessages as T, IImageGenerationProvider as Ta, IAIProvider as Tc, IFileSystem as Ti, TErrorExternalInput as Tl, TOOL_EVENT_PREFIX as Tn, logger as To, toolTraceContextFor as Tr, ITool as Ts, IExecutionProxyConfig as Tt, IPermissionEvaluationContext as U, IProviderCredentialRequirement as Ua, IToolSchema as Uc, IContextOptions as Ui, IToolMessage as Ul, hasUsableSecretReference as Un, IEventEmitterPlugin as Uo, Validator as Ur, PROVIDER_CALL_EVENTS as Us, printablePeerDriver as Ut, projectPermissionPolicy as V, TStructuredOutputMechanism as Va, IObjectParameterSchema as Vc, IStreamExecutionRequest as Vi, ITextMessagePart as Vl, ENV_REFERENCE_PREFIX as Vn, EVENT_EMITTER_EVENTS as Vo, ErrorUtils as Vr, TActionResponse as Vs, AGENT_EVENT_PREFIX as Vt, IPermissionLists as W, IProviderDefinition as Wa, TJSONSchemaEnum as Wc, IConversationContext as Wi, IUriImageMessagePart as Wl, isEnvReference as Wn, TEventEmitterListener as Wo, validateAgentConfig as Wr, PROVIDER_FALLBACK_EVENTS as Ws, EventHistoryModule as Wt, getToolPermissionProfile as X, IProviderProfileConfig as Xa, IProviderNativeWebToolCapabilities as Xc, TConversationContextMetadata as Xi, TUniversalMessageRole as Xl, createSystemMessage as Xn, IJsonSchemaOutput as Xo, TMessageConverterRegistry as Xr, readModelFallbackNotice as Xs, IVerifiedProviderCallUsage as Xt, evaluatePermission as Y, IProviderProbeResult as Ya, IProviderFunctionCallingCapability as Yc, IToolExecutionRequest as Yi, TUniversalMessagePart as Yl, createAssistantMessage as Yn, TExecutionEventData as Yo, MessageConverter as Yr, TSpanEvent as Ys, sumMessagesUsage as Yt, isToolDeniedOutright as Z, IProviderProfileDefaults as Za, IProviderNativeWebToolCapability as Zc, TResponseMetadata as Zi, chatEntryToMessage as Zl, createToolMessage as Zn, IStructuredOutputSpec as Zo, TMessageFormatConverter as Zr, TUserEvent as Zs, TProviderUsageProvenance as Zt, getModelName as _, TManagerToolParameters as _a, IEventServiceOwnerBinding as _c, hashToolSchema as _i, PluginError as _l, ToolResultAdmissionError as _n, ILogger as _o, zodToJsonSchema as _r, IRecoverableExecutionJournal as _s, TBackgroundPermissionPolicy as _t, TMetadataValue as _u, IModelPrice as a, setToolProgressCallback as aa, ObservableEventService as ac, IProviderRuntimeConfig as ai, classifyProviderFailure as al, AgentFactory as an, findProviderDefinition as ao, resolveMediaProviderConfig as ar, IZodSchema as as, PROTECTED_FILE_NAMES as at, IToolActionIdentity as au, readTokenUsageFromMessage as b, IMediaProviderDefinition as ba, IToolEventData as bc, IManagerLifecycleOptions as bi, RobotaError as bl, Robota as bn, SilentLogger as bo, isMintedSpanId as br, IResumeToolCallsResult as bs, TRUST_TO_MODE as bt, estimateBlendedCostPer1000 as c, confirmAction as ca, bindWithOwnerPath as cc, IToolSchemaProjectionChange as ci, toProviderError as cl, IAgentCreationStats as cn, IAgent as co, processEnvResolver as cr, ICacheEntry as cs, RISK_CLASS_POLICY as ct, IToolWaitRequest as cu, DEFAULT_MAX_OUTPUT as d, selectAction as da, isDefaultEventService as dc, PERMISSIVE_TOOL_SCHEMA_PROFILE as di, CircuitBreakerOpenError as dl, DEFAULT_TOOL_RESULT_HARD_CHARS as dn, IAbstractTool as do, extractEnumValues as dr, ICacheStats as ds, TArgumentKind as dt, TComplexConfigValue as du, IToolExecutionStep as ea, TASK_EVENTS as ec, AbstractTool as ei, createDefaultProviderCapabilities as el, IRegistryTransactionError as en, TProviderCredentialField as eo, createProviderFromConfig as er, normalizeStructuredOutput as es, registerToolPermissionProfile as et, isChatEntry as eu, IModelDefinition as f, textAction as fa, IAgentEventData as fc, STRICT_TOOL_SCHEMA_PROFILE as fi, ConfigurationError as fl, DEFAULT_TOOL_RESULT_WARNING_CHARS as fn, IAbstractToolOptions as fo, getSchemaTypeName as fr, ICacheStorage as fs, TMatchDirection as ft, TConfigData as fu, getModelMaxOutput as g, IToolManager as ga, IEventService as gc, TToolSchemaProjectionProfileBase as gi, NetworkError as gl, TToolResultAdmissionErrorCode as gn, ConsoleLogger as go, closeObjectSchemas as gr, IModelJournalContext as gs, DEFAULT_BACKGROUND_PERMISSION_POLICY as gt, TMetadata as gu, getModelContextWindow as h, IAIProviderManager as ha, IEventObjectValue as hc, TToolSchemaProjectionOutcome as hi, ModelNotAvailableError as hl, MAX_TOOL_RESULT_CHARS as hn, TToolExecutionFunction as ho, ISchemaClosureOptions as hr, IExecutionRoundCheckpoint as hs, isReadOnlyCommandLine as ht, TLoggerData as hu, runHooks as i, isProgressReportingTool as ia, DefaultEventService as ic, IExecutorAwareProviderConfig as ii, TProviderFailureReason as il, runRegistryTransaction as in, TProviderSetupHelpLinkKind as io, createVideoProviderFromDefinition as ir, IZodParseResult as is, PROTECTED_DIRECTORY_NAMES as it, messageToHistoryEntry as iu, isBroadExecutionAllowRule as j, IUriImageInputSource as ja, ITokenUsage as jc, IEventHistoryModule as ji, IProviderCapabilityTable as jl, IEventEmitterHierarchicalEventData as jn, IPluginContract as jo, UnsupportedShellError as jr, TToolExecutor as js, IHierarchicalOrchestrationSpec as jt, IContextWindowState as k, IMediaOutputRef as ka, IProviderRequest as kc, ISpinner as ki, TRoleModelMap as kl, ToolRegistry as kn, IPluginConfig as ko, IPlatformShellResolutionRequest as kr, IToolResult as ks, IGroupChatOrchestrationSpec as kt, lookupModelPrice as l, isConfirmed as la, composeEventName as lc, IToolSchemaProjectionProfile as li, AuthenticationError as ll, IAgentFactoryOptions as ln, IAgentConfig as lo, IStructuredOutputResolutionInput as lr, ICacheKey as ls, TToolRiskClass as lt, IToolWaitResponse as lu, formatTokenCount as m, IToolFactory as ma, IEventContext as mc, TOOL_SCHEMA_PROJECTION_MAX_NODES as mi, IProviderFailureDetails as ml, IToolResultSpillStore as mn, IToolWithEventService as mo, ISchemaClosureChange as mr, IExecutionJournal as ms, TResolveInWorkspace as mt, TContextData as mu, decodeHookVerdict as n, getToolEstimatedDuration as na, AbstractEventService as nc, AbstractPlugin as ni, TModelFallbackCallback as nl, isRegistryTransactionError as nn, TProviderModelLifecycle as no, IMediaProviderOverrides as nr, validateAgainstJsonSchema as ns, toolNameMatches as nt, isToolMessage as nu, MODEL_PRICES as o, CONFIRM_NO as oa, StructuredEventService as oc, TProviderLoggingData as oi, readProviderFailureDetails as ol, AgentTemplates as on, formatSupportedProviderTypes as oo, TEnvResolver as or, IZodSchemaDef as os, isProtectedPath as ot, IToolContinuation as ou, findModelDefinition as p, IOpenAPIToolConfig as pa, IBaseEventData as pc, TOOL_SCHEMA_PROJECTION_MAX_DEPTH as pi, EmptyCompletionError as pl, IToolResultAdmissionOptions as pn, IToolContract as po, hasValidationConstraints as pr, IExecutionContinuationState as ps, IReadOnlyCommandContext as pt, TConfigValue as pu, TToolArgs as q, IProviderModelCatalog as qa, IProviderSpecificOptions as qc, IConversationServiceOptions as qi, TUniversalMessage as ql, LocalExecutor as qn, IRunOptions as qo, validateProviderName as qr, TOOL_BODY_EVENTS as qs, collectAssistantUsageMetadata as qt, GuardrailExecutor as r, getToolExecutionSteps as ra, DEFAULT_ABSTRACT_EVENT_SERVICE as rc, AbstractAIProvider as ri, IProviderFailureClassification as rl, lifecycleOf as rn, TProviderSetupField as ro, createImageProviderFromDefinition as rr, ISchemaConversionOptions as rs, ICriticalPathContext as rt, isUserMessage as ru, calculateModelCost as s, CONFIRM_YES as sa, bindEventServiceOwner as sc, IToolSchemaProjection as si, scrubSecrets as sl, ITemplateApplicationResult as sn, getProviderCredentialRequirement as so, createRecordEnvResolver as sr, IResponseFormatConfig as ss, removesCriticalPath as st, IToolContinuationPrompt as su, isEnforcing as t, TToolProgressCallback as ta, TASK_EVENT_PREFIX as tc, AbstractExecutor as ti, IModelFallbackNotice as tl, IRegistryTransactionStep as tn, TProviderModelCatalogStatus as to, normalizeProviderConfig as tr, parseStructuredResponseText as ts, requiresFreshApproval as tt, isSystemMessage as tu, DEFAULT_CONTEXT_WINDOW as u, multiSelectAction as ua, generateSpanId as uc, PARAMETER_SCHEMA_KEYWORDS as ui, CacheIntegrityError as ul, IAgentLifecycleEvents as un, IAgentTemplate as uo, resolveStructuredOutputCapability as ur, ICacheOptions as us, UNCLASSIFIED_TOOL_FALLBACK as ut, IToolWaitState as uu, registerModelMetadata as v, IMediaProviderConfig as va, IExecutionEventData as vc, projectToolSchema as vi, ProviderError as vl, admitToolResult as vn, ILoggerOptions as vo, callJournaledProvider as vr, IResumeExecutionOptions as vs, TPermissionDecision$1 as vt, TToolParameters as vu, IContextTokenEstimateOptions as w, IImageEditRequest as wa, TEventUniversalValue as wc, IDirent as wi, TErrorContextData as wl, TOOL_EVENTS as wn, getGlobalLoggerSink as wo, subprocessTraceEnvironment as wr, IParameterValidationResult as ws, withEventEmission as wt, readTokenUsageFromMetadata as x, findMediaProviderDefinition as xa, TEventExtensionValue as xc, AbstractAgent as xi, SameToolInputLoopError as xl, IDestroyResult as xn, TUtilLogLevel as xo, outboundTraceContextFor as xr, TExecutionJournalRecord as xs, TTrustLevel as xt, IMessageTokenUsage as y, IMediaProviderCredentialRequirement as ya, IOwnerPathSegment as yc, AbstractManager as yi, RateLimitError as yl, wasToolResultAdmitted as yn, IUtilLogEntry as yo, buildTraceparent as yr, IResumeToolCallsOptions as ys, TPermissionMode as yt, TypeUtils as yu, IPermissionPolicyContext as z, isVideoGenerationProvider as za, TToolChoice as zc, ILocalExecutorConfig as zi, IInlineImageMessagePart as zl, TOutputRetention as zn, PluginCategory as zo, ExecutionSuspendedError as zr, IActionRequest as zs, TOrchestrationPrimitive as zt };
+//# sourceMappingURL=index-DQrmrFn9.d.ts.map