@interopio/io-assist-ng 0.0.1 → 1.0.0

package/README.internal.md

@@ -0,0 +1,865 @@
+# io.Assist — Internal Developer Documentation
+
+**Audience:** Developers working on or extending `@interopio/io-assist-ng`.
+
+---
+
+## Table of Contents
+
+- [Architecture Overview](#architecture-overview)
+- [Project Structure](#project-structure)
+- [Public API Surface](#public-api-surface)
+- [Configuration & Validation](#configuration--validation)
+- [Provider Registration](#provider-registration)
+- [Root Component — IoAssist](#root-component--ioassist)
+- [State Management (NgRx Store)](#state-management-ngrx-store)
+  - [Store Shape](#store-shape)
+  - [Facades](#facades)
+  - [Effects](#effects)
+- [Services](#services)
+  - [IOConnectService](#ioconnectservice)
+  - [IOIntelWebService](#iointelwebservice)
+  - [AgentService](#agentservice)
+  - [AgentManagerService](#agentmanagerservice)
+  - [SamplingService](#samplingservice)
+  - [ElicitationService](#elicitationservice)
+  - [McpAppsService](#mcpappsservice)
+  - [ThreadService](#threadservice)
+  - [ToolsService](#toolsservice)
+  - [PromptService](#promptservice)
+  - [WorkingContextService](#workingcontextservice)
+  - [OverlayService](#overlayservice)
+  - [ConsumerAssetLoaderService](#consumerassetloaderservice)
+  - [ResponsiveUIService](#responsiveuiservice)
+  - [LoggerService](#loggerservice)
+  - [ComponentEffectManagerService](#componenteffectmanagerservice)
+  - [SubscriptionCleanupService](#subscriptioncleanupservice)
+  - [CopyToClipboardService](#copytoclipboardservice)
+- [Components](#components)
+  - [Chat Layout](#chat-layout)
+  - [Header](#header)
+  - [Input Area](#input-area)
+  - [Messages](#messages)
+  - [Threads](#threads)
+  - [Tools](#tools)
+  - [Prompts](#prompts)
+  - [Working Context Panel](#working-context-panel)
+  - [MCP App Resource](#mcp-app-resource)
+  - [Shared UI Primitives](#shared-ui-primitives)
+- [Directives](#directives)
+- [AG-UI Streaming Pipeline](#ag-ui-streaming-pipeline)
+- [Response Stream Store](#response-stream-store)
+- [Sampling & Elicitation Flow](#sampling--elicitation-flow)
+- [MCP Apps Integration](#mcp-apps-integration)
+- [Styling](#styling)
+- [Testing](#testing)
+
+---
+
+## Architecture Overview
+
+`@interopio/io-assist-ng` is a standalone Angular library (no NgModule). The consumer calls `provideIoAssist(config)` once in their app config and drops `<io-assist [config]="dynamicConfig()">` into a template. Everything else — store, effects, services, UI — is bootstrapped internally.
+
+```
+Consumer App
+ └── provideIoAssist(config)           ← registers DI providers
+      ├── IO_ASSIST_CONFIG token        ← validated static config
+      ├── IO_ASSIST_DYNAMIC_CONFIG      ← WritableSignal<IoAssistDynamicConfig> (seeded empty)
+      ├── provideIoConnect(...)         ← io.Connect Angular integration
+      ├── provideStore(appReducers)     ← NgRx store with 8 slices
+      ├── provideEffects(...)           ← 7 effect classes
+      └── provideStoreDevtools()
+
+ └── <io-assist [config]="dynamicConfig()">   ← root component
+      ├── input.required<IoAssistDynamicConfig>()  ← runtime user + headers
+      ├── effect() → IO_ASSIST_DYNAMIC_CONFIG.set(config)
+      ├── IOConnectService              ← io.Connect readiness + theme sync
+      ├── IOIntelWebService             ← ai-web API init
+      ├── AppLifecycleFacade            ← lifecycle state signals
+      └── <chat />                      ← full UI tree
+```
+
+**Key layers:**
+
+| Layer | Responsibility |
+|-------|---------------|
+| **Static Config / Validation** | Zod schema validates `IoAssistStaticConfig` at provider registration time |
+| **Dynamic Config** | `IoAssistDynamicConfig` passed as component input, synced to `IO_ASSIST_DYNAMIC_CONFIG` signal |
+| **NgRx Store** | 8 feature slices with reducers, selectors, and facades |
+| **Effects** | Async operations (API calls, streaming, lifecycle) |
+| **Services** | Business logic, API integration, UI orchestration |
+| **Components** | Standalone Angular components with signal-based reactivity |
+
+---
+
+## Project Structure
+
+```
+src/
+├── public-api.ts                      # Package exports
+├── styles.css                         # Tailwind entry point
+└── lib/
+    ├── io-assist.component.ts         # Root <io-assist> component
+    ├── io-assist.component.html       # Root template
+    ├── io-assist.providers.ts         # provideIoAssist() function
+    ├── io-assist.config.ts            # Config types + IO_ASSIST_CONFIG token
+    ├── io-assist.schema.ts            # Zod validation schema
+    ├── io-assist.types.ts             # Prompt/icon types
+    ├── components/
+    │   ├── chat/                      # Main chat layout
+    │   ├── header/                    # App header with thread toggle
+    │   ├── input-area/                # Message input + action bar
+    │   ├── messages/                  # Message rendering (user, assistant, tool)
+    │   ├── threads/                   # Thread history panel
+    │   ├── tool/                      # Tool list + management
+    │   ├── prompt/                    # Prompt library + favorites
+    │   └── working-context-panel/     # Working context inspector
+    └── shared/
+        ├── components/                # Reusable UI primitives
+        ├── constants/                 # UI strings, config constants
+        ├── directives/                # Animation + accent border directives
+        ├── enums/                     # Loading state, message roles, etc.
+        ├── services/                  # All business logic services
+        ├── store/                     # NgRx store (8 feature slices)
+        ├── styles/                    # Shared SCSS/Tailwind utilities
+        ├── types/                     # Shared type definitions
+        └── utils/                     # Icon parsing, sanitization utilities
+```
+
+---
+
+## Public API Surface
+
+File: `src/public-api.ts`
+
+Only these are exported — everything else is internal:
+
+```typescript
+export * from './lib/io-assist.component';      // IoAssist component
+export * from './lib/io-assist.providers';       // provideIoAssist()
+export * from './lib/io-assist.types';           // IoAssistPrompt, IoAssistPromptCategory, IconResource, IconType
+export * from './lib/io-assist.config';          // IoAssistStaticConfig, IoAssistDynamicConfig, AIWebConfig, IoAssistUserConfig, IO_ASSIST_CONFIG, IO_ASSIST_DYNAMIC_CONFIG
+```
+
+---
+
+## Configuration & Validation
+
+### Config types
+
+File: `src/lib/io-assist.config.ts`
+
+io.Assist uses two separate configuration types:
+
+**Static config** — passed to `provideIoAssist()` at bootstrap. Does not include user identity.
+
+```typescript
+type IoAssistStaticConfig = {
+    connectConfig: IOConnectNgSettings; // io.Connect platform settings
+    aiWebConfig: AIWebConfig;           // { agentServer, mcp? }
+    defaultAgentName?: string;
+    workingContext?: {
+        factory: IoIntelWorkingContextFactoryFunction;
+        config?: IoIntelWorkingContext.Config;
+    };
+    defaultPrompts?: IoAssistPromptCategory[];
+};
+
+type AIWebConfig = {
+    agentServer: Omit<IoAiWeb.WebConfig['agentServer'], 'headers'>; // headers excluded
+    mcp?: IoAiWeb.WebConfig['mcp'];
+};
+```
+
+**Dynamic config** — passed as `[config]` input to `<io-assist>` at runtime. Holds the active user's identity and request headers.
+
+```typescript
+type IoAssistUserConfig = { id: string; name?: string };
+
+type IoAssistDynamicConfig = {
+    user: IoAssistUserConfig;
+    agentServer?: {
+        headers?: Record<string, string>; // request headers for every agent call (e.g. auth tokens)
+    };
+};
+```
+
+### DI tokens
+
+| Token | Type | Set by |
+|-------|------|--------|
+| `IO_ASSIST_CONFIG` | `InjectionToken<IoAssistStaticConfig>` | `provideIoAssist()` (once, at bootstrap) |
+| `IO_ASSIST_DYNAMIC_CONFIG` | `InjectionToken<WritableSignal<IoAssistDynamicConfig>>` | `provideIoAssist()` seeds with `{ user: { id: '' } }`; overwritten on each `IoAssist` component input change via `effect()` |
+
+### Zod validation
+
+File: `src/lib/io-assist.schema.ts`
+
+Two schemas are defined:
+
+**`IoAssistStaticConfigSchema`** — validated at `provideIoAssist()` time. Key validations:
+
+- `aiWebConfig.agentServer.baseUrl` — valid URL
+- `mcp.mcpApps.sandboxProxyUrl` — non-empty string if `mcpApps` provided
+- `mcp.clientsConfig.capabilities.elicitation.handler` — function type
+- `defaultPrompts[].prompts[].name` — non-empty string
+- `defaultPrompts[].prompts[].iconResource.type` — enum `'svg' | 'url' | 'data-url'`
+
+If validation fails, `provideIoAssist()` throws `"Invalid IoAssist configuration provided."`.
+
+**`IoAssistDynamicConfigSchema`** — validated in `IoAssist.ngOnInit()`. Key validations:
+
+- `user.id` — non-empty string (required)
+- `agentServer.headers` — optional record of strings
+
+If validation fails, `ngOnInit` throws a `ZodError`.
+
+---
+
+## Provider Registration
+
+File: `src/lib/io-assist.providers.ts`
+
+```typescript
+function provideIoAssist(config: IoAssistStaticConfig): EnvironmentProviders
+```
+
+Registers:
+
+1. `IO_ASSIST_CONFIG` — the Zod-validated static config
+2. `IO_ASSIST_DYNAMIC_CONFIG` — `useFactory: () => signal<IoAssistDynamicConfig>({ user: { id: '' } })` (empty seed; overwritten by the `IoAssist` component input)
+3. `provideBrowserGlobalErrorListeners()` — Angular global error handling
+4. `provideZonelessChangeDetection()` — zoneless Angular (signal-based)
+5. `provideStore(appReducers)` — NgRx store with all 8 reducers
+6. `provideEffects(...)` — 7 effect classes
+7. `provideStoreDevtools({ maxAge: 25 })` — Redux DevTools integration
+8. `provideIoConnect(config.connectConfig)` — io.Connect Angular bootstrap
+
+---
+
+## Root Component — IoAssist
+
+File: `src/lib/io-assist.component.ts`
+
+Selector: `<io-assist>`
+
+**Input:**
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `config` | `IoAssistDynamicConfig` (required) | Active user identity + optional per-request headers. Validated in `ngOnInit`. |
+
+**Lifecycle:**
+
+1. `effect()` — syncs the `config` input into the `IO_ASSIST_DYNAMIC_CONFIG` writable signal whenever the input changes.
+2. `ngOnInit` — validates `config` via `IoAssistDynamicConfigSchema.parse()` (throws `ZodError` if invalid), writes config to `IO_ASSIST_DYNAMIC_CONFIG`, then registers the io.Connect readiness effect.
+3. `ngAfterViewInit` — calls `ConsumerAssetLoaderService.loadConsumerAssets()` to inject fonts and Prism.js into the DOM.
+
+**Template states:**
+
+- **Pending** — shows spinner while io.Connect initializes and core services start
+- **Error** — shows error message with "Refresh" button
+- **Ready** — renders `<chat />` (the full UI tree)
+
+**Signals used:**
+
+| Signal | Source | Purpose |
+|--------|--------|---------|
+| `isIoReady` | `IOConnectService.isIoConnectReady` | io.Connect platform ready |
+| `isAppCoreServicesStarted` | `AppLifecycleFacade` | ai-web initialized + agents/prompts loaded |
+| `appCoreServicesError` | `AppLifecycleFacade` | Error message if init failed |
+| `isAppCoreServicesPending` | `AppLifecycleFacade` | Currently initializing |
+
+---
+
+## State Management (NgRx Store)
+
+### Store Shape
+
+File: `src/lib/shared/store/app.state.ts`
+
+```typescript
+type AppState = {
+    threadsStore: ThreadReducerStateType;
+    appLifecycleStore: AppLifecycleStateType;
+    promptStore: PromptReducerStateType;
+    toolStore: ToolReducerStateType;
+    messageStore: MessageReducerStateType;
+    responseStreamStore: ResponseStreamReducerStateType;
+    agentStore: AgentReducerStateType;
+    workingContextStore: WorkingContextReducerStateType;
+};
+```
+
+### Facades
+
+Every store slice has a facade that wraps selectors as Angular signals and provides typed dispatch methods. Components inject facades, not the raw store.
+
+**AgentFacade** — `store/agent/agent.facade.ts`
+
+| Signal | Description |
+|--------|-------------|
+| `availableAgents` | All agents from the server |
+| `selectedAgent` | Currently active agent |
+
+| Method | Description |
+|--------|-------------|
+| `dispatchListAvailableAgents()` | Fetch agents from server |
+| `dispatchSelectAgent(agentId)` | Switch active agent |
+
+**AppLifecycleFacade** — `store/app-lifecycle/app-lifecycle.facade.ts`
+
+| Signal | Description |
+|--------|-------------|
+| `isAppCoreServicesStarted` | Core services initialized successfully |
+| `appCoreServicesLoadingState` | Loading state enum value |
+| `isPendingAppCoreServicesOperation` | Currently initializing |
+| `appCoreServicesErrorMessage` | Error message or null |
+
+| Method | Description |
+|--------|-------------|
+| `dispatchInitAppCoreServices()` | Trigger initialization |
+
+**MessageFacade** — `store/message/message.facade.ts`
+
+| Signal | Description |
+|--------|-------------|
+| `allMessages` | All messages for active thread |
+| `messageLength` | Message count |
+| `lastUserMessage` | Most recent user message |
+| `isGeneratingResponse` | Stream in progress |
+| `isLoadingMessagesFromThread` | Loading thread messages |
+| `toolTraceState` | Tool trace expand/collapse state |
+| `isLastResponseSuccess` | Last response completed without error |
+
+| Method | Description |
+|--------|-------------|
+| `dispatchGetResponse(params, threadId, isStream?, agent?)` | Send user message and get agent response |
+| `dispatchReloadResponse(params, threadId, isStream?, agent?)` | Regenerate last response |
+| `dispatchClearMessages()` | Clear all messages |
+| `dispatchFetchMessagesFromThread(thread)` | Load messages from an existing thread |
+| `dispatchAbortResponseGeneration(threadId)` | Cancel active stream |
+| `dispatchToggleToolTrace(stateForMessageId)` | Expand/collapse tool trace |
+
+**ThreadFacade** — `store/thread/thread.facade.ts`
+
+| Signal | Description |
+|--------|-------------|
+| `allThreads` | All threads for current user |
+| `activeThreadId` | Currently active thread ID |
+| `activeThread` | Currently active thread object |
+| `isFetchingThreads` | Loading threads |
+
+| Method | Description |
+|--------|-------------|
+| `dispatchFetchThreads(agentId)` | Fetch all threads for agent + user |
+| `dispatchRenameThread(thread, newTitle)` | Rename a thread |
+| `dispatchDeleteThread(thread)` | Delete a thread |
+| `dispatchChangeActiveThread(threadId)` | Switch active thread |
+
+**ResponseStreamFacade** — `store/response-stream/response-stream.facade.ts`
+
+| Signal | Description |
+|--------|-------------|
+| `allStreams` | All per-thread stream states |
+| `threadsCurrentlyStreaming` | Thread IDs with active streams |
+| `threadsWithCompletionNotification` | Threads with background completion notifications |
+| `hasAnyCompletionNotification` | Any thread has a background notification |
+
+| Method | Description |
+|--------|-------------|
+| `isThreadStreaming(threadId)` | Check if specific thread is streaming |
+| `createIsStreamingSignal(threadIdSignal)` | Reactive signal from thread ID signal |
+| `dispatchStartThreadStream(threadId, userMessage)` | Start tracking a stream |
+| `dispatchCompleteThreadStream(threadId, shouldNotify)` | Mark stream complete |
+
+**ToolFacade** — `store/tool/tool.facade.ts`
+
+| Signal | Description |
+|--------|-------------|
+| `allTools` | All available tools |
+| `enabledTools` | Currently enabled tools |
+
+| Method | Description |
+|--------|-------------|
+| `dispatchFetchTools()` | Fetch all tools from MCP servers |
+| `dispatchToggleTool(tool)` | Enable/disable a tool |
+
+**PromptFacade** — `store/prompt/prompt.facade.ts`
+
+| Signal | Description |
+|--------|-------------|
+| `allPrompts` | All parsed prompts |
+| `favoritePromptNames` | Names of favorited prompts |
+| `selectedPrompt` | Currently selected prompt |
+
+| Method | Description |
+|--------|-------------|
+| `dispatchParsePromptsConfig()` | Parse and normalize configured prompts |
+| `dispatchSelectPrompt(prompt)` | Select a prompt (fills input) |
+| `dispatchToggleFavoritePrompt(name)` | Toggle favorite state |
+
+**WorkingContextFacade** — `store/working-context/working-context.facade.ts`
+
+| Signal | Description |
+|--------|-------------|
+| `workingContext` | Current working context values |
+| `isWorkingContextEnabled` | Whether working context is configured |
+
+| Method | Description |
+|--------|-------------|
+| `dispatchGetWorkingContext()` | Fetch current context |
+| `dispatchUpdateWorkingContext(context)` | Update with new values |
+
+### Effects
+
+| Effect Class | Key Operations |
+|-------------|----------------|
+| `AppLifecycleEffects` | Monitors IOIntelWebService init state → dispatches success/failure → triggers agent list + prompt parse |
+| `AgentEffects` | Lists agents from server, selects agent (by config name or first available), fetches threads + tools on selection |
+| `MessageEffects` | Handles `getResponse`/`reloadResponse` → streams AG-UI events into store actions (see [AG-UI Streaming Pipeline](#ag-ui-streaming-pipeline)) |
+| `ThreadEffects` | Fetches threads for agent + user (reads `user.id` from `IO_ASSIST_DYNAMIC_CONFIG`), rename/delete, cleans up MCP app prefs on delete |
+| `ToolEffects` | Fetches all tools from MCP servers, toggles tool enabled state |
+| `PromptEffects` | Parses config `defaultPrompts` into UI-ready prompt objects via `PromptService` |
+| `WorkingContextEffects` | Fetches and subscribes to working context changes via `WorkingContextService` |
+
+---
+
+## Services
+
+### IOConnectService
+
+File: `shared/services/io/io.service.ts`
+
+Connects to io.Connect platform. Exposes:
+- `isIoConnectReady` — signal from `IOConnectStore`
+- `isDarkMode` — signal synced with io.Connect theme
+- `startIODependentTasks()` — subscribes to theme changes, initializes ai-web factory, dispatches lifecycle init
+- `requestIOModal(config)` — wraps io.Connect modals API
+- `isModalsApiAvailable()` — checks if modals library is loaded
+
+### IOIntelWebService
+
+File: `shared/services/io-ai-web/io-ai-web.service.ts`
+
+Initializes `@interopio/ai-web` API. Key behavior:
+- `initialize()` — builds `IoAiWeb.WebConfig` from `IO_ASSIST_CONFIG`, calls `IoAiWebFactory`, attaches MCP apps service
+- `buildMcpConfig(mcp)` — injects sampling/elicitation handlers from `SamplingService`/`ElicitationService` (custom or built-in)
+- `constructConfig()` — spreads static `agentServer` fields, and sets `headers` from `IO_ASSIST_DYNAMIC_CONFIG.agentServer.headers` (the sole source of request headers)
+- Exposes signals: `isInitialized`, `isInitializing`, `isError`
+- Exposes API wrappers: `listAgents()`, `listThreads()`, `listTools()`, `getWorkingContext()`, etc.
+
+### AgentService
+
+File: `shared/services/agent/agent.service.ts`
+
+Builds API call parameters. Key methods:
+- `getResponse(params, isStream, agent)` — calls ai-web stream/generate
+- `reloadResponse(params, isStream, agent)` — regenerates last response
+- `getSamplingResponse(params, skipThread)` — non-streaming generation for sampling flow
+- `buildAgentParams(params, skipThreadManagement)` — constructs memory params with `thread: threadId, resource: user.id`
+
+**Critical behavior:**
+- `user.id` is read from `IO_ASSIST_DYNAMIC_CONFIG().user.id` at call time — this scopes all threads to the current user
+- When `skipThreadManagement=true` (sampling), the active thread is NOT inherited to avoid polluting conversation history
+- Empty assistant messages are filtered out before sending (prevents Anthropic empty-content errors)
+
+### AgentManagerService
+
+File: `shared/services/agent/agent-manager/agent-manager.service.ts`
+
+Lists available agents via `IOIntelWebService.listAgents()`.
+
+### SamplingService
+
+File: `shared/services/io-ai-web/sampling/sampling.service.ts`
+
+Handles MCP sampling requests:
+
+1. `selectSamplingHandler(mcp)` — returns custom handler if `mcp.clientsConfig.capabilities.sampling.handler` is provided, otherwise returns the built-in handler
+2. Built-in flow:
+   - Rejects requests from background threads (user not on the requesting thread)
+   - Shows a confirmation UI:
+     - **io.Connect modal** (if `IOModals` library is available) — `noInputsConfirmationDialog` template
+     - **Built-in panel overlay** (fallback) — `OverlayService.showPanelOverlay()` with Continue/Cancel buttons
+   - On accept: calls `AgentService.getSamplingResponse()`, maps finish reason → MCP stop reason, returns `SamplingSuccessResponse`
+   - On decline: returns `SamplingErrorResponse` with rejection message
+
+### ElicitationService
+
+File: `shared/services/io-ai-web/elicitation/elicitation.service.ts`
+
+Handles MCP elicitation requests:
+
+1. `selectElicitationHandler(mcp)` — returns custom handler if provided, otherwise built-in
+2. Built-in flow:
+   - Validates `_meta.toolName` starts with `io_connect`
+   - Rejects background thread requests
+   - Shows accept/decline/cancel UI (modal or overlay)
+   - Accept returns `{ action: 'accept', content: {} }` (empty content — actual form input is a TODO)
+   - Decline returns `{ action: 'decline' }`
+   - Cancel returns `{ action: 'cancel' }`
+
+### McpAppsService
+
+File: `shared/services/mcp-apps/mcp-apps.service.ts`
+
+Wraps `ai-web` MCP Apps API for Angular consumption:
+- `attach(api)` — subscribes to `onAppCreated`, `onRecreateRequested`, `onAppRecreated` events
+- `activeInstances` — signal tracking all live `AppInstance` objects
+- Handles duplicate instance dialog (3-option: replace oldest / replace all / new instance)
+- Feeds app chat messages into the message store via `MessageFacade.dispatchGetResponse()`
+- Thread switch triggers `closeAll()` + re-creation of pending apps for the new thread
+
+### ThreadService
+
+File: `shared/services/thread/thread.service.ts`
+
+Thread operations:
+- `fetchThreads(agentId, userId)` — lists threads from server
+- `toUIThreads(threads)` — converts backend threads to UI model with relative-time labels
+- `renameThread(thread, newTitle)` — renames via API
+- `deleteThread(thread)` — deletes via API
+- `deleteThreadState(threadId)` — cleans up persisted MCP app preferences for deleted threads
+
+### ToolsService
+
+File: `shared/services/tools/tools.service.ts`
+
+- `listTools()` — fetches all tools from MCP servers
+- `toggleTool(tool)` — enables/disables a tool
+
+### PromptService
+
+File: `shared/services/prompt/prompt.service.ts`
+
+- Takes `defaultPrompts` from config and maps them to UI-ready objects
+- Validates and normalizes icon resources (falls back to default icon)
+- Icon sanitization: SVG strings have `fill`, `width`, `height` stripped; hardcoded colors → `currentColor`
+
+### WorkingContextService
+
+File: `shared/services/working-context/working-context.service.ts`
+
+- `getWorkingContext()` — fetches current context values
+- `subscribeToWorkingContext()` — subscribes to `onChanged` callback
+- `isEnabled()` — checks if working context is configured
+
+### OverlayService
+
+File: `shared/services/overlay/overlay.service.ts`
+
+CDK-based overlay system:
+- `showPanelOverlay(config)` — creates centered overlay with backdrop, attaches `AppPanelComponent`
+- Supports HTML content (string) or injected Angular component
+- Maintains an overlay stack — backdrop click closes only the topmost overlay
+- `closeCurrentOverlay()` — disposes the top overlay
+- Also manages thread history panel visibility signal
+
+### ConsumerAssetLoaderService
+
+File: `shared/services/consumer-asset-loader/consumer-asset-loader.service.ts`
+
+Injects external assets into the consumer app's DOM at runtime:
+- **Google Inter font** — `<link>` to Google Fonts CDN
+- **Prism.js CSS** — syntax highlighting styles
+- **Prism.js JS** — syntax highlighting runtime
+
+Called in `IoAssist.ngAfterViewInit()` after the DOM is ready.
+
+### ResponsiveUIService
+
+File: `shared/services/responsive-ui/responsive-ui.service.ts`
+
+Tailwind-style breakpoint tracking:
+- Uses `ResizeObserver` on the root component element
+- Exposes signal-based breakpoint state matching Tailwind thresholds
+- Components use it to adapt layout (e.g., compact header on small viewports)
+
+### LoggerService
+
+File: `shared/services/logger/logger.service.ts`
+
+- Wraps io.Connect logger when available
+- Falls back to `console` methods
+- Namespaced: `logger.get('SamplingService').info(...)`
+
+### ComponentEffectManagerService
+
+File: `shared/services/component-effect-manager/component-effect-manager.service.ts`
+
+- Named Angular `effect()` registration
+- Tracks effects by name to prevent duplicates
+- Auto-cleanup on service destroy
+
+### SubscriptionCleanupService
+
+File: `shared/services/subscription-cleanup/subscription-cleanup.service.ts`
+
+- Named subscription registry (`add(name, subscription)`)
+- `destroy()` unsubscribes all
+- Used in components/services that manage RxJS subscriptions manually
+
+### CopyToClipboardService
+
+File: `shared/services/copy-to-clipboard/copy-to-clipboard.service.ts`
+
+- Uses `navigator.clipboard.writeText()` with `<textarea>` fallback for older browsers
+
+---
+
+## Components
+
+### Chat Layout
+
+File: `components/chat/chat.component.ts`
+
+Main container component. Renders:
+- Thread history panel (toggle sidebar)
+- Header
+- Message area
+- Favorite prompts (shown on home screen when no messages)
+- Input area
+- AI disclaimer footer
+
+### Header
+
+File: `components/header/header.component.ts`
+
+- Thread history toggle button (with notification dot for background completions)
+- Home button (starts new thread)
+- Working context button (opens inspector panel)
+
+### Input Area
+
+File: `components/input-area/input-area.component.ts`
+
+- Auto-resizing textarea
+- `Enter` sends, `Shift+Enter` for newlines
+- `Shift+Up/Down` cycles through user's message history
+- Action bar with tools panel and prompt library buttons
+- Send button with loading state during streaming
+
+### Messages
+
+| Component | Purpose |
+|-----------|---------|
+| `MessageAreaComponent` | Scrollable message list with auto-scroll |
+| `UserMessageComponent` | User message bubble |
+| `AssistantMessageComponent` | Markdown-rendered assistant response |
+| `ToolTraceMessageComponent` | Expandable tool call trace (name + status) |
+| `ToolMessageComponent` | Tool call args + result display |
+| `MessageFooterComponent` | Copy + regenerate buttons |
+| `McpAppResourceComponent` | Mounts MCP App iframe element |
+
+### Threads
+
+| Component | Purpose |
+|-----------|---------|
+| `ThreadHistoryComponent` | Sidebar panel with thread list |
+| `ThreadHistoryListComponent` | Grouped list with relative-time dividers |
+| `ThreadHistoryListItemComponent` | Individual thread with rename/delete actions |
+
+### Tools
+
+| Component | Purpose |
+|-----------|---------|
+| `ToolListComponent` | Searchable list of all available tools |
+| `ToolListItemComponent` | Individual tool with enable/disable toggle |
+| `ToolInfoComponent` | Tool metadata tooltip |
+
+### Prompts
+
+| Component | Purpose |
+|-----------|---------|
+| `PromptListComponent` | Categorized prompt browser with search |
+| `PromptListItemComponent` | Individual prompt with favorite toggle |
+| `FavoritePromptListComponent` | Home screen favorites grid |
+
+### Working Context Panel
+
+File: `components/working-context-panel/working-context-panel.component.ts`
+
+- Info callout explaining what working context is
+- JSON-formatted display of current context values (rendered as markdown)
+
+### MCP App Resource
+
+File: `components/messages/mcp-app-resource/mcp-app-resource.component.ts`
+
+- Receives an `AppInstance` from `McpAppsService`
+- Mounts `app.element` (the sandbox proxy iframe) into the DOM
+- Only renders for inline display mode
+
+### Shared UI Primitives
+
+| Component | File |
+|-----------|------|
+| `AppIconComponent` | `shared/components/app-icon/` |
+| `AppButtonComponent` | `shared/components/app-button/` |
+| `AppToggleComponent` | `shared/components/app-toggle/` |
+| `AppInputComponent` | `shared/components/app-input/` |
+| `AppTooltipComponent` | `shared/components/app-tooltip/` |
+| `AppPanelComponent` | `shared/components/app-panel/` |
+| `AppSpinnerComponent` | `shared/components/app-spinner/` |
+| `AppMdFormatterComponent` | `shared/components/app-md-formatter/` |
+| `AppCopyToClipboardButtonComponent` | `shared/components/app-copy-to-clipboard-button/` |
+
+---
+
+## Directives
+
+### Animation Effect Directive
+
+File: `shared/directives/animation/`
+
+Applies CSS animations to host elements with:
+- Configurable animation type and duration
+- Start/complete event emitters
+- Used for message entrance animations
+
+### Accent Gradient Border Directive
+
+File: `shared/directives/accent-border/`
+
+Applies a gradient border effect to elements. Used for visual emphasis on active/streaming states.
+
+---
+
+## AG-UI Streaming Pipeline
+
+File: `store/message/message.effects.ts`
+
+The core streaming loop. When `getResponse` or `reloadResponse` is dispatched:
+
+1. **Start** — dispatches `startThreadStream(threadId, userMessage)` to track stream state
+2. **Stream** — `AgentService.getResponse()` returns an AG-UI `StreamResponse` observable
+3. **Event processing** — each AG-UI event is mapped to store actions:
+
+| AG-UI Event | Store Action |
+|-------------|-------------|
+| `TEXT_MESSAGE_START` | `addAssistantMessage` (creates placeholder) |
+| `TEXT_MESSAGE_CONTENT` | `addAssistantMessage` (updates content) or `updateStreamContent` (background thread) |
+| `TOOL_CALL_START` | `addToolCallMessage` |
+| `TOOL_CALL_ARGS` | Accumulated in local `Map<toolCallId, args>` |
+| `TOOL_CALL_END` | Parses accumulated args JSON → `updateToolCallResult` |
+| `TOOL_CALL_RESULT` | Parses result → `updateToolCallResult` |
+
+4. **Complete** — dispatches `completeThreadStream(threadId, shouldNotify)`. Sets `shouldNotify=true` if the user switched to a different thread (background completion).
+5. **Error** — dispatches `failThreadStream` + logs error
+6. **Abort** — dispatches `abortThreadStream`
+
+**Background thread handling:** If the user switches threads while a stream is active:
+- Content deltas go to `updateStreamContent` (stored in response stream store, not visible UI)
+- On completion, `shouldNotify=true` triggers a notification dot on the thread history button
+- When the user switches back, the accumulated content is replayed
+
+---
+
+## Response Stream Store
+
+File: `store/response-stream/`
+
+Per-thread stream tracking:
+
+```typescript
+type ThreadStreamState = {
+    threadId: string;
+    status: 'idle' | 'streaming' | 'completed' | 'error' | 'aborted';
+    accumulatedContent: string;
+    currentMessageId: string | null;
+    hasCompletionNotification: boolean;
+    errorMessage?: string;
+    userMessage: UIMessage | null;
+    toolMessages: UIToolMessage[];
+};
+```
+
+| Action | Behavior |
+|--------|----------|
+| `startThreadStream` | Creates/overwrites stream entry with status `streaming` |
+| `updateStreamContent` | Updates accumulated content (only if `streaming`) |
+| `addStreamToolMessage` | Merges tool message by ID (update existing or append) |
+| `completeThreadStream` | Sets terminal status + notification flag |
+| `failThreadStream` | Sets `error` status + error message |
+| `abortThreadStream` | Sets `aborted` status |
+| `clearCompletionNotification` | Clears notification flag (e.g., when user views the thread) |
+| `untrackThreadStreamState` | Removes stream entry (only if in terminal state) |
+
+---
+
+## Sampling & Elicitation Flow
+
+### Sampling
+
+```
+MCP Server → SamplingRequest → SamplingService.handleSamplingRequest()
+  ├── Background thread? → SamplingErrorResponse (rejected)
+  ├── io.Connect modal available? → noInputsConfirmationDialog
+  │     ├── "Continue" → AgentService.getSamplingResponse() → SamplingSuccessResponse
+  │     └── "Cancel" → SamplingErrorResponse
+  └── Fallback → OverlayService.showPanelOverlay()
+        ├── "Continue" → AgentService.getSamplingResponse() → SamplingSuccessResponse
+        └── "Cancel" → SamplingErrorResponse
+```
+
+**Stop reason mapping:** Agent `finishReason` is mapped to MCP stop reasons:
+- `'stop'` → `'endTurn'`
+- `'length'` → `'maxTokens'`
+- other → `'endTurn'` (default)
+
+### Elicitation
+
+```
+MCP Server → ElicitationRequest → ElicitationService.handleElicitationRequest()
+  ├── Invalid _meta.toolName? → ElicitationRejectionResponse
+  ├── Background thread? → ElicitationCancelResponse
+  ├── io.Connect modal available? → Dialog with Accept/Decline
+  │     ├── "Accept" → ElicitationConfirmationResponse { action: 'accept', content: {} }
+  │     ├── "Decline" → ElicitationRejectionResponse { action: 'decline' }
+  │     └── Close → ElicitationCancelResponse { action: 'cancel' }
+  └── Fallback → OverlayService panel
+```
+
+---
+
+## MCP Apps Integration
+
+### How it works
+
+1. **Config** — consumer provides `mcp.mcpApps` (sandboxProxyUrl + displayMode) and `extensions['io.modelcontextprotocol/ui']` in capabilities
+2. **Init** — `IOIntelWebService.initialize()` passes config to ai-web which starts the MCP Apps controller
+3. **Attach** — `McpAppsService.attach(api)` subscribes to app lifecycle events
+4. **Stream interception** — during AG-UI streaming, ai-web's stream interceptor watches for tools with `_meta.ui.resourceUri` and auto-creates app instances
+5. **Rendering** — `McpAppResourceComponent` mounts the `AppInstance.element` (sandbox proxy iframe) for inline mode; workspace mode opens an io.Connect workspace window
+6. **Communication** — apps use `postMessage` (inline) or io.Connect interop (workspace) to exchange data with the host
+7. **Thread lifecycle** — on thread switch, `McpAppsService` closes all apps and recreates pending ones for the new thread
+
+### Duplicate handling
+
+When a tool is called while an instance already exists (workspace mode), `McpAppsService` shows a 3-option dialog:
+- Uses io.Connect modal if available
+- Falls back to overlay panel
+- Options: Replace Oldest / Replace All / New Instance
+
+---
+
+## Styling
+
+- **Tailwind CSS** — main styling approach, built from `src/styles.css` via PostCSS
+- **Exported stylesheet** — `@interopio/io-assist-ng/styles.css` must be imported by the consumer
+- **Prism.js** — injected at runtime for code syntax highlighting
+- **Inter font** — injected at runtime from Google Fonts CDN
+- **Theme sync** — CSS variables adapt to io.Connect dark/light theme via `IOConnectService`
+
+---
+
+## Testing
+
+- Test files are colocated with source (`*.spec.ts` alongside `*.ts`)
+- Framework: Karma + Jasmine
+- Run: `npm run test:disable` (currently disabled in CI)
+- Coverage:
+  - Most component/service specs are smoke tests (`should create`)
+  - `icon.utils.spec.ts` has extensive behavior/security tests for SVG sanitization
+  - Store reducers/selectors/actions have basic coverage