@coffer-org/server 3.4.0 → 5.0.0

package/dist/mcp-tools.js

@@ -1,6 +1,7 @@
+import { createHash } from 'node:crypto';
 import { z } from 'zod';
-import { buildTools } from '@coffer-org/mcp';
-import { SchemaCache } from '@coffer-org/mcp/schema';
+import { buildTools } from "./mcp-contract/tools.js";
+import { SchemaCache } from "./mcp-contract/schema.js";
 import { LocalClient } from "./mcp-local.js";
 import { frontendInstructions } from "./frontend-agent.js";
 import { mintUploadTicket } from "./upload-ticket.js";
@@ -81,7 +82,7 @@ export async function collectMcpTools(opts = {}) {
                     how_to: `curl -H "Authorization: Bearer <token>" -F "file=@<path>" ${uploadUrl}  →  {"name":"<name>"}. Then set a file field to {"name":"<name>"}. mime/size are filled in by the server — do not send your own.` +
                         (base
                             ? ''
-                            : " The server has no public URL configured (core settings publicUrl / PUBLIC_URL env), so the path is relative — resolve it against this MCP server's own origin."),
+                            : " The server has no public URL configured (system settings publicUrl / PUBLIC_URL env), so the path is relative — resolve it against this MCP server's own origin."),
                 });
             },
         });
@@ -204,7 +205,7 @@ export async function collectMcpTools(opts = {}) {
             server: 'coffer',
             bareName: 'list_settings',
             httpName: 'list_settings',
-            description: 'List every plugin and system settings group (including "core"): each field\'s key/kind/required and the current values (secrets masked). Call before update_settings.',
+            description: "List every settings group (the instance's own `system` group and each plugin's): each field's key/kind/required and the current values (secrets masked). Call before update_settings.",
             inputSchema: {},
             scope: 'settings',
             role: 'admin',
@@ -221,13 +222,13 @@ export async function collectMcpTools(opts = {}) {
             server: 'coffer',
             bareName: 'update_settings',
             httpName: 'update_settings',
-            description: 'Update a plugin or system settings group. plugin — the plugin id (e.g. "claude-agent", "core"); fields — only the settings to change (see list_settings). Send real secret values; the masked placeholder (********) is treated as unchanged.',
-            inputSchema: { plugin: z.string(), fields: z.record(z.string(), z.unknown()) },
+            description: 'Update a plugin or system settings group. group — the settings group id (e.g. "system", "claude-agent"); fields — only the settings to change (see list_settings). Send real secret values; the masked placeholder (********) is treated as unchanged.',
+            inputSchema: { group: z.string(), fields: z.record(z.string(), z.unknown()) },
             scope: 'settings',
             role: 'admin',
             handler: async (args) => {
                 try {
-                    const row = await writePluginSettings(getEm().fork(), args.plugin, args.fields, actor);
+                    const row = await writePluginSettings(getEm().fork(), args.group, args.fields, actor);
                     return ok(row);
                 }
                 catch (e) {
@@ -239,7 +240,7 @@ export async function collectMcpTools(opts = {}) {
                         return fail(`Validation error:\n${lines.join('\n')}`);
                     }
                     if (e instanceof NotFoundError)
-                        return fail(`Plugin '${String(args.plugin)}' has no settings.`);
+                        return fail(`No settings group '${String(args.group)}'.`);
                     return fail(`Error: ${e.message}`);
                 }
             },
@@ -304,6 +305,10 @@ export function collectLibraryPurposes(reg) {
             : []),
     }));
 }
