@memberjunction/ng-conversations 5.40.1 → 5.41.0

package/README.md

@@ -2,6 +2,20 @@
 
 A comprehensive Angular component library for building conversation-based interfaces in MemberJunction, including messaging, artifact management, collections, projects, tasks, agent interaction panels, and collaboration features.
 
+> **Layering note.** The orchestration logic (agent dispatch, default-agent resolution, mention parsing, bridge state, streaming, client tools, sessions observability) lives in **`@memberjunction/conversations-runtime`** — a pure-TS, framework-agnostic package. This widget is one consumer of the runtime; React/Vue/Node hosts are also intended consumers. The widget is automatically wired to the runtime via `ConversationsRuntimeBootstrap` (registered `providedIn: 'root'`), which injects adapters for notifications, active-task tracking, and realtime sessions. See [`guides/CONVERSATIONS_UX_STACK_GUIDE.md`](../../../../guides/CONVERSATIONS_UX_STACK_GUIDE.md) for the full architecture.
+
+## Customization without forking
+
+The widget exposes three layers of extension:
+
+| Surface | What it lets you do |
+|---|---|
+| **6 named slots** (`mjChatSlot` directive) | Replace the `header`, `emptyState`, `agentPresence`, `messageRenderer`, `messageExtra`, or `demonstrationSurface` regions with your own templates. Three consumption modes: project an ad-hoc template, wrap the exported default for containment, or subclass the default. |
+| **Before/After cancelable events** | `(beforeAgentTurn)`, `(beforeToolInvoked)`, `(beforeResponseFormSubmitted)` let you observe AND veto (`event.Cancel = true`) before the action runs. Plus informational `(sessionStarted)` / `(sessionChannelStateChanged)` / `(sessionEnded)` for realtime lifecycle. |
+| **`--mj-chat-*` design tokens** | Override bubble colors, composer chrome, character accents, and voice-state hues via standard CSS custom-property overrides. Defaults adapt to dark mode through semantic `--mj-*` tokens. |
+
+Slot interfaces + cloneable default components + the `ChatSlotDirective` are exported — see the public API.
+
 ## Overview
 
 The `@memberjunction/ng-conversations` package is a large, feature-rich module that powers MemberJunction's conversation UI. It provides 40+ components covering the entire conversation lifecycle: message composition and rendering (with markdown, mentions, code blocks, and artifacts), conversation navigation and history, threaded discussions, artifact collections and libraries, project/task management, agent execution panels, sharing/permission modals, search, notifications, and export.
@@ -192,6 +206,31 @@ The overlay is generic — it raises events for navigation and tool execution. T
 </mj-active-agent-indicator>
 ```
 
+### Real-Time Voice (Co-Agent) UX
+
+The package hosts the full client UX for MJ's real-time co-agent sessions — live voice calls with the conversation's agent, with interactive channel surfaces (the live Whiteboard) docked beside the call. Architecture background: [guides/REALTIME_CO_AGENTS_GUIDE.md](../../../../guides/REALTIME_CO_AGENTS_GUIDE.md).
+
+**`RealtimeSessionService`** (`services/realtime-session.service.ts`) is the provider-agnostic orchestrator, injectable at root. It drives a **client-direct** session: it calls the `StartRealtimeClientSession` mutation to mint a server-scoped ephemeral credential, resolves the matching `BaseRealtimeClient` driver (from `@memberjunction/ai-realtime-client` — OpenAI, Gemini, ElevenLabs, or AssemblyAI) through the ClassFactory by the server-reported `Provider` key, and connects the browser **directly** to the realtime provider — audio frames never transit the MJ server; only tool calls, final transcripts, channel state, and usage telemetry relay back over GraphQL. It exposes the reactive session state hosts consume: `ConnectionState$` (`connecting | listening | speaking | thinking | error | closed`), `Captions$`, `Active$`, `DelegationProgress$` / `DelegationResult$` / `DelegationNarration$`, `ActiveChannels$`, `ChannelFocus$`, `Minimized$`, plus `SendText` (typed input into the live call), `ToggleMute`, `RegisterClientToolHandler` (prefix-routed, client-executed UI tools), and the explicit delegation cancel channel — `CancelDelegation(callId)` / `CancelInFlightDelegations()` call the `CancelRealtimeSessionTool` mutation and flip the card to "Cancelled by user" (deliberate policy: **true barge-in never aborts delegated work** — only the per-card ✕ does). The client driver's `OnUsage` token deltas are accumulated and relayed onto the co-agent's observability prompt run via `RelayRealtimeUsage`, debounced (10 s) plus a teardown flush.
+
+**Co-agent selection, pairing constraints & authorization-gated overrides**: the composer's voice picker (`mj-voice-agent-picker`, opened by the caret next to the phone button — or automatically on a conversation with no prior agent participation) lets every user choose which **co-agent** (ACTIVE Realtime-type agent, from the same run-permission-filtered cache the @mention routing uses) fronts the call when more than one exists; the choice rides the mint's `coAgentId` and persists cross-device via `UserInfoEngine` (`mj.realtimeVoice.coAgent.v1`), so the friction-free instant start honors it too. A co-agent with rows in `MJ: AI Agent Paired Agents` may only front its paired targets — the picker constrains the target list to those rows (Sequence order, `IsDefault` preselected; pure helpers in `services/voice-pairing.ts`) — while a co-agent with zero rows stays universal (today's flow untouched; pairings constrain a chosen co-agent, they never mandate one). The **voice-model selector** (and any future session-config override, carried as the mint's `configOverridesJson`, e.g. `{"realtime":{"modelPreference":…}}`) renders only for users holding the **`Realtime: Advanced Session Controls`** MJ Authorization — evaluated client-side by the pure `UserHoldsAuthorization` helper (`services/user-authorization.ts`) from cached metadata as a *disclosure* gate; the server independently enforces the authorization on the mint, and unauthorized users silently get server defaults. (The gear popover's interface-density control is UX disclosure, not session config — it is not gated.)
+
+**The call overlay** (`components/realtime/`): `RealtimeSessionOverlayComponent` (`mj-realtime-session-overlay`) fills the conversation panel in place while a session is active — hosted by `ConversationChatAreaComponent` behind `Active$`, started from the mic button in `MessageInputComponent`. Two columns:
+
+- **Main column** — the unified APP-BAR (`RealtimeAgentBannerComponent`: identity + turn state + model name + the disclosure-gated action cluster — captions, the gear popover hosting the interface-density escape hatch and developer links, minimize, End call; in review the Start-live + Close actions live here too), then the pure-audio hero orb OR the unified session thread (`RealtimeSessionThreadComponent`, fed by the shared `RealtimeSessionState` merge of caption/delegation/narration streams), the channel strip, and the bottom dock (`RealtimeComposerComponent`: phone-call strip at low disclosure levels ⇄ fused mute/captions minis + typed composer at level 2+; typed turns behave identically to spoken ones).
+- **Right panel** — `RealtimeSurfaceTabsComponent`, the tabbed surface panel (`RealtimeSurfaceTabsModel` is the framework-free, unit-tested tab state): channel tabs lead the strip, then **one tab per artifact** a delegated run produces (added UNFOCUSED with a persistent violet "unseen" glow until visited — content never steals the screen), with the Activity rail pinned LAST.
+
+**Progressive disclosure** (`realtime-disclosure.ts`): the console *grows with the user*. A first-ever call is PURE AUDIO — a breathing hero orb, mute / Details / End, nothing to read; the caption thread, composer dock, surface panel and gear unlock by level (0–4) as the user acts (the hero's "Show the conversation", the T-to-type hotkey, the Details peek) or across sessions via the per-user milestones ratchet (UserInfoEngine, `mj.realtimeVoice.uxMilestones.v1`; the gear's Simple/Standard/Pro/Auto density control is the manual escape hatch). Content never flips the console open — **the one auto-reveal is a channel's first agent activity** (`RealtimeSessionService.ChannelActivity$`): the panel opens as a peek with that channel's tab focused + flashed, while the left column stays exactly as it was. Review mode bypasses disclosure entirely.
+
+**Audio-reactive visuals** (`realtime-audio-visuals.ts`): when the active driver meters its audio planes (`BaseRealtimeClient.GetAudioActivity()` — all four current drivers do, both directions), the overlay samples it on a requestAnimationFrame loop *outside Angular* and writes CSS variables directly: the hero orb scales with the smoothed output envelope (speaker-cone attack/decay), the EQ bars render the true 9-bin spectrum, and the visuals recolor by speaking direction (agent = brand, user = green) with hysteresis so syllable gaps never flicker. Un-metered drivers gracefully keep the turn-state-driven animations. See the guide's §11 for the full pipeline.
+
+**Interactive channels are plugins** — the shell is channel-agnostic. `BaseRealtimeChannelClient` (`components/realtime/channels/base-realtime-channel-client.ts`) is the contract: a client-executed tool set declared to the realtime model at session mint, a perception serializer feeding coalesced state deltas into the model as context notes, a dynamically-created Angular surface component the plugin binds itself, a persisted state of record, prior-session restore (`RestoreState`), artifact snapshots (`SaveAsArtifact`), and focus-mode layout requests. Plugins resolve at session start from the `MJ: AI Agent Channels` registry by `ClientPluginClass` key.
+
+**The live Whiteboard is a thin consumer of [`@memberjunction/ng-whiteboard`](../whiteboard/README.md)** — the board itself (the `WhiteboardState` engine, the `Whiteboard_*` tool API, the host/board/toolbar/zoom/popover/snapshot components, exports, the sandboxed-HTML-widget input bridge, the context menu) lives in that generic package; read its README for whiteboard details. This package contributes only the integration glue (`components/realtime/whiteboard/`): `RealtimeWhiteboardChannel`, the ~200-line channel plugin that declares `WHITEBOARD_TOOL_DEFINITIONS` to the model, routes `Whiteboard_*` calls to the bound host (or the pure engine call when the pane is collapsed), pipes the coalesced `SceneDelta` stream into the model as `[whiteboard]` context notes (with do-not-narrate-minor-edits etiquette inline), forwards widget submissions (`MJWhiteboard.submit` — the tutoring loop) and agent-undo events, persists/restores the board as the channel's state of record, and snapshots it to versioned `MJ: Artifacts`; plus `WhiteboardArtifactViewerPlugin` (`mj-whiteboard-artifact-viewer`), the saved-board artifact viewer rendered through the package's read-only snapshot component.
+
+**Session review & resume carryover**: a past session replays through the same overlay in review mode — `ConversationChatAreaComponent.OpenRealtimeSessionReview(agentSessionId)` loads a `RealtimeSessionReview` via `RealtimeSessionReviewService`. The loader is **chain-aware**: a session resumed via `lastSessionId` chains legs, and the loader walks the chain backwards (capped, cycle-guarded), rendering every leg chronologically with a divider between legs that carries the previous leg's `CloseReason` as a chip; the chain's conversation-history artifacts load as unfocused artifact tabs, and a read-only Whiteboard tab appears when a board was saved. "Start live session" resumes as a new session chained via `lastSessionId` — saved channel states restore *and* the prior legs' transcript is hydrated into the new model's prompt server-side. The conversations resource also accepts a `realtimeSessionId` query param (the deep link the custom `MJ: AI Agent Sessions` form emits) and opens review mode directly.
+
+This package never navigates (no Router): developer links emit a `RealtimeNavigateRequest` the host converts onto its `openEntityRecord` chain, and minimizing the call shows the host's floating "on call" pill while the session stays live.
+
 ### Collaboration
 
 ```html
