@coffer-org/plugin-webchat 2.0.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,22 @@
+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: 'webchat',
+    version: '1.0.0',
+    dependsOn: ['orchestrator'],
+    settings: defineSettings({
+        label: 'webchat.settings.label',
+        fields: [
+            field.select({
+                key: 'reasoning_display',
+                label: 'webchat.settings.reasoning_display',
+                default: 'live',
+                options: [
+                    { value: 'live', title: 'webchat.settings.reasoning_display_live' },
+                    { value: 'off', title: 'webchat.settings.reasoning_display_off' },
+                ],
+            }),
+        ],
+    }),
+});

package/dist/runtime/actions.d.ts

@@ -0,0 +1,22 @@
+import { type ActionCaller } from '@coffer-org/server/plugin-hooks';
+export interface ThreadSummary {
+    convId: string;
+    title: string;
+    lastTs: number;
+    count: number;
+}
+export interface HistoryMsg {
+    msgId: string;
+    role: 'user' | 'assistant';
+    text: string;
+    ts: number;
+    reasoning?: string;
+}
+export declare function threadsAction(_body: Record<string, unknown>, caller: ActionCaller): Promise<{
+    threads: ThreadSummary[];
+}>;
+export declare function historyAction(body: Record<string, unknown>, caller: ActionCaller): Promise<{
+    convId: string;
+    messages: HistoryMsg[];
+    headMsgId: string | null;
+}>;

package/dist/runtime/actions.js

@@ -0,0 +1,38 @@
+import { HttpError } from '@coffer-org/server/plugin-hooks';
+import { chatIdFor, conversations, history } from "./chain-store.js";
+const TITLE_MAX = 60;
+function title(firstUserText) {
+    const t = firstUserText.trim().replace(/\s+/g, ' ');
+    return t.length <= TITLE_MAX ? t : `${t.slice(0, TITLE_MAX - 1)}…`;
+}
+export async function threadsAction(_body, caller) {
+    const chats = await conversations(caller.id);
+    const prefixLen = `u:${caller.id}:`.length;
+    return {
+        threads: chats.map((c) => ({
+            convId: c.chatId.slice(prefixLen),
+            title: title(c.firstUserText),
+            lastTs: c.lastTs,
+            count: c.count,
+        })),
+    };
+}
+export async function historyAction(body, caller) {
+    const convId = body['convId'];
+    if (typeof convId !== 'string' || !convId)
+        throw new HttpError(400, 'missing required field: convId');
+    const rows = await history(chatIdFor(caller.id, convId));
+    const reasoningByBot = new Map(rows.filter((m) => m.role === 'reasoning').map((m) => [m.msgId.slice(0, -2), m.text]));
+    const visible = rows.filter((m) => m.role !== 'reasoning');
+    return {
+        convId,
+        messages: visible.map((m) => ({
+            msgId: m.msgId,
+            role: m.role,
+            text: m.text,
+            ts: m.ts,
+            ...(reasoningByBot.has(m.msgId) ? { reasoning: reasoningByBot.get(m.msgId) } : {}),
+        })),
+        headMsgId: visible.at(-1)?.msgId ?? null,
+    };
+}

package/dist/runtime/chain-store.d.ts

@@ -0,0 +1,33 @@
+import { type ThreadChat, type StoredMsg } from '@coffer-org/server/thread-store';
+import type { ConvMessage } from '@coffer-org/plugin-orchestrator/runtime';
+export declare const CONNECTOR = "webchat";
+export declare function chatIdFor(userId: string, convId: string): string;
+export declare function chatPrefixFor(userId: string): string;
+export declare function recordUser(m: {
+    chatId: string;
+    msgId: string;
+    sender?: string | null;
+    text: string;
+    ts: number;
+    replyToId: string | null;
+}): Promise<void>;
+export declare function recordAssistant(m: {
+    chatId: string;
+    parentMsgId: string | null;
+    botMsgId: string | null;
+    text: string;
+    now: number;
+}): Promise<boolean>;
+export declare function recordReasoning(m: {
+    chatId: string;
+    botMsgId: string;
+    parentMsgId: string | null;
+    text: string;
+    now: number;
+}): Promise<boolean>;
+export declare function buildChain(headMsgId: string, opts: {
+    chatId: string;
+    maxDepth?: number;
+}): Promise<ConvMessage[]>;
+export declare function history(chatId: string, limit?: number): Promise<StoredMsg[]>;
+export declare function conversations(userId: string): Promise<ThreadChat[]>;