+export async function siteSection(siteUrl) {
+    const site = await frontendInstructions(siteUrl);
+    return site ? `## web\n${site}` : null;
+}
 export async function buildDomainSections() {
     const libraries = collectLibraryPurposes();
     let overview = null;
@@ -340,14 +345,39 @@ export async function buildDomainSections() {
         'For duplicates, read both records completely, compare fields/collections/extends/attachments, recommend the less complete record for trash, and offer a field-by-field merge first. ' +
         'Use list_trash and restore_record for recovery; purge_record is irreversible and requires explicit confirmation.';
     const rules = (await collectPluginInstructions()).map(({ id, instructions }) => `## ${id}\n${instructions}`);
-    const site = await frontendInstructions();
-    return [
-        dataModel,
-        ...(overview ? [overview] : []),
-        ...(singleSection ? [singleSection] : []),
-        ...(site ? [`## web\n${site}`] : []),
-        ...rules,
-    ];
+    return [dataModel, ...(overview ? [overview] : []), ...(singleSection ? [singleSection] : []), ...rules];
+}
+export async function collectStarterHints(hooks = pluginHooks, emFactory = () => getEm().fork(), reg) {
+    const parts = [];
+    for (const [id, h] of Object.entries(hooks)) {
+        const hint = h.agent?.starterHint;
+        if (hint == null)
+            continue;
+        try {
+            const text = typeof hint === 'function' ? await hint(pluginCtx(id, emFactory())) : hint;
+            if (text)
+                parts.push(`- ${id}: ${text}`);
+        }
+        catch (e) {
+            log.warn(`plugin ${id}: starterHint skipped — ${e.message}`);
+        }
+    }
+    let registry = reg;
+    if (!registry) {
+        try {
+            registry = getActiveRegistry();
+        }
+        catch {
+            registry = undefined;
+        }
+    }
+    for (const v of registry?.libraries ?? []) {
+        if (v.meta.starterHint)
+            parts.push(`- ${v.meta.id}: ${v.meta.starterHint}`);
+    }
+    const combined = parts.join('\n');
+    const hash = createHash('sha1').update(combined).digest('hex');
+    return { combined, hash };
 }
 export function buildMcpInstructions(sections) {
     const base = [

package/dist/migrations.d.ts

@@ -29,6 +29,11 @@ export type OpRecorder = (op: MigrationOp) => void;
 export declare function describeMigrationConcerns(plugin: string, version: number, ops: MigrationOp[]): string | null;
 export declare function makeTable(em: EntityManager, table: string, record?: OpRecorder): TableOps;
 export declare function renameSystemShelfKey(em: EntityManager): Promise<void>;
+export declare const SYSTEM_MIGRATIONS: {
+    name: string;
+    up(em: EntityManager): Promise<void>;
+}[];
+export declare function runSystemMigrations(em: EntityManager): Promise<void>;
 export declare function validateMigrations(pluginId: string, list: Migration[]): void;
 interface RunArgs {
     em: EntityManager;

package/dist/migrations.js

@@ -1,6 +1,8 @@
 import { DatabaseSchema } from '@mikro-orm/sql';
+import { fieldEntries } from '@coffer-org/sdk/shelf';
 import { dialectOf } from "./dialect.js";
 import { getLogger } from '@coffer-org/sdk/logger';
+import { SYSTEM_SETTINGS } from "./system-settings.js";
 const log = getLogger('migrations');
 function sqlType(col) {
     if (col === 'integer' || col === 'boolean')
@@ -392,6 +394,126 @@ export function makeTable(em, table, record) {
 export async function renameSystemShelfKey(em) {
     await makeTable(em, '_embeddings').renameColumn('type', 'shelf_key');
 }
+const LEGACY_ORCHESTRATOR_FIELDS = ['agent_id', 'access_password', 'trigger_prefix', 'reply_window'];
+export const SYSTEM_MIGRATIONS = [
+    {
+        name: 'embeddings-shelf-key',
+        up: renameSystemShelfKey,
+    },
+    {
+        name: 'core-settings-to-system',
+        up: async (em) => {
+            const conn = em.getConnection();
+            const src = await introspectTable(em, '_settings__core');
+            const dst = await introspectTable(em, '_settings__system');
+            if (!src.exists || !dst.exists)
+                return;
+            const already = (await conn.execute(`SELECT 1 FROM "_settings__system" WHERE "plugin_id" = 'system' LIMIT 1`));
+            if (already.length > 0)
+                return;
+            const rows = (await conn.execute(`SELECT * FROM "_settings__core" WHERE "plugin_id" = 'core' LIMIT 1`));
+            const row = rows[0];
+            if (!row)
+                return;
+            const carried = ['publicUrl', 'language'].filter((c) => src.columns.has(c) && dst.columns.has(c));
+            if (carried.length === 0)
+                return;
+            const cols = ['plugin_id', ...carried];
+            const values = ['system', ...carried.map((c) => row[c] ?? null)];
+            await conn.execute(`INSERT INTO "_settings__system" (${cols.map((c) => `"${c}"`).join(', ')}) ` +
+                `VALUES (${cols.map(() => '?').join(', ')})`, values);
+            log.info(`[system-migration] settings moved from _settings__core to _settings__system`);
+        },
+    },
+    {
+        name: 'core-state-to-system',
+        up: async (em) => {
+            const conn = em.getConnection();
+            if (!(await introspectTable(em, '_plugin_state')).exists)
+                return;
+            await conn.execute(`UPDATE "_plugin_state" SET "plugin" = 'system' ` +
+                `WHERE "plugin" = 'core' ` +
+                `AND "key" NOT IN (SELECT "key" FROM "_plugin_state" WHERE "plugin" = 'system')`);
+            await conn.execute(`DELETE FROM "_plugin_state" WHERE "plugin" = 'core'`);
+        },
+    },
+    {
+        name: 'drop-legacy-core-settings',
+        up: async (em) => {
+            const conn = em.getConnection();
+            if (!(await introspectTable(em, '_settings__core')).exists)
+                return;
+            if (!(await introspectTable(em, '_settings__system')).exists)
+                return;
+            const landed = (await conn.execute(`SELECT 1 FROM "_settings__system" WHERE "plugin_id" = 'system' LIMIT 1`));
+            if (landed.length === 0)
+                return;
+            await conn.execute(`DROP TABLE IF EXISTS "_settings__core"`);
+            log.info('[system-migration] dropped the legacy _settings__core table');
+        },
+    },
+    {
+        name: 'orchestrator-settings-to-system',
+        up: async (em) => {
+            const DEFAULTS = Object.fromEntries(fieldEntries(SYSTEM_SETTINGS.fields)
+                .filter(([k]) => LEGACY_ORCHESTRATOR_FIELDS.includes(k))
+                .map(([k, f]) => [k, f.default]));
+            const conn = em.getConnection();
+            const src = await introspectTable(em, '_settings__orchestrator');
+            const dst = await introspectTable(em, '_settings__system');
+            if (!src.exists || !dst.exists)
+                return;
+            const carried = LEGACY_ORCHESTRATOR_FIELDS.filter((c) => src.columns.has(c) && dst.columns.has(c));
+            if (carried.length === 0)
+                return;
+            const rows = (await conn.execute(`SELECT * FROM "_settings__orchestrator" WHERE "plugin_id" = 'orchestrator' LIMIT 1`));
+            const row = rows[0];
+            if (!row)
+                return;
+            let wrote = false;
+            for (const c of carried) {
+                const value = row[c];
+                if (value === undefined || value === null)
+                    continue;
+                const def = DEFAULTS[c];
+                const whereExtra = def === undefined ? `${q(c)} IS NULL` : `(${q(c)} IS NULL OR ${q(c)} = ?)`;
+                const params = def === undefined ? [value] : [value, def];
+                await conn.execute(`UPDATE "_settings__system" SET ${q(c)} = ? WHERE "plugin_id" = 'system' AND ${whereExtra}`, params);
+                wrote = true;
+            }
+            if (wrote)
+                log.info('[system-migration] orchestrator settings carried into _settings__system');
+        },
+    },
+    {
+        name: 'drop-legacy-orchestrator-settings',
+        up: async (em) => {
+            const conn = em.getConnection();
+            const src = await introspectTable(em, '_settings__orchestrator');
+            const dst = await introspectTable(em, '_settings__system');
+            if (!src.exists || !dst.exists)
+                return;
+            const fields = LEGACY_ORCHESTRATOR_FIELDS;
+            const srcRows = (await conn.execute(`SELECT * FROM "_settings__orchestrator" WHERE "plugin_id" = 'orchestrator' LIMIT 1`));
+            const srcRow = srcRows[0];
+            const needsLanding = fields.filter((c) => src.columns.has(c) && srcRow?.[c] !== undefined && srcRow?.[c] !== null);
+            if (needsLanding.length > 0) {
+                const dstRows = (await conn.execute(`SELECT * FROM "_settings__system" WHERE "plugin_id" = 'system' LIMIT 1`));
+                const dstRow = dstRows[0];
+                const landed = needsLanding.every((c) => dst.columns.has(c) && dstRow?.[c] !== undefined && dstRow?.[c] !== null);
+                if (!landed)
+                    return;
+            }
+            await conn.execute(`DROP TABLE IF EXISTS "_settings__orchestrator"`);
+            log.info('[system-migration] dropped the legacy _settings__orchestrator table');
+        },
+    },
+];
+export async function runSystemMigrations(em) {
+    for (const m of SYSTEM_MIGRATIONS) {
+        await m.up(em);
+    }
+}
 export function validateMigrations(pluginId, list) {
     const versions = list.map((m) => m.version).sort((a, b) => a - b);
     versions.forEach((v, i) => {

package/dist/mutate.js

@@ -1,35 +1,70 @@
 import { serialize } from '@mikro-orm/core';
-import { buildZodObject, buildZodObjectPartial, fieldEntries } from '@coffer-org/sdk/shelf';
+import { buildZodObject, buildZodObjectPartial, fieldEntries, collectionGroups } from '@coffer-org/sdk/shelf';
 import { isJsonStored, decodeVmsg } from '@coffer-org/sdk/fields';
 import { resolveFlag } from '@coffer-org/sdk/condition';
-import { applyDerived } from '@coffer-org/sdk/derive';
 import { getEm } from "./db.js";
 import { selectRows } from "./read-rows.js";
 import { normalizeFileFields, dropUnchangedFileFields, touchesFileFields } from "./file-fields.js";
 import { notifyRecordsChanged } from "./index-signal.js";
 import { encodeTemporal, decodeTemporal } from "./temporal.js";
-import { splitCollections, writeCollections, deleteCollections, flattenEmbedded, nestEmbedded, readCollections, } from "./collection-io.js";
-import { injectParts, applyStoredParts, hasStoredPartWork, newPartMemo, } from "./part-injection.js";
+import { splitCollections, writeCollections, deleteCollections, flattenEmbedded, flattenEmbeddedAt, nestEmbedded, readCollections, readCollectionsWithMeta, } from "./collection-io.js";
+import { stripClockKeysDeep, clockValuesOf } from "./cache-clock.js";
+import { refreshCachedUnits } from "./cache-refresh.js";
+import { hasStoredPartWork, newPartMemo } from "./part-injection.js";
+import { changedFields, runTriggers } from "./trigger-queue.js";
+import { getActiveRegistry } from "./registry-context.js";
+import { sameValue } from "./value-compare.js";
 const EMPTY_SETTINGS = {};
 const EMPTY_GLOBAL = {};
 function nowIso() {
     return new Date().toISOString();
 }
-function partCtx(m, memo, em) {
+function partCtx(m, memo, now, em) {
     return {
         settings: EMPTY_SETTINGS,
         global: EMPTY_GLOBAL,
         meta: { library: m.library, shelf: m.shelf },
         ...(memo ? { memo } : {}),
         ...(em ? { em } : {}),
+        ...(now !== undefined ? { now } : {}),
     };
 }
-async function mergeStoredParts(m, record, memo, em) {
-    const computed = await applyStoredParts(m.fields, record, partCtx(m, memo, em));
-    if (computed === record)
-        return false;
-    Object.assign(record, computed);
-    return true;
+async function driveTriggers(m, before, after, memo, now, em, opts = {}) {
+    const changed = changedFields(before, after, m.fields);
+    const graph = getActiveRegistry().mutateGraph;
+    const shelfKey = `${m.library}/${m.shelf}`;
+    const preTrigger = { ...after };
+    const touched = [];
+    const triggered = await runTriggers(m.fields, after, changed, graph, shelfKey, partCtx(m, memo, now, em), {
+        ...opts,
+        touched,
+    });
+    Object.assign(after, triggered);
+    return { changed: changedFields(preTrigger, after, m.fields).map((c) => c.path.join('.')), touched };
+}
+async function persistUntouchedCollectionDiffs(tx, m, id, patchedKeys, before, beforeMeta, after) {
+    for (const c of collectionGroups(m.fields)) {
+        if (patchedKeys.has(c.key))
+            continue;
+        const beforeRows = before[c.key] ?? [];
+        const afterRows = after[c.key] ?? [];
+        const metas = beforeMeta[c.key] ?? [];
+        const childFields = c.group.fields;
+        const table = `${m.library}__${m.shelf}__${c.key}`;
+        const n = Math.min(beforeRows.length, afterRows.length, metas.length);
+        for (let i = 0; i < n; i++) {
+            const rowId = metas[i].id;
+            const flatBefore = encodeJsonAt(childFields, flattenEmbeddedAt(childFields, beforeRows[i]));
+            const flatAfter = encodeJsonAt(childFields, flattenEmbeddedAt(childFields, afterRows[i]));
+            const rowPatch = {};
+            for (const [k, v] of Object.entries(flatAfter)) {
+                if (!sameValue(flatBefore[k] ?? null, v ?? null))
+                    rowPatch[k] = v ?? null;
+            }
+            if (Object.keys(rowPatch).length > 0)
+                await tx.nativeUpdate(table, { id: rowId }, rowPatch);
+        }
+    }
 }
 export function encodeJsonAt(fields, data) {
     const out = { ...data };
@@ -84,10 +119,11 @@ export async function getRecord(m, entityName, id, opts = {}) {
     if (!row)
         return undefined;
     const flat = decodeTemporal(m, row);
+    const clocks = clockValuesOf(flat);
     const nested = nestEmbedded(m, flat);
-    const collections = await readCollections(fork, m, id);
+    const { collections, meta } = await readCollectionsWithMeta(fork, m, id);
     const record = { ...nested, ...collections };
-    return injectParts(m.fields, record, partCtx(m));
+    return refreshCachedUnits(m, entityName, record, clocks, meta, partCtx(m));
 }
 export async function createRecord(m, entityName, input, ctx, afterBase) {
     const parsed = buildZodObject(m).safeParse(input);
@@ -99,7 +135,9 @@ export async function createRecord(m, entityName, input, ctx, afterBase) {
     if (fileIssues.length)
         throw new ValidationError(fileIssues);
     const memo = newPartMemo();
-    await mergeStoredParts(m, parsedData, memo);
+    const triggerResult = hasStoredPartWork(m.fields)
+        ? await driveTriggers(m, {}, parsedData, memo, ts, undefined, { seedAll: true })
+        : { changed: [], touched: [] };
     const { base, collections } = splitCollections(m, { ...parsedData });
     const data = encodeJson(m, encodeTemporal(m, flattenEmbedded(m, { ...base, created_at: ts, updated_at: ts })));
     let id;
@@ -110,21 +148,16 @@ export async function createRecord(m, entityName, input, ctx, afterBase) {
         await tx.flush();
         id = entity.id;
         await writeCollections(tx, m, id, collections);
-        const derived = await applyDerived(m.fields, { ...parsedData, id });
-        if (Object.keys(derived).length) {
-            await tx.nativeUpdate(entityName, { id }, encodeJson(m, encodeTemporal(m, flattenEmbedded(m, derived))));
-            Object.assign(parsedData, derived);
-        }
         const _extends = afterBase ? await afterBase(tx, id) : undefined;
-        writeEvent(tx, ctx.actor, 'create', `${m.library}/${m.shelf}`, id, null, {
-            ...parsedData,
-            id,
-            ...(_extends ? { _extends } : {}),
-        });
+        writeEvent(tx, ctx.actor, 'create', `${m.library}/${m.shelf}`, id, null, stripClockKeysDeep(m.fields, { ...parsedData, id, ...(_extends ? { _extends } : {}) }));
     });
     notifyRecordsChanged();
     const record = { ...parsedData, id, created_at: ts, updated_at: ts };
-    return injectParts(m.fields, record, partCtx(m, memo));
+    return {
+        ...stripClockKeysDeep(m.fields, record),
+        changed: triggerResult.changed,
+        ...(triggerResult.touched.length ? { changedRecords: triggerResult.touched } : {}),
+    };
 }
 export async function updateRecord(m, entityName, id, input, ctx, afterBase) {
     let patch = input;
@@ -141,6 +174,7 @@ export async function updateRecord(m, entityName, id, input, ctx, afterBase) {
         throw new ValidationError(parsed.error.issues.map(toIssue));
     const memo = newPartMemo();
     let result;
+    let triggerResult = { changed: [], touched: [] };
     await getEm()
         .fork()
         .transactional(async (tx) => {
@@ -158,7 +192,7 @@ export async function updateRecord(m, entityName, id, input, ctx, afterBase) {
         const merged = { ...existing, ...base };
         const reqIssues = [];
         for (const [key, f] of fieldEntries(m.fields)) {
-            if (f.virtual || f.required === true)
+            if (f.required === true)
                 continue;
             if (key.includes('__'))
                 continue;
@@ -170,30 +204,37 @@ export async function updateRecord(m, entityName, id, input, ctx, afterBase) {
         }
         if (reqIssues.length)
             throw new ValidationError(reqIssues);
-        const storedCollections = hasStoredPartWork(m.fields) ? await readCollections(tx, m, id) : {};
+        const storedWithMeta = hasStoredPartWork(m.fields)
+            ? await readCollectionsWithMeta(tx, m, id)
+            : { collections: {}, meta: {} };
+        const storedCollections = storedWithMeta.collections;
         const target = { ...merged, ...storedCollections, ...collections };
-        if (await mergeStoredParts(m, target, memo, tx)) {
+        if (hasStoredPartWork(m.fields)) {
+            const before = { ...existing, ...storedCollections };
+            triggerResult = await driveTriggers(m, before, target, memo, ts, tx);
             const resplit = splitCollections(m, target);
             Object.assign(merged, resplit.base);
-            for (const k of Object.keys(collections)) {
+            const patchedKeys = new Set(Object.keys(collections));
+            for (const k of patchedKeys) {
                 const rows = resplit.collections[k];
                 if (rows)
                     collections[k] = rows;
             }
+            await persistUntouchedCollectionDiffs(tx, m, id, patchedKeys, storedCollections, storedWithMeta.meta, resplit.collections);
         }
         const dbRow = encodeJson(m, encodeTemporal(m, flattenEmbedded(m, { ...merged, updated_at: ts })));
         await tx.upsert(entityName, dbRow);
         await writeCollections(tx, m, id, collections);
         const allCollections = await readCollections(tx, m, id);
-        const derived = await applyDerived(m.fields, { ...merged, ...allCollections });
-        if (Object.keys(derived).length) {
-            await tx.nativeUpdate(entityName, { id }, encodeJson(m, encodeTemporal(m, flattenEmbedded(m, derived))));
-            Object.assign(merged, derived);
-        }
         const _extends = afterBase ? await afterBase(tx, id) : undefined;
         const after = { ...merged, ...allCollections, updated_at: ts, ...(_extends ? { _extends } : {}) };
+        stripClockKeysDeep(m.fields, after);
         writeEvent(tx, ctx.actor, 'update', `${m.library}/${m.shelf}`, id, existing, after);
-        result = await injectParts(m.fields, after, partCtx(m, memo, tx));
+        result = {
+            ...after,
+            changed: triggerResult.changed,
+            ...(triggerResult.touched.length ? { changedRecords: triggerResult.touched } : {}),
+        };
     });
     notifyRecordsChanged();
     return result;
@@ -228,7 +269,7 @@ export async function restoreRecord(m, entityName, id, ctx, afterBase) {
         const _extends = afterBase ? await afterBase(tx, id) : undefined;
         const restored = { ...nested, ...collections, ...(_extends ? { _extends } : {}) };
         writeEvent(tx, ctx.actor, 'restore', `${m.library}/${m.shelf}`, id, null, restored);
-        result = await injectParts(m.fields, restored, partCtx(m, undefined, tx));
+        result = restored;
     });
     notifyRecordsChanged();
     return result;

package/dist/orchestrator/agent-capabilities.d.ts

@@ -0,0 +1,2 @@
+import type { AgentToolProvider, AttachmentRef } from './types.ts';
+export declare function makeAttachmentCapabilities(attachments: AttachmentRef[]): Promise<AgentToolProvider>;