Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

23.9 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

import { authFetch } from "@/features/auth";
import { apiUrl } from "@/lib/api-base";
import { formatFastApiDetail } from "@/lib/format-fastapi-error";
import { openStreamResponse } from "@/lib/open-stream-response";
import { readSseJsonEvents } from "@/lib/sse-json-events";
import type {
  DocumentUploadResult,
  FolderSyncJob,
  FolderSyncJobEvent,
  IndexJob,
  JobEvent,
  KnowledgeBase,
  LinkedFolder,
  LinkedFolderScope,
  RagDocument,
  ReembedJob,
  ReembedStatus,
  UploadedDocument,
} from "../types/rag";
import { noteRagAvailability, noteRagResponse } from "./rag-availability";

const RAG_BASE = "/api/rag";

function parseErrorText(status: number, body: unknown): string {
  if (body && typeof body === "object") {
    const { detail, message } = body as { detail?: unknown; message?: unknown };
    const formatted = formatFastApiDetail(detail);
    if (formatted) return formatted;
    if (typeof message === "string" && message) return message;
  }
  return `Request failed (${status})`;
}

export function ragError(status: number, body: unknown): Error & { status: number } {
  return Object.assign(new Error(parseErrorText(status, body)), { status });
}

/** True for a definitive server answer, so retrying cannot help. */
export function isRagClientError(error: unknown): boolean {
  const status = (error as { status?: unknown } | null)?.status;
  return typeof status === "number" && status >= 400 && status < 500 && status !== 429;
}

async function ragRequest<T>(
  path: string,
  init?: { method?: string; body?: object; signal?: AbortSignal },
): Promise<T> {
  const response = await authFetch(`${RAG_BASE}${path}`, {
    method: init?.method,
    headers: init?.body ? { "Content-Type": "application/json" } : undefined,
    body: init?.body ? JSON.stringify(init.body) : undefined,
    signal: init?.signal,
  });
  if (response.status === 204) {
    noteRagResponse(204, null);
    return undefined as T;
  }
  const json = await response.json().catch(() => null);
  // Every RAG endpoint but the list gates on the extension, so its status reports availability.
  noteRagResponse(response.status, json);
  if (!response.ok) throw ragError(response.status, json);
  return json as T;
}

export interface NativeUploadRef {
  nativePathLease: string;
}

export type UploadSource = File | NativeUploadRef;

async function ragUpload(
  path: string,
  source: UploadSource,
  ocr?: boolean,
  caption?: boolean,
): Promise<DocumentUploadResult> {
  const form = new FormData();
  if (source instanceof File) form.append("file", source);
  else form.append("nativePathLease", source.nativePathLease);
  if (ocr !== undefined) form.append("ocr", String(ocr));
  if (caption !== undefined) form.append("caption", String(caption));
  // No Content-Type: let the browser set the multipart boundary.
  const response = await authFetch(`${RAG_BASE}${path}`, {
    method: "POST",
    body: form,
  });
  const json = await response.json().catch(() => null);
  noteRagResponse(response.status, json);
  if (!response.ok) throw ragError(response.status, json);
  return json as DocumentUploadResult;
}

/** Not gated on sqlite-vec, so its status says nothing about RAG availability. */
export async function extractDocumentText(
  file: File,
  beforeRetry?: () => void,
): Promise<{ text: string; truncated: boolean }> {
  const form = new FormData();
  form.append("file", file);
  const response = await authFetch(
    `${RAG_BASE}/extract-text`,
    { method: "POST", body: form },
    { beforeRetry },
  );
  const json = await response.json().catch(() => null);
  if (!response.ok) throw ragError(response.status, json);
  return json as { text: string; truncated: boolean };
}

export async function listKnowledgeBases(): Promise<KnowledgeBase[]> {
  const data = await ragRequest<{
    knowledgeBases: KnowledgeBase[];
    ragAvailable?: boolean;
    ragUnavailableReason?: string | null;
  }>("/knowledge-bases");
  // The only endpoint that returns 200 instead of 503 when RAG cannot run; the marker tells them apart.
  noteRagAvailability(data);
  return data.knowledgeBases ?? [];
}

export const KNOWLEDGE_BASES_CHANGED_EVENT = "unsloth-knowledge-bases-changed";

