@frontera-sdk/knowledge 0.0.0-stage → 1.53.17

package/src/knowledge-client.ts

@@ -0,0 +1,155 @@
+import type { FronteraClient } from '@frontera-sdk/core/client'
+import type { RequestOptions } from '@frontera-sdk/core/transport'
+
+import { KNOWLEDGE_ROUTES as R, routeRequest, type KnowledgeRoute } from './routes'
+import type {
+  AgentKnowledgeBases,
+  AnyKnowledgeSource,
+  DeletedKnowledgeBase,
+  DocumentListQuery,
+  DocumentPage,
+  DocumentStatuses,
+  DocumentText,
+  DocumentTextQuery,
+  KnowledgeBase,
+  KnowledgeCapabilities,
+  KnowledgeDocument,
+  KnowledgeDocumentDetails,
+  ManagedKnowledgeSource,
+  RemovedDocumentPage,
+  RemovedSource,
+  SearchRequest,
+  SearchResponse,
+  SourceInput,
+  SourcePatch,
+  SourcesOfBase,
+  SourceTest,
+  UploadResult,
+} from './types'
+import { waitUntilReady, type WaitOptions, type WaitResult } from './wait-until-ready'
+
+/** The most ids one status request takes. */
+const STATUS_BATCH = 200
+
+/**
+ * Typed client for Knowledge.
+ *
+ * The credential on the `FronteraClient` decides who acts and from where: a
+ * workspace key created with the Knowledge purpose acts as its workspace, an
+ * App token as the person using the App in the App's workspace, and a person's
+ * own sign-in as that person. Bases, documents and search take all three
+ * (an App does not create, rename or delete bases, or choose an Agent's bases);
+ * sources take only a person signed in. A refusal throws a `FronteraError`;
+ * `refusalReason(error)` from `./errors` says why.
+ */
+export class KnowledgeClient {
+  constructor(private readonly client: FronteraClient) {}
+
+  private call<T>(route: KnowledgeRoute, params: Record<string, string> = {}, options: Omit<RequestOptions, 'method'> = {}): Promise<T> {
+    const { method, path } = routeRequest(route, params)
+    return this.client.request<T>(path, { ...options, method })
+  }
+
+  /** What the caller may do from where it stands. Throws with reason `knowledge_off` where Knowledge does not run. */
+  me(): Promise<KnowledgeCapabilities> {
+    return this.call<KnowledgeCapabilities>(R.me)
+  }
+
+  /** Search the knowledge bases the caller reads; each result is a citation. */
+  search(request: SearchRequest, signal?: AbortSignal): Promise<SearchResponse> {
+    return this.call<SearchResponse>(R.search, {}, { body: request, signal })
+  }
+
+  readonly bases = {
+    /** The knowledge bases the caller reads: its workspace's own, and organization bases shared with that workspace. */
+    list: async (): Promise<KnowledgeBase[]> => (await this.call<{ bases: KnowledgeBase[] }>(R.listBases)).bases,
+    get: async (id: string): Promise<KnowledgeBase> => (await this.call<{ base: KnowledgeBase }>(R.getBase, { id })).base,
+    /** A workspace base in the caller's workspace. */
+    create: async (input: { name: string; description?: string | null }): Promise<KnowledgeBase> =>
+      (await this.call<{ base: KnowledgeBase }>(R.createBase, {}, { body: input })).base,
+    update: async (id: string, input: { name?: string; description?: string | null }): Promise<KnowledgeBase> =>
+      (await this.call<{ base: KnowledgeBase }>(R.updateBase, { id }, { body: input })).base,
+    /** Deletes the base and every document in it. */
+    delete: async (id: string): Promise<DeletedKnowledgeBase> => (await this.call<{ base: DeletedKnowledgeBase }>(R.deleteBase, { id })).base,
+  }
+
+  readonly documents = {
+    /** A page of a base's documents, newest first. Pass `nextCursor` back as `cursor` for the next page. */
+    list: (baseId: string, query: DocumentListQuery = {}): Promise<DocumentPage> =>
+      this.call<DocumentPage>(R.listDocuments, { id: baseId }, { query: { status: query.status, limit: query.limit, cursor: query.cursor } }),
+    /**
+     * Adds a file. The same bytes sent to the same base again answer the
+     * document they made, with `duplicate: true`, so sending again after a
+     * timeout or a crash never makes a copy. A `Blob` needs `fileName`.
+     */
+    upload: async (baseId: string, file: Blob, options: { fileName?: string; title?: string; signal?: AbortSignal } = {}): Promise<UploadResult> => {
+      const fileName = options.fileName ?? (file instanceof File ? file.name : undefined)
+      if (!fileName) throw new TypeError('A Blob needs options.fileName: Knowledge reads the type of a file from its name')
+      const form = new FormData()
+      form.append('file', file, fileName)
+      if (options.title !== undefined) form.append('title', options.title)
+      return this.call<UploadResult>(R.uploadDocument, { id: baseId }, { body: form, signal: options.signal })
+    },
+    /** One document with its base. A document not yet read (`scanning`) answers `not_found`; `status` sees it. */
+    get: async (id: string): Promise<KnowledgeDocumentDetails> => (await this.call<{ document: KnowledgeDocumentDetails }>(R.getDocument, { id })).document,
+    /** Where each document stands, in any status, in the order asked; any id the caller cannot see is in `missing`. */
+    status: async (ids: readonly string[], signal?: AbortSignal): Promise<DocumentStatuses> => {
+      const answer: DocumentStatuses = { documents: [], missing: [] }
+      for (let at = 0; at < ids.length; at += STATUS_BATCH) {
+        const batch = await this.call<DocumentStatuses>(R.documentStatuses, {}, { body: { ids: ids.slice(at, at + STATUS_BATCH) }, signal })
+        answer.documents.push(...batch.documents)
+        answer.missing.push(...batch.missing)
+      }
+      return answer
+    },
+    remove: async (id: string): Promise<KnowledgeDocument> => (await this.call<{ document: KnowledgeDocument }>(R.removeDocument, { id })).document,
+    /** Read a failed or old document again. */
+    reprocess: async (id: string): Promise<KnowledgeDocument> => (await this.call<{ document: KnowledgeDocument }>(R.reprocessDocument, { id })).document,
+    /** A ready document's text page by page, for citing it. */
+    text: (id: string, query: DocumentTextQuery = {}): Promise<DocumentText> =>
+      this.call<DocumentText>(R.documentText, { id }, { query: { fromPage: query.fromPage, toPage: query.toPage, maxChars: query.maxChars } }),
+    /** The original file, its body unread. */
+    file: (id: string, signal?: AbortSignal): Promise<Response> => {
+      const { method, path } = routeRequest(R.documentFile, { id })
+      return this.client.requestRaw(path, { method, signal })
+    },
+    /** Polls until every document is settled; see `WaitOptions`. */
+    waitUntilReady: (ids: readonly string[], options: WaitOptions = {}): Promise<WaitResult> => waitUntilReady(this, ids, options),
+  }
+
+  readonly agents = {
+    /** The knowledge bases an Agent may search, and which it picks. */
+    bases: (agentId: string): Promise<AgentKnowledgeBases> => this.call<AgentKnowledgeBases>(R.agentBases, { agentId }),
+    /** Replaces the Agent's picks; they apply at once. */
+    setBases: (agentId: string, knowledgeBaseIds: readonly string[]): Promise<AgentKnowledgeBases> =>
+      this.call<AgentKnowledgeBases>(R.setAgentBases, { agentId }, { body: { knowledgeBaseIds } }),
+  }
+
+  /** Sources: another system's list of documents that a base syncs from. Only a person signed in manages them. */
+  readonly sources = {
+    list: (baseId: string): Promise<SourcesOfBase> => this.call<SourcesOfBase>(R.listSources, { id: baseId }),
+    get: async (id: string): Promise<AnyKnowledgeSource> => (await this.call<{ source: AnyKnowledgeSource }>(R.getSource, { id })).source,
+    add: async (baseId: string, input: SourceInput): Promise<ManagedKnowledgeSource> =>
+      (await this.call<{ source: ManagedKnowledgeSource }>(R.addSource, { id: baseId }, { body: input })).source,
+    /** Reads the first page as the source would be added, and stores nothing. With `detect`, works out where the items and fields are first. */
+    test: async (baseId: string, input: SourceInput, options: { detect?: boolean } = {}): Promise<SourceTest> =>
+      (await this.call<{ test: SourceTest }>(R.testSource, { id: baseId }, { body: input, query: { detect: options.detect } })).test,
+    /** A change that moves where the credential would be sent needs `credential` again (reason `credential_required`). */
+    update: async (id: string, patch: SourcePatch): Promise<ManagedKnowledgeSource> =>
+      (await this.call<{ source: ManagedKnowledgeSource }>(R.updateSource, { id }, { body: patch })).source,
+    replaceCredential: async (id: string, credential: string): Promise<ManagedKnowledgeSource> =>
+      (await this.call<{ source: ManagedKnowledgeSource }>(R.replaceSourceCredential, { id }, { body: { credential } })).source,
+    /** Sync now. Refused while it syncs, is paused or is being removed. */
+    sync: async (id: string): Promise<ManagedKnowledgeSource> => (await this.call<{ source: ManagedKnowledgeSource }>(R.syncSource, { id })).source,
+    pause: async (id: string): Promise<AnyKnowledgeSource> => (await this.call<{ source: AnyKnowledgeSource }>(R.pauseSource, { id })).source,
+    resume: async (id: string): Promise<ManagedKnowledgeSource> => (await this.call<{ source: ManagedKnowledgeSource }>(R.resumeSource, { id })).source,
+    /** Removes the source; its documents are deleted in the background. */
+    remove: async (id: string): Promise<RemovedSource> => (await this.call<{ source: RemovedSource }>(R.removeSource, { id })).source,
+    /** A page of the base's documents their source no longer has, most recently hidden first. */
+    removedDocuments: (baseId: string, query: { limit?: number; cursor?: string } = {}): Promise<RemovedDocumentPage> =>
+      this.call<RemovedDocumentPage>(R.removedDocuments, { id: baseId }, { query: { limit: query.limit, cursor: query.cursor } }),
+    /** Deletes up to 100 of them now; answers the ids deleted. */
+    deleteRemovedDocuments: async (baseId: string, documentIds: readonly string[]): Promise<string[]> =>
+      (await this.call<{ deleted: string[] }>(R.deleteRemovedDocuments, { id: baseId }, { body: { documentIds } })).deleted,
+  }
+}

