@djangocfg/ui-tools 2.1.335 → 2.1.336

package/src/tools/Chat/core/reducer.ts

@@ -0,0 +1,335 @@
+/**
+ * Pure chat state machine. Zero React. Zero I/O.
+ *
+ * Invariants:
+ *  - At most one message has `isStreaming === true` at any time. It is always
+ *    the last message in the array.
+ *  - Messages are immutable; updates produce new objects.
+ *  - `version` bumps on edit so memo keys invalidate.
+ */
+
+import type { ChatAttachment, ChatMessage, ChatSource, ChatToolCall } from '../types';
+
+export interface ChatState {
+  sessionId: string | null;
+  messages: ChatMessage[];
+  /** Initial history load in flight. */
+  isLoading: boolean;
+  /** Assistant is generating a reply. */
+  isStreaming: boolean;
+  /** Older history page in flight. */
+  isLoadingMore: boolean;
+  hasMore: boolean;
+  oldestCursor: string | null;
+  error: string | null;
+}
+
+export const initialState: ChatState = {
+  sessionId: null,
+  messages: [],
+  isLoading: false,
+  isStreaming: false,
+  isLoadingMore: false,
+  hasMore: true,
+  oldestCursor: null,
+  error: null,
+};
+
+export type ChatAction =
+  | {
+      type: 'SESSION_SET';
+      sessionId: string;
+      messages?: ChatMessage[];
+      hasMore?: boolean;
+      cursor?: string | null;
+    }
+  | { type: 'HISTORY_LOAD_START' }
+  | {
+      type: 'HISTORY_LOAD_DONE';
+      messages: ChatMessage[];
+      hasMore: boolean;
+      cursor: string | null;
+    }
+  | { type: 'HISTORY_MORE_START' }
+  | {
+      type: 'HISTORY_MORE_DONE';
+      messages: ChatMessage[];
+      hasMore: boolean;
+      cursor: string | null;
+    }
+  | { type: 'MESSAGE_USER_ADD'; message: ChatMessage }
+  | { type: 'STREAM_START'; id: string; createdAt?: number }
+  | { type: 'STREAM_CHUNK'; delta: string }
+  | { type: 'STREAM_TOOL_ACTIVITY'; tool: string }
+  | { type: 'TOOL_CALL_START'; messageId: string; toolCall: ChatToolCall }
+  | { type: 'TOOL_CALL_DELTA'; messageId: string; toolId: string; delta: string }
+  | {
+      type: 'TOOL_CALL_END';
+      messageId: string;
+      toolId: string;
+      output: unknown;
+      status: 'success' | 'error';
+    }
+  | {
+      type: 'STREAM_DONE';
+      id: string;
+      tokensIn?: number;
+      tokensOut?: number;
+      sources?: ChatSource[];
+    }
+  | { type: 'STREAM_CANCELLED'; id: string; partialText: string; label?: string }
+  | { type: 'STREAM_ERROR'; id?: string; message: string }
+  | { type: 'MESSAGE_EDIT'; id: string; content: string }
+  | { type: 'MESSAGE_DELETE'; id: string }
+  | { type: 'MESSAGES_CLEAR' }
+  | { type: 'ERROR_SET'; error: string | null }
+  | {
+      type: 'ATTACHMENT_PROGRESS';
+      messageId: string;
+      attachmentId: string;
+      progress?: number;
+      status?: ChatAttachment['status'];
+    };
+
+function updateLastStreaming(
+  messages: ChatMessage[],
+  patch: (m: ChatMessage) => ChatMessage,
+): ChatMessage[] {
+  const idx = findLastStreamingIndex(messages);
+  if (idx === -1) return messages;
+  const next = messages.slice();
+  next[idx] = patch(messages[idx]);
+  return next;
+}
+
+function findLastStreamingIndex(messages: ChatMessage[]): number {
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    if (messages[i].isStreaming) return i;
+  }
+  return -1;
+}
+
+function patchMessageById(
+  messages: ChatMessage[],
+  id: string,
+  patch: (m: ChatMessage) => ChatMessage,
+): ChatMessage[] {
+  const idx = messages.findIndex((m) => m.id === id);
+  if (idx === -1) return messages;
+  const next = messages.slice();
+  next[idx] = patch(messages[idx]);
+  return next;
+}
+
+export function reducer(state: ChatState, action: ChatAction): ChatState {
+  switch (action.type) {
+    case 'SESSION_SET':
+      return {
+        ...state,
+        sessionId: action.sessionId,
+        messages: action.messages ?? state.messages,
+        hasMore: action.hasMore ?? state.hasMore,
+        oldestCursor: action.cursor ?? state.oldestCursor,
+        error: null,
+      };
+
+    case 'HISTORY_LOAD_START':
+      return { ...state, isLoading: true, error: null };
+
+    case 'HISTORY_LOAD_DONE':
+      return {
+        ...state,
+        isLoading: false,
+        messages: action.messages,
+        hasMore: action.hasMore,
+        oldestCursor: action.cursor,
+      };
+
+    case 'HISTORY_MORE_START':
+      return { ...state, isLoadingMore: true };
+
+    case 'HISTORY_MORE_DONE':
+      return {
+        ...state,
+        isLoadingMore: false,
+        // Older messages prepend to the top.
+        messages: [...action.messages, ...state.messages],
+        hasMore: action.hasMore,
+        oldestCursor: action.cursor,
+      };
+
+    case 'MESSAGE_USER_ADD':
+      return {
+        ...state,
+        messages: [...state.messages, action.message],
+        error: null,
+      };
+
+    case 'STREAM_START': {
+      if (state.isStreaming) {
+        if (typeof console !== 'undefined') {
+          // Soft guard — UI should disable the composer; this catches bugs.
+          // eslint-disable-next-line no-console
+          console.warn('[chat] STREAM_START while already streaming, ignoring');
+        }
+        return state;
+      }
+      const placeholder: ChatMessage = {
+        id: action.id,
+        role: 'assistant',
+        content: '',
+        createdAt: action.createdAt ?? Date.now(),
+        isStreaming: true,
+      };
+      return {
+        ...state,
+        isStreaming: true,
+        messages: [...state.messages, placeholder],
+      };
+    }
+
+    case 'STREAM_CHUNK': {
+      const messages = updateLastStreaming(state.messages, (m) => ({
+        ...m,
+        content: m.content + action.delta,
+      }));
+      return { ...state, messages };
+    }
+
+    case 'STREAM_TOOL_ACTIVITY': {
+      const messages = updateLastStreaming(state.messages, (m) => ({
+        ...m,
+        toolActivity: action.tool,
+      }));
+      return { ...state, messages };
+    }
+
+    case 'TOOL_CALL_START': {
+      const messages = patchMessageById(state.messages, action.messageId, (m) => ({
+        ...m,
+        toolCalls: [...(m.toolCalls ?? []), action.toolCall],
+      }));
+      return { ...state, messages };
+    }
+
+    case 'TOOL_CALL_DELTA': {
+      const messages = patchMessageById(state.messages, action.messageId, (m) => {
+        if (!m.toolCalls) return m;
+        return {
+          ...m,
+          toolCalls: m.toolCalls.map((tc) =>
+            tc.id === action.toolId
+              ? { ...tc, streamingText: (tc.streamingText ?? '') + action.delta }
+              : tc,
+          ),
+        };
+      });
+      return { ...state, messages };
+    }
+
+    case 'TOOL_CALL_END': {
+      const messages = patchMessageById(state.messages, action.messageId, (m) => {
+        if (!m.toolCalls) return m;
+        return {
+          ...m,
+          toolCalls: m.toolCalls.map((tc) =>
+            tc.id === action.toolId
+              ? {
+                  ...tc,
+                  output: action.output,
+                  status: action.status,
+                  streamingText: undefined,
+                  endedAt: Date.now(),
+                }
+              : tc,
+          ),
+        };
+      });
+      return { ...state, messages };
+    }
+
+    case 'STREAM_DONE': {
+      const messages = patchMessageById(state.messages, action.id, (m) => ({
+        ...m,
+        isStreaming: false,
+        tokensIn: action.tokensIn ?? m.tokensIn,
+        tokensOut: action.tokensOut ?? m.tokensOut,
+        sources: action.sources ?? m.sources,
+      }));
+      return { ...state, isStreaming: false, messages };
+    }
+
+    case 'STREAM_CANCELLED': {
+      const suffix = action.label ?? '[cancelled]';
+      const messages = patchMessageById(state.messages, action.id, (m) => ({
+        ...m,
+        isStreaming: false,
+        content: action.partialText + (action.partialText ? `\n\n_${suffix}_` : `_${suffix}_`),
+      }));
+      return { ...state, isStreaming: false, messages };
+    }
+
+    case 'STREAM_ERROR': {
+      const messages = action.id
+        ? patchMessageById(state.messages, action.id, (m) => ({
+            ...m,
+            isStreaming: false,
+            isError: true,
+          }))
+        : state.messages;
+      return { ...state, isStreaming: false, error: action.message, messages };
+    }
+
+    case 'MESSAGE_EDIT': {
+      const messages = patchMessageById(state.messages, action.id, (m) => ({
+        ...m,
+        content: action.content,
+        version: (m.version ?? 0) + 1,
+      }));
+      return { ...state, messages };
+    }
+
+    case 'MESSAGE_DELETE':
+      return {
+        ...state,
+        messages: state.messages.filter((m) => m.id !== action.id),
+      };
+
+    case 'MESSAGES_CLEAR':
+      return {
+        ...state,
+        messages: [],
+        isStreaming: false,
+        error: null,
+      };
+
+    case 'ERROR_SET':
+      return { ...state, error: action.error };
+
+    case 'ATTACHMENT_PROGRESS': {
+      const messages = patchMessageById(state.messages, action.messageId, (m) => {
+        if (!m.attachments) return m;
+        return {
+          ...m,
+          attachments: m.attachments.map((a) =>
+            a.id === action.attachmentId
+              ? {
+                  ...a,
+                  progress: action.progress ?? a.progress,
+                  status: action.status ?? a.status,
+                }
+              : a,
+          ),
+        };
+      });
+      return { ...state, messages };
+    }
+
+    default: {
+      // Exhaustiveness check.
+      const _exhaustive: never = action;
+      void _exhaustive;
+      return state;
+    }
+  }
+}

