@coffer-org/server 3.4.0 → 5.0.0

package/dist/orchestrator/live-message.js

@@ -0,0 +1,100 @@
+import { chunk } from "./format.js";
+import { getLogger } from '@coffer-org/sdk/logger';
+const log = getLogger('orchestrator');
+export function plainRender(max) {
+    return (r) => chunk((r.text ?? '').trim() || '⚠️ the agent returned no response', max);
+}
+async function swallow(fn, fallback, label) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        log.error(`live-message ${label}: ${err instanceof Error ? err.message : String(err)}`);
+        return fallback;
+    }
+}
+export function makeLiveChannel(o) {
+    let msgId = null;
+    let pending = '';
+    let lastSent = '';
+    let busy = false;
+    let closed = false;
+    let gen = 0;
+    let inFlight = Promise.resolve();
+    const timer = setInterval(() => {
+        if (closed || busy)
+            return;
+        const t = pending.slice(0, o.maxLength);
+        if (!t || t === lastSent)
+            return;
+        busy = true;
+        const myGen = gen;
+        if (!msgId) {
+            inFlight = o.ops
+                .send(t)
+                .then((id) => {
+                if (gen === myGen) {
+                    msgId = id;
+                    lastSent = t;
+                }
+            })
+                .catch((err) => {
+                log.error(`live-message send: ${err instanceof Error ? err.message : String(err)}`);
+            })
+                .finally(() => {
+                busy = false;
+            });
+            return;
+        }
+        const id = msgId;
+        inFlight = o.ops
+            .edit(id, t)
+            .then(() => {
+            if (gen === myGen)
+                lastSent = t;
+        })
+            .catch((err) => {
+            log.error(`live-message edit: ${err instanceof Error ? err.message : String(err)}`);
+        })
+            .finally(() => {
+            busy = false;
+        });
+    }, o.throttleMs);
+    if (typeof timer.unref === 'function')
+        timer.unref();
+    return {
+        update(text) {
+            pending = text;
+        },
+        segment() {
+            gen++;
+            msgId = null;
+            pending = '';
+            lastSent = '';
+        },
+        async finish(r) {
+            closed = true;
+            clearInterval(timer);
+            await inFlight;
+            const parts = o.render(r);
+            let last = null;
+            const [head, ...rest] = parts;
+            if (msgId && head !== undefined) {
+                const id = msgId;
+                if (head !== lastSent) {
+                    await swallow(() => o.ops.edit(id, head), undefined, 'edit(final)');
+                    lastSent = head;
+                }
+                last = id;
+            }
+            else if (head !== undefined) {
+                last = await swallow(() => o.ops.send(head), null, 'send(final)');
+            }
+            for (const p of rest) {
+                const id = await swallow(() => o.ops.send(p), null, 'send(overflow)');
+                last = id ?? last;
+            }
+            return last;
+        },
+    };
+}

package/dist/orchestrator/pipeline.d.ts

@@ -0,0 +1,11 @@
+import type { Connector, IncomingConversation, GatePolicy, AgentRuntime } from './types.ts';
+import type { LogDb } from './db.ts';
+export declare function setLogDb(db: LogDb | undefined): void;
+export type RunAgentFn = AgentRuntime['run'];
+export interface PipelineDeps {
+    runAgent?: RunAgentFn;
+    logDb?: LogDb | null;
+    policy?: GatePolicy;
+    agentBase?: () => Promise<string>;
+}
+export declare function handleIncoming(connector: Connector, conversation: IncomingConversation, deps?: PipelineDeps): Promise<void>;

package/dist/orchestrator/pipeline.js

