@coffer-org/server 3.3.0 → 4.0.0

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,7 @@
+import type { SystemLayer } from './types.ts';
+export declare function buildSystem(input: {
+    base: string;
+    channelSystem?: string;
+    volatileSystem?: string;
+    environment?: string;
+}): SystemLayer[];

package/dist/orchestrator/system-assembly.js

@@ -0,0 +1,13 @@
+import { currentEnvironment } from "./environment.js";
+export function buildSystem(input) {
+    const text = [input.base, input.channelSystem].filter(Boolean).join('\n\n');
+    const layers = [{ text, stable: true }];
+    const environment = input.environment ?? currentEnvironment();
+    const volatile = [environment, input.volatileSystem]
+        .map((part) => part?.trim())
+        .filter(Boolean)
+        .join('\n\n');
+    if (volatile)
+        layers.push({ text: volatile, stable: false });
+    return layers;
+}

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] };
+}

package/dist/orchestrator/types.d.ts

@@ -0,0 +1,144 @@
+export interface AttachmentRef {
+    name: string;
+    mime?: string;
+    size?: number;
+    label?: string;
+}
+export interface AgentToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (args: Record<string, unknown>) => Promise<unknown>;
+    forcedAfterAnswer?: boolean;
+}
+export interface AgentToolProvider {
+    tools: AgentToolDefinition[];
+}
+export type AgentToolContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    mime: string;
+    data: string;
+} | {
+    type: 'document';
+    mime: 'application/pdf';
+    data: string;
+};
+export interface AgentToolContentResult {
+    __cofferToolContent: true;
+    content: AgentToolContentBlock[];
+    isError?: boolean;
+}
+export interface ConvMessage {
+    role: 'user' | 'assistant';
+    content: string;
+    attachments?: AttachmentRef[];
+    sender?: string | null;
+    msgId: string;
+    ts: number;
+}
+export interface SystemLayer {
+    text: string;
+    stable: boolean;
+}
+export interface AgentCapabilities {
+    vision?: boolean;
+    documents?: boolean;
+    tools?: boolean;
+    reasoning?: boolean;
+}
+export interface AgentPreset {
+    id: string;
+    title: string;
+    hint?: string;
+    quality?: number;
+    time?: number;
+    default?: boolean;
+    capabilities?: AgentCapabilities;
+}
+export interface AgentDescriptor {
+    id: string;
+    title: string;
+    presets: AgentPreset[];
+}
+export interface AgentRequest {
+    system: SystemLayer[];
+    messages: ConvMessage[];
+    toolProvider?: AgentToolProvider;
+    presetId?: string;
+    onDelta?: (accumulated: string) => void;
+    onReasoning?: (accumulated: string) => void;
+    onSegment?: () => void;
+}
+export interface AgentResult {
+    text: string | null;
+    reasoning: string | null;
+    tokensIn: number | null;
+    tokensOut: number | null;
+    stopReason: string | null;
+    presetId: string | null;
+    suggestions?: string[] | null;
+}
+export interface AgentRuntime {
+    id: string;
+    run(request: AgentRequest): Promise<AgentResult>;
+    systemBase(): Promise<string>;
+    describe(): Promise<AgentDescriptor>;
+    starters?(): Promise<string[]>;
+}
+export interface ConnectorRegistration {
+    id: string;
+}
+export interface AttachmentMaterializer {
+    store(bytes: Uint8Array, opts?: {
+        originalName?: string;
+        mime?: string;
+    }): Promise<AttachmentRef>;
+}
+export interface IncomingConversation {
+    connectorId: string;
+    agentId?: string;
+    presetId?: string;
+    chatId: string;
+    channelSystem?: string;
+    volatileSystem?: string;
+    sender: {
+        id: string;
+        displayName?: string;
+    };
+    messages: ConvMessage[];
+    prepareAttachments?: (materializer: AttachmentMaterializer) => Promise<ConvMessage[]>;
+    supportsSuggestions?: boolean;
+}
+export interface ReplyContext {
+    parentMsgId: string | null;
+}
+export interface ReplyPayload {
+    text: string | null;
+    reasoning: string | null;
+    suggestions: string[] | null;
+}
+export interface ReplyChannel {
+    update(text: string): void;
+    updateReasoning?(acc: string): void;
+    segment(): void;
+    finish(r: ReplyPayload): Promise<string | null>;
+}
+export interface Connector {
+    id: string;
+    reply(chatId: string, ctx: ReplyContext): ReplyChannel;
+    recordAssistant(m: {
+        parentMsgId: string | null;
+        botMsgId: string | null;
+        text: string;
+        reasoning: string | null;
+    }): Promise<void>;
+}
+export interface GatePolicy {
+    agentId?: string;
+    accessPassword: string;
+    triggerPrefix: string;
+    replyWindow: number;
+}

