@coffer-org/server 3.3.0 → 4.0.0

package/dist/orchestrator/file-inspection.js

@@ -0,0 +1,61 @@
+import { readFile, stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { mimeForName } from "../file-fields.js";
+import { uploadsDir } from "../uploads.js";
+const MAX_VISION_BYTES = 5 * 1024 * 1024;
+const MAX_DOCUMENT_BYTES = 10 * 1024 * 1024;
+const MAX_TEXT_BYTES = 512 * 1024;
+const textResult = (text, isError = false) => ({
+    __cofferToolContent: true,
+    content: [{ type: 'text', text }],
+    ...(isError ? { isError: true } : {}),
+});
+export async function inspectUpload(name, ref = {}) {
+    if (!name || basename(name) !== name)
+        return textResult('Invalid upload name.', true);
+    const file = join(uploadsDir(), name);
+    let size;
+    try {
+        size = (await stat(file)).size;
+    }
+    catch {
+        return textResult(`File is no longer present on the server: ${name}`, true);
+    }
+    const mime = ref.mime ?? mimeForName(name);
+    if (mime === 'image/jpeg' || mime === 'image/png' || mime === 'image/gif' || mime === 'image/webp') {
+        if (size > MAX_VISION_BYTES)
+            return textResult(`Image is ${size} bytes, above the ${MAX_VISION_BYTES}-byte inspection limit.`, true);
+        const bytes = await readFile(file);
+        return {
+            __cofferToolContent: true,
+            content: [
+                { type: 'text', text: `Image: ${ref.label ?? name} (${mime}, ${size} bytes).` },
+                { type: 'image', mime, data: bytes.toString('base64') },
+            ],
+        };
+    }
+    if (mime === 'application/pdf') {
+        if (size > MAX_DOCUMENT_BYTES)
+            return textResult(`PDF is ${size} bytes, above the ${MAX_DOCUMENT_BYTES}-byte inspection limit.`, true);
+        const bytes = await readFile(file);
+        return {
+            __cofferToolContent: true,
+            content: [
+                { type: 'text', text: `PDF: ${ref.label ?? name} (${size} bytes).` },
+                { type: 'document', mime: 'application/pdf', data: bytes.toString('base64') },
+            ],
+        };
+    }
+    if (mime?.startsWith('text/') || mime === 'application/json' || mime === 'text/csv') {
+        if (size > MAX_TEXT_BYTES)
+            return textResult(`Text file is too large to inspect: ${size} bytes.`, true);
+        return textResult(`Text file: ${ref.label ?? name}\n\n${(await readFile(file)).toString('utf8')}`);
+    }
+    return textResult(`This file type cannot be inspected by the agent (${mime ?? 'unknown'}). ` +
+        'It can still be attached to a record.', true);
+}
+export function isAgentToolContentResult(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.__cofferToolContent === true);
+}

package/dist/orchestrator/format.d.ts

@@ -0,0 +1 @@
+export declare function chunk(text: string, max: number): string[];

package/dist/orchestrator/format.js

@@ -0,0 +1,6 @@
+export function chunk(text, max) {
+    const out = [];
+    for (let i = 0; i < text.length; i += max)
+        out.push(text.slice(i, i + max));
+    return out.length ? out : [''];
+}

package/dist/orchestrator/index.d.ts

@@ -0,0 +1,30 @@
+import type { BackgroundTask } from '../background-scheduler.ts';
+import { listRecentMessageMetrics } from '../msg-log.ts';
+import { listDiagnostics } from './diagnostics.ts';
+export { handleIncoming } from './pipeline.ts';
+export { registerAgent, resolveAgent, registerConnector, isConnectorRegistered, clearRuntimeRegistries, listRegisteredAgents, listRegisteredConnectors, listAgentCatalog, getDefaultAgentId, liveAgentId, } from './registry.ts';
+export { attachmentMaterializer } from './attachments.ts';
+export { makeAttachmentCapabilities } from './agent-capabilities.ts';
+export { makeSystemCapabilities } from './system-capabilities.ts';
+export { makeSuggestionCapabilities } from './suggestion-capabilities.ts';
+export type { SuggestionCapability } from './suggestion-capabilities.ts';
+export { currentEnvironment, systemTimeZone } from './environment.ts';
+export { inspectUpload, isAgentToolContentResult } from './file-inspection.ts';
+export type { PipelineDeps, RunAgentFn } from './pipeline.ts';
+export { buildPolicy, loadGatePolicy, loadAgentId } from './config.ts';
+export { getConversationStarters, refreshSystemStarters } from './starters.ts';
+export { isSenderAllowed } from './allow.ts';
+export { makeLiveChannel, plainRender } from './live-message.ts';
+export type { LiveChannelOps, LiveChannelOpts, RenderFn } from './live-message.ts';
+export { chunk } from './format.ts';
+export type { Connector, IncomingConversation, GatePolicy, ReplyContext, ReplyPayload, ReplyChannel, AttachmentRef, AttachmentMaterializer, AgentToolDefinition, AgentToolProvider, ConvMessage, SystemLayer, AgentRequest, AgentResult, AgentRuntime, AgentCapabilities, AgentPreset, AgentDescriptor, ConnectorRegistration, AgentToolContentBlock, AgentToolContentResult, } from './types.ts';
+export declare function startOrchestrator(): void;
+export declare function stopOrchestrator(): void;
+export declare const orchestratorStartersTask: BackgroundTask;
+export declare function orchestratorDiagnostics(): Promise<{
+    generatedAt: string;
+    agents: string[];
+    connectors: string[];
+    recentMessages: Awaited<ReturnType<typeof listRecentMessageMetrics>>;
+    recentErrors: ReturnType<typeof listDiagnostics>;
+}>;