// Also on failure: a delete can fail because the row is already gone.
function announceKnowledgeBasesChanged(): void {
  if (typeof window === "undefined") return;
  window.dispatchEvent(new Event(KNOWLEDGE_BASES_CHANGED_EVENT));
}

export function subscribeKnowledgeBasesChanged(
  onChanged: () => void,
): () => void {
  if (typeof window === "undefined") return () => undefined;
  window.addEventListener(KNOWLEDGE_BASES_CHANGED_EVENT, onChanged);
  return () => window.removeEventListener(KNOWLEDGE_BASES_CHANGED_EVENT, onChanged);
}

export function createKnowledgeBase(payload: {
  name: string;
  description?: string;
}): Promise<{ id: string; name: string }> {
  return ragRequest<{ id: string; name: string }>("/knowledge-bases", {
    method: "POST",
    body: {
      name: payload.name,
      ...(payload.description ? { description: payload.description } : {}),
    },
  }).finally(announceKnowledgeBasesChanged);
}

export function updateKnowledgeBase(
  kbId: string,
  payload: { name?: string; description?: string },
): Promise<{ ok: boolean }> {
  const body: Record<string, unknown> = {};
  if (payload.name !== undefined) body.name = payload.name;
  if (payload.description !== undefined) body.description = payload.description;
  return ragRequest<{ ok: boolean }>(
    `/knowledge-bases/${encodeURIComponent(kbId)}`,
    { method: "PATCH", body },
  ).finally(announceKnowledgeBasesChanged);
}

export function deleteKnowledgeBase(kbId: string): Promise<{ ok: boolean }> {
  return ragRequest<{ ok: boolean }>(
    `/knowledge-bases/${encodeURIComponent(kbId)}`,
    { method: "DELETE" },
  ).finally(announceKnowledgeBasesChanged);
}

export async function listKnowledgeBaseDocuments(
  kbId: string,
): Promise<RagDocument[]> {
  const data = await ragRequest<{ documents: RagDocument[] }>(
    `/knowledge-bases/${encodeURIComponent(kbId)}/documents`,
  );
  return data.documents ?? [];
}

export function uploadKnowledgeBaseDocument(
  kbId: string,
  file: UploadSource,
  ocr?: boolean,
  caption?: boolean,
): Promise<DocumentUploadResult> {
  return ragUpload(
    `/knowledge-bases/${encodeURIComponent(kbId)}/documents`,
    file,
    ocr,
    caption,
  );
}

export async function listThreadDocuments(
  threadId: string,
): Promise<RagDocument[]> {
  const data = await ragRequest<{ documents: RagDocument[] }>(
    `/threads/${encodeURIComponent(threadId)}/documents`,
  );
  return data.documents ?? [];
}

export function uploadThreadDocument(
  threadId: string,
  file: UploadSource,
  ocr?: boolean,
  caption?: boolean,
): Promise<DocumentUploadResult> {
  return ragUpload(
    `/threads/${encodeURIComponent(threadId)}/documents`,
    file,
    ocr,
    caption,
  );
}

export async function listProjectDocuments(
  projectId: string,
): Promise<RagDocument[]> {
  const data = await ragRequest<{ documents: RagDocument[] }>(
    `/projects/${encodeURIComponent(projectId)}/documents`,
  );
  return data.documents ?? [];
}

export function uploadProjectDocument(
  projectId: string,
  file: UploadSource,
  ocr?: boolean,
  caption?: boolean,
): Promise<DocumentUploadResult> {
  return ragUpload(
    `/projects/${encodeURIComponent(projectId)}/documents`,
    file,
    ocr,
    caption,
  );
}

const projectSourcesCache = new Map<string, { has: boolean; at: number }>();
const PROJECT_SOURCES_TTL_MS = 30_000;

export async function projectHasSources(projectId: string): Promise<boolean> {
  const cached = projectSourcesCache.get(projectId);
  if (cached && Date.now() - cached.at < PROJECT_SOURCES_TTL_MS) {
    return cached.has;
  }
  try {
    const docs = await listProjectDocuments(projectId);
    const has = docs.some((doc) => doc.status !== "failed");
    projectSourcesCache.set(projectId, { has, at: Date.now() });
    return has;
  } catch {
    return false;
  }
}

