@wildix/wilma-copilot-headless 0.1.1 → 0.1.2

package/dist/hooks/useCopilotSessionStream.js

@@ -0,0 +1,61 @@
+import { useEffect, useState } from 'react';
+import { getCopilotEventIndex, initialCopilotUiState, reduceCopilotEvent, } from '@wildix/wilma-copilot-core';
+import { GetSessionEventsCommand } from '@wildix/wilma-copilot-sessions-client';
+import { PAGE_LIMIT } from './shared';
+export function useCopilotSessionStream({ copilotClient, sessionId, live = true, streamEvents, onRelationship, onError, }) {
+    const [state, setState] = useState(initialCopilotUiState);
+    const [isLoading, setIsLoading] = useState(Boolean(sessionId));
+    const [error, setError] = useState();
+    useEffect(() => {
+        if (!sessionId) {
+            setState(initialCopilotUiState);
+            setIsLoading(false);
+            return;
+        }
+        const abort = new AbortController();
+        let nextIndex = 0;
+        setState(initialCopilotUiState);
+        setIsLoading(true);
+        setError(undefined);
+        const apply = (event) => {
+            nextIndex = Math.max(nextIndex, getCopilotEventIndex(event) + 1);
+            if (event.relationship)
+                onRelationship?.(event.relationship.sessionId);
+            setState((current) => reduceCopilotEvent(current, event));
+        };
+        const replay = async (startIndex = 0) => {
+            const output = await copilotClient.send(new GetSessionEventsCommand({ sessionId, startIndex, limit: PAGE_LIMIT }), {
+                abortSignal: abort.signal,
+            });
+            for (const event of output.events ?? []) {
+                apply(event);
+            }
+            if (output.nextStartIndex != null && !abort.signal.aborted) {
+                await replay(output.nextStartIndex);
+            }
+        };
+        void (async () => {
+            try {
+                await replay();
+                setIsLoading(false);
+                if (live && streamEvents && !abort.signal.aborted) {
+                    for await (const event of streamEvents(sessionId, nextIndex, abort.signal))
+                        apply(event);
+                }
+            }
+            catch (cause) {
+                if (!abort.signal.aborted) {
+                    setError(cause instanceof Error ? cause : new Error(String(cause)));
+                    onError?.(cause);
+                }
+            }
+            finally {
+                if (!abort.signal.aborted)
+                    setIsLoading(false);
+            }
+        })();
+        return () => abort.abort();
+    }, [copilotClient, live, onError, onRelationship, sessionId, streamEvents]);
+    return { state, isLoading, error };
+}
+//# sourceMappingURL=useCopilotSessionStream.js.map

package/dist/hooks/useCopilotSessionStream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCopilotSessionStream.js","sourceRoot":"","sources":["../../src/hooks/useCopilotSessionStream.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wildix/wilma-copilot-headless",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "React hooks for Wilma Copilot relationships, session streams and asks with injected clients.",
   "main": "./dist/index.js",
