@coffer-org/server 3.4.0 → 5.0.0

package/dist/orchestrator/types.d.ts

@@ -0,0 +1,141 @@
+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;
+    context?: string;
+    attachments?: AttachmentRef[];
+    sender?: string | null;
+    msgId: string;
+    ts: number;
+}
+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: string;
+    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;
+    turnContext?: 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-injection.d.ts

@@ -1,7 +1,7 @@
 import type { EntityManager } from '@mikro-orm/core';
 import { type LayoutEl } from '@coffer-org/sdk/fields';
-import { type RefState } from './part-ref.ts';
-type Row = Record<string, unknown>;
+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 {
@@ -14,8 +14,7 @@ export interface PartCtx {
     em?: EntityManager;
     memo?: PartMemo;
     refs?: RefState;
+    now?: string;
 }
-export declare function injectParts(fields: LayoutEl[], row: Row, ctx: PartCtx): Promise<Row>;
 export declare function hasStoredPartWork(fields: LayoutEl[]): boolean;
 export declare function applyStoredParts(fields: LayoutEl[], row: Row, ctx: PartCtx): Promise<Row>;
-export {};

package/dist/part-injection.js

@@ -1,358 +1,25 @@
-import { isField, isGroup, isCollectionGroup } from '@coffer-org/sdk/fields';
-import { mandatedClientParts } from '@coffer-org/sdk/parts';
-import { PartContractError } from "./part-errors.js";
-import { createRefLoader } from "./part-ref.js";
+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();
-class NeedsCompletion extends Error {
-    scope;
-    key;
-    constructor(scope, key) {
-        super(`needs completion: ${key}`);
-        this.scope = scope;
-        this.key = key;
-    }
-}
-let scopeUid = 0;
-async function partValue(p, ctx) {
-    return typeof p.value === 'function' ? await p.value(ctx) : p.value;
-}
-function rethrowLoud(e) {
-    if (e instanceof PartContractError || e instanceof NeedsCompletion)
-        throw e;
-}
-function isComputeUnit(fm) {
-    return Boolean(fm.parts?.length) || (fm.virtual === true && fm.compute !== undefined);
-}
-const unitsCache = new WeakMap();
-function scopeUnits(fields) {
-    const cached = unitsCache.get(fields);
-    if (cached)
-        return cached;
-    const out = new Map();
-    const scan = (list) => {
-        for (const it of list) {
-            if (isField(it)) {
-                if (isComputeUnit(it.type))
-                    out.set(it.key, it.type);
-            }
-            else if (isGroup(it) && !it.key)
-                scan(it.fields);
-        }
-    };
-    scan(fields);
-    unitsCache.set(fields, out);
-    return out;
-}
-const embeddedCache = new WeakMap();
-function scopeEmbedded(fields) {
-    const cached = embeddedCache.get(fields);
-    if (cached)
-        return cached;
-    const out = new Map();
-    const scan = (list) => {
-        for (const it of list) {
-            if (!isGroup(it))
-                continue;
-            if (!it.key)
-                scan(it.fields);
-            else if (!isCollectionGroup(it))
-                out.set(it.key, it.fields);
-        }
-    };
-    scan(fields);
-    embeddedCache.set(fields, out);
-    return out;
-}
-const relationsCache = new WeakMap();
-function levelRelations(fields) {
-    const cached = relationsCache.get(fields);
-    if (cached)
-        return cached;
-    const out = new Map();
-    const scan = (list) => {
-        for (const it of list) {
-            if (isField(it)) {
-                if (it.type.relation)
-                    out.set(it.key, it.type);
-            }
-            else if (isGroup(it) && !it.key)
-                scan(it.fields);
-        }
-    };
-    scan(fields);
-    relationsCache.set(fields, out);
-    return out;
-}
-function childScope(scope, key) {
-    const existing = scope.groups.get(key);
-    if (existing)
-        return existing;
-    const sub = scope.embedded.get(key);
-    if (!sub)
-        return null;
-    const cur = scope.obj[key];
-    if (!isPlainObject(cur))
-        return null;
-    const copy = { ...cur };
-    scope.obj[key] = copy;
-    const child = newScope(scope.st, copy, sub, `${scope.path}${key}.`, scope.level, scope.level.label);
-    scope.groups.set(key, child);
-    return child;
-}
-function makeProxy(scope) {
-    return new Proxy(scope.obj, {
-        get(target, prop, receiver) {
-            if (typeof prop === 'string') {
-                if (scope.units.has(prop) && scope.status.get(prop) !== 'done')
-                    throw new NeedsCompletion(scope, prop);
-                const child = childScope(scope, prop);
-                if (child)
-                    return child.proxy;
-            }
-            return Reflect.get(target, prop, receiver);
-        },
-    });
-}
-function newScope(st, obj, fields, path, level, label) {
-    const scope = {
-        st,
-        uid: ++scopeUid,
-        obj,
-        units: scopeUnits(fields),
-        embedded: scopeEmbedded(fields),
-        status: new Map(),
-        inflight: new Map(),
-        path,
-        level: level,
-        proxy: null,
-        groups: new Map(),
-    };
-    scope.proxy = makeProxy(scope);
-    if (!level)
-        scope.level = { fields, scope, proxy: scope.proxy, label };
-    return scope;
-}
-function refsOf(st) {
-    if (!st.refs) {
-        st.refs = {
-            chain: st.selfKey ? [st.selfKey] : [],
-            loader: createRefLoader((m, record, refs) => injectParts(m.fields, record, {
-                settings: {},
-                global: {},
-                meta: { library: m.library, shelf: m.shelf },
-                ...(st.ctx.em ? { em: st.ctx.em } : {}),
-                refs,
-            }), st.ctx.em),
-        };
-    }
-    return st.refs;
-}
-function siteOf(field, role) {
-    return role ? `'${field}.${role}'` : `'${field}'`;
-}
-function refFor(scope, key, field, role) {
-    const level = scope.level;
-    const fm = levelRelations(level.fields).get(key);
-    if (!fm?.relation) {
-        const known = [...levelRelations(level.fields).keys()];
-        throw new PartContractError(`ctx.ref('${key}') in ${scope.st.ctx.meta.library}/${scope.st.ctx.meta.shelf} ${siteOf(field, role)}: ` +
-            `'${key}' is not a relation field of ${level.label} ` +
-            `(relation fields there: ${known.length ? known.map((k) => `'${k}'`).join(', ') : 'none'}). ` +
-            `ctx.ref takes the KEY of a relation declared next to this field, not a path.`);
-    }
-    if (fm.hints?.['multi'] === true || fm.hints?.['multiple'] === true) {
-        throw new PartContractError(`ctx.ref('${key}') in ${scope.st.ctx.meta.library}/${scope.st.ctx.meta.shelf} ${siteOf(field, role)}: ` +
-            `'${key}' is a MULTIPLE relation — ctx.ref resolves one record, not a list.`);
-    }
-    const raw = level.scope.obj[key];
-    if (raw == null || raw === '')
-        return Promise.resolve(null);
-    const id = typeof raw === 'number' ? raw : Number(raw);
-    if (!Number.isInteger(id))
-        return Promise.resolve(null);
-    const refs = refsOf(scope.st);
-    return refs.loader.load(fm.relation.library, fm.relation.shelf, id, refs.chain);
-}
-function storedRefError(scope, key, field, role) {
-    const { library, shelf } = scope.st.ctx.meta;
-    return new PartContractError(`ctx.ref('${key}') in ${library}/${shelf} ${siteOf(field, role)}: a computed-AND-STORED part must not read ` +
-        `another record. Its column is written once, at write time, and nothing recomputes it when the record it ` +
-        `read changes — the value would be stale and look authoritative. Drop the part's 'key' so the value is ` +
-        `computed on every read instead.`);
-}
-function computeCtxFor(scope, self, stored, field, role) {
-    const st = scope.st;
-    return {
-        record: st.recordLevel.proxy,
-        parent: scope.level.proxy,
-        settings: st.ctx.settings,
-        global: st.ctx.global,
-        meta: st.ctx.meta,
-        self,
-        ref: stored
-            ? (key) => {
-                throw storedRefError(scope, key, field, role);
-            }
-            : (key) => refFor(scope, key, field, role),
-    };
-}
-async function completeValue(scope, key, fm, value, idx) {
-    if (value == null || typeof value !== 'object' || Array.isArray(value))
-        return value;
-    const st = scope.st;
-    const write = st.mode === 'write';
-    const self = { ...value };
-    const scopeId = `${st.ctx.meta.library}/${st.ctx.meta.shelf}`;
-    const path = idx === undefined ? `${scopeId}|${scope.path}${key}` : `${scopeId}|${scope.path}${key}.${idx}`;
-    const contextOnly = [];
-    for (const p of fm.parts) {
-        if (p.mode !== 'pinned' && p.mode !== 'computed')
-            continue;
-        if (write)
-            contextOnly.push(p.role);
-        const memoKey = `${path}|${p.role}`;
-        if (st.memo.has(memoKey)) {
-            self[p.role] = st.memo.get(memoKey);
-            continue;
-        }
-        try {
-            const v = await partValue(p, computeCtxFor(scope, self, false, key, p.role));
-            self[p.role] = v;
-            st.memo.set(memoKey, v);
-        }
-        catch (e) {
-            rethrowLoud(e);
-            console.warn(`[${write ? 'part-compute' : 'part-injection'}] '${key}.${p.role}' threw`, e);
-        }
-    }
-    if (write) {
-        for (const p of fm.parts) {
-            if (p.mode !== 'computedStored')
-                continue;
-            try {
-                self[p.key] = await partValue(p, computeCtxFor(scope, self, true, key, p.role));
-            }
-            catch (e) {
-                rethrowLoud(e);
-                console.warn(`[part-compute] '${key}.${p.role}' threw`, e);
-            }
-        }
-        if (contextOnly.length)
-            st.strip.push({ value: self, roles: contextOnly });
-    }
-    return self;
-}
-function materializable(fm) {
-    const parts = fm.parts ?? [];
-    if (!parts.some((p) => p.mode === 'computedStored'))
-        return false;
-    if (mandatedClientParts(fm.required, parts).length > 0)
-        return false;
-    return true;
-}
-function storedFilled(fm, value) {
-    if (value == null || typeof value !== 'object')
-        return false;
-    const v = value;
-    return (fm.parts ?? []).some((p) => p.key && v[p.key] != null && v[p.key] !== '');
-}
-function isPlainObject(v) {
-    return v != null && typeof v === 'object' && !Array.isArray(v);
-}
-async function runVirtualField(scope, key, fm) {
-    if (scope.st.mode === 'write') {
-        delete scope.obj[key];
-        return;
-    }
-    try {
-        scope.obj[key] = await partValue({ value: fm.compute }, computeCtxFor(scope, {}, false, key, ''));
-    }
-    catch (e) {
-        rethrowLoud(e);
-        console.warn(`[part-injection] '${key}' threw`, e);
-    }
-}
-async function runFieldUnit(scope, key, fm) {
-    if (fm.virtual === true && fm.compute !== undefined)
-        return runVirtualField(scope, key, fm);
-    if (!fm.parts?.length)
-        return;
-    const value = scope.obj[key];
-    if (value == null) {
-        if (scope.st.mode !== 'write' || fm.hints?.['multiple'] === true || !materializable(fm))
-            return;
-        const made = await completeValue(scope, key, fm, {}, undefined);
-        if (storedFilled(fm, made))
-            scope.obj[key] = made;
-        return;
-    }
-    if (fm.hints?.['multiple'] === true) {
-        if (!Array.isArray(value))
-            return;
-        const out = [];
-        for (const [i, v] of value.entries())
-            out.push(await completeValue(scope, key, fm, v, i));
-        scope.obj[key] = out;
-        return;
-    }
-    scope.obj[key] = await completeValue(scope, key, fm, value, undefined);
-}
-async function completeUnit(scope, key, chain) {
+async function completeUnit(scope, key) {
     if (scope.status.get(key) === 'done')
         return;
     const fm = scope.units.get(key);
     if (!fm)
         return;
-    const hop = `${scope.uid}:${key}`;
-    const repeat = chain.indexOf(hop);
-    if (repeat !== -1) {
-        const names = [...chain.slice(repeat), hop].map((h) => `'${h.slice(h.indexOf(':') + 1)}'`);
-        throw new PartContractError(`[part-injection] ${scope.st.ctx.meta.library}/${scope.st.ctx.meta.shelf}: completion cycle ${names.join(' → ')}` +
-            ` — these composite parts read each other, so neither can be completed first.`);
-    }
-    const inflight = scope.inflight.get(key);
-    if (inflight)
-        return inflight;
-    const next = [...chain, hop];
-    const run = (async () => {
-        const resolved = new Set();
-        for (;;) {
-            try {
-                await runFieldUnit(scope, key, fm);
-                break;
-            }
-            catch (e) {
-                if (!(e instanceof NeedsCompletion))
-                    throw e;
-                const dep = `${e.scope.uid}:${e.key}`;
-                if (resolved.has(dep))
-                    throw new PartContractError(`[part-injection] ${scope.st.ctx.meta.library}/${scope.st.ctx.meta.shelf}: '${key}' demands '${e.key}' ` +
-                        `again after it was completed — its compute function cannot make progress (a stale suspension held ` +
-                        `across invocations, or a value object read outside the context it was handed).`);
-                resolved.add(dep);
-                await completeUnit(e.scope, e.key, next);
-            }
-        }
-        scope.status.set(key, 'done');
-    })();
-    scope.inflight.set(key, run);
-    try {
-        await run;
-    }
-    finally {
-        scope.inflight.delete(key);
-    }
+    await runFieldUnit(scope, key, fm);
+    scope.status.set(key, 'done');
 }
 async function driveScope(scope, fields) {
     for (const it of fields) {
-        if (isField(it)) {
+        if (isNamedField(it)) {
             if (!isComputeUnit(it.type))
                 continue;
-            await completeUnit(scope, it.key, []);
+            await completeUnit(scope, it.key);
         }
-        else if (isGroup(it)) {
+        else if (hasChildren(it)) {
             const sub = it.fields;
-            if (!it.key) {
+            if (!isStorageGroup(it)) {
                 await driveScope(scope, sub);
             }
             else if (isCollectionGroup(it)) {
@@ -362,7 +29,7 @@ async function driveScope(scope, fields) {
                 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}'`)
+                    ? runScope(scope.st, row, sub, [...scope.path, it.key, i], null, `collection row '${it.key}'`)
                     : Promise.resolve(row)));
             }
             else {
@@ -372,7 +39,7 @@ async function driveScope(scope, fields) {
                     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);
+                    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;
@@ -393,56 +60,46 @@ 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)) {
-            if (it.type.virtual === true && it.type.compute !== undefined)
-                found.unstored = true;
-            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;
 }
-async function runWalk(fields, row, ctx, mode) {
+async function runWalk(fields, row, ctx) {
     const id = row['id'] ?? row['base_id'];
     const st = {
         ctx,
-        mode,
+        mode: 'write',
         memo: ctx.memo ?? newPartMemo(),
         refs: ctx.refs ?? null,
-        strip: [],
         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}`);
+    const scope = newScope(st, { ...row }, fields, [], null, `${ctx.meta.library}/${ctx.meta.shelf}`);
     st.recordLevel = scope.level;
     await driveScope(scope, fields);
-    for (const s of st.strip)
-        for (const role of s.roles)
-            delete s.value[role];
     return scope.obj;
 }
-export async function injectParts(fields, row, ctx) {
-    if (!partWork(fields).unstored)
-        return row;
-    return runWalk(fields, row, ctx, 'read');
-}
 export function hasStoredPartWork(fields) {
     return partWork(fields).computedStored;
 }
 export async function applyStoredParts(fields, row, ctx) {
     if (!partWork(fields).computedStored)
         return row;
-    return runWalk(fields, row, ctx, 'write');
+    return runWalk(fields, row, ctx);
 }

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