@coffer-org/server 6.0.0 → 7.1.0

package/dist/embed-openai.d.ts

@@ -14,11 +14,11 @@ export declare class OpenAIEmbeddingError extends Error {
     });
 }
 export declare function embeddingFailureMessage(error: unknown): string;
-export declare function embedBatch(texts: string[], apiKey: string, fetchImpl?: typeof fetch): Promise<{
+export declare function embedBatch(texts: string[], apiKey: string, fetchImpl?: typeof fetch, signal?: AbortSignal): Promise<{
     vectors: number[][];
     tokens: number;
 }>;
-export declare function embedOne(text: string, apiKey: string, fetchImpl?: typeof fetch): Promise<{
+export declare function embedOne(text: string, apiKey: string, fetchImpl?: typeof fetch, signal?: AbortSignal): Promise<{
     vector: number[];
     tokens: number;
 }>;

package/dist/embed-openai.js

@@ -54,7 +54,7 @@ export function embeddingFailureMessage(error) {
             return `OpenAI embeddings are unavailable${error.status == null ? '' : ` (HTTP ${error.status})`}. RAG will retry; records are still saved.`;
     }
 }
-export async function embedBatch(texts, apiKey, fetchImpl = fetch) {
+export async function embedBatch(texts, apiKey, fetchImpl = fetch, signal) {
     if (texts.length === 0)
         return { vectors: [], tokens: 0 };
     if (!apiKey)
@@ -65,6 +65,7 @@ export async function embedBatch(texts, apiKey, fetchImpl = fetch) {
             method: 'POST',
             headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
             body: JSON.stringify({ model: EMBED_MODEL, input: texts, dimensions: EMBED_DIM }),
+            ...(signal ? { signal } : {}),
         });
     }
     catch (cause) {
@@ -79,8 +80,8 @@ export async function embedBatch(texts, apiKey, fetchImpl = fetch) {
     const vectors = [...json.data].sort((a, b) => a.index - b.index).map((d) => d.embedding);
     return { vectors, tokens: json.usage?.total_tokens ?? 0 };
 }
-export async function embedOne(text, apiKey, fetchImpl = fetch) {
-    const { vectors, tokens } = await embedBatch([text], apiKey, fetchImpl);
+export async function embedOne(text, apiKey, fetchImpl = fetch, signal) {
+    const { vectors, tokens } = await embedBatch([text], apiKey, fetchImpl, signal);
     const vector = vectors[0];
     if (!vector)
         throw new Error('embeddings: empty response');

package/dist/embeddings.d.ts

@@ -39,3 +39,4 @@ export declare function searchEmbeddings(queryVec: number[], k: number, opts?: {
     shelfKeys?: Set<string>;
 }): Promise<EmbeddingHit[]>;
 export declare function listEventsSince(lastId: number, limit: number): Promise<EventRow[]>;
+export declare function latestEventId(): Promise<number>;

package/dist/embeddings.js

@@ -116,3 +116,11 @@ export async function listEventsSince(lastId, limit) {
     }));
     return rows;
 }
+export async function latestEventId() {
+    const em = getEm().fork();
+    const rows = (await em.find('_Event', {}, {
+        orderBy: { id: 'DESC' },
+        limit: 1,
+    }));
+    return rows[0]?.id ?? 0;
+}

package/dist/index.js

@@ -22,6 +22,7 @@ import { registerPluginUserApi, registerPluginAdminApi } from "./plugin-user-api
 import { registerAuthApi, resolveRequestUser, requireAdmin, PUBLIC_API_PATHS } from "./auth-api.js";
 import { registerMcpHttp } from "./mcp-http.js";
 import { registerOAuthApi } from "./oauth-api.js";
+import { registerInstanceApi } from "./instance-api.js";
 import { baseUrl } from "./public-url.js";
 import { discoverPluginAssets, discoverRuntime } from "./plugin-discovery.js";
 import { checkLatestVersion, resolveUpdateTarget, resolveAllUpdateTargets, resolveBaseTargets, resolveRuntimeTarget, runNpmInstall, } from "./plugin-updates.js";
@@ -146,6 +147,7 @@ app.get('/health', async (_req, reply) => {
         return reply.code(503).send({ status: 'db_unavailable' });
     }
 });