@@ -14,20 +14,20 @@
   "peerDependencies": {
     "@wildix/wilma-assistant-client": ">=0.0.9 <1",
     "@wildix/wilma-copilot-core": ">=0.1 <1",
-    "@wildix/wilma-copilot-sessions-client": ">=1.0.9 <2",
+    "@wildix/wilma-copilot-sessions-client": ">=1.0.15 <2",
     "react": "^19"
   },
   "devDependencies": {
     "@types/react": "^19.1.9",
     "@wildix/eslint-config-style-guide": "^1.2.2",
-    "@wildix/wilma-assistant-client": "0.0.9",
-    "@wildix/wilma-copilot-sessions-client": "1.0.10",
+    "@wildix/wilma-assistant-client": "0.0.13",
+    "@wildix/wilma-copilot-sessions-client": "1.0.15",
     "eslint": "^8",
     "react": "^19",
     "rimraf": "^5.0.5",
     "typescript": "^5.9.2",
     "vitest": "^4.0.4",
-    "@wildix/wilma-copilot-core": "0.1.1"
+    "@wildix/wilma-copilot-core": "0.1.2"
   },
   "exports": {
     ".": {

package/src/hooks/CopilotSessionStreamSlot.tsx

@@ -0,0 +1,28 @@
+import {createElement, Fragment, type ReactElement, type ReactNode} from 'react';
+
+import type {CopilotSessionStreamHandle} from '@wildix/wilma-copilot-core';
+
+import {useCopilotSessionStream, type UseCopilotSessionStreamOptions} from './useCopilotSessionStream';
+
+export interface CopilotSessionStreamSlotProps extends UseCopilotSessionStreamOptions {
+  children: (handle: CopilotSessionStreamHandle) => ReactNode;
+}
+
+/**
+ * Runs `useCopilotSessionStream` for one included session and hands the result to
+ * `children`.
+ *
+ * Hooks cannot be called in a loop, and an "included" session list is exactly that — an
+ * array whose length changes at runtime. Rendering one of these per included session id
+ * gives each its own stream and its own component identity, so React (not a manual map
+ * of subscriptions) is what starts and tears them down as sessions are included and
+ * removed.
+ */
+export function CopilotSessionStreamSlot({children, ...options}: CopilotSessionStreamSlotProps): ReactElement {
+  const handle = useCopilotSessionStream(options);
+
+  // `createElement` rather than JSX: this package ships `.ts` sources with no JSX
+  // transform configured, and a bare fragment is the only wrapper a "returns whatever
+  // `children` produced" component needs.
+  return createElement(Fragment, null, children(handle));
+}

package/src/hooks/index.ts

@@ -0,0 +1,9 @@
+export * from './CopilotSessionStreamSlot';
+export * from './shared';
+export * from './useCopilotActions';
+export * from './useCopilotAlerts';
+export * from './useCopilotAsk';
+export * from './useCopilotPanelView';
+export * from './useCopilotRecentSessions';
+export * from './useCopilotRelationship';
+export * from './useCopilotSessionStream';

package/src/hooks/shared.ts

@@ -0,0 +1,12 @@
+import type {CopilotContextLookup, WilmaCopilotSessionsClient} from '@wildix/wilma-copilot-sessions-client';
+
+export const PAGE_LIMIT = 1000;
+
+export interface CopilotDependencies {
+  copilotClient: WilmaCopilotSessionsClient;
+  onError?: (error: unknown) => void;
+}
+
+export function lookupKey(lookup: CopilotContextLookup | undefined): string {
+  return JSON.stringify(lookup ?? {});
+}

package/src/hooks/useCopilotActions.ts

@@ -0,0 +1,115 @@
+import {useCallback, useState} from 'react';
+
+import {asRecord, type CopilotSmartActionEntry, getSmartActionType} from '@wildix/wilma-copilot-core';
+import {ActCommand} from '@wildix/wilma-copilot-sessions-client';
+
+import {type CopilotDependencies} from './shared';
+
+export interface UseCopilotActionsOptions extends CopilotDependencies {
+  sessionId?: string;
+  /**
+   * Opens the URL of an `openUrl` smart action. Navigation belongs to the host, so the
+   * SDK reports the invocation and leaves the window to the app.
+   */
+  onOpenUrl?: (url: string, openInNewTab: boolean) => void;
+}
+
+/** Playbook progress the agent made by hand, as `Act` takes it. */
+export interface CopilotPlaybookProgress {
+  /** Steps the agent ticked. Append-only server-side, so re-sending an id is a no-op. */
+  stepIds?: readonly string[];
+  /** Marks the whole playbook complete. Honoured only while the view reports `canMarkComplete`. */
+  complete?: boolean;
+}
+
+export interface CopilotActionsHandle {
+  /** Keys of the smart actions this client already invoked, for the muted styling. */
+  usedKeys: ReadonlySet<string>;
+  /**
+   * Runs a suggestion against `sessionId`, or against `overrideSessionId` when it came
+   * from another session. A panel showing included sessions offers their actions too,
+   * and an action belongs to the session that suggested it, not to the one in focus.
+   */
+  runSmartAction: (entry: CopilotSmartActionEntry, overrideSessionId?: string) => Promise<void>;
+  searchKnowledge: (questionId: string, question?: string) => Promise<void>;
+  markPlaybookProgress: (assetId: string, progress: CopilotPlaybookProgress) => Promise<void>;
+}
+
+/**
+ * The three members of `CopilotClientAction`. All are accepted into the session mailbox, so the
+ * outcome arrives as an `action` event and — for a playbook tick or a knowledge answer — as the
+ * asset re-emitted under its own id, rather than from the call itself.
+ */
+export function useCopilotActions({
+  copilotClient,
+  sessionId,
+  onOpenUrl,
+  onError,
+}: UseCopilotActionsOptions): CopilotActionsHandle {
+  const [usedKeys, setUsedKeys] = useState<ReadonlySet<string>>(new Set());
+
+  const runSmartAction = useCallback(
+    async (entry: CopilotSmartActionEntry, overrideSessionId?: string) => {
+      const type = getSmartActionType(entry.action);
+      const target = overrideSessionId ?? sessionId;
+      if (!type || !target) return;
+      setUsedKeys((current) => new Set(current).add(entry.key));
+
+      if (type === 'openUrl') {
+        const {url, openInNewTab} = asRecord(entry.action.openUrl);
+        if (typeof url === 'string' && url) onOpenUrl?.(url, openInNewTab !== false);
+      }
+
+      try {
+        await copilotClient.send(
+          new ActCommand({
+            sessionId: target,
+            action: {smartAction: {assetId: entry.assetId, actionId: entry.itemId}},
+          }),
+        );
+      } catch (cause) {
+        onError?.(cause);
+      }
+    },
+    [copilotClient, onError, onOpenUrl, sessionId],
+  );
+
+  const searchKnowledge = useCallback(
+    async (questionId: string, question?: string) => {
+      if (!sessionId) return;
+
+      try {
+        await copilotClient.send(new ActCommand({sessionId, action: {knowledgeSearch: {questionId, question}}}));
+      } catch (cause) {
+        onError?.(cause);
+      }
+    },
+    [copilotClient, onError, sessionId],
+  );
+
+  const markPlaybookProgress = useCallback(
+    async (assetId: string, {stepIds, complete}: CopilotPlaybookProgress) => {
+      if (!sessionId) return;
+
+      try {
+        await copilotClient.send(
+          new ActCommand({
+            sessionId,
+            action: {
+              playbook: {
+                assetId,
+                ...(stepIds ? {stepIds: [...stepIds]} : {}),
+                ...(complete === undefined ? {} : {complete}),
+              },
+            },
+          }),
+        );
+      } catch (cause) {
+        onError?.(cause);
+      }
+    },
+    [copilotClient, onError, sessionId],
+  );
+
+  return {usedKeys, runSmartAction, searchKnowledge, markPlaybookProgress};
+}

package/src/hooks/useCopilotAlerts.ts

@@ -0,0 +1,50 @@
+import {useCallback, useEffect, useMemo, useRef, useState} from 'react';
+
+import {collectCopilotAlerts, type CopilotAlert, type CopilotUiState} from '@wildix/wilma-copilot-core';
+
+export interface UseCopilotAlertsOptions {
+  state: CopilotUiState;
+  /** True while recorded events are replaying. Those are history, and history never alerts. */
+  isLoading?: boolean;
+  /** Called once per batch of alerts that arrived live, oldest first. */
+  onAlert?: (alerts: CopilotAlert[]) => void;
+}
+
+export interface CopilotAlertsHandle {
+  /** Alerts seen since the last `clear`, oldest first. Drives an unread badge. */
+  unseen: CopilotAlert[];
+  clear: () => void;
+}
+
+/**
+ * Watches a session for the few things worth interrupting for (`collectCopilotAlerts`).
+ *
+ * The point of the hook is the baseline. A session is rehydrated by replaying its
+ * recorded events, so a panel opened next to a call that has been running for ten
+ * minutes sees every earlier detection arrive at once — and firing a notification for
+ * each would be both wrong and unbearable. Everything present when the stream settles
+ * is therefore marked seen without alerting, and only what arrives afterwards is news.
+ */
+export function useCopilotAlerts({state, isLoading = false, onAlert}: UseCopilotAlertsOptions): CopilotAlertsHandle {
+  const [unseen, setUnseen] = useState<CopilotAlert[]>([]);
+  const alerts = useMemo(() => collectCopilotAlerts(state), [state]);
+  const seenRef = useRef<Set<string>>(new Set());
+  const settledRef = useRef(false);
+
+  useEffect(() => {
+    const fresh = alerts.filter((alert) => !seenRef.current.has(alert.key));
+    for (const alert of fresh) seenRef.current.add(alert.key);
+
+    if (!settledRef.current) {
+      settledRef.current = !isLoading;
+
+      return;
+    }
+
+    if (fresh.length === 0) return;
+    setUnseen((current) => [...current, ...fresh]);
+    onAlert?.(fresh);
+  }, [alerts, isLoading, onAlert]);
+
+  return {unseen, clear: useCallback(() => setUnseen([]), [])};
+}

package/src/hooks/useCopilotAsk.ts

@@ -0,0 +1,46 @@
+import {useCallback, useState} from 'react';
+
+import {StartSessionCommand, type WilmaAssistantClient} from '@wildix/wilma-assistant-client';
+import {AskCommand} from '@wildix/wilma-copilot-sessions-client';
+
+import {type CopilotDependencies} from './shared';
+
+export interface UseCopilotAskOptions extends CopilotDependencies {
+  assistantClient: WilmaAssistantClient;
+  copilotSessionId?: string;
+}
+
+export function useCopilotAsk({assistantClient, copilotClient, copilotSessionId, onError}: UseCopilotAskOptions): {
+  ask: (question: string) => Promise<string | undefined>;
+  isAsking: boolean;
+} {
+  const [isAsking, setIsAsking] = useState(false);
+  const ask = useCallback(
+    async (question: string) => {
+      const message = question.trim();
+      if (!message || !copilotSessionId) return undefined;
+      setIsAsking(true);
+
+      try {
+        const started = await assistantClient.send(
+          new StartSessionCommand({
+            message,
+            visibility: 'hidden',
+            target: `copilot://sessions/${copilotSessionId}`,
+          }),
+        );
+        await copilotClient.send(new AskCommand({sessionId: copilotSessionId, wilmaSessionId: started.sessionId}));
+
+        return started.sessionId;
+      } catch (cause) {
+        onError?.(cause);
+        throw cause;
+      } finally {
+        setIsAsking(false);
+      }
+    },
+    [assistantClient, copilotClient, copilotSessionId, onError],
+  );
+
+  return {ask, isAsking};
+}

package/src/hooks/useCopilotPanelView.ts

@@ -0,0 +1,84 @@
+import {useCallback, useEffect, useMemo, useState} from 'react';
+
+export type CopilotPanelView =
+  /** The session the panel opened on: guidance, smart actions and the composer. */
+  | {kind: 'live'}
+  | {kind: 'history'}
+  /** An earlier session from the history, read-only. */
+  | {kind: 'session'; sessionId: string};
+
+export interface CopilotPanelViewHandle {
+  view: CopilotPanelView;
+  /** The session the current view is about, if it is about one. */
+  sessionId: string | undefined;
+  /** Whether transcript lines are interleaved in the live timeline. */
+  showTranscript: boolean;
+  toggleTranscript: () => void;
+  setShowTranscript: (value: boolean) => void;
+  openHistory: () => void;
+  openSession: (sessionId: string) => void;
+  /** Returns to the view that opened this one, and to the live view from the root. */
+  back: () => void;
+  goLive: () => void;
+  /**
+   * Past sessions folded into the live timeline instead of opened on their own, oldest
+   * first. History offers this as "include" beside "switch to", for pulling an earlier
+   * conversation's guidance into view without losing the current one.
+   */
+  includedSessionIds: string[];
+  isIncluded: (sessionId: string) => boolean;
+  includeSession: (sessionId: string) => void;
+  removeIncludedSession: (sessionId: string) => void;
+}
+
+const LIVE_VIEW: CopilotPanelView = {kind: 'live'};
+
+/**
+ * Which view the panel is showing, as a stack.
+ *
+ * A stack rather than a flag because the views nest: history opens a session, and every
+ * back step has to land where the reader came from rather than dropping them at the live
+ * session. Transcript lines are toggled inline on the timeline instead of opening a
+ * separate view.
+ *
+ * `initialView` opens the panel on that view with the live one beneath it, so a deep
+ * link into the history still has somewhere to go back to.
+ */
+export function useCopilotPanelView(initialView?: CopilotPanelView): CopilotPanelViewHandle {
+  const [stack, setStack] = useState<CopilotPanelView[]>(() =>
+    initialView && initialView.kind !== 'live' ? [LIVE_VIEW, initialView] : [LIVE_VIEW],
+  );
+  const [showTranscript, setShowTranscript] = useState(false);
+  const [includedSessionIds, setIncludedSessionIds] = useState<string[]>([]);
+  const view = stack[stack.length - 1] ?? LIVE_VIEW;
+  const sessionId = view.kind === 'session' ? view.sessionId : undefined;
+  const push = useCallback((next: CopilotPanelView) => setStack((current) => [...current, next]), []);
+
+  useEffect(() => {
+    setShowTranscript(false);
+  }, [sessionId, view.kind]);
+
+  const includedSet = useMemo(() => new Set(includedSessionIds), [includedSessionIds]);
+
+  return {
+    view,
+    sessionId,
+    showTranscript,
+    toggleTranscript: useCallback(() => setShowTranscript((current) => !current), []),
+    setShowTranscript,
+    openHistory: useCallback(() => push({kind: 'history'}), [push]),
+    openSession: useCallback((id: string) => push({kind: 'session', sessionId: id}), [push]),
+    back: useCallback(() => setStack((current) => (current.length > 1 ? current.slice(0, -1) : current)), []),
+    goLive: useCallback(() => setStack([LIVE_VIEW]), []),
+    includedSessionIds,
+    isIncluded: useCallback((id: string) => includedSet.has(id), [includedSet]),
+    includeSession: useCallback(
+      (id: string) => setIncludedSessionIds((current) => (current.includes(id) ? current : [...current, id])),
+      [],
+    ),
+    removeIncludedSession: useCallback(
+      (id: string) => setIncludedSessionIds((current) => current.filter((entry) => entry !== id)),
+      [],
+    ),
+  };
+}

package/src/hooks/useCopilotRecentSessions.ts

@@ -0,0 +1,45 @@
+import {useEffect, useState} from 'react';
+
+import {sortSessionsRecentFirst} from '@wildix/wilma-copilot-core';
+import {type CopilotSessionSummary, ListSessionsCommand} from '@wildix/wilma-copilot-sessions-client';
+
+import {type CopilotDependencies} from './shared';
+
+export function useCopilotRecentSessions(options: CopilotDependencies & {enabled?: boolean; limit?: number}): {
+  sessions: CopilotSessionSummary[];
+  isLoading: boolean;
+  error?: Error;
+  refresh: () => void;
+} {
+  const {copilotClient, enabled = true, limit = 20, onError} = options;
+  const [sessions, setSessions] = useState<CopilotSessionSummary[]>([]);
+  const [isLoading, setIsLoading] = useState(enabled);
+  const [error, setError] = useState<Error>();
+  const [nonce, setNonce] = useState(0);
+
+  useEffect(() => {
+    if (!enabled) return;
+    let cancelled = false;
+    setIsLoading(true);
+    void copilotClient
+      .send(new ListSessionsCommand({limit}))
+      .then((result) => {
+        if (!cancelled) setSessions(sortSessionsRecentFirst(result.sessions ?? []));
+      })
+      .catch((cause: unknown) => {
+        if (!cancelled) {
+          setError(cause instanceof Error ? cause : new Error(String(cause)));
+          onError?.(cause);
+        }
+      })
+      .finally(() => {
+        if (!cancelled) setIsLoading(false);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [copilotClient, enabled, limit, nonce, onError]);
+
+  return {sessions, isLoading, error, refresh: () => setNonce((value) => value + 1)};
+}

package/src/hooks/useCopilotRelationship.ts

@@ -0,0 +1,102 @@
+import {useCallback, useEffect, useRef, useState} from 'react';
+
+import {type CopilotRelationshipHandle, sortSessionsRecentFirst} from '@wildix/wilma-copilot-core';
+import {
+  type CopilotContextLookup,
+  type CopilotSessionSummary,
+  EnrichCommand,
+  ListRelationshipSessionsCommand,
+  OpenCommand,
+} from '@wildix/wilma-copilot-sessions-client';
+
+import {type CopilotDependencies, lookupKey} from './shared';
+
+export interface UseCopilotRelationshipOptions extends CopilotDependencies {
+  lookup?: CopilotContextLookup;
+  enabled?: boolean;
+  sessionsLimit?: number;
+}
+
+export function useCopilotRelationship({
+  copilotClient,
+  lookup,
+  enabled = true,
+  sessionsLimit = 50,
+  onError,
+}: UseCopilotRelationshipOptions): CopilotRelationshipHandle {
+  const [relationshipId, setRelationshipId] = useState<string>();
+  const [defaultSessionId, setDefaultSessionId] = useState<string>();
+  const [sessions, setSessions] = useState<CopilotSessionSummary[]>([]);
+  const [isLoading, setIsLoading] = useState(enabled);
+  const [error, setError] = useState<Error>();
+  const [attempt, setAttempt] = useState(0);
+  const relationshipRef = useRef<string | undefined>(undefined);
+  const openedLookupRef = useRef<string | undefined>(undefined);
+
+  relationshipRef.current = relationshipId;
+
+  const loadSessions = useCallback(
+    async (id: string, signal?: AbortSignal) => {
+      const result = await copilotClient.send(
+        new ListRelationshipSessionsCommand({relationshipId: id, limit: sessionsLimit}),
+        signal ? {abortSignal: signal} : undefined,
+      );
+      if (!signal?.aborted) setSessions(sortSessionsRecentFirst(result.sessions ?? []));
+    },
+    [copilotClient, sessionsLimit],
+  );
+
+  const refresh = useCallback(() => {
+    if (relationshipRef.current) void loadSessions(relationshipRef.current).catch(onError);
+  }, [loadSessions, onError]);
+
+  const retry = useCallback(() => {
+    setError(undefined);
+    setAttempt((value) => value + 1);
+  }, []);
+
+  useEffect(() => {
+    if (!enabled) return;
+    const abort = new AbortController();
+    setIsLoading(true);
+
+    void (async () => {
+      try {
+        const result = await copilotClient.send(new OpenCommand({lookup}), {abortSignal: abort.signal});
+        if (abort.signal.aborted) return;
+        openedLookupRef.current = lookupKey(lookup);
+        setRelationshipId(result.relationshipId);
+        setDefaultSessionId(result.session.id);
+        await loadSessions(result.relationshipId, abort.signal);
+        setError(undefined);
+      } catch (cause) {
+        if (!abort.signal.aborted) {
+          const next = cause instanceof Error ? cause : new Error(String(cause));
+          setError(next);
+          onError?.(cause);
+        }
+      } finally {
+        if (!abort.signal.aborted) setIsLoading(false);
+      }
+    })();
+
+    return () => abort.abort();
+  }, [attempt, copilotClient, enabled, loadSessions, onError]);
+
+  const key = lookupKey(lookup);
+  useEffect(() => {
+    const currentId = relationshipRef.current;
+    if (!enabled || !currentId || openedLookupRef.current === undefined || openedLookupRef.current === key) return;
+    openedLookupRef.current = key;
+
+    void copilotClient
+      .send(new EnrichCommand({relationshipId: currentId, lookup: lookup as CopilotContextLookup}))
+      .then((result) => {
+        setRelationshipId(result.relationshipId);
+        setSessions(sortSessionsRecentFirst(result.related ?? []));
+      })
+      .catch(onError);
+  }, [copilotClient, enabled, key, lookup, onError]);
+
+  return {relationshipId, sessions, defaultSessionId, isLoading, error, retry, refresh};
+}