/** The composer bar and the Sources panel are separate hooks over one scope. */
export const PROJECT_SOURCES_CHANGED_EVENT = "unsloth-project-sources-changed";
/** Legacy alias kept for existing listeners. */
export const PROJECT_SOURCES_UPDATED_EVENT = PROJECT_SOURCES_CHANGED_EVENT;

/** Only drops the cache: callers also invalidate before mutating, where a refetch would resurrect a row. */
export function invalidateProjectSources(projectId: string): void {
  projectSourcesCache.delete(projectId);
}

export function announceProjectSourcesUpdated(projectId: string): void {
  publishProjectSourcesChanged(projectId);
  getProjectChannel()?.postMessage({ kind: "sources", projectId });
}

export function subscribeProjectSourcesUpdated(
  projectId: string,
  onUpdated: () => void,
): () => void {
  if (typeof window === "undefined") return () => undefined;
  const listener = (event: Event) => {
    const detail = (event as CustomEvent<{ projectId?: string }>).detail;
    if (detail?.projectId === projectId) onUpdated();
  };
  window.addEventListener(PROJECT_SOURCES_CHANGED_EVENT, listener);
  subscribeProjectSourcesBroadcast();
  return () => {
    window.removeEventListener(PROJECT_SOURCES_CHANGED_EVENT, listener);
  };
}

function publishProjectSourcesChanged(projectId: string): void {
  projectSourcesCache.delete(projectId);
  if (typeof window === "undefined") return;
  window.dispatchEvent(
    new CustomEvent(PROJECT_SOURCES_CHANGED_EVENT, { detail: { projectId } }),
  );
}

/** CustomEvent reaches only its own tab, so other tabs hear changes here. Opened lazily. */
let projectChannel: BroadcastChannel | null | undefined;

function getProjectChannel(): BroadcastChannel | null {
  if (projectChannel !== undefined) {
    return projectChannel;
  }
  if (
    typeof window === "undefined" ||
    typeof BroadcastChannel === "undefined"
  ) {
    projectChannel = null;
    return null;
  }
  projectChannel = new BroadcastChannel(PROJECT_SOURCES_CHANGED_EVENT);
  // Node's BroadcastChannel holds the event loop open and hangs a test run.
  (projectChannel as { unref?: () => void }).unref?.();
  projectChannel.onmessage = (event: MessageEvent) => {
    const message = event.data as {
      kind?: string;
      projectId?: string;
      delta?: number;
      count?: number;
      from?: string;
    } | null;
    if (!message) {
      return;
    }
    if (message.kind === "work-query") {
      answerWorkQuery();
      return;
    }
    if (!message.projectId) {
      return;
    }
    if (message.kind === "work-state" && message.from) {
      seedRemoteProjectWork(
        message.projectId,
        message.from,
        message.count ?? 0,
      );
      return;
    }
    if (message.kind === "work" && message.from) {
      noteRemoteProjectWork(
        message.projectId,
        message.from,
        message.delta ?? 0,
      );
      return;
    }
    if (message.kind === "work" || message.kind === "work-state") {
      return;
    }
    publishProjectSourcesChanged(message.projectId);
  };
  askForWorkInFlight();
  return projectChannel;
}

/** BroadcastChannel does not replay, so a tab opening mid-upload asks for work in flight. */
function askForWorkInFlight(): void {
  projectChannel?.postMessage({ kind: "work-query" });
}

function answerWorkQuery(): void {
  const channel = getProjectChannel();
  if (!channel) return;
  for (const [projectId, count] of projectWorkInFlight) {
    channel.postMessage({ kind: "work-state", projectId, count, from: TAB_ID });
  }
}

/** Per-tab id: a merged count would let the first upload to finish release the second. */
const TAB_ID = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;

export function subscribeProjectSourcesBroadcast(): void {
  getProjectChannel();
}

/**
 * Work in flight per project, so the composer gates sends on uploads and folder syncs
 * started elsewhere that have no row yet.
 */
const projectWorkInFlight = new Map<string, number>();

export const PROJECT_WORK_CHANGED_EVENT = "unsloth-project-work-changed";

export function noteProjectWork(projectId: string, delta: number): void {
  const next = (projectWorkInFlight.get(projectId) ?? 0) + delta;
  if (next > 0) {
    projectWorkInFlight.set(projectId, next);
  } else {
    projectWorkInFlight.delete(projectId);
  }
  getProjectChannel()?.postMessage({
    kind: "work",
    projectId,
    delta,
    from: TAB_ID,
  });
  syncWorkHeartbeat();
  publishProjectWorkChanged(projectId);
}

