@threadplane/chat 0.0.50 → 0.0.52

package/types/threadplane-chat.d.ts

@@ -1,20 +1,63 @@
-import * as _angular_core from '@angular/core';
-import { InjectionToken, Signal, TemplateRef, Type, WritableSignal } from '@angular/core';
 import * as _threadplane_render from '@threadplane/render';
-import { AngularRegistry, StandardSchemaV1, RenderEvent, ViewRegistry, RenderViewEntry, RenderHost, StandardSchemaInferOutput } from '@threadplane/render';
-export { ViewRegistry, toRenderRegistry, views, withViews, withoutViews } from '@threadplane/render';
-import { Observable } from 'rxjs';
+import { StandardSchemaV1, StandardSchemaInferOutput, AngularRegistry, RenderEvent, ViewRegistry, RenderViewEntry, RenderHost } from '@threadplane/render';
+export { StandardSchemaInferInput, StandardSchemaInferOutput, StandardSchemaV1, ViewRegistry, toRenderRegistry, views, withViews, withoutViews } from '@threadplane/render';
+import { A2uiComponentDef, A2uiSurface, A2uiMessage, A2uiActionMessage } from '@threadplane/a2ui';
+export { A2uiAction, A2uiActionContextEntry, A2uiActionMessage, A2uiChildren, A2uiClientDataModel, A2uiComponent, A2uiComponentDef, A2uiSurface, A2uiTheme, DynamicBoolean, DynamicNumber, DynamicString, isLiteralBoolean, isLiteralNumber, isLiteralString, isPathRef } from '@threadplane/a2ui';
+import * as _angular_core from '@angular/core';
+import { Type, InjectionToken, Signal, TemplateRef, WritableSignal, InputSignal, InputSignalWithTransform } from '@angular/core';
 import * as _json_render_core from '@json-render/core';
 import { StateStore, Spec } from '@json-render/core';
+import { Observable } from 'rxjs';
 import * as _threadplane_chat from '@threadplane/chat';
-import { A2uiComponentDef, A2uiSurface, A2uiMessage, A2uiActionMessage } from '@threadplane/a2ui';
-export { A2uiAction, A2uiActionContextEntry, A2uiActionMessage, A2uiChildren, A2uiClientDataModel, A2uiComponent, A2uiComponentDef, A2uiSurface, A2uiTheme, DynamicBoolean, DynamicNumber, DynamicString, isLiteralBoolean, isLiteralNumber, isLiteralString, isPathRef } from '@threadplane/a2ui';
 import { PartialJsonParser } from '@cacheplane/partial-json';
 import { BaseMessage } from '@langchain/core/messages';
 import * as _cacheplane_partial_markdown from '@cacheplane/partial-markdown';
 import { CitationDefinition, MarkdownDocumentNode, MarkdownNode, MarkdownParagraphNode, MarkdownHeadingNode, MarkdownBlockquoteNode, MarkdownListNode, MarkdownListItemNode, MarkdownCodeBlockNode, MarkdownThematicBreakNode, MarkdownTextNode, MarkdownEmphasisNode, MarkdownStrongNode, MarkdownStrikethroughNode, MarkdownInlineCodeNode, MarkdownLinkNode, MarkdownAutolinkNode, MarkdownImageNode, MarkdownSoftBreakNode, MarkdownHardBreakNode, MarkdownCitationReferenceNode, MarkdownTableNode, MarkdownTableRowNode, MarkdownTableCellNode } from '@cacheplane/partial-markdown';
+import { NavigationExtras } from '@angular/router';
 import { DomSanitizer, SafeHtml } from '@angular/platform-browser';
 
