@k2b/cloud 0.6.0-rc.0

package/src/ai/client/file-source.ts

@@ -0,0 +1,95 @@
+/**
+ * FileSource adapter over a conversation's VFS routes (/conversations/:id/files).
+ * Files share one flat conversation namespace. Origin metadata preserves who
+ * created a file without encoding policy in its path. Browser-safe module.
+ */
+import type { FileSource, FileTreeEntry, FileViewContent } from "@k2b/ui";
+import type { AiFileStat } from "../files-store";
+
+const readError = async (response: Response, fallback: string): Promise<string> => {
+  const body = await response.json().catch(() => null);
+  return body && typeof body === "object" && "message" in body && typeof body.message === "string" ? body.message : fallback;
+};
+
+const TEXT_MEDIA_TYPES = new Set([
+  "application/json",
+  "application/yaml",
+  "application/xml",
+  "image/svg+xml",
+  "text/javascript",
+  "text/typescript",
+]);
+const isTextMediaType = (mediaType: string): boolean => mediaType.startsWith("text/") || TEXT_MEDIA_TYPES.has(mediaType);
+
+const bytesToBase64 = (bytes: Uint8Array): string => {
+  let binary = "";
+  const CHUNK = 0x8000;
+  for (let index = 0; index < bytes.length; index += CHUNK) {
+    binary += String.fromCharCode(...bytes.subarray(index, index + CHUNK));
+  }
+  return btoa(binary);
+};
+
+export const conversationFileSource = (baseUrl: string, conversationId: string): FileSource => {
+  const filesUrl = (suffix = "", params?: Record<string, string>) => {
+    const query = params ? `?${new URLSearchParams(params).toString()}` : "";
+    return `${baseUrl}/conversations/${conversationId}/files${suffix}${query}`;
+  };
+
+  const request = async <T>(url: string, init: RequestInit, fallback: string): Promise<T> => {
+    const response = await fetch(url, {
+      ...init,
+      headers: init.body instanceof FormData ? undefined : { "Content-Type": "application/json" },
+    });
+    if (!response.ok) throw new Error(await readError(response, fallback));
+    return (await response.json()) as T;
+  };
+
+  return {
+    async list(): Promise<FileTreeEntry[]> {
+      const result = await request<{ files: AiFileStat[] }>(filesUrl(), { method: "GET" }, "Failed to load files");
+      return result.files.map((file) => ({
+        path: file.path,
+        size: file.size,
+        mediaType: file.mediaType,
+        updatedAt: file.updatedAt,
+        badge: file.origin === "user" ? "upload" : undefined,
+      }));
+    },
+
+    async read(path: string): Promise<FileViewContent> {
+      const response = await fetch(filesUrl("/content", { path }));
+      if (!response.ok) throw new Error(await readError(response, "Failed to load file"));
+      const mediaType = response.headers.get("Content-Type")?.split(";")[0]?.trim() || "application/octet-stream";
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      return isTextMediaType(mediaType)
+        ? { encoding: "utf8", content: new TextDecoder().decode(bytes), mediaType }
+        : { encoding: "base64", content: bytesToBase64(bytes), mediaType };
+    },
+
+    async write(path, content, encoding = "utf8") {
+      await request(filesUrl("/content"), { method: "PUT", body: JSON.stringify({ path, content, encoding }) }, "Failed to save file");
+    },
+
+    async remove(path) {
+      await request(filesUrl("", { path }), { method: "DELETE" }, "Failed to delete file");
+    },
+
+    async rename(from, to) {
+      await request(filesUrl("/rename"), { method: "POST", body: JSON.stringify({ from, to }) }, "Failed to rename file");
+    },
+
+    async upload(_dirPath, files) {
+      for (const file of files) {
+        const form = new FormData();
+        form.append("file", file);
+        const response = await fetch(filesUrl(), { method: "POST", body: form });
+        if (!response.ok) throw new Error(await readError(response, `Failed to upload ${file.name}`));
+      }
+    },
+
+    downloadHref: (path) => filesUrl("/content", { path }),
+
+    isReadOnly: () => false,
+  };
+};

package/src/ai/client/live-connection.ts