@@ -0,0 +1,198 @@
+import { loadAllowed, saveAllowed, isAllowed, addAllowed, makeThrottle, allowFileFor } from "./allow.js";
+import { loadAgentId, loadGatePolicy } from "./config.js";
+import { buildSystem } from "./system-assembly.js";
+import { attachmentMaterializer } from "./attachments.js";
+import { makeAttachmentCapabilities } from "./agent-capabilities.js";
+import { makeSystemCapabilities } from "./system-capabilities.js";
+import { makeSuggestionCapabilities } from "./suggestion-capabilities.js";
+import { resolveAgent } from "./registry.js";
+import { recordDiagnostic } from "./diagnostics.js";
+import { getLogger } from '@coffer-org/sdk/logger';
+const log = getLogger('orchestrator');
+let logDb;
+export function setLogDb(db) {
+    logDb = db;
+}
+const throttleByConnector = new Map();
+function passThrottle(connectorId) {
+    let t = throttleByConnector.get(connectorId);
+    if (!t) {
+        t = makeThrottle(5, 60_000);
+        throttleByConnector.set(connectorId, t);
+    }
+    return t;
+}
+let cachedBase;
+let cachedBaseAgentId;
+function cachedAgentBase() {
+    const runtime = resolveAgent();
+    if (cachedBaseAgentId !== runtime.id) {
+        cachedBaseAgentId = runtime.id;
+        cachedBase = runtime.systemBase();
+    }
+    return cachedBase;
+}
+function openChannel(connector, chatId, ctx) {
+    try {
+        return connector.reply(chatId, ctx);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        log.error(`connector error in reply: ${message}`);
+        recordDiagnostic('error', 'connector.reply', message);
+        return null;
+    }
+}
+async function safeCall(fn, fallback, label) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        log.error(`connector error in ${label}: ${message}`);
+        recordDiagnostic('error', `connector.${label}`, message);
+        return fallback;
+    }
+}
+export async function handleIncoming(connector, conversation, deps) {
+    const policy = deps?.policy ?? (await loadGatePolicy());
+    const selectedAgentId = conversation.agentId ?? policy.agentId ?? (deps?.runAgent ? undefined : await loadAgentId());
+    const runtime = deps?.runAgent ? undefined : resolveAgent(selectedAgentId);
+    const agent = deps?.runAgent ?? runtime.run.bind(runtime);
+    const db = deps && 'logDb' in deps ? deps.logDb : logDb;
+    const agentBase = deps?.agentBase ?? (() => (selectedAgentId ? runtime.systemBase() : cachedAgentBase()));
+    const { connectorId, chatId, sender, messages } = conversation;
+    const last = messages[messages.length - 1];
+    if (!last || last.role !== 'user')
+        return;
+    const incomingMsgId = last.msgId;
+    const allowFile = allowFileFor(connectorId);
+    if (policy.accessPassword) {
+        let allow = loadAllowed(allowFile);
+        if (!isAllowed(allow, sender.id)) {
+            if (last.content.trim() === policy.accessPassword) {
+                allow = addAllowed(allow, sender.id, Date.now());
+                saveAllowed(allowFile, allow);
+                const ch = openChannel(connector, chatId, { parentMsgId: incomingMsgId });
+                if (ch)
+                    await safeCall(() => ch.finish({ text: '✅ Access granted. Send your requests.', reasoning: null, suggestions: null }), null, 'finish(enroll)');
+            }
+            else if (passThrottle(connectorId)(sender.id)) {
+                const ch = openChannel(connector, chatId, { parentMsgId: incomingMsgId });
+                if (ch)
+                    await safeCall(() => ch.finish({
+                        text: '🔒 Access locked. Send the password to gain access.',
+                        reasoning: null,
+                        suggestions: null,
+                    }), null, 'finish(locked)');
+            }
+            return;
+        }
+    }
+    if (policy.triggerPrefix && !last.content.toLowerCase().startsWith(policy.triggerPrefix.toLowerCase()))
+        return;
+    const queryText = policy.triggerPrefix ? last.content.slice(policy.triggerPrefix.length).trim() : last.content.trim();
+    if (!queryText) {
+        if (conversation.prepareAttachments && !policy.triggerPrefix) {
+            await safeCall(() => conversation.prepareAttachments(attachmentMaterializer), messages, 'prepareAttachments');
+        }
+        return;
+    }
+    const preparedMessages = conversation.prepareAttachments
+        ? await safeCall(() => conversation.prepareAttachments(attachmentMaterializer), messages, 'prepareAttachments')
+        : messages;
+    const agentMessages = preparedMessages.map((m, i) => i === preparedMessages.length - 1
+        ? {
+            ...m,
+            ...(policy.triggerPrefix ? { content: queryText } : {}),
+            ...(conversation.turnContext ? { context: conversation.turnContext } : {}),
+        }
+        : m);
+    const base = await agentBase();
+    const system = buildSystem({ base, channelSystem: conversation.channelSystem });
+    db?.logTurn({
+        connector: connectorId,
+        chatId,
+        userId: sender.id,
+        role: 'user',
+        text: queryText,
+        tokensIn: null,
+        tokensOut: null,
+        ms: null,
+        agentId: selectedAgentId ?? null,
+        presetId: conversation.presetId ?? null,
+    });
+    const startedAt = Date.now();
+    const ch = openChannel(connector, chatId, { parentMsgId: incomingMsgId });
+    if (!ch)
+        return;
+    let result;
+    const suggestionCaps = conversation.supportsSuggestions ? makeSuggestionCapabilities() : undefined;
+    try {
+        const attachmentTools = await makeAttachmentCapabilities(agentMessages.flatMap((m) => m.attachments ?? []));
+        const toolProvider = {
+            tools: [...attachmentTools.tools, ...makeSystemCapabilities().tools, ...(suggestionCaps?.tools ?? [])],
+        };
+        result = await agent({
+            system,
+            messages: agentMessages,
+            toolProvider,
+            ...(conversation.presetId ? { presetId: conversation.presetId } : {}),
+            onDelta: (acc) => {
+                try {
+                    ch.update(acc);
+                }
+                catch (err) {
+                    log.error(`connector error in update: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            },
+            onReasoning: (acc) => {
+                try {
+                    ch.updateReasoning?.(acc);
+                }
+                catch (err) {
+                    log.error(`connector error in updateReasoning: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            },
+            onSegment: () => {
+                try {
+                    ch.segment();
+                }
+                catch (err) {
+                    log.error(`connector error in segment: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            },
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        log.error(`agent error: ${message}`);
+        recordDiagnostic('error', 'agent.run', message);
+    }
+    if (result && suggestionCaps)
+        result.suggestions = suggestionCaps.getCaptured();
+    const botMsgId = await safeCall(() => ch.finish({
+        text: result?.text ?? null,
+        reasoning: result?.reasoning ?? null,
+        suggestions: result?.suggestions ?? null,
+    }), null, 'finish');
+    if (result?.text)
+        db?.logTurn({
+            connector: connectorId,
+            chatId,
+            userId: sender.id,
+            role: 'assistant',
+            text: result.text,
+            tokensIn: result.tokensIn,
+            tokensOut: result.tokensOut,
+            ms: Date.now() - startedAt,
+            agentId: selectedAgentId ?? null,
+            presetId: result.presetId,
+        });
+    await safeCall(() => connector.recordAssistant({
+        parentMsgId: incomingMsgId,
+        botMsgId,
+        text: result?.text ?? '',
+        reasoning: result?.reasoning ?? null,
+    }), undefined, 'recordAssistant');
+}

package/dist/orchestrator/registry.d.ts

@@ -0,0 +1,13 @@
+import type { AgentDescriptor, AgentRuntime, ConnectorRegistration } from './types.ts';
+export declare function registerAgent(runtime: AgentRuntime, opts?: {
+    default?: boolean;
+}): () => void;
+export declare function resolveAgent(id?: string): AgentRuntime;
+export declare function liveAgentId(agentId: string | null | undefined): string | undefined;
+export declare function registerConnector(registration: ConnectorRegistration): () => void;
+export declare function isConnectorRegistered(id: string): boolean;
+export declare function listRegisteredAgents(): string[];
+export declare function listRegisteredConnectors(): string[];
+export declare function listAgentCatalog(): Promise<AgentDescriptor[]>;
+export declare function getDefaultAgentId(): string | undefined;
+export declare function clearRuntimeRegistries(): void;

package/dist/orchestrator/registry.js

@@ -0,0 +1,74 @@
+import { getLogger } from '@coffer-org/sdk/logger';
+const log = getLogger('orchestrator');
+const agents = new Map();
+const connectors = new Map();
+let defaultAgentId;
+export function registerAgent(runtime, opts = {}) {
+    const current = agents.get(runtime.id);
+    if (current && current !== runtime)
+        throw new Error(`agent already registered: ${runtime.id}`);
+    agents.set(runtime.id, runtime);
+    if (opts.default || !defaultAgentId)
+        defaultAgentId = runtime.id;
+    return () => unregisterAgent(runtime.id, runtime);
+}
+function unregisterAgent(id, expected) {
+    if (agents.get(id) !== expected)
+        return;
+    agents.delete(id);
+    if (defaultAgentId === id)
+        defaultAgentId = agents.keys().next().value;
+}
+export function resolveAgent(id) {
+    const key = id ?? defaultAgentId;
+    const runtime = key ? agents.get(key) : undefined;
+    if (!runtime)
+        throw new Error(id ? `agent is not registered: ${id}` : 'no agent is registered');
+    return runtime;
+}
+export function liveAgentId(agentId) {
+    return agentId && agents.has(agentId) ? agentId : undefined;
+}
+export function registerConnector(registration) {
+    const current = connectors.get(registration.id);
+    if (current && current !== registration)
+        throw new Error(`connector already registered: ${registration.id}`);
+    connectors.set(registration.id, registration);
+    return () => {
+        if (connectors.get(registration.id) === registration)
+            connectors.delete(registration.id);
+    };
+}
+export function isConnectorRegistered(id) {
+    return connectors.has(id);
+}
+export function listRegisteredAgents() {
+    return [...agents.keys()].sort();
+}
+export function listRegisteredConnectors() {
+    return [...connectors.keys()].sort();
+}
+export async function listAgentCatalog() {
+    const ids = [...agents.keys()].sort();
+    const out = [];
+    for (const id of ids) {
+        const runtime = agents.get(id);
+        if (!runtime)
+            continue;
+        try {
+            out.push(await runtime.describe());
+        }
+        catch (err) {
+            log.error(`agent describe failed for ${id}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return out;
+}
+export function getDefaultAgentId() {
+    return defaultAgentId;
+}
+export function clearRuntimeRegistries() {
+    agents.clear();
+    connectors.clear();
+    defaultAgentId = undefined;
+}

package/dist/orchestrator/starters.d.ts

@@ -0,0 +1,19 @@
+import { getPluginSettings } from '../plugin-runtime.ts';
+import { getPluginState, setPluginState } from '../plugin-state.ts';
+import { collectStarterHints } from '../mcp-tools.ts';
+import { loadAgentId } from './config.ts';
+import { getDefaultAgentId } from './registry.ts';
+import type { AgentRuntime } from './types.ts';
+export interface StartersDeps {
+    getPluginSettings: typeof getPluginSettings;
+    getPluginState: typeof getPluginState;
+    setPluginState: typeof setPluginState;
+    collectStarterHints: typeof collectStarterHints;
+    loadAgentId: typeof loadAgentId;
+    resolveAgent: (id?: string) => AgentRuntime;
+    getDefaultAgentId: typeof getDefaultAgentId;
+    today: () => string;
+    now: () => string;
+}
+export declare function getConversationStarters(deps?: StartersDeps): Promise<string[]>;
+export declare function refreshSystemStarters(deps?: StartersDeps): Promise<void>;

package/dist/orchestrator/starters.js

@@ -0,0 +1,81 @@
+import { getPluginSettings } from "../plugin-runtime.js";
+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";
+const log = getLogger('orchestrator');
+const PLUGIN = 'orchestrator';
+const STATE_KEY = 'system_starters';
+const defaultDeps = {
+    getPluginSettings,
+    getPluginState,
+    setPluginState,
+    collectStarterHints,
+    loadAgentId,
+    resolveAgent,
+    getDefaultAgentId,
+    today: todayDateString,
+    now: () => new Date().toISOString(),
+};
+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) {
+    const raw = await deps.getPluginState(PLUGIN, STATE_KEY);
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function getConversationStarters(deps = defaultDeps) {
+    return (await readCache(deps))?.starters ?? [];
+}
+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;
+    }
+    if (!runtime.starters)
+        return;
+    let starters;
+    try {
+        starters = await runtime.starters();
+    }
+    catch (err) {
+        log.warn(`system starters generation failed: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    await deps.setPluginState(PLUGIN, STATE_KEY, JSON.stringify({
+        date,
+        language,
+        hintsHash: hints.hash,
+        agentId,
+        starters,
+        generatedAt: deps.now(),
+    }));
+}

package/dist/orchestrator/suggestion-capabilities.d.ts

@@ -0,0 +1,5 @@
+import type { AgentToolProvider } from './types.ts';
+export interface SuggestionCapability extends AgentToolProvider {
+    getCaptured(): string[] | null;
+}
+export declare function makeSuggestionCapabilities(): SuggestionCapability;

package/dist/orchestrator/suggestion-capabilities.js

@@ -0,0 +1,33 @@
+const MAX_SUGGESTIONS = 4;
+export function makeSuggestionCapabilities() {
+    let captured = null;
+    const tool = {
+        name: 'suggest_replies',
+        description: 'You have already given your final answer, shown above. Propose 2-4 short, concrete follow-up replies in ' +
+            "the user's own language that a user might plausibly send next — grounded in what you ACTUALLY wrote, not " +
+            'generic filler. If your answer ended with a question, one suggestion should directly answer that exact ' +
+            'question. If your answer named specific items (a record, a recipe, a place), prefer a suggestion that ' +
+            'references one of them by name over a vague "tell me more". Call this once; skip it entirely if nothing ' +
+            'concrete fits — it does not change your answer, it only offers the user clickable shortcuts.',
+        inputSchema: {
+            suggestions: {
+                type: 'array',
+                items: { type: 'string' },
+                description: '2-4 short reply options, grounded in the answer above, in the language of the conversation.',
+            },
+        },
+        forcedAfterAnswer: true,
+        handler: async (args) => {
+            const raw = args['suggestions'];
+            const list = Array.isArray(raw)
+                ? raw
+                    .map((v) => String(v).trim())
+                    .filter((v) => v.length > 0)
+                    .slice(0, MAX_SUGGESTIONS)
+                : [];
+            captured = list.length ? list : null;
+            return { ok: true };
+        },
+    };
+    return { tools: [tool], getCaptured: () => captured };
+}

package/dist/orchestrator/system-assembly.d.ts

@@ -0,0 +1,4 @@
+export declare function buildSystem(input: {
+    base: string;
+    channelSystem?: string;
+}): string;

package/dist/orchestrator/system-assembly.js

@@ -0,0 +1,3 @@
+export function buildSystem(input) {
+    return [input.base, input.channelSystem].filter(Boolean).join('\n\n');
+}

package/dist/orchestrator/system-capabilities.d.ts

@@ -0,0 +1,2 @@
+import type { AgentToolProvider } from './types.ts';
+export declare function makeSystemCapabilities(): AgentToolProvider;

package/dist/orchestrator/system-capabilities.js

@@ -0,0 +1,63 @@
+import { stat, statfs } from 'node:fs/promises';
+import { arch, freemem, platform, totalmem } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { discoverRuntime } from "../plugin-discovery.js";
+import { systemTimeZone } from "./environment.js";
+const mb = (bytes) => Math.round(bytes / 1024 / 1024);
+function databasePath() {
+    return resolve(process.env['DB_PATH'] ?? 'data/app.db');
+}
+async function databaseState() {
+    const path = databasePath();
+    const out = { path };
+    try {
+        out['size_mb'] = mb((await stat(path)).size);
+    }
+    catch {
+        out['size_mb'] = null;
+    }
+    try {
+        const fs = await statfs(dirname(path));
+        out['disk_free_mb'] = mb(Number(fs.bavail) * Number(fs.bsize));
+        out['disk_total_mb'] = mb(Number(fs.blocks) * Number(fs.bsize));
+    }
+    catch {
+        out['disk_free_mb'] = null;
+        out['disk_total_mb'] = null;
+    }
+    return out;
+}
+async function runtimeVersion() {
+    try {
+        return (await discoverRuntime())?.installedVersion ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function makeSystemCapabilities() {
+    const serverState = {
+        name: 'mcp__coffer__server_state',
+        description: 'Health and identity of the Coffer server this assistant runs on: installed version, uptime, Node version, ' +
+            'platform, memory, and the database file path with its size and free disk space. ' +
+            'Use it for questions about the instance itself ("which version am I running", "is the disk filling up", ' +
+            '"how long has the server been up"). It returns nothing about the user\'s records — use count_records for those. ' +
+            'The current date and time are already given in the system prompt; do not call this tool to find them.',
+        inputSchema: {},
+        handler: async () => ({
+            coffer_version: await runtimeVersion(),
+            uptime_seconds: Math.round(process.uptime()),
+            node_version: process.version,
+            platform: platform(),
+            arch: arch(),
+            timezone: systemTimeZone(),
+            memory: {
+                total_mb: mb(totalmem()),
+                free_mb: mb(freemem()),
+                process_rss_mb: mb(process.memoryUsage().rss),
+            },
+            database: await databaseState(),
+        }),
+    };
+    return { tools: [serverState] };
+}