+/** Precise authored function tool — what `action()` returns. Carries the schema
+ *  `S` and the handler's resolved return type `R`. */
+interface FunctionToolDef<S extends StandardSchemaV1 = StandardSchemaV1, R = unknown> {
+    readonly kind: 'function';
+    readonly description: string;
+    readonly schema: S;
+    readonly handler: (args: StandardSchemaInferOutput<S>) => R | Promise<R>;
+}
+/** Bivariant union member used only for registry storage/iteration. The handler
+ *  param is `any` (NOT `never`): `any` is simultaneously a supertype any precise
+ *  `FunctionToolDef<S,R>` is assignable to under `strictFunctionTypes`, AND
+ *  callable by internal code that has narrowed by `kind` and parsed runtime args.
+ *  A `never` param would satisfy the former but break the latter. */
+interface AnyFunctionToolDef {
+    readonly kind: 'function';
+    readonly description: string;
+    readonly schema: StandardSchemaV1;
+    readonly handler: (args: any) => unknown | Promise<unknown>;
+}
+interface ViewToolDef<S extends StandardSchemaV1 = StandardSchemaV1, C = unknown> {
+    readonly kind: 'view';
+    readonly description: string;
+    readonly schema: S;
+    readonly component: Type<C>;
+}
+interface AskToolDef<S extends StandardSchemaV1 = StandardSchemaV1, C = unknown> {
+    readonly kind: 'ask';
+    readonly description: string;
+    readonly schema: S;
+    readonly component: Type<C>;
+}
+/** A client tool the model can call; executed in the browser. */
+type ClientToolDef = AnyFunctionToolDef | ViewToolDef | AskToolDef;
+/** A frozen, name-keyed registry of client tools. */
+type ClientToolRegistry = Readonly<Record<string, ClientToolDef>>;
+
+/**
+ * Application-wide options for {@link provideChat}. Every field is optional;
+ * the values are exposed to all chat components in the tree via the
+ * `CHAT_CONFIG` injection token, so you set them once at bootstrap instead of
+ * threading props through every component.
+ */
 interface ChatConfig {
     /** Shared render registry for consumers that read CHAT_CONFIG. */
     renderRegistry?: AngularRegistry;
@@ -39,6 +82,46 @@ interface ChatConfig {
     __licensePublicKey?: Uint8Array;
 }
 declare const CHAT_CONFIG: InjectionToken<ChatConfig>;
+/**
+ * Bootstrap `@threadplane/chat` in an Angular application or standalone
+ * component tree.
+ *
+ * Call this once inside `bootstrapApplication` (or the `providers` array of a
+ * root `ApplicationConfig`). It registers the shared {@link ChatConfig} token
+ * so every chat component in the tree can read the render registry, avatar
+ * label, and assistant display name without explicit prop threading.
+ *
+ * A license check is fired asynchronously on every call (it never throws; a
+ * watermark is shown in non-commercial builds when no valid token is supplied).
+ *
+ * @param config Options bag that controls the chat feature set:
+ *   - `renderRegistry` — shared {@link AngularRegistry} wiring tool-view
+ *     components to their names; pass the value returned by
+ *     `defineAngularRegistry` from `\@threadplane/render`.
+ *   - `avatarLabel` — short label shown in the AI avatar bubble (default `"A"`).
+ *   - `assistantName` — display name shown above assistant messages
+ *     (default `"Assistant"`).
+ *   - `license` — signed token from threadplane.ai; omit in development.
+ * @returns An `EnvironmentProviders` value suitable for the `providers` array
+ *   of `bootstrapApplication` or `ApplicationConfig`.
+ * @example
+ * ```ts
+ * // main.ts
+ * import { bootstrapApplication } from '@angular/platform-browser';
+ * import { provideChat } from '@threadplane/chat';
+ * import { defineAngularRegistry, provideRender } from '@threadplane/render';
+ * import { DayCardComponent } from './day-card.component';
+ *
+ * const registry = defineAngularRegistry({ day_card: DayCardComponent });
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideChat({ renderRegistry: registry, avatarLabel: 'AI' }),
+ *     provideRender({ registry }),
+ *   ],
+ * });
+ * ```
+ */
 declare function provideChat(config: ChatConfig): _angular_core.EnvironmentProviders;
 
 type MessageTemplateType = 'human' | 'ai' | 'tool' | 'system' | 'function';
@@ -121,15 +204,55 @@ interface Message {
      */
     toolCallIds?: string[];
 }
+/**
+ * Type guard narrowing a {@link Message} to `role: 'user'`.
+ *
+ * @param m The message to test.
+ * @returns `true` (and narrows `m`) when the message was sent by the user.
+ * @example
+ * ```ts
+ * const userTurns = agent.messages().filter(isUserMessage);
+ * ```
+ */
 declare function isUserMessage(m: Message): m is Message & {
     role: 'user';
 };
+/**
+ * Type guard narrowing a {@link Message} to `role: 'assistant'`.
+ *
+ * @param m The message to test.
+ * @returns `true` (and narrows `m`) when the message came from the assistant.
+ * @example
+ * ```ts
+ * const reply = agent.messages().findLast(isAssistantMessage);
+ * ```
+ */
 declare function isAssistantMessage(m: Message): m is Message & {
     role: 'assistant';
 };
+/**
+ * Type guard narrowing a {@link Message} to `role: 'tool'` (a tool result turn).
+ *
+ * @param m The message to test.
+ * @returns `true` (and narrows `m`) when the message is a tool result.
+ * @example
+ * ```ts
+ * if (isToolMessage(m)) console.log(m.toolCallId);
+ * ```
+ */
 declare function isToolMessage(m: Message): m is Message & {
     role: 'tool';
 };
+/**
+ * Type guard narrowing a {@link Message} to `role: 'system'`.
+ *
+ * @param m The message to test.
+ * @returns `true` (and narrows `m`) when the message is a system message.
+ * @example
+ * ```ts
+ * const visible = agent.messages().filter((m) => !isSystemMessage(m));
+ * ```
+ */
 declare function isSystemMessage(m: Message): m is Message & {
     role: 'system';
 };
@@ -166,6 +289,12 @@ interface Subagent {
     name?: string;
     status: Signal<SubagentStatus>;
     messages: Signal<Message[]>;
+    /**
+     * The subagent's own tool calls (name/args/result), referenced by
+     * `Message.toolCallIds` in `messages`. Optional: adapters that don't surface
+     * subagent tool calls omit it; consumers default to `[]`.
+     */
+    toolCalls?: Signal<ToolCall[]>;
     state: Signal<Record<string, unknown>>;
 }
 
@@ -246,6 +375,60 @@ interface ClientToolsCapability {
     resolve(toolCallId: string, result: ClientToolResult): void;
 }
 
+/**
+ * The failure class of an {@link AgentError}, used to drive UI and retry logic:
+ *
+ * - `connection` — offline / DNS / connection refused / `fetch` failed. Retryable.
+ * - `auth` — `401` / `403`; credentials or API key are wrong. Not retryable.
+ * - `server` — a `5xx` (retryable) or a non-auth `4xx` like `400`/`404`/`429` (not retryable).
+ * - `interrupted` — the stream closed mid-response after a run had started. Retryable.
+ * - `aborted` — the user pressed stop; treated as a graceful idle, not surfaced as an error.
+ */
+type AgentErrorKind = 'connection' | 'auth' | 'server' | 'interrupted' | 'aborted';
+/**
+ * Structured, classified failure surfaced on `Agent.error`. Extends `Error`, so
+ * existing `.message` / `instanceof Error` reads keep working — but adds a
+ * machine-readable {@link AgentErrorKind}, a `retryable` flag, an optional HTTP
+ * `status`, and the original `cause`.
+ *
+ * You rarely construct one yourself; adapters normalize raw failures via
+ * {@link toAgentError}. Read it off the agent to render legible, cause-specific UI:
+ *
+ * @example
+ * ```ts
+ * const err = agent.error();            // AgentError | undefined
+ * if (err) {
+ *   console.warn(err.message);          // legible, per-kind copy
+ *   if (err.kind === 'auth') showApiKeyHelp();
+ *   if (err.retryable) showRetryButton(); // → agent.retry()
+ * }
+ * ```
+ */
+declare class AgentError extends Error {
+    /** The classified failure type. See {@link AgentErrorKind}. */
+    readonly kind: AgentErrorKind;
+    /** Whether retrying the same request could plausibly succeed:
+     *  `connection` | `server` (5xx) | `interrupted` → true; `auth` | `aborted` | non-auth `4xx` → false. */
+    readonly retryable: boolean;
+    /** The HTTP status code when the failure came from an HTTP response. */
+    readonly status?: number;
+    /** The original raw error this was classified from, preserved for debugging/telemetry. */
+    readonly cause: unknown;
+    constructor(init: {
+        kind: AgentErrorKind;
+        message: string;
+        retryable: boolean;
+        status?: number;
+        cause?: unknown;
+    });
+}
+/**
+ * Default, human-facing copy per {@link AgentErrorKind}. Used as the message when
+ * a classified error has no better text. Override by mapping `error.kind` to your
+ * own strings in a custom error component.
+ */
+declare const AGENT_ERROR_MESSAGES: Record<AgentErrorKind, string>;
+
 /**
  * Runtime-neutral contract chat primitives consume.
  *
@@ -259,15 +442,18 @@ interface ClientToolsCapability {
  * Invariant: state lives on signals; `events$` carries only things that are
  * not derivable from signals.
  */
-interface Agent {
+interface Agent<TState = Record<string, unknown>> {
     messages: Signal<Message[]>;
     status: Signal<AgentStatus>;
     isLoading: Signal<boolean>;
-    error: Signal<unknown>;
+    error: Signal<AgentError | undefined>;
     toolCalls: Signal<ToolCall[]>;
-    state: Signal<Record<string, unknown>>;
+    state: Signal<TState>;
     submit: (input: AgentSubmitInput, opts?: AgentSubmitOptions) => Promise<void>;
     stop: () => Promise<void>;
+    /** Re-run the last submitted input after a failure. No-op if a run is already
+     *  in flight or there is nothing to retry. Clears `error` and sets loading. */
+    retry: () => Promise<void>;
     /**
      * Discards the assistant message at the given index AND all messages after
      * it, then re-runs the agent against the trimmed conversation tail. The
@@ -285,6 +471,37 @@ interface Agent {
     events$: Observable<AgentEvent>;
 }
 
+/**
+ * Whether `raw` represents an abort (a `DOMException`/`Error` named `AbortError`,
+ * or an abort-ish message). Shared by the runtime adapters and {@link toAgentError}
+ * so a user-requested stop settles to idle instead of surfacing as an error.
+ *
+ * @param raw Any thrown/rejected value.
+ * @returns `true` if it looks like an abort.
+ */
+declare function isAbortError(raw: unknown): boolean;
+/**
+ * Classify any raw error into a structured {@link AgentError}.
+ *
+ * Resolution order (first match wins): an existing `AgentError` is returned
+ * unchanged (idempotent) → a user abort → a structured `status`/`cause.status`
+ * → network/connection markers → an HTTP-shaped status in the message → a
+ * `server` + retryable fallback. The original error is always preserved on
+ * `cause`. Runtime adapters call this before setting `Agent.error`; custom
+ * backends can call it too (or throw an `AgentError` directly).
+ *
+ * @param raw Any thrown/rejected value — an `Error`, a `{ status }` object, a string, etc.
+ * @returns The classified {@link AgentError} (kind, retryable, status?, cause).
+ * @example
+ * ```ts
+ * const e = toAgentError(new Error('HTTP 500: Internal Server Error'));
+ * e.kind;      // 'server'
+ * e.retryable; // true
+ * e.status;    // 500
+ * ```
+ */
+declare function toAgentError(raw: unknown): AgentError;
+
 /**
  * Runtime-neutral snapshot of a point in an agent's execution history.
  *
@@ -308,7 +525,7 @@ interface AgentCheckpoint {
  * implement this. Pure request/response runtimes that don't have checkpoints
  * should implement plain Agent.
  */
-interface AgentWithHistory extends Agent {
+interface AgentWithHistory<TState = Record<string, unknown>> extends Agent<TState> {
     history: Signal<AgentCheckpoint[]>;
     /**
      * Optional reactive map of `messageId → checkpointId`, computed by
@@ -320,6 +537,27 @@ interface AgentWithHistory extends Agent {
     messageCheckpoints?: Signal<ReadonlyMap<string, string>>;
 }
 
+/** A typed handle that threads a state shape through Angular DI from
+ *  `provideAgent(ref, …)` to `injectAgent(ref)` without per-call-site
+ *  restatement of the generic. */
+interface AgentRef<TState> {
+    readonly token: InjectionToken<Agent<TState>>;
+}
+/**
+ * Create a typed agent handle.
+ *
+ * @param debugName Optional name shown in Angular DI error messages.
+ * @returns An {@link AgentRef} carrying a state-typed `InjectionToken`.
+ * @example
+ * ```ts
+ * interface TripState { day: number; places: string[]; }
+ * export const TRIP = createAgentRef<TripState>('trip');
+ * // app.config.ts: provideAgent(TRIP, { assistantId: 'trip' })
+ * // component:     const agent = injectAgent(TRIP); // LangGraphAgent<TripState>
+ * ```
+ */
+declare function createAgentRef<TState>(debugName?: string): AgentRef<TState>;
+
 type AgentRuntimeTelemetryEvent = 'ngaf:runtime_instance_created' | 'ngaf:runtime_request_created' | 'ngaf:stream_started' | 'ngaf:stream_ended' | 'ngaf:stream_errored';
 interface AgentRuntimeTelemetryProperties {
     transport: 'langgraph' | 'ag-ui' | 'custom' | string;
@@ -349,7 +587,7 @@ declare class MessageTemplateDirective {
  */
 declare function getMessageType(message: Message): MessageTemplateType;
 declare class ChatMessageListComponent {
-    readonly agent: _angular_core.InputSignal<Agent>;
+    readonly agent: _angular_core.InputSignal<Agent<Record<string, unknown>>>;
     readonly messageTemplates: _angular_core.Signal<readonly MessageTemplateDirective[]>;
     readonly messages: _angular_core.Signal<Message[]>;
     readonly getMessageType: typeof getMessageType;
@@ -484,7 +722,7 @@ declare class ChatSuggestionsComponent {
  */
 declare function submitMessage(agent: Agent, text: string): string | null;
 declare class ChatInputComponent {
-    readonly agent: _angular_core.InputSignal<Agent>;
+    readonly agent: _angular_core.InputSignal<Agent<Record<string, unknown>>>;
     readonly submitOnEnter: _angular_core.InputSignal<boolean>;
     readonly placeholder: _angular_core.InputSignal<string>;
     /** When true (default), shows a stop button while the agent is streaming. */
@@ -522,9 +760,21 @@ declare class ChatInputComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<ChatInputComponent, "chat-input", never, { "agent": { "alias": "agent"; "required": true; "isSignal": true; }; "submitOnEnter": { "alias": "submitOnEnter"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "showStopButton": { "alias": "showStopButton"; "required": false; "isSignal": true; }; }, { "submitted": "submitted"; "stopped": "stopped"; }, never, ["[chatInputBanner]", "[chatInputAttachments]", "[chatInputLeading]", "[chatInputModelSelect]", "[chatInputTrailing]", "[chatInputFooter]"], true, never>;
 }
 
+/**
+ * Whether the agent should show a "typing" indicator — it is loading and has
+ * not yet started streaming the assistant's reply.
+ *
+ * @param agent The agent to inspect.
+ * @returns `true` while the agent is awaiting a response but no assistant text
+ *   has streamed yet; `false` once tokens arrive or the agent is idle.
+ * @example
+ * ```ts
+ * \@if (isTyping(agent)) { <chat-typing-indicator [agent]="agent" /> }
+ * ```
+ */
 declare function isTyping(agent: Agent): boolean;
 declare class ChatTypingIndicatorComponent {
-    readonly agent: _angular_core.InputSignal<Agent>;
+    readonly agent: _angular_core.InputSignal<Agent<Record<string, unknown>>>;
     readonly visible: _angular_core.Signal<boolean>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ChatTypingIndicatorComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<ChatTypingIndicatorComponent, "chat-typing-indicator", never, { "agent": { "alias": "agent"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
@@ -620,15 +870,26 @@ declare class ChatScrollBubbleComponent {
 
 declare function extractErrorMessage(error: unknown): string | null;
 declare class ChatErrorComponent {
-    readonly agent: _angular_core.InputSignal<Agent>;
-    readonly errorMessage: _angular_core.Signal<string | null>;
+    readonly agent: _angular_core.InputSignal<Agent<Record<string, unknown>>>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ChatErrorComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<ChatErrorComponent, "chat-error", never, { "agent": { "alias": "agent"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
+/**
+ * Read the agent's current human-in-the-loop interrupt, if any.
+ *
+ * @param agent The agent to inspect.
+ * @returns The pending {@link AgentInterrupt}, or `undefined` when the agent is
+ *   not currently waiting on an interrupt.
+ * @example
+ * ```ts
+ * const interrupt = getInterrupt(agent);
+ * if (interrupt) agent.resume('approved');
+ * ```
+ */
 declare function getInterrupt(agent: Agent): AgentInterrupt | undefined;
 declare class ChatInterruptComponent {
-    readonly agent: _angular_core.InputSignal<Agent>;
+    readonly agent: _angular_core.InputSignal<Agent<Record<string, unknown>>>;
     readonly templateRef: _angular_core.Signal<TemplateRef<any> | undefined>;
     readonly interrupt: _angular_core.Signal<AgentInterrupt | undefined>;
     defaultText(i: AgentInterrupt): string;
@@ -695,9 +956,11 @@ interface Group {
     name: string;
     calls: ToolCall[];
     templateRef?: ChatToolCallTemplateDirective;
+    /** Present when this group anchors a subagent spawned by its (single) task call. */
+    subagent?: Subagent;
 }
 declare class ChatToolCallsComponent {
-    readonly agent: _angular_core.InputSignal<Agent>;
+    readonly agent: _angular_core.InputSignal<Agent<Record<string, unknown>>>;
     readonly message: _angular_core.InputSignal<Message | undefined>;
     readonly grouping: _angular_core.InputSignal<"auto" | "none">;
     readonly groupSummary: _angular_core.InputSignal<((name: string, count: number) => string) | undefined>;
@@ -736,7 +999,7 @@ declare class ChatToolCallsComponent {
  * (and a `status` a component chooses not to declare) are harmless.
  */
 declare class ChatToolViewsComponent {
-    readonly agent: _angular_core.InputSignal<Agent>;
+    readonly agent: _angular_core.InputSignal<Agent<Record<string, unknown>>>;
     readonly events: _angular_core.OutputEmitterRef<RenderEvent>;
     readonly message: _angular_core.InputSignal<Message | undefined>;
     readonly views: _angular_core.InputSignal<Readonly<Record<string, _angular_core.Type<unknown> | _threadplane_render.RenderViewEntry>> | undefined>;
@@ -753,7 +1016,7 @@ declare class ChatToolViewsComponent {
 }
 
 declare class ChatSubagentsComponent {
-    readonly agent: _angular_core.InputSignal<Agent>;
+    readonly agent: _angular_core.InputSignal<Agent<Record<string, unknown>>>;
     readonly templateRef: _angular_core.Signal<TemplateRef<any> | undefined>;
     readonly activeSubagents: _angular_core.Signal<Subagent[]>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ChatSubagentsComponent, never>;
@@ -959,7 +1222,7 @@ declare class ChatGenuiSkeletonComponent {
 }
 
 declare class ChatTimelineComponent {
-    readonly agent: _angular_core.InputSignal<AgentWithHistory>;
+    readonly agent: _angular_core.InputSignal<AgentWithHistory<Record<string, unknown>>>;
     readonly checkpointSelected: _angular_core.OutputEmitterRef<AgentCheckpoint>;
     readonly templateRef: _angular_core.Signal<TemplateRef<any> | undefined>;
     readonly history: _angular_core.Signal<AgentCheckpoint[]>;
@@ -1013,14 +1276,17 @@ declare class ChatWelcomeComponent {
 declare class ChatWelcomeSuggestionComponent {
     readonly label: _angular_core.InputSignal<string>;
     readonly value: _angular_core.InputSignal<string>;
+    /** Optional short description, surfaced as a hover/focus tooltip on the chip. */
+    readonly description: _angular_core.InputSignal<string | undefined>;
     readonly selected: _angular_core.OutputEmitterRef<string>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ChatWelcomeSuggestionComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ChatWelcomeSuggestionComponent, "chat-welcome-suggestion", never, { "label": { "alias": "label"; "required": true; "isSignal": true; }; "value": { "alias": "value"; "required": true; "isSignal": true; }; }, { "selected": "selected"; }, never, ["[chatWelcomeSuggestionIcon]"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ChatWelcomeSuggestionComponent, "chat-welcome-suggestion", never, { "label": { "alias": "label"; "required": true; "isSignal": true; }; "value": { "alias": "value"; "required": true; "isSignal": true; }; "description": { "alias": "description"; "required": false; "isSignal": true; }; }, { "selected": "selected"; }, never, ["[chatWelcomeSuggestionIcon]"], true, never>;
 }
 
 interface ChatSelectOption {
     value: string;
     label: string;
+    description?: string;
     disabled?: boolean;
 }
 /**
@@ -1101,6 +1367,35 @@ declare class ChatCitationsCardComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<ChatCitationsCardComponent, "chat-citations-card", never, { "citation": { "alias": "citation"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
+interface ThreadRoutingConfig {
+    /** The app-owned source-of-truth signal for the active thread id. */
+    threadId: WritableSignal<string | null>;
+    /** Router commands for a thread id (or the bare/welcome path when null).
+     *  Default: `(id) => (id ? ['/', id] : ['/'])`. */
+    toCommands?: (id: string | null) => unknown[];
+    /** Extract the thread id from a URL (null = bare). Default: last non-empty path segment. */
+    threadIdFromUrl?: (url: string) => string | null;
+    /** Optional async validity check; on `false` the helper redirects to the bare path
+     *  (`replaceUrl: true`). LangGraph apps pass `id => threads.getThread(id).then(Boolean)`. */
+    validate?: (id: string) => Promise<boolean>;
+    /** Extras merged into every navigate (default `{ queryParamsHandling: 'preserve' }`). */
+    navigationExtras?: NavigationExtras;
+}
+/**
+ * Bind an app-owned `activeThreadId` signal to the URL — restore on load, stamp on change,
+ * validate-or-redirect, with a bare URL meaning "no thread" (welcome). URL is the source of
+ * truth; nothing is written to localStorage. Must be called in an injection context.
+ *
+ * @example
+ * ```ts
+ * export const ACTIVE_THREAD = signal<string | null>(null);
+ * // providers: provideAgent({ threadId: ACTIVE_THREAD, onThreadId: id => ACTIVE_THREAD.set(id) })
+ * const threads = inject(LangGraphThreadsAdapter);
+ * injectThreadRouting({ threadId: ACTIVE_THREAD, validate: id => threads.getThread(id).then(Boolean) });
+ * ```
+ */
+declare function injectThreadRouting(config: ThreadRoutingConfig): void;
+
 interface ChatLifecycle {
     /** True after `<chat>` initializes with a non-null agent binding. */
     readonly componentReady: Signal<boolean>;
@@ -1124,6 +1419,21 @@ interface ParseTreeStore {
     readonly spec: Signal<Spec | null>;
     readonly elementStates: Signal<Map<string, ElementAccumulationState>>;
 }
+/**
+ * Create a {@link ParseTreeStore} — feeds streamed JSON chunks through a
+ * partial-JSON parser and exposes the progressively-materialized spec and
+ * per-element accumulation state as signals, so a generative-UI surface can
+ * render while the spec is still arriving.
+ *
+ * @param parser The partial-JSON parser used to incrementally materialize chunks.
+ * @returns A {@link ParseTreeStore}; call `push(chunk)` as bytes stream in.
+ * @example
+ * ```ts
+ * const store = createParseTreeStore(parser);
+ * store.push('{"type":"Car');
+ * store.spec(); // best-effort Spec | null
+ * ```
+ */
 declare function createParseTreeStore(parser: PartialJsonParser): ParseTreeStore;
 
 /** Chat-internal projection of an A2UI component, materialized by the
@@ -1178,6 +1488,19 @@ interface A2uiSurfaceStore {
     readonly surfaceStates: Signal<Map<string, A2uiSurfaceState>>;
     surfaceState(surfaceId: string): Signal<A2uiSurfaceState | undefined>;
 }
+/**
+ * Create an {@link A2uiSurfaceStore} — the per-conversation store that buffers
+ * streamed A2UI surface updates, tracks each surface's data model + lifecycle
+ * state, and exposes them as signals for rendering. One store backs a chat
+ * thread's A2UI surfaces.
+ *
+ * @returns A fresh, empty {@link A2uiSurfaceStore}.
+ * @example
+ * ```ts
+ * const store = createA2uiSurfaceStore();
+ * const surfaces = store.surfaces; // Signal<Map<string, A2uiSurface>>
+ * ```
+ */
 declare function createA2uiSurfaceStore(): A2uiSurfaceStore;
 
 type ContentType = 'pending' | 'markdown' | 'json-render' | 'a2ui' | 'mixed';
@@ -1193,6 +1516,19 @@ interface ContentClassifier {
     readonly errors: Signal<string[]>;
     dispose(): void;
 }
+/**
+ * Create a {@link ContentClassifier} — the streaming accumulator that inspects
+ * an assistant message's content as it arrives and classifies it (markdown vs a
+ * generative-UI/A2UI spec), exposing the parsed result and per-element state as
+ * signals so the renderer can switch modes mid-stream.
+ *
+ * @returns A fresh {@link ContentClassifier}; call `dispose()` when done.
+ * @example
+ * ```ts
+ * const cc = createContentClassifier();
+ * effect(() => console.log(cc.type())); // 'pending' | 'markdown' | 'spec'
+ * ```
+ */
 declare function createContentClassifier(): ContentClassifier;
 
 /**
@@ -1214,7 +1550,7 @@ interface ChatRenderEvent {
 }
 
 declare class ChatComponent {
-    readonly agent: _angular_core.InputSignal<Agent>;
+    readonly agent: _angular_core.InputSignal<Agent<Record<string, unknown>>>;
     readonly views: _angular_core.InputSignal<Readonly<Record<string, _angular_core.Type<unknown> | _threadplane_render.RenderViewEntry>> | undefined>;
     /**
      * Client-declared tools (`view`/`ask`/`function`) the model may call. When
@@ -1421,7 +1757,7 @@ declare class ChatComponent {
 }
 
 declare class ChatPopupComponent {
-    readonly agent: _angular_core.InputSignal<Agent>;
+    readonly agent: _angular_core.InputSignal<Agent<Record<string, unknown>>>;
     /** A2UI component catalog forwarded to the inner <chat>. Without it,
      * messages classified as A2UI parse correctly but never mount a
      * surface. Pass `a2uiBasicCatalog()` from `@threadplane/chat`. */
@@ -1461,7 +1797,7 @@ declare class ChatPopupComponent {
 }
 
 declare class ChatSidebarComponent {
-    readonly agent: _angular_core.InputSignal<Agent>;
+    readonly agent: _angular_core.InputSignal<Agent<Record<string, unknown>>>;
     /** A2UI component catalog forwarded to the inner <chat>. Without it,
      * messages classified as A2UI parse correctly but never mount a
      * surface. Pass `a2uiBasicCatalog()` from `@threadplane/chat`. */
@@ -1495,7 +1831,7 @@ declare class ChatSidebarComponent {
 }
 
 declare class ChatTimelineSliderComponent {
-    readonly agent: _angular_core.InputSignal<AgentWithHistory>;
+    readonly agent: _angular_core.InputSignal<AgentWithHistory<Record<string, unknown>>>;
     readonly selectedIndex: _angular_core.WritableSignal<number>;
     readonly history: _angular_core.Signal<AgentCheckpoint[]>;
     readonly replayRequested: _angular_core.OutputEmitterRef<string>;
@@ -1517,7 +1853,7 @@ declare class ChatSidenavComponent {
     readonly projects: _angular_core.InputSignal<Project[] | null>;
     readonly selectedProjectId: _angular_core.InputSignal<string | null>;
     readonly projectActions: _angular_core.InputSignal<ProjectActionAdapter | null>;
-    readonly agent: _angular_core.InputSignal<Agent | AgentWithHistory | null>;
+    readonly agent: _angular_core.InputSignal<Agent<Record<string, unknown>> | AgentWithHistory<Record<string, unknown>> | null>;
     readonly debug: _angular_core.InputSignal<boolean>;
     readonly newChat: _angular_core.OutputEmitterRef<void>;
     readonly threadSelected: _angular_core.OutputEmitterRef<string>;
@@ -1568,7 +1904,7 @@ declare class ChatSidenavScrimComponent {
 
 type InterruptAction = 'accept' | 'edit' | 'respond' | 'ignore';
 declare class ChatInterruptPanelComponent {
-    readonly agent: _angular_core.InputSignal<Agent>;
+    readonly agent: _angular_core.InputSignal<Agent<Record<string, unknown>>>;
     readonly action: _angular_core.OutputEmitterRef<InterruptAction>;
     readonly interrupt: _angular_core.Signal<AgentInterrupt | undefined>;
     readonly interruptReason: _angular_core.Signal<string>;
@@ -1578,7 +1914,7 @@ declare class ChatInterruptPanelComponent {
 
 type ChatApprovalAction = 'approve' | 'edit' | 'cancel';
 declare class ChatApprovalCardComponent {
-    readonly agent: _angular_core.InputSignal<Agent>;
+    readonly agent: _angular_core.InputSignal<Agent<Record<string, unknown>>>;
     readonly matchKind: _angular_core.InputSignal<string | undefined>;
     readonly title: _angular_core.InputSignal<string>;
     readonly showEdit: _angular_core.InputSignal<boolean>;
@@ -1608,7 +1944,9 @@ declare function statusColor(status: SubagentStatus): string;
 declare class ChatSubagentCardComponent {
     readonly subagent: _angular_core.InputSignal<Subagent>;
     readonly state: _angular_core.Signal<TraceState>;
-    readonly latestMessageContent: _angular_core.Signal<string>;
+    protected textOf(m: Message): string;
+    protected toolCallsFor(m: Message): ToolCall[];
+    protected toToolCallInfo(tc: ToolCall): ToolCallInfo;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ChatSubagentCardComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<ChatSubagentCardComponent, "chat-subagent-card", never, { "subagent": { "alias": "subagent"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
@@ -1844,8 +2182,6 @@ declare class MarkdownTableCellComponent {
  */
 declare const IS_HEADER_ROW: InjectionToken<Signal<boolean>>;
 
-declare const CHAT_MARKDOWN_STYLES = "\n  chat-streaming-md { display: block; color: var(--ngaf-chat-text); line-height: var(--ngaf-chat-line-height); }\n\n  /* Headings */\n  chat-streaming-md h1, chat-streaming-md h2, chat-streaming-md h3, chat-streaming-md h4, chat-streaming-md h5, chat-streaming-md h6 {\n    font-weight: 600;\n    line-height: 1.25;\n    margin: 1.25rem 0 0.75rem;\n  }\n  chat-streaming-md h1:first-child, chat-streaming-md h2:first-child, chat-streaming-md h3:first-child,\n  chat-streaming-md h4:first-child, chat-streaming-md h5:first-child, chat-streaming-md h6:first-child { margin-top: 0; }\n  chat-streaming-md h1 { font-size: 1.5em; font-weight: 700; }\n  chat-streaming-md h2 { font-size: 1.25em; }\n  chat-streaming-md h3 { font-size: 1.1em; }\n  chat-streaming-md h4 { font-size: 1em; }\n  chat-streaming-md h5, chat-streaming-md h6 { font-size: 0.95em; color: var(--ngaf-chat-text-muted); }\n\n  /* Paragraphs and inline emphasis */\n  chat-streaming-md p { margin: 0 0 0.75rem; line-height: 1.6; font-size: var(--ngaf-chat-font-size); }\n  chat-streaming-md p:last-child { margin-bottom: 0; }\n  chat-streaming-md strong, chat-streaming-md b { font-weight: 700; }\n  chat-streaming-md em, chat-streaming-md i { font-style: italic; }\n  chat-streaming-md del, chat-streaming-md s { text-decoration: line-through; color: var(--ngaf-chat-text-muted); }\n  chat-streaming-md mark { background: var(--ngaf-chat-surface-alt); padding: 0 2px; border-radius: 2px; }\n  chat-streaming-md sub { font-size: 0.75em; vertical-align: sub; }\n  chat-streaming-md sup { font-size: 0.75em; vertical-align: super; }\n\n  /* Links */\n  chat-streaming-md a { color: var(--ngaf-chat-primary); text-decoration: underline; text-underline-offset: 2px; }\n  chat-streaming-md a:hover { text-decoration-thickness: 2px; }\n\n  /* Lists (CommonMark + GFM task lists) */\n  chat-streaming-md ul, chat-streaming-md ol { margin: 0 0 0.75rem; padding-left: 1.5rem; }\n  chat-streaming-md ul { list-style: disc outside; }\n  chat-streaming-md ol { list-style: decimal outside; }\n  chat-streaming-md ul ul { list-style: circle outside; }\n  chat-streaming-md ul ul ul { list-style: square outside; }\n  chat-streaming-md li { margin: 0.2rem 0; }\n  chat-streaming-md li::marker { color: var(--ngaf-chat-text-muted); }\n  chat-streaming-md li > p { margin: 0 0 0.25rem; }\n  chat-streaming-md li > ul, chat-streaming-md li > ol { margin: 0.25rem 0 0; }\n  /* GFM task lists: marked emits <li><input type=\"checkbox\" disabled> ... */\n  chat-streaming-md li:has(> input[type=\"checkbox\"]) { list-style: none; margin-left: -1.25rem; }\n  chat-streaming-md li > input[type=\"checkbox\"] { margin-right: 0.5rem; vertical-align: middle; }\n\n  /* Code (inline + fenced) */\n  chat-streaming-md code {\n    background: var(--ngaf-chat-surface-alt);\n    color: var(--ngaf-chat-text);\n    padding: 1px 5px;\n    border-radius: 4px;\n    font-family: var(--ngaf-chat-font-mono);\n    font-size: 0.9em;\n  }\n  chat-streaming-md pre {\n    background: var(--ngaf-chat-surface-alt);\n    color: var(--ngaf-chat-text);\n    padding: 12px 14px;\n    border-radius: var(--ngaf-chat-radius-card);\n    overflow-x: auto;\n    font-family: var(--ngaf-chat-font-mono);\n    font-size: var(--ngaf-chat-font-size-sm);\n    line-height: 1.5;\n    margin: 0 0 0.75rem;\n  }\n  chat-streaming-md pre code { background: transparent; padding: 0; border-radius: 0; font-size: inherit; }\n\n  /* Blockquote */\n  chat-streaming-md blockquote {\n    border-left: 3px solid var(--ngaf-chat-separator);\n    padding: 0.25rem 0 0.25rem 12px;\n    margin: 0 0 0.75rem;\n    color: var(--ngaf-chat-text-muted);\n  }\n  chat-streaming-md blockquote > :last-child { margin-bottom: 0; }\n\n  /* Horizontal rule */\n  chat-streaming-md hr {\n    border: none;\n    border-top: 1px solid var(--ngaf-chat-separator);\n    margin: 1rem 0;\n  }\n\n  /* Tables (GFM) */\n  chat-streaming-md table {\n    border-collapse: collapse;\n    margin: 0 0 0.75rem;\n    width: 100%;\n    font-size: 0.95em;\n  }\n  chat-streaming-md thead { background: var(--ngaf-chat-surface-alt); }\n  chat-streaming-md th, chat-streaming-md td {\n    border: 1px solid var(--ngaf-chat-separator);\n    padding: 6px 10px;\n    text-align: left;\n    vertical-align: top;\n  }\n  chat-streaming-md th { font-weight: 600; }\n  /* Component-rendered table: chat-md-table becomes a horizontally-scrollable\n     wrapper for the inner <table>; row/cell elements stay layout-transparent\n     so the browser's table layout takes over. Without this overflow wrapper,\n     wide tables push their parent container past the viewport horizontally. */\n  chat-streaming-md chat-md-table {\n    display: block;\n    overflow-x: auto;\n    max-width: 100%;\n    margin: 0 0 0.75rem;\n  }\n  chat-streaming-md chat-md-table-row { display: contents; }\n  chat-streaming-md chat-md-table-cell { display: contents; }\n  chat-streaming-md chat-md-table > table { margin: 0; }\n  /* Task-list items: checkbox + first paragraph render inline; subsequent\n     blocks (sub-lists, multi-paragraph items) flow normally below. */\n  chat-streaming-md li.chat-md-list-item--task {\n    list-style: none;\n    margin-left: -1.25rem;\n    display: flex;\n    flex-wrap: wrap;\n    align-items: baseline;\n    gap: 0.5rem;\n  }\n  chat-streaming-md li.chat-md-list-item--task > input[type=\"checkbox\"] {\n    margin: 0;\n    flex: 0 0 auto;\n    transform: translateY(2px);\n  }\n  /* The chat-md-children wrapper around list-item content takes remaining width */\n  chat-streaming-md li.chat-md-list-item--task > chat-md-children {\n    flex: 1 1 auto;\n    min-width: 0;\n  }\n  /* Tight task items: only the FIRST paragraph aligns inline with the\n     checkbox (margin collapsed). Subsequent paragraphs/blocks keep their\n     normal vertical spacing so multi-block items render readably. */\n  chat-streaming-md li.chat-md-list-item--task > chat-md-children > chat-md-paragraph:first-child > p {\n    margin: 0;\n  }\n\n  /* Media */\n  chat-streaming-md img { max-width: 100%; height: auto; border-radius: 6px; }\n  /* Broken-image fallback: muted pill showing alt text + icon. Triggered\n     when <img> fires (error). Caught by live browser smoke \u2014 prior impl\n     showed only the browser's broken-image icon with no readable alt. */\n  chat-streaming-md .chat-md-image--broken {\n    display: inline-flex;\n    align-items: center;\n    gap: 0.4rem;\n    padding: 0.25rem 0.5rem;\n    background: var(--ngaf-chat-surface-alt);\n    border: 1px dashed var(--ngaf-chat-separator);\n    border-radius: 6px;\n    font-size: 0.9em;\n    color: var(--ngaf-chat-text-muted, currentColor);\n    opacity: 0.85;\n  }\n  chat-streaming-md .chat-md-image__icon { font-size: 1em; line-height: 1; }\n  chat-streaming-md .chat-md-image__alt { font-style: italic; }\n";
-
 /**
  * Renders markdown content to sanitized HTML.
  * Falls back to plain text with newline->br conversion if `marked` is not installed.
@@ -1865,21 +2201,6 @@ declare function renderMarkdown(content: string, sanitizer: DomSanitizer): SafeH
  */
 declare function formatDuration(ms: number): string;
 
-/** Chevron down (▼ replacement). 12x12, stroke-based. */
-declare const ICON_CHEVRON_DOWN = "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"12\" height=\"12\" viewBox=\"0 0 12 12\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M3 4.5L6 7.5L9 4.5\"/></svg>";
-/** Chevron up (▲ replacement). 12x12, stroke-based. */
-declare const ICON_CHEVRON_UP = "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"12\" height=\"12\" viewBox=\"0 0 12 12\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M3 7.5L6 4.5L9 7.5\"/></svg>";
-/** Gear icon (⚙ replacement). 14x14. */
-declare const ICON_TOOL = "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"14\" height=\"14\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><circle cx=\"12\" cy=\"12\" r=\"3\"/><path d=\"M12 1v2M12 21v2M4.22 4.22l1.42 1.42M18.36 18.36l1.42 1.42M1 12h2M21 12h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42\"/></svg>";
-/** Warning triangle (⚠ replacement). 18x18. */
-declare const ICON_WARNING = "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"18\" height=\"18\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z\"/><line x1=\"12\" y1=\"9\" x2=\"12\" y2=\"13\"/><line x1=\"12\" y1=\"17\" x2=\"12.01\" y2=\"17\"/></svg>";
-/** Robot/agent icon (replacement). 14x14. */
-declare const ICON_AGENT = "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"14\" height=\"14\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><rect x=\"3\" y=\"11\" width=\"18\" height=\"10\" rx=\"2\"/><circle cx=\"12\" cy=\"5\" r=\"2\"/><path d=\"M12 7v4\"/><line x1=\"8\" y1=\"16\" x2=\"8\" y2=\"16\"/><line x1=\"16\" y1=\"16\" x2=\"16\" y2=\"16\"/></svg>";
-/** Check mark replacement. 12x12. */
-declare const ICON_CHECK = "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"12\" height=\"12\" viewBox=\"0 0 12 12\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M2.5 6L5 8.5L9.5 3.5\"/></svg>";
-/** Send arrow (for chat input). 16x16. */
-declare const ICON_SEND = "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"16\" height=\"16\" viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M8 12V4M8 4L4 8M8 4L12 8\"/></svg>";
-
 /** Catalog entry for the A2UI surface renderer.
  *
  * `component` is mounted once all of the component's bindings (data
@@ -1997,14 +2318,24 @@ declare class A2uiSurfaceComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<A2uiSurfaceComponent, "a2ui-surface", never, { "surface": { "alias": "surface"; "required": false; "isSignal": true; }; "state": { "alias": "state"; "required": false; "isSignal": true; }; "catalog": { "alias": "catalog"; "required": true; "isSignal": true; }; "handlers": { "alias": "handlers"; "required": false; "isSignal": true; }; "surfaceFallback": { "alias": "surfaceFallback"; "required": false; "isSignal": true; }; }, { "events": "events"; "action": "action"; }, never, never, true, never>;
 }
 
-declare function surfaceToSpec(surface: A2uiSurface): Spec | null;
-
 /** Builds an A2uiActionMessage from handler params and the current surface.
  *  The action.context is serialized as v1 DynamicValue-wrapped entries.
  *  Sets action.label when the source component is a Button with a Text
  *  child whose literalString is non-empty. */
 declare function buildA2uiActionMessage(params: Record<string, unknown>, surface: A2uiSurface): A2uiActionMessage;
 
+/**
+ * Build the built-in A2UI component catalog — a {@link ViewRegistry} mapping
+ * the standard A2UI element types (Card, Button, TextField, Image, AudioPlayer,
+ * Video, …) to their Angular renderers. Spread it into `provideViews` (with any
+ * of your own views) so an agent's A2UI surface specs render.
+ *
+ * @returns A {@link ViewRegistry} of the standard A2UI components.
+ * @example
+ * ```ts
+ * providers: [provideViews({ ...a2uiBasicCatalog(), MyWidget: MyWidgetComponent })]
+ * ```
+ */
 declare function a2uiBasicCatalog(): ViewRegistry;
 
 /** Writes a typed value to the render state store if the prop has a binding path. */
@@ -2348,37 +2679,164 @@ declare class A2uiVideoComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<A2uiVideoComponent, "a2ui-video", never, { "url": { "alias": "url"; "required": false; "isSignal": true; }; "autoPlay": { "alias": "autoPlay"; "required": false; "isSignal": true; }; "controls": { "alias": "controls"; "required": false; "isSignal": true; }; "bindings": { "alias": "bindings"; "required": false; "isSignal": true; }; "emit": { "alias": "emit"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "childKeys": { "alias": "childKeys"; "required": false; "isSignal": true; }; "spec": { "alias": "spec"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-/** A client tool the model can call; executed in the browser. */
-type ClientToolDef = FunctionToolDef | ViewToolDef | AskToolDef;
-interface FunctionToolDef<S extends StandardSchemaV1 = StandardSchemaV1> {
-    readonly kind: 'function';
-    readonly description: string;
-    readonly schema: S;
-    readonly handler: (args: StandardSchemaInferOutput<S>) => unknown | Promise<unknown>;
-}
-interface ViewToolDef {
-    readonly kind: 'view';
-    readonly description: string;
-    readonly schema: StandardSchemaV1;
-    readonly component: Type<unknown>;
-}
-interface AskToolDef {
-    readonly kind: 'ask';
-    readonly description: string;
-    readonly schema: StandardSchemaV1;
-    readonly component: Type<unknown>;
-}
-/** A frozen, name-keyed registry of client tools. */
-type ClientToolRegistry = Readonly<Record<string, ClientToolDef>>;
+/**
+ * @internal
+ * Identity mapped type that flattens an object type so editor quick-info shows
+ * the expanded shape instead of a raw conditional/mapped-type expression.
+ */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
 
-/** Async function tool — its resolved return value becomes the tool result. */
-declare function action<S extends StandardSchemaV1>(description: string, schema: S, handler: (args: StandardSchemaInferOutput<S>) => unknown | Promise<unknown>): FunctionToolDef<S>;
-/** Render-only component tool — the model fills its props; auto-acknowledged. */
-declare function view(description: string, schema: StandardSchemaV1, component: Type<unknown>): ClientToolDef;
-/** Interactive (HITL) component tool — the value it emits becomes the result. */
-declare function ask(description: string, schema: StandardSchemaV1, component: Type<unknown>): ClientToolDef;
-/** Collect named client tools into a frozen registry (the key is the tool name). */
-declare function tools(map: Record<string, ClientToolDef>): ClientToolRegistry;
+/** Value type carried by an Angular signal input. */
+type InputValue<P> = P extends InputSignal<infer T> ? T : P extends InputSignalWithTransform<infer T, infer _U> ? T : never;
+/** A component instance's declared signal inputs, as a plain prop bag.
+ *
+ *  Implementation note: Angular's `InputSignal` and `InputSignalWithTransform`
+ *  use `InputSignalNode` in an invariant position, making them invariant in their
+ *  type parameters under TypeScript's structural system. `InputSignal<number>`
+ *  does NOT extend `InputSignal<unknown>`. We therefore use `any` in the filter
+ *  predicate — `any` is a two-way assignability wildcard that correctly subsumes
+ *  all concrete instantiations without widening the extracted value type. */
+type ComponentInputs<C> = {
+    [K in keyof C as C[K] extends InputSignal<any> | InputSignalWithTransform<any, any> ? K : never]: InputValue<C[K]>;
+};
+/** STRICT: every prop the schema PRODUCES must be a declared input with an
+ *  assignable type. FLEXIBLE: the component may declare extra inputs the schema
+ *  doesn't fill. A schema key absent from `Inputs` maps to `never`, so its
+ *  (non-never) value fails assignment and the error pins to that prop.
+ *
+ *  This mapped type is homomorphic over `keyof Out`, so it preserves the
+ *  optionality (`?`) of each schema prop. A consequence: an OPTIONAL schema prop
+ *  is accepted against a `required` component input — the compiler cannot know
+ *  the model will actually supply it. That residual case (required input not
+ *  guaranteed by the schema) is caught at runtime by the schema-readiness mount
+ *  gate, which holds the fallback until the streamed props validate. Compile
+ *  time blocks structural mismatches; runtime blocks missing-but-required props. */
+type CompatibleProps<Out, Inputs> = {
+    [K in keyof Out]: K extends keyof Inputs ? Inputs[K] : never;
+};
+/** The accepted `component` parameter type for `view`/`ask`: the real component
+ *  `Type<C>` when the schema output is compatible, else a labelled error tuple
+ *  that surfaces both shapes in the compiler message.
+ *
+ *  Implementation note: `C extends ...` (distributive over C) lets TypeScript
+ *  infer `C` from the `Type<C>` arm first, then verify the constraint. A bare
+ *  conditional on the param type blocks inference when C appears only on the
+ *  right-hand side of the inner `extends`. */
+type AcceptComponent<S extends StandardSchemaV1, C> = C extends (StandardSchemaInferOutput<S> extends CompatibleProps<StandardSchemaInferOutput<S>, ComponentInputs<C>> ? C : never) ? Type<C> : readonly [
+    'Schema output is not assignable to this component\'s inputs',
+    StandardSchemaInferOutput<S>,
+    ComponentInputs<C>
+];
+/** Reverse helper: derive a component's input prop types FROM a schema, so a
+ *  component authored straight from the schema is guaranteed compatible. */
+type ViewProps<S extends StandardSchemaV1> = Prettify<StandardSchemaInferOutput<S>>;
+
+/**
+ * Declare an async function tool the model can call; its resolved return value
+ * becomes the tool result shipped back to the model.
+ *
+ * @param description Natural-language description the model sees.
+ * @param schema Standard Schema (e.g. a Zod object) for the arguments; the
+ *   handler's argument type is inferred from it.
+ * @param handler Runs in the browser when the model calls the tool; its return
+ *   type `R` is carried on the resulting {@link FunctionToolDef}.
+ * @returns A {@link FunctionToolDef} for inclusion in {@link tools}.
+ * @example
+ * ```ts
+ * const move = action('Move a stop', z.object({ fromDay: z.number() }), (a) => a.fromDay);
+ * const registry = tools({ move_stop: move });
+ * ```
+ */
+declare function action<S extends StandardSchemaV1, R>(description: string, schema: S, handler: (args: StandardSchemaInferOutput<S>) => R | Promise<R>): FunctionToolDef<S, R>;
+/**
+ * Render-only component tool — the model fills the component's props from the
+ * schema's output; the tool call is auto-acknowledged once the component mounts.
+ *
+ * The component's signal inputs are checked against the schema output type
+ * (strict-but-flexible: every schema key must be a declared input with an
+ * assignable type; the component may declare extra inputs the schema doesn't fill).
+ * Author the component with `ViewProps<typeof schema>` as the input type set to
+ * guarantee the shapes stay aligned.
+ *
+ * @param description Natural-language description the model sees.
+ * @param schema Standard Schema defining the props the model must supply.
+ * @param component Angular component whose signal inputs must be compatible with
+ *   the schema output. A type-level error is reported here when they diverge.
+ * @returns A {@link ViewToolDef} for inclusion in {@link tools}.
+ * @example
+ * ```ts
+ * const schema = z.object({ label: z.string(), day: z.number() });
+ * type Inputs = ViewProps<typeof schema>; // { label: string; day: number }
+ *
+ * \@Component({ ... })
+ * class DayCardComponent {
+ *   label = input.required<string>();
+ *   day   = input.required<number>();
+ * }
+ *
+ * const dayCard = view('Show a day card', schema, DayCardComponent);
+ * const registry = tools({ day_card: dayCard });
+ * ```
+ */
+declare function view<S extends StandardSchemaV1, C>(description: string, schema: S, component: AcceptComponent<S, C>): ViewToolDef<S, C>;
+/**
+ * Interactive (human-in-the-loop) component tool — the model fills the
+ * component's props from the schema's output; the value the component emits
+ * back to the framework becomes the tool result sent to the model.
+ *
+ * The component's signal inputs are checked against the schema output type
+ * (strict-but-flexible: every schema key must be a declared input with an
+ * assignable type; the component may declare extra inputs the schema doesn't
+ * fill). Author the component with `ViewProps<typeof schema>` to derive input
+ * prop types directly from the schema.
+ *
+ * @param description Natural-language description the model sees.
+ * @param schema Standard Schema defining the props the model must supply.
+ * @param component Angular component whose signal inputs must be compatible with
+ *   the schema output. A type-level error is reported here when they diverge.
+ * @returns An {@link AskToolDef} for inclusion in {@link tools}.
+ * @example
+ * ```ts
+ * const schema = z.object({ question: z.string(), options: z.array(z.string()) });
+ * type Inputs = ViewProps<typeof schema>;
+ *
+ * \@Component({ ... })
+ * class ChoiceCardComponent {
+ *   question = input.required<string>();
+ *   options  = input.required<string[]>();
+ *   // Emits the chosen option back to the model.
+ * }
+ *
+ * const choice = ask('Ask the user to choose', schema, ChoiceCardComponent);
+ * const registry = tools({ pick_option: choice });
+ * ```
+ */
+declare function ask<S extends StandardSchemaV1, C>(description: string, schema: S, component: AcceptComponent<S, C>): AskToolDef<S, C>;
+/**
+ * Collect named client tools into a frozen, name-keyed registry.
+ *
+ * The overload is generic over the entire map (`const M`) so that each tool's
+ * precise type ({@link FunctionToolDef}`<S,R>`, {@link ViewToolDef}`<S,C>`, or
+ * {@link AskToolDef}`<S,C>`) and every literal key are preserved in the
+ * {@link ClientToolRegistry} passed to `provideChat`. This lets downstream
+ * consumers look up individual tools without losing generic information.
+ *
+ * @param map An object literal mapping tool names to tool definitions created
+ *   by {@link action}, {@link view}, or {@link ask}.
+ * @returns A frozen `Readonly<M>` where `M` is the exact inferred map shape.
+ * @example
+ * ```ts
+ * const move = action('Move a stop', z.object({ fromDay: z.number() }), (a) => a.fromDay);
+ * const dayCard = view('Show a day card', z.object({ label: z.string() }), DayCardComponent);
+ *
+ * const registry = tools({ move_stop: move, day_card: dayCard });
+ * // registry.move_stop is FunctionToolDef<...>
+ * // registry.day_card  is ViewToolDef<...>
+ * ```
+ */
+declare function tools<const M extends Record<string, ClientToolDef>>(map: M): Readonly<M>;
 
 /** Validate raw model args against a Standard Schema. */
 declare function validateArgs(schema: StandardSchemaV1, args: unknown): Promise<{
@@ -2389,7 +2847,7 @@ declare function validateArgs(schema: StandardSchemaV1, args: unknown): Promise<
     error: string;
 }>;
 /** Validate args, run the handler, and normalize the outcome to a ClientToolResult. */
-declare function executeFunctionTool(def: FunctionToolDef, rawArgs: unknown): Promise<ClientToolResult>;
+declare function executeFunctionTool(def: AnyFunctionToolDef, rawArgs: unknown): Promise<ClientToolResult>;
 
 /**
  * Watches the agent's pending client tool calls and auto-runs FUNCTION tools,
@@ -2411,13 +2869,12 @@ interface ClientToolsCoordinator {
 }
 /** Build the catalog spec list shipped to the model. */
 declare function toClientToolSpecs(registry: ClientToolRegistry): ClientToolSpec[];
-declare function createClientToolsCoordinator(registry: ClientToolRegistry): ClientToolsCoordinator;
 
 interface MockAgent extends Agent {
     messages: WritableSignal<Message[]>;
     status: WritableSignal<AgentStatus>;
     isLoading: WritableSignal<boolean>;
-    error: WritableSignal<unknown>;
+    error: WritableSignal<AgentError | undefined>;
     toolCalls: WritableSignal<ToolCall[]>;
     state: WritableSignal<Record<string, unknown>>;
     interrupt?: WritableSignal<AgentInterrupt | undefined>;
@@ -2454,7 +2911,7 @@ interface MockAgentOptions {
     messages?: Message[];
     status?: AgentStatus;
     isLoading?: boolean;
-    error?: unknown;
+    error?: AgentError;
     toolCalls?: ToolCall[];
     state?: Record<string, unknown>;
     withInterrupt?: boolean;
@@ -2462,7 +2919,25 @@ interface MockAgentOptions {
     history?: AgentCheckpoint[];
     events$?: Observable<AgentEvent>;
 }
+/**
+ * Build an in-memory {@link Agent} for tests and stories — no transport, no
+ * network. Every field is a writable signal so a test can drive UI states
+ * (loading, error, interrupts, tool calls, subagents) deterministically.
+ *
+ * @param opts Initial values for the mock's signals; all optional.
+ * @returns A {@link MockAgent} satisfying the full `Agent` contract.
+ * @example
+ * ```ts
+ * const agent = mockAgent({
+ *   messages: [{ id: '1', role: 'assistant', content: 'Hi' }],
+ *   isLoading: true,
+ * });
+ * ```
+ */
 declare function mockAgent(opts?: MockAgentOptions): MockAgent;
 
-export { A2uiAudioPlayerComponent, A2uiButtonComponent, A2uiCardComponent, A2uiCheckBoxComponent, A2uiColumnComponent, A2uiDateTimeInputComponent, A2uiDividerComponent, A2uiIconComponent, A2uiImageComponent, A2uiListComponent, A2uiModalComponent, A2uiMultipleChoiceComponent, A2uiRowComponent, A2uiSliderComponent, A2uiSurfaceComponent, A2uiTabsComponent, A2uiTextComponent, A2uiTextFieldComponent, A2uiVideoComponent, CHAT_CONFIG, CHAT_LIFECYCLE, CHAT_MARKDOWN_STYLES, ChatApprovalCardComponent, ChatCitationCardTemplateDirective, ChatCitationsCardComponent, ChatCitationsComponent, ChatComponent, ChatConfirmDialogComponent, ChatErrorComponent, ChatGenerativeUiComponent, ChatGenuiSkeletonComponent, ChatHistorySearchPaletteComponent, ChatInputComponent, ChatInterruptComponent, ChatInterruptPanelComponent, ChatLauncherButtonComponent, ChatMessageActionsComponent, ChatMessageComponent, ChatMessageListComponent, ChatOverflowMenuComponent, ChatPopupComponent, ChatProjectListComponent, ChatReasoningComponent, ChatScrollBubbleComponent, ChatSelectComponent, ChatSidebarComponent, ChatSidenavComponent, ChatSidenavScrimComponent, ChatStreamingMdComponent, ChatSubagentCardComponent, ChatSubagentsComponent, ChatSuggestionsComponent, ChatThreadListComponent, ChatTimelineComponent, ChatTimelineSliderComponent, ChatToolCallCardComponent, ChatToolCallTemplateDirective, ChatToolCallsComponent, ChatToolViewsComponent, ChatTraceComponent, ChatTypingIndicatorComponent, ChatWelcomeComponent, ChatWelcomeSuggestionComponent, ChatWindowComponent, CitationsResolverService, ICON_AGENT, ICON_CHECK, ICON_CHEVRON_DOWN, ICON_CHEVRON_UP, ICON_SEND, ICON_TOOL, ICON_WARNING, IS_HEADER_ROW, MARKDOWN_VIEW_REGISTRY, MarkdownAutolinkComponent, MarkdownBlockquoteComponent, MarkdownChildrenComponent, MarkdownCitationReferenceComponent, MarkdownCodeBlockComponent, MarkdownDocumentComponent, MarkdownEmphasisComponent, MarkdownHardBreakComponent, MarkdownHeadingComponent, MarkdownImageComponent, MarkdownInlineCodeComponent, MarkdownLinkComponent, MarkdownListComponent, MarkdownListItemComponent, MarkdownParagraphComponent, MarkdownSoftBreakComponent, MarkdownStrikethroughComponent, MarkdownStrongComponent, MarkdownTableCellComponent, MarkdownTableComponent, MarkdownTableRowComponent, MarkdownTextComponent, MarkdownThematicBreakComponent, MessageTemplateDirective, a2uiBasicCatalog, action, ask, buildA2uiActionMessage, cacheplaneMarkdownViews, createA2uiSurfaceStore, createClientToolsCoordinator, createContentClassifier, createParseTreeStore, createPartialArgsBridge, deriveJsonSchema, emitBinding, executeFunctionTool, extractErrorMessage, formatDuration, getInterrupt, getMessageType, isAssistantMessage, isSystemMessage, isToolMessage, isTyping, isUserMessage, messageContent, mockAgent, normalizeEnvelopeArgs, normalizeViewEntry, provideChat, renderMarkdown, startClientToolExecutor, statusColor, submitMessage, surfaceToSpec, toClientToolSpecs, tools, validateArgs, view };
-export type { A2uiComponentView, A2uiSurfaceState, A2uiSurfaceStore, A2uiViewEntry, A2uiViews, Agent, AgentCheckpoint, AgentCustomEvent, AgentEvent, AgentInterrupt, AgentRuntimeTelemetryEvent, AgentRuntimeTelemetryPayload, AgentRuntimeTelemetryProperties, AgentRuntimeTelemetrySink, AgentStateUpdateEvent, AgentStatus, AgentSubmitInput, AgentSubmitOptions, AgentWithHistory, AskToolDef, ChatApprovalAction, ChatConfig, ChatLifecycle, ChatMessageRole, ChatRenderEvent, ChatScrollBubbleMode, ChatSelectOption, ChatSidenavMode, ChatToolCallTemplateContext, Citation, ClientToolDef, ClientToolRegistry, ClientToolResult, ClientToolSpec, ClientToolsCapability, ClientToolsCoordinator, ContentBlock, ContentClassifier, ContentType, ElementAccumulationState, FunctionToolDef, InterruptAction, Message, MessageTemplateType, MockAgent, MockAgentOptions, OverflowMenuItem, ParseTreeStore, PartialArgsBridge, Project, ProjectActionAdapter, ResolvedCitation, Role, Subagent, SubagentStatus, Thread, ThreadActionAdapter, ThreadMatch, ToolCall, ToolCallInfo, ToolCallStatus, TraceState, ViewToolDef };
+/** Inferred argument type for a schema (alias of StandardSchemaInferOutput). */
+type ToolArgs<S extends StandardSchemaV1> = StandardSchemaInferOutput<S>;
+
+export { A2uiAudioPlayerComponent, A2uiButtonComponent, A2uiCardComponent, A2uiCheckBoxComponent, A2uiColumnComponent, A2uiDateTimeInputComponent, A2uiDividerComponent, A2uiIconComponent, A2uiImageComponent, A2uiListComponent, A2uiModalComponent, A2uiMultipleChoiceComponent, A2uiRowComponent, A2uiSliderComponent, A2uiSurfaceComponent, A2uiTabsComponent, A2uiTextComponent, A2uiTextFieldComponent, A2uiVideoComponent, AGENT_ERROR_MESSAGES, AgentError, CHAT_CONFIG, CHAT_LIFECYCLE, ChatApprovalCardComponent, ChatCitationCardTemplateDirective, ChatCitationsCardComponent, ChatCitationsComponent, ChatComponent, ChatConfirmDialogComponent, ChatErrorComponent, ChatGenerativeUiComponent, ChatGenuiSkeletonComponent, ChatHistorySearchPaletteComponent, ChatInputComponent, ChatInterruptComponent, ChatInterruptPanelComponent, ChatLauncherButtonComponent, ChatMessageActionsComponent, ChatMessageComponent, ChatMessageListComponent, ChatOverflowMenuComponent, ChatPopupComponent, ChatProjectListComponent, ChatReasoningComponent, ChatScrollBubbleComponent, ChatSelectComponent, ChatSidebarComponent, ChatSidenavComponent, ChatSidenavScrimComponent, ChatStreamingMdComponent, ChatSubagentCardComponent, ChatSubagentsComponent, ChatSuggestionsComponent, ChatThreadListComponent, ChatTimelineComponent, ChatTimelineSliderComponent, ChatToolCallCardComponent, ChatToolCallTemplateDirective, ChatToolCallsComponent, ChatToolViewsComponent, ChatTraceComponent, ChatTypingIndicatorComponent, ChatWelcomeComponent, ChatWelcomeSuggestionComponent, ChatWindowComponent, CitationsResolverService, IS_HEADER_ROW, MARKDOWN_VIEW_REGISTRY, MarkdownAutolinkComponent, MarkdownBlockquoteComponent, MarkdownChildrenComponent, MarkdownCitationReferenceComponent, MarkdownCodeBlockComponent, MarkdownDocumentComponent, MarkdownEmphasisComponent, MarkdownHardBreakComponent, MarkdownHeadingComponent, MarkdownImageComponent, MarkdownInlineCodeComponent, MarkdownLinkComponent, MarkdownListComponent, MarkdownListItemComponent, MarkdownParagraphComponent, MarkdownSoftBreakComponent, MarkdownStrikethroughComponent, MarkdownStrongComponent, MarkdownTableCellComponent, MarkdownTableComponent, MarkdownTableRowComponent, MarkdownTextComponent, MarkdownThematicBreakComponent, MessageTemplateDirective, a2uiBasicCatalog, action, ask, buildA2uiActionMessage, cacheplaneMarkdownViews, createA2uiSurfaceStore, createAgentRef, createContentClassifier, createParseTreeStore, createPartialArgsBridge, deriveJsonSchema, emitBinding, executeFunctionTool, extractErrorMessage, formatDuration, getInterrupt, getMessageType, injectThreadRouting, isAbortError, isAssistantMessage, isSystemMessage, isToolMessage, isTyping, isUserMessage, messageContent, mockAgent, normalizeEnvelopeArgs, normalizeViewEntry, provideChat, renderMarkdown, startClientToolExecutor, statusColor, submitMessage, toAgentError, toClientToolSpecs, tools, validateArgs, view };
+export type { A2uiComponentView, A2uiSurfaceState, A2uiSurfaceStore, A2uiViewEntry, A2uiViews, Agent, AgentCheckpoint, AgentCustomEvent, AgentErrorKind, AgentEvent, AgentInterrupt, AgentRef, AgentRuntimeTelemetryEvent, AgentRuntimeTelemetryPayload, AgentRuntimeTelemetryProperties, AgentRuntimeTelemetrySink, AgentStateUpdateEvent, AgentStatus, AgentSubmitInput, AgentSubmitOptions, AgentWithHistory, AnyFunctionToolDef, AskToolDef, ChatApprovalAction, ChatConfig, ChatLifecycle, ChatMessageRole, ChatRenderEvent, ChatScrollBubbleMode, ChatSelectOption, ChatSidenavMode, ChatToolCallTemplateContext, Citation, ClientToolDef, ClientToolRegistry, ClientToolResult, ClientToolSpec, ClientToolsCapability, ClientToolsCoordinator, ContentBlock, ContentClassifier, ContentType, ElementAccumulationState, FunctionToolDef, InterruptAction, Message, MessageTemplateType, MockAgent, MockAgentOptions, OverflowMenuItem, ParseTreeStore, PartialArgsBridge, Project, ProjectActionAdapter, ResolvedCitation, Role, Subagent, SubagentStatus, Thread, ThreadActionAdapter, ThreadMatch, ThreadRoutingConfig, ToolArgs, ToolCall, ToolCallInfo, ToolCallStatus, TraceState, ViewProps, ViewToolDef };