package/src/provider.tsx

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react'
+import type { FronteraClient } from '@frontera-sdk/core/client'
+
+import { FronteraKnowledgeContext } from './hooks'
+import { KnowledgeClient } from './knowledge-client'
+
+/**
+ * Plug Knowledge into `createFronteraApp` or `FronteraAppProvider`:
+ *
+ * ```tsx
+ * createFronteraApp(<App />, { providers: [knowledgeProvider] })
+ * ```
+ *
+ * The App reads and adds as the person using it, in the App's workspace. The
+ * client is rebuilt whenever the host rotates the credential, because the
+ * `FronteraClient` it wraps is replaced rather than changed.
+ */
+export function knowledgeProvider(value: { client: FronteraClient }, children: ReactNode): ReactNode {
+  return <FronteraKnowledgeContext.Provider value={new KnowledgeClient(value.client)}>{children}</FronteraKnowledgeContext.Provider>
+}

package/src/routes.ts

@@ -0,0 +1,55 @@
+/**
+ * Every Knowledge route this package calls, by the method it backs. The
+ * service's contract test checks each one against the platform's own route
+ * table, and lists the routes left out on purpose, so a route added to the
+ * platform is a decision here rather than a gap.
+ */
+export const KNOWLEDGE_ROUTES = {
+  me: 'GET /me',
+  listBases: 'GET /bases',
+  createBase: 'POST /bases',
+  getBase: 'GET /bases/:id',
+  updateBase: 'PATCH /bases/:id',
+  deleteBase: 'DELETE /bases/:id',
+  listDocuments: 'GET /bases/:id/documents',
+  uploadDocument: 'POST /bases/:id/documents',
+  documentStatuses: 'POST /documents/status',
+  getDocument: 'GET /documents/:id',
+  removeDocument: 'DELETE /documents/:id',
+  reprocessDocument: 'POST /documents/:id/reprocess',
+  documentText: 'GET /documents/:id/text',
+  documentFile: 'GET /documents/:id/file',
+  search: 'POST /search',
+  agentBases: 'GET /agents/:agentId/bases',
+  setAgentBases: 'PUT /agents/:agentId/bases',
+  listSources: 'GET /bases/:id/sources',
+  addSource: 'POST /bases/:id/sources',
+  testSource: 'POST /bases/:id/sources/test',
+  getSource: 'GET /sources/:id',
+  updateSource: 'PATCH /sources/:id',
+  replaceSourceCredential: 'PUT /sources/:id/credential',
+  syncSource: 'POST /sources/:id/sync',
+  pauseSource: 'POST /sources/:id/pause',
+  resumeSource: 'POST /sources/:id/resume',
+  removeSource: 'DELETE /sources/:id',
+  removedDocuments: 'GET /bases/:id/removed-documents',
+  deleteRemovedDocuments: 'POST /bases/:id/removed-documents/batch-delete',
+} as const
+
+export type KnowledgeRoute = (typeof KNOWLEDGE_ROUTES)[keyof typeof KNOWLEDGE_ROUTES]
+
+/** Where the platform serves Knowledge. */
+export const KNOWLEDGE_PATH = '/v1/knowledge-app'
+
+type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+
+/** The method and the path of a route, each `:name` filled from `params`. */
+export function routeRequest(route: KnowledgeRoute, params: Record<string, string> = {}): { method: Method; path: string } {
+  const space = route.indexOf(' ')
+  const path = route.slice(space + 1).replace(/:(\w+)/g, (_, name: string) => {
+    const value = params[name]
+    if (value === undefined) throw new TypeError(`${route} needs ${name}`)
+    return encodeURIComponent(value)
+  })
+  return { method: route.slice(0, space) as Method, path: `${KNOWLEDGE_PATH}${path}` }
+}

