threadshelf 1.2.0

package/dist/src/generation/quick-setup.js

@@ -0,0 +1,215 @@
+import { inspectHardware, judgeFit } from './hardware.js';
+import { defaultLlamaInstallRoot, findLlamaExecutables, installLlamaCpp, readInstalledSource, resolveLlamaRelease, sourceFromRelease, } from './llama-install.js';
+import { getCatalogModel, quantQualityTier, searchCatalogModels, TRUSTED_PUBLISHERS, } from './model-catalog.js';
+import { downloadModel, modelFilesPresent, planModelDownload, } from './model-download.js';
+import { createHash } from 'crypto';
+import { updateGenerationConfig } from './config.js';
+const CANDIDATE_LIMIT = 8;
+/**
+ * A stable identity for "what this plan will fetch": versions, digests and
+ * sizes, nothing else. Hardware readings and warnings are deliberately excluded
+ * — free VRAM drifts constantly and would invalidate a plan the user is still
+ * reading. The server compares this against the value the client approved before
+ * it downloads anything.
+ */
+export const quickSetupFingerprint = (plan) => {
+    const material = {
+        runtime: {
+            action: plan.runtime.action,
+            tag: plan.runtime.tag,
+            variant: plan.runtime.variant,
+            sha256: plan.runtime.sha256 ?? null,
+            companions: plan.runtime.companions.map((companion) => companion.sha256),
+        },
+        model: plan.model
+            ? {
+                action: plan.model.action,
+                repoId: plan.model.repoId,
+                quant: plan.model.quant,
+                totalBytes: plan.model.totalBytes,
+                files: plan.model.files.map((file) => file.sha256 ?? `size:${file.sizeBytes}`),
+            }
+            : null,
+        totalDownloadBytes: plan.totalDownloadBytes,
+    };
+    return createHash('sha256').update(JSON.stringify(material)).digest('hex').slice(0, 32);
+};
+export const quickSetupFingerprintMatches = (plan, approved) => typeof approved === 'string' &&
+    /^[a-f0-9]{32}$/.test(approved) &&
+    approved === quickSetupFingerprint(plan);
+const percentOf = (done, total) => total && total > 0 ? Math.min(100, Math.round((done / total) * 100)) : undefined;
+const findExistingInstall = async (variant, tag) => {
+    const executables = await findLlamaExecutables();
+    for (const executable of executables) {
+        // The install directory is `<root>/llama.cpp/<tag>-<flavor>`; matching on the
+        // recorded metadata is more reliable than parsing that path back apart.
+        const marker = executable.match(/^(.*[\\/]llama\.cpp[\\/][^\\/]+)[\\/]/);
+        if (!marker?.[1])
+            continue;
+        const installed = await readInstalledSource(marker[1]);
+        if (installed?.tag === tag && (installed.flavor ?? 'cpu') === variant)
+            return executable;
+    }
+    return undefined;
+};
+/**
+ * Picks the most-downloaded GGUF repository from a trusted publisher whose
+ * recommended quantisation fits the detected memory budget.
+ */
+export const chooseSetupModel = async (profile, fetchImpl = fetch) => {
+    const { models } = await searchCatalogModels({ limit: 40, sort: 'downloads', fetchImpl });
+    const candidates = models
+        .filter((model) => model.trustedPublisher && model.gated === false)
+        .slice(0, CANDIDATE_LIMIT);
+    for (const candidate of candidates) {
+        const detail = await getCatalogModel(candidate.id, fetchImpl).catch(() => null);
+        if (!detail)
+            continue;
+        // Best quality tier that fits, then the largest file within that tier. Going
+        // by size alone would happily pick a legacy `Q4_1` over a better `Q4_K_M`.
+        const fitting = detail.quants
+            .filter((quant) => quantQualityTier(quant.label) > 1 && judgeFit(quant.totalBytes, profile) === 'fits')
+            .sort((a, b) => quantQualityTier(b.label) - quantQualityTier(a.label) || b.totalBytes - a.totalBytes)[0];
+        if (fitting)
+            return { detail, quant: fitting.label };
+    }
+    return null;
+};
+export const buildQuickSetupPlan = async ({ variant, repoId, quant, releaseTag, fetchImpl = fetch, } = {}) => {
+    const hardware = await inspectHardware();
+    const warnings = [];
+    const chosenVariant = variant ?? (process.platform === 'darwin' ? 'cpu' : hardware.suggestedVariant);
+    const release = await resolveLlamaRelease({ tag: releaseTag, fetchImpl });
+    let source;
+    try {
+        source = sourceFromRelease(release, { variant: chosenVariant });
+    }
+    catch (error) {
+        // A GPU build may simply not exist for this platform in this release.
+        warnings.push(`${chosenVariant.toUpperCase()} build unavailable (${error instanceof Error ? error.message : 'unknown'}); falling back to CPU.`);
+        source = sourceFromRelease(release, { variant: 'cpu' });
+    }
+    const effectiveVariant = source.flavor ?? 'cpu';
+    const existingExecutable = await findExistingInstall(effectiveVariant, source.tag);
+    const runtime = {
+        action: existingExecutable ? 'reuse' : 'install',
+        variant: effectiveVariant,
+        tag: source.tag,
+        url: existingExecutable ? undefined : source.url,
+        sha256: existingExecutable ? undefined : source.sha256,
+        sizeBytes: existingExecutable ? undefined : source.sizeBytes,
+        companions: existingExecutable
+            ? []
+            : (source.companions ?? []).map((companion) => ({
+                url: companion.url,
+                sha256: companion.sha256,
+                sizeBytes: companion.sizeBytes,
+            })),
+        destination: defaultLlamaInstallRoot(),
+        executablePath: existingExecutable,
+        releaseUrl: source.releaseUrl,
+    };
+    let model;
+    const selection = repoId
+        ? { detail: await getCatalogModel(repoId, fetchImpl), quant }
+        : await chooseSetupModel(hardware, fetchImpl);
+    if (!selection) {
+        warnings.push('No catalog model matched the detected memory budget. Pick one manually from the model browser.');
+    }
+    else {
+        const downloadPlan = await planModelDownload({
+            repoId: selection.detail.id,
+            quant: selection.quant,
+            detail: selection.detail,
+            fetchImpl,
+        });
+        // A model already on disk must not be presented as a fresh multi-gigabyte
+        // transfer; the downloader would skip it anyway.
+        const present = await modelFilesPresent(downloadPlan);
+        model = {
+            action: present ? 'reuse' : 'download',
+            repoId: downloadPlan.repoId,
+            quant: downloadPlan.quant,
+            totalBytes: downloadPlan.totalBytes,
+            directory: downloadPlan.directory,
+            files: downloadPlan.files.map((file) => ({
+                url: file.url,
+                sha256: file.sha256,
+                sizeBytes: file.sizeBytes,
+            })),
+            license: downloadPlan.license,
+            contextLength: downloadPlan.contextLength,
+            fit: judgeFit(downloadPlan.totalBytes, hardware),
+        };
+        if (downloadPlan.requiresToken) {
+            warnings.push(`${downloadPlan.repoId} is gated and needs HF_TOKEN before it can download.`);
+        }
+    }
+    if (hardware.detectionSource === 'none') {
+        warnings.push('No accelerator detected. Generation will run on CPU.');
+    }
+    // The figure on the confirm button must cover every byte the run will fetch,
+    // runtime archive and companions included — not just the model.
+    const runtimeBytes = runtime.action === 'install'
+        ? (runtime.sizeBytes ?? 0) +
+            runtime.companions.reduce((sum, companion) => sum + (companion.sizeBytes ?? 0), 0)
+        : 0;
+    const plan = {
+        hardware,
+        runtime,
+        model,
+        totalDownloadBytes: runtimeBytes + (model?.action === 'download' ? model.totalBytes : 0),
+        warnings,
+        fingerprint: '',
+    };
+    return { ...plan, fingerprint: quickSetupFingerprint(plan) };
+};
+export const runQuickSetupPlan = async (plan, { onProgress, signal, fetchImpl = fetch, } = {}) => {
+    let executablePath = plan.runtime.executablePath;
+    if (plan.runtime.action === 'install') {
+        signal?.throwIfAborted();
+        onProgress?.({ step: 'runtime', phase: 'resolving' });
+        // The plan is re-resolved rather than trusted: a client must not be able to
+        // hand the server an arbitrary URL to fetch and execute.
+        const release = await resolveLlamaRelease({ tag: plan.runtime.tag, fetchImpl });
+        const source = sourceFromRelease(release, { variant: plan.runtime.variant });
+        const result = await installLlamaCpp(source, {
+            signal,
+            onProgress: (progress) => onProgress?.({
+                step: 'runtime',
+                phase: progress.phase,
+                percent: percentOf(progress.downloadedBytes ?? 0, progress.totalBytes),
+            }),
+        });
+        executablePath = result.executablePath;
+    }
+    if (!executablePath)
+        throw new Error('llama.cpp setup did not produce an executable');
+    let modelPath;
+    if (plan.model) {
+        signal?.throwIfAborted();
+        onProgress?.({ step: 'model', phase: 'resolving' });
+        const downloadPlan = await planModelDownload({
+            repoId: plan.model.repoId,
+            quant: plan.model.quant,
+            fetchImpl,
+        });
+        const result = await downloadModel(downloadPlan, {
+            signal,
+            onProgress: (progress) => onProgress?.({
+                step: 'model',
+                phase: progress.phase,
+                file: 'file' in progress ? progress.file : undefined,
+                percent: progress.phase === 'downloading'
+                    ? percentOf(progress.downloadedBytes, progress.totalBytes)
+                    : undefined,
+            }),
+        });
+        modelPath = result.primaryPath;
+    }
+    // Pin the executable so later runs do not re-discover a different build.
+    await updateGenerationConfig({ llamaCpp: { executablePath } }).catch(() => undefined);
+    onProgress?.({ step: 'done', executablePath, modelPath });
+    return { executablePath, modelPath };
+};
+export const trustedSetupPublishers = TRUSTED_PUBLISHERS;