package/src/tools/Chat/core/transport/http.ts

@@ -0,0 +1,167 @@
+/**
+ * HTTP + SSE transport. Default implementation for web hosts.
+ *
+ * Backend contract (see @dev/@refactoring7-chat/06-integration.md):
+ *   POST   /sessions                     → SessionInfo (JSON)
+ *   GET    /sessions/:id/history?cursor= → HistoryPage (JSON)
+ *   POST   /sessions/:id/messages        → SSE stream of ChatStreamEvent
+ *   POST   /sessions/:id/messages/buffered → ChatMessage (JSON, fallback)
+ *   DELETE /sessions/:id                 → 204
+ */
+
+import type {
+  ChatMessage,
+  ChatStreamEvent,
+  ChatTransport,
+  CreateSessionOptions,
+  HistoryPage,
+  SendOptions,
+  SessionInfo,
+  StreamOptions,
+} from '../../types';
+import { TransportError } from './types';
+import { parseSSE } from './sse';
+
+export interface HttpTransportConfig {
+  /** Base URL without trailing slash, e.g. '/api/chat' or 'https://api.example.com/v1/chat'. */
+  baseUrl: string;
+  /** Optional slug appended/forwarded as project identifier. */
+  slug?: string;
+  /** Returns headers applied to every request — e.g. Authorization. */
+  getAuthHeader?: () => Record<string, string> | Promise<Record<string, string>>;
+  /** Default fetch timeout (per non-streaming request). */
+  timeoutMs?: number;
+  /** Override fetch implementation (useful for tests or custom retry layers). */
+  fetchImpl?: typeof fetch;
+}
+
+const DEFAULT_TIMEOUT = 20_000;
+
+async function jsonOrThrow<T>(res: Response, label: string): Promise<T> {
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new TransportError(
+      `${label} failed (${res.status}): ${text || res.statusText}`,
+      mapStatusToCode(res.status),
+    );
+  }
+  try {
+    return (await res.json()) as T;
+  } catch {
+    throw new TransportError(`${label} returned invalid JSON`, 'invalid_response');
+  }
+}
+
+function mapStatusToCode(status: number): string {
+  if (status === 401) return 'unauthorized';
+  if (status === 403) return 'forbidden';
+  if (status === 404) return 'not_found';
+  if (status === 429) return 'rate_limited';
+  if (status >= 500) return 'server_error';
+  return 'http_error';
+}
+
+function withTimeout(signal: AbortSignal | undefined, timeoutMs: number): AbortSignal {
+  const ctrl = new AbortController();
+  const onAbort = () => ctrl.abort();
+  signal?.addEventListener('abort', onAbort, { once: true });
+  setTimeout(() => ctrl.abort(), timeoutMs);
+  return ctrl.signal;
+}
+
+export function createHttpTransport(config: HttpTransportConfig): ChatTransport {
+  const fetchImpl = config.fetchImpl ?? fetch;
+  const timeout = config.timeoutMs ?? DEFAULT_TIMEOUT;
+  const base = config.baseUrl.replace(/\/$/, '');
+
+  async function buildHeaders(extra?: Record<string, string>): Promise<Record<string, string>> {
+    const auth = (await config.getAuthHeader?.()) ?? {};
+    return {
+      'Content-Type': 'application/json',
+      ...auth,
+      ...(extra ?? {}),
+    };
+  }
+
+  return {
+    async createSession(opts?: CreateSessionOptions): Promise<SessionInfo> {
+      const res = await fetchImpl(`${base}/sessions`, {
+        method: 'POST',
+        headers: await buildHeaders(),
+        body: JSON.stringify({ slug: config.slug, metadata: opts?.metadata ?? {} }),
+        signal: withTimeout(undefined, timeout),
+      });
+      return jsonOrThrow<SessionInfo>(res, 'createSession');
+    },
+
+    async loadHistory(sessionId, cursor, limit): Promise<HistoryPage> {
+      const params = new URLSearchParams();
+      if (cursor) params.set('cursor', cursor);
+      if (limit) params.set('limit', String(limit));
+      const url = `${base}/sessions/${encodeURIComponent(sessionId)}/history${
+        params.toString() ? `?${params.toString()}` : ''
+      }`;
+      const res = await fetchImpl(url, {
+        method: 'GET',
+        headers: await buildHeaders(),
+        signal: withTimeout(undefined, timeout),
+      });
+      return jsonOrThrow<HistoryPage>(res, 'loadHistory');
+    },
+
+    async *stream(
+      sessionId: string,
+      content: string,
+      options: StreamOptions,
+    ): AsyncGenerator<ChatStreamEvent, void, void> {
+      const url = `${base}/sessions/${encodeURIComponent(sessionId)}/messages`;
+      const res = await fetchImpl(url, {
+        method: 'POST',
+        headers: await buildHeaders({ Accept: 'text/event-stream' }),
+        body: JSON.stringify({
+          content,
+          attachments: options.attachments ?? [],
+          metadata: options.metadata ?? {},
+        }),
+        signal: options.signal,
+      });
+
+      if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new TransportError(
+          `stream failed (${res.status}): ${text || res.statusText}`,
+          mapStatusToCode(res.status),
+        );
+      }
+
+      yield* parseSSE(res, { signal: options.signal });
+    },
+
+    async send(sessionId, content, options?: SendOptions): Promise<ChatMessage> {
+      const url = `${base}/sessions/${encodeURIComponent(sessionId)}/messages/buffered`;
+      const res = await fetchImpl(url, {
+        method: 'POST',
+        headers: await buildHeaders(),
+        body: JSON.stringify({
+          content,
+          attachments: options?.attachments ?? [],
+          metadata: options?.metadata ?? {},
+        }),
+        signal: options?.signal ?? withTimeout(undefined, timeout),
+      });
+      return jsonOrThrow<ChatMessage>(res, 'send');
+    },
+
+    async closeSession(sessionId: string): Promise<void> {
+      const url = `${base}/sessions/${encodeURIComponent(sessionId)}`;
+      const res = await fetchImpl(url, {
+        method: 'DELETE',
+        headers: await buildHeaders(),
+        signal: withTimeout(undefined, timeout),
+      });
+      if (!res.ok && res.status !== 404) {
+        throw new TransportError(`closeSession failed (${res.status})`, mapStatusToCode(res.status));
+      }
+    },
+  };
+}