+registerInstanceApi(app);
 let librariesPayload = null;
 app.get('/api/libraries', async (req, reply) => {
     if (!librariesPayload) {

package/dist/instance-api.d.ts

@@ -0,0 +1,5 @@
+import type { FastifyInstance } from 'fastify';
+export interface InstanceFacts {
+    origin: string;
+}
+export declare function registerInstanceApi(app: FastifyInstance): void;

package/dist/instance-api.js

@@ -0,0 +1,4 @@
+import { baseUrl } from "./public-url.js";
+export function registerInstanceApi(app) {
+    app.get('/api/instance', async (req) => ({ origin: await baseUrl(req) }));
+}

package/dist/mcp-tools.d.ts

@@ -13,7 +13,7 @@ export interface McpToolDef {
     inputSchema: z.ZodRawShape;
     scope: 'crud' | 'plugin' | 'rag' | 'settings' | 'upload';
     role: AuthRole;
-    handler: (args: Record<string, unknown>) => Promise<ToolResult>;
+    handler: (args: Record<string, unknown>, signal?: AbortSignal) => Promise<ToolResult>;
 }
 export interface RagDeps {
     embeddingApiKey: string;
@@ -73,6 +73,12 @@ export declare function collectLibraryPurposes(reg?: {
 }, locales?: LocaleResolver): LibraryPurpose[];
 export declare function siteSection(siteUrl: string): Promise<string | null>;
 export declare function buildDomainSections(locales?: LocaleResolver): Promise<string[]>;
+export interface StarterHint {
+    id: string;
+    text: string;
+    hash: string;
+}
+export declare const CORE_STARTER_HINT: string;
 export declare function collectStarterHints(hooks?: Record<string, PluginHooks>, emFactory?: () => EntityManager, reg?: {
     libraries: {
         meta: {
@@ -81,9 +87,6 @@ export declare function collectStarterHints(hooks?: Record<string, PluginHooks>,
             starterHint?: string;
         };
     }[];
-}, locales?: LocaleResolver): Promise<{
-    combined: string;
-    hash: string;
-}>;
+}, locales?: LocaleResolver): Promise<StarterHint[]>;
 export declare function buildMcpInstructions(sections: string[]): string;
 export {};

package/dist/mcp-tools.js

@@ -130,9 +130,9 @@ export async function collectMcpTools(opts = {}) {
                 inputSchema: t.inputSchema,
                 scope: 'plugin',
                 role: t.role ?? 'member',
-                handler: async (args) => {
+                handler: async (args, signal) => {
                     try {
-                        const data = await t.handler(args, pluginCtx(id, getEm().fork()));
+                        const data = await t.handler(args, pluginCtx(id, getEm().fork(), signal));
                         return ok(data);
                     }
                     catch (e) {
@@ -162,7 +162,7 @@ export async function collectMcpTools(opts = {}) {
             },
             scope: 'rag',
             role: 'member',
-            handler: async (args) => {
+            handler: async (args, signal) => {
                 const library = args.library;
                 const shelf = args.shelf;
                 if (shelf && !library) {
@@ -180,7 +180,7 @@ export async function collectMcpTools(opts = {}) {
                 }
                 let vector = null;
                 try {
-                    vector = (await embedOne(args.query, embeddingApiKey)).vector;
+                    vector = (await embedOne(args.query, embeddingApiKey, undefined, signal)).vector;
                 }
                 catch (e) {
                     log.warn(`embedding failed, text-only search — ${embeddingFailureMessage(e)}`);
@@ -351,16 +351,23 @@ export async function buildDomainSections(locales) {
     const rules = (await collectPluginInstructions()).map(({ id, instructions }) => `## ${id}\n${instructions}`);
     return [dataModel, ...(overview ? [overview] : []), ...(singleSection ? [singleSection] : []), ...rules];
 }
+export const CORE_STARTER_HINT = 'what this Coffer instance itself holds — which libraries are present and what kinds of ' +
+    'questions the stored data can answer';
+function hintHash(text) {
+    return createHash('sha1').update(text).digest('hex');
+}
 export async function collectStarterHints(hooks = pluginHooks, emFactory = () => getEm().fork(), reg, locales) {
-    const parts = [];
+    const out = [{ id: 'system', text: CORE_STARTER_HINT, hash: hintHash(CORE_STARTER_HINT) }];
     for (const [id, h] of Object.entries(hooks)) {
         const hint = h.agent?.starterHint;
         if (hint == null)
             continue;
         try {
-            const text = typeof hint === 'function' ? await hint(pluginCtx(id, emFactory())) : hint;
-            if (text)
-                parts.push(`- ${id}: ${text}`);
+            const hintText = typeof hint === 'function' ? await hint(pluginCtx(id, emFactory())) : hint;
+            if (hintText) {
+                const text = `${id}: ${hintText}`;
+                out.push({ id: `plugin:${id}`, text, hash: hintHash(text) });
+            }
         }
         catch (e) {
             log.warn(`plugin ${id}: starterHint skipped — ${e.message}`);
@@ -380,11 +387,10 @@ export async function collectStarterHints(hooks = pluginHooks, emFactory = () =>
         if (!v.meta.starterHint)
             continue;
         const name = v.meta.label ? i18n.resolve(v.meta.label) : undefined;
-        parts.push(`- ${v.meta.id}${name ? ` ("${name}")` : ''}: ${v.meta.starterHint}`);
+        const text = `${v.meta.id}${name ? ` ("${name}")` : ''}: ${v.meta.starterHint}`;
+        out.push({ id: `library:${v.meta.id}`, text, hash: hintHash(text) });
     }
-    const combined = parts.join('\n');
-    const hash = createHash('sha1').update(combined).digest('hex');
-    return { combined, hash };
+    return out;
 }
 export function buildMcpInstructions(sections) {
     const base = [

package/dist/orchestrator/starter-sources.d.ts

@@ -0,0 +1,2 @@
+export declare function shelfSources(slug: string, getShelfOwner: (library: string, shelf: string) => string | undefined): string[];
+export declare function defaultShelfSources(slug: string): string[];

package/dist/orchestrator/starter-sources.js

@@ -0,0 +1,22 @@
+import { getActiveRegistry } from "../registry-context.js";
+export function shelfSources(slug, getShelfOwner) {
+    const parts = slug.split('/');
+    if (parts.length !== 2)
+        return [];
+    const [library, shelf] = parts;
+    if (!library || !shelf)
+        return [];
+    const out = [`library:${library}`];
+    const owner = getShelfOwner(library, shelf);
+    if (owner)
+        out.push(`plugin:${owner}`);
+    return out;
+}
+export function defaultShelfSources(slug) {
+    try {
+        return shelfSources(slug, getActiveRegistry().getShelfOwner);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/orchestrator/starters.d.ts

@@ -3,6 +3,7 @@ import { getPluginState, setPluginState } from '../plugin-state.ts';
 import { collectStarterHints } from '../mcp-tools.ts';
 import { loadAgentId } from './config.ts';
 import { getDefaultAgentId } from './registry.ts';
+import { listEventsSince, latestEventId } from '../embeddings.ts';
 import type { AgentRuntime } from './types.ts';
 export interface StartersDeps {
     getPluginSettings: typeof getPluginSettings;
@@ -12,8 +13,11 @@ export interface StartersDeps {
     loadAgentId: typeof loadAgentId;
     resolveAgent: (id?: string) => AgentRuntime;
     getDefaultAgentId: typeof getDefaultAgentId;
-    today: () => string;
-    now: () => string;
+    now: () => number;
+    shuffle: <T>(xs: T[]) => T[];
+    listEventsSince: typeof listEventsSince;
+    latestEventId: typeof latestEventId;
+    shelfSources: (slug: string) => string[];
 }
-export declare function getConversationStarters(deps?: StartersDeps): Promise<string[]>;
 export declare function refreshSystemStarters(deps?: StartersDeps): Promise<void>;
+export declare function getConversationStarters(deps?: StartersDeps): Promise<string[]>;

package/dist/orchestrator/starters.js

@@ -3,12 +3,30 @@ import { SYSTEM_SETTINGS_ID } from "../system-settings.js";
 import { getPluginState, setPluginState } from "../plugin-state.js";
 import { collectStarterHints } from "../mcp-tools.js";
 import { getLogger } from '@coffer-org/sdk/logger';
-import { todayDateString } from "./environment.js";
 import { loadAgentId } from "./config.js";
 import { resolveAgent, getDefaultAgentId } from "./registry.js";
+import { listEventsSince, latestEventId } from "../embeddings.js";
+import { defaultShelfSources } from "./starter-sources.js";
 const log = getLogger('orchestrator');
 const PLUGIN = 'orchestrator';
 const STATE_KEY = 'system_starters';
+const POOL_VERSION = 2;
+const ENTRY_TTL_MS = 24 * 60 * 60_000;
+const EARLY_DEBOUNCE_MS = 60 * 60_000;
+const EARLY_COOLDOWN_MS = 6 * 60 * 60_000;
+const EARLY_BUDGET_PER_DAY = 10;
+const SAMPLE_MIN = 4;
+const SAMPLE_MAX = 5;
+const PER_SOURCE_SOFT_CAP = 2;
+const EVENT_BATCH = 5000;
+function shuffled(xs) {
+    const out = [...xs];
+    for (let i = out.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [out[i], out[j]] = [out[j], out[i]];
+    }
+    return out;
+}
 const defaultDeps = {
     getPluginSettings,
     getPluginState,
@@ -17,65 +35,177 @@ const defaultDeps = {
     loadAgentId,
     resolveAgent,
     getDefaultAgentId,
-    today: todayDateString,
-    now: () => new Date().toISOString(),
+    now: () => Date.now(),
+    shuffle: shuffled,
+    listEventsSince,
+    latestEventId,
+    shelfSources: defaultShelfSources,
 };
 async function currentLanguage(deps) {
     const system = await deps.getPluginSettings(SYSTEM_SETTINGS_ID);
     const v = system['language'];
     return typeof v === 'string' && v ? v : 'en';
 }
-async function readCache(deps) {
+function isPool(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const p = v;
+    return p.version === POOL_VERSION && typeof p.language === 'string' && typeof p.sources === 'object' && !!p.sources;
+}
+async function readPool(deps) {
     const raw = await deps.getPluginState(PLUGIN, STATE_KEY);
     if (!raw)
         return null;
     try {
-        return JSON.parse(raw);
+        const parsed = JSON.parse(raw);
+        return isPool(parsed) ? parsed : null;
     }
     catch {
         return null;
     }
 }
-export async function getConversationStarters(deps = defaultDeps) {
-    return (await readCache(deps))?.starters ?? [];
+function fresh(entry, nowMs) {
+    return nowMs - Date.parse(entry.generatedAt) < ENTRY_TTL_MS;
+}
+function dayKey(nowMs) {
+    return new Date(nowMs).toISOString().slice(0, 10);
+}
+function earlyBudgetLeft(pool, nowMs) {
+    const spent = pool.earlyRuns;
+    if (!spent || spent.date !== dayKey(nowMs))
+        return true;
+    return spent.count < EARLY_BUDGET_PER_DAY;
+}
+function countEarlyRun(pool, nowMs) {
+    const key = dayKey(nowMs);
+    pool.earlyRuns =
+        pool.earlyRuns?.date === key ? { date: key, count: pool.earlyRuns.count + 1 } : { date: key, count: 1 };
+}
+function pickEarly(pool, hints, nowMs) {
+    const at = (h) => Date.parse(pool.sources[h.id].generatedAt);
+    return hints
+        .filter((h) => {
+        const e = pool.sources[h.id];
+        if (!e?.dirtySince)
+            return false;
+        if (nowMs - Date.parse(e.dirtySince) < EARLY_DEBOUNCE_MS)
+            return false;
+        return nowMs - Date.parse(e.generatedAt) >= EARLY_COOLDOWN_MS;
+    })
+        .sort((a, b) => at(a) - at(b))[0];
+}
+function tryResolve(deps, agentId) {
+    try {
+        return deps.resolveAgent(agentId);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function markChangedSources(deps, pool, declared, nowMs) {
+    if (pool.eventCursor == null) {
+        pool.eventCursor = await deps.latestEventId();
+        return true;
+    }
+    const rows = await deps.listEventsSince(pool.eventCursor, EVENT_BATCH);
+    if (!rows.length)
+        return false;
+    for (const row of rows) {
+        for (const id of deps.shelfSources(String(row.type ?? ''))) {
+            if (!declared.has(id))
+                continue;
+            const entry = pool.sources[id];
+            if (!entry || entry.dirtySince)
+                continue;
+            entry.dirtySince = new Date(nowMs).toISOString();
+        }
+    }
+    pool.eventCursor = rows[rows.length - 1].id;
+    return true;
 }
 export async function refreshSystemStarters(deps = defaultDeps) {
-    const date = deps.today();
     const [language, hints] = await Promise.all([currentLanguage(deps), deps.collectStarterHints()]);
     const agentId = (await deps.loadAgentId()) ?? deps.getDefaultAgentId();
     if (!agentId)
         return;
-    const cached = await readCache(deps);
-    if (cached &&
-        cached.date === date &&
-        cached.language === language &&
-        cached.hintsHash === hints.hash &&
-        cached.agentId === agentId) {
-        return;
-    }
-    let runtime;
-    try {
-        runtime = deps.resolveAgent(agentId);
-    }
-    catch {
-        return;
+    const stored = await readPool(deps);
+    const pool = stored && stored.language === language ? stored : { version: POOL_VERSION, language, sources: {} };
+    let dirty = pool !== stored;
+    const declared = new Set(hints.map((h) => h.id));
+    for (const id of Object.keys(pool.sources)) {
+        if (!declared.has(id)) {
+            delete pool.sources[id];
+            dirty = true;
+        }
     }
-    if (!runtime.starters)
-        return;
-    let starters;
-    try {
-        starters = await runtime.starters();
+    const nowMs = deps.now();
+    if (await markChangedSources(deps, pool, declared, nowMs))
+        dirty = true;
+    const stale = hints.find((h) => {
+        const e = pool.sources[h.id];
+        if (!e)
+            return true;
+        if (e.hintHash !== h.hash || e.agentId !== agentId)
+            return true;
+        return !fresh(e, nowMs);
+    });
+    const early = stale || !earlyBudgetLeft(pool, nowMs) ? undefined : pickEarly(pool, hints, nowMs);
+    const target = stale ?? early;
+    if (target) {
+        const runtime = tryResolve(deps, agentId);
+        if (runtime?.starters) {
+            try {
+                const messages = await runtime.starters(target.text);
+                pool.sources[target.id] = {
+                    messages,
+                    generatedAt: new Date(nowMs).toISOString(),
+                    hintHash: target.hash,
+                    agentId,
+                };
+                if (target === early)
+                    countEarlyRun(pool, nowMs);
+                dirty = true;
+            }
+            catch (err) {
+                log.warn(`starters for ${target.id} failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
     }
-    catch (err) {
-        log.warn(`system starters generation failed: ${err instanceof Error ? err.message : String(err)}`);
-        return;
+    if (dirty)
+        await setPool(deps, pool);
+}
+async function setPool(deps, pool) {
+    await deps.setPluginState(PLUGIN, STATE_KEY, JSON.stringify(pool));
+}
+export async function getConversationStarters(deps = defaultDeps) {
+    const [pool, language] = await Promise.all([readPool(deps), currentLanguage(deps)]);
+    if (!pool)
+        return [];
+    if (pool.language !== language)
+        return [];
+    const nowMs = deps.now();
+    const seen = new Set();
+    const primary = [];
+    const spare = [];
+    for (const entry of deps.shuffle(Object.values(pool.sources))) {
+        if (!fresh(entry, nowMs))
+            continue;
+        let taken = 0;
+        for (const message of deps.shuffle(entry.messages)) {
+            if (seen.has(message))
+                continue;
+            seen.add(message);
+            if (taken < PER_SOURCE_SOFT_CAP) {
+                primary.push(message);
+                taken++;
+            }
+            else {
+                spare.push(message);
+            }
+        }
     }
-    await deps.setPluginState(PLUGIN, STATE_KEY, JSON.stringify({
-        date,
-        language,
-        hintsHash: hints.hash,
-        agentId,
-        starters,
-        generatedAt: deps.now(),
-    }));
+    const out = deps.shuffle(primary).slice(0, SAMPLE_MAX);
+    if (out.length < SAMPLE_MIN)
+        out.push(...deps.shuffle(spare).slice(0, SAMPLE_MAX - out.length));
+    return out;
 }

package/dist/orchestrator/types.d.ts

@@ -8,7 +8,7 @@ export interface AgentToolDefinition {
     name: string;
     description: string;
     inputSchema: Record<string, unknown>;
-    handler: (args: Record<string, unknown>) => Promise<unknown>;
+    handler: (args: Record<string, unknown>, signal?: AbortSignal) => Promise<unknown>;
     forcedAfterAnswer?: boolean;
 }
 export interface AgentToolProvider {
@@ -83,7 +83,7 @@ export interface AgentRuntime {
     run(request: AgentRequest): Promise<AgentResult>;
     systemBase(): Promise<string>;
     describe(): Promise<AgentDescriptor>;
-    starters?(): Promise<string[]>;
+    starters?(hint: string): Promise<string[]>;
 }
 export interface ConnectorRegistration {
     id: string;

package/dist/plugin-hooks.d.ts

@@ -25,8 +25,9 @@ export interface Migration {
 export interface PluginCtx {
     em: EntityManager;
     log: Logger;
+    signal?: AbortSignal;
 }
-export declare function pluginCtx(id: string, em: EntityManager): PluginCtx;
+export declare function pluginCtx(id: string, em: EntityManager, signal?: AbortSignal): PluginCtx;
 export interface Seed {
     name: string;
     run(ctx: PluginCtx): Promise<void> | void;

package/dist/plugin-hooks.js

@@ -1,6 +1,6 @@
 import { getLogger } from '@coffer-org/sdk/logger';
-export function pluginCtx(id, em) {
-    return { em, log: getLogger(id) };
+export function pluginCtx(id, em, signal) {
+    return { em, log: getLogger(id), ...(signal ? { signal } : {}) };
 }
 export class HttpError extends Error {
     status;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffer-org/server",
-  "version": "6.0.0",
+  "version": "7.1.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -36,7 +36,7 @@
     "postpack": "node ../../scripts/swap-exports.mjs src"
   },
   "dependencies": {
-    "@coffer-org/sdk": "^6.0.0",
+    "@coffer-org/sdk": "^7.1.0",
     "@extractus/oembed-extractor": "^4.1.0",
     "@fastify/cors": "^11.2.0",
     "@fastify/multipart": "^10.0.0",