@alia.onl/sdk 15.8.0 → 19.1.0

package/src/runtime/sharing.ts

@@ -0,0 +1,165 @@
+import { useMutation, useQuery } from '@tanstack/react-query';
+import { useMemo } from 'react';
+import { useAliaApi } from './api';
+import { useAliaRuntime } from './config';
+import { aliaQueryKeys } from './query-keys';
+import { API_ROUTES } from './routes';
+import type { Message } from './types';
+
+/** A conversation's read-only link (`POST /v1/conversations/:id/share`, `docs/agent-embedding.md` §6). */
+export interface AliaConversationShare {
+  conversationId: string;
+  /** What `GET /v1/shared/:token` reads it by; the host builds its own URL around it. */
+  token: string;
+  expiresAt: string;
+}
+
+/** How long a share link lives unless the caller says otherwise, in hours (the API takes 1–168). */
+export const DEFAULT_SHARE_TTL_HOURS = 24;
+
+/** Mint and revoke a conversation's share link, as the signed-in person. */
+export function useShareConversation() {
+  const api = useAliaApi();
+  const share = useMutation({
+    mutationFn: async ({
+      conversationId,
+      ttlHours = DEFAULT_SHARE_TTL_HOURS,
+    }: {
+      conversationId: string;
+      ttlHours?: number;
+    }): Promise<AliaConversationShare> => {
+      const hours = Math.min(168, Math.max(1, Math.round(ttlHours)));
+      const { data } = await api.post<{ token?: unknown; expiresAt?: unknown }>(
+        API_ROUTES.conversations.share(conversationId),
+        { ttlHours: hours },
+      );
+      if (typeof data?.token !== 'string' || typeof data.expiresAt !== 'string') {
+        throw new Error('The share link came back without a token.');
+      }
+      return { conversationId, token: data.token, expiresAt: data.expiresAt };
+    },
+  });
+  const revoke = useMutation({
+    mutationFn: async (conversationId: string): Promise<void> => {
+      await api.delete(API_ROUTES.conversations.share(conversationId));
+    },
+  });
+  return useMemo(
+    () => ({
+      /** Mint the link of `conversationId` (1–168 hours, default 24). */
+      share: (conversationId: string, ttlHours?: number) =>
+        share.mutateAsync({ conversationId, ttlHours }),
+      /** End the link: the token stops answering. */
+      revoke: (conversationId: string) => revoke.mutateAsync(conversationId),
+      isSharing: share.isPending,
+    }),
+    [share, revoke],
+  );
+}
+
+/** A message of a shared conversation: words and pictures, and who wrote them. Never a tool's output. */
+export interface AliaSharedMessage {
+  role: 'user' | 'assistant';
+  content: string | Array<{ type: string; [key: string]: unknown }>;
+  agent?: AliaSharedAgent;
+}
+
+export interface AliaSharedAgent {
+  id: string;
+  name: string;
+  handle?: string;
+  character?: unknown;
+}
+
+export interface AliaSharedConversationData {
+  title: string;
+  /** The conversation's lead, when it was an agent's. */
+  agent?: AliaSharedAgent;
+  messages: AliaSharedMessage[];
+  expiresAt: string;
+}
+
+/** The agent the server sent, kept only with an id and a name. */
+function readSharedAgent(value: unknown): AliaSharedAgent | undefined {
+  if (value === null || typeof value !== 'object') return undefined;
+  const { id, name, handle, character } = value as Record<string, unknown>;
+  if (typeof id !== 'string' || typeof name !== 'string') return undefined;
+  return {
+    id,
+    name,
+    ...(typeof handle === 'string' ? { handle } : {}),
+    ...(character === undefined || character === null ? {} : { character }),
+  };
+}
+
+/** The shared conversation as the contract names it; any message of another shape is left out. */
+export function readSharedConversation(value: unknown): AliaSharedConversationData | null {
+  if (value === null || typeof value !== 'object') return null;
+  const raw = value as Record<string, unknown>;
+  if (!Array.isArray(raw.messages) || typeof raw.expiresAt !== 'string') return null;
+  const messages = raw.messages.flatMap((message): AliaSharedMessage[] => {
+    if (message === null || typeof message !== 'object') return [];
+    const { role, content, agent } = message as Record<string, unknown>;
+    if (role !== 'user' && role !== 'assistant') return [];
+    if (typeof content !== 'string' && !Array.isArray(content)) return [];
+    const author = readSharedAgent(agent);
+    return [
+      {
+        role,
+        content: content as AliaSharedMessage['content'],
+        ...(author ? { agent: author } : {}),
+      },
+    ];
+  });
+  const lead = readSharedAgent(raw.agent);
+  return {
+    title: typeof raw.title === 'string' ? raw.title : '',
+    ...(lead ? { agent: lead } : {}),
+    messages,
+    expiresAt: raw.expiresAt,
+  };
+}
+
+/** The shared messages as the thread draws them: an agent's under its own identity. */
+export function sharedMessages(shared: AliaSharedConversationData): Message[] {
+  return shared.messages.map((message, index) => ({
+    id: `shared-${index}`,
+    role: message.role,
+    content: message.content,
+    ...(message.agent ? { agentInfo: { ...message.agent } } : {}),
+  }));
+}
+
+/** Thrown when a token answers nothing: revoked, expired or never minted. */
+export class SharedConversationGoneError extends Error {
+  constructor() {
+    super('This shared conversation is no longer available.');
+    this.name = 'SharedConversationGoneError';
+  }
+}
+
+/**
+ * A conversation somebody shared, read by its token. The route needs no session, so it is fetched
+ * plainly rather than through the signed-in Oxy client: a person who is not signed in can read it.
+ */
+export function useSharedConversation(token: string | undefined) {
+  const { apiUrl } = useAliaRuntime();
+  return useQuery({
+    queryKey: aliaQueryKeys.shared(token ?? ''),
+    queryFn: async (): Promise<AliaSharedConversationData> => {
+      const response = await fetch(new URL(API_ROUTES.shared(token ?? ''), apiUrl).toString(), {
+        headers: { Accept: 'application/json' },
+      });
+      if (response.status === 404 || response.status === 410) {
+        throw new SharedConversationGoneError();
+      }
+      if (!response.ok)
+        throw new Error(`Shared conversation failed with status ${response.status}`);
+      const shared = readSharedConversation(await response.json());
+      if (shared === null) throw new Error('The shared conversation had an unexpected shape.');
+      return shared;
+    },
+    enabled: token !== undefined && token !== '',
+    retry: (count, error) => !(error instanceof SharedConversationGoneError) && count < 2,
+  });
+}