package/dist/src/generation/registry.js

@@ -0,0 +1,23 @@
+import { createLlamaCppProvider } from './providers/llama-cpp.js';
+import { createOpenRouterProvider } from './providers/openrouter.js';
+const providers = new Map([
+    ['llama-cpp', createLlamaCppProvider()],
+    ['openrouter', createOpenRouterProvider()],
+]);
+export const getGenerationProvider = (id) => {
+    const provider = providers.get(id);
+    if (!provider)
+        throw new Error(`Unknown generation provider: ${id}`);
+    return provider;
+};
+export const listGenerationProviders = () => [...providers.values()];
+export const setGenerationProviderForTests = (id, provider) => {
+    const previous = providers.get(id);
+    providers.set(id, provider);
+    return () => {
+        if (previous)
+            providers.set(id, previous);
+        else
+            providers.delete(id);
+    };
+};

package/dist/src/generation/service.js

@@ -0,0 +1,100 @@
+import { ValidationError } from '../validation.js';
+import { persistGenerationError } from './error-log.js';
+import { getGenerationProvider } from './registry.js';
+const PROVIDERS = new Set(['llama-cpp', 'openrouter']);
+const ROLES = new Set(['system', 'user', 'assistant']);
+const MAX_MESSAGES = 500;
+const MAX_CONTEXT_CHARS = 4_000_000;
+export const validateChatRequest = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new ValidationError('Invalid chat request');
+    }
+    const raw = value;
+    if (typeof raw.provider !== 'string' || !PROVIDERS.has(raw.provider)) {
+        throw new ValidationError('Invalid provider', { field: 'provider' });
+    }
+    if (typeof raw.model !== 'string' || !raw.model.trim() || raw.model.length > 4096) {
+        throw new ValidationError('Invalid model', { field: 'model' });
+    }
+    if (!Array.isArray(raw.messages) ||
+        raw.messages.length === 0 ||
+        raw.messages.length > MAX_MESSAGES) {
+        throw new ValidationError(`Invalid messages: expected 1-${MAX_MESSAGES} entries`, {
+            field: 'messages',
+        });
+    }
+    let totalChars = 0;
+    const messages = raw.messages.map((entry, index) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            throw new ValidationError(`Invalid messages[${index}]`, { field: 'messages' });
+        }
+        const message = entry;
+        if (typeof message.role !== 'string' || !ROLES.has(message.role)) {
+            throw new ValidationError(`Invalid messages[${index}].role`, { field: 'messages' });
+        }
+        if (typeof message.content !== 'string' || !message.content.trim()) {
+            throw new ValidationError(`Invalid messages[${index}].content`, { field: 'messages' });
+        }
+        totalChars += message.content.length;
+        return {
+            role: message.role,
+            content: message.content,
+        };
+    });
+    if (totalChars > MAX_CONTEXT_CHARS) {
+        throw new ValidationError(`Conversation context exceeds ${MAX_CONTEXT_CHARS} characters`, {
+            field: 'messages',
+        });
+    }
+    const temperature = raw.temperature === undefined ? 0.7 : Number(raw.temperature);
+    if (!Number.isFinite(temperature) || temperature < 0 || temperature > 2) {
+        throw new ValidationError('Invalid temperature: expected 0-2', { field: 'temperature' });
+    }
+    const maxTokens = raw.maxTokens === undefined ? 1024 : Number(raw.maxTokens);
+    if (!Number.isInteger(maxTokens) || maxTokens < 1 || maxTokens > 32768) {
+        throw new ValidationError('Invalid maxTokens: expected integer from 1 to 32768', {
+            field: 'maxTokens',
+        });
+    }
+    if (raw.openRouterZdr !== undefined && typeof raw.openRouterZdr !== 'boolean') {
+        throw new ValidationError('Invalid openRouterZdr: expected boolean', {
+            field: 'openRouterZdr',
+        });
+    }
+    if (raw.persistDiagnostics !== undefined && typeof raw.persistDiagnostics !== 'boolean') {
+        throw new ValidationError('Invalid persistDiagnostics: expected boolean', {
+            field: 'persistDiagnostics',
+        });
+    }
+    return {
+        provider: raw.provider,
+        model: raw.model.trim(),
+        messages,
+        temperature,
+        maxTokens,
+        openRouterZdr: raw.provider === 'openrouter' ? raw.openRouterZdr : undefined,
+        persistDiagnostics: raw.persistDiagnostics,
+    };
+};
+export const generateChat = async (input, signal) => {
+    const request = validateChatRequest(input);
+    try {
+        return await getGenerationProvider(request.provider).chat(request, signal);
+    }
+    catch (error) {
+        if (!signal?.aborted)
+            await persistGenerationError(request, error).catch(() => undefined);
+        throw error;
+    }
+};
+export const generateChatStream = async (input, onDelta, signal) => {
+    const request = validateChatRequest(input);
+    try {
+        return await getGenerationProvider(request.provider).chatStream(request, onDelta, signal);
+    }
+    catch (error) {
+        if (!signal?.aborted)
+            await persistGenerationError(request, error).catch(() => undefined);
+        throw error;
+    }
+};