package/src/types.ts

@@ -0,0 +1,187 @@
+import type * as Wire from './wire-types'
+
+/**
+ * The public shapes of `@frontera-sdk/knowledge`. Everything a route answers
+ * through a response schema is named from `wire-types.ts`, which the service
+ * generates from those schemas; the source answers, which have no schema yet,
+ * are written here and pinned by the service's contract test. Dates travel as
+ * ISO strings. A field may be added in a release; none is removed or retyped.
+ */
+
+/** Where a document stands. `ready`, `failed` and `blocked` are settled; the rest are still on their way. */
+export const DOCUMENT_STATUSES = ['scanning', 'pending', 'processing', 'ready', 'failed', 'blocked'] as const
+export type DocumentStatus = (typeof DOCUMENT_STATUSES)[number]
+
+/** The statuses a document does not leave by itself. */
+export const SETTLED_STATUSES: ReadonlySet<DocumentStatus> = new Set(['ready', 'failed', 'blocked'])
+
+/** The kinds of file a search can be narrowed to. */
+export const DOCUMENT_TYPES = ['pdf', 'word', 'sheet', 'slides', 'image', 'text', 'other'] as const
+export type DocumentType = (typeof DOCUMENT_TYPES)[number]
+
+/** How recently a document changed, for narrowing a search. */
+export const UPDATED_RANGES = ['week', 'month', 'year'] as const
+export type UpdatedRange = (typeof UPDATED_RANGES)[number]
+
+/** What the caller may do from where it stands. */
+export type KnowledgeCapabilities = Wire.CapabilitiesAnswer
+export type KnowledgeBase = Wire.BaseAnswer['base']
+export type DeletedKnowledgeBase = Wire.DeletedBaseAnswer['base']
+export type KnowledgeDocument = Wire.DocumentAnswer['document']
+/** A document with the base it is in. */
+export type KnowledgeDocumentDetails = Wire.DocumentDetailsAnswer['document']
+/** One page of a base's documents, newest first; `nextCursor` is null on the last page. */
+export type DocumentPage = Wire.DocumentsAnswer
+/** The document of the uploaded bytes; `duplicate` when the base already had those bytes. */
+export type UploadResult = Wire.UploadedAnswer
+/** The asked documents the caller can see, in the order asked, and every other id in `missing`. */
+export type DocumentStatuses = Wire.StatusesAnswer
+/** A document's text page by page, for citing it; `nextPage` is where to continue when `cut`. */
+export type DocumentText = Wire.DocumentTextAnswer
+export type SearchResponse = Wire.SearchAnswer
+/** One search result: the passage's document, page and snippet, and `openUrl`, the document's page on the platform. */
+export type Citation = Wire.SearchAnswer['results'][number]
+/** The knowledge bases an Agent may search, which of them it picks, and whether the caller may change the picks. */
+export type AgentKnowledgeBases = Wire.AgentBasesAnswer
+
+export type DocumentListQuery = {
+  status?: DocumentStatus
+  /** 1 to 200. Without `limit` and `cursor` the route answers every document at once. */
+  limit?: number
+  cursor?: string
+}
+
+export type SearchRequest = {
+  query: string
+  knowledgeBaseIds?: string[]
+  types?: DocumentType[]
+  /** Who added the documents. */
+  addedBy?: string[]
+  updated?: UpdatedRange
+  /** 1 to 50. */
+  limit?: number
+  /** The words as typed: no corrected spelling, even when they find nothing. */
+  exact?: boolean
+  /** Each passage's whole text in `text`, for a program that writes its own answer from the results. */
+  includeText?: boolean
+}
+
+export type DocumentTextQuery = {
+  fromPage?: number
+  toPage?: number
+  /** 1 to 100,000; 20,000 when not given. */
+  maxChars?: number
+}
+
+export type SourceSpec = Wire.SourceSpec
+export type SourceInput = Wire.SourceInput
+export type SourcePatch = Wire.SourcePatch
+export type PullConfig = Wire.PullConfig
+export type SourceAuth = Wire.SourceAuth
+
+export type SourceSchedule = SourceSpec['schedule']
+export type KeepRemovedDays = SourceSpec['keepRemovedDays']
+/** `running` while a sync is in progress, `failed` after the last sync failed (it tries again by itself), `removing` while its documents are deleted. */
+export type SourceState = 'idle' | 'running' | 'failed' | 'paused' | 'removing'
+
+/**
+ * Where a source's sync is: when the next sync is due (null for none), when the
+ * last started and the last that finished well, the failures in a row, the last
+ * failure (its own sentence only for whoever manages the base), and while a
+ * sync runs, how far it is.
+ */
+export type SourceSync = {
+  nextRunAt: string | null
+  lastRunAt: string | null
+  lastSuccessAt: string | null
+  failures: number
+  error: { kind: string; message: string } | null
+  pass: { pages: number; listed: number; stored: number; removed: number } | null
+}
+
+/** A source as anyone who reads its base, or an organization owner or admin, sees it. */
+export type KnowledgeSource = {
+  id: string
+  knowledgeBaseId: string
+  kind: 'api_pull'
+  name: string
+  host: string
+  schedule: SourceSchedule
+  state: SourceState
+  documents: number
+  sync: SourceSync
+  createdAt: string
+  updatedAt: string
+  canManage: boolean
+  /** Pause or remove it: whoever manages its base, and organization owners and admins. */
+  canStop: boolean
+}
+
+/** A source as whoever manages its base sees it: its whole shape, what waits in Removed at source, and when and by whom its credential was set. */
+export type ManagedKnowledgeSource = KnowledgeSource & {
+  keepRemovedDays: KeepRemovedDays
+  removedAtSource: number
+  config: PullConfig
+  auth: SourceAuth
+  credential: { setAt: string; setBy: string } | null
+  createdBy: string
+  updatedBy: string
+}
+
+export type AnyKnowledgeSource = KnowledgeSource | ManagedKnowledgeSource
+
+export function isManagedSource(source: AnyKnowledgeSource): source is ManagedKnowledgeSource {
+  return 'config' in source
+}
+
+export type SourcesOfBase = {
+  sources: AnyKnowledgeSource[]
+  /** The organization's policy lets this base's layer have sources. */
+  sourcesAllowed: boolean
+  canAdd: boolean
+}
+
+/** A removed source and how many documents it had, which are deleted in the background. */
+export type RemovedSource = { id: string; documents: number }
+
+export type SourcePullFailure = 'refused' | 'notFound' | 'slowDown' | 'unreachable' | 'timedOut' | 'badAnswer' | 'tooLarge' | 'blocked'
+export type SourceItemField = 'id' | 'title' | 'updatedAt' | 'link' | 'content'
+
+export type SourceSampleItem =
+  | { kind: 'removed'; id: string }
+  | {
+    kind: 'document'
+    id: string
+    title: string
+    updatedAt: string
+    link: string | null
+    content:
+      | { kind: 'inline'; format: 'html' | 'markdown' | 'text'; chars: number; overLimit: boolean; excerpt: string }
+      | { kind: 'file'; host: string; credential: boolean }
+  }
+
+/** Test connection's answer: the first page as a sync would read it, or the one problem that stopped it. Nothing is stored. */
+export type SourceTest =
+  | {
+    connected: true
+    page: { items: number; bytes: number; ms: number; more: boolean; large: boolean }
+    items: SourceSampleItem[]
+    unmapped: { items: number; fields: Array<{ field: SourceItemField; at: string; missing: number }> }
+    overLimit: number
+    /** With `detect`: the config the page was read with, and the first item's fields with samples. */
+    detected?: { config: PullConfig; itemFields: Array<{ path: string; sample: string }> }
+  }
+  | { connected: false; problem: { kind: SourcePullFailure; message: string; retryAt: string | null } }
+
+/** A document its source no longer has, hidden until its source's retention deletes it. */
+export type RemovedDocument = {
+  id: string
+  title: string
+  fileName: string | null
+  mimeType: string | null
+  source: { id: string; name: string }
+  removedAt: string
+  deletesAt: string
+}
+
+export type RemovedDocumentPage = { documents: RemovedDocument[]; nextCursor: string | null }

