@m6d/cortex-angular

Angular AI chat UI library. Provides a self-contained chat widget with streaming messages, tool call visualization, composer attachments, syntax highlighting, and i18n support.

Usage

import { CortexChatWidgetComponent, CortexClientConfig } from '@m6d/cortex-angular';

@Component({
  imports: [CortexChatWidgetComponent],
  template: `<cortex-chat-widget [config]="config" />`,
})
export class MyComponent {
  protected readonly config: CortexClientConfig = {
    locale: signal('en'),
    transport: {
      baseUrl: '/api/agents/assistant',
      getHeaders: () => ({ Authorization: `Bearer ${token}` }),
    },
    // The WebSocket URL is derived from baseUrl (…/agents/assistant/ws); set
    // `wsUrl` only to override it, and point it at that same agent-scoped path.
  };
}

No root-level providers needed — each widget instance is fully self-contained. You can render multiple widgets with different configs on the same page.

Configuration

| Property | Type | Description | | ----------------------- | ------------------------------- | ------------------------------------------------------------------------------- | | locale | Signal<string> | Active locale ("en", "ar") | | transport.baseUrl | string \| Signal<string> | Agent API base URL | | transport.getHeaders | () => Record<string, string> | Request headers provider | | wsUrl | string | WebSocket URL for real-time events (optional) | | theme | CortexClientTheme | 'light' \| 'dark' \| 'system' (default: 'light') | | showDebugButton | boolean | Show/hide the debug toggle button (default: false) | | toolComponents | Record<string, Type<unknown>> | Custom Angular components for tool rendering (optional) | | onToolCall | (toolCall) => unknown | Client-side tool call handler (optional) | | trustSameOriginEmbeds | boolean | Allow embedded tool pages served from this page's own origin (default: false) |

transport.getHeaders can return any request headers needed by the host app. WebSocket auth continues to derive the token query param from a bearer Authorization header when present.

Client tools

Control-Center tools published with type "embedded" render inside the chat as an embedded flow (payment, signature, ...): the widget asks the server to initiate, shows the returned page in a sandboxed iframe (inline card or modal, per tool config), and submits the page's cortex:client-tool postMessage outcome back to the run as-is — anything that must actually be true lives in the integrating backend's own records. No widget configuration is needed. One caveat: an embed served from the host page's own origin is refused by default, because a same-origin iframe cannot be sandboxed — it could reach into the host page, and embed URLs come from Control Center tool config, whose administrator is not necessarily the site owner. When both are the same party and the embeds are the site's own pages, set trustSameOriginEmbeds: true to render them anyway (with full access, as any of the site's own pages has). Other pending tool calls keep the existing toolComponents / hooks.onToolCall behavior. That hook is also how static client tools work: declare an executor-less tool in the server config and answer it here by returning its output from hooks.onToolCall for that tool name. Consumer hooks.onToolCall implementations must return undefined for tool names they do not own — answering an unknown pending call would settle an embedded flow before the user completes it.

Requirements

• Angular >= 21.2.0