@genesislcap/ai-assistant 15.58.2 → 15.60.0

package/dist/ai-assistant.d.ts

@@ -16,6 +16,7 @@ import { ChatDriverResult } from '@genesislcap/foundation-ai';
 import type { ChatFallback } from '@genesislcap/foundation-ai';
 import type { ChatInputDuringExecutionMode } from '@genesislcap/foundation-ai';
 import type { ChatMessage } from '@genesislcap/foundation-ai';
+import type { ChatMessageFeedbackRating } from '@genesislcap/foundation-ai';
 import type { ChatThinkingPolicy } from '@genesislcap/foundation-ai';
 import type { ChatToolChoice } from '@genesislcap/foundation-ai';
 import type { ChatToolDefinition } from '@genesislcap/foundation-ai';
@@ -502,6 +503,12 @@ export declare class AgentSession {
      * Returns `undefined` when there was no active agent, so a caller can skip its events.
      */
     release(): Promise<AgentTransition | undefined>;
+    /**
+     * Hand a transition to the owner. A throwing listener is logged rather than propagated, for the
+     * same reason a throwing hook is: the transition has already happened, and failing the caller
+     * would leave it believing it had not.
+     */
+    private reportTransition;
     /**
      * Fire `onDeactivate` on the active agent and abort pending lifecycle work, for session
      * teardown, so machines release resources cleanly. The session is not reusable afterwards: the
@@ -533,14 +540,24 @@ export declare interface AgentSessionDeps {
      * after construction on some paths, so a value captured here would pin the wrong one.
      */
     sessionKey: () => string;
+    /**
+     * Called after every real transition (a swap to a different agent, or a release), once the
+     * session already reflects it. Not called for a re-activation of the same agent, for the direct
+     * {@link AgentSession.setFlowOwner} restore write, or on {@link AgentSession.dispose}.
+     *
+     * One place for the lifecycle events (GENC-1485): the session is shared between a `ChatDriver`
+     * and the `OrchestratingDriver` wrapping it, and either may move it, so the owner learns of a
+     * transition here rather than from whichever caller happened to make it.
+     */
+    onTransition?: (transition: AgentTransition) => void;
 }
 
 /**
  * What changed when an agent was activated or released.
  *
- * Returned rather than dispatched: the host listens on the `OrchestratingDriver`, not on the
- * `ChatDriver` that owns the session, so a self-dispatching session would need telling which
- * target to fire on.
+ * Returned to the caller, and also reported to the session's owner through
+ * {@link AgentSessionDeps.onTransition}, which is how the owning `ChatDriver` raises the lifecycle
+ * events whoever triggered the change (GENC-1485).
  *
  * @beta
  */
@@ -557,6 +574,14 @@ export declare interface AgentTransition {
     flowOwnerChangedTo?: string | null;
 }
 