package/dist/orchestrator/types.js

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

package/dist/part-errors.d.ts

@@ -0,0 +1,3 @@
+export declare class PartContractError extends Error {
+    constructor(message: string);
+}

package/dist/part-errors.js

@@ -0,0 +1,6 @@
+export class PartContractError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PartContractError';
+    }
+}

package/dist/part-injection.d.ts

@@ -1,12 +1,20 @@
+import type { EntityManager } from '@mikro-orm/core';
 import { type LayoutEl } from '@coffer-org/sdk/fields';
+import type { RefState } from './part-ref.ts';
+import { type Row } from './compute-unit.ts';
+export type PartMemo = Map<string, unknown>;
+export declare const newPartMemo: () => PartMemo;
 export interface PartCtx {
-    record: Record<string, unknown>;
     settings: Record<string, unknown>;
     global: Record<string, unknown>;
     meta: {
         library: string;
         shelf: string;
     };
+    em?: EntityManager;
+    memo?: PartMemo;
+    refs?: RefState;
+    now?: string;
 }
-export declare function injectParts(fields: LayoutEl[], row: Record<string, unknown>, ctx: PartCtx): Promise<Record<string, unknown>>;
-export declare function applyStoredParts(fields: LayoutEl[], row: Record<string, unknown>, ctx: PartCtx): Promise<Record<string, unknown>>;
+export declare function hasStoredPartWork(fields: LayoutEl[]): boolean;
+export declare function applyStoredParts(fields: LayoutEl[], row: Row, ctx: PartCtx): Promise<Row>;

package/dist/part-injection.js