/** Heartbeat sends the absolute count, since a zero delta cannot revive a lapsed entry. */
const WORK_HEARTBEAT_MS = 45_000;
let workHeartbeat: ReturnType<typeof setInterval> | null = null;

function syncWorkHeartbeat(): void {
  if (projectWorkInFlight.size === 0) {
    if (workHeartbeat !== null) {
      clearInterval(workHeartbeat);
      workHeartbeat = null;
    }
    return;
  }
  if (workHeartbeat !== null) {
    return;
  }
  workHeartbeat = setInterval(answerWorkQuery, WORK_HEARTBEAT_MS);
  (workHeartbeat as { unref?: () => void }).unref?.();
}

function publishProjectWorkChanged(projectId: string): void {
  if (typeof window === "undefined") {
    return;
  }
  window.dispatchEvent(
    new CustomEvent(PROJECT_WORK_CHANGED_EVENT, { detail: { projectId } }),
  );
}

/** Another tab's work expires: only its starter reports the end, and it may close first. */
const REMOTE_WORK_TTL_MS = 120_000;
/** Per project, per tab: aggregated, the first upload to finish would clear the second's count. */
const remoteProjectWork = new Map<
  string,
  Map<string, { count: number; until: number }>
>();
const remoteWorkTimers = new Map<string, ReturnType<typeof setTimeout>>();

function armRemoteWorkExpiry(projectId: string): void {
  const timer = remoteWorkTimers.get(projectId);
  if (timer !== undefined) {
    clearTimeout(timer);
  }
  remoteWorkTimers.delete(projectId);
  const bySender = remoteProjectWork.get(projectId);
  if (!bySender || bySender.size === 0) return;
  // Arm for the earliest sender deadline, or a closed tab stays counted until some later event.
  let earliest = Number.POSITIVE_INFINITY;
  for (const entry of bySender.values()) {
    earliest = Math.min(earliest, entry.until);
  }
  const expiry = setTimeout(
    () => {
      remoteWorkTimers.delete(projectId);
      const now = Date.now();
      const live = remoteProjectWork.get(projectId);
      if (live) {
        for (const [sender, entry] of live) {
          if (entry.until <= now) live.delete(sender);
        }
        if (live.size === 0) remoteProjectWork.delete(projectId);
      }
      publishProjectWorkChanged(projectId);
      armRemoteWorkExpiry(projectId);
    },
    Math.max(0, earliest - Date.now()),
  );
  // A pending timer would hold a Node test run open.
  (expiry as { unref?: () => void }).unref?.();
  remoteWorkTimers.set(projectId, expiry);
}

function setRemoteProjectWork(
  projectId: string,
  from: string,
  count: number,
): void {
  const bySender = remoteProjectWork.get(projectId) ?? new Map();
  if (count <= 0) {
    bySender.delete(from);
  } else {
    bySender.set(from, { count, until: Date.now() + REMOTE_WORK_TTL_MS });
  }
  if (bySender.size === 0) {
    remoteProjectWork.delete(projectId);
    const timer = remoteWorkTimers.get(projectId);
    if (timer !== undefined) {
      clearTimeout(timer);
      remoteWorkTimers.delete(projectId);
    }
  } else {
    remoteProjectWork.set(projectId, bySender);
    armRemoteWorkExpiry(projectId);
  }
  publishProjectWorkChanged(projectId);
}

function remoteSenderCount(projectId: string, from: string): number {
  const entry = remoteProjectWork.get(projectId)?.get(from);
  return entry && entry.until > Date.now() ? entry.count : 0;
}

function noteRemoteProjectWork(
  projectId: string,
  from: string,
  delta: number,
): void {
  const current = remoteSenderCount(projectId, from);
  // A zero delta is the heartbeat: it only renews this sender's deadline.
  if (delta === 0 && current === 0) return;
  setRemoteProjectWork(projectId, from, Math.max(0, current + delta));
}

/** Absolute count from a tab; never lowers a delta-raised count and revives a lapsed entry. */
function seedRemoteProjectWork(
  projectId: string,
  from: string,
  count: number,
): void {
  if (count <= 0) return;
  setRemoteProjectWork(projectId, from, Math.max(remoteSenderCount(projectId, from), count));
}

