@coffer-org/server 3.4.0 → 4.0.0

package/dist/orchestrator/allow.d.ts

@@ -0,0 +1,16 @@
+import type { GatePolicy } from './types.ts';
+export declare const stateDir: () => string;
+export declare function carryLegacyState(): void;
+export declare function allowFileFor(connectorId: string): string;
+export interface AllowState {
+    ids: Record<string, number>;
+}
+export declare function emptyAllowed(): AllowState;
+export declare function loadAllowed(file: string): AllowState;
+export declare function saveAllowed(file: string, state: AllowState): void;
+export declare function isAllowed(state: AllowState, id: string | number | null | undefined): boolean;
+export declare function addAllowed(state: AllowState, id: string | number, now: number): AllowState;
+export declare function isSenderAllowed(connectorId: string, senderId: string, deps?: {
+    policy?: GatePolicy;
+}): Promise<boolean>;
+export declare function makeThrottle(maxAttempts?: number, windowMs?: number): (id: string | number, now?: number) => boolean;

package/dist/orchestrator/allow.js

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadGatePolicy } from "./config.js";
+import { carryInto, dataDir } from "../data-dir.js";
+export const stateDir = () => process.env['ORCHESTRATOR_STATE_DIR'] ?? path.join(dataDir(), 'state');
+function legacyStateDirs() {
+    return [
+        path.join(process.cwd(), 'packages', 'plugin-orchestrator', 'runtime', 'state'),
+        path.join(process.cwd(), 'node_modules', '@coffer-org', 'plugin-orchestrator', 'runtime', 'state'),
+    ];
+}
+export function carryLegacyState() {
+    carryInto(stateDir(), ...legacyStateDirs());
+}
+export function allowFileFor(connectorId) {
+    return path.join(stateDir(), `${connectorId}.allowed.json`);
+}
+export function emptyAllowed() {
+    return { ids: {} };
+}
+export function loadAllowed(file) {
+    try {
+        const obj = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        if (obj && typeof obj === 'object' && 'ids' in obj && typeof obj.ids === 'object') {
+            return obj;
+        }
+        return emptyAllowed();
+    }
+    catch {
+        return emptyAllowed();
+    }
+}
+export function saveAllowed(file, state) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(state), 'utf-8');
+    fs.renameSync(tmp, file);
+}
+export function isAllowed(state, id) {
+    return id != null && Object.prototype.hasOwnProperty.call(state.ids, String(id));
+}
+export function addAllowed(state, id, now) {
+    return { ids: { ...state.ids, [String(id)]: now } };
+}
+export async function isSenderAllowed(connectorId, senderId, deps) {
+    const policy = deps?.policy ?? (await loadGatePolicy());
+    if (!policy.accessPassword)
+        return true;
+    return isAllowed(loadAllowed(allowFileFor(connectorId)), senderId);
+}
+export function makeThrottle(maxAttempts = 5, windowMs = 60_000) {
+    const hits = new Map();
+    return function allowAttempt(id, now = Date.now()) {
+        const key = String(id);
+        const rec = hits.get(key);
+        if (!rec || now - rec.start >= windowMs) {
+            hits.set(key, { start: now, count: 1 });
+            return true;
+        }
+        if (rec.count >= maxAttempts)
+            return false;
+        rec.count += 1;
+        return true;
+    };
+}

package/dist/orchestrator/attachments.d.ts

@@ -0,0 +1,2 @@
+import type { AttachmentMaterializer } from './types.ts';
+export declare const attachmentMaterializer: AttachmentMaterializer;

package/dist/orchestrator/attachments.js

@@ -0,0 +1,11 @@
+import { saveUploadBytes } from "../uploads.js";
+export const attachmentMaterializer = {
+    async store(bytes, opts = {}) {
+        const stored = await saveUploadBytes(bytes, opts);
+        return {
+            name: stored.name,
+            ...(stored.mime ? { mime: stored.mime } : {}),
+            size: stored.size,
+        };
+    },
+};

package/dist/orchestrator/config.d.ts

@@ -0,0 +1,4 @@
+import type { GatePolicy } from './types.ts';
+export declare function buildPolicy(dbSettings?: Record<string, unknown>): GatePolicy;
+export declare function loadAgentId(): Promise<string | undefined>;
+export declare function loadGatePolicy(): Promise<GatePolicy>;

package/dist/orchestrator/config.js