@@ -0,0 +1,140 @@
+import {
+  createLiveWebSocket,
+  type LiveWebSocket,
+  type LiveWebSocketClose,
+  type LiveWebSocketError,
+  type LiveWebSocketStatus,
+} from "../../browser/live-websocket";
+import { AI_LIVE_WS_TYPE, type AiLiveServerMessage, parseAiLiveServerMessage } from "../live-events";
+import type { AiConversationStreamTransport, AiStreamConnectionStatus } from "./transport";
+
+type TurnSubscription = {
+  conversationId: string;
+  generation: number;
+  onEvent: Parameters<AiConversationStreamTransport["subscribe"]>[0]["onEvent"];
+  onStatus?: Parameters<AiConversationStreamTransport["subscribe"]>[0]["onStatus"];
+  onError?: Parameters<AiConversationStreamTransport["subscribe"]>[0]["onError"];
+};
+
+export type AiLiveConnection = {
+  connect: () => void;
+  markApplied: (cursor: string | null | undefined) => void;
+  streamTransport: AiConversationStreamTransport;
+  dispose: () => void;
+};
+
+export type CreateAiLiveConnectionOptions = {
+  url?: string;
+  initialCursor: string;
+  onLiveMessage: (message: AiLiveServerMessage) => void;
+  onLiveStatus?: (status: LiveWebSocketStatus) => void;
+  onFatal?: (error: LiveWebSocketError) => void;
+};
+
+const reconnectableAiClose = (close: LiveWebSocketClose): LiveWebSocketError | null =>
+  close.code === 1008 ? { code: close.reason || "access_denied", message: "Live access changed or expired." } : null;
+
+const streamStatus = (status: LiveWebSocketStatus): AiStreamConnectionStatus | null => {
+  if (status === "connecting" || status === "reconnecting") return status;
+  if (status === "paused") return "reconnecting";
+  return null;
+};
+
+/** One browser connection for AI invalidations and the currently visible turn. */
+export const createAiLiveConnection = (options: CreateAiLiveConnectionOptions): AiLiveConnection => {
+  let socket: LiveWebSocket;
+  let turn: TurnSubscription | null = null;
+  let turnGeneration = 0;
+  let connected = false;
+  let disposed = false;
+  let liveSubscribeCount = 0;
+
+  const sendTurnSubscription = () => {
+    if (!connected || !turn) return;
+    if (
+      !socket.send({
+        type: AI_LIVE_WS_TYPE.turnSubscribe,
+        payload: { conversationId: turn.conversationId },
+      })
+    ) {
+      turn.onStatus?.("reconnecting");
+    }
+  };
+
+  socket = createLiveWebSocket<AiLiveServerMessage>({
+    url: options.url ?? "/api/ai/live",
+    initialCursor: options.initialCursor,
+    subscribe: (cursor) => ({
+      type: AI_LIVE_WS_TYPE.subscribe,
+      payload: { fromCursor: cursor, recover: liveSubscribeCount++ > 0 },
+    }),
+    parse: parseAiLiveServerMessage,
+    classifyClose: reconnectableAiClose,
+    onOpen: sendTurnSubscription,
+    onStatus: (status) => {
+      connected = status === "open";
+      options.onLiveStatus?.(status);
+      const next = streamStatus(status);
+      if (next) turn?.onStatus?.(next);
+    },
+    onMessage: (message) => {
+      if (message.type === AI_LIVE_WS_TYPE.turnEvent) {
+        if (!turn || turn.conversationId !== message.payload.conversationId) return;
+        if (message.payload.event.type === "state") turn.onStatus?.("open");
+        turn.onEvent(message.payload.event);
+        return;
+      }
+      if (message.type === AI_LIVE_WS_TYPE.turnError) {
+        if (!turn || turn.conversationId !== message.payload.conversationId) return;
+        const current = turn;
+        turn = null;
+        current.onError?.(new Error(message.payload.message));
+        return;
+      }
+      options.onLiveMessage(message);
+    },
+    onFatal: (error) => {
+      connected = false;
+      const current = turn;
+      turn = null;
+      current?.onError?.(new Error(error.message));
+      options.onFatal?.(error);
+    },
+  });
+
+  const streamTransport: AiConversationStreamTransport = {
+    subscribe: ({ conversationId, onEvent, onStatus, onError }) => {
+      const generation = ++turnGeneration;
+      const subscription: TurnSubscription = { conversationId, generation, onEvent, onStatus, onError };
+      turn = subscription;
+      onStatus?.("connecting");
+      sendTurnSubscription();
+      return {
+        close: () => {
+          if (turn?.generation !== generation) return;
+          turn = null;
+          if (connected) {
+            socket.send({
+              type: AI_LIVE_WS_TYPE.turnUnsubscribe,
+              payload: { conversationId },
+            });
+          }
+        },
+      };
+    },
+  };
+
+  return {
+    connect: () => {
+      if (!disposed) socket.connect();
+    },
+    markApplied: (cursor) => socket.markApplied(cursor),
+    streamTransport,
+    dispose: () => {
+      if (disposed) return;
+      disposed = true;
+      turn = null;
+      socket.dispose();
+    },
+  };
+};