package/dist/runtime/chain-store.js

@@ -0,0 +1,61 @@
+import { getThreadMessage, putThreadMessage, listThreadMessages, listThreadChats } from '@coffer-org/server/thread-store';
+import { getLogger } from '@coffer-org/sdk/logger';
+const log = getLogger('webchat');
+export const CONNECTOR = 'webchat';
+const DEFAULT_MAX_DEPTH = 40;
+export function chatIdFor(userId, convId) {
+    return `u:${userId}:${convId}`;
+}
+export function chatPrefixFor(userId) {
+    return `u:${userId}:`;
+}
+export async function recordUser(m) {
+    await putThreadMessage({ connector: CONNECTOR, chatId: m.chatId, msgId: m.msgId, role: 'user', sender: m.sender ?? null, text: m.text, ts: m.ts, replyToId: m.replyToId });
+}
+export async function recordAssistant(m) {
+    if (m.botMsgId == null || !m.text.trim())
+        return false;
+    await putThreadMessage({ connector: CONNECTOR, chatId: m.chatId, msgId: m.botMsgId, role: 'assistant', text: m.text, ts: m.now, replyToId: m.parentMsgId });
+    return true;
+}
+export async function recordReasoning(m) {
+    if (!m.text.trim())
+        return false;
+    await putThreadMessage({
+        connector: CONNECTOR,
+        chatId: m.chatId,
+        msgId: `${m.botMsgId}~r`,
+        role: 'reasoning',
+        text: m.text,
+        ts: m.now - 1,
+        replyToId: m.parentMsgId,
+    });
+    return true;
+}
+export async function buildChain(headMsgId, opts) {
+    const max = opts.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const acc = [];
+    let cur = headMsgId;
+    const seen = new Set();
+    while (cur && acc.length < max && !seen.has(cur)) {
+        seen.add(cur);
+        const stored = await getThreadMessage(CONNECTOR, opts.chatId, cur);
+        if (!stored)
+            break;
+        if (stored.role !== 'reasoning') {
+            acc.push({ role: stored.role, content: stored.text, sender: stored.sender, msgId: stored.msgId, ts: stored.ts });
+        }
+        cur = stored.replyToId;
+    }
+    if (acc.length >= max)
+        log.info(`chain capped at ${max} for ${headMsgId}`);
+    while (acc.length && acc.at(-1)?.role !== 'user')
+        acc.pop();
+    return acc.reverse();
+}
+export function history(chatId, limit) {
+    return listThreadMessages(CONNECTOR, chatId, limit);
+}
+export function conversations(userId) {
+    return listThreadChats(CONNECTOR, chatPrefixFor(userId));
+}

package/dist/runtime/config.d.ts

@@ -0,0 +1,2 @@
+import type { GatePolicy } from '@coffer-org/plugin-orchestrator/runtime';
+export declare function policy(): GatePolicy;

package/dist/runtime/config.js

@@ -0,0 +1,7 @@
+export function policy() {
+    return {
+        accessPassword: '',
+        triggerPrefix: '',
+        replyWindow: 1800,
+    };
+}

package/dist/runtime/connector.d.ts

@@ -0,0 +1,16 @@
+import type { Connector } from '@coffer-org/plugin-orchestrator/runtime';
+import { recordAssistant as storeAssistant, recordReasoning as storeReasoning } from './chain-store.ts';
+import type { ReasoningDisplay } from './settings.ts';
+export interface StreamingConnector {
+    connector: Connector;
+    recorded(): string | null;
+}
+export interface StreamingConnectorOpts {
+    chatId: string;
+    botMsgId: string;
+    emit: (event: string, data: unknown) => void;
+    display: ReasoningDisplay;
+    record?: typeof storeAssistant;
+    recordReasoning?: typeof storeReasoning;
+}
+export declare function makeStreamingConnector(opts: StreamingConnectorOpts): StreamingConnector;

package/dist/runtime/connector.js