package/dist/src/generation/threads.js

@@ -0,0 +1,311 @@
+import { randomUUID } from 'node:crypto';
+import { getStoredThreads, listThreadSummaries, deleteStoredFile, replaceThreadsForFile, StoredThreadWriteError, updateStoredThread, updateStoredThreadFromCurrent, renameStoredThread, indexStoredFile, } from '../store.js';
+import { validateTurns, ValidationError } from '../validation.js';
+import { addManualCollection } from '../services/collections.js';
+import { portableModelLabel } from '../model-label.js';
+export const THREADSHELF_CHAT_COLLECTION = 'threadshelf_conversations';
+const LEGACY_THREADSHELF_CHAT_COLLECTION = '__threadshelf_chats';
+const THREADSHELF_CHAT_SOURCE_PREFIX = 'threadshelf://chat/';
+const THREAD_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+// Longest chat title we persist, for both auto-derived and user-set names.
+export const CHAT_TITLE_MAX = 200;
+export class ThreadShelfChatNotFoundError extends Error {
+    constructor() {
+        super('ThreadShelf chat not found');
+        this.name = 'ThreadShelfChatNotFoundError';
+    }
+}
+export class ThreadShelfChatBusyError extends Error {
+    constructor() {
+        super('This ThreadShelf chat is already generating a response');
+        this.name = 'ThreadShelfChatBusyError';
+    }
+}
+const activeChats = new Set();
+const acquireGenerationKey = (key) => {
+    if (activeChats.has(key))
+        throw new ThreadShelfChatBusyError();
+    activeChats.add(key);
+    return () => activeChats.delete(key);
+};
+export const acquireThreadShelfChat = (id) => {
+    const normalized = assertThreadShelfChatId(id);
+    return acquireGenerationKey(`chat\0${normalized}`);
+};
+export const assertThreadShelfChatId = (value) => {
+    if (typeof value !== 'string' || !THREAD_ID_PATTERN.test(value)) {
+        throw new ThreadShelfChatNotFoundError();
+    }
+    return value.toLowerCase();
+};
+const sourceFileForId = (id) => `${THREADSHELF_CHAT_SOURCE_PREFIX}${id}`;
+const idFromSourceFile = (sourceFile) => {
+    if (!sourceFile.startsWith(THREADSHELF_CHAT_SOURCE_PREFIX))
+        return null;
+    const id = sourceFile.slice(THREADSHELF_CHAT_SOURCE_PREFIX.length);
+    return THREAD_ID_PATTERN.test(id) ? id.toLowerCase() : null;
+};
+const parseTurns = (row) => {
+    return validateTurns(JSON.parse(row.turnsJson));
+};
+const markCreatedChatTurns = (turns) => turns.map((turn) => ({
+    ...turn,
+    ...(turn.model ? { model: portableModelLabel(turn.model) } : {}),
+    createdInThreadShelf: true,
+}));
+const toChat = (row) => {
+    const id = idFromSourceFile(row.sourceFile);
+    if (!id || !row.createdInThreadShelf)
+        throw new ThreadShelfChatNotFoundError();
+    const createdAt = row.threadCreatedAt || row.ingestedAt;
+    return {
+        id,
+        title: row.title || 'New chat',
+        createdAt,
+        updatedAt: row.lastTurnAt || row.ingestedAt || createdAt,
+        turnCount: row.turnCount,
+        model: portableModelLabel(row.lastModel) ||
+            portableModelLabel([...parseTurns(row)].reverse().find((turn) => turn.model)?.model) ||
+            undefined,
+        createdInThreadShelf: true,
+        turns: markCreatedChatTurns(parseTurns(row)),
+    };
+};
+const conversationFromChat = (chat) => ({
+    key: chat.id,
+    title: chat.title,
+    turns: chat.turns,
+    createdInThreadShelf: true,
+    threadCreatedAt: chat.createdAt,
+});
+const insertChat = async (chat) => {
+    await replaceThreadsForFile(THREADSHELF_CHAT_COLLECTION, sourceFileForId(chat.id), 'threadshelf', [conversationFromChat(chat)]);
+};
+const updateChat = async (chat) => {
+    await updateStoredThread(THREADSHELF_CHAT_COLLECTION, sourceFileForId(chat.id), 'threadshelf', conversationFromChat(chat));
+};
+const indexWithStatus = async (target) => {
+    try {
+        const indexedChunks = await indexStoredFile(target.collection, target.sourceFile);
+        return { saved: true, indexed: true, indexedChunks };
+    }
+    catch (error) {
+        const warning = `Conversation was saved, but semantic indexing failed and will be retried: ${error instanceof Error ? error.message : String(error)}`;
+        console.warn('[generation:index]', warning);
+        // The pending marker was written atomically with the turns. The server's
+        // recovery worker retries it from current storage, including after restart.
+        return { saved: true, indexed: false, indexedChunks: 0, warning };
+    }
+};
+const migrateLegacyChat = async (row) => {
+    const chat = toChat(row);
+    await addManualCollection(THREADSHELF_CHAT_COLLECTION);
+    await insertChat(chat);
+    await replaceThreadsForFile(LEGACY_THREADSHELF_CHAT_COLLECTION, row.sourceFile, 'threadshelf', []);
+    await indexWithStatus({
+        collection: THREADSHELF_CHAT_COLLECTION,
+        sourceFile: row.sourceFile,
+    });
+    return chat;
+};
+// This title is persisted, so truncating here discards the text permanently.
+// Keep it whole up to the same ceiling `renameChat` enforces; shortening for
+// display is the UI's job (see `.r-title` in `_search.scss`).
+export const titleFromPrompt = (prompt) => {
+    const compact = prompt.replace(/\s+/g, ' ').trim();
+    return compact.length > CHAT_TITLE_MAX ? `${compact.slice(0, CHAT_TITLE_MAX - 1)}…` : compact;
+};
+export const createThreadShelfChat = async (title = 'New chat', initialTurns = []) => {
+    const now = new Date().toISOString();
+    const turns = markCreatedChatTurns(initialTurns.map((turn) => ({ ...turn, createdAt: turn.createdAt ?? now })));
+    const firstPrompt = turns.find((turn) => typeof turn.user === 'string')?.user;
+    const model = [...turns].reverse().find((turn) => turn.model)?.model;
+    const chat = {
+        id: randomUUID(),
+        title: title === 'New chat' && firstPrompt ? titleFromPrompt(firstPrompt) : title,
+        createdAt: now,
+        updatedAt: now,
+        turnCount: turns.length,
+        model,
+        createdInThreadShelf: true,
+        turns,
+    };
+    await addManualCollection(THREADSHELF_CHAT_COLLECTION);
+    await insertChat(chat);
+    if (turns.length) {
+        await indexWithStatus({
+            collection: THREADSHELF_CHAT_COLLECTION,
+            sourceFile: sourceFileForId(chat.id),
+        });
+    }
+    return chat;
+};
+export const renameThreadShelfChat = async (value, title) => {
+    const trimmed = title.replace(/\s+/g, ' ').trim();
+    // A bare Error would surface as a 502; an empty title is a client mistake.
+    if (!trimmed)
+        throw new ValidationError('A chat title cannot be empty', { field: 'title' });
+    const chat = await getThreadShelfChat(value);
+    return toChat(await renameStoredThread(THREADSHELF_CHAT_COLLECTION, sourceFileForId(chat.id), chat.id, trimmed.slice(0, CHAT_TITLE_MAX)));
+};
+export const deleteThreadShelfChat = async (value) => {
+    const release = acquireThreadShelfChat(value);
+    try {
+        const chat = await getThreadShelfChat(value);
+        // A crash during legacy migration can leave both copies. Remove the fallback
+        // first so deleting the primary copy cannot make the legacy one reappear.
+        await deleteStoredFile(LEGACY_THREADSHELF_CHAT_COLLECTION, sourceFileForId(chat.id));
+        await deleteStoredFile(THREADSHELF_CHAT_COLLECTION, sourceFileForId(chat.id));
+    }
+    finally {
+        release();
+    }
+};
+export const getThreadShelfChat = async (value) => {
+    const id = assertThreadShelfChatId(value);
+    const sourceFile = sourceFileForId(id);
+    const rows = await getStoredThreads(THREADSHELF_CHAT_COLLECTION, sourceFile);
+    const row = rows.find((candidate) => candidate.conversationKey === id);
+    if (row) {
+        const chat = toChat(row);
+        if (parseTurns(row).some((turn) => turn.createdInThreadShelf !== true)) {
+            await updateChat(chat);
+            await indexWithStatus({
+                collection: THREADSHELF_CHAT_COLLECTION,
+                sourceFile,
+            });
+        }
+        return chat;
+    }
+    const legacyRows = await getStoredThreads(LEGACY_THREADSHELF_CHAT_COLLECTION, sourceFile);
+    const legacy = legacyRows.find((candidate) => candidate.conversationKey === id);
+    if (!legacy)
+        throw new ThreadShelfChatNotFoundError();
+    return migrateLegacyChat(legacy);
+};
+export const listThreadShelfChats = async () => {
+    const [legacyRows, rows] = await Promise.all([
+        listThreadSummaries(LEGACY_THREADSHELF_CHAT_COLLECTION),
+        listThreadSummaries(THREADSHELF_CHAT_COLLECTION),
+    ]);
+    const chats = new Map();
+    for (const row of [...legacyRows, ...rows]) {
+        const id = idFromSourceFile(row.sourceFile);
+        if (!id || !row.createdInThreadShelf)
+            continue;
+        const createdAt = row.threadCreatedAt;
+        chats.set(id, {
+            id,
+            title: row.title || 'New chat',
+            createdAt,
+            updatedAt: row.lastTurnAt || createdAt,
+            turnCount: row.turnCount,
+            model: portableModelLabel(row.lastModel) || undefined,
+            createdInThreadShelf: true,
+        });
+    }
+    return [...chats.values()].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+};
+export const appendThreadShelfChatExchange = async (value, prompt, response) => {
+    const chat = await getThreadShelfChat(value);
+    const now = new Date().toISOString();
+    const provenance = {
+        createdAt: now,
+        createdInThreadShelf: true,
+        generationProvider: response.provider,
+    };
+    await updateStoredThreadFromCurrent(THREADSHELF_CHAT_COLLECTION, sourceFileForId(chat.id), chat.id, (current) => {
+        const turns = [
+            ...parseTurns(current),
+            { user: prompt, model: response.model, ...provenance },
+        ];
+        if (response.reasoning?.trim())
+            turns.push({ thinking: response.reasoning, model: response.model, ...provenance });
+        turns.push({ ai: response.content, model: response.model, ...provenance });
+        return {
+            provider: 'threadshelf',
+            conversation: {
+                key: current.conversationKey,
+                title: current.turnCount === 0 && current.title === 'New chat'
+                    ? titleFromPrompt(prompt)
+                    : current.title,
+                turns,
+                createdInThreadShelf: true,
+                threadCreatedAt: current.threadCreatedAt,
+            },
+        };
+    });
+    const persistence = await indexWithStatus({
+        collection: THREADSHELF_CHAT_COLLECTION,
+        sourceFile: sourceFileForId(chat.id),
+    });
+    const updated = await getThreadShelfChat(chat.id);
+    return { chat: updated, persistence };
+};
+export const acquireStoredThreadGeneration = (target) => target.collection === THREADSHELF_CHAT_COLLECTION && idFromSourceFile(target.sourceFile)
+    ? acquireThreadShelfChat(idFromSourceFile(target.sourceFile))
+    : acquireGenerationKey(`stored\0${target.collection}\0${target.sourceFile}\0${target.conversationKey}`);
+export const resolveStoredThreadGenerationTarget = async (collection, sourceFile, conversationKey) => {
+    const rows = await getStoredThreads(collection === 'all' ? null : collection, sourceFile);
+    const candidates = conversationKey
+        ? rows.filter((row) => row.conversationKey === conversationKey)
+        : rows;
+    const row = [...candidates].sort((a, b) => b.ingestedAt.localeCompare(a.ingestedAt))[0];
+    if (!row)
+        return null;
+    return {
+        collection: row.collection,
+        sourceFile: row.sourceFile,
+        conversationKey: row.conversationKey,
+        title: row.title,
+        provider: row.provider,
+        createdInThreadShelf: row.createdInThreadShelf,
+        threadCreatedAt: row.threadCreatedAt,
+        turns: parseTurns(row),
+    };
+};
+export const appendStoredThreadExchange = async (target, prompt, response) => {
+    const now = new Date().toISOString();
+    const provenance = {
+        createdAt: now,
+        createdInThreadShelf: true,
+        generationProvider: response.provider,
+    };
+    try {
+        await updateStoredThreadFromCurrent(target.collection, target.sourceFile, target.conversationKey, (current) => {
+            const currentTurns = parseTurns(current);
+            const turns = [
+                ...currentTurns,
+                { user: prompt, model: response.model, ...provenance },
+            ];
+            if (response.reasoning?.trim()) {
+                turns.push({ thinking: response.reasoning, model: response.model, ...provenance });
+            }
+            turns.push({ ai: response.content, model: response.model, ...provenance });
+            return {
+                provider: current.provider || target.provider,
+                conversation: {
+                    key: current.conversationKey,
+                    title: current.title || target.title,
+                    turns,
+                    createdInThreadShelf: current.createdInThreadShelf,
+                    threadCreatedAt: current.threadCreatedAt,
+                },
+            };
+        });
+    }
+    catch (error) {
+        if (!(error instanceof StoredThreadWriteError))
+            throw error;
+        return {
+            saved: false,
+            indexed: false,
+            indexedChunks: 0,
+            warning: `${error.message}. The generated response remains available in this browser session but was not added to the archive.`,
+        };
+    }
+    return indexWithStatus({
+        collection: target.collection,
+        sourceFile: target.sourceFile,
+    });
+};

package/dist/src/generation/types.js

@@ -0,0 +1 @@
+export {};