package/src/ai/client/projection.ts

@@ -0,0 +1,178 @@
+import type { AiStreamEvent, AiTurnBlock, AiTurnSnapshot, AiWireEvent } from "../protocol";
+import { applyWireEventToBlocks, isNewerWireEvent, reconcileResolvedTurnActions, toolBlockId } from "../protocol";
+import type { AiConversation, AiStoredMessage } from "../types";
+
+export type AiActiveTurn = {
+  turnId: string;
+  attempt: number;
+  seq: number;
+  status: "running" | "waiting_for_action";
+  blocks: AiTurnBlock[];
+  modelProfileId: string | null;
+};
+
+export type AiChatProjection = {
+  conversation: AiConversation | null;
+  messages: AiStoredMessage[];
+  activeTurn: AiActiveTurn | null;
+};
+
+export const emptyProjection = (conversation: AiConversation | null = null): AiChatProjection => ({
+  conversation,
+  messages: [],
+  activeTurn: null,
+});
+
+const mergeMessages = (existing: AiStoredMessage[], incoming: AiStoredMessage[]): AiStoredMessage[] => {
+  if (incoming.length === 0) return existing;
+  const byId = new Map(existing.map((message) => [message.id, message]));
+  for (const message of incoming) byId.set(message.id, message);
+  return [...byId.values()].sort((a, b) => a.seq - b.seq);
+};
+
+/** A turn is "waiting" when any of its tool blocks is awaiting a user action. */
+const deriveStatus = (blocks: AiTurnBlock[]): "running" | "waiting_for_action" =>
+  blocks.some((block) => block.kind === "tool" && (block.status === "awaiting_approval" || block.status === "awaiting_client"))
+    ? "waiting_for_action"
+    : "running";
+
+const overlayBlocks = (base: AiTurnBlock[], overlay: AiTurnBlock[]): AiTurnBlock[] => {
+  const next = [...base];
+  const indexById = new Map(next.map((block, index) => [block.id, index]));
+  for (const block of overlay) {
+    const index = indexById.get(block.id);
+    if (index === undefined) {
+      indexById.set(block.id, next.length);
+      next.push(block);
+    } else {
+      next[index] = block;
+    }
+  }
+  return next;
+};
+
+const normalizeCustomApprovalBlocks = (blocks: AiTurnBlock[]): AiTurnBlock[] => {
+  const normalized: AiTurnBlock[] = [];
+  const indexById = new Map<string, number>();
+  for (const block of blocks) {
+    const parentCallId =
+      block.kind === "tool" && block.status === "awaiting_approval" ? /^(.*)-approval-\d+$/.exec(block.callId)?.[1] : undefined;
+    const next = parentCallId ? { ...block, id: toolBlockId(parentCallId) } : block;
+    const index = indexById.get(next.id);
+    if (index === undefined) {
+      indexById.set(next.id, normalized.length);
+      normalized.push(next);
+    } else {
+      normalized[index] = next;
+    }
+  }
+  return normalized;
+};
+
+/** Never let a same-turn DB/SSE snapshot remove blocks the browser already observed. */
+export const mergeActiveTurn = (previous: AiActiveTurn | null, incoming: AiActiveTurn | null): AiActiveTurn | null => {
+  if (!previous || !incoming || previous.turnId !== incoming.turnId) return incoming;
+  if (previous.attempt !== incoming.attempt) return incoming.attempt > previous.attempt ? incoming : previous;
+
+  const incomingIsNewer = incoming.seq >= previous.seq;
+  const blocks = incomingIsNewer ? overlayBlocks(previous.blocks, incoming.blocks) : overlayBlocks(incoming.blocks, previous.blocks);
+  return {
+    ...(incomingIsNewer ? incoming : previous),
+    seq: Math.max(previous.seq, incoming.seq),
+    blocks,
+    status: deriveStatus(blocks),
+  };
+};
+
+export const reconcileActiveTurnActions = (
+  turn: AiActiveTurn,
+  actions: Parameters<typeof reconcileResolvedTurnActions>[1],
+): AiActiveTurn => {
+  const blocks = reconcileResolvedTurnActions(turn.blocks, actions);
+  return blocks === turn.blocks ? turn : { ...turn, blocks, status: deriveStatus(blocks) };
+};
+
+/** Convert a server turn snapshot into a live active-turn (queued turns count as running). */
+export const activeTurnFromSnapshot = (snapshot: AiTurnSnapshot | null): AiActiveTurn | null => {
+  if (!snapshot) return null;
+  if (snapshot.status === "completed" || snapshot.status === "failed" || snapshot.status === "aborted") return null;
+  return {
+    turnId: snapshot.turnId,
+    attempt: snapshot.attempt,
+    seq: snapshot.seq,
+    status: snapshot.status === "waiting_for_action" ? "waiting_for_action" : "running",
+    blocks: normalizeCustomApprovalBlocks(snapshot.blocks),
+    modelProfileId: snapshot.modelProfileId,
+  };
+};
+
+/**
+ * Fold one stream event into the projection. Pure and total: the client and any
+ * test converge on the same state for the same ordered event sequence.
+ *
+ * Rules:
+ * - `state` replaces everything (reconnect baseline).
+ * - `turn_started` atomically installs the attempt's ordered block baseline;
+ *   stale attempts are ignored. Older senders without a baseline reset to only
+ *   locally pending steering blocks.
+ * - block events apply only when strictly newer than the active turn's cursor.
+ * - `turn_finished` folds the turn's persisted messages in and clears the active turn.
+ */
+export const reduceProjection = (state: AiChatProjection, event: AiStreamEvent): AiChatProjection => {
+  if (event.type === "state") {
+    // The snapshot only carries the newest window. History the client already
+    // paged in (older than the window) must survive a reconnect — losing the
+    // scrollback under the reader would be unpredictable.
+    const windowOldest = event.messages[0]?.seq;
+    const sameConversation = state.conversation?.id === event.conversation.id;
+    const preservedOlder =
+      sameConversation && windowOldest !== undefined ? state.messages.filter((message) => message.seq < windowOldest) : [];
+    return {
+      conversation: event.conversation,
+      messages: [...preservedOlder, ...event.messages],
+      activeTurn: mergeActiveTurn(sameConversation ? state.activeTurn : null, activeTurnFromSnapshot(event.activeTurn)),
+    };
+  }
+
+  return reduceWireEvent(state, event);
+};
+
+export const reduceWireEvent = (state: AiChatProjection, event: AiWireEvent): AiChatProjection => {
+  const active = state.activeTurn;
+
+  if (event.type === "turn_started") {
+    if (active && active.turnId === event.turnId && event.attempt < active.attempt) return state;
+    const pendingSteers =
+      active?.turnId === event.turnId ? active.blocks.filter((block) => block.kind === "steer_message" && block.status !== "consumed") : [];
+    const blocks = event.blocks ? overlayBlocks(normalizeCustomApprovalBlocks(event.blocks), pendingSteers) : pendingSteers;
+    return {
+      ...state,
+      activeTurn: {
+        turnId: event.turnId,
+        attempt: event.attempt,
+        seq: event.seq,
+        status: deriveStatus(blocks),
+        blocks,
+        modelProfileId: event.modelProfileId,
+      },
+    };
+  }
+
+  if (event.type === "turn_finished") {
+    if (!active || active.turnId !== event.turnId) return state;
+    return { ...state, messages: mergeMessages(state.messages, event.messages ?? []), activeTurn: null };
+  }
+
+  // block_set / block_delta
+  if (!active || active.turnId !== event.turnId) return state;
+  if (!isNewerWireEvent(event, active)) return state;
+  const blocks = applyWireEventToBlocks(active.blocks, event);
+  return { ...state, activeTurn: { ...active, attempt: event.attempt, seq: event.seq, blocks, status: deriveStatus(blocks) } };
+};
+
+/** Assistant/tool messages of the active turn are represented by live blocks; hide them. */
+export const visibleMessages = (state: AiChatProjection): AiStoredMessage[] => {
+  const activeTurnId = state.activeTurn?.turnId;
+  if (!activeTurnId) return state.messages;
+  return state.messages.filter((message) => message.loopId !== activeTurnId || (message.message.role === "user" && !message.meta?.steerId));
+};

