@hanzo/rooms 0.1.11 → 0.1.12

package/dist/lib/attach.js

@@ -1,76 +1,111 @@
 /**
- * Files that go with a chat message.
+ * Files that go with a chat message — by REFERENCE.
  *
- * @hanzo/ai's `send(text, images)` carries a picture as an `image_url` part the
- * model reads, and nothing else rides that wire, so a file goes one of two
- * ways: an image as a `data:` URI beside the words, a text file as its own
- * words after the message, fenced under its name. Any other kind is refused by
- * name, before anything is held.
+ * A file put into a conversation is uploaded to the org's workspace and indexed
+ * there (`lib/files`). The turn carries what NAMES it — id, name, type, size —
+ * and the passages read from it for the question, each citing
+ * file › section › ¶n. No byte of the file rides the chat request, so there is
+ * no size a file must stay under to go with a message.
  *
- * This module judges and reads a file; `pane.ts` holds what it admits, per
- * conversation, for the composer's chips and the column's Sources alike.
+ * The names and the passages travel in one block after the words. The block is
+ * what the model reads; `said` takes it back off for drawing, so a person sees
+ * their words and the files' chips, never the passages.
  */
-export const IMAGE_MAX = 8 * 1024 * 1024;
-export const TEXT_MAX = 256 * 1024;
-const TEXT_TYPE = /^(text\/|application\/(json|ld\+json|xml|x-yaml|yaml|toml|javascript|typescript|x-sh|sql|x-tex))/;
-const TEXT_NAME = /\.(md|mdx|txt|csv|tsv|json|jsonl|ya?ml|toml|xml|html?|css|scss|[cm]?[jt]sx?|py|go|rs|rb|java|kt|swift|c|cc|cpp|h|hpp|cs|php|sh|bash|zsh|sql|ini|env|log|tex|proto|graphql)$/i;
-/** Which way a file goes with a message, or null when it cannot go. */
-export function kindOf(file) {
-    if (file.type.startsWith('image/'))
-        return 'image';
-    if (TEXT_TYPE.test(file.type) || TEXT_NAME.test(file.name))
-        return 'text';
-    return null;
+const OPEN = '<workspace-files>';
+const CLOSE = '</workspace-files>';
+/** A size as a person reads it. */
+export function weigh(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return '';
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    let n = bytes / 1024;
+    let u = 0;
+    while (n >= 1024 && u < units.length - 1) {
+        n /= 1024;
+        u++;
+    }
+    return `${n >= 10 ? Math.round(n) : n.toFixed(1)} ${units[u]}`;
 }
-function read(file, as) {
-    return new Promise((resolve, reject) => {
-        const reader = new FileReader();
-        reader.onload = () => resolve(String(reader.result ?? ''));
-        reader.onerror = () => reject(reader.error ?? new Error(`${file.name} could not be read.`));
-        if (as === 'url')
-            reader.readAsDataURL(file);
-        else
-            reader.readAsText(file);
-    });
+/** Text that cannot close the block it sits in. */
+const inert = (s) => s.split(CLOSE).join('</workspace files>');
+/**
+ * The message as sent: the words, then one block naming the files and holding
+ * what was read from them for this question.
+ *
+ * `why` says why there are no passages, when there are none — still indexing,
+ * stored without indexing, or the read failed — so the model says so rather
+ * than answering as though it had read the files.
+ */
+export function compose(text, carried, grounds, why) {
+    const words = text.trim();
+    const all = [...carried.attached, ...carried.reused];
+    if (!all.length)
+        return words;
+    const passages = grounds?.passages ?? [];
+    const lines = [
+        OPEN,
+        JSON.stringify({ attached: carried.attached, reused: carried.reused }),
+        `The person's workspace holds these files: ${all.map((f) => `${f.name} (${f.type || 'file'}, ${weigh(f.size)})`).join('; ')}.`,
+    ];
+    if (passages.length) {
+        lines.push(words
+            ? 'Answer from the passages below, read from those files for this question. Cite each claim with its number, like [1], and end with a Sources list giving each passage you cited as "[n] file › section › ¶n". If the passages do not answer the question, say what is missing.'
+            : 'The person sent these files without a question: say what each one is and what it covers, from the passages below, citing them like [1].');
+        passages.forEach((p, i) => {
+            lines.push('', `[${i + 1}] ${inert(p.cite)}`, inert(p.text.trim()));
+        });
+    }
+    else {
+        lines.push(`No passages could be read from them${why ? ` (${why})` : ''}: say so, and answer only what you can without them.`);
+    }
+    lines.push(CLOSE);
+    const block = lines.join('\n');
+    return words ? `${words}\n\n${block}` : block;
 }
-/** A file read for a message, or the sentence that says why it cannot go. */
-export async function admit(file) {
-    const kind = kindOf(file);
-    if (!kind)
-        return `${file.name}: only images and text files go with a message.`;
-    const max = kind === 'image' ? IMAGE_MAX : TEXT_MAX;
-    if (file.size > max)
-        return `${file.name} is larger than ${kind === 'image' ? '8 MB' : '256 KB'}.`;
+/** Takes the files block back off a turn, for drawing. */
+export function said(content) {
+    const at = content.startsWith(`${OPEN}\n`) ? 0 : content.lastIndexOf(`\n${OPEN}\n`);
+    if (at < 0)
+        return { text: content, carried: null, cites: [] };
+    const start = content.indexOf(OPEN, at) + OPEN.length + 1;
+    const end = content.indexOf(CLOSE, start);
+    const body = content.slice(start, end < 0 ? undefined : end);
+    const nl = body.indexOf('\n');
     try {
-        return { kind, data: await read(file, kind === 'image' ? 'url' : 'text') };
+        const head = JSON.parse(nl < 0 ? body : body.slice(0, nl));
+        const carried = {
+            attached: Array.isArray(head.attached) ? head.attached.filter(isRef) : [],
+            reused: Array.isArray(head.reused) ? head.reused.filter(isRef) : [],
+        };
+        const cites = [...body.matchAll(/^\[(\d+)\] (.+)$/gm)].map((m) => m[2]);
+        return { text: content.slice(0, at).trimEnd(), carried, cites };
     }
     catch {
-        return `${file.name} could not be read.`;
+        return { text: content, carried: null, cites: [] };
     }
 }
-/** A fence longer than any run of backticks inside the words, so they cannot close it. */
-function fence(words) {
-    const longest = Math.max(0, ...(words.match(/`+/g) ?? []).map((run) => run.length));
-    return '`'.repeat(Math.max(3, longest + 1));
+function isRef(v) {
+    const r = v;
+    return !!r && typeof r.id === 'string' && typeof r.name === 'string';
 }
 /**
- * The message as sent: the words, then each text file fenced with its name as
- * the info string — the shape a model writes a file in, and the one the
- * column's Sources reads back out of the turn. With no words and no text file,
- * the images' names, so the turn says what it carries.
+ * Every file the conversation's turns have carried, once each, oldest first —
+ * what a later question in the same conversation reads again.
  */
-export function compose(text, files) {
-    const blocks = files
-        .filter((f) => f.kind === 'text')
-        .map((f) => {
-        const f3 = fence(f.data);
-        return `${f3}${f.name}\n${f.data.replace(/\n$/, '')}\n${f3}`;
-    });
-    const out = [text.trim(), ...blocks].filter(Boolean).join('\n\n');
-    return out || files.map((f) => f.name).join(', ');
+export function carriedIn(turns) {
+    const out = new Map();
+    for (const t of turns) {
+        if (t.role !== 'user' || typeof t.content !== 'string')
+            continue;
+        const c = said(t.content).carried;
+        for (const f of [...(c?.attached ?? []), ...(c?.reused ?? [])])
+            if (!out.has(f.id))
+                out.set(f.id, f);
+    }
+    return [...out.values()];
 }
-/** The images of a message, as the URIs @hanzo/ai's `send` takes. */
-export const images = (files) => files.filter((f) => f.kind === 'image').map((f) => f.data);
 /** A wire turn's parts — text and `image_url` — as the parts `@hanzo/ui/chat` draws. */
 export function partsOf(content) {
     const out = [];

package/dist/lib/files.d.ts

@@ -0,0 +1,162 @@
+/**
+ * WORKSPACE FILES — a dropped file goes to the org's own storage, is indexed
+ * there, and is asked about by reference.
+ *
+ * The bytes never ride a chat request and never pass through the API: a small
+ * file is one presigned PUT, a large one a multipart upload whose parts are
+ * presigned PUTs straight to Hanzo S3 (resumable — the store keeps the parts it
+ * has, and a second attempt sends only the rest). The file then lands in the
+ * workspace's Drive bucket, is registered with knowledge (`/v1/knowledge/files`)
+ * and indexed in three layers on the platform's durable queue: its table of
+ * contents, passages cut inside its sections, and a graph to the other files.
+ *
+ * A chat turn carries the file's REFERENCE — id, name, type, size — and the
+ * passages `retrieve` reads for the question, each citing file › section › ¶n.
+ */
+import type { HttpClient } from '@hanzo/ai';
+/** The HTTP half of an `@hanzo/ai` client: all this module needs. */
+export interface Api {
+    http: Pick<HttpClient, 'json'>;
+}
+/** A workspace file as knowledge records it. */
+export interface WorkFile {
+    id: string;
+    name: string;
+    type: string;
+    size: number;
+    bucket: string;
+    key: string;
+    status: 'queued' | 'indexing' | 'ready' | 'stored' | 'failed';
+    stage?: 'extract' | 'toc' | 'passages' | 'embed' | 'graph';
+    error?: string;
+    chars?: number;
+    clipped?: boolean;
+    sections?: number;
+    passages?: number;
+    embedded?: number;
+    parent?: string;
+}
+/** What a chat message carries of a file: enough to name it and ask about it. */
+export interface FileRef {
+    id: string;
+    name: string;
+    type: string;
+    size: number;
+}
+export declare const refOf: (f: Pick<WorkFile, 'id' | 'name' | 'type' | 'size'>) => FileRef;
+/** A file's ingest has ended, one way or the other. */
+export declare const settled: (f: WorkFile) => boolean;
+/** A file can be asked about: its passages are written, even while it embeds. */
+export declare const askable: (f: WorkFile) => boolean;
+/** The name a bucket takes from its workspace: a DNS-safe slug, at most 40. */
+export declare const slug: (name: string) => string;
+export declare function workspace(api: Api, org: string): Promise<string>;
+/** Runs `work` over `items`, at most `n` at a time, and settles when all have. */
+export declare function pool<T>(items: readonly T[], n: number, work: (item: T) => Promise<void>): Promise<void>;
+/** Files over this go up in parts. */
+export declare const MULTIPART_AT: number;
+/**
+ * Uploads a file to bucket/key, reporting the fraction sent. A large file goes
+ * in parts; one that was interrupted — a dropped connection, a reload — resumes
+ * from the parts the store already holds.
+ */
+export declare function upload(api: Api, bucket: string, key: string, file: File, progress: (fraction: number) => void, signal?: AbortSignal): Promise<void>;
+/** Registers an uploaded object as a workspace file and queues its ingest. */
+export declare const register: (api: Api, bucket: string, key: string) => Promise<WorkFile>;
+/** One file's record, with how far its ingest has got. */
+export declare const fileOf: (api: Api, id: string) => Promise<WorkFile>;
+/** The files of one bucket, for Drive's index state. */
+export declare const filesIn: (api: Api, bucket: string) => Promise<WorkFile[]>;
+/** Removes a file from the index; the object stays where it is. */
+export declare const forget: (api: Api, id: string) => Promise<unknown>;
+/**
+ * Polls a file until its ingest settles, calling `seen` with each new record.
+ * Answers the last record; stops early when `signal` aborts.
+ */
+export declare function follow(api: Api, id: string, seen: (f: WorkFile) => void, signal?: AbortSignal): Promise<WorkFile>;
+/**
+ * Waits, at most `ms`, for each file to have passages to read or to settle,
+ * and answers what the index last said of each.
+ */
+export declare function readable(api: Api, list: readonly WorkFile[], ms: number): Promise<WorkFile[]>;
+/** Where a file is under a key: the chat's folder, with a dropped folder's own path kept. */
+export declare const chatKey: (file: File) => string;
+/**
+ * Every file in a drop, folders walked: a dropped folder arrives as entries, not
+ * files, and each file found under it keeps its path (`relative`).
+ */
+export declare function dropped(dt: DataTransfer): Promise<File[]>;
+/** One passage, with where it is. */
+export interface Passage {
+    file: {
+        id: string;
+        name: string;
+        type: string;
+        bucket: string;
+        key: string;
+    };
+    section: {
+        id: number;
+        title: string;
+        path: string;
+    };
+    part: number;
+    text: string;
+    cite: string;
+    score: number;
+    via: 'search' | 'toc' | 'graph';
+    why?: string;
+}
+/** What `retrieve` grounds an answer in. */
+export interface Grounds {
+    sections: {
+        file: Passage['file'];
+        section: Passage['section'];
+        summary?: string;
+    }[];
+    passages: Passage[];
+    picked: 'model' | 'search';
+    degraded?: boolean;
+}
+/** ToC-first retrieval: the sections a model picks from the files' tables of contents, their passages, and the graph's. */
+export declare const retrieve: (api: Api, query: string, files: string[], limit?: number) => Promise<Grounds>;
+/** Passages of the org's files that match, for Drive's search. */
+export declare const search: (api: Api, query: string, limit?: number) => Promise<{
+    passages: Passage[];
+}>;
+/** One node of a file's table of contents. */
+export interface TocEntry {
+    id: number;
+    parent: number;
+    level: number;
+    title: string;
+    summary?: string;
+    size: number;
+    synthetic?: boolean;
+}
+export declare const toc: (api: Api, id: string) => Promise<{
+    file: WorkFile;
+    sections: TocEntry[];
+}>;
+/** One section, opened. */
+export interface Opened {
+    file: Passage['file'];
+    section: Passage['section'];
+    summary?: string;
+    text: string;
+    children: TocEntry[];
+    links: {
+        file: Passage['file'];
+        section: Passage['section'];
+        kind: string;
+        label: string;
+    }[];
+    entities: {
+        name: string;
+        kind: string;
+        files: number;
+    }[];
+}
+export declare const section: (api: Api, id: string, n: number) => Promise<Opened>;
+/** A signed download address for a file's bytes. */
+export declare const download: (api: Api, bucket: string, key: string) => Promise<string>;

package/dist/lib/files.js

@@ -0,0 +1,289 @@
+/**
+ * WORKSPACE FILES — a dropped file goes to the org's own storage, is indexed
+ * there, and is asked about by reference.
+ *
+ * The bytes never ride a chat request and never pass through the API: a small
+ * file is one presigned PUT, a large one a multipart upload whose parts are
+ * presigned PUTs straight to Hanzo S3 (resumable — the store keeps the parts it
+ * has, and a second attempt sends only the rest). The file then lands in the
+ * workspace's Drive bucket, is registered with knowledge (`/v1/knowledge/files`)
+ * and indexed in three layers on the platform's durable queue: its table of
+ * contents, passages cut inside its sections, and a graph to the other files.
+ *
+ * A chat turn carries the file's REFERENCE — id, name, type, size — and the
+ * passages `retrieve` reads for the question, each citing file › section › ¶n.
+ */
+export const refOf = (f) => ({ id: f.id, name: f.name, type: f.type, size: f.size });
+/** A file's ingest has ended, one way or the other. */
+export const settled = (f) => f.status === 'ready' || f.status === 'stored' || f.status === 'failed';
+/** A file can be asked about: its passages are written, even while it embeds. */
+export const askable = (f) => f.status === 'ready' || (f.status === 'indexing' && (f.stage === 'embed' || f.stage === 'graph') && (f.passages ?? 0) > 0);
+/** The name a bucket takes from its workspace: a DNS-safe slug, at most 40. */
+export const slug = (name) => name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40)
+    .replace(/-+$/, '') || 'workspace';
+const objects = (bucket) => `/v1/s3/buckets/${encodeURIComponent(bucket)}`;
+/**
+ * THE WORKSPACE'S BUCKET: the one named for the org, made on first use. Drive
+ * opens it by default, so what a chat stores is where Drive looks.
+ */
+const buckets = new Map();
+export function workspace(api, org) {
+    const name = slug(org);
+    let found = buckets.get(name);
+    if (!found) {
+        found = (async () => {
+            const out = await api.http.json({ path: '/v1/s3/buckets' });
+            if (!(out?.buckets ?? []).some((b) => b.name === name)) {
+                await api.http.json({ method: 'POST', path: '/v1/s3/buckets', body: { name } }).catch((e) => {
+                    // Two tabs racing the first upload both try to make it; the loser's 409 is the bucket existing.
+                    if (!/409|exist/i.test(String(e?.message ?? e)))
+                        throw e;
+                });
+            }
+            return name;
+        })();
+        buckets.set(name, found);
+        found.catch(() => buckets.delete(name));
+    }
+    return found;
+}
+/** One PUT of a body to a presigned URL, reporting bytes sent. */
+function put(url, body, type, sent, signal) {
+    return new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        xhr.open('PUT', url);
+        if (type)
+            xhr.setRequestHeader('Content-Type', type);
+        xhr.upload.onprogress = (e) => sent(e.loaded);
+        xhr.onload = () => (xhr.status >= 200 && xhr.status < 300 ? (sent(body.size), resolve()) : reject(new Error(`the store answered ${xhr.status}`)));
+        xhr.onerror = () => reject(new Error('the upload was interrupted'));
+        xhr.onabort = () => reject(new DOMException('aborted', 'AbortError'));
+        signal?.addEventListener('abort', () => xhr.abort(), { once: true });
+        xhr.send(body);
+    });
+}
+/** Runs `work` over `items`, at most `n` at a time, and settles when all have. */
+export async function pool(items, n, work) {
+    let next = 0;
+    const lane = async () => {
+        while (next < items.length)
+            await work(items[next++]);
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(n, items.length)) }, lane));
+}
+/** Files over this go up in parts. */
+export const MULTIPART_AT = 8 * 1024 * 1024;
+/** How many parts are in flight at once. */
+const LANES = 4;
+const resumeKey = (bucket, key, file) => `hanzo.upload.${bucket}/${key}/${file.size}/${file.lastModified}`;
+function remembered(k) {
+    try {
+        return window.localStorage.getItem(k);
+    }
+    catch {
+        return null;
+    }
+}
+function remember(k, id) {
+    try {
+        if (id)
+            window.localStorage.setItem(k, id);
+        else
+            window.localStorage.removeItem(k);
+    }
+    catch {
+        // A private window keeps no resume point; the upload still goes.
+    }
+}
+/**
+ * Uploads a file to bucket/key, reporting the fraction sent. A large file goes
+ * in parts; one that was interrupted — a dropped connection, a reload — resumes
+ * from the parts the store already holds.
+ */
+export async function upload(api, bucket, key, file, progress, signal) {
+    const type = file.type || undefined;
+    if (file.size < MULTIPART_AT) {
+        const grant = await api.http.json({ method: 'POST', path: `${objects(bucket)}/objects`, body: { bucket, key } });
+        if (!grant?.url)
+            throw new Error('The store issued no upload address.');
+        await put(grant.url, file, type, (n) => progress(file.size ? n / file.size : 1), signal);
+        return;
+    }
+    const rk = resumeKey(bucket, key, file);
+    // The resume point is the upload id and the part size it was cut at: a part
+    // the store holds is only the same part when it is cut at the same size.
+    const [had, cut] = (remembered(rk) ?? '').split(' ');
+    let upload = had || null;
+    let partSize = Number(cut) || 16 * 1024 * 1024;
+    const done = new Map();
+    if (upload) {
+        try {
+            const had = await api.http.json({
+                path: `${objects(bucket)}/uploads/${encodeURIComponent(upload)}`,
+                query: { key },
+            });
+            for (const p of had?.parts ?? [])
+                done.set(p.part, p.size);
+        }
+        catch {
+            upload = null;
+        }
+    }
+    if (!upload) {
+        const started = await api.http.json({
+            method: 'POST',
+            path: `${objects(bucket)}/uploads`,
+            body: { bucket, key, type },
+        });
+        upload = started.upload;
+        partSize = started.partSize || partSize;
+        remember(rk, `${upload} ${partSize}`);
+    }
+    const id = upload;
+    const count = Math.max(1, Math.ceil(file.size / partSize));
+    const sent = new Map();
+    for (const [n, size] of done)
+        sent.set(n, size);
+    const report = () => progress([...sent.values()].reduce((a, b) => a + b, 0) / file.size);
+    report();
+    const todo = [];
+    for (let n = 1; n <= count; n++) {
+        const want = Math.min(partSize, file.size - (n - 1) * partSize);
+        if (done.get(n) !== want)
+            todo.push(n);
+    }
+    const urls = new Map();
+    const mint = async (from) => {
+        const batch = todo.slice(from, from + 32).filter((n) => !urls.has(n));
+        if (!batch.length)
+            return;
+        const out = await api.http.json({
+            method: 'POST',
+            path: `${objects(bucket)}/uploads/${encodeURIComponent(id)}/parts`,
+            body: { bucket, upload: id, key, parts: batch },
+        });
+        for (const u of out?.urls ?? [])
+            urls.set(u.part, u.url);
+    };
+    let next = 0;
+    const lane = async () => {
+        while (next < todo.length) {
+            if (signal?.aborted)
+                throw new DOMException('aborted', 'AbortError');
+            const i = next++;
+            const n = todo[i];
+            if (!urls.has(n))
+                await mint(i);
+            const body = file.slice((n - 1) * partSize, Math.min(file.size, n * partSize));
+            for (let attempt = 0;; attempt++) {
+                try {
+                    await put(urls.get(n), body, undefined, (b) => (sent.set(n, b), report()), signal);
+                    break;
+                }
+                catch (e) {
+                    if (e?.name === 'AbortError' || attempt === 3)
+                        throw e;
+                    // A URL minted minutes ago may have expired: mint the part again.
+                    urls.delete(n);
+                    await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+                    await mint(i);
+                }
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(LANES, todo.length || 1) }, lane));
+    await api.http.json({
+        method: 'POST',
+        path: `${objects(bucket)}/uploads/${encodeURIComponent(id)}/complete`,
+        body: { bucket, upload: id, key },
+    });
+    remember(rk, null);
+}
+/** Registers an uploaded object as a workspace file and queues its ingest. */
+export const register = (api, bucket, key) => api.http.json({ method: 'POST', path: '/v1/knowledge/files', body: { bucket, key } });
+/** One file's record, with how far its ingest has got. */
+export const fileOf = (api, id) => api.http.json({ path: `/v1/knowledge/files/${encodeURIComponent(id)}` });
+/** The files of one bucket, for Drive's index state. */
+export const filesIn = (api, bucket) => api.http
+    .json({ path: '/v1/knowledge/files', query: { bucket, limit: 1000 } })
+    .then((out) => out?.files ?? []);
+/** Removes a file from the index; the object stays where it is. */
+export const forget = (api, id) => api.http.json({ method: 'DELETE', path: `/v1/knowledge/files/${encodeURIComponent(id)}` });
+/**
+ * Polls a file until its ingest settles, calling `seen` with each new record.
+ * Answers the last record; stops early when `signal` aborts.
+ */
+export async function follow(api, id, seen, signal) {
+    let wait = 800;
+    for (;;) {
+        const f = await fileOf(api, id);
+        seen(f);
+        if (settled(f) || signal?.aborted)
+            return f;
+        await new Promise((r) => setTimeout(r, wait));
+        wait = Math.min(wait * 1.4, 5000);
+    }
+}
+/**
+ * Waits, at most `ms`, for each file to have passages to read or to settle,
+ * and answers what the index last said of each.
+ */
+export async function readable(api, list, ms) {
+    const until = Date.now() + ms;
+    let now = list.slice();
+    while (Date.now() < until && now.some((f) => !askable(f) && !settled(f))) {
+        await new Promise((r) => setTimeout(r, 1200));
+        now = await Promise.all(now.map((f) => (askable(f) || settled(f) ? f : fileOf(api, f.id).catch(() => f))));
+    }
+    return now;
+}
+/** Where a file is under a key: the chat's folder, with a dropped folder's own path kept. */
+export const chatKey = (file) => {
+    const rel = file.relative || file.webkitRelativePath || file.name;
+    return `chat/${rel.replace(/^\/+/, '').replace(/\.\.+\//g, '')}`;
+};
+/**
+ * Every file in a drop, folders walked: a dropped folder arrives as entries, not
+ * files, and each file found under it keeps its path (`relative`).
+ */
+export async function dropped(dt) {
+    const items = Array.from(dt.items ?? []).filter((i) => i.kind === 'file');
+    const entries = items.map((i) => i.webkitGetAsEntry?.() ?? null);
+    if (!entries.some((e) => e?.isDirectory))
+        return Array.from(dt.files ?? []);
+    const out = [];
+    const walk = async (entry, prefix) => {
+        if (entry.isFile) {
+            const file = await new Promise((res, rej) => entry.file(res, rej));
+            Object.defineProperty(file, 'relative', { value: prefix + file.name });
+            out.push(file);
+            return;
+        }
+        const reader = entry.createReader();
+        for (;;) {
+            const batch = await new Promise((res, rej) => reader.readEntries(res, rej));
+            if (!batch.length)
+                break;
+            for (const child of batch)
+                await walk(child, `${prefix}${entry.name}/`);
+        }
+    };
+    for (const e of entries)
+        if (e)
+            await walk(e, '');
+    return out;
+}
+/** ToC-first retrieval: the sections a model picks from the files' tables of contents, their passages, and the graph's. */
+export const retrieve = (api, query, files, limit = 8) => api.http.json({ method: 'POST', path: '/v1/knowledge/files/retrieve', body: { query, files, limit } });
+/** Passages of the org's files that match, for Drive's search. */
+export const search = (api, query, limit = 12) => api.http.json({ method: 'POST', path: '/v1/knowledge/files/search', body: { query, limit } });
+export const toc = (api, id) => api.http.json({ path: `/v1/knowledge/files/${encodeURIComponent(id)}/toc` });
+export const section = (api, id, n) => api.http.json({ path: `/v1/knowledge/files/${encodeURIComponent(id)}/sections/${n}` });
+/** A signed download address for a file's bytes. */
+export const download = (api, bucket, key) => api.http
+    .json({ path: `${objects(bucket)}/objects/${key.split('/').map(encodeURIComponent).join('/')}` })
+    .then((g) => g.url);