@@ -1,125 +1,105 @@
-import { isField, isGroup, isCollectionGroup } from '@coffer-org/sdk/fields';
-async function partValue(p, ctx, self) {
-    return typeof p.value === 'function' ? await p.value({ ...ctx, self }) : p.value;
+import { hasChildren, isNamedField, isCollectionGroup, isStorageGroup } from '@coffer-org/sdk/fields';
+import { runFieldUnit, isComputeUnit, childScope, newScope, isPlainObject, } from "./compute-unit.js";
+export const newPartMemo = () => new Map();
+async function completeUnit(scope, key) {
+    if (scope.status.get(key) === 'done')
+        return;
+    const fm = scope.units.get(key);
+    if (!fm)
+        return;
+    await runFieldUnit(scope, key, fm);
+    scope.status.set(key, 'done');
 }
-async function completeOne(key, fm, value, ctx) {
-    if (value == null || typeof value !== 'object' || Array.isArray(value))
-        return value;
-    const self = { ...value };
-    for (const p of fm.parts) {
-        if (p.mode !== 'pinned' && p.mode !== 'computed')
-            continue;
-        try {
-            self[p.role] = await partValue(p, ctx, self);
-        }
-        catch (e) {
-            console.warn(`[part-injection] '${key}.${p.role}' threw`, e);
-        }
-    }
-    return self;
-}
-async function computeOne(key, fm, value, ctx) {
-    if (value == null || typeof value !== 'object' || Array.isArray(value))
-        return value;
-    const self = { ...value };
-    const contextOnly = [];
-    for (const p of fm.parts) {
-        if (p.mode !== 'pinned' && p.mode !== 'computed')
-            continue;
-        contextOnly.push(p.role);
-        try {
-            self[p.role] = await partValue(p, ctx, self);
-        }
-        catch (e) {
-            console.warn(`[part-compute] '${key}.${p.role}' threw`, e);
-        }
-    }
-    for (const p of fm.parts) {
-        if (p.mode !== 'computedStored')
-            continue;
-        try {
-            self[p.key] = await partValue(p, ctx, self);
-        }
-        catch (e) {
-            console.warn(`[part-compute] '${key}.${p.role}' threw`, e);
-        }
-    }
-    for (const role of contextOnly)
-        delete self[role];
-    return self;
-}
-async function walkFields(fields, obj, ctx, complete) {
-    const out = { ...obj };
+async function driveScope(scope, fields) {
     for (const it of fields) {
-        if (isField(it)) {
-            const fm = it.type;
-            if (!fm.parts?.length)
-                continue;
-            const value = out[it.key];
-            if (value == null)
+        if (isNamedField(it)) {
+            if (!isComputeUnit(it.type))
                 continue;
-            if (fm.hints?.['multiple'] === true) {
-                if (!Array.isArray(value))
-                    continue;
-                out[it.key] = await Promise.all(value.map((v) => complete(it.key, fm, v, ctx)));
-            }
-            else {
-                out[it.key] = await complete(it.key, fm, value, ctx);
-            }
+            await completeUnit(scope, it.key);
         }
-        else if (isGroup(it)) {
-            if (!it.key) {
-                Object.assign(out, await walkFields(it.fields, out, ctx, complete));
+        else if (hasChildren(it)) {
+            const sub = it.fields;
+            if (!isStorageGroup(it)) {
+                await driveScope(scope, sub);
             }
             else if (isCollectionGroup(it)) {
-                const rows = out[it.key];
-                if (Array.isArray(rows)) {
-                    out[it.key] = await Promise.all(rows.map((row) => row != null && typeof row === 'object'
-                        ? walkFields(it.fields, row, ctx, complete)
-                        : row));
-                }
+                const rows = scope.obj[it.key];
+                if (!Array.isArray(rows))
+                    continue;
+                const copies = rows.map((row) => (isPlainObject(row) ? { ...row } : row));
+                scope.obj[it.key] = copies;
+                await Promise.all(copies.map((row, i) => isPlainObject(row)
+                    ? runScope(scope.st, row, sub, [...scope.path, it.key, i], null, `collection row '${it.key}'`)
+                    : Promise.resolve(row)));
             }
             else {
-                const sub = out[it.key];
-                if (sub != null && typeof sub === 'object' && !Array.isArray(sub)) {
-                    out[it.key] = await walkFields(it.fields, sub, ctx, complete);
+                const cur = scope.obj[it.key];
+                const child = childScope(scope, it.key);
+                if (child) {
+                    await driveScope(child, sub);
+                }
+                else if (cur == null && scope.st.mode === 'write' && partWork(sub).computedStored) {
+                    const made = newScope(scope.st, {}, sub, [...scope.path, it.key], scope.level, scope.level.label);
+                    await driveScope(made, sub);
+                    if (Object.keys(made.obj).length) {
+                        scope.obj[it.key] = made.obj;
+                        scope.groups.set(it.key, made);
+                    }
                 }
             }
         }
     }
-    return out;
+}
+async function runScope(st, obj, fields, path, level, label) {
+    const scope = newScope(st, obj, fields, path, level, label);
+    await driveScope(scope, fields);
+    return scope.obj;
 }
 const partWorkCache = new WeakMap();
 function partWork(fields) {
     const cached = partWorkCache.get(fields);
     if (cached !== undefined)
         return cached;
-    const found = { unstored: false, computedStored: false };
+    const found = { computedStored: false };
     for (const it of fields) {
-        if (isField(it)) {
-            for (const p of it.type.parts ?? []) {
-                if (p.mode === 'pinned' || p.mode === 'computed')
-                    found.unstored = true;
-                else if (p.mode === 'computedStored')
+        if (isNamedField(it)) {
+            if (it.type.compute !== undefined)
+                found.computedStored = true;
+            for (const p of it.type.parts ?? [])
+                if (p.mode === 'computedStored')
                     found.computedStored = true;
-            }
         }
-        else if (isGroup(it)) {
+        else if (hasChildren(it)) {
+            if (isStorageGroup(it) && it.compute !== undefined)
+                found.computedStored = true;
             const sub = partWork(it.fields);
-            found.unstored ||= sub.unstored;
             found.computedStored ||= sub.computedStored;
         }
     }
     partWorkCache.set(fields, found);
     return found;
 }
-export async function injectParts(fields, row, ctx) {
-    if (!partWork(fields).unstored)
-        return row;
-    return walkFields(fields, row, ctx, completeOne);
+async function runWalk(fields, row, ctx) {
+    const id = row['id'] ?? row['base_id'];
+    const st = {
+        ctx,
+        mode: 'write',
+        memo: ctx.memo ?? newPartMemo(),
+        refs: ctx.refs ?? null,
+        selfKey: typeof id === 'number' ? `${ctx.meta.library}/${ctx.meta.shelf}#${id}` : null,
+        recordLevel: null,
+        now: ctx.now ?? new Date().toISOString(),
+    };
+    const scope = newScope(st, { ...row }, fields, [], null, `${ctx.meta.library}/${ctx.meta.shelf}`);
+    st.recordLevel = scope.level;
+    await driveScope(scope, fields);
+    return scope.obj;
+}
+export function hasStoredPartWork(fields) {
+    return partWork(fields).computedStored;
 }
 export async function applyStoredParts(fields, row, ctx) {
     if (!partWork(fields).computedStored)
         return row;
-    return walkFields(fields, row, ctx, computeOne);
+    return runWalk(fields, row, ctx);
 }

package/dist/part-ref.d.ts

@@ -0,0 +1,13 @@
+import type { EntityManager } from '@mikro-orm/core';
+import type { ShelfDef } from '@coffer-org/sdk/shelf';
+type Row = Record<string, unknown>;
+export type CompleteRef = (m: ShelfDef, record: Row, refs: RefState) => Promise<Row>;
+export interface RefLoader {
+    load(library: string, shelf: string, id: number, chain: readonly string[]): Promise<Row | null>;
+}
+export interface RefState {
+    loader: RefLoader;
+    chain: readonly string[];
+}
+export declare function createRefLoader(complete: CompleteRef, em?: EntityManager): RefLoader;
+export {};

package/dist/part-ref.js

@@ -0,0 +1,109 @@
+import { getEm } from "./db.js";
+import { selectRows } from "./read-rows.js";
+import { nestEmbedded, readAtMany } from "./collection-io.js";
+import { decodeTemporal } from "./temporal.js";
+import { shelfTableName } from "./entity-schema.js";
+import { getShelf } from "./registry-context.js";
+import { chunk } from "./batch.js";
+import { PartContractError } from "./part-errors.js";
+const MAX_REF_DEPTH = 8;
+export function createRefLoader(complete, em) {
+    const cache = new Map();
+    const waiters = new Map();
+    const pending = new Map();
+    let scheduled = false;
+    const loader = { load };
+    function load(library, shelf, id, chain) {
+        const key = `${library}/${shelf}#${id}`;
+        if (chain.includes(key)) {
+            console.warn(`[part-ref] ref loop ${[...chain, key].join(' → ')} — resolved as null. Two records reach each other ` +
+                `through ctx.ref; the value at the far end of the loop cannot be computed.`);
+            return Promise.resolve(null);
+        }
+        if (chain.length >= MAX_REF_DEPTH) {
+            console.warn(`[part-ref] ref chain deeper than ${MAX_REF_DEPTH} hops (${[...chain, key].join(' → ')}) — resolved as null.`);
+            return Promise.resolve(null);
+        }
+        const hit = cache.get(key);
+        if (hit)
+            return hit;
+        const p = new Promise((resolve, reject) => {
+            waiters.set(key, { resolve, reject, chain: [...chain, key] });
+        });
+        p.catch(() => { });
+        cache.set(key, p);
+        const shelfKey = `${library}/${shelf}`;
+        const ids = pending.get(shelfKey);
+        if (ids)
+            ids.push(id);
+        else
+            pending.set(shelfKey, [id]);
+        if (!scheduled) {
+            scheduled = true;
+            queueMicrotask(flush);
+        }
+        return p;
+    }
+    function flush() {
+        scheduled = false;
+        const batches = [...pending];
+        pending.clear();
+        for (const [shelfKey, ids] of batches)
+            void runBatch(shelfKey, ids);
+    }
+    function settle(key, fn) {
+        const w = waiters.get(key);
+        if (!w)
+            return;
+        waiters.delete(key);
+        fn(w);
+    }
+    async function runBatch(shelfKey, ids) {
+        const slash = shelfKey.indexOf('/');
+        const library = shelfKey.slice(0, slash);
+        const shelf = shelfKey.slice(slash + 1);
+        const keyOf = (id) => `${shelfKey}#${id}`;
+        const unique = [...new Set(ids)];
+        try {
+            const m = getShelf(library, shelf);
+            if (!m)
+                throw new PartContractError(`ctx.ref: no shelf '${shelfKey}' in the registry`);
+            const fork = em ?? getEm().fork();
+            const table = shelfTableName(library, shelf);
+            const flats = [];
+            for (const part of chunk(unique)) {
+                flats.push(...(await selectRows(fork, table, { id: { $in: part }, deleted_at: null })));
+            }
+            const foundIds = flats.map((r) => Number(r['id']));
+            const collectionsById = await readAtMany(fork, table, m.fields, foundIds);
+            const seen = new Set();
+            await Promise.all(flats.map(async (flat) => {
+                const id = Number(flat['id']);
+                seen.add(id);
+                const key = keyOf(id);
+                const w = waiters.get(key);
+                if (!w)
+                    return;
+                const record = {
+                    ...nestEmbedded(m, decodeTemporal(m, flat)),
+                    ...(collectionsById.get(id) ?? {}),
+                };
+                try {
+                    const done = await complete(m, record, { loader, chain: w.chain });
+                    settle(key, (x) => x.resolve(done));
+                }
+                catch (e) {
+                    settle(key, (x) => x.reject(e));
+                }
+            }));
+            for (const id of unique)
+                if (!seen.has(id))
+                    settle(keyOf(id), (w) => w.resolve(null));
+        }
+        catch (e) {
+            for (const id of unique)
+                settle(keyOf(id), (w) => w.reject(e));
+        }
+    }
+    return loader;
+}

package/dist/plugin-hooks.d.ts

@@ -42,6 +42,7 @@ export interface AgentTool {
 export interface AgentContribution {
     instructions?: string | ((ctx: PluginCtx) => string | Promise<string>);
     tools?: AgentTool[];
+    starterHint?: string | ((ctx: PluginCtx) => string | Promise<string>);
 }
 export type PluginAction = (body: Record<string, unknown>) => Promise<unknown>;
 export declare class HttpError extends Error {

package/dist/plugin-i18n.js

@@ -3,7 +3,8 @@ const cache = new Map();
 async function systemLanguage(fallback) {
     try {
         const { getPluginSettings } = await import("./plugin-runtime.js");
-        return (await getPluginSettings('core'))['language'] || fallback;
+        const { SYSTEM_SETTINGS_ID } = await import("./system-settings.js");
+        return (await getPluginSettings(SYSTEM_SETTINGS_ID))['language'] || fallback;
     }
     catch {
         return fallback;

package/dist/plugin-runtime.d.ts

@@ -1,9 +1,9 @@
-import { type Registry } from '@coffer-org/core/compose';
+import { type Registry } from '@coffer-org/sdk/compose';
 import type { PluginManifest } from '@coffer-org/sdk/plugin';
 export declare function getPlugins(): Promise<PluginManifest[]>;
 export declare function readDisabled(): Promise<Set<string>>;
 export declare function getDisabled(): Promise<Set<string>>;
-export declare function getPluginSettings(pluginId: string): Promise<Record<string, unknown>>;
+export declare function getPluginSettings(groupId: string): Promise<Record<string, unknown>>;
 export declare function requireSettings<K extends string>(pluginId: string, keys: readonly K[]): Promise<Record<K, string>>;
 export declare function initStorage(): Promise<Set<string>>;
 export declare function initPlugins(): Promise<Registry>;