@m6d/cortex-angular 0.11.1 → 0.13.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@m6d/cortex-angular",
-  "version": "0.11.1",
-  "description": "Reusable AI agent chat UI library for Angular",
+  "version": "0.13.0",
+  "description": "Angular chat widget for Cortex agents",
   "license": "MIT",
   "sideEffects": false,
   "exports": {
@@ -40,7 +40,10 @@
   },
   "releaseWatchPaths": [
     "internal/client",
-    "internal/contracts"
+    "internal/contracts/src/charts",
+    "internal/contracts/src/client-tools",
+    "internal/contracts/src/markdown",
+    "internal/contracts/src/wire"
   ],
   "module": "fesm2022/m6d-cortex-angular.mjs",
   "typings": "types/m6d-cortex-angular.d.ts",

package/theme.css

@@ -64,7 +64,7 @@
   /* These read --cortex-font-size (or the color named) when unset, so they ship
    * unset: declaring one here gives that part its own value. Code blocks default
    * to a tint of the heading color, so they stand a step off whatever they sit
-   * on: the transcript, the user's bubble, or a host's own surface.
+   * on: the transcript, the user's bubble, or a consumer's own surface.
    *
    * --cortex-font-size-message: 0.875rem;      message text and the composer
    * --cortex-font-size-header: 0.875rem;       the chat and history titles

package/types/m6d-cortex-angular.d.ts

@@ -22,6 +22,11 @@ declare const ATTACHMENT_ORIGINS: readonly [
 	"tool"
 ];
 export type AttachmentOrigin = (typeof ATTACHMENT_ORIGINS)[number];
+declare function checkAttachmentPolicy(file: {
+	type: string;
+	size: number;
+	name: string;
+}): "type" | "size" | "name" | "ok";
 export type AttachmentSummary = {
 	id: string;
 	filename: string;
@@ -43,8 +48,16 @@ export type ThreadSummary = {
 	};
 };
 /**
- * What the server offers this agent's clients, fetched once at widget startup.
- * The widget hides UI for anything absent; enforcement stays server-side.
+ * Body of `POST /threads`. Only a console operator's request is read: its
+ * test thread keeps `variables` as the session the agent's server would
+ * otherwise fill per end user.
+ */
+export type CreateThreadRequest = {
+	variables?: Record<string, string | number | boolean>;
+};
+/**
+ * What Cortex offers this agent's clients, fetched once at widget startup.
+ * The widget hides UI for anything absent; Cortex enforces each.
  */
 export type AgentCapabilities = {
 	attachments: boolean;
@@ -63,18 +76,24 @@ export type Suggestion = {
 	title: string;
 	prompt: string;
 };
-/** The runtime contract's `suggestionsSchema` and `greetingSchema` are built from these. */
+/** The manifest's suggestion and greeting schemas are built from these. */
 export type Suggestions = Record<Locale, Suggestion[]>;
 export type Greeting = Record<Locale, string>;
 export type CortexHeaders = Record<string, string>;
 /**
- * How the widget reaches its cortex server. `baseUrl` may be a thunk so a host
- * with a reactive origin (an Angular Signal is itself a `() => string`) is read
+ * How the widget reaches Cortex. `baseUrl` may be a thunk so a consumer with
+ * a reactive origin (an Angular Signal is itself a `() => string`) is read
  * at the moment of each request rather than captured once.
  */
 export type CortexTransport = {
 	baseUrl: string | (() => string);
 	getHeaders: () => CortexHeaders | Promise<CortexHeaders>;
+	/**
+	 * Sent with every thread the widget creates. The console's playground puts
+	 * a test thread's variables here; Cortex honours it only from a verified
+	 * console operator.
+	 */
+	threadBody?: CreateThreadRequest;
 };
 export type ColorScheme = "light" | "dark";
 export type MediaRenderContext = {
@@ -98,7 +117,7 @@ export type CortexTheme = "light" | "dark" | "system";
 export type CortexToolCallContext = {
 	threadId: string;
 };
-/** A tool the server left for the client to answer. */
+/** A tool call Cortex left for the client to answer. */
 export type CortexToolCall = {
 	toolCallId: string;
 	toolName: string;
@@ -151,16 +170,16 @@ export type CortexConfig = {
 	 * Render embedded tool pages served from this page's own origin with their
 	 * full identity — which, same-origin, means no effective sandbox at all: such
 	 * an embed can reach into the host page. By default they are refused
-	 * (rendered inert), because embed URLs come from Control Center tool config,
-	 * and whoever administers that is not necessarily whoever owns this site.
-	 * Enable only when both are the same party and the embeds are this site's
-	 * own pages — then a second origin just for embeds is no longer needed.
+	 * (rendered inert), because embed URLs come from the tool's definition in
+	 * Cortex, and whoever administers that is not necessarily whoever owns this
+	 * site. Enable only when both are the same party and the embeds are this
+	 * site's own pages, so the embeds need no origin of their own.
 	 */
 	trustSameOriginEmbeds?: boolean;
 	hooks?: CortexHooks;
 };
 /**
- * What the header receives, the host's own or the widget's: where the widget
+ * What the header receives, the consumer's own or the widget's: where the widget
  * is, what to show, and the actions the default header offers. One header
  * serves both screens; `screen` says which is showing.
  */
@@ -171,10 +190,10 @@ export type CortexHeaderContext = {
 	title: string | null;
 	/** `agentName` in the widget's locale. */
 	agentName: string | undefined;
-	/** How many conversations the history lists; 0 while it loads. */
-	threadCount: number;
+	/** How many conversations the history lists; undefined while the first load is out. */
+	threadCount: number | undefined;
 	isWorking: boolean;
-	/** Whether the host enabled the debug switch, and whether it is on. */
+	/** Whether the consumer enabled the debug switch, and whether it is on. */
 	debug: {
 		shown: boolean;
 		on: boolean;
@@ -187,13 +206,13 @@ export type CortexHeaderContext = {
 	toggleDebug: () => void;
 };
 /**
- * What the blank-chat landing receives, the host's own or the widget's. The
+ * What the blank-chat landing receives, the consumer's own or the widget's. The
  * composer arrives ready to place as the SDK's own view type (`View`), so a
  * custom landing keeps the widget's attachments and send rules. Each SDK
  * exports it as `CortexLandingContext` with its view type filled in.
  */
 export type LandingContext<View> = {
-	/** The agent's greeting in the widget's locale, or the built-in one. */
+	/** The agent's greeting in the widget's locale, or the built-in one; empty until the handshake answers. */
 	greeting: string;
 	/** Empty until the handshake answers, and for an agent that takes no messages. */
 	suggestions: Suggestion[];
@@ -210,7 +229,7 @@ export type LandingContext<View> = {
 	/** Shows the whole history: its screen, or the sidebar in full mode, as the header's `openHistory`. */
 	openHistory: () => void;
 };
-/** What the history's list receives, the host's own or the widget's. Its header is the header slot. */
+/** What the history's list receives, the consumer's own or the widget's. Its header is the header slot. */
 export type CortexThreadListContext = {
 	/** Newest first; undefined while the first load is out. */
 	threads: ThreadSummary[] | undefined;
@@ -220,20 +239,41 @@ export type CortexThreadListContext = {
 	deleteThread: (threadId: string) => void;
 	newChat: () => void;
 };
-/** Each part of the widget a host can draw itself, with the context it receives. */
+/** Each part of the widget a consumer can draw itself, with the context it receives. */
 export type CortexSlotContexts<View> = {
 	header: CortexHeaderContext;
 	landing: LandingContext<View>;
 	threadList: CortexThreadListContext;
 };
+/** Why Cortex dropped a message instead of running it: a call on the thread waits for approval. */
+export type SendRefusal = "approval_pending";
+/** Why the composer refused a file before uploading it: the attachment policy's reason, or one file too many. */
+export type AttachmentRefusal = Exclude<ReturnType<typeof checkAttachmentPolicy>, "ok"> | "count";
 export type QueuedAttachment = {
 	localId: string;
 	filename: string;
 	status: "uploading" | "ready" | "deleting" | "error";
+	/** Set on an `error` chip the composer never uploaded. */
+	refusal?: AttachmentRefusal;
 	threadId?: string;
 	attachmentId?: string;
 	summary?: AttachmentSummary;
 };
+/**
+ * Why Cortex left a read unanswered: it could not be reached (or failed),
+ * it refused the caller's sign-in (401), or it serves no such agent (404).
+ */
+export type Unanswered = "unreachable" | "refused" | "missing";
+/**
+ * A turn shown as failed, with Cortex's reason when it gave one (a message
+ * that never got out has none). The reason may name the model provider's
+ * answer, so a widget shows it only where its debug view is offered. A
+ * message Cortex refused names why instead.
+ */
+export type TurnFailure = {
+	reason: string | undefined;
+	refusal?: SendRefusal;
+};
 declare const ATTACHMENT_STATUSES$1: readonly [
 	"pending",
 	"described",
@@ -261,7 +301,7 @@ export type CortexAngularConfig = CortexConfig & {
 };
 /** The landing's context, its composer a template to place with `ngTemplateOutlet`. */
 export type CortexLandingContext = LandingContext<TemplateRef<unknown>>;
-/** Each part of the widget a host can draw itself, with the context it receives. */
+/** Each part of the widget a consumer can draw itself, with the context it receives. */
 export type CortexAngularSlotContexts = CortexSlotContexts<TemplateRef<unknown>>;
 declare class AttachmentQueueService {
 	readonly items: import("@angular/core").WritableSignal<QueuedAttachment[]>;
@@ -281,6 +321,7 @@ declare class AttachmentQueueService {
 			summary: AttachmentSummary$1;
 			localId: string;
 			filename: string;
+			refusal?: "type" | "size" | "name" | "count";
 			threadId?: string;
 			attachmentId?: string;
 		}[];
@@ -294,7 +335,7 @@ declare class AttachmentQueueService {
 declare class CortexChatService {
 	/**
 	 * Selection is the Thread handed to `selectThread`, resolved against the live
-	 * list: the row there receives the title and isRunning updates the server
+	 * list: the row there receives the title and isRunning updates Cortex
 	 * pushes, so the selection follows them without hand-syncing. The snapshot
 	 * only answers for a thread the list has not caught up with yet.
 	 */
@@ -306,14 +347,22 @@ declare class CortexChatService {
 	readonly isAgentWorking: import("@angular/core").Signal<boolean>;
 	/**
 	 * Derived, never hand-synced: a call only counts as owed while the stream is
-	 * idle — mid-turn an unsettled call is just a server tool executing. Reading
+	 * idle — mid-turn an unsettled call is just a tool Cortex is executing. Reading
 	 * straight from the SDK's signals is what brings the composer back the
 	 * instant `addToolResult` settles the call part — the SDK's delivery promise
 	 * only resolves once the continuation turn ends, far too late to gate UI on.
 	 */
 	readonly hasPendingToolCalls: import("@angular/core").Signal<boolean>;
-	/** What the server offers this agent's clients; undefined until the handshake answers. */
+	/** A call waits for the user to approve or deny it: no message may go out until it is decided. */
+	readonly awaitsApproval: import("@angular/core").Signal<boolean>;
+	/** The last turn failed: Cortex said its run failed, or the message never got out. */
+	readonly turnFailure: import("@angular/core").WritableSignal<TurnFailure | undefined>;
+	/** The text of a message Cortex refused, handed back to the composer until a message goes out. */
+	readonly returnedDraft: import("@angular/core").WritableSignal<string | undefined>;
+	/** What Cortex offers this agent's clients; undefined until the handshake answers. */
 	readonly capabilities: import("@angular/core").WritableSignal<AgentCapabilities | undefined>;
+	/** Why the handshake has not answered yet, once a try has failed. */
+	readonly unanswered: import("@angular/core").WritableSignal<Unanswered | undefined>;
 	private readonly events;
 	private readonly selectedThreadSnapshot;
 	private readonly config;
@@ -340,7 +389,7 @@ declare class CortexChatService {
 	 * Capability-gated controls stay hidden until the handshake answers, so it
 	 * is asked until it does, and afresh after every reconnect: the old answer
 	 * may be stale (a trigger toggled while the socket was down), so it is
-	 * forgotten first.
+	 * forgotten first. Why it has not answered is shown until an answer arrives.
 	 */
 	private loadCapabilities;
 	get events$(): Observable<"onError" | "onFinish" | "onThreadSelected" | "onSend">;
@@ -354,17 +403,17 @@ declare class CortexChatService {
 	 */
 	ensureThread(): Observable<string>;
 	send(prompt: string, attachments?: AttachmentSummary[]): Observable<void>;
-	/** Answers a tool call on behalf of a consumer-supplied tool component.
-	 * Returns the delivery promise so callers (the client tool embed) can
-	 * re-arm on a transient failure instead of stranding the pending call. */
+	/** Answers a tool call on behalf of a tool component or the client tool
+	 * embed. Returns the delivery, which fails when the answer did not reach
+	 * Cortex, so the caller can ask for it again instead of stranding the call. */
 	addToolResult(toolCallId: string, toolName: string, output: unknown): Promise<void>;
-	/** The user's decision on a server tool the run parked on; the run resumes once delivered. */
+	/** The user's decision on a call the run parked on; the run resumes once delivered. */
 	respondToApproval(approvalId: string, approved: boolean): Promise<void>;
 	abort(): Promise<void>;
 	deleteThread(threadId: string): Observable<void>;
 	/**
-	 * Points the widget at a thread with a chat client of its own. The client is
-	 * server-authoritative: on mount it asks cortex for the transcript and for
+	 * Points the widget at a thread with a chat client of its own. Cortex owns
+	 * the transcript: on mount the client asks it for the transcript and for
 	 * whatever run is still generating, so selecting a thread, reloading the page
 	 * and a second tab all re-attach through one path.
 	 */
@@ -398,17 +447,19 @@ export declare class CortexChatWidgetComponent implements OnInit {
 	protected readonly viewMode: import("@angular/core").Signal<CortexViewMode>;
 	private readonly composer;
 	private readonly landingComposer;
-	/** The host's own parts by slot; each replaces the widget's default and gets the same context. */
+	/** The consumer's own parts by slot; each replaces the widget's default and gets the same context. */
 	private readonly slotDirectives;
 	protected readonly slots: import("@angular/core").Signal<Map<keyof CortexAngularSlotContexts, TemplateRef<{
 		$implicit: CortexHeaderContext | CortexThreadListContext | LandingContext<TemplateRef<unknown>>;
 	}>>>;
+	/** Why the handshake has not answered, worded for the composer's place. */
+	protected readonly unansweredNotice: import("@angular/core").Signal<"translate_access_refused" | "translate_agent_unreachable" | "translate_agent_missing" | undefined>;
 	protected readonly chatHeader: import("@angular/core").Signal<{
 		screen: "chat" | "threads";
 		viewMode: CortexViewMode;
 		title: string | null;
 		agentName: string | undefined;
-		threadCount: number;
+		threadCount: number | undefined;
 		isWorking: boolean;
 		debug: {
 			shown: boolean;
@@ -424,7 +475,7 @@ export declare class CortexChatWidgetComponent implements OnInit {
 		viewMode: CortexViewMode;
 		title: string | null;
 		agentName: string | undefined;
-		threadCount: number;
+		threadCount: number | undefined;
 		isWorking: boolean;
 		debug: {
 			shown: boolean;
@@ -482,7 +533,7 @@ export type SlotTemplateContext<Slot extends SlotName> = {
 	$implicit: CortexAngularSlotContexts[Slot];
 };
 /**
- * Marks the host's own part of `<cortex-chat-widget>`, named by `cortexSlot`:
+ * Marks the consumer's own part of `<cortex-chat-widget>`, named by `cortexSlot`:
  * `header`, `landing` or `threadList`. It replaces the widget's default and
  * receives the context the default is drawn from; `header` serves both the
  * chat and the history screen.