@@ -0,0 +1,43 @@
+import { makeLiveChannel, plainRender } from '@coffer-org/plugin-orchestrator/runtime';
+import { recordAssistant as storeAssistant, recordReasoning as storeReasoning } from "./chain-store.js";
+const WEBCHAT_THROTTLE_MS = 250;
+const WEBCHAT_MAX = 100_000;
+export function makeStreamingConnector(opts) {
+    const record = opts.record ?? storeAssistant;
+    const recordReasoningFn = opts.recordReasoning ?? storeReasoning;
+    let recordedId = null;
+    const connector = {
+        id: 'webchat',
+        reply(_chatId, _ctx) {
+            const ch = makeLiveChannel({
+                ops: {
+                    send: async (text) => { opts.emit('message', { msgId: opts.botMsgId, text }); return opts.botMsgId; },
+                    edit: async (msgId, text) => { opts.emit('delta', { msgId, text }); },
+                },
+                throttleMs: WEBCHAT_THROTTLE_MS,
+                maxLength: WEBCHAT_MAX,
+                render: plainRender(WEBCHAT_MAX),
+            });
+            return {
+                ...ch,
+                updateReasoning(acc) {
+                    if (opts.display === 'off')
+                        return;
+                    opts.emit('reasoning', { msgId: opts.botMsgId, text: acc });
+                },
+            };
+        },
+        async recordAssistant(m) {
+            const now = Math.floor(Date.now() / 1000);
+            const wrote = await record({ chatId: opts.chatId, parentMsgId: m.parentMsgId, botMsgId: m.botMsgId, text: m.text, now });
+            recordedId = wrote ? m.botMsgId : null;
+            if (wrote && opts.display !== 'off' && m.reasoning && m.botMsgId) {
+                await recordReasoningFn({ chatId: opts.chatId, botMsgId: m.botMsgId, parentMsgId: m.parentMsgId, text: m.reasoning, now });
+            }
+        },
+    };
+    return {
+        connector,
+        recorded: () => recordedId,
+    };
+}

package/dist/runtime/format.d.ts

@@ -0,0 +1 @@
+export declare const WEB_FORMAT: string;

package/dist/runtime/format.js

@@ -0,0 +1,10 @@
+export const WEB_FORMAT = [
+    'CRITICAL OUTPUT FORMAT — MARKDOWN ONLY. Format the reply strictly as Markdown (GFM). NEVER emit raw HTML tags — they are stripped before rendering and their content may be lost.',
+    'Inline: **bold**, *italic*, `inline code`, ~~strikethrough~~. Links: [text](https://…).',
+    'Blocks: blank-line-separated paragraphs, `#`–`###` headings, `>` blockquotes, `---` separators.',
+    'Lists: `- item` for bullets, `1. item` for numbered steps. Nest with two spaces.',
+    'Tables render as real tables — use GFM pipe syntax with a header separator row.',
+    'Code blocks: triple backticks with a language tag (```python) — highlighted on render.',
+    'The reply is read in a narrow chat panel (~360px) — keep it short and skimmable: short paragraphs, lists over prose, narrow tables.',
+    'Use Unicode symbols and emoji to structure replies: arrows (→), status marks (✅ ⚠️ ❌ ⏳), topic emoji (📅 💰 🏥 🛒 🌱 …).',
+].join('\n');

package/dist/runtime/index.d.ts

@@ -0,0 +1,7 @@
+import type { PluginHooks } from '@coffer-org/server/plugin-hooks';
+export type { ThreadSummary, HistoryMsg } from './actions.ts';
+export { WEB_FORMAT } from './format.ts';
+export { makeStreamingConnector } from './connector.ts';
+export { chatIdFor, chatPrefixFor, recordUser, recordAssistant, buildChain } from './chain-store.ts';
+export { sendAction, pageContext } from './send.ts';
+export declare const serverHooks: PluginHooks;

package/dist/runtime/index.js

@@ -0,0 +1,27 @@
+import { pruneThreadMessages } from '@coffer-org/server/thread-store';
+import { threadsAction, historyAction } from "./actions.js";
+import { sendAction } from "./send.js";
+import { CONNECTOR } from "./chain-store.js";
+const THREAD_TTL_MS = Number(process.env['WEBCHAT_THREAD_TTL_MS'] ?? 30 * 86_400_000);
+export { WEB_FORMAT } from "./format.js";
+export { makeStreamingConnector } from "./connector.js";
+export { chatIdFor, chatPrefixFor, recordUser, recordAssistant, buildChain } from "./chain-store.js";
+export { sendAction, pageContext } from "./send.js";
+export const serverHooks = {
+    userActions: {
+        threads: threadsAction,
+        history: historyAction,
+    },
+    streamActions: {
+        send: (body, ctx) => sendAction(body, ctx),
+    },
+    backgroundTasks: [
+        {
+            name: 'webchat-thread-prune',
+            intervalMs: 86_400_000,
+            run: async () => {
+                await pruneThreadMessages(CONNECTOR, Math.floor((Date.now() - THREAD_TTL_MS) / 1000));
+            },
+        },
+    ],
+};