export function projectWorkCount(projectId: string): number {
  let remoteCount = 0;
  const now = Date.now();
  for (const entry of remoteProjectWork.get(projectId)?.values() ?? []) {
    if (entry.until > now) remoteCount += entry.count;
  }
  return (projectWorkInFlight.get(projectId) ?? 0) + remoteCount;
}

const MAX_FOLDER_JOB_READ_FAILURES = 20;

const watchedFolderJobs = new Set<string>();

/** Tied to the backend job, not its starter, since leaving the Sources tab does not stop the sync. */
export function watchProjectFolderJob(projectId: string, jobId: string): void {
  if (watchedFolderJobs.has(jobId)) {
    return;
  }
  watchedFolderJobs.add(jobId);
  noteProjectWork(projectId, 1);
  void (async () => {
    // A failed read is not a finished job: a backend restart can miss a tick.
    let consecutiveFailures = 0;
    try {
      for (let attempt = 0; attempt < 600; attempt += 1) {
        try {
          const job = await getFolderSyncJob(jobId);
          consecutiveFailures = 0;
          if (job.status === "completed" || job.status === "failed") {
            break;
          }
        } catch (error) {
          // An answered 4xx means the job rows are gone (unlink or history prune).
          if (isRagClientError(error)) break;
          consecutiveFailures += 1;
          if (consecutiveFailures >= MAX_FOLDER_JOB_READ_FAILURES) {
            break;
          }
        }
        await new Promise((resolve) => setTimeout(resolve, 3000));
      }
    } finally {
      watchedFolderJobs.delete(jobId);
      // Announce before releasing the gate, or a released send reads the cached "no sources".
      announceProjectSourcesUpdated(projectId);
      noteProjectWork(projectId, -1);
    }
  })();
}

/** Throttles lookups: two bars mount at once, and later backend jobs must still be seen. */
const folderReconcileNotBefore = new Map<string, number>();

/** Shorter than the backend scan interval, so a periodic caller is never skipped. */
const FOLDER_RECONCILE_MIN_GAP_MS = 5000;

/**
 * Pick up folder syncs already running (e.g. after a reload): the backend scans before
 * writing rows, so the composer's list cannot see them.
 */
export async function reconcileProjectFolderJobs(
  projectId: string,
): Promise<void> {
  const now = Date.now();
  if ((folderReconcileNotBefore.get(projectId) ?? 0) > now) return;
  folderReconcileNotBefore.set(projectId, now + FOLDER_RECONCILE_MIN_GAP_MS);
  noteProjectWork(projectId, 1);
  try {
    const folders = await listLinkedFolders({ type: "project", id: projectId });
    for (const folder of folders) {
      if (folder.activeJobId) {
        watchProjectFolderJob(projectId, folder.activeJobId);
      }
    }
  } catch {
    // Do not record a project as reconciled on an answer that never came.
    folderReconcileNotBefore.delete(projectId);
  } finally {
    noteProjectWork(projectId, -1);
  }
}

export async function listLinkedFolders(
  scope?: LinkedFolderScope,
): Promise<LinkedFolder[]> {
  const query = scope
    ? `?scope_type=${encodeURIComponent(scope.type)}&scope_id=${encodeURIComponent(scope.id)}`
    : "";
  const data = await ragRequest<{ linkedFolders: LinkedFolder[] }>(
    `/linked-folders${query}`,
  );
  return data.linkedFolders ?? [];
}

interface LinkedFolderMutationResult {
  linkedFolder: LinkedFolder;
  job: FolderSyncJob;
}

export function createLinkedFolder(
  scope: LinkedFolderScope,
  nativePathLease: string,
  displayName: string,
): Promise<LinkedFolderMutationResult> {
  const parent =
    scope.type === "knowledge_base" ? "knowledge-bases" : "projects";
  return ragRequest(
    `/${parent}/${encodeURIComponent(scope.id)}/linked-folders`,
    {
      method: "POST",
      body: { nativePathLease, displayName },
    },
  );
}

export function deleteLinkedFolder(
  linkedFolderId: string,
  removeIndex: boolean,
): Promise<{ ok: boolean }> {
  return ragRequest(
    `/linked-folders/${encodeURIComponent(linkedFolderId)}?remove_index=${removeIndex}`,
    { method: "DELETE" },
  );
}