package/dist/orchestrator/index.js

@@ -0,0 +1,56 @@
+import { openLogDb } from "./db.js";
+import { listRecentMessageMetrics } from "../msg-log.js";
+import { listRegisteredAgents, listRegisteredConnectors } from "./registry.js";
+import { listDiagnostics } from "./diagnostics.js";
+import { setLogDb } from "./pipeline.js";
+import { refreshSystemStarters } from "./starters.js";
+import { getLogger } from '@coffer-org/sdk/logger';
+const log = getLogger('orchestrator');
+export { handleIncoming } from "./pipeline.js";
+export { registerAgent, resolveAgent, registerConnector, isConnectorRegistered, clearRuntimeRegistries, listRegisteredAgents, listRegisteredConnectors, listAgentCatalog, getDefaultAgentId, liveAgentId, } from "./registry.js";
+export { attachmentMaterializer } from "./attachments.js";
+export { makeAttachmentCapabilities } from "./agent-capabilities.js";
+export { makeSystemCapabilities } from "./system-capabilities.js";
+export { makeSuggestionCapabilities } from "./suggestion-capabilities.js";
+export { currentEnvironment, systemTimeZone } from "./environment.js";
+export { inspectUpload, isAgentToolContentResult } from "./file-inspection.js";
+export { buildPolicy, loadGatePolicy, loadAgentId } from "./config.js";
+export { getConversationStarters, refreshSystemStarters } from "./starters.js";
+export { isSenderAllowed } from "./allow.js";
+import { carryLegacyState } from "./allow.js";
+export { makeLiveChannel, plainRender } from "./live-message.js";
+export { chunk } from "./format.js";
+let db;
+const STARTERS_CHECK_INTERVAL_MS = 10 * 60_000;
+function runStartersRefresh() {
+    return refreshSystemStarters().catch((err) => log.warn(`system starters: ${String(err)}`));
+}
+export function startOrchestrator() {
+    carryLegacyState();
+    db = openLogDb();
+    setLogDb(db);
+    void runStartersRefresh();
+}
+export function stopOrchestrator() {
+    try {
+        db?.close();
+    }
+    catch {
+    }
+    db = undefined;
+    setLogDb(undefined);
+}
+export const orchestratorStartersTask = {
+    name: 'core:orchestrator-starters',
+    intervalMs: STARTERS_CHECK_INTERVAL_MS,
+    run: runStartersRefresh,
+};
+export async function orchestratorDiagnostics() {
+    return {
+        generatedAt: new Date().toISOString(),
+        agents: listRegisteredAgents(),
+        connectors: listRegisteredConnectors(),
+        recentMessages: await listRecentMessageMetrics(25),
+        recentErrors: listDiagnostics(25),
+    };
+}

package/dist/orchestrator/live-message.d.ts

@@ -0,0 +1,14 @@
+import type { ReplyChannel, ReplyPayload } from './types.ts';
+export interface LiveChannelOps {
+    send(text: string): Promise<string | null>;
+    edit(msgId: string, text: string): Promise<void>;
+}
+export type RenderFn = (r: ReplyPayload) => string[];
+export interface LiveChannelOpts {
+    ops: LiveChannelOps;
+    throttleMs: number;
+    render: RenderFn;
+    maxLength: number;
+}
+export declare function plainRender(max: number): RenderFn;
+export declare function makeLiveChannel(o: LiveChannelOpts): ReplyChannel;

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 = policy.triggerPrefix
+        ? preparedMessages.map((m, i) => (i === preparedMessages.length - 1 ? { ...m, content: queryText } : m))
+        : preparedMessages;
+    const base = await agentBase();
+    const system = buildSystem({
+        base,
+        channelSystem: conversation.channelSystem,
+        volatileSystem: conversation.volatileSystem,
+    });
+    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(),
+    }));
+}