@@ -272,6 +311,22 @@ The overlay is generic — it raises events for navigation and tool execution. T
 | `ActiveAgentIndicatorComponent` | `mj-active-agent-indicator` | Active processing indicator |
 | `ActiveTasksPanelComponent` | `mj-active-tasks-panel` | Active tasks panel |
 
+### Real-Time Voice Components
+
+| Component | Selector | Description |
+|-----------|----------|-------------|
+| `RealtimeSessionOverlayComponent` | `mj-realtime-session-overlay` | The in-place "call mode" overlay for a live voice session (progressive-disclosure console: pure-audio hero → full two-column; audio-reactive orb/EQ) |
+| `RealtimeAgentBannerComponent` | `mj-realtime-agent-banner` | The unified app-bar: identity + turn-state + disclosure-gated actions (captions, gear popover w/ density + dev links, minimize, End; review Start-live + Close) |
+| `RealtimeSessionThreadComponent` | `mj-realtime-session-thread` | Unified live thread (captions, delegation cards, ephemeral narration) |
+| `RealtimeActivityRailComponent` | `mj-realtime-activity-rail` | Session activity rail (the surface panel's pinned-last tab) |
+| `RealtimeDelegationCardComponent` | `mj-realtime-delegation-card` | "Working on it" → result card for a delegated agent run |
+| `RealtimeChannelStripComponent` | `mj-realtime-channel-strip` | Chip-per-channel strip |
+| `RealtimeComposerComponent` | `mj-realtime-composer` | The bottom dock: phone-call strip (levels 0–1: mute / captions / Details peek / End) ⇄ fused minis + typed composer (level 2+) |
+| `RealtimeSurfaceTabsComponent` | `mj-realtime-surface-tabs` | Tabbed surface panel: channel tabs first, glowing unfocused artifact tabs, Activity pinned last (backed by the framework-free, unit-tested `RealtimeSurfaceTabsModel`) |
+| `WhiteboardArtifactViewerComponent` | `mj-whiteboard-artifact-viewer` | Saved-board artifact viewer (registered as `WhiteboardArtifactViewerPlugin`); renders via `@memberjunction/ng-whiteboard`'s snapshot component |
+
+> The live whiteboard surface itself (`mj-realtime-whiteboard-host`, board, toolbar, zoom, "What the agent sees" popover) ships in [`@memberjunction/ng-whiteboard`](../whiteboard/README.md); the `RealtimeWhiteboardChannel` plugin here creates it dynamically in a channel tab.
+
 ### Utility Components
 
 | Component | Selector | Description |
@@ -325,6 +380,8 @@ RxJS `BehaviorSubject` instances for all state, with derived observables using `
 | `@memberjunction/ng-markdown` | Markdown rendering |
 | `@memberjunction/ng-shared-generic` | Shared generic components |
 | `@memberjunction/ng-testing` | Testing framework components |
+| `@memberjunction/ng-whiteboard` | The generic collaborative whiteboard (consumed by the realtime Whiteboard channel + artifact viewer) |
+| `@memberjunction/ai-realtime-client` | Browser-side realtime drivers (OpenAI / Gemini / ElevenLabs / AssemblyAI) used by `RealtimeSessionService` |
 
 ### Kendo UI Packages
 

package/dist/__tests__/channel-optional-surface.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=channel-optional-surface.test.d.ts.map

package/dist/__tests__/channel-optional-surface.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-optional-surface.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/channel-optional-surface.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/channel-optional-surface.test.js

@@ -0,0 +1,53 @@
+/**
+ * Unit tests for the OPTIONAL CLIENT SURFACE contract on {@link BaseRealtimeChannelClient} (Phase 2).
+ *
+ * A bridge-contributed channel (e.g. meeting-controls or a platform-native whiteboard) may be
+ * SERVER-ONLY — no MJ Angular surface. The contract change makes `GetSurfaceComponent` optional
+ * (defaults to `null`) and adds `HasSurface()` so the overlay can skip a surfaceless channel's tab
+ * while still wiring its tools + perception. These tests pin both the server-only default and the
+ * surface-bearing override, without rendering Angular.
+ */
+import { describe, it, expect } from 'vitest';
+import { BaseRealtimeChannelClient } from '../lib/components/realtime/channels/base-realtime-channel-client';
+/** A server-only channel: contributes tools + perception, but renders NO surface. */
+class ServerOnlyChannel extends BaseRealtimeChannelClient {
+    get ChannelName() { return 'ServerOnly'; }
+    get ToolNamePrefix() { return 'ServerOnly_'; }
+    get TabTitle() { return 'Server Only'; }
+    get TabIcon() { return 'fa-solid fa-gear'; }
+    GetToolDefinitions() {
+        return [{ Name: 'ServerOnly_Do', Description: 'do', ParametersSchema: { type: 'object' } }];
+    }
+    ApplyAgentTool() { return JSON.stringify({ success: true }); }
+    BindSurface() { }
+}
+/** A surface-bearing channel for the positive case. */
+class FakeSurface {
+}
+class SurfaceChannel extends BaseRealtimeChannelClient {
+    get ChannelName() { return 'WithSurface'; }
+    get ToolNamePrefix() { return 'WithSurface_'; }
+    get TabTitle() { return 'With Surface'; }
+    get TabIcon() { return 'fa-solid fa-chalkboard'; }
+    GetToolDefinitions() { return []; }
+    ApplyAgentTool() { return '{}'; }
+    BindSurface() { }
+    GetSurfaceComponent() { return FakeSurface; }
+}
+describe('BaseRealtimeChannelClient — optional client surface', () => {
+    it('a server-only channel returns null from GetSurfaceComponent and false from HasSurface', () => {
+        const ch = new ServerOnlyChannel();
+        expect(ch.GetSurfaceComponent()).toBeNull();
+        expect(ch.HasSurface()).toBe(false);
+    });
+    it('a server-only channel still contributes tools (tools/perception are unaffected by no surface)', () => {
+        const ch = new ServerOnlyChannel();
+        expect(ch.GetToolDefinitions().map((t) => t.Name)).toEqual(['ServerOnly_Do']);
+    });
+    it('a surface-bearing channel returns its component and reports HasSurface true', () => {
+        const ch = new SurfaceChannel();
+        expect(ch.GetSurfaceComponent()).toBe(FakeSurface);
+        expect(ch.HasSurface()).toBe(true);
+    });
+});
+//# sourceMappingURL=channel-optional-surface.test.js.map

package/dist/__tests__/channel-optional-surface.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-optional-surface.test.js","sourceRoot":"","sources":["../../src/__tests__/channel-optional-surface.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAG9C,OAAO,EAAE,yBAAyB,EAAE,MAAM,kEAAkE,CAAC;AAE7G,qFAAqF;AACrF,MAAM,iBAAkB,SAAQ,yBAAyB;IACvD,IAAW,WAAW,KAAa,OAAO,YAAY,CAAC,CAAC,CAAC;IACzD,IAAW,cAAc,KAAa,OAAO,aAAa,CAAC,CAAC,CAAC;IAC7D,IAAW,QAAQ,KAAa,OAAO,aAAa,CAAC,CAAC,CAAC;IACvD,IAAW,OAAO,KAAa,OAAO,kBAAkB,CAAC,CAAC,CAAC;IACpD,kBAAkB;QACvB,OAAO,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,WAAW,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC9F,CAAC;IACM,cAAc,KAAa,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACtE,WAAW,KAA2C,CAAC;CAE/D;AAED,uDAAuD;AACvD,MAAM,WAAW;CAAG;AACpB,MAAM,cAAe,SAAQ,yBAAsC;IACjE,IAAW,WAAW,KAAa,OAAO,aAAa,CAAC,CAAC,CAAC;IAC1D,IAAW,cAAc,KAAa,OAAO,cAAc,CAAC,CAAC,CAAC;IAC9D,IAAW,QAAQ,KAAa,OAAO,cAAc,CAAC,CAAC,CAAC;IACxD,IAAW,OAAO,KAAa,OAAO,wBAAwB,CAAC,CAAC,CAAC;IAC1D,kBAAkB,KAA+B,OAAO,EAAE,CAAC,CAAC,CAAC;IAC7D,cAAc,KAAa,OAAO,IAAI,CAAC,CAAC,CAAC;IACzC,WAAW,KAAuB,CAAC;IAC1B,mBAAmB,KAAwB,OAAO,WAAW,CAAC,CAAC,CAAC;CACjF;AAED,QAAQ,CAAC,qDAAqD,EAAE,GAAG,EAAE;IACnE,EAAE,CAAC,uFAAuF,EAAE,GAAG,EAAE;QAC/F,MAAM,EAAE,GAAG,IAAI,iBAAiB,EAAE,CAAC;QACnC,MAAM,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC5C,MAAM,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+FAA+F,EAAE,GAAG,EAAE;QACvG,MAAM,EAAE,GAAG,IAAI,iBAAiB,EAAE,CAAC;QACnC,MAAM,CAAC,EAAE,CAAC,kBAAkB,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC;IAChF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6EAA6E,EAAE,GAAG,EAAE;QACrF,MAAM,EAAE,GAAG,IAAI,cAAc,EAAE,CAAC;QAChC,MAAM,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACnD,MAAM,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC","sourcesContent":["/**\n * Unit tests for the OPTIONAL CLIENT SURFACE contract on {@link BaseRealtimeChannelClient} (Phase 2).\n *\n * A bridge-contributed channel (e.g. meeting-controls or a platform-native whiteboard) may be\n * SERVER-ONLY — no MJ Angular surface. The contract change makes `GetSurfaceComponent` optional\n * (defaults to `null`) and adds `HasSurface()` so the overlay can skip a surfaceless channel's tab\n * while still wiring its tools + perception. These tests pin both the server-only default and the\n * surface-bearing override, without rendering Angular.\n */\nimport { describe, it, expect } from 'vitest';\nimport type { Type } from '@angular/core';\nimport { RealtimeToolDefinition } from '@memberjunction/ai';\nimport { BaseRealtimeChannelClient } from '../lib/components/realtime/channels/base-realtime-channel-client';\n\n/** A server-only channel: contributes tools + perception, but renders NO surface. */\nclass ServerOnlyChannel extends BaseRealtimeChannelClient {\n  public get ChannelName(): string { return 'ServerOnly'; }\n  public get ToolNamePrefix(): string { return 'ServerOnly_'; }\n  public get TabTitle(): string { return 'Server Only'; }\n  public get TabIcon(): string { return 'fa-solid fa-gear'; }\n  public GetToolDefinitions(): RealtimeToolDefinition[] {\n    return [{ Name: 'ServerOnly_Do', Description: 'do', ParametersSchema: { type: 'object' } }];\n  }\n  public ApplyAgentTool(): string { return JSON.stringify({ success: true }); }\n  public BindSurface(): void { /* never called — no surface */ }\n  // Deliberately does NOT override GetSurfaceComponent — inherits the null default.\n}\n\n/** A surface-bearing channel for the positive case. */\nclass FakeSurface {}\nclass SurfaceChannel extends BaseRealtimeChannelClient<FakeSurface> {\n  public get ChannelName(): string { return 'WithSurface'; }\n  public get ToolNamePrefix(): string { return 'WithSurface_'; }\n  public get TabTitle(): string { return 'With Surface'; }\n  public get TabIcon(): string { return 'fa-solid fa-chalkboard'; }\n  public GetToolDefinitions(): RealtimeToolDefinition[] { return []; }\n  public ApplyAgentTool(): string { return '{}'; }\n  public BindSurface(): void { /* no-op */ }\n  public override GetSurfaceComponent(): Type<FakeSurface> { return FakeSurface; }\n}\n\ndescribe('BaseRealtimeChannelClient — optional client surface', () => {\n  it('a server-only channel returns null from GetSurfaceComponent and false from HasSurface', () => {\n    const ch = new ServerOnlyChannel();\n    expect(ch.GetSurfaceComponent()).toBeNull();\n    expect(ch.HasSurface()).toBe(false);\n  });\n\n  it('a server-only channel still contributes tools (tools/perception are unaffected by no surface)', () => {\n    const ch = new ServerOnlyChannel();\n    expect(ch.GetToolDefinitions().map((t) => t.Name)).toEqual(['ServerOnly_Do']);\n  });\n\n  it('a surface-bearing channel returns its component and reports HasSurface true', () => {\n    const ch = new SurfaceChannel();\n    expect(ch.GetSurfaceComponent()).toBe(FakeSurface);\n    expect(ch.HasSurface()).toBe(true);\n  });\n});\n"]}

package/dist/__tests__/chat-events.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Tests for the Before/After cancelable chat event arg classes.
+ *
+ * Asserts:
+ *   - CancellableChatEventArgs base class default: Cancel = false.
+ *   - Each Before* class extends CancellableChatEventArgs and carries its
+ *     readonly payload fields.
+ *   - Each After* class carries its payload as readonly fields.
+ *   - Listeners can set Cancel = true on Before events.
+ *
+ * Pure logic — no Angular runtime needed. Vitest-ready.
+ */
+export {};
+//# sourceMappingURL=chat-events.test.d.ts.map

package/dist/__tests__/chat-events.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-events.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/chat-events.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/__tests__/chat-events.test.js

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Tests for the Before/After cancelable chat event arg classes.
+ *
+ * Asserts:
+ *   - CancellableChatEventArgs base class default: Cancel = false.
+ *   - Each Before* class extends CancellableChatEventArgs and carries its
+ *     readonly payload fields.
+ *   - Each After* class carries its payload as readonly fields.
+ *   - Listeners can set Cancel = true on Before events.
+ *
+ * Pure logic — no Angular runtime needed. Vitest-ready.
+ */
+import { describe, it, expect } from 'vitest';
+import { CancellableChatEventArgs, BeforeAgentTurnEventArgs, AfterAgentTurnEventArgs, BeforeToolInvokedEventArgs, AfterToolInvokedEventArgs, BeforeResponseFormSubmittedEventArgs, AfterResponseFormSubmittedEventArgs, SessionStartedEventArgs, SessionChannelStateChangedEventArgs, SessionEndedEventArgs, } from '../lib/events/chat-events';
+describe('CancellableChatEventArgs (base class)', () => {
+    it('defaults Cancel to false', () => {
+        const e = new CancellableChatEventArgs();
+        expect(e.Cancel).toBe(false);
+    });
+    it('lets listeners flip Cancel to true', () => {
+        const e = new CancellableChatEventArgs();
+        e.Cancel = true;
+        e.CancelReason = 'rate-limited';
+        expect(e.Cancel).toBe(true);
+        expect(e.CancelReason).toBe('rate-limited');
+    });
+});
+describe('BeforeAgentTurnEventArgs', () => {
+    it('extends CancellableChatEventArgs and carries its payload', () => {
+        const e = new BeforeAgentTurnEventArgs('conv-1', 'hello', 'app-1');
+        expect(e).toBeInstanceOf(CancellableChatEventArgs);
+        expect(e.ConversationId).toBe('conv-1');
+        expect(e.MessageText).toBe('hello');
+        expect(e.ApplicationId).toBe('app-1');
+        expect(e.Cancel).toBe(false);
+    });
+    it('applicationId defaults to null when omitted', () => {
+        const e = new BeforeAgentTurnEventArgs('conv-1', 'hello');
+        expect(e.ApplicationId).toBeNull();
+    });
+});
+describe('AfterAgentTurnEventArgs', () => {
+    it('carries its payload as readonly fields', () => {
+        const result = { success: true, executionTimeMs: 100 };
+        const e = new AfterAgentTurnEventArgs('conv-1', 'run-1', result);
+        expect(e.ConversationId).toBe('conv-1');
+        expect(e.AgentRunId).toBe('run-1');
+        expect(e.Result).toBe(result);
+    });
+});
+describe('BeforeToolInvokedEventArgs', () => {
+    it('extends CancellableChatEventArgs and carries tool name + args', () => {
+        const e = new BeforeToolInvokedEventArgs('NavigateToRecord', { id: '1' });
+        expect(e).toBeInstanceOf(CancellableChatEventArgs);
+        expect(e.ToolName).toBe('NavigateToRecord');
+        expect(e.Args).toEqual({ id: '1' });
+    });
+});
+describe('AfterToolInvokedEventArgs', () => {
+    it('carries tool name + args + result', () => {
+        const e = new AfterToolInvokedEventArgs('NavigateToRecord', { id: '1' }, { ok: true });
+        expect(e.ToolName).toBe('NavigateToRecord');
+        expect(e.Args).toEqual({ id: '1' });
+        expect(e.Result).toEqual({ ok: true });
+    });
+});
+describe('BeforeResponseFormSubmittedEventArgs', () => {
+    it('extends CancellableChatEventArgs and carries form id + values', () => {
+        const e = new BeforeResponseFormSubmittedEventArgs('form-1', { q1: 'yes' });
+        expect(e).toBeInstanceOf(CancellableChatEventArgs);
+        expect(e.FormId).toBe('form-1');
+        expect(e.Values).toEqual({ q1: 'yes' });
+    });
+});
+describe('AfterResponseFormSubmittedEventArgs', () => {
+    it('carries form id + values as readonly fields', () => {
+        const e = new AfterResponseFormSubmittedEventArgs('form-1', { q1: 'yes' });
+        expect(e.FormId).toBe('form-1');
+        expect(e.Values).toEqual({ q1: 'yes' });
+    });
+});
+describe('Session* informational events', () => {
+    it('SessionStartedEventArgs carries session id + channel kinds', () => {
+        const e = new SessionStartedEventArgs('sess-1', ['text', 'voice']);
+        expect(e.SessionId).toBe('sess-1');
+        expect(e.ChannelKinds).toEqual(['text', 'voice']);
+    });
+    it('SessionChannelStateChangedEventArgs carries session id + channel kind + state', () => {
+        const e = new SessionChannelStateChangedEventArgs('sess-1', 'voice', 'open');
+        expect(e.SessionId).toBe('sess-1');
+        expect(e.ChannelKind).toBe('voice');
+        expect(e.State).toBe('open');
+    });
+    it('SessionEndedEventArgs carries session id + narrowed reason', () => {
+        const e = new SessionEndedEventArgs('sess-1', 'explicit');
+        expect(e.SessionId).toBe('sess-1');
+        expect(e.Reason).toBe('explicit');
+    });
+    it('SessionEndedEventArgs accepts all narrowed reason values', () => {
+        // Compile-time check: the narrowed union should permit exactly these three.
+        const explicit = new SessionEndedEventArgs('sess-1', 'explicit');
+        const error = new SessionEndedEventArgs('sess-1', 'error');
+        const unknown = new SessionEndedEventArgs('sess-1', 'unknown');
+        expect(explicit.Reason).toBe('explicit');
+        expect(error.Reason).toBe('error');
+        expect(unknown.Reason).toBe('unknown');
+    });
+});
+//# sourceMappingURL=chat-events.test.js.map

package/dist/__tests__/chat-events.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-events.test.js","sourceRoot":"","sources":["../../src/__tests__/chat-events.test.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @fileoverview Tests for the Before/After cancelable chat event arg classes.\n *\n * Asserts:\n *   - CancellableChatEventArgs base class default: Cancel = false.\n *   - Each Before* class extends CancellableChatEventArgs and carries its\n *     readonly payload fields.\n *   - Each After* class carries its payload as readonly fields.\n *   - Listeners can set Cancel = true on Before events.\n *\n * Pure logic — no Angular runtime needed. Vitest-ready.\n */\n\nimport { describe, it, expect } from 'vitest';\n\nimport {\n    CancellableChatEventArgs,\n    BeforeAgentTurnEventArgs,\n    AfterAgentTurnEventArgs,\n    BeforeToolInvokedEventArgs,\n    AfterToolInvokedEventArgs,\n    BeforeResponseFormSubmittedEventArgs,\n    AfterResponseFormSubmittedEventArgs,\n    SessionStartedEventArgs,\n    SessionChannelStateChangedEventArgs,\n    SessionEndedEventArgs,\n} from '../lib/events/chat-events';\n\ndescribe('CancellableChatEventArgs (base class)', () => {\n    it('defaults Cancel to false', () => {\n        const e = new CancellableChatEventArgs();\n        expect(e.Cancel).toBe(false);\n    });\n\n    it('lets listeners flip Cancel to true', () => {\n        const e = new CancellableChatEventArgs();\n        e.Cancel = true;\n        e.CancelReason = 'rate-limited';\n        expect(e.Cancel).toBe(true);\n        expect(e.CancelReason).toBe('rate-limited');\n    });\n});\n\ndescribe('BeforeAgentTurnEventArgs', () => {\n    it('extends CancellableChatEventArgs and carries its payload', () => {\n        const e = new BeforeAgentTurnEventArgs('conv-1', 'hello', 'app-1');\n        expect(e).toBeInstanceOf(CancellableChatEventArgs);\n        expect(e.ConversationId).toBe('conv-1');\n        expect(e.MessageText).toBe('hello');\n        expect(e.ApplicationId).toBe('app-1');\n        expect(e.Cancel).toBe(false);\n    });\n\n    it('applicationId defaults to null when omitted', () => {\n        const e = new BeforeAgentTurnEventArgs('conv-1', 'hello');\n        expect(e.ApplicationId).toBeNull();\n    });\n});\n\ndescribe('AfterAgentTurnEventArgs', () => {\n    it('carries its payload as readonly fields', () => {\n        const result = { success: true, executionTimeMs: 100 } as never;\n        const e = new AfterAgentTurnEventArgs('conv-1', 'run-1', result);\n        expect(e.ConversationId).toBe('conv-1');\n        expect(e.AgentRunId).toBe('run-1');\n        expect(e.Result).toBe(result);\n    });\n});\n\ndescribe('BeforeToolInvokedEventArgs', () => {\n    it('extends CancellableChatEventArgs and carries tool name + args', () => {\n        const e = new BeforeToolInvokedEventArgs('NavigateToRecord', { id: '1' });\n        expect(e).toBeInstanceOf(CancellableChatEventArgs);\n        expect(e.ToolName).toBe('NavigateToRecord');\n        expect(e.Args).toEqual({ id: '1' });\n    });\n});\n\ndescribe('AfterToolInvokedEventArgs', () => {\n    it('carries tool name + args + result', () => {\n        const e = new AfterToolInvokedEventArgs('NavigateToRecord', { id: '1' }, { ok: true });\n        expect(e.ToolName).toBe('NavigateToRecord');\n        expect(e.Args).toEqual({ id: '1' });\n        expect(e.Result).toEqual({ ok: true });\n    });\n});\n\ndescribe('BeforeResponseFormSubmittedEventArgs', () => {\n    it('extends CancellableChatEventArgs and carries form id + values', () => {\n        const e = new BeforeResponseFormSubmittedEventArgs('form-1', { q1: 'yes' });\n        expect(e).toBeInstanceOf(CancellableChatEventArgs);\n        expect(e.FormId).toBe('form-1');\n        expect(e.Values).toEqual({ q1: 'yes' });\n    });\n});\n\ndescribe('AfterResponseFormSubmittedEventArgs', () => {\n    it('carries form id + values as readonly fields', () => {\n        const e = new AfterResponseFormSubmittedEventArgs('form-1', { q1: 'yes' });\n        expect(e.FormId).toBe('form-1');\n        expect(e.Values).toEqual({ q1: 'yes' });\n    });\n});\n\ndescribe('Session* informational events', () => {\n    it('SessionStartedEventArgs carries session id + channel kinds', () => {\n        const e = new SessionStartedEventArgs('sess-1', ['text', 'voice']);\n        expect(e.SessionId).toBe('sess-1');\n        expect(e.ChannelKinds).toEqual(['text', 'voice']);\n    });\n\n    it('SessionChannelStateChangedEventArgs carries session id + channel kind + state', () => {\n        const e = new SessionChannelStateChangedEventArgs('sess-1', 'voice', 'open');\n        expect(e.SessionId).toBe('sess-1');\n        expect(e.ChannelKind).toBe('voice');\n        expect(e.State).toBe('open');\n    });\n\n    it('SessionEndedEventArgs carries session id + narrowed reason', () => {\n        const e = new SessionEndedEventArgs('sess-1', 'explicit');\n        expect(e.SessionId).toBe('sess-1');\n        expect(e.Reason).toBe('explicit');\n    });\n\n    it('SessionEndedEventArgs accepts all narrowed reason values', () => {\n        // Compile-time check: the narrowed union should permit exactly these three.\n        const explicit = new SessionEndedEventArgs('sess-1', 'explicit');\n        const error = new SessionEndedEventArgs('sess-1', 'error');\n        const unknown = new SessionEndedEventArgs('sess-1', 'unknown');\n        expect(explicit.Reason).toBe('explicit');\n        expect(error.Reason).toBe('error');\n        expect(unknown.Reason).toBe('unknown');\n    });\n});\n"]}

package/dist/__tests__/conversation-naming.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=conversation-naming.test.d.ts.map

package/dist/__tests__/conversation-naming.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-naming.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/conversation-naming.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/conversation-naming.test.js

@@ -0,0 +1,110 @@
+/**
+ * Unit tests for the SHARED conversation auto-naming helper — the single
+ * implementation behind both the composer's first-message naming and the realtime
+ * session path (sessions that created their own conversation name it on call end).
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { AIEngineBase } from '@memberjunction/ai-engine-base';
+import { ConversationEngine } from '@memberjunction/core-entities';
+import { GenerateAndApplyConversationName, NAME_CONVERSATION_PROMPT } from '../lib/services/conversation-naming';
+const USER = { ID: 'user-1' };
+const PROVIDER = {};
+describe('GenerateAndApplyConversationName', () => {
+    let saveSpy;
+    beforeEach(() => {
+        vi.spyOn(AIEngineBase.Instance, 'Config').mockResolvedValue(undefined);
+        vi.spyOn(AIEngineBase.Instance, 'Prompts', 'get').mockReturnValue([
+            { ID: 'prompt-1', Name: NAME_CONVERSATION_PROMPT }
+        ]);
+        saveSpy = vi.spyOn(ConversationEngine.Instance, 'SaveConversation').mockResolvedValue(true);
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('runs the Name Conversation prompt, saves the parsed name + description, and returns them', async () => {
+        const runPrompt = vi.fn().mockResolvedValue({
+            success: true,
+            parsedResult: { name: 'Ottawa Weather Briefing', description: 'Weather and stocks' }
+        });
+        const result = await GenerateAndApplyConversationName({
+            ConversationId: 'conv-1',
+            MessageText: 'whats the weather in ottawa?',
+            Provider: PROVIDER,
+            CurrentUser: USER,
+            RunPrompt: runPrompt
+        });
+        expect(runPrompt).toHaveBeenCalledWith('prompt-1', 'whats the weather in ottawa?');
+        expect(saveSpy).toHaveBeenCalledWith('conv-1', { Name: 'Ottawa Weather Briefing', Description: 'Weather and stocks' }, USER);
+        expect(result).toEqual({ Name: 'Ottawa Weather Briefing', Description: 'Weather and stocks' });
+    });
+    it('parses fenced raw output when parsedResult is absent', async () => {
+        const result = await GenerateAndApplyConversationName({
+            ConversationId: 'conv-2',
+            MessageText: 'hello',
+            Provider: PROVIDER,
+            CurrentUser: USER,
+            RunPrompt: vi.fn().mockResolvedValue({
+                success: true,
+                output: '```json\n{"name":"Quick Hello"}\n```'
+            })
+        });
+        expect(result).toEqual({ Name: 'Quick Hello', Description: '' });
+        expect(saveSpy).toHaveBeenCalledWith('conv-2', { Name: 'Quick Hello', Description: '' }, USER);
+    });
+    it('returns null (no save) on timeout — the conversation keeps its default name', async () => {
+        vi.useFakeTimers();
+        const never = new Promise(() => undefined);
+        const pending = GenerateAndApplyConversationName({
+            ConversationId: 'conv-3',
+            MessageText: 'slow',
+            Provider: PROVIDER,
+            CurrentUser: USER,
+            TimeoutMs: 5000,
+            RunPrompt: vi.fn().mockReturnValue(never)
+        });
+        await vi.advanceTimersByTimeAsync(5001);
+        const result = await pending;
+        vi.useRealTimers();
+        expect(result).toBeNull();
+        expect(saveSpy).not.toHaveBeenCalled();
+    });
+    it('returns null when the Name Conversation prompt is not seeded', async () => {
+        vi.spyOn(AIEngineBase.Instance, 'Prompts', 'get').mockReturnValue([]);
+        const result = await GenerateAndApplyConversationName({
+            ConversationId: 'conv-4',
+            MessageText: 'x',
+            Provider: PROVIDER,
+            CurrentUser: USER,
+            RunPrompt: vi.fn()
+        });
+        expect(result).toBeNull();
+    });
+    it.each([
+        ['failed run', { success: false }],
+        ['empty result', null],
+        ['unparseable output', { success: true, output: 'not json at all {{{' }],
+        ['parsed without a name', { success: true, parsedResult: { description: 'only desc' } }]
+    ])('returns null (no save) for %s', async (_label, runResult) => {
+        const result = await GenerateAndApplyConversationName({
+            ConversationId: 'conv-5',
+            MessageText: 'x',
+            Provider: PROVIDER,
+            CurrentUser: USER,
+            RunPrompt: vi.fn().mockResolvedValue(runResult)
+        });
+        expect(result).toBeNull();
+        expect(saveSpy).not.toHaveBeenCalled();
+    });
+    it('returns null when the save fails (name generated but not applied)', async () => {
+        saveSpy.mockResolvedValue(false);
+        const result = await GenerateAndApplyConversationName({
+            ConversationId: 'conv-6',
+            MessageText: 'x',
+            Provider: PROVIDER,
+            CurrentUser: USER,
+            RunPrompt: vi.fn().mockResolvedValue({ success: true, parsedResult: { name: 'N' } })
+        });
+        expect(result).toBeNull();
+    });
+});
+//# sourceMappingURL=conversation-naming.test.js.map

package/dist/__tests__/conversation-naming.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-naming.test.js","sourceRoot":"","sources":["../../src/__tests__/conversation-naming.test.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Unit tests for the SHARED conversation auto-naming helper — the single\n * implementation behind both the composer's first-message naming and the realtime\n * session path (sessions that created their own conversation name it on call end).\n */\nimport { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';\nimport { UserInfo } from '@memberjunction/core';\nimport { GraphQLDataProvider } from '@memberjunction/graphql-dataprovider';\nimport { AIEngineBase } from '@memberjunction/ai-engine-base';\nimport { ConversationEngine } from '@memberjunction/core-entities';\nimport { GenerateAndApplyConversationName, NAME_CONVERSATION_PROMPT } from '../lib/services/conversation-naming';\n\nconst USER = { ID: 'user-1' } as unknown as UserInfo;\nconst PROVIDER = {} as unknown as GraphQLDataProvider;\n\ndescribe('GenerateAndApplyConversationName', () => {\n  let saveSpy: ReturnType<typeof vi.spyOn>;\n\n  beforeEach(() => {\n    vi.spyOn(AIEngineBase.Instance, 'Config').mockResolvedValue(undefined as never);\n    vi.spyOn(AIEngineBase.Instance, 'Prompts', 'get').mockReturnValue([\n      { ID: 'prompt-1', Name: NAME_CONVERSATION_PROMPT }\n    ] as never);\n    saveSpy = vi.spyOn(ConversationEngine.Instance, 'SaveConversation').mockResolvedValue(true as never);\n  });\n\n  afterEach(() => {\n    vi.restoreAllMocks();\n  });\n\n  it('runs the Name Conversation prompt, saves the parsed name + description, and returns them', async () => {\n    const runPrompt = vi.fn().mockResolvedValue({\n      success: true,\n      parsedResult: { name: 'Ottawa Weather Briefing', description: 'Weather and stocks' }\n    });\n\n    const result = await GenerateAndApplyConversationName({\n      ConversationId: 'conv-1',\n      MessageText: 'whats the weather in ottawa?',\n      Provider: PROVIDER,\n      CurrentUser: USER,\n      RunPrompt: runPrompt\n    });\n\n    expect(runPrompt).toHaveBeenCalledWith('prompt-1', 'whats the weather in ottawa?');\n    expect(saveSpy).toHaveBeenCalledWith(\n      'conv-1',\n      { Name: 'Ottawa Weather Briefing', Description: 'Weather and stocks' },\n      USER\n    );\n    expect(result).toEqual({ Name: 'Ottawa Weather Briefing', Description: 'Weather and stocks' });\n  });\n\n  it('parses fenced raw output when parsedResult is absent', async () => {\n    const result = await GenerateAndApplyConversationName({\n      ConversationId: 'conv-2',\n      MessageText: 'hello',\n      Provider: PROVIDER,\n      CurrentUser: USER,\n      RunPrompt: vi.fn().mockResolvedValue({\n        success: true,\n        output: '```json\\n{\"name\":\"Quick Hello\"}\\n```'\n      })\n    });\n\n    expect(result).toEqual({ Name: 'Quick Hello', Description: '' });\n    expect(saveSpy).toHaveBeenCalledWith('conv-2', { Name: 'Quick Hello', Description: '' }, USER);\n  });\n\n  it('returns null (no save) on timeout — the conversation keeps its default name', async () => {\n    vi.useFakeTimers();\n    const never = new Promise<never>(() => undefined);\n    const pending = GenerateAndApplyConversationName({\n      ConversationId: 'conv-3',\n      MessageText: 'slow',\n      Provider: PROVIDER,\n      CurrentUser: USER,\n      TimeoutMs: 5000,\n      RunPrompt: vi.fn().mockReturnValue(never)\n    });\n    await vi.advanceTimersByTimeAsync(5001);\n    const result = await pending;\n    vi.useRealTimers();\n\n    expect(result).toBeNull();\n    expect(saveSpy).not.toHaveBeenCalled();\n  });\n\n  it('returns null when the Name Conversation prompt is not seeded', async () => {\n    vi.spyOn(AIEngineBase.Instance, 'Prompts', 'get').mockReturnValue([] as never);\n    const result = await GenerateAndApplyConversationName({\n      ConversationId: 'conv-4',\n      MessageText: 'x',\n      Provider: PROVIDER,\n      CurrentUser: USER,\n      RunPrompt: vi.fn()\n    });\n    expect(result).toBeNull();\n  });\n\n  it.each([\n    ['failed run', { success: false }],\n    ['empty result', null],\n    ['unparseable output', { success: true, output: 'not json at all {{{' }],\n    ['parsed without a name', { success: true, parsedResult: { description: 'only desc' } }]\n  ])('returns null (no save) for %s', async (_label, runResult) => {\n    const result = await GenerateAndApplyConversationName({\n      ConversationId: 'conv-5',\n      MessageText: 'x',\n      Provider: PROVIDER,\n      CurrentUser: USER,\n      RunPrompt: vi.fn().mockResolvedValue(runResult)\n    });\n    expect(result).toBeNull();\n    expect(saveSpy).not.toHaveBeenCalled();\n  });\n\n  it('returns null when the save fails (name generated but not applied)', async () => {\n    saveSpy.mockResolvedValue(false as never);\n    const result = await GenerateAndApplyConversationName({\n      ConversationId: 'conv-6',\n      MessageText: 'x',\n      Provider: PROVIDER,\n      CurrentUser: USER,\n      RunPrompt: vi.fn().mockResolvedValue({ success: true, parsedResult: { name: 'N' } })\n    });\n    expect(result).toBeNull();\n  });\n});\n"]}

