@coffer-org/plugin-orchestrator 1.2.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@coffer-org/sdk/plugin").PluginManifest;
+export default _default;

package/dist/index.js

@@ -0,0 +1,16 @@
+import { definePlugin } from '@coffer-org/sdk/plugin';
+import { defineSettings } from '@coffer-org/sdk/settings';
+import { field } from '@coffer-org/sdk/fields';
+export default definePlugin({
+    id: 'orchestrator',
+    version: '1.0.0',
+    dependsOn: ['agent'],
+    settings: defineSettings({
+        label: 'orchestrator.settings.label',
+        fields: [
+            field.password({ key: 'access_password', label: 'orchestrator.settings.access_password' }),
+            field.string({ key: 'trigger_prefix', label: 'orchestrator.settings.trigger_prefix' }),
+            field.int({ key: 'reply_window', label: 'orchestrator.settings.reply_window', default: 1800 }),
+        ],
+    }),
+});

package/dist/runtime/allow.d.ts

@@ -0,0 +1,9 @@
+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 makeThrottle(maxAttempts?: number, windowMs?: number): (id: string | number, now?: number) => boolean;

package/dist/runtime/allow.js

@@ -0,0 +1,44 @@
+import fs from 'node:fs';
+import path from 'node:path';
+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 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/runtime/config.d.ts

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

package/dist/runtime/config.js

@@ -0,0 +1,12 @@
+export function buildPolicy(dbSettings = {}) {
+    const db = dbSettings;
+    return {
+        accessPassword: db.access_password ?? '',
+        triggerPrefix: db.trigger_prefix ?? '',
+        replyWindow: Number(db.reply_window ?? 1800) || 1800,
+    };
+}
+export async function loadGatePolicy() {
+    const { getPluginSettings } = await import('@coffer-org/server/plugin-runtime');
+    return buildPolicy(await getPluginSettings('orchestrator'));
+}

package/dist/runtime/db.d.ts

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

package/dist/runtime/db.js

@@ -0,0 +1,7 @@
+import { logMessage } from '@coffer-org/server/msg-log';
+export function openLogDb() {
+    return {
+        logTurn(row) { logMessage(row).catch((e) => console.error('[orchestrator] logTurn:', e)); },
+        close() { },
+    };
+}

package/dist/runtime/format.d.ts

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

package/dist/runtime/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/runtime/index.d.ts

@@ -0,0 +1,5 @@
+import type { PluginHooks } from '@coffer-org/server/plugin-hooks';
+export { handleIncoming } from './pipeline.ts';
+export { buildPolicy, loadGatePolicy } from './config.ts';
+export type { Connector, ConnectorCapabilities, IncomingPayload, GatePolicy } from './types.ts';
+export declare const serverHooks: PluginHooks;

package/dist/runtime/index.js

@@ -0,0 +1,12 @@
+import { openLogDb } from "./db.js";
+import { setLogDb } from "./pipeline.js";
+export { handleIncoming } from "./pipeline.js";
+export { buildPolicy, loadGatePolicy } from "./config.js";
+let db;
+export const serverHooks = {
+    init: () => { db = openLogDb(); setLogDb(db); },
+    teardown: () => { try {
+        db?.close();
+    }
+    catch { } db = undefined; setLogDb(undefined); },
+};

package/dist/runtime/pipeline.d.ts

@@ -0,0 +1,12 @@
+import { runAgent } from '@coffer-org/plugin-agent/runtime';
+import type { Connector, IncomingPayload, GatePolicy } from './types.ts';
+import type { LogDb } from './db.ts';
+export declare function setLogDb(db: LogDb | undefined): void;
+export type RunAgentFn = typeof runAgent;
+export interface PipelineDeps {
+    runAgent?: RunAgentFn;
+    logDb?: LogDb | null;
+    throttleMs?: number;
+    policy?: GatePolicy;
+}
+export declare function handleIncoming(connector: Connector, payload: IncomingPayload, deps?: PipelineDeps): Promise<void>;

package/dist/runtime/pipeline.js