+/**
+ * The event types in {@link AiDriverEventMap}, as a runtime list. Built from a record keyed by the
+ * map, so adding an event to the map without adding it here is a compile error.
+ *
+ * @beta
+ */
+export declare const AI_DRIVER_EVENT_TYPES: ReadonlyArray<keyof AiDriverEventMap>;
+
 /**
  * Union of all available animation names, derived from {@link ANIMATION_DEFS}.
  *
@@ -751,21 +776,22 @@ export declare interface AiDockProvider {
 }
 
 /**
- * Common interface implemented by both `ChatDriver` (single-agent) and
- * `OrchestratingDriver` (multi-agent). `FoundationAiAssistant` depends only
- * on this interface — the concrete class is chosen at startup based on how
- * many agents are configured.
+ * Common interface implemented by `ChatDriver` (single-agent), `OrchestratingDriver`
+ * (multi-agent) and any decorator built on {@link BaseDriverDecorator}. `FoundationAiAssistant`
+ * depends only on this interface — the concrete driver is chosen at startup based on how many
+ * agents are configured, and may be wrapped.
  *
- * Extends `EventTarget` so consumers can subscribe to `history-updated` events
+ * Extends `EventTarget` so consumers can subscribe to the events in {@link AiDriverEventMap}
  * without knowing the concrete implementation.
  *
  * @beta
  */
 export declare interface AiDriver extends EventTarget {
     /**
-     * Send a user message and run the tool loop to completion.
+     * Send a user message and run the tool loop to completion. `options.delegate` sends it on the
+     * user's behalf instead (GENC-1660): see {@link SendMessageOptions}.
      */
-    sendMessage(input: string, attachments?: ChatAttachment[]): Promise<ChatDriverResult>;
+    sendMessage(input: string, attachments?: ChatAttachment[], options?: SendMessageOptions): Promise<ChatDriverResult>;
     /**
      * Continue the tool loop from the current history without appending a new
      * user message. Used by `OrchestratingDriver` on agent handoffs — the
@@ -835,12 +861,17 @@ export declare interface AiDriver extends EventTarget {
      * than on the next message, then, when `resumeNote` is given and the agent has not opted out,
      * runs one turn from the restored history with the note in the tail of its first model call.
      *
+     * `agent` is the flow owner's config, for a driver that holds no list of agents to look it up
+     * in (GENC-1660): a config cannot be persisted, so after a reload only its name survives, and
+     * whoever runs a bare `ChatDriver` is the one that knows which agent it runs. A driver that does
+     * hold a list (the orchestrator) looks the owner up itself and ignores this.
+     *
      * Returns the turn's result when one ran, `undefined` otherwise (no flow owner, the owner is not
-     * configured, or no note). Never throws for those cases.
+     * configured or not given, or no note). Never throws for those cases.
      *
      * @beta
      */
-    resumeRestoredFlow?(resumeNote?: string): Promise<ChatDriverResult | undefined>;
+    resumeRestoredFlow?(resumeNote?: string, agent?: AgentConfig): Promise<ChatDriverResult | undefined>;
     /**
      * Return the full, unredacted conversation history.
      */
@@ -914,6 +945,54 @@ export declare interface AiDriver extends EventTarget {
      * since that ticket's breaking release.
      */
     setFlowOwner(name: string | null): void;
+    /**
+     * The transient flow lock: the name of the stateful agent that owns the current flow, or `null`
+     * (GENC-1660). The reading half of {@link AiDriver.setFlowOwner}; changes are announced on
+     * `flow-owner-changed`. Lets a decorator scope its behaviour to a flow without reaching for a
+     * concrete driver.
+     *
+     * Optional, so a third-party driver need not implement it; every shipped driver does.
+     *
+     * @beta
+     */
+    getFlowOwner?(): string | null;
+    /**
+     * Install an {@link InteractionInterceptor}: told about every interaction this driver opens,
+     * with its live context, and able to claim it and answer it instead of the person (GENC-1660).
+     * Interceptors are asked outermost first and the first claim wins. Returns a remover.
+     *
+     * Optional, so a third-party driver need not implement it; every shipped driver does.
+     *
+     * @beta
+     */
+    addInteractionInterceptor?(interceptor: InteractionInterceptor): () => void;
+    /**
+     * Show a widget in the transcript OUTSIDE any tool loop, and resolve with its result
+     * (GENC-1660): `requestInteraction` for something that is not a tool handler. How a decorator
+     * asks the person something of its own, such as what to do after a turn failed.
+     *
+     * It takes the one interaction slot like any other, so a turn that requests an interaction
+     * while it is open throws. Pass `options.signal` to close it — unanswered, like a timeout — when
+     * the moment passes. Interceptors are offered it like any other, with the active agent (if any)
+     * as its owner.
+     *
+     * Optional, so a third-party driver need not implement it; every shipped driver does.
+     *
+     * @beta
+     */
+    presentInteraction?<T = InteractionResult>(componentName: string, data: unknown, options?: InteractionRequestOptions): Promise<T>;
+    /**
+     * Add a named capability to every tool handler's context, under `context.capabilities[name]`
+     * (GENC-1660). How a decorator gives the working agent's handlers something to call — the
+     * autopilot's `mode` / `setMode`, say — without the agent knowing the decorator exists.
+     * `factory` builds the value per handler call, from who is calling; sub-agents' handlers see
+     * their root's capabilities. Returns a remover.
+     *
+     * Optional, so a third-party driver need not implement it; every shipped driver does.
+     *
+     * @beta
+     */
+    provideHandlerCapability?(name: string, factory: HandlerCapabilityFactory): () => void;
     /**
      * Headroom the next turn could need, and which agent set that requirement
      * (GENC-1582). `undefined` when no agent the turn could land on declares a
@@ -1031,6 +1110,53 @@ export declare interface AiDriver extends EventTarget {
     cancel?(): void;
 }
 
+/**
+ * Every event an {@link AiDriver} can dispatch, by type (GENC-1660).
+ *
+ * The list a decorator forwards: {@link BaseDriverDecorator} re-dispatches each of these from its
+ * inner driver, so an event missing here is an event a host behind a decorator never sees. That is
+ * the failure the orchestrator's hand-written proxy list had twice (`external-cost-recorded`, then
+ * the lifecycle events a bare `ChatDriver` never raised). Details typed `unknown` are forwarded
+ * as-is and not yet described here.
+ *
+ * @beta
+ */
+export declare interface AiDriverEventMap {
+    /** The transcript changed. Detail: the full history. */
+    'history-updated': CustomEvent<ReadonlyArray<ChatMessage>>;
+    /** A sub-agent's own transcript changed. */
+    'sub-agent-history-updated': CustomEvent<unknown>;
+    /** A sub-agent run started. */
+    'sub-agent-start': CustomEvent<unknown>;
+    /** A sub-agent run ended. */
+    'sub-agent-stop': CustomEvent<unknown>;
+    /** A blocking interaction that overrides the chat input opened. */
+    'interaction-start': CustomEvent<unknown>;
+    /** That interaction settled. */
+    'interaction-stop': CustomEvent<{
+        interactionId: string;
+    }>;
+    /** The provider resolved for a turn changed. */
+    'provider-changed': CustomEvent<{
+        name: string;
+    }>;
+    /** Spend was recorded against an already-resolved interaction. */
+    'external-cost-recorded': CustomEvent<{
+        interactionId: string;
+        costUsd: number;
+    }>;
+    /** The active agent changed. Detail: the new agent, or `undefined` after a release. */
+    'agent-changed': CustomEvent<AgentConfig | undefined>;
+    /** A stateful agent released its flow. Detail: the released agent. */
+    'agent-released': CustomEvent<AgentConfig>;
+    /** The flow-owner lock changed. Detail: the new owner's name, or `null` when cleared. */
+    'flow-owner-changed': CustomEvent<string | null>;
+    /** Routing started (the classifier is about to run). Orchestrator only. */
+    'orchestrating-start': CustomEvent<undefined>;
+    /** Routing finished and an agent is installed. Orchestrator only. */
+    'orchestrating-stop': CustomEvent<undefined>;
+}
+
 /**
  * Optional app-registered policy for which cloud vendor backs the tier-shaped
  * provider registry slots (`low` / `high` / …). Apps inject a concrete
@@ -1525,6 +1651,97 @@ declare interface BaseAgentConfig {
     contextReserve?: ContextReserveInput;
 }
 
+/**
+ * The base of every driver decorator (GENC-1660): an {@link AiDriver} that wraps another and
+ * passes every member, and every event in {@link AiDriverEventMap}, through to it.
+ *
+ * A decorator extends this and overrides only what it changes, so decorators stack in any order
+ * and a member or event added to `AiDriver` reaches the host through every layer by default.
+ * `OrchestratingDriver` is one; it used to forward by hand, and twice a member it did not forward
+ * silently did nothing for every multi-agent host (`recordExternalCost`, then
+ * `getHistoryForPersistence`).
+ *
+ * Abstract with no abstract members, so it cannot be constructed on its own: a decorator that
+ * changes nothing is not one.
+ *
+ * Optional `AiDriver` members are implemented here unconditionally, as a forward that falls back
+ * to the "not supported" answer when the inner driver lacks them. A host that feature-detects with
+ * `?.` therefore always finds them, and gets the same answer it would from the inner driver.
+ *
+ * @beta
+ */
+export declare abstract class BaseDriverDecorator<TInner extends AiDriver = AiDriver> extends EventTarget implements AiDriver {
+    protected readonly inner: TInner;
+    /** Undoes this layer's hold on its inner driver; see {@link BaseDriverDecorator.detach}. */
+    private readonly detachers;
+    protected constructor(inner: TInner);
+    /**
+     * Let go of the inner driver WITHOUT disposing it: stop forwarding its events, and undo whatever
+     * a subclass registered through {@link BaseDriverDecorator.onDetach} (its interceptors, its
+     * capabilities, its own listeners). For dropping or replacing a decorator while the driver it
+     * wrapped lives on — otherwise the old layer keeps re-dispatching every event and is never
+     * collected. Idempotent. `dispose()` detaches too.
+     */
+    detach(): void;
+    /** Register something {@link BaseDriverDecorator.detach} must undo. */
+    protected onDetach(undo: () => void): void;
+    sendMessage(input: string, attachments?: ChatAttachment[], options?: SendMessageOptions): Promise<ChatDriverResult>;
+    continueFromHistory(transientPrimer?: ChatMessage[], options?: ContinueFromHistoryOptions): Promise<ChatDriverResult>;
+    resolveInteraction(interactionId: string, result: unknown): void;
+    recordExternalCost(interactionId: string, costUsd: number): boolean;
+    getInteractionContext(interactionId: string): InteractionContext | undefined;
+    loadHistory(messages: ChatMessage[]): void;
+    primeRestoredAgentState(snapshots: Record<string, unknown>): void;
+    canRestoreFlowOwner(agentName: string): boolean;
+    canResumeRestoredFlow(agentName: string): boolean;
+    resumeRestoredFlow(resumeNote?: string, agent?: AgentConfig): Promise<ChatDriverResult | undefined>;
+    getRawHistory(): readonly ChatMessage[];
+    getHistoryForPersistence(): ChatMessage[];
+    getCondensePoliciesForPersistence(messages: readonly ChatMessage[]): PersistedCondensePolicy[];
+    restoreCondensePolicies(entries: readonly unknown[] | undefined): {
+        restored: number;
+        awaitingReactivation: number;
+    };
+    getActiveAgent(): AgentConfig | undefined;
+    setPinnedAgent(name: string | null): void;
+    setFlowOwner(name: string | null): void;
+    getFlowOwner(): string | null;
+    /**
+     * Forwarded, so an interceptor installed on any layer lands on the driver that opens the
+     * interactions. A decorator that answers interactions installs its own on `this.inner`.
+     */
+    addInteractionInterceptor(interceptor: InteractionInterceptor): () => void;
+    presentInteraction<T = InteractionResult>(componentName: string, data: unknown, options?: InteractionRequestOptions): Promise<T>;
+    provideHandlerCapability(name: string, factory: HandlerCapabilityFactory): () => void;
+    getContextReserve(): ContextReserveResolution | undefined;
+    getPreambleTokens(): number | undefined;
+    setContextGuard(policy?: ContextGuardPolicy): void;
+    compact(options?: CompactionPlanOptions): Promise<ChatMessage | null>;
+    getCompactionPlan(options?: CompactionPlanOptions): CompactionProjection | null;
+    canCompact(options?: CompactionPlanOptions): boolean;
+    isBusy(): boolean;
+    getSuggestions(history: ChatMessage[], prompt: string, count: number, allAgentInfo?: AllAgentSummary[]): Promise<string[]>;
+    getTurnSnapshots(): ReadonlyArray<TurnSnapshot>;
+    /**
+     * The inner driver's entries. Diagnostics compose down the stack: a decorator with entries of
+     * its own overrides this and appends them to `super.getExternalDiagnostics()`.
+     */
+    getExternalDiagnostics(): ReadonlyArray<DiagnosticEntry>;
+    getActiveProviderName(): string;
+    dispose(): void | Promise<void>;
+    cancel(): void;
+    /**
+     * Every driver in the stack, outermost first: `driver`, then each inner driver down to the one
+     * that is not a decorator.
+     *
+     * For diagnostics and labelling only: behaviour must go through `AiDriver` members, which every
+     * layer forwards, never through a concrete class found here.
+     *
+     * @internal
+     */
+    static layers(driver: AiDriver): AiDriver[];
+}
+
 /**
  * Id of the blocked banner, referenced by the composer controls'
  * `aria-describedby`. Shadow-DOM-scoped, so a fixed string cannot collide with
@@ -1822,6 +2039,13 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     private unlinkLifecycleFromMessage?;
     /** A sub-agent runs inside its parent's message: the parent's `turnSignal`, handed down. */
     private inheritedTurnSignal?;
+    /** Capabilities provided on this driver by decorators (GENC-1660). Only the root's are used. */
+    private readonly handlerCapabilities;
+    /**
+     * For a sub-agent's driver, the driver that invoked it: its capabilities, flow owner and owner
+     * path are the ones this driver's handlers see, so a capability reaches sub-agents unchanged.
+     */
+    private capabilityParent?;
     /**
      * Active agent's provider selector (static name or per-turn resolver).
      * `undefined` means "use the registry default".
@@ -1926,6 +2150,11 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * the point: two would let `getActiveAgent()` disagree between the outer and inner driver.
      * `@internal` rather than private so that reach is legal without six delegating one-liners.
      *
+     * **This driver raises the lifecycle events for every transition of the session**, whoever made
+     * it: itself, through {@link ChatDriver.activateAgent} or a release, or the orchestrator reaching
+     * through (GENC-1485). Before, only the orchestrator dispatched them, so a host on a bare
+     * `ChatDriver` never learned its flow owner.
+     *
      * @internal
      */
     readonly agentSession: AgentSession;
@@ -2199,6 +2428,30 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * @beta
      */
     activateAgent(config: AgentConfig): Promise<void>;
+    /**
+     * {@inheritDoc AiDriver.resumeRestoredFlow}
+     *
+     * This driver holds no list of agents, so it resumes only the `agent` it is handed (GENC-1660):
+     * whoever runs a bare `ChatDriver` knows which agent that is, and after a reload only the name
+     * survived. Without one it does nothing, as a driver without this member did before; given one
+     * that is not the restored flow owner, it refuses.
+     *
+     * For headless callers: the shipped host restores and resumes through `OrchestratingDriver`,
+     * and a bare `ChatDriver` does not answer `canRestoreFlowOwner`, so the host never plans a resume
+     * for one.
+     *
+     * The orchestrator does not delegate here, because it installs a decorated config of its own;
+     * this is the bare-driver path.
+     *
+     * @beta
+     */
+    resumeRestoredFlow(resumeNote?: string, agent?: AgentConfig): Promise<ChatDriverResult | undefined>;
+    /**
+     * Raise the host-facing lifecycle events for one session transition (GENC-1485), in the order
+     * the orchestrator raised them before it stopped doing so itself: the flow lock first, then the
+     * release, then the active agent.
+     */
+    private dispatchAgentTransition;
     /**
      * {@inheritDoc AiDriver.getActiveAgent}
      *
@@ -2226,6 +2479,12 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * @beta
      */
     setFlowOwner(name: string | null): void;
+    /**
+     * {@inheritDoc AiDriver.getFlowOwner}
+     *
+     * @beta
+     */
+    getFlowOwner(): string | null;
     /**
      * Install `config` as the active agent **without firing lifecycle hooks**.
      *
@@ -2528,7 +2787,38 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      *   and `presentation` to control whether the host wraps the widget in a chat
      *   bubble and/or shows the "Assistant" label.
      */
-    requestInteraction<T>(componentName: string, data: any, options?: InteractionRequestOptions, onOpened?: (interactionId: string) => void): Promise<T>;
+    requestInteraction<T>(componentName: string, data: any, options?: InteractionRequestOptions, onOpened?: (interactionId: string) => void, innerPath?: readonly string[], onSettled?: (settled: InteractionSettled) => void): Promise<T>;
+    /**
+     * {@inheritDoc AiDriver.addInteractionInterceptor}
+     *
+     * Consulted only on the root driver, where every interaction opens: a sub-agent's request
+     * travels up to its root, carrying its owner path, and is offered there once.
+     *
+     * @beta
+     */
+    addInteractionInterceptor(interceptor: InteractionInterceptor): () => void;
+    /**
+     * {@inheritDoc AiDriver.presentInteraction}
+     *
+     * @beta
+     */
+    presentInteraction<T = InteractionResult>(componentName: string, data: unknown, options?: InteractionRequestOptions): Promise<T>;
+    /**
+     * {@inheritDoc AiDriver.provideHandlerCapability}
+     *
+     * Throws if `name` is already provided: two decorators answering to one name would leave a
+     * handler unable to tell which it is talking to.
+     *
+     * @beta
+     */
+    provideHandlerCapability(name: string, factory: HandlerCapabilityFactory): () => void;
+    /**
+     * The capabilities this driver's handlers see, and who they see them as: the root's factories,
+     * the root's flow owner, and the owner path from the root down to this driver's agent.
+     */
+    private capabilityScope;
+    /** Build `context.capabilities` for one handler call, or `undefined` when nothing is provided. */
+    private buildCapabilities;
     /**
      * Record what came of an interaction, after it resolved, on its history message
      * (`interaction.outcome`): handed to its widget and persisted with the session, never sent to a
@@ -2583,7 +2873,7 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * can continue an existing conversation. Call this before the first user message.
      */
     loadHistory(messages: ChatMessage[]): void;
-    sendMessage(userInput: string, attachments?: ChatAttachment[]): Promise<ChatDriverResult>;
+    sendMessage(userInput: string, attachments?: ChatAttachment[], options?: SendMessageOptions): Promise<ChatDriverResult>;
     /**
      * Builds the context object passed to every tool handler call.
      * Centralised here so fold shortcut dispatch and the main tool loop use the
@@ -2714,10 +3004,10 @@ export declare interface ChatDriverConfig {
      * Leave acting on `releaseAgent` to the owner of this driver.
      *
      * Set by `OrchestratingDriver` for its inner driver, which performs the release itself after the
-     * turn so it can fire the host-facing `agent-released` / `agent-changed` / `flow-owner-changed`
-     * events. Both drivers share one `AgentSession`, so releasing here first would empty it and make
-     * the orchestrator's own release a silent no-op — leaving the host with a locked picker and a
-     * stale active agent.
+     * turn, because a release ends its handoff loop and it reads the flag to know. Both drivers share
+     * one `AgentSession`, and releasing here first would clear the flag before the orchestrator saw
+     * it. The host-facing `agent-released` / `agent-changed` / `flow-owner-changed` events fire from
+     * the session's transition either way (GENC-1485).
      *
      * Left unset, a driver releases its own agent, which is what a bare `ChatDriver` needs: nothing
      * else is watching the flag.
@@ -3112,6 +3402,14 @@ export declare interface DebugLog {
  */
 export declare const DEFAULT_ANIMATIONS: AiAssistantAnimation[];
 
+/**
+ * How a delegated `user` message is framed for the model when its sender gives no phrase. Names no
+ * decorator, so the model has none to repeat.
+ *
+ * @beta
+ */
+export declare const DEFAULT_DELEGATE_FRAMING = "Sent on the user's behalf.";
+
 /**
  * Identity helper that infers the narrowest possible type for an agent config,
  * preserving string literal types (including `name`) without requiring `as const`.
@@ -3156,6 +3454,36 @@ export declare function defineAgent<const T extends AgentConfig>(config: T): T;
  */
 export declare function defineStatefulAgent<S>(opts: StatefulAgentInit<S>): AgentConfig;
 
+/**
+ * What the working agent is told about an interaction an interceptor answered (GENC-1660): added
+ * to the result of the tool call that requested it, as `decidedOnUsersBehalf` on an object result
+ * or as a line appended to a text one.
+ *
+ * Built only from what the platform already holds — the claimant's framing, and the choice and
+ * narration it recorded — so the text the person saw and the text the agent is told about are the
+ * same string. It never names the claimant, so the agent has nothing to repeat about one.
+ *
+ * @beta
+ */
+export declare interface DelegatedDecision {
+    /** The claimant's {@link InteractionInterceptor.decisionFraming}, e.g. "Decided on the user's behalf". */
+    readonly framing: string;
+    /** What was chosen, as recorded by the claimant. */
+    readonly choice?: string;
+    /** What the person was shown about it, verbatim, as the assistant's own words. */
+    readonly shownToUser?: string;
+}
+
+/**
+ * A message written or sent on the user's behalf by a driver decorator (GENC-1660). See
+ * `ChatMessage.delegate`.
+ *
+ * @beta
+ */
+export declare type DelegatedMessage = ChatMessage & {
+    delegate: string;
+};
+
 /**
  * One entry in the diagnostics stream — the debug-log timeline-entry union
  * (`message` / `turn` / `event`, as `getDebugLog()` builds) plus a point-in-time
@@ -4162,11 +4490,11 @@ export declare class FoundationAiAssistant extends GenesisElement {
     showingSplash: boolean;
     private driver?;
     /**
-     * This element's driver as an orchestrator, or `undefined` when the session is running a bare
-     * `ChatDriver`. The only place in this element that narrows the type; the test itself lives in
-     * `asOrchestrator`, shared with the session persister.
+     * Which kind of driver this element runs, for the `driver.created` / `assistant.connected` log
+     * lines only. Looks through any decorators (GENC-1660): behaviour goes through `AiDriver`
+     * members, which every layer forwards, so this is the one place the concrete class matters.
      */
-    private get orchestrator();
+    private get driverKind();
     private driverCleanup?;
     private loadingTimer;
     private unsubBus?;
@@ -4872,6 +5200,22 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * promise is enforced rather than relying on two copies agreeing.
      */
     private debugLogFilename;
+    /**
+     * The most recent rateable reply, whose thumbs stay visible without a hover.
+     *
+     * @internal
+     */
+    get latestReply(): ChatMessage | undefined;
+    /** @internal */
+    get messageFeedbackDescription(): string;
+    /**
+     * Hand a rated reply to the host's `ui.messageFeedback.send`, with a getter for the same
+     * lifetime log the agent-log Send button submits — built only if the host asks for it.
+     * Rejects when the host does, or does not settle in time.
+     *
+     * @internal
+     */
+    submitMessageFeedback(reply: ChatMessage, rating: ChatMessageFeedbackRating, note: string | undefined): Promise<void>;
     /**
      * Back to idle: nothing in flight, no flash, no open compose box, no note. Called on
      * disconnect and on a session switch / Clear (a note typed against one conversation
@@ -5249,6 +5593,35 @@ export declare type GenesisWriteReviewCompletedEventDetail = InteractionResult<G
  */
 export declare function getAiPopoutManager(): FoundationAiPopoutManager | undefined;
 
+/**
+ * Builds a capability's value for one tool-handler call (GENC-1660). Called per call, so it can
+ * reflect the moment; it should be cheap and must not throw (a throw is logged and the capability
+ * left out of that call). Returning `undefined` leaves the capability out, which is how a decorator
+ * says "not available here".
+ *
+ * @beta
+ */
+export declare type HandlerCapabilityFactory = (scope: HandlerCapabilityScope) => unknown;
+
+/**
+ * Who a handler capability is being built for (GENC-1660): the tool handler about to run.
+ *
+ * @beta
+ */
+export declare interface HandlerCapabilityScope {
+    /**
+     * The agents from the root down to the one whose handler is running, outermost first — e.g.
+     * `['bootstrap', 'brief-critic']` for a sub-agent's handler. The same shape as
+     * `InteractionOpened.ownerPath`, so a decorator scopes the two the same way.
+     */
+    readonly ownerPath: readonly string[];
+    /**
+     * The root driver's flow owner when the handler runs, or `null`. A sub-agent has no flow of its
+     * own, so it sees its root's: a capability scoped to a flow applies to the flow's sub-agents.
+     */
+    readonly flowOwner: string | null;
+}
+
 /**
  * A single in-flight per-call chat-input override pushed by a `requestSubAgent`
  * or `requestInteraction` call. Tracked as an array (not a counter) so the
@@ -5303,6 +5676,15 @@ export declare type InteractionCompletedEventDetail = ChatInteractionEventsMap['
 export declare interface InteractionContext<TState extends object = Record<string, unknown>> {
     /** Stable id of the interaction this context belongs to. */
     readonly interactionId: string;
+    /**
+     * Who holds this pending interaction right now: `'user'`, or the id of the interceptor that
+     * claimed it, e.g. `'autopilot'` (GENC-1660). `'user'` unless something claimed it.
+     *
+     * Reactive through {@link InteractionContext.subscribe}: a change calls `notify()`, so a view
+     * must re-read it on every notification rather than once on mount, or it would stay hidden after
+     * a hand-back. Only the claimant changes it, through its `InteractionHold`.
+     */
+    readonly heldBy: InteractionHolder;
     /**
      * Durable, remount-surviving source of truth for the interaction — a socket
      * handle, the current phase, a half-typed draft. A plain object, deliberately
@@ -5355,11 +5737,120 @@ export declare interface InteractionContext<TState extends object = Record<strin
  */
 export declare type InteractionCostEventDetail = ChatInteractionEventsMap['interaction-cost'];
 
+/**
+ * The handle an interceptor uses to move a pending interaction between the person and itself
+ * (GENC-1660): to the person when it hands back or is paused, back to itself when resumed.
+ *
+ * Every interceptor is offered one, but only the claimant's works: on any other interceptor's
+ * handle, and after the interaction ends, its members do nothing and return `false`. A claim is
+ * granted only once `onInteractionOpened` has returned `'claim'` (it may yet be refused), so the
+ * claimant's own handle does nothing until then either: act on it afterwards. Views read the
+ * result as `ctx.heldBy`; they never change it.
+ *
+ * @beta
+ */
+export declare interface InteractionHold {
+    /**
+     * Give the interaction to the person (`'user'`) or back to the claimant (`'claimant'`). Notifies
+     * the context's subscribers and records `interaction.held`. Returns whether it applied.
+     */
+    set(holder: 'user' | 'claimant'): boolean;
+    /**
+     * Say what the claimant decided, before it settles the interaction, so the tool that asked is
+     * told honestly (GENC-1660). When the interaction then resolves while the claimant holds it, the
+     * driver adds a {@link DelegatedDecision} built from this to that tool's result, so the working
+     * agent learns the choice was made on the user's behalf and what the user was shown about it.
+     *
+     * Optional to call: without it the record carries only the framing. Later calls replace earlier
+     * ones. Returns `false`, recording nothing, unless this interceptor holds the interaction.
+     */
+    recordDecision(decision: {
+        choice?: string;
+        shownToUser?: string;
+    }): boolean;
+    /**
+     * Settle the interaction AS the claimant (GENC-1660). The only route that stamps the claimant as
+     * `answeredBy`: an answer through the host's `resolveInteraction` — a click — is the person's,
+     * whoever held the interaction at the time, so attribution never depends on a view honouring
+     * `heldBy`. Returns `false`, settling nothing, unless this interceptor holds it right now.
+     */
+    resolve(result: unknown): boolean;
+}
+
+/**
+ * Who holds a pending interaction: the person, or the id of the interceptor that claimed it
+ * (GENC-1660). See {@link InteractionContext.heldBy}.
+ *
+ * @beta
+ */
+export declare type InteractionHolder = 'user' | (string & {});
+
+/**
+ * Something that is told about every interaction a driver opens, and may answer it instead of the
+ * person (GENC-1660). Installed with `AiDriver.addInteractionInterceptor`, typically by a driver
+ * decorator such as an autopilot or a test harness.
+ *
+ * Interceptors are asked outermost first. The first to claim an interaction holds it; the rest
+ * observe — they see the same context but their `hold` does nothing. Nobody can claim a `userOnly`
+ * interaction. A throwing interceptor is logged and treated as abstaining.
+ *
+ * @beta
+ */
+export declare interface InteractionInterceptor {
+    /** The holder id this interceptor's claims are recorded under, e.g. `'autopilot'`. Not `'user'`. */
+    readonly id: string;
+    /**
+     * How a {@link DelegatedDecision} it settled opens, as the working agent reads it. Must not name
+     * the interceptor. Defaults to "Decided on the user's behalf"; an autopilot grounded in a brief
+     * would say "Decided on the user's behalf, from their brief".
+     */
+    readonly decisionFraming?: string;
+    /** Return `'claim'` to hold the interaction, or nothing to leave it with the person. */
+    onInteractionOpened(opened: InteractionOpened): 'claim' | undefined | void;
+}
+
+/**
+ * A new interaction, as offered to each installed interceptor (GENC-1660).
+ *
+ * Offered once, at the root driver, after its context exists and before its message is appended,
+ * so the first render of its widget already knows who holds it.
+ *
+ * @beta
+ */
+export declare interface InteractionOpened {
+    readonly interactionId: string;
+    readonly componentName: string;
+    /** The `data` the widget was requested with. */
+    readonly data: unknown;
+    /**
+     * The agents that asked for it, outermost first: the root's active agent, then each sub-agent
+     * the request travelled up through — e.g. `['bootstrap', 'brief-critic']`. The last entry is the
+     * agent whose tool handler called `requestInteraction`.
+     */
+    readonly ownerPath: readonly string[];
+    /** Set from `InteractionRequestOptions.userOnly`: nobody may claim it. */
+    readonly userOnly: boolean;
+    /** The interaction's live context, the same object its widget is handed. */
+    readonly ctx: InteractionContext;
+    /** See {@link InteractionHold}. Works only for the interceptor whose claim was granted. */
+    readonly hold: InteractionHold;
+}
+
 /**
  * Opens an interaction somewhere else — the parent driver, for a sub-agent's — and tells
- * `onOpened` its id.
+ * `onOpened` its id. `ownerPath` is the agents the request has already come up through, outermost
+ * first, so the root can tell interceptors who asked (GENC-1660).
  */
-declare type InteractionRequester = <T>(componentName: string, data: any, options?: InteractionRequestOptions, onOpened?: (interactionId: string) => void) => Promise<T>;
+declare type InteractionRequester = <T>(componentName: string, data: any, options?: InteractionRequestOptions, onOpened?: (interactionId: string) => void, ownerPath?: readonly string[], onSettled?: (settled: InteractionSettled) => void) => Promise<T>;
+
+/**
+ * Who answered an interaction, as its requester is told (GENC-1660). `answeredBy` is absent when it
+ * closed unanswered (a timeout or a stop); `decision` is present when an interceptor answered.
+ */
+declare interface InteractionSettled {
+    readonly answeredBy?: string;
+    readonly decision?: DelegatedDecision;
+}
 
 /**
  * A message's interaction widget, in the wrapper that mounts it. Everything the widget is shown
@@ -5373,6 +5864,14 @@ export declare const interactionWrapperTemplate: ViewTemplate<ChatMessage, Found
 /** True when the assistant is active in the layout panel (docked) rather than the bubble. */
 export declare function isAiAssistantDocked(): boolean;
 
+/**
+ * Whether `message` was written or sent on the user's behalf. A delegated message renders as the
+ * assistant, whatever its role.
+ *
+ * @beta
+ */
+export declare const isDelegated: (message: ChatMessage) => message is DelegatedMessage;
+
 /**
  * The interchangeable "assistant is working" loading-indicator styles. At most
  * one of these may be enabled at a time — enabling one disables the other.
@@ -5454,12 +5953,19 @@ export declare const NOOP_ACTIVITY_BUS: ActivityBus;
  * and `ChatDriver`, classifying each user message and routing it to the right
  * specialist — each with its own focused system prompt, tools, and primer.
  *
+ * A {@link BaseDriverDecorator} over the `ChatDriver` it constructs (GENC-1485, GENC-1660): every
+ * `AiDriver` member and event it does not override passes straight through. Its inner driver is
+ * always one it built, never a composition choice, because routing reaches `ChatDriver`-only
+ * members (`installAgent`, `agentSession`, `getHistory`, `setProviderHistoryTransform`, the
+ * release flag and the `report…` exits). Other decorators go outside it.
+ *
  * @beta
  */
-export declare class OrchestratingDriver extends EventTarget implements AiDriver {
+export declare class OrchestratingDriver extends BaseDriverDecorator<ChatDriver> {
     private readonly providerRegistry;
     private readonly agents;
-    private readonly chatDriver;
+    /** The inner driver this one built and routes onto. */
+    private get chatDriver();
     private readonly specialists;
     private readonly fallback?;
     private readonly maxHandoffs;
@@ -5516,80 +6022,14 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
         /** AI service error copy, passed through to the inner ChatDriver (GENC-1611). */
         aiServiceErrorMessages?: Partial<Record<AIServiceRefusal, string>>;
     });
-    resolveInteraction(interactionId: string, result: unknown): void;
-    /** Delegated for the same reason as `resolveInteraction`: the history that owns the
-     *  interaction — and therefore the cost — lives on the wrapped driver, not here. */
-    recordExternalCost(interactionId: string, costUsd: number): boolean;
-    getInteractionContext(interactionId: string): InteractionContext | undefined;
-    isBusy(): boolean;
-    /** Currently active provider name from the underlying ChatDriver. */
-    getActiveProviderName(): string;
-    /**
-     * Pins routing to a specific agent by name. While pinned, the classifier is
-     * skipped and the continuation tool is hidden from the agent's tool list, so
-     * the agent cannot quietly hand back to the orchestrator. Pass `null` to
-     * return to automatic routing.
-     */
-    setPinnedAgent(name: string | null): void;
-    /**
-     * Set the flow-owner lock — used to restore state from Redux on driver
-     * reconstruction (agents-array changes, pop-in/pop-out). Not intended for
-     * external callers to manipulate routing; that's what `setPinnedAgent` is
-     * for.
-     */
-    setFlowOwner(name: string | null): void;
-    loadHistory(messages: ChatMessage[]): void;
-    getRawHistory(): readonly ChatMessage[];
-    /**
-     * Delegates to the inner {@link ChatDriver} — condensation policies are registered there, so it
-     * is the only object that knows which payloads the model has stopped seeing (GENC-1566).
-     *
-     * **This forward is the whole feature, for any multi-agent host.** `AiDriver` declares
-     * `getHistoryForPersistence` optional, and `SessionPersister` calls it through `?.`, falling back
-     * to {@link OrchestratingDriver.getRawHistory}. This class does NOT extend `ChatDriver` — it
-     * wraps one — so without an explicit forward the optional call resolves to `undefined` and every
-     * host on an orchestrating driver silently keeps persisting the full payloads. Measured exactly
-     * that way on a Create run: 10 `context.condensed` events fired, and the session still stored
-     * the two largest `read_context` results at 26,907 and 23,060 chars. The method existed, the
-     * tests passed, and the feature did nothing.
-     */
-    getHistoryForPersistence(): ChatMessage[];
     /**
-     * Delegates to the inner {@link ChatDriver}, which owns the condensation registry and clocks
-     * (GENC-1632). The forward matters for the same reason as `getHistoryForPersistence` above: the
-     * persister reaches it through `?.`, so a missing forward would compile, pass the ChatDriver
-     * tests, and do nothing for every orchestrated host — which is every host with an agents array.
+     * Build the inner driver, after validating the agents' providers, so a bad config throws before
+     * a driver exists to subscribe to the registry. Static because it runs before `super()`.
      */
-    getCondensePoliciesForPersistence(messages: readonly ChatMessage[]): PersistedCondensePolicy[];
-    /**
-     * Delegates to the inner {@link ChatDriver} (GENC-1632). The deferred activation stamp it
-     * performs is taken by the inner driver's `installAgent`, which this driver's own
-     * `installAgent` always reaches, so nothing extra is needed here.
-     */
-    restoreCondensePolicies(entries: readonly unknown[] | undefined): {
-        restored: number;
-        awaitingReactivation: number;
-    };
-    /** {@inheritDoc AiDriver.setContextGuard} */
-    setContextGuard(policy?: ContextGuardPolicy): void;
-    /** {@inheritDoc AiDriver.compact} */
-    compact(options?: CompactionPlanOptions): Promise<ChatMessage | null>;
-    /** {@inheritDoc AiDriver.canCompact} */
-    canCompact(options?: CompactionPlanOptions): boolean;
-    /** {@inheritDoc AiDriver.getPreambleTokens} */
-    getPreambleTokens(): number | undefined;
-    /** {@inheritDoc AiDriver.getCompactionPlan} */
-    getCompactionPlan(options?: CompactionPlanOptions): CompactionProjection | null;
-    /** Delegates to the inner {@link ChatDriver} — turns are captured there. */
-    getTurnSnapshots(): ReadonlyArray<TurnSnapshot>;
-    /** Delegates to the inner {@link ChatDriver} — interactions resolve there, so it holds the buffer. */
-    getExternalDiagnostics(): ReadonlyArray<DiagnosticEntry>;
+    private static createInner;
     getSuggestions(history: ChatMessage[], prompt: string, count: number, allAgentInfo?: AllAgentSummary[]): Promise<string[]>;
-    sendMessage(input: string, attachments?: ChatAttachment[]): Promise<ChatDriverResult>;
+    sendMessage(input: string, attachments?: ChatAttachment[], options?: SendMessageOptions): Promise<ChatDriverResult>;
     private runOrchestratedTurn;
-    continueFromHistory(transientPrimer?: ChatMessage[], options?: ContinueFromHistoryOptions): Promise<ChatDriverResult>;
-    /** {@inheritDoc AiDriver.primeRestoredAgentState} */
-    primeRestoredAgentState(snapshots: Record<string, unknown>): void;
     /** {@inheritDoc AiDriver.canRestoreFlowOwner} */
     canRestoreFlowOwner(agentName: string): boolean;
     /** {@inheritDoc AiDriver.canResumeRestoredFlow} */
@@ -5601,6 +6041,10 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
      * to classify, and a restored lock already says which agent owns the flow. `continueFromHistory`
      * on its own would not do — it neither routes nor installs, so it would run on whatever agent
      * happened to be installed (none, straight after a reload).
+     *
+     * Looks the owner up in its own agents list, so the `agent` argument is not needed and is
+     * ignored; and does not delegate to the inner driver's resume, which would install the agent
+     * undecorated.
      */
     resumeRestoredFlow(resumeNote?: string): Promise<ChatDriverResult | undefined>;
     /**
@@ -5609,13 +6053,11 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
      * Two cases, because routing has two modes and they need opposite answers.
      */
     getContextReserve(): ContextReserveResolution | undefined;
-    /** {@inheritDoc AiDriver.getActiveAgent} */
-    getActiveAgent(): AgentConfig | undefined;
     private installAgent;
     /**
-     * Release the current stateful agent: fire `onDeactivate`, clear the
-     * flow-owner lock, dispatch events so the host (and Redux) reflect the
-     * unlocked state. Called automatically when a tool handler invokes
+     * Release the current stateful agent: fire `onDeactivate` and clear the flow-owner lock. The
+     * inner driver raises the events from the session's transition, so the host (and Redux) reflect
+     * the unlocked state (GENC-1485). Called automatically when a tool handler invokes
      * `context.releaseAgent`.
      *
      * The user-pin (`pinnedAgentName`) is intentionally *not* cleared — a user
@@ -6022,6 +6464,25 @@ export declare type RoutingDecision =
 /** A pin or an active flow owned the turn; the classifier was skipped. */
 | 'pinned';
 
+/**
+ * Options for `AiDriver.sendMessage` (GENC-1660).
+ *
+ * @beta
+ */
+export declare interface SendMessageOptions {
+    /**
+     * Send the message on the user's behalf, as this decorator (e.g. `'autopilot'`). The platform
+     * stamps it on the stored message as `delegate`, so it renders as the assistant and the model
+     * reads it framed.
+     */
+    delegate?: string;
+    /**
+     * The phrase the model reads in front of a delegated message. Defaults to
+     * {@link DEFAULT_DELEGATE_FRAMING}. Ignored unless `delegate` is set.
+     */
+    delegateFraming?: string;
+}
+
 /**
  * `detail` of the `AiAssistantEvent.SessionCleared` event. Captured *before*
  * teardown so a host can tidy up whatever the active agent was working on