package/dist/__tests__/delegation-result-parser.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=delegation-result-parser.test.d.ts.map

package/dist/__tests__/delegation-result-parser.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation-result-parser.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/delegation-result-parser.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/delegation-result-parser.test.js

@@ -0,0 +1,107 @@
+import { describe, it, expect } from 'vitest';
+import { ParseDelegationResultJson } from '../lib/services/delegation-result-parser';
+describe('ParseDelegationResultJson', () => {
+    it('parses a successful result with a runId', () => {
+        const parsed = ParseDelegationResultJson(JSON.stringify({ success: true, output: 'all done', runId: 'run-123' }));
+        expect(parsed).toEqual({ Success: true, Output: 'all done', RunID: 'run-123' });
+    });
+    it('parses a successful result without a runId (RunID undefined)', () => {
+        const parsed = ParseDelegationResultJson(JSON.stringify({ success: true, output: 'all done' }));
+        expect(parsed.Success).toBe(true);
+        expect(parsed.Output).toBe('all done');
+        expect(parsed.RunID).toBeUndefined();
+    });
+    it('ignores an empty-string runId', () => {
+        const parsed = ParseDelegationResultJson(JSON.stringify({ success: true, output: 'x', runId: '' }));
+        expect(parsed.RunID).toBeUndefined();
+    });
+    it('parses the structured error shape ({success:false, error})', () => {
+        const parsed = ParseDelegationResultJson(JSON.stringify({ success: false, error: 'boom' }));
+        expect(parsed).toEqual({ Success: false, Output: 'boom', RunID: undefined });
+    });
+    it('still carries runId on a failed result that reported one', () => {
+        const parsed = ParseDelegationResultJson(JSON.stringify({ success: false, error: 'boom', runId: 'run-9' }));
+        expect(parsed.Success).toBe(false);
+        expect(parsed.RunID).toBe('run-9');
+    });
+    it('treats success as true unless explicitly false', () => {
+        const parsed = ParseDelegationResultJson(JSON.stringify({ output: 'no flag' }));
+        expect(parsed.Success).toBe(true);
+        expect(parsed.Output).toBe('no flag');
+    });
+    it('surfaces a non-JSON payload as the raw output (success assumed)', () => {
+        const parsed = ParseDelegationResultJson('plain text result');
+        expect(parsed).toEqual({ Success: true, Output: 'plain text result' });
+    });
+    it('prefers output over error when both are present', () => {
+        const parsed = ParseDelegationResultJson(JSON.stringify({ success: false, output: 'partial', error: 'late failure' }));
+        expect(parsed.Output).toBe('partial');
+    });
+    describe('artifacts', () => {
+        it('parses artifacts into PascalCase entries', () => {
+            const parsed = ParseDelegationResultJson(JSON.stringify({
+                success: true,
+                output: 'done',
+                runId: 'run-1',
+                artifacts: [{ artifactId: 'a-1', artifactVersionId: 'av-1', name: 'Weather Report' }]
+            }));
+            expect(parsed.Artifacts).toEqual([
+                { ArtifactID: 'a-1', ArtifactVersionID: 'av-1', Name: 'Weather Report' }
+            ]);
+        });
+        it('leaves Artifacts undefined when the field is absent', () => {
+            const parsed = ParseDelegationResultJson(JSON.stringify({ success: true, output: 'done' }));
+            expect(parsed.Artifacts).toBeUndefined();
+        });
+        it('leaves Artifacts undefined for an empty array', () => {
+            const parsed = ParseDelegationResultJson(JSON.stringify({ success: true, output: 'done', artifacts: [] }));
+            expect(parsed.Artifacts).toBeUndefined();
+        });
+        it('leaves Artifacts undefined when the field is not an array', () => {
+            const parsed = ParseDelegationResultJson(JSON.stringify({ success: true, output: 'done', artifacts: 'nope' }));
+            expect(parsed.Artifacts).toBeUndefined();
+        });
+        it('drops malformed entries (missing ids) and keeps valid ones', () => {
+            const parsed = ParseDelegationResultJson(JSON.stringify({
+                success: true,
+                output: 'done',
+                artifacts: [
+                    { artifactId: 'a-1' }, // no version id → dropped
+                    { artifactVersionId: 'av-2' }, // no artifact id → dropped
+                    { artifactId: 42, artifactVersionId: 'av-3' }, // non-string id → dropped
+                    { artifactId: 'a-4', artifactVersionId: 'av-4', name: 'Kept' }
+                ]
+            }));
+            expect(parsed.Artifacts).toEqual([{ ArtifactID: 'a-4', ArtifactVersionID: 'av-4', Name: 'Kept' }]);
+        });
+        it('falls back to "Artifact" for a missing or blank name', () => {
+            const parsed = ParseDelegationResultJson(JSON.stringify({
+                success: true,
+                output: 'done',
+                artifacts: [
+                    { artifactId: 'a-1', artifactVersionId: 'av-1' },
+                    { artifactId: 'a-2', artifactVersionId: 'av-2', name: '   ' }
+                ]
+            }));
+            expect(parsed.Artifacts?.map(a => a.Name)).toEqual(['Artifact', 'Artifact']);
+        });
+        it('trims artifact names', () => {
+            const parsed = ParseDelegationResultJson(JSON.stringify({
+                success: true,
+                output: 'done',
+                artifacts: [{ artifactId: 'a-1', artifactVersionId: 'av-1', name: '  Q3 Summary  ' }]
+            }));
+            expect(parsed.Artifacts?.[0].Name).toBe('Q3 Summary');
+        });
+        it('still carries artifacts on a failed result that reported them', () => {
+            const parsed = ParseDelegationResultJson(JSON.stringify({
+                success: false,
+                error: 'partial failure',
+                artifacts: [{ artifactId: 'a-1', artifactVersionId: 'av-1', name: 'Partial' }]
+            }));
+            expect(parsed.Success).toBe(false);
+            expect(parsed.Artifacts).toHaveLength(1);
+        });
+    });
+});
+//# sourceMappingURL=delegation-result-parser.test.js.map

