@coffer-org/server 2.6.0 → 2.7.0

package/dist/auth-api.js

@@ -75,9 +75,18 @@ export async function registerAuthApi(app) {
             return reply.code(409).send({ error: 'already_setup' });
         const body = (req.body ?? {});
         if (!body.login || !body.password || !body.displayName) {
-            return reply.code(422).send({ issues: [{ field: !body.login ? 'login' : !body.password ? 'password' : 'displayName', code: 'required' }] });
+            return reply
+                .code(422)
+                .send({
+                issues: [{ field: !body.login ? 'login' : !body.password ? 'password' : 'displayName', code: 'required' }],
+            });
         }
-        const user = await createUser({ login: body.login, password: body.password, displayName: body.displayName, role: 'admin' });
+        const user = await createUser({
+            login: body.login,
+            password: body.password,
+            displayName: body.displayName,
+            role: 'admin',
+        });
         const { raw } = await createSession(user.id, SESSION_TTL_MS);
         setCookie(reply, raw, SESSION_TTL_MS / 1000);
         return publicUser(user);
@@ -129,7 +138,12 @@ export async function registerAuthApi(app) {
         if (!body.login || !body.password || !body.displayName || (body.role !== 'admin' && body.role !== 'member')) {
             return reply.code(422).send({ issues: [{ field: 'login', code: 'required' }] });
         }
-        const user = await createUser({ login: body.login, password: body.password, displayName: body.displayName, role: body.role });
+        const user = await createUser({
+            login: body.login,
+            password: body.password,
+            displayName: body.displayName,
+            role: body.role,
+        });
         return publicUser(user);
     });
     app.patch('/api/auth/users/:id', async (req, reply) => {

package/dist/auth-store.js

@@ -1,7 +1,13 @@
 import { getEm } from "./db.js";
 import { hashPassword, generateToken, hashToken } from "./auth-crypto.js";
 function toAuthUser(row) {
-    return { id: row.id, login: row.login, displayName: row.display_name, role: row.role, disabled: Boolean(row.disabled) };
+    return {
+        id: row.id,
+        login: row.login,
+        displayName: row.display_name,
+        role: row.role,
+        disabled: Boolean(row.disabled),
+    };
 }
 export async function countUsers() {
     const em = getEm().fork();

package/dist/background-scheduler.js

@@ -22,7 +22,10 @@ export function makeScheduler(opts = {}) {
     function arm(cb, ms) {
         if (stopped)
             return;
-        const h = setTimer(() => { timers.delete(h); cb(); }, ms);
+        const h = setTimer(() => {
+            timers.delete(h);
+            cb();
+        }, ms);
         timers.add(h);
     }
     function enqueue(task) {
@@ -51,7 +54,11 @@ export function makeScheduler(opts = {}) {
         const timeoutMs = task.timeoutMs ?? defaultTimeoutMs;
         let to;
         const timeout = new Promise((resolve) => {
-            to = setTimer(() => { timers.delete(to); log.warn(`${task.name}: timed out after ${timeoutMs}ms`); resolve(); }, timeoutMs);
+            to = setTimer(() => {
+                timers.delete(to);
+                log.warn(`${task.name}: timed out after ${timeoutMs}ms`);
+                resolve();
+            }, timeoutMs);
             timers.add(to);
         });
         try {
@@ -62,7 +69,10 @@ export function makeScheduler(opts = {}) {
             catch (e) {
                 runPromise = Promise.reject(e);
             }
-            await Promise.race([runPromise.catch((e) => log.warn(`${task.name}: ${e.message}`)), timeout]);
+            await Promise.race([
+                runPromise.catch((e) => log.warn(`${task.name}: ${e.message}`)),
+                timeout,
+            ]);
         }
         finally {
             clearTimer(to);
@@ -70,13 +80,17 @@ export function makeScheduler(opts = {}) {
         }
     }
     return {
-        register(task) { tasks.push(task); },
+        register(task) {
+            tasks.push(task);
+        },
         start() {
             if (started || stopped)
                 return;
             started = true;
-            arm(() => { for (const t of tasks)
-                enqueue(t); }, startupDelayMs);
+            arm(() => {
+                for (const t of tasks)
+                    enqueue(t);
+            }, startupDelayMs);
         },
         stop() {
             stopped = true;

package/dist/collection-io.js

@@ -47,14 +47,17 @@ export async function writeAt(tx, prefix, fields, parentId, collections) {
             await deleteAt(tx, table, childFields, ex.id);
         await tx.nativeDelete(table, { parent_id: parentId });
         const sKeys = scalarKeys(childFields);
-        const jsonKeys = new Set(fieldEntries(childFields).filter(([, fm]) => isJsonStored(fm)).map(([k]) => k));
+        const jsonKeys = new Set(fieldEntries(childFields)
+            .filter(([, fm]) => isJsonStored(fm))
+            .map(([k]) => k));
         let position = 0;
         for (const r of rows) {
             const flatR = flattenEmbeddedAt(childFields, r);
             const picked = {};
             for (const k of sKeys)
                 if (flatR[k] !== undefined)
-                    picked[k] = jsonKeys.has(k) && flatR[k] !== null && typeof flatR[k] === 'object' ? JSON.stringify(flatR[k]) : flatR[k];
+                    picked[k] =
+                        jsonKeys.has(k) && flatR[k] !== null && typeof flatR[k] === 'object' ? JSON.stringify(flatR[k]) : flatR[k];
             const child = tx.create(table, { parent_id: parentId, position, ...picked });
             await tx.flush();
             const childId = child.id;

package/dist/embed-openai.js

@@ -29,7 +29,8 @@ function parseErrorBody(body) {
 }
 function classifyEmbeddingFailure(status, code, detail) {
     const marker = `${code ?? ''} ${detail ?? ''}`.toLowerCase();
-    if (status === 402 || /insufficient_quota|billing|payment_required|payment required|hard.?limit|quota exceeded/.test(marker))
+    if (status === 402 ||
+        /insufficient_quota|billing|payment_required|payment required|hard.?limit|quota exceeded/.test(marker))
         return 'billing';
     if (status === 401 || status === 403)
         return 'auth';

package/dist/embeddings.d.ts

@@ -25,6 +25,7 @@ export declare function cosine(a: ArrayLike<number>, b: ArrayLike<number>): numb
 export declare function twoPassSearch(rows: EmbeddingRow[], queryVec: ArrayLike<number>, k: number, opts?: {
     coarseDims?: number;
     poolMinFactor?: number;
+    shelfKeys?: Set<string>;
 }): EmbeddingHit[];
 export declare function upsertEmbedding(args: {
     shelfKey: string;
@@ -34,5 +35,7 @@ export declare function upsertEmbedding(args: {
     model: string;
 }): Promise<void>;
 export declare function deleteEmbedding(shelfKey: string, recordId: number): Promise<void>;
-export declare function searchEmbeddings(queryVec: number[], k: number): Promise<EmbeddingHit[]>;
+export declare function searchEmbeddings(queryVec: number[], k: number, opts?: {
+    shelfKeys?: Set<string>;
+}): Promise<EmbeddingHit[]>;
 export declare function listEventsSince(lastId: number, limit: number): Promise<EventRow[]>;

package/dist/embeddings.js

@@ -12,7 +12,10 @@ async function loadCache() {
     const em = getEm().fork();
     const rows = (await em.find('_Embedding', {}));
     cache = rows.map((r) => ({
-        shelfKey: r.shelf_key, recordId: r.record_id, snippet: r.snippet, full: decodeVector(r.vector),
+        shelfKey: r.shelf_key,
+        recordId: r.record_id,
+        snippet: r.snippet,
+        full: decodeVector(r.vector),
     }));
     return cache;
 }
@@ -30,7 +33,9 @@ export async function migrateEmbeddingVectorsToBlob() {
     const em = getEm().fork();
     if (dialectOf(em) !== 'sqlite')
         return 0;
-    const [{ n }] = (await em.getConnection().execute("SELECT count(*) AS n FROM _embeddings WHERE typeof(vector) = 'text'"));
+    const [{ n }] = (await em
+        .getConnection()
+        .execute("SELECT count(*) AS n FROM _embeddings WHERE typeof(vector) = 'text'"));
     if (n === 0)
         return 0;
     const rows = (await em.find('_Embedding', {}));
@@ -59,7 +64,8 @@ export function cosine(a, b) {
     return denom ? dot / denom : 0;
 }
 export function twoPassSearch(rows, queryVec, k, opts = {}) {
-    const N = rows.length;
+    const scope = opts.shelfKeys ? rows.filter((r) => opts.shelfKeys.has(r.shelfKey)) : rows;
+    const N = scope.length;
     if (N === 0)
         return [];
     const coarseDims = opts.coarseDims ?? COARSE_DIMS;
@@ -68,13 +74,13 @@ export function twoPassSearch(rows, queryVec, k, opts = {}) {
     const m = Math.min(coarseDims, qFull.length);
     const qSmall = qFull.subarray(0, m);
     const poolSize = Math.min(N, Math.max(k * poolMinFactor, Math.ceil(N * 0.1)));
-    const pool = rows
+    const pool = scope
         .map((r, i) => ({ i, d: 1 - cosine(r.full.subarray(0, m), qSmall) }))
         .sort((a, b) => a.d - b.d)
         .slice(0, poolSize);
     return pool
         .map(({ i }) => {
-        const r = rows[i];
+        const r = scope[i];
         return { shelfKey: r.shelfKey, recordId: r.recordId, snippet: r.snippet, distance: 1 - cosine(r.full, qFull) };
     })
         .sort((a, b) => a.distance - b.distance)
@@ -99,11 +105,14 @@ export async function deleteEmbedding(shelfKey, recordId) {
     await em.nativeDelete('_Embedding', { shelf_key: shelfKey, record_id: recordId });
     invalidateEmbeddingCache();
 }
-export async function searchEmbeddings(queryVec, k) {
-    return twoPassSearch(await loadCache(), queryVec, k);
+export async function searchEmbeddings(queryVec, k, opts = {}) {
+    return twoPassSearch(await loadCache(), queryVec, k, opts);
 }
 export async function listEventsSince(lastId, limit) {
     const em = getEm().fork();
-    const rows = (await em.find('_Event', { id: { $gt: lastId } }, { orderBy: { id: 'ASC' }, limit }));
+    const rows = (await em.find('_Event', { id: { $gt: lastId } }, {
+        orderBy: { id: 'ASC' },
+        limit,
+    }));
     return rows;
 }

package/dist/entity-schema.d.ts

@@ -18,6 +18,7 @@ export declare const EmbeddingSchema: EntitySchema<any, never, import("@mikro-or
 export declare const PluginStateSchema: EntitySchema<any, never, import("@mikro-orm/core").EntityCtor<any>>;
 export declare const RecordActivitySchema: EntitySchema<any, never, import("@mikro-orm/core").EntityCtor<any>>;
 export declare const ThreadMessageSchema: EntitySchema<any, never, import("@mikro-orm/core").EntityCtor<any>>;
+export declare const ThreadStateSchema: EntitySchema<any, never, import("@mikro-orm/core").EntityCtor<any>>;
 export declare function buildPluginEntities(plugins: PluginManifest[]): EntitySchema[];
 export declare const MsgLogSchema: EntitySchema<any, never, import("@mikro-orm/core").EntityCtor<any>>;
 export declare const UserSchema: EntitySchema<any, never, import("@mikro-orm/core").EntityCtor<any>>;

package/dist/entity-schema.js

@@ -180,6 +180,17 @@ export const ThreadMessageSchema = new EntitySchema({
         reply_to_id: { type: 'text', nullable: true },
     },
 });
+export const ThreadStateSchema = new EntitySchema({
+    name: '_ThreadState',
+    tableName: '_thread_state',
+    properties: {
+        connector: { type: 'text', primary: true },
+        chat_id: { type: 'text', primary: true },
+        agent_id: { type: 'text', nullable: true },
+        preset_id: { type: 'text', nullable: true },
+        updated_at: { type: 'text' },
+    },
+});
 export function buildPluginEntities(plugins) {
     return plugins.flatMap((p) => [
         ...(p.libraries ?? []).flatMap((v) => v.shelves.flatMap((m) => [buildEntitySchema(m), ...buildCollectionEntities(m)])),
@@ -202,6 +213,8 @@ export const MsgLogSchema = new EntitySchema({
         tokens_in: { type: 'integer', nullable: true },
         tokens_out: { type: 'integer', nullable: true },
         ms: { type: 'integer', nullable: true },
+        agent_id: { type: 'text', nullable: true },
+        preset_id: { type: 'text', nullable: true },
     },
 });
 export const UserSchema = new EntitySchema({
@@ -280,9 +293,20 @@ export const OAuthTokenSchema = new EntitySchema({
     },
 });
 export const systemEntities = [
-    EventSchema, PluginRowSchema, MigrationRowSchema, SeedRowSchema,
-    EmbeddingSchema, PluginStateSchema, RecordActivitySchema, MsgLogSchema,
-    UserSchema, SessionSchema, ApiTokenSchema,
-    OAuthClientSchema, OAuthCodeSchema, OAuthTokenSchema,
+    EventSchema,
+    PluginRowSchema,
+    MigrationRowSchema,
+    SeedRowSchema,
+    EmbeddingSchema,
+    PluginStateSchema,
+    RecordActivitySchema,
+    MsgLogSchema,
+    UserSchema,
+    SessionSchema,
+    ApiTokenSchema,
+    OAuthClientSchema,
+    OAuthCodeSchema,
+    OAuthTokenSchema,
     ThreadMessageSchema,
+    ThreadStateSchema,
 ];

package/dist/extend-io.js

@@ -2,6 +2,7 @@ import { getExtendsFor } from "./registry-context.js";
 import { buildExtendZodPartial } from '@coffer-org/sdk/extend';
 import { upsertExtendRecord, deleteExtendRecord, getExtendRecord } from "./extend-table.js";
 import { toIssue, ValidationError } from "./mutate.js";
+import { normalizeFileFieldsAt } from "./file-fields.js";
 export function splitBody(body) {
     const raw = (body ?? {});
     const base = {};
@@ -48,7 +49,11 @@ export async function saveExtends(em, library, shelf, baseId, extData) {
             continue;
         const parsed = buildExtendZodPartial(e).safeParse(data);
         if (parsed.success && Object.keys(parsed.data).length > 0) {
-            await upsertExtendRecord(em, e, baseId, parsed.data);
+            const row = parsed.data;
+            const fileIssues = normalizeFileFieldsAt(e.fields, row);
+            if (fileIssues.length)
+                throw new ValidationError(fileIssues);
+            await upsertExtendRecord(em, e, baseId, row);
         }
     }
 }

package/dist/extend-table.js

@@ -1,5 +1,7 @@
 import { getEm } from "./db.js";
-import { splitAt, writeAt, readAt, readAtMany, deleteAt } from "./collection-io.js";
+import { splitAt, writeAt, readAt, readAtMany, deleteAt, flattenEmbeddedAt, nestEmbeddedAt } from "./collection-io.js";
+import { encodeJsonAt } from "./mutate.js";
+import { encodeTemporalAt, decodeTemporalAt } from "./temporal.js";
 import { chunk } from "./batch.js";
 import { selectRows } from "./read-rows.js";
 export function extendEntityName(e) {
@@ -11,8 +13,9 @@ export async function getExtendRecord(e, baseId, em) {
     const [flat] = (await selectRows(fork, name, { base_id: baseId }, { limit: 1 }));
     if (!flat)
         return undefined;
+    const decoded = nestEmbeddedAt(e.fields, decodeTemporalAt(e.fields, flat));
     const collections = await readAt(fork, name, e.fields, baseId);
-    return { ...flat, ...collections };
+    return { ...decoded, ...collections };
 }
 export async function getExtendRecords(e, baseIds, em) {
     const out = new Map();
@@ -30,14 +33,16 @@ export async function getExtendRecords(e, baseIds, em) {
     const collectionsById = await readAtMany(fork, name, e.fields, presentIds);
     for (const flat of flats) {
         const id = Number(flat.base_id);
-        out.set(id, { ...flat, ...(collectionsById.get(id) ?? {}) });
+        const decoded = nestEmbeddedAt(e.fields, decodeTemporalAt(e.fields, flat));
+        out.set(id, { ...decoded, ...(collectionsById.get(id) ?? {}) });
     }
     return out;
 }
 export async function upsertExtendRecord(em, e, baseId, data) {
     const name = extendEntityName(e);
     const { base, collections } = splitAt(e.fields, data);
-    await em.upsert(name, { base_id: baseId, ...base });
+    const flat = encodeJsonAt(e.fields, encodeTemporalAt(e.fields, flattenEmbeddedAt(e.fields, base)));
+    await em.upsert(name, { base_id: baseId, ...flat });
     await writeAt(em, name, e.fields, baseId, collections);
 }
 export async function deleteExtendRecord(em, e, baseId) {

package/dist/file-fields.d.ts

@@ -1,6 +1,8 @@
 import type { ShelfDef } from '@coffer-org/sdk/shelf';
+import type { LayoutEl } from '@coffer-org/sdk/fields';
 import type { ValidationIssue } from './mutate.ts';
 export declare function mimeForName(name: string): string | undefined;
 export declare function touchesFileFields(m: ShelfDef, input: unknown): boolean;
 export declare function dropUnchangedFileFields(m: ShelfDef, input: Record<string, unknown>, stored: Record<string, unknown>): Record<string, unknown>;
+export declare function normalizeFileFieldsAt(fields: LayoutEl[], data: Record<string, unknown>): ValidationIssue[];
 export declare function normalizeFileFields(m: ShelfDef, data: Record<string, unknown>): ValidationIssue[];

package/dist/file-fields.js

@@ -1,6 +1,6 @@
 import { statSync } from 'node:fs';
 import { join } from 'node:path';
-import { fieldEntries } from '@coffer-org/sdk/shelf';
+import { fieldEntries, collectionGroups } from '@coffer-org/sdk/shelf';
 import { jsonValue } from '@coffer-org/sdk/fields';
 import { uploadsDir } from "./uploads.js";
 const MIME_BY_EXT = {
@@ -87,9 +87,9 @@ export function dropUnchangedFileFields(m, input, stored) {
     }
     return out ?? input;
 }
-export function normalizeFileFields(m, data) {
+function normalizeLevel(fields, data, path) {
     const issues = [];
-    for (const [key, f] of fieldEntries(m.fields)) {
+    for (const [key, f] of fieldEntries(fields)) {
         if (f.prim !== 'file')
             continue;
         if (!(key in data))
@@ -101,21 +101,40 @@ export function normalizeFileFields(m, data) {
         const isArray = Array.isArray(parsed);
         const items = (isArray ? parsed : [parsed]);
         const out = [];
+        let failed = false;
         for (const it of items) {
             if (typeof it !== 'object' || it === null || typeof it.name !== 'string') {
-                issues.push({ field: key, code: 'file_not_uploaded', path: [key] });
+                issues.push({ field: key, code: 'file_not_uploaded', path: [...path, key] });
+                failed = true;
                 continue;
             }
             const resolved = resolveEntry(it);
             if (!resolved) {
-                issues.push({ field: key, code: 'file_not_uploaded', params: { name: it.name }, path: [key] });
+                issues.push({ field: key, code: 'file_not_uploaded', params: { name: it.name }, path: [...path, key] });
+                failed = true;
                 continue;
             }
             out.push(resolved);
         }
-        if (issues.length)
+        if (failed)
             continue;
         data[key] = isArray ? out : out[0];
     }
+    for (const c of collectionGroups(fields)) {
+        const rows = data[c.key];
+        if (!Array.isArray(rows))
+            continue;
+        rows.forEach((row, i) => {
+            if (typeof row !== 'object' || row === null)
+                return;
+            issues.push(...normalizeLevel(c.group.fields, row, [...path, c.key, i]));
+        });
+    }
     return issues;
 }
+export function normalizeFileFieldsAt(fields, data) {
+    return normalizeLevel(fields, data, []);
+}
+export function normalizeFileFields(m, data) {
+    return normalizeFileFieldsAt(m.fields, data);
+}

package/dist/index.js

@@ -24,7 +24,7 @@ import { baseUrl } from "./public-url.js";
 import { discoverPluginAssets, discoverRuntime } from "./plugin-discovery.js";
 import { checkLatestVersion, resolveUpdateTarget, resolveAllUpdateTargets, resolveBaseTargets, resolveRuntimeTarget, runNpmInstall, } from "./plugin-updates.js";
 import { buildClientSchema } from "./schema-api.js";
-import { recordList, recordListPage, isPagedRequest, recordGet, recordCreate, recordUpdate, recordDelete, recordRestore, recordPurge, recordTrashList, MAX_PAGE, UnknownShelfError, } from "./records-api.js";
+import { recordList, recordListPage, isPagedRequest, recordGet, recordCreate, recordUpdate, recordDelete, recordRestore, recordPurge, recordTrashList, MAX_PAGE, UnknownShelfError, ensureSingle, SingleShelfError, } from "./records-api.js";
 import { maskTree, preserveTree } from "./field-masking.js";
 import { writePluginSettings } from "./settings-write.js";
 import { rootLogger, getLogger } from "./log.js";
@@ -125,6 +125,8 @@ async function guard(reply, fn) {
     catch (e) {
         if (e instanceof ValidationError)
             return reply.code(422).send({ error: 'validation', issues: e.issues });
+        if (e instanceof SingleShelfError)
+            return reply.code(409).send({ error: 'single_shelf', message: e.message });
         if (e instanceof NotFoundError)
             return reply.code(404).send({ error: 'not_found' });
         app.log.error(e);
@@ -481,6 +483,15 @@ app.patch('/api/:library/:shelf/:id/activity', async (req, reply) => {
         throw e;
     }
 });
+app.get('/api/:library/:shelf/single', async (req, reply) => {
+    const { library, shelf } = req.params;
+    const m = getShelf(library, shelf);
+    if (!m)
+        return reply.code(404).send({ error: 'unknown_shelf' });
+    if (!m.single)
+        return reply.code(404).send({ error: 'not_single_shelf' });
+    return maskRecordRow(library, shelf, await ensureSingle(library, shelf));
+});
 app.get('/api/:library/:shelf/:id', async (req, reply) => {
     const { library, shelf, id } = req.params;
     const rid = Number(id);
@@ -535,7 +546,10 @@ app.patch('/api/:library/:shelf/:id', (req, reply) => guard(reply, async () => {
                 const bk = `_extend_${def.id}`;
                 const sub = body[bk];
                 if (sub && typeof sub === 'object') {
-                    body = { ...body, [bk]: preserveTree(def.fields, sub, (exRecs[def.id] ?? {})) };
+                    body = {
+                        ...body,
+                        [bk]: preserveTree(def.fields, sub, (exRecs[def.id] ?? {})),
+                    };
                 }
             }
         }

package/dist/mcp-http.test-helpers.js

@@ -13,7 +13,10 @@ export async function freshMcpApp(opts = {}) {
     await orm.schema.update({ safe: false, dropTables: false });
     const app = Fastify();
     app.addHook('onRequest', async (req, reply) => {
-        const gated = req.url.startsWith('/api/') || req.url.startsWith('/uploads/') || req.url === '/mcp' || req.url.startsWith('/mcp?');
+        const gated = req.url.startsWith('/api/') ||
+            req.url.startsWith('/uploads/') ||
+            req.url === '/mcp' ||
+            req.url.startsWith('/mcp?');
         if (!gated)
             return;
         if (PUBLIC_API_PATHS.some((p) => req.url.startsWith(p)))

package/dist/mcp-local.js

@@ -1,5 +1,5 @@
 import { ValidationError, NotFoundError } from '@coffer-org/mcp/client';
-import { recordList, recordListPage, recordGet, recordCreate, recordUpdate, recordDelete, UnknownShelfError, recordTrashList, recordRestore, recordPurge, } from "./records-api.js";
+import { recordList, recordListPage, recordGet, recordCreate, recordUpdate, recordDelete, UnknownShelfError, recordTrashList, recordRestore, recordPurge, SingleShelfError, } from "./records-api.js";
 import { ValidationError as ServerValidationError } from "./mutate.js";
 import { buildClientSchema } from "./schema-api.js";
 export function mapError(e) {
@@ -7,6 +7,8 @@ export function mapError(e) {
         throw new ValidationError(e.issues ?? []);
     if (e instanceof UnknownShelfError)
         throw new NotFoundError('not_found');
+    if (e instanceof SingleShelfError)
+        throw new ValidationError([{ field: 'shelf', code: 'single_shelf', message: e.message }]);
     throw e;
 }
 export function splitListQuery(raw) {

package/dist/mcp-tools.d.ts

@@ -3,7 +3,7 @@ import { z } from 'zod';
 import { type ToolResult } from '@coffer-org/mcp';
 import { type AuthRole, type PluginHooks } from './plugin-hooks.ts';
 import { type Condition } from '@coffer-org/sdk/condition';
-import { type EmbeddingHit } from './embeddings.ts';
+import { type RagHit } from './rag-search.ts';
 export interface McpToolDef {
     server: string;
     bareName: string;
@@ -17,7 +17,7 @@ export interface McpToolDef {
 export interface RagDeps {
     embeddingApiKey: string;
 }
-export declare function formatHits(hits: EmbeddingHit[]): string;
+export declare function formatHits(hits: RagHit[]): string;
 export declare function resolveRagDeps(): Promise<RagDeps | null>;
 export declare function collectMcpTools(opts?: {
     rag?: RagDeps | null;
@@ -28,6 +28,19 @@ export declare function collectPluginInstructions(hooks?: Record<string, PluginH
     id: string;
     instructions: string;
 }[]>;
+type SingleShelf = {
+    library: string;
+    shelf: string;
+    claude: string;
+};
+export declare function collectSingleShelves(reg?: {
+    shelves: {
+        library: string;
+        shelf: string;
+        single?: boolean;
+        claude?: string;
+    }[];
+}): SingleShelf[];
 type LibraryPurpose = {
     id: string;
     agent: string;