package/src/upload-files.ts

@@ -0,0 +1,133 @@
+import { refusalReason, retryAfterSeconds, type KnowledgeRefusalReason } from './errors'
+import type { KnowledgeClient } from './knowledge-client'
+import type { KnowledgeDocument } from './types'
+import { sleep, throwIfAborted, type WaitOptions } from './wait-until-ready'
+
+/** The largest file Knowledge accepts. The service's contract test keeps it equal to the platform's limit. */
+export const MAX_UPLOAD_BYTES = 50 * 1024 * 1024
+
+/** One file to add: `path` names it in the outcome, and its last part is the file name Knowledge reads the type from. */
+export type FileToUpload = { path: string; file: Blob; title?: string }
+
+export type UploadOutcome =
+  | { path: string; outcome: 'uploaded' | 'duplicate'; document: KnowledgeDocument }
+  /** Knowledge refused the file and sending it again would be refused too. */
+  | { path: string; outcome: 'refused'; reason: KnowledgeRefusalReason | null; message: string }
+  /** No answer after every try, or, with `wait`, the document was gone. */
+  | { path: string; outcome: 'failed'; message: string }
+
+export type UploadFilesOptions = {
+  /** Files in flight at once; 4 by default. */
+  concurrency?: number
+  /** Tries after the first for a network failure or a server error; 3 by default. A refusal is never retried. */
+  retries?: number
+  /** The first pause before a retry, doubled each time, with jitter; 1,000 ms by default. */
+  retryDelayMs?: number
+  signal?: AbortSignal
+  /** Each file's outcome as soon as its upload answers, before any wait. */
+  onOutcome?: (outcome: UploadOutcome) => void
+  /** Wait until every added document is settled, and send a file once more if its upload did not get it stored. */
+  wait?: boolean | Omit<WaitOptions, 'resend' | 'signal'>
+}
+
+const isAsync = <T>(files: Iterable<T> | AsyncIterable<T>): files is AsyncIterable<T> => Symbol.asyncIterator in files
+
+const fileNameOf = (path: string) => path.split(/[\\/]/).pop() || path
+
+/**
+ * Sends one file until it gets an answer. Sending again is safe: the same bytes
+ * in the same base answer the document they made. While Knowledge is `busy` it
+ * waits as long as it is asked to, without counting a try; a network failure,
+ * a rate limit or a server error is tried again up to `retries` times; any
+ * other refusal is final.
+ */
+async function sendFile(knowledge: KnowledgeClient, baseId: string, entry: FileToUpload, options: UploadFilesOptions): Promise<UploadOutcome> {
+  const { retries = 3, retryDelayMs = 1000, signal } = options
+  const fileName = fileNameOf(entry.path)
+  if (entry.file.size > MAX_UPLOAD_BYTES) {
+    return { path: entry.path, outcome: 'refused', reason: 'file_too_large', message: `${fileName}: a file may be at most ${MAX_UPLOAD_BYTES / 1024 / 1024} MB` }
+  }
+  let failures = 0
+  for (;;) {
+    throwIfAborted(signal)
+    try {
+      const { document, duplicate } = await knowledge.documents.upload(baseId, entry.file, { fileName, title: entry.title, signal })
+      return { path: entry.path, outcome: duplicate ? 'duplicate' : 'uploaded', document }
+    } catch (error) {
+      throwIfAborted(signal)
+      const message = error instanceof Error ? error.message : String(error)
+      const reason = refusalReason(error)
+      const wait = retryAfterSeconds(error)
+      if (reason === 'busy') {
+        await sleep((wait ?? 30) * 1000, signal)
+        continue
+      }
+      const status = (error as { status?: unknown }).status
+      const retryable = typeof status !== 'number' || status === 429 || status >= 500
+      if (!retryable) return { path: entry.path, outcome: 'refused', reason: reason ?? null, message }
+      if (++failures > retries) return { path: entry.path, outcome: 'failed', message }
+      await sleep(wait !== undefined ? wait * 1000 : retryDelayMs * 2 ** (failures - 1) * (0.5 + Math.random()), signal)
+    }
+  }
+}
+
+/**
+ * Adds many files to one base, `concurrency` at a time, and answers one
+ * outcome per file in the order given. Files are read from `files` as workers
+ * free up, so a long folder walk can feed it lazily.
+ */
+export async function uploadFiles(
+  knowledge: KnowledgeClient,
+  baseId: string,
+  files: Iterable<FileToUpload> | AsyncIterable<FileToUpload>,
+  options: UploadFilesOptions = {},
+): Promise<UploadOutcome[]> {
+  const { concurrency = 4, signal, onOutcome, wait } = options
+  const source = isAsync(files) ? files[Symbol.asyncIterator]() : files[Symbol.iterator]()
+  const entries: FileToUpload[] = []
+  const outcomes: UploadOutcome[] = []
+  const worker = async () => {
+    for (;;) {
+      const next = await source.next()
+      if (next.done) return
+      const at = entries.push(next.value) - 1
+      outcomes[at] = await sendFile(knowledge, baseId, next.value, options)
+      onOutcome?.(outcomes[at]!)
+    }
+  }
+  await Promise.all(Array.from({ length: Math.max(1, concurrency) }, worker))
+  if (!wait) return outcomes
+
+  // A document id can stand for several files with the same bytes; each one's outcome follows it.
+  const filesOf = new Map<string, number[]>()
+  outcomes.forEach((outcome, at) => {
+    if (outcome.outcome === 'uploaded' || outcome.outcome === 'duplicate') filesOf.set(outcome.document.id, [...(filesOf.get(outcome.document.id) ?? []), at])
+  })
+  const resendFailures = new Map<number, string>()
+  const settled = await knowledge.documents.waitUntilReady([...filesOf.keys()], {
+    ...(wait === true ? {} : wait),
+    signal,
+    resend: async (documentId) => {
+      const ats = filesOf.get(documentId)!
+      const again = await sendFile(knowledge, baseId, entries[ats[0]!]!, options)
+      if (again.outcome === 'refused' || again.outcome === 'failed') {
+        for (const at of ats) resendFailures.set(at, again.message)
+        throw new Error(again.message)
+      }
+      filesOf.set(again.document.id, ats)
+      return { document: again.document, duplicate: again.outcome === 'duplicate' }
+    },
+  })
+  for (const document of settled.documents) {
+    for (const at of filesOf.get(document.id) ?? []) {
+      const outcome = outcomes[at]!
+      if (outcome.outcome === 'uploaded' || outcome.outcome === 'duplicate') outcomes[at] = { ...outcome, document }
+    }
+  }
+  for (const id of settled.missing) {
+    for (const at of filesOf.get(id) ?? []) {
+      outcomes[at] = { path: entries[at]!.path, outcome: 'failed', message: resendFailures.get(at) ?? `${fileNameOf(entries[at]!.path)}: the document was removed before it was read` }
+    }
+  }
+  return outcomes
+}