package/dist/__tests__/delegation-result-parser.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation-result-parser.test.js","sourceRoot":"","sources":["../../src/__tests__/delegation-result-parser.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,yBAAyB,EAAE,MAAM,0CAA0C,CAAC;AAErF,QAAQ,CAAC,2BAA2B,EAAE,GAAG,EAAE;IACzC,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACjD,MAAM,MAAM,GAAG,yBAAyB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;QAClH,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAClF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8DAA8D,EAAE,GAAG,EAAE;QACtE,MAAM,MAAM,GAAG,yBAAyB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;QAChG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACvC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,aAAa,EAAE,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,MAAM,GAAG,yBAAyB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QACpG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,aAAa,EAAE,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4DAA4D,EAAE,GAAG,EAAE;QACpE,MAAM,MAAM,GAAG,yBAAyB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;QAC5F,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAC/E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0DAA0D,EAAE,GAAG,EAAE;QAClE,MAAM,MAAM,GAAG,yBAAyB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;QAC5G,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,MAAM,MAAM,GAAG,yBAAyB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;QAChF,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iEAAiE,EAAE,GAAG,EAAE;QACzE,MAAM,MAAM,GAAG,yBAAyB,CAAC,mBAAmB,CAAC,CAAC;QAC9D,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC,CAAC;IACzE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,MAAM,GAAG,yBAAyB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC;QACvH,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;QACzB,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;YAClD,MAAM,MAAM,GAAG,yBAAyB,CAAC,IAAI,CAAC,SAAS,CAAC;gBACtD,OAAO,EAAE,IAAI;gBACb,MAAM,EAAE,MAAM;gBACd,KAAK,EAAE,OAAO;gBACd,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC;aACtF,CAAC,CAAC,CAAC;YACJ,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC;gBAC/B,EAAE,UAAU,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,EAAE;aACzE,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;YAC7D,MAAM,MAAM,GAAG,yBAAyB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;YAC5F,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,aAAa,EAAE,CAAC;QAC3C,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;YACvD,MAAM,MAAM,GAAG,yBAAyB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;YAC3G,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,aAAa,EAAE,CAAC;QAC3C,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;YACnE,MAAM,MAAM,GAAG,yBAAyB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;YAC/G,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,aAAa,EAAE,CAAC;QAC3C,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,4DAA4D,EAAE,GAAG,EAAE;YACpE,MAAM,MAAM,GAAG,yBAAyB,CAAC,IAAI,CAAC,SAAS,CAAC;gBACtD,OAAO,EAAE,IAAI;gBACb,MAAM,EAAE,MAAM;gBACd,SAAS,EAAE;oBACT,EAAE,UAAU,EAAE,KAAK,EAAE,EAAuC,0BAA0B;oBACtF,EAAE,iBAAiB,EAAE,MAAM,EAAE,EAA+B,2BAA2B;oBACvF,EAAE,UAAU,EAAE,EAAE,EAAE,iBAAiB,EAAE,MAAM,EAAE,EAAe,0BAA0B;oBACtF,EAAE,UAAU,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE;iBAC/D;aACF,CAAC,CAAC,CAAC;YACJ,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;QACrG,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;YAC9D,MAAM,MAAM,GAAG,yBAAyB,CAAC,IAAI,CAAC,SAAS,CAAC;gBACtD,OAAO,EAAE,IAAI;gBACb,MAAM,EAAE,MAAM;gBACd,SAAS,EAAE;oBACT,EAAE,UAAU,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE;oBAChD,EAAE,UAAU,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE;iBAC9D;aACF,CAAC,CAAC,CAAC;YACJ,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;QAC/E,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,sBAAsB,EAAE,GAAG,EAAE;YAC9B,MAAM,MAAM,GAAG,yBAAyB,CAAC,IAAI,CAAC,SAAS,CAAC;gBACtD,OAAO,EAAE,IAAI;gBACb,MAAM,EAAE,MAAM;gBACd,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC;aACtF,CAAC,CAAC,CAAC;YACJ,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACxD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,+DAA+D,EAAE,GAAG,EAAE;YACvE,MAAM,MAAM,GAAG,yBAAyB,CAAC,IAAI,CAAC,SAAS,CAAC;gBACtD,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,iBAAiB;gBACxB,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;aAC/E,CAAC,CAAC,CAAC;YACJ,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAC3C,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC","sourcesContent":["import { describe, it, expect } from 'vitest';\nimport { ParseDelegationResultJson } from '../lib/services/delegation-result-parser';\n\ndescribe('ParseDelegationResultJson', () => {\n  it('parses a successful result with a runId', () => {\n    const parsed = ParseDelegationResultJson(JSON.stringify({ success: true, output: 'all done', runId: 'run-123' }));\n    expect(parsed).toEqual({ Success: true, Output: 'all done', RunID: 'run-123' });\n  });\n\n  it('parses a successful result without a runId (RunID undefined)', () => {\n    const parsed = ParseDelegationResultJson(JSON.stringify({ success: true, output: 'all done' }));\n    expect(parsed.Success).toBe(true);\n    expect(parsed.Output).toBe('all done');\n    expect(parsed.RunID).toBeUndefined();\n  });\n\n  it('ignores an empty-string runId', () => {\n    const parsed = ParseDelegationResultJson(JSON.stringify({ success: true, output: 'x', runId: '' }));\n    expect(parsed.RunID).toBeUndefined();\n  });\n\n  it('parses the structured error shape ({success:false, error})', () => {\n    const parsed = ParseDelegationResultJson(JSON.stringify({ success: false, error: 'boom' }));\n    expect(parsed).toEqual({ Success: false, Output: 'boom', RunID: undefined });\n  });\n\n  it('still carries runId on a failed result that reported one', () => {\n    const parsed = ParseDelegationResultJson(JSON.stringify({ success: false, error: 'boom', runId: 'run-9' }));\n    expect(parsed.Success).toBe(false);\n    expect(parsed.RunID).toBe('run-9');\n  });\n\n  it('treats success as true unless explicitly false', () => {\n    const parsed = ParseDelegationResultJson(JSON.stringify({ output: 'no flag' }));\n    expect(parsed.Success).toBe(true);\n    expect(parsed.Output).toBe('no flag');\n  });\n\n  it('surfaces a non-JSON payload as the raw output (success assumed)', () => {\n    const parsed = ParseDelegationResultJson('plain text result');\n    expect(parsed).toEqual({ Success: true, Output: 'plain text result' });\n  });\n\n  it('prefers output over error when both are present', () => {\n    const parsed = ParseDelegationResultJson(JSON.stringify({ success: false, output: 'partial', error: 'late failure' }));\n    expect(parsed.Output).toBe('partial');\n  });\n\n  describe('artifacts', () => {\n    it('parses artifacts into PascalCase entries', () => {\n      const parsed = ParseDelegationResultJson(JSON.stringify({\n        success: true,\n        output: 'done',\n        runId: 'run-1',\n        artifacts: [{ artifactId: 'a-1', artifactVersionId: 'av-1', name: 'Weather Report' }]\n      }));\n      expect(parsed.Artifacts).toEqual([\n        { ArtifactID: 'a-1', ArtifactVersionID: 'av-1', Name: 'Weather Report' }\n      ]);\n    });\n\n    it('leaves Artifacts undefined when the field is absent', () => {\n      const parsed = ParseDelegationResultJson(JSON.stringify({ success: true, output: 'done' }));\n      expect(parsed.Artifacts).toBeUndefined();\n    });\n\n    it('leaves Artifacts undefined for an empty array', () => {\n      const parsed = ParseDelegationResultJson(JSON.stringify({ success: true, output: 'done', artifacts: [] }));\n      expect(parsed.Artifacts).toBeUndefined();\n    });\n\n    it('leaves Artifacts undefined when the field is not an array', () => {\n      const parsed = ParseDelegationResultJson(JSON.stringify({ success: true, output: 'done', artifacts: 'nope' }));\n      expect(parsed.Artifacts).toBeUndefined();\n    });\n\n    it('drops malformed entries (missing ids) and keeps valid ones', () => {\n      const parsed = ParseDelegationResultJson(JSON.stringify({\n        success: true,\n        output: 'done',\n        artifacts: [\n          { artifactId: 'a-1' },                                      // no version id → dropped\n          { artifactVersionId: 'av-2' },                              // no artifact id → dropped\n          { artifactId: 42, artifactVersionId: 'av-3' },              // non-string id → dropped\n          { artifactId: 'a-4', artifactVersionId: 'av-4', name: 'Kept' }\n        ]\n      }));\n      expect(parsed.Artifacts).toEqual([{ ArtifactID: 'a-4', ArtifactVersionID: 'av-4', Name: 'Kept' }]);\n    });\n\n    it('falls back to \"Artifact\" for a missing or blank name', () => {\n      const parsed = ParseDelegationResultJson(JSON.stringify({\n        success: true,\n        output: 'done',\n        artifacts: [\n          { artifactId: 'a-1', artifactVersionId: 'av-1' },\n          { artifactId: 'a-2', artifactVersionId: 'av-2', name: '   ' }\n        ]\n      }));\n      expect(parsed.Artifacts?.map(a => a.Name)).toEqual(['Artifact', 'Artifact']);\n    });\n\n    it('trims artifact names', () => {\n      const parsed = ParseDelegationResultJson(JSON.stringify({\n        success: true,\n        output: 'done',\n        artifacts: [{ artifactId: 'a-1', artifactVersionId: 'av-1', name: '  Q3 Summary  ' }]\n      }));\n      expect(parsed.Artifacts?.[0].Name).toBe('Q3 Summary');\n    });\n\n    it('still carries artifacts on a failed result that reported them', () => {\n      const parsed = ParseDelegationResultJson(JSON.stringify({\n        success: false,\n        error: 'partial failure',\n        artifacts: [{ artifactId: 'a-1', artifactVersionId: 'av-1', name: 'Partial' }]\n      }));\n      expect(parsed.Success).toBe(false);\n      expect(parsed.Artifacts).toHaveLength(1);\n    });\n  });\n});\n"]}