function startLinkedFolderJob(
  linkedFolderId: string,
  action: "sync" | "rebuild",
): Promise<{ job: FolderSyncJob }> {
  return ragRequest(
    `/linked-folders/${encodeURIComponent(linkedFolderId)}/${action}`,
    { method: "POST" },
  );
}

export function syncLinkedFolder(
  linkedFolderId: string,
): Promise<{ job: FolderSyncJob }> {
  return startLinkedFolderJob(linkedFolderId, "sync");
}

export function rebuildLinkedFolder(
  linkedFolderId: string,
): Promise<{ job: FolderSyncJob }> {
  return startLinkedFolderJob(linkedFolderId, "rebuild");
}

export function getFolderSyncJob(jobId: string): Promise<FolderSyncJob> {
  return ragRequest(`/linked-folder-jobs/${encodeURIComponent(jobId)}`);
}

export async function listAllDocuments(): Promise<UploadedDocument[]> {
  const data = await ragRequest<{ documents: UploadedDocument[] }>(
    "/documents",
  );
  return data.documents ?? [];
}

export async function deleteDocument(
  documentId: string,
  projectId?: string | null,
): Promise<{ ok: boolean }> {
  const result = await ragRequest<{ ok: boolean }>(
    `/documents/${encodeURIComponent(documentId)}`,
    {
      method: "DELETE",
    },
  );
  if (projectId) announceProjectSourcesUpdated(projectId);
  return result;
}

export function getReembedStatus(): Promise<ReembedStatus> {
  return ragRequest("/reembed");
}

export function startReembed(): Promise<{ job: ReembedJob }> {
  return ragRequest("/reembed", { method: "POST" });
}

export function cancelReembed(): Promise<{ job: ReembedJob }> {
  return ragRequest("/reembed/cancel", { method: "POST" });
}

export function getJob(jobId: string, signal?: AbortSignal): Promise<IndexJob> {
  return ragRequest(`/jobs/${encodeURIComponent(jobId)}`, { signal });
}

const SSE_STALL_MS = 12000;

async function openEventStream(
  url: string,
  signal: AbortSignal | undefined,
): Promise<ReadableStream<Uint8Array>> {
  const response = await openStreamResponse(authFetch, url, { signal });
  if (!response.ok) {
    const body = await response.json().catch(() => null);
    noteRagResponse(response.status, body);
    throw ragError(response.status, body);
  }
  if (!response.body) throw new Error("Stream response missing body");
  return response.body;
}

// HTTP/1.1 allows six connections per origin; one shared budget keeps upload POSTs from stalling.
const MAX_RAG_STREAMS = 4;
let activeRagStreams = 0;

async function* boundedEventStream<T>(
  path: string,
  signal?: AbortSignal,
  stallMs?: number,
): AsyncGenerator<T> {
  if (activeRagStreams >= MAX_RAG_STREAMS) {
    throw new Error("RAG stream capacity reached");
  }
  activeRagStreams += 1;
  try {
    const body = await openEventStream(`${RAG_BASE}${path}`, signal);
    yield* readSseJsonEvents<T>(body, stallMs);
  } finally {
    activeRagStreams -= 1;
  }
}

// Returns on [DONE]; transport errors propagate so callers can poll getJob.
export function streamJobEvents(
  jobId: string,
  signal?: AbortSignal,
): AsyncGenerator<JobEvent> {
  // No stall bound: this consumer reads an early end as a finished job.
  return boundedEventStream<JobEvent>(
    `/jobs/${encodeURIComponent(jobId)}/events`,
    signal,
  );
}

export function streamFolderSyncJobEvents(
  jobId: string,
  signal?: AbortSignal,
): AsyncGenerator<FolderSyncJobEvent> {
  return boundedEventStream<FolderSyncJobEvent>(
    `/linked-folder-jobs/${encodeURIComponent(jobId)}/events`,
    signal,
    SSE_STALL_MS,
  );
}

// Signed URL (no bearer) so pdf.js can issue Range requests. Absolute because consumers bypass
// authFetch, and a relative path under Tauri resolves against the webview origin.
export async function getDocumentFileUrl(documentId: string): Promise<string> {
  const data = await ragRequest<{ url: string }>(
    `/documents/${encodeURIComponent(documentId)}/file-url`,
  );
  return apiUrl(data.url);
}