package/src/runtime/sse-frame-reader.ts

@@ -0,0 +1,88 @@
+/**
+ * Reassembles an SSE byte stream into whole frames.
+ *
+ * ## Why this is a module rather than a few lines inside the read loop
+ *
+ * It used to be a few lines inside the read loop, and that is exactly how the
+ * bug happened. `buffer` was correctly declared outside the loop, so a line
+ * split across two `reader.read()` calls survived — but `currentEventType` was
+ * declared INSIDE it and reset to `''` on every chunk. A frame is
+ * `event: X\ndata: {…}\n\n` (`packages/api/src/lib/sse-emitter.ts:24`), and a
+ * chunk boundary falls wherever the network puts it, so any frame split between
+ * its `event:` and `data:` lines arrived with its type forgotten. It then fell
+ * through to the OpenAI-shaped branch, found no `choices[0]`, and was dropped
+ * without a trace.
+ *
+ * The events that carry the most bytes are the ones most likely to be split, so
+ * this was not rare and not uniform: `alia.title`, `alia.tool_result`,
+ * `alia.plan_preview`, `alia.host_action`, `alia.agent_turn` and the
+ * artifact events are precisely the large ones. A title that sometimes does not
+ * arrive, a canvas that sometimes does not open.
+ *
+ * Two pieces of state that must both outlive a chunk are easy to get half
+ * right when they are loose variables in a 1 000-line hook, and hard to get
+ * wrong when they are fields of one object whose whole job is to hold them.
+ * That is the reason for this file, and the reason the test can feed the same
+ * stream split at every byte offset — which no test of the hook could do.
+ */
+
+export interface SseFrame {
+  /** The `event:` name, or `''` for an unnamed (OpenAI-shaped) frame. */
+  readonly event: string;
+  /** The `data:` payload, trimmed. `[DONE]` is passed through as-is. */
+  readonly data: string;
+}
+
+export interface SseFrameReader {
+  /** Feed one decoded chunk; get back every frame it completed. */
+  push(chunk: string): SseFrame[];
+}
+
+export function createSseFrameReader(): SseFrameReader {
+  let buffer = '';
+  let currentEventType = '';
+
+  return {
+    push(chunk: string): SseFrame[] {
+      buffer += chunk;
+
+      const frames: SseFrame[] = [];
+      const lines = buffer.split('\n');
+      // The trailing element is whatever came after the last newline, which is
+      // an incomplete line unless the chunk happened to end on a boundary (in
+      // which case it is `''` and costs nothing to carry).
+      buffer = lines.pop() ?? '';
+
+      for (const rawLine of lines) {
+        // A stream that uses CRLF leaves the CR on the end of every line;
+        // `data: {…}\r` is not valid JSON.
+        const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
+
+        if (line.startsWith('event: ')) {
+          currentEventType = line.slice(7).trim();
+          continue;
+        }
+
+        // A blank line closes a frame. Resetting here is what stops a `data:`
+        // line in the NEXT frame inheriting this frame's event name.
+        if (line === '') {
+          currentEventType = '';
+          continue;
+        }
+
+        if (line.startsWith('data: ')) {
+          frames.push({ event: currentEventType, data: line.slice(6).trim() });
+          // One `data:` line is one frame for this protocol. The event name is
+          // consumed with it, so a second `data:` without its own `event:` is
+          // correctly unnamed rather than inheriting.
+          currentEventType = '';
+        }
+
+        // Comments (`: keep-alive`) and any field this client does not read
+        // are ignored, as the SSE specification requires.
+      }
+
+      return frames;
+    },
+  };
+}