@@ -0,0 +1,19 @@
+import { SYSTEM_SETTINGS_ID } from "../system-settings.js";
+export function buildPolicy(dbSettings = {}) {
+    const db = dbSettings;
+    return {
+        ...(typeof db.agent_id === 'string' && db.agent_id ? { agentId: db.agent_id } : {}),
+        accessPassword: db.access_password ?? '',
+        triggerPrefix: db.trigger_prefix ?? '',
+        replyWindow: Number(db.reply_window ?? 1800) || 1800,
+    };
+}
+export async function loadAgentId() {
+    const { getPluginSettings } = await import("../plugin-runtime.js");
+    const value = (await getPluginSettings(SYSTEM_SETTINGS_ID))['agent_id'];
+    return typeof value === 'string' && value ? value : undefined;
+}
+export async function loadGatePolicy() {
+    const { getPluginSettings } = await import("../plugin-runtime.js");
+    return buildPolicy(await getPluginSettings(SYSTEM_SETTINGS_ID));
+}

package/dist/orchestrator/db.d.ts

@@ -0,0 +1,17 @@
+export type LogTurn = {
+    connector: string;
+    chatId: string;
+    userId: string;
+    role: 'user' | 'assistant';
+    text: string;
+    tokensIn: number | null;
+    tokensOut: number | null;
+    ms: number | null;
+    agentId: string | null;
+    presetId: string | null;
+};
+export interface LogDb {
+    logTurn(row: LogTurn): void;
+    close(): void;
+}
+export declare function openLogDb(): LogDb;

package/dist/orchestrator/db.js

@@ -0,0 +1,12 @@
+import { logMessage } from "../msg-log.js";
+import { getLogger } from '@coffer-org/sdk/logger';
+const log = getLogger('orchestrator');
+export function openLogDb() {
+    return {
+        logTurn(row) {
+            logMessage(row).catch((e) => log.error('logTurn failed', e));
+        },
+        close() {
+        },
+    };
+}

package/dist/orchestrator/diagnostics.d.ts

@@ -0,0 +1,9 @@
+export interface DiagnosticEvent {
+    ts: string;
+    level: 'error' | 'warn';
+    source: string;
+    message: string;
+}
+export declare function recordDiagnostic(level: DiagnosticEvent['level'], source: string, message: string): void;
+export declare function listDiagnostics(limit?: number): DiagnosticEvent[];
+export declare function clearDiagnostics(): void;

package/dist/orchestrator/diagnostics.js

@@ -0,0 +1,13 @@
+const MAX_EVENTS = 100;
+const events = [];
+export function recordDiagnostic(level, source, message) {
+    events.unshift({ ts: new Date().toISOString(), level, source, message: message.slice(0, 500) });
+    if (events.length > MAX_EVENTS)
+        events.length = MAX_EVENTS;
+}
+export function listDiagnostics(limit = 25) {
+    return events.slice(0, Math.max(1, Math.min(100, Math.trunc(limit))));
+}
+export function clearDiagnostics() {
+    events.length = 0;
+}

package/dist/orchestrator/environment.d.ts

@@ -0,0 +1,3 @@
+export declare function systemTimeZone(): string;
+export declare function todayDateString(now?: Date, timeZone?: string): string;
+export declare function currentEnvironment(now?: Date, timeZone?: string): string;

package/dist/orchestrator/environment.js

@@ -0,0 +1,30 @@
+export function systemTimeZone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+    }
+    catch {
+        return 'UTC';
+    }
+}
+function part(now, timeZone, locale, options) {
+    return new Intl.DateTimeFormat(locale, { ...options, timeZone }).format(now);
+}
+export function todayDateString(now = new Date(), timeZone = systemTimeZone()) {
+    return part(now, timeZone, 'en-CA', { year: 'numeric', month: '2-digit', day: '2-digit' });
+}
+export function currentEnvironment(now = new Date(), timeZone = systemTimeZone()) {
+    let zone = timeZone;
+    try {
+        new Intl.DateTimeFormat('en-CA', { timeZone: zone }).format(now);
+    }
+    catch {
+        zone = 'UTC';
+    }
+    const date = part(now, zone, 'en-CA', { year: 'numeric', month: '2-digit', day: '2-digit' });
+    const weekday = part(now, zone, 'en-US', { weekday: 'long' });
+    const time = part(now, zone, 'en-GB', { hour: '2-digit', minute: '2-digit', hour12: false });
+    return [
+        `Current moment, refreshed on every turn: ${date} (${weekday}), ${time}, timezone ${zone}.`,
+        'Resolve every relative date against this value — "today", "tomorrow", "this week", ages, and expiry, warranty or due-date checks. Never infer the date from your training data and never tell the user you cannot know it.',
+    ].join('\n');
+}

package/dist/orchestrator/file-inspection.d.ts

@@ -0,0 +1,3 @@
+import type { AgentToolContentResult, AttachmentRef } from './types.ts';
+export declare function inspectUpload(name: string, ref?: Pick<AttachmentRef, 'mime' | 'size' | 'label'>): Promise<AgentToolContentResult>;
+export declare function isAgentToolContentResult(value: unknown): value is AgentToolContentResult;

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>;