package/src/tools/Chat/core/transport/index.ts

@@ -0,0 +1,13 @@
+export { createHttpTransport, type HttpTransportConfig } from './http';
+export { createMockTransport, type MockTransportOptions } from './mock';
+export { parseSSE, type ParseSSEOptions } from './sse';
+export { TransportError } from './types';
+export type {
+  ChatTransport,
+  ChatStreamEvent,
+  CreateSessionOptions,
+  SessionInfo,
+  HistoryPage,
+  StreamOptions,
+  SendOptions,
+} from './types';

package/src/tools/Chat/core/transport/mock.ts

@@ -0,0 +1,134 @@
+/**
+ * In-memory chat transport for stories and tests. Replays scripted replies.
+ */
+
+import type {
+  ChatMessage,
+  ChatStreamEvent,
+  ChatTransport,
+  CreateSessionOptions,
+  HistoryPage,
+  SendOptions,
+  SessionInfo,
+  StreamOptions,
+} from '../../types';
+import { createId } from '../ids';
+
+export interface MockTransportOptions {
+  /** Each entry is the assistant's reply for one user turn. Strings are split
+   *  into chunks; arrays are taken as the exact event sequence (after a
+   *  prepended `message_start` and before a synthetic `message_end`). */
+  replies?: Array<string | ChatStreamEvent[]>;
+  latencyMs?: number;
+  /** Initial history returned by `createSession`. */
+  initialMessages?: ChatMessage[];
+  shouldFail?: (attempt: number) => boolean;
+}
+
+const DEFAULT_REPLY = 'Hi there!';
+
+function splitForStream(text: string, parts = 4): string[] {
+  if (!text) return [];
+  const chunkSize = Math.max(1, Math.ceil(text.length / parts));
+  const out: string[] = [];
+  for (let i = 0; i < text.length; i += chunkSize) {
+    out.push(text.slice(i, i + chunkSize));
+  }
+  return out;
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+export function createMockTransport(opts: MockTransportOptions = {}): ChatTransport {
+  const replies = opts.replies?.length ? opts.replies : [DEFAULT_REPLY];
+  const latency = opts.latencyMs ?? 30;
+  const history: ChatMessage[] = [...(opts.initialMessages ?? [])];
+  let turn = 0;
+  let attempt = 0;
+
+  return {
+    async createSession(_opts?: CreateSessionOptions): Promise<SessionInfo> {
+      await sleep(latency);
+      return {
+        sessionId: createId('s'),
+        messages: history.length ? [...history] : undefined,
+        hasMore: false,
+        cursor: null,
+        resumed: history.length > 0,
+      };
+    },
+
+    async loadHistory(_sid, _cursor, _limit): Promise<HistoryPage> {
+      await sleep(latency);
+      return { messages: [], hasMore: false, nextCursor: null };
+    },
+
+    async *stream(
+      _sid: string,
+      content: string,
+      options: StreamOptions,
+    ): AsyncGenerator<ChatStreamEvent, void, void> {
+      attempt += 1;
+      if (opts.shouldFail?.(attempt)) {
+        throw new Error('mock transport scripted failure');
+      }
+
+      // Record the user message for any subsequent loadHistory.
+      history.push({
+        id: createId('u'),
+        role: 'user',
+        content,
+        createdAt: Date.now(),
+      });
+
+      const messageId = createId('a');
+      yield { type: 'message_start', messageId, sessionId: _sid };
+
+      const reply = replies[turn % replies.length];
+      turn += 1;
+
+      if (typeof reply === 'string') {
+        for (const piece of splitForStream(reply)) {
+          if (options.signal.aborted) return;
+          await sleep(latency);
+          yield { type: 'chunk', delta: piece };
+        }
+        yield { type: 'message_end', tokensIn: content.length, tokensOut: reply.length };
+      } else {
+        for (const ev of reply) {
+          if (options.signal.aborted) return;
+          await sleep(latency);
+          yield ev;
+        }
+        // If the script didn't end the message itself, do it for them.
+        const lastType = reply[reply.length - 1]?.type;
+        if (lastType !== 'message_end' && lastType !== 'error') {
+          yield { type: 'message_end' };
+        }
+      }
+    },
+
+    async send(_sid, content, _options?: SendOptions): Promise<ChatMessage> {
+      await sleep(latency);
+      const reply = replies[turn % replies.length];
+      turn += 1;
+      const text =
+        typeof reply === 'string'
+          ? reply
+          : reply
+              .filter((e) => e.type === 'chunk')
+              .map((e) => (e as { delta: string }).delta)
+              .join('');
+      return {
+        id: createId('a'),
+        role: 'assistant',
+        content: text || DEFAULT_REPLY,
+        createdAt: Date.now(),
+      };
+    },
+
+    async closeSession(_sid: string): Promise<void> {
+      // no-op
+    },
+  };
+}