package/src/runtime/stream-events.ts

@@ -0,0 +1,146 @@
+/**
+ * The stream frames of ADR 0020, read strictly (`docs/agent-embedding.md` §2, §4, §5).
+ *
+ * A frame is kept only when it has the version and every field the contract names, with the
+ * types it names; anything else is not that frame and is dropped whole, never half-applied. Pure:
+ * `use-conversation-stream.ts` decides what each one does to the thread.
+ */
+
+/** The consulted agent, as `alia.agent_start` names it. */
+export interface ConsultAgent {
+  id: string;
+  name: string;
+  handle?: string;
+  color?: string;
+  character?: unknown;
+}
+
+export type ConsultEvent =
+  | { type: 'start'; consultId: string; agent: ConsultAgent; task?: string }
+  | { type: 'delta'; consultId: string; content: string }
+  | {
+      type: 'tool';
+      consultId: string;
+      phase: 'call' | 'result';
+      toolCallId: string;
+      name: string;
+      input?: Record<string, unknown>;
+      output?: unknown;
+    }
+  | {
+      type: 'end';
+      consultId: string;
+      status: 'completed' | 'failed';
+      content?: string;
+      errorCode?: string;
+    };
+
+/** The consult frames' names, the retired `alia.agent` not among them. */
+export const CONSULT_EVENTS = [
+  'alia.agent_start',
+  'alia.agent_delta',
+  'alia.agent_tool',
+  'alia.agent_end',
+] as const;
+
+type Raw = Record<string, unknown>;
+
+const isObject = (value: unknown): value is Raw =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+const isText = (value: unknown): value is string => typeof value === 'string' && value !== '';
+const optionalText = (value: unknown): string | undefined =>
+  typeof value === 'string' && value !== '' ? value : undefined;
+
+/** A frame of this contract: version 1 and a consult it belongs to. */
+function versioned(data: unknown): (Raw & { consultId: string }) | null {
+  if (!isObject(data) || data.eventVersion !== 1 || !isText(data.consultId)) return null;
+  return data as Raw & { consultId: string };
+}
+
+/** The consult frame `event` carries, or `null` when it is not one or not well-formed. */
+export function parseConsultEvent(event: string, data: unknown): ConsultEvent | null {
+  const frame = versioned(data);
+  if (frame === null) return null;
+  const { consultId } = frame;
+  switch (event) {
+    case 'alia.agent_start': {
+      const agent = frame.agent;
+      if (!isObject(agent) || !isText(agent.id) || !isText(agent.name)) return null;
+      return {
+        type: 'start',
+        consultId,
+        agent: {
+          id: agent.id,
+          name: agent.name,
+          ...(optionalText(agent.handle) ? { handle: agent.handle as string } : {}),
+          ...(optionalText(agent.color) ? { color: agent.color as string } : {}),
+          ...(agent.character === undefined || agent.character === null
+            ? {}
+            : { character: agent.character }),
+        },
+        ...(optionalText(frame.task) ? { task: frame.task as string } : {}),
+      };
+    }
+    case 'alia.agent_delta':
+      return typeof frame.content === 'string'
+        ? { type: 'delta', consultId, content: frame.content }
+        : null;
+    case 'alia.agent_tool': {
+      const { phase, toolCallId, name, input } = frame;
+      if ((phase !== 'call' && phase !== 'result') || !isText(toolCallId) || !isText(name)) {
+        return null;
+      }
+      if (input !== undefined && !isObject(input)) return null;
+      return {
+        type: 'tool',
+        consultId,
+        phase,
+        toolCallId,
+        name,
+        ...(input === undefined ? {} : { input }),
+        ...(phase === 'result' ? { output: frame.output } : {}),
+      };
+    }
+    case 'alia.agent_end': {
+      const { status, content, error } = frame;
+      if (status !== 'completed' && status !== 'failed') return null;
+      if (content !== undefined && typeof content !== 'string') return null;
+      const errorCode = isObject(error) && isText(error.code) ? error.code : undefined;
+      return {
+        type: 'end',
+        consultId,
+        status,
+        ...(content === undefined ? {} : { content }),
+        ...(errorCode === undefined ? {} : { errorCode }),
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+/** A UI effect the model asked the embedding client for (`alia.host_action`). */
+export interface HostAction {
+  toolCallId: string;
+  app: string;
+  name: string;
+  input: Record<string, unknown>;
+}
+
+/** The host action an `alia.host_action` frame carries, or `null` when it is not well-formed. */
+export function parseHostAction(data: unknown): HostAction | null {
+  if (!isObject(data) || data.eventVersion !== 1) return null;
+  const { toolCallId, app, name, input } = data;
+  if (!isText(toolCallId) || !isText(app) || !isText(name)) return null;
+  if (input !== undefined && !isObject(input)) return null;
+  return { toolCallId, app, name, input: (input as Record<string, unknown> | undefined) ?? {} };
+}
+
+/** The error code that ends a turn an agent's feature gate refused (§5). */
+export const FEATURE_ENTITLEMENT_REQUIRED = 'feature_entitlement_required';
+
+/** The feature an error refused, when the error is a feature gate's refusal. */
+export function lockedFeatureOf(error: unknown): string | null {
+  if (!isObject(error) || error.code !== FEATURE_ENTITLEMENT_REQUIRED) return null;
+  return isText(error.feature) ? error.feature : null;
+}

package/src/runtime/stream-outcome.ts

@@ -0,0 +1,21 @@
+/** Evidence the client may use to decide whether a streamed turn answered. */
+export interface StreamOutputEvidence {
+  realOutputChars: number;
+  agentOutputChars: number;
+  durableArtifactCount: number;
+  /** Progress only. Deliberately not sufficient for success. */
+  toolInvocationCount: number;
+}
+
+/**
+ * A successful turn needs a user-facing answer or durable product output.
+ * Reasoning and ordinary tool cards are progress; accepting either on stream
+ * close leaves an empty assistant bubble that looks successfully completed.
+ */
+export function hasUsableStreamOutput(evidence: StreamOutputEvidence): boolean {
+  return (
+    evidence.realOutputChars > 0 ||
+    evidence.agentOutputChars > 0 ||
+    evidence.durableArtifactCount > 0
+  );
+}

package/src/runtime/thought-store.ts

@@ -0,0 +1,103 @@
+import { create } from 'zustand';
+import type { FailedTurn } from './turn-failure';
+import type { Message } from './types';
+
+/** The thought panel's tabs. The store owns them because it owns which one opens. */
+export type ThoughtTab = 'steps' | 'sources' | 'activity';
+
+/**
+ * Whether the conversation a selection belongs to has its messages yet. `loading` is the
+ * seeded-then-upgraded window in which a message can be on screen without its tool history;
+ * `failed` is a load that will not arrive. The panel shows each as itself instead of as "no steps".
+ */
+export type ThoughtScopeStatus = 'loading' | 'ready' | 'failed';
+
+/**
+ * The conversation a thought selection was made in, as the panel reads it.
+ *
+ * ## Why the messages travel WITH the selection
+ *
+ * The panel used to read one global array that the chat screen copied into only while the panel
+ * was open. So the first press on a tool row rendered against whatever the array held — the
+ * previous conversation, or nothing — and found no message by id: three empty tabs under five
+ * visible tool rows. And with the new-chat screen mounted under a conversation, TWO chat screens
+ * raced to write the array, and the empty one could win.
+ *
+ * Now a selection names its conversation and carries that conversation's messages, written in the
+ * same update as the message id, and a later sync is accepted only from the SAME conversation. A
+ * screen showing another conversation cannot blank what was opened from this one.
+ */
+export interface ThoughtScope {
+  /** `null` for a conversation that has not been created yet — the first turn of a new chat. */
+  conversationId: string | null;
+  messages: Message[];
+  status: ThoughtScopeStatus;
+  /** A turn is in flight in this conversation. */
+  isLoading: boolean;
+  /** The turn that got no answer in this conversation, or `null`. */
+  failedTurn: FailedTurn | null;
+}
+
+/** The turn the thought panel is about. */
+export interface ThoughtSelection {
+  messageId: string;
+  /**
+   * Which tab the panel opens on. A caller that already knows what the reader asked for — the
+   * Sources row under an answer — says so, instead of landing them on Steps to go hunting.
+   */
+  tab: ThoughtTab;
+  /** The conversation the message lives in. */
+  scope: ThoughtScope;
+}
+
+interface ThoughtState {
+  /** `null` while no turn is selected. */
+  selection: ThoughtSelection | null;
+  /**
+   * Select a turn, with the conversation it was pressed in. One update: there is no render in
+   * which the id is set and the messages are not.
+   */
+  open: (messageId: string, scope: ThoughtScope, tab?: ThoughtTab) => void;
+  setTab: (tab: ThoughtTab) => void;
+  /**
+   * The chat screen's newest view of a conversation. Taken only when it is the conversation the
+   * open selection belongs to; every other screen's write is dropped, which is what keeps a second
+   * mounted chat from blanking the panel.
+   */
+  sync: (scope: ThoughtScope) => void;
+  /** Clear the selection. */
+  close: () => void;
+}
+
+/**
+ * What the thought panel shows. Session state: the thread writes it, the panel (which the host
+ * places — a right panel, a sheet) reads it.
+ */
+export const useThoughtStore = create<ThoughtState>()((set, get) => ({
+  selection: null,
+
+  open: (messageId, scope, tab = 'steps') => set({ selection: { messageId, tab, scope } }),
+
+  setTab: (tab) => {
+    const { selection } = get();
+    if (selection !== null) set({ selection: { ...selection, tab } });
+  },
+
+  sync: (scope) => {
+    const { selection } = get();
+    if (selection === null || selection.scope.conversationId !== scope.conversationId) return;
+    const held = selection.scope;
+    if (
+      held.messages === scope.messages &&
+      held.status === scope.status &&
+      held.isLoading === scope.isLoading &&
+      held.failedTurn === scope.failedTurn
+    )
+      return;
+    set({ selection: { ...selection, scope } });
+  },
+
+  close: () => {
+    if (get().selection !== null) set({ selection: null });
+  },
+}));