package/dist/runtime/send.d.ts

@@ -0,0 +1,12 @@
+import { handleIncoming } from '@coffer-org/plugin-orchestrator/runtime';
+import type { ActionCaller } from '@coffer-org/server/plugin-hooks';
+export interface SendDeps {
+    handleIncoming?: typeof handleIncoming;
+}
+export interface StreamCtx {
+    caller: ActionCaller;
+    emit: (event: string, data: unknown) => void;
+    signal: AbortSignal;
+}
+export declare function pageContext(ctx: unknown): string;
+export declare function sendAction(body: Record<string, unknown>, ctx: StreamCtx, deps?: SendDeps): Promise<void>;

package/dist/runtime/send.js

@@ -0,0 +1,57 @@
+import { randomUUID } from 'node:crypto';
+import { handleIncoming } from '@coffer-org/plugin-orchestrator/runtime';
+import { chatIdFor, recordUser, buildChain, history } from "./chain-store.js";
+import { policy } from "./config.js";
+import { makeStreamingConnector } from "./connector.js";
+import { WEB_FORMAT } from "./format.js";
+import { loadReasoningDisplay } from "./settings.js";
+export function pageContext(ctx) {
+    if (typeof ctx !== 'object' || ctx === null)
+        return '';
+    const c = ctx;
+    const path = typeof c['path'] === 'string' ? c['path'] : '';
+    if (!path)
+        return '';
+    const library = typeof c['library'] === 'string' ? c['library'] : '';
+    const type = typeof c['type'] === 'string' ? c['type'] : '';
+    const id = typeof c['id'] === 'string' ? c['id'] : '';
+    const where = library && type && id ? `record ${library}/${type}/${id}` : library && type ? `the ${library}/${type} list` : path;
+    return `CURRENT PAGE — the user is looking at ${where} (SPA path ${path}). When they say "this", "here", or "this record", they most likely mean it. Do not mention this note unless it is relevant.`;
+}
+export async function sendAction(body, ctx, deps = {}) {
+    const doHandle = deps.handleIncoming ?? handleIncoming;
+    const convId = typeof body['convId'] === 'string' ? body['convId'] : '';
+    const text = typeof body['text'] === 'string' ? body['text'] : '';
+    if (!convId) {
+        ctx.emit('error', { message: 'missing required field: convId' });
+        return;
+    }
+    if (!text.trim()) {
+        ctx.emit('error', { message: 'missing required field: text' });
+        return;
+    }
+    const chatId = chatIdFor(ctx.caller.id, convId);
+    const msgId = randomUUID();
+    const botMsgId = randomUUID();
+    const nowSec = Math.floor(Date.now() / 1000);
+    const explicitReplyTo = typeof body['replyTo'] === 'string' && body['replyTo'] ? body['replyTo'] : null;
+    const replyTo = explicitReplyTo ?? (await history(chatId, 1)).at(-1)?.msgId ?? null;
+    await recordUser({ chatId, msgId, sender: ctx.caller.id, text, ts: nowSec, replyToId: replyTo });
+    const messages = await buildChain(msgId, { chatId });
+    const { connector, recorded } = makeStreamingConnector({
+        chatId,
+        botMsgId,
+        emit: ctx.emit,
+        display: await loadReasoningDisplay(),
+    });
+    const volatileSystem = pageContext(body['context']);
+    await doHandle(connector, {
+        connectorId: 'webchat',
+        channelSystem: WEB_FORMAT,
+        ...(volatileSystem ? { volatileSystem } : {}),
+        chatId,
+        sender: { id: ctx.caller.id },
+        messages,
+    }, { policy: policy() });
+    ctx.emit('done', { msgId: recorded(), parentMsgId: msgId });
+}

package/dist/runtime/settings.d.ts

@@ -0,0 +1,3 @@
+export type ReasoningDisplay = 'off' | 'live';
+export declare function toReasoningDisplay(v: unknown): ReasoningDisplay;
+export declare function loadReasoningDisplay(): Promise<ReasoningDisplay>;

package/dist/runtime/settings.js

@@ -0,0 +1,7 @@
+import { getPluginSettings } from '@coffer-org/server/plugin-runtime';
+export function toReasoningDisplay(v) {
+    return v === 'off' ? 'off' : 'live';
+}
+export async function loadReasoningDisplay() {
+    return toReasoningDisplay((await getPluginSettings('webchat'))['reasoning_display']);
+}