@@ -0,0 +1,141 @@
+import { runAgent } from '@coffer-org/plugin-agent/runtime';
+import { chunk } from "./format.js";
+import { join } from 'node:path';
+import { loadThreads, saveThreads, resolveParent, getSession, recordSession, pruneThreads, } from "./threads.js";
+import { loadAllowed, saveAllowed, isAllowed, addAllowed, makeThrottle } from "./allow.js";
+import { loadGatePolicy } from "./config.js";
+const DEFAULT_STREAM_THROTTLE_MS = 2000;
+const stateDir = () => process.env['ORCHESTRATOR_STATE_DIR']
+    ?? join(new URL('../../runtime/state', import.meta.url).pathname);
+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;
+}
+async function safeCall(fn, fallback, label) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        console.error(`[orchestrator] connector error in ${label}:`, err instanceof Error ? err.message : String(err));
+        return fallback;
+    }
+}
+export async function handleIncoming(connector, payload, deps) {
+    const agent = deps?.runAgent ?? runAgent;
+    const db = deps && 'logDb' in deps ? deps.logDb : logDb;
+    const throttleMs = deps?.throttleMs ?? DEFAULT_STREAM_THROTTLE_MS;
+    const policy = deps?.policy ?? await loadGatePolicy();
+    const { chatId, userId, text, replyToId } = payload;
+    const dir = stateDir();
+    const allowFile = join(dir, `${connector.id}.allowed.json`);
+    const threadsFile = join(dir, `${connector.id}.threads.json`);
+    if (policy.accessPassword) {
+        let allow = loadAllowed(allowFile);
+        if (!isAllowed(allow, userId)) {
+            if (text.trim() === policy.accessPassword) {
+                allow = addAllowed(allow, userId, Date.now());
+                saveAllowed(allowFile, allow);
+                await safeCall(() => connector.sendMessage(chatId, '✅ Access granted. Send your requests.'), null, 'sendMessage(enroll)');
+            }
+            else if (passThrottle(connector.id)(userId)) {
+                await safeCall(() => connector.sendMessage(chatId, '🔒 Access locked. Send the password to gain access.'), null, 'sendMessage(locked)');
+            }
+            return;
+        }
+    }
+    if (policy.triggerPrefix && !text.toLowerCase().startsWith(policy.triggerPrefix.toLowerCase()))
+        return;
+    const queryText = policy.triggerPrefix ? text.slice(policy.triggerPrefix.length).trim() : text.trim();
+    if (!queryText)
+        return;
+    const now = Date.now();
+    let threads = loadThreads(threadsFile);
+    const parent = resolveParent(threads, { replyToMsgId: replyToId, now }, policy.replyWindow);
+    const parentSession = getSession(threads, parent);
+    db?.logTurn({ connector: connector.id, chatId, userId, role: 'user', text: queryText, sessionId: parentSession, tokensIn: null, tokensOut: null, ms: null });
+    const startedAt = Date.now();
+    const canStream = connector.capabilities.streaming && typeof connector.editMessage === 'function';
+    const max = connector.capabilities.maxMessageLength;
+    let result;
+    let placeholderId = null;
+    if (canStream) {
+        const stopTyping = connector.capabilities.typing && connector.startTyping
+            ? await safeCall(async () => connector.startTyping(chatId), undefined, 'startTyping')
+            : undefined;
+        let pending = '', lastEdited = '', editing = false, closed = false;
+        let editPromise = Promise.resolve();
+        const timer = setInterval(() => {
+            if (closed || editing)
+                return;
+            const t = pending.slice(0, max);
+            if (!t || t === lastEdited)
+                return;
+            editing = true;
+            if (!placeholderId) {
+                editPromise = safeCall(() => connector.sendMessage(chatId, t), null, 'sendMessage(stream-create)')
+                    .then((s) => { placeholderId = s?.msgId ?? null; lastEdited = t; })
+                    .finally(() => { editing = false; });
+                return;
+            }
+            editPromise = safeCall(() => connector.editMessage(chatId, placeholderId, t), undefined, 'editMessage(stream)')
+                .then(() => { lastEdited = t; })
+                .finally(() => { editing = false; });
+        }, throttleMs);
+        try {
+            result = await agent({ prompt: queryText, sessionId: parentSession, onDelta: (acc) => { pending = acc; } });
+            if (result.text == null && parentSession)
+                result = await agent({ prompt: queryText, sessionId: null, onDelta: (acc) => { pending = acc; } });
+        }
+        finally {
+            closed = true;
+            clearInterval(timer);
+            await editPromise;
+            stopTyping?.();
+        }
+    }
+    else {
+        const stopTyping = connector.capabilities.typing && connector.startTyping
+            ? await safeCall(async () => connector.startTyping(chatId), undefined, 'startTyping')
+            : undefined;
+        try {
+            result = await agent({ prompt: queryText, sessionId: parentSession });
+            if (result.text == null && parentSession)
+                result = await agent({ prompt: queryText, sessionId: null });
+        }
+        finally {
+            stopTyping?.();
+        }
+    }
+    let botMsgId = null;
+    const out = result.text ?? '⚠️ the agent returned no response';
+    const parts = chunk(out, max);
+    if (canStream && placeholderId) {
+        await safeCall(() => connector.editMessage(chatId, placeholderId, parts[0]), undefined, 'editMessage(final)');
+        botMsgId = placeholderId;
+        for (const p of parts.slice(1)) {
+            const s = await safeCall(() => connector.sendMessage(chatId, p), null, 'sendMessage(overflow)');
+            botMsgId = s?.msgId ?? botMsgId;
+        }
+    }
+    else {
+        for (const p of parts) {
+            const s = await safeCall(() => connector.sendMessage(chatId, p), null, 'sendMessage(deliver)');
+            botMsgId = s?.msgId ?? botMsgId;
+        }
+    }
+    if (result.text)
+        db?.logTurn({ connector: connector.id, chatId, userId, role: 'assistant', text: result.text, sessionId: result.sessionId, tokensIn: result.tokensIn, tokensOut: result.tokensOut, ms: Date.now() - startedAt });
+    if (result.sessionId) {
+        const incomingMsgId = replyToId ?? String(now);
+        threads = recordSession(threads, { msgId: incomingMsgId, botMsgId, sessionId: result.sessionId, now });
+        threads = pruneThreads(threads, now, 7);
+        saveThreads(threadsFile, threads);
+    }
+}