package/src/ai/client/transport.ts

@@ -0,0 +1,111 @@
+import type { AiStreamEvent } from "../protocol";
+
+export type AiStreamHandle = { close: () => void };
+export type AiStreamFetch = (url: string, init: RequestInit) => Promise<Response>;
+export type AiStreamConnectionStatus = "connecting" | "open" | "reconnecting";
+export type AiConversationStreamTransport = {
+  subscribe: (input: {
+    conversationId: string;
+    url: string;
+    onEvent: (event: AiStreamEvent) => void;
+    onStatus?: (status: AiStreamConnectionStatus) => void;
+    onError?: (error: Error) => void;
+  }) => AiStreamHandle;
+};
+
+const RECONNECT_BASE_MS = 500;
+const RECONNECT_MAX_MS = 5_000;
+const CONNECT_TIMEOUT_MS = 10_000;
+
+/** Parse an SSE byte stream into decoded data payloads. */
+export async function* parseAiSse(response: Response, signal: AbortSignal): AsyncGenerator<AiStreamEvent> {
+  const reader = response.body?.getReader();
+  if (!reader) return;
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (!signal.aborted) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const chunks = buffer.split("\n\n");
+      buffer = chunks.pop() ?? "";
+      for (const chunk of chunks) {
+        const data = chunk
+          .split("\n")
+          .filter((line) => line.startsWith("data:"))
+          .map((line) => line.slice(5).trimStart())
+          .join("\n");
+        if (data) yield JSON.parse(data) as AiStreamEvent;
+      }
+    }
+  } finally {
+    await reader.cancel().catch(() => undefined);
+  }
+}
+
+/**
+ * Subscribe to a conversation's SSE stream with automatic reconnect. Each
+ * (re)connect starts with a fresh `state` event, so the projection self-heals on
+ * every reconnect without cursor bookkeeping.
+ */
+export const subscribeAiStream = (input: {
+  url: string;
+  onEvent: (event: AiStreamEvent) => void;
+  onStatus?: (status: AiStreamConnectionStatus) => void;
+  fetch?: AiStreamFetch;
+}): AiStreamHandle => {
+  const fetchStream: AiStreamFetch = input.fetch ?? fetch;
+  let reconnectDelay = RECONNECT_BASE_MS;
+  let stopped = false;
+  let activeAttempt: AbortController | null = null;
+  let connectTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const clearConnectTimer = () => {
+    if (connectTimer !== null) clearTimeout(connectTimer);
+    connectTimer = null;
+  };
+
+  const loop = async () => {
+    while (!stopped) {
+      const attempt = new AbortController();
+      activeAttempt = attempt;
+      connectTimer = setTimeout(() => attempt.abort(), CONNECT_TIMEOUT_MS);
+      try {
+        input.onStatus?.(reconnectDelay === RECONNECT_BASE_MS ? "connecting" : "reconnecting");
+        const response = await fetchStream(input.url, { signal: attempt.signal, headers: { Accept: "text/event-stream" } });
+        clearConnectTimer();
+        if (stopped) return;
+        if (!response.ok || !response.body) throw new Error(`AI stream failed: ${response.status}`);
+        input.onStatus?.("open");
+        reconnectDelay = RECONNECT_BASE_MS;
+        for await (const event of parseAiSse(response, attempt.signal)) {
+          if (stopped) break;
+          input.onEvent(event);
+        }
+      } catch {
+        if (stopped) return;
+      } finally {
+        clearConnectTimer();
+        if (activeAttempt === attempt) activeAttempt = null;
+      }
+      if (stopped) return;
+      await new Promise((resolve) => setTimeout(resolve, reconnectDelay));
+      reconnectDelay = Math.min(reconnectDelay * 2, RECONNECT_MAX_MS);
+    }
+  };
+
+  void loop();
+  return {
+    close: () => {
+      stopped = true;
+      clearConnectTimer();
+      activeAttempt?.abort();
+      activeAttempt = null;
+    },
+  };
+};
+
+export const aiSseConversationStreamTransport: AiConversationStreamTransport = {
+  subscribe: ({ url, onEvent, onStatus }) => subscribeAiStream({ url, onEvent, onStatus }),
+};