@alia.onl/sdk 15.7.0 → 19.0.0

package/src/hooks/useAliaChat.ts

@@ -1,573 +0,0 @@
-import React, { useCallback, useEffect, useId, useRef, useState } from 'react';
-import { useOxy } from '@oxy.so/services/ui/client';
-import type { ChatMessage, ToolInvocation } from '../types';
-import { getTextFromContent, type MessageContent } from '../lib/content-utils';
-import { resolveModelId } from '../lib/catalogue';
-import { agentMessageId, delegatedAgent } from '../lib/delegation';
-import { streamAliaChat } from '../lib/chat-transport';
-import type { AliaChatStreamEvent } from '../lib/chat-stream';
-
-import { ALIA_API_URL } from '../lib/api-url';
-import { useAliaActivityStore } from '../lib/activity-store';
-import { turnActivityState } from '../lib/turn-state';
-
-export interface UseAliaChatOptions {
-  /**
-   * The agents the host knows, with their look: a delegation's thinking avatar is drawn from here
-   * until the agent's answer brings its own. Without it (or for an agent it lacks) the default look.
-   */
-  agents?: ReadonlyArray<{ id: string; character?: unknown }>;
-  /**
-   * Base URL the hook sends its requests to. Defaults to
-   * `EXPO_PUBLIC_ALIA_API_URL`, then `https://api.alia.onl`.
-   *
-   * The hook appends its own paths — `POST /v1/chat/completions` for a turn and
-   * `GET /catalogue` for the model check — so the value is a host, not a route.
-   *
-   * Point this at YOUR OWN backend to use the SDK from an origin Alia does not
-   * enumerate: Alia's product route, `POST /alia/chat`, answers CORS preflights
-   * only for Alia's own origins, while a server-to-server call carries no
-   * `Origin` header and is answered on its credential alone. Your backend
-   * receives the SDK's request, forwards the `Authorization` header it carries
-   * (the signed-in user's Oxy access token) to `/alia/chat`, and streams the
-   * SSE body back unchanged. The README's *consumer-backend path* section has
-   * the minimal relay; issue #244 records why this is the supported shape today.
-   */
-  apiUrl?: string;
-  /**
-   * The model to answer with, as `publisher/model` from `GET /catalogue`.
-   *
-   * Optional, and checked against the catalogue before a request carries it: an
-   * identifier the server no longer offers is not sent, so a retirement does not
-   * turn into a 400 inside a consumer's app. Omitted, the request carries no
-   * `model` and the server's default model answers.
-   */
-  model?: string;
-  /** App context injected as system message so Alia knows which app the user is in. */
-  clientContext?: string;
-  /**
-   * Optional assertion for callers that already hold the surrounding
-   * OxyProvider's active token. A different token is refused; the SDK never
-   * writes this value to an Authorization header itself.
-   */
-  accessToken?: string;
-}
-
-export interface SendOptions {
-  images?: ReadonlyArray<string>;
-}
-
-export interface UseAliaChatReturn {
-  messages: ChatMessage[];
-  setMessages: React.Dispatch<React.SetStateAction<ChatMessage[]>>;
-  /** `images` are `data:` or `https:` URLs sent with the turn as `image_url` parts. */
-  send: (text: string, options?: SendOptions) => void;
-  isStreaming: boolean;
-  stop: () => void;
-  clear: () => void;
-  /** The person accepted a proposed plan; the card collapses to "approved". */
-  approvePlan: (planId: string) => void;
-  /** The person cancelled a proposed plan: the card collapses to "cancelled" and the turn stops. */
-  rejectPlan: (planId: string) => void;
-  error: string | null;
-}
-
-interface ActiveRequest {
-  readonly key: symbol;
-  readonly controller: AbortController;
-}
-
-interface PendingUpdates {
-  readonly assistantId: string;
-  content: string;
-  reasoning: string;
-  tools: ToolInvocation[];
-  /** How many delegated agents have answered in this turn. */
-  agentAnswers: number;
-  timer: ReturnType<typeof setTimeout> | null;
-}
-
-function generateId(): string {
-  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
-    return `msg-${crypto.randomUUID()}`;
-  }
-  return `msg-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
-}
-
-function isAbort(error: unknown, signal: AbortSignal): boolean {
-  return signal.aborted || (error instanceof Error && error.name === 'AbortError');
-}
-
-function abortError(): Error {
-  const error = new Error('The Alia request was aborted.');
-  error.name = 'AbortError';
-  return error;
-}
-
-function waitWithAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
-  if (signal.aborted) return Promise.reject(abortError());
-  return new Promise<T>((resolve, reject) => {
-    const onAbort = (): void => reject(abortError());
-    signal.addEventListener('abort', onAbort, { once: true });
-    promise.then(
-      (value) => {
-        signal.removeEventListener('abort', onAbort);
-        resolve(value);
-      },
-      (error: unknown) => {
-        signal.removeEventListener('abort', onAbort);
-        reject(error);
-      },
-    );
-  });
-}
-
-/**
- * SSE streaming chat hook for Alia.
- *
- * The SDK deliberately stays on `/v1/chat/completions`: unlike the product
- * origin, this raw-source package is embedded by apps whose browser origins are
- * not all on Alia's narrow CORS allowlist. The endpoint is still Alia's product
- * handler during its recorded compatibility window.
- */
-export function useAliaChat(options: UseAliaChatOptions = {}): UseAliaChatReturn {
-  const { apiUrl = ALIA_API_URL, model, clientContext, accessToken: accessTokenProp } = options;
-  const directoryRef = useRef(new Map<string, { id: string; character?: unknown }>());
-  directoryRef.current = new Map((options.agents ?? []).map((agent) => [agent.id, agent]));
-  const requestUrl = '/v1/chat/completions';
-
-  const { oxyServices } = useOxy();
-  const [messages, setMessages] = useState<ChatMessage[]>([]);
-  const [isStreaming, setIsStreaming] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const messagesRef = useRef<ChatMessage[]>([]);
-  const activeRequestRef = useRef<ActiveRequest | null>(null);
-  const pendingRef = useRef<PendingUpdates | null>(null);
-  const mountedRef = useRef(true);
-
-  useEffect(() => {
-    messagesRef.current = messages;
-  }, [messages]);
-
-  // The turn's lifecycle, published for every "Ask Alia" button (`useAliaActivity`).
-  const activitySource = useId();
-  const activity = turnActivityState(messages, isStreaming);
-  useEffect(() => {
-    const { setLocal } = useAliaActivityStore.getState();
-    setLocal(activitySource, activity);
-    return () => setLocal(activitySource, 'idle');
-  }, [activitySource, activity]);
-
-  const updateAssistant = useCallback(
-    (assistantId: string, updater: (message: ChatMessage) => Partial<ChatMessage>) => {
-      if (!mountedRef.current) return;
-      setMessages((previous) => {
-        const index = previous.findIndex((message) => message.id === assistantId);
-        if (index < 0 || previous[index]?.role !== 'assistant') return previous;
-        const updated = [...previous];
-        const current = updated[index];
-        if (!current) return previous;
-        updated[index] = { ...current, ...updater(current) };
-        messagesRef.current = updated;
-        return updated;
-      });
-    },
-    [],
-  );
-
-  const removeEmptyAssistant = useCallback((assistantId: string) => {
-    if (!mountedRef.current) return;
-    setMessages((previous) => {
-      const target = previous.find((message) => message.id === assistantId);
-      if (
-        target?.role !== 'assistant' ||
-        getTextFromContent(target.content).trim().length > 0 ||
-        (target.thinking?.trim().length ?? 0) > 0 ||
-        (target.toolInvocations?.length ?? 0) > 0
-      ) {
-        return previous;
-      }
-      const updated = previous.filter((message) => message.id !== assistantId);
-      messagesRef.current = updated;
-      return updated;
-    });
-  }, []);
-
-  /**
-   * An agent's message of this turn, before Alia's own: opened empty by the call that sends for the
-   * agent, filled by its answer. Without an open one, an answer makes a message of its own.
-   */
-  const insertAgentMessage = useCallback(
-    (
-      assistantId: string,
-      agent: { id: string; name: string; character?: unknown },
-      content: string,
-    ) => {
-      if (!mountedRef.current) return;
-      const id = agentMessageId(assistantId, agent.id);
-      setMessages((previous) => {
-        const open = previous.find((message) => message.id === id);
-        let updated: ChatMessage[];
-        if (open && (content === '' || getTextFromContent(open.content) === '')) {
-          // Already open: an answer fills it; a second call to the same agent changes nothing.
-          if (content === '') return previous;
-          // The answer carries the look the server has now: it replaces the one the call guessed.
-          updated = previous.map((message) =>
-            message === open
-              ? {
-                  ...open,
-                  content,
-                  agentInfo: {
-                    id: agent.id,
-                    name: agent.name,
-                    character: agent.character ?? open.agentInfo?.character,
-                  },
-                }
-              : message,
-          );
-        } else {
-          const message: ChatMessage = {
-            id: open ? `${id}-${previous.length}` : id,
-            role: 'assistant',
-            content,
-            createdAt: Date.now(),
-            agentInfo: { id: agent.id, name: agent.name, character: agent.character },
-          };
-          const at = previous.findIndex((candidate) => candidate.id === assistantId);
-          updated = [...previous];
-          updated.splice(at < 0 ? updated.length : at, 0, message);
-        }
-        messagesRef.current = updated;
-        return updated;
-      });
-    },
-    [],
-  );
-
-  /** A turn that ends with an agent never answering leaves no empty message of the agent's. */
-  const removeUnansweredAgents = useCallback((assistantId: string) => {
-    if (!mountedRef.current) return;
-    setMessages((previous) => {
-      const updated = previous.filter(
-        (message) =>
-          !(
-            message.agentInfo !== undefined &&
-            message.id.startsWith(`${assistantId}-agent-`) &&
-            getTextFromContent(message.content).trim() === ''
-          ),
-      );
-      if (updated.length === previous.length) return previous;
-      messagesRef.current = updated;
-      return updated;
-    });
-  }, []);
-
-  const flushPendingUpdates = useCallback(
-    (pending: PendingUpdates) => {
-      const content = pending.content;
-      const reasoning = pending.reasoning;
-      const tools = [...pending.tools];
-      if (!content && !reasoning && tools.length === 0) return;
-
-      pending.content = '';
-      pending.reasoning = '';
-      updateAssistant(pending.assistantId, (last) => ({
-        ...(content ? { content: getTextFromContent(last.content) + content } : {}),
-        ...(reasoning ? { thinking: (last.thinking ?? '') + reasoning } : {}),
-        ...(tools.length > 0 ? { toolInvocations: tools } : {}),
-      }));
-    },
-    [updateAssistant],
-  );
-
-  const cancelPendingTimer = useCallback((pending: PendingUpdates) => {
-    if (pending.timer !== null) {
-      clearTimeout(pending.timer);
-      pending.timer = null;
-    }
-  }, []);
-
-  const scheduleFlush = useCallback(
-    (pending: PendingUpdates) => {
-      if (pending.timer !== null) return;
-      pending.timer = setTimeout(() => {
-        pending.timer = null;
-        flushPendingUpdates(pending);
-      }, 50);
-    },
-    [flushPendingUpdates],
-  );
-
-  const stop = useCallback(() => {
-    const active = activeRequestRef.current;
-    activeRequestRef.current = null;
-    active?.controller.abort();
-
-    const pending = pendingRef.current;
-    if (pending !== null) {
-      cancelPendingTimer(pending);
-      flushPendingUpdates(pending);
-      pendingRef.current = null;
-    }
-    if (mountedRef.current) setIsStreaming(false);
-  }, [cancelPendingTimer, flushPendingUpdates]);
-
-  useEffect(() => {
-    mountedRef.current = true;
-    return () => {
-      mountedRef.current = false;
-      activeRequestRef.current?.controller.abort();
-      activeRequestRef.current = null;
-      const pending = pendingRef.current;
-      if (pending !== null) cancelPendingTimer(pending);
-      pendingRef.current = null;
-    };
-  }, [cancelPendingTimer]);
-
-  const send = useCallback(
-    async (text: string, options?: SendOptions) => {
-      const trimmed = text.trim();
-      const images = options?.images ?? [];
-      if (!trimmed && images.length === 0) return;
-
-      const activeToken = oxyServices.session.accessToken;
-      if (accessTokenProp !== undefined && accessTokenProp !== activeToken) {
-        setError('The supplied token is not the active Oxy session.');
-        return;
-      }
-
-      // A new turn supersedes the previous one. Scope every later update to its
-      // assistant id and request key so an abort racing with the replacement
-      // cannot mutate the new placeholder or clear its streaming state.
-      const previousRequest = activeRequestRef.current;
-      activeRequestRef.current = null;
-      previousRequest?.controller.abort();
-      const previousPending = pendingRef.current;
-      if (previousPending !== null) {
-        cancelPendingTimer(previousPending);
-        flushPendingUpdates(previousPending);
-      }
-
-      const userContent: MessageContent =
-        images.length > 0
-          ? [
-              ...(trimmed ? [{ type: 'text', text: trimmed }] : []),
-              ...images.map((url) => ({ type: 'image_url', image_url: { url } })),
-            ]
-          : trimmed;
-      const userMessage: ChatMessage = {
-        id: generateId(),
-        role: 'user',
-        content: userContent,
-        createdAt: Date.now(),
-      };
-      const assistantMessage: ChatMessage = {
-        id: generateId(),
-        role: 'assistant',
-        content: '',
-        toolInvocations: [],
-        createdAt: Date.now(),
-      };
-      const history = messagesRef.current.filter(
-        (message) =>
-          message.role !== 'assistant' ||
-          getTextFromContent(message.content).trim().length > 0 ||
-          (message.thinking?.trim().length ?? 0) > 0 ||
-          (message.toolInvocations?.length ?? 0) > 0,
-      );
-      setMessages((previous) => {
-        const updated = [...previous, userMessage, assistantMessage];
-        messagesRef.current = updated;
-        return updated;
-      });
-      setError(null);
-      setIsStreaming(true);
-
-      const apiMessages: Array<{ role: string; content: MessageContent }> = [];
-      if (clientContext) apiMessages.push({ role: 'system', content: clientContext });
-      for (const message of history) {
-        if (message.role === 'system') continue;
-        apiMessages.push({ role: message.role, content: getTextFromContent(message.content) });
-        for (const tool of message.toolInvocations ?? []) {
-          if (tool.state === 'result' && tool.result !== undefined && tool.result !== null) {
-            apiMessages.push({
-              role: 'system',
-              content: `[Tool result from ${tool.toolName}: ${JSON.stringify(tool.result).slice(0, 500)}]`,
-            });
-          }
-        }
-      }
-      apiMessages.push({ role: 'user', content: userContent });
-
-      const pending: PendingUpdates = {
-        assistantId: assistantMessage.id,
-        content: '',
-        reasoning: '',
-        tools: [],
-        agentAnswers: 0,
-        timer: null,
-      };
-      pendingRef.current = pending;
-      const controller = new AbortController();
-      const request: ActiveRequest = { key: Symbol('alia-chat-request'), controller };
-      activeRequestRef.current = request;
-      const linked = oxyServices.createLinkedClient({ baseURL: apiUrl });
-
-      const applyEvent = (event: AliaChatStreamEvent): void => {
-        switch (event.kind) {
-          case 'content':
-            pending.content += event.content;
-            scheduleFlush(pending);
-            return;
-          case 'reasoning':
-            pending.reasoning += event.content;
-            scheduleFlush(pending);
-            return;
-          case 'tool_call': {
-            const invocation: ToolInvocation = {
-              toolCallId: event.toolCallId,
-              toolName: event.toolName,
-              state: 'call',
-              args: event.args,
-            };
-            const index = pending.tools.findIndex((tool) => tool.toolCallId === event.toolCallId);
-            if (index < 0) pending.tools = [...pending.tools, invocation];
-            else pending.tools[index] = invocation;
-            flushPendingUpdates(pending);
-            // A call to an agent opens the agent's message at once: empty, thinking, until it answers.
-            const agent = delegatedAgent(invocation);
-            // The call names the agent; its look is the host's directory's, until the answer brings the server's.
-            if (agent)
-              insertAgentMessage(
-                pending.assistantId,
-                { ...agent, character: directoryRef.current.get(agent.id)?.character },
-                '',
-              );
-            return;
-          }
-          case 'tool_result': {
-            const index = pending.tools.findIndex((tool) => tool.toolCallId === event.toolCallId);
-            const result: ToolInvocation = {
-              toolCallId: event.toolCallId,
-              toolName: event.toolName,
-              state: 'result',
-              result: event.output,
-              ...(index < 0 ? {} : { args: pending.tools[index]?.args }),
-            };
-            if (index < 0) pending.tools = [...pending.tools, result];
-            else pending.tools[index] = result;
-            flushPendingUpdates(pending);
-            return;
-          }
-          case 'research_progress':
-            updateAssistant(pending.assistantId, (last) => ({
-              researchProgress: {
-                ...event.progress,
-                subQuestions: event.progress.subQuestions ?? last.researchProgress?.subQuestions,
-              },
-            }));
-            return;
-          case 'plan_preview':
-            updateAssistant(pending.assistantId, () => ({
-              pendingPlan: {
-                planId: event.planId,
-                steps: event.steps,
-                approved: false,
-                rejected: false,
-              },
-            }));
-            return;
-          case 'agent_answer': {
-            // A delegated agent speaks as itself: its answer is its own message, placed before
-            // Alia's reply, as the Alia app places it. The call that sent for it already opened
-            // the message; an answer with no call opens it. Several agents are several messages.
-            pending.agentAnswers++;
-            insertAgentMessage(pending.assistantId, event.agent, event.content);
-            return;
-          }
-        }
-      };
-
-      try {
-        const effectiveModel = await waitWithAbort(
-          resolveModelId(apiUrl, model),
-          controller.signal,
-        );
-        await streamAliaChat(
-          linked.client,
-          { url: requestUrl, model: effectiveModel, messages: apiMessages },
-          controller.signal,
-          applyEvent,
-        );
-      } catch (caught: unknown) {
-        cancelPendingTimer(pending);
-        flushPendingUpdates(pending);
-        if (isAbort(caught, controller.signal)) {
-          removeEmptyAssistant(pending.assistantId);
-        } else if (mountedRef.current) {
-          const message = caught instanceof Error ? caught.message : 'Something went wrong.';
-          setError(message);
-          updateAssistant(pending.assistantId, (last) =>
-            getTextFromContent(last.content).trim().length === 0
-              ? { content: "I'm having trouble connecting right now. Please try again." }
-              : {},
-          );
-        }
-      } finally {
-        cancelPendingTimer(pending);
-        flushPendingUpdates(pending);
-        removeUnansweredAgents(pending.assistantId);
-        // Alia said nothing herself after handing the turn over: no empty reply under the answers.
-        if (pending.agentAnswers > 0) removeEmptyAssistant(pending.assistantId);
-        linked.dispose();
-        if (pendingRef.current === pending) pendingRef.current = null;
-        if (activeRequestRef.current?.key === request.key) {
-          activeRequestRef.current = null;
-          if (mountedRef.current) setIsStreaming(false);
-        }
-      }
-    },
-    [
-      accessTokenProp,
-      apiUrl,
-      cancelPendingTimer,
-      clientContext,
-      flushPendingUpdates,
-      model,
-      oxyServices,
-      requestUrl,
-      removeEmptyAssistant,
-      removeUnansweredAgents,
-      insertAgentMessage,
-      scheduleFlush,
-      updateAssistant,
-    ],
-  );
-
-  const clear = useCallback(() => {
-    stop();
-    messagesRef.current = [];
-    setMessages([]);
-    setError(null);
-  }, [stop]);
-
-  const decidePlan = useCallback((planId: string, decision: 'approved' | 'rejected') => {
-    setMessages((prev) =>
-      prev.map((message) =>
-        message.pendingPlan?.planId === planId
-          ? { ...message, pendingPlan: { ...message.pendingPlan, [decision]: true } }
-          : message,
-      ),
-    );
-  }, []);
-  const approvePlan = useCallback((planId: string) => decidePlan(planId, 'approved'), [decidePlan]);
-  const rejectPlan = useCallback(
-    (planId: string) => {
-      decidePlan(planId, 'rejected');
-      stop();
-    },
-    [decidePlan, stop],
-  );
-
-  return { messages, setMessages, send, isStreaming, stop, clear, approvePlan, rejectPlan, error };
-}

package/src/lib/api-url.ts

@@ -1,2 +0,0 @@
-/** Where Alia's API is: `EXPO_PUBLIC_ALIA_API_URL`, then `https://api.alia.onl`. */
-export const ALIA_API_URL = process.env.EXPO_PUBLIC_ALIA_API_URL ?? 'https://api.alia.onl';