package/dist/runtime/threads.d.ts

@@ -0,0 +1,26 @@
+export interface ThreadEntry {
+    sessionId: string;
+    ts: number;
+}
+export interface Threads {
+    map: Record<string, ThreadEntry>;
+    last: {
+        msgId: string;
+        ts: number;
+    } | null;
+}
+export declare function emptyThreads(): Threads;
+export declare function resolveParent(threads: Threads, { replyToMsgId, now }: {
+    replyToMsgId: string | null;
+    now: number;
+}, replyWindowSec: number): string | null;
+export declare function getSession(threads: Threads, parentId: string | null): string | null;
+export declare function recordSession(threads: Threads, { msgId, botMsgId, sessionId, now }: {
+    msgId: string;
+    botMsgId: string | null;
+    sessionId: string;
+    now: number;
+}): Threads;
+export declare function pruneThreads(threads: Threads, now: number, ttlDays: number): Threads;
+export declare function loadThreads(file: string): Threads;
+export declare function saveThreads(file: string, threads: Threads): void;

package/dist/runtime/threads.js

@@ -0,0 +1,49 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function emptyThreads() {
+    return { map: {}, last: null };
+}
+export function resolveParent(threads, { replyToMsgId, now }, replyWindowSec) {
+    if (replyToMsgId != null)
+        return replyToMsgId;
+    const last = threads.last;
+    if (last && now - last.ts < replyWindowSec * 1000)
+        return last.msgId;
+    return null;
+}
+export function getSession(threads, parentId) {
+    if (parentId == null)
+        return null;
+    return threads.map[parentId]?.sessionId ?? null;
+}
+export function recordSession(threads, { msgId, botMsgId, sessionId, now }) {
+    const map = { ...threads.map };
+    map[msgId] = { sessionId, ts: now };
+    if (botMsgId != null)
+        map[botMsgId] = { sessionId, ts: now };
+    return { map, last: { msgId: botMsgId ?? msgId, ts: now } };
+}
+export function pruneThreads(threads, now, ttlDays) {
+    const cutoff = now - ttlDays * 86_400_000;
+    const map = {};
+    for (const [k, v] of Object.entries(threads.map)) {
+        if (v.ts >= cutoff)
+            map[k] = v;
+    }
+    return { map, last: threads.last };
+}
+export function loadThreads(file) {
+    try {
+        const obj = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        if (obj && typeof obj === 'object' && 'map' in obj)
+            return obj;
+        return emptyThreads();
+    }
+    catch {
+        return emptyThreads();
+    }
+}
+export function saveThreads(file, threads) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(threads), 'utf-8');
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,25 @@
+export interface ConnectorCapabilities {
+    streaming: boolean;
+    typing: boolean;
+    maxMessageLength: number;
+}
+export interface Connector {
+    id: string;
+    capabilities: ConnectorCapabilities;
+    sendMessage(chatId: string, text: string): Promise<{
+        msgId: string;
+    } | null>;
+    editMessage?(chatId: string, msgId: string, text: string): Promise<void>;
+    startTyping?(chatId: string): () => void;
+}
+export interface IncomingPayload {
+    chatId: string;
+    userId: string;
+    text: string;
+    replyToId: string | null;
+}
+export interface GatePolicy {
+    accessPassword: string;
+    triggerPrefix: string;
+    replyWindow: number;
+}

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@coffer-org/plugin-orchestrator",
+  "version": "1.2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./runtime": "./src/runtime/index.ts"
+  },
+  "distExports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "default": "./dist/runtime/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "test": "node --import tsx --test \"src/runtime/*.test.ts\""
+  },
+  "dependencies": {
+    "@coffer-org/sdk": "^1.2.0",
+    "@coffer-org/server": "^1.2.0",
+    "@coffer-org/plugin-agent": "^1.2.0"
+  }
+}