@coffer-org/server 3.4.0 → 4.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}`);
                 }
             },
@@ -349,6 +350,38 @@ export async function buildDomainSections() {
         ...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 = [
         "Coffer is the user's personal database, organized into libraries (kitchen, people, finance, health, devices, home, garden, documents, travel, and more), each holding typed records.",

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

package/dist/orchestrator/agent-capabilities.js

@@ -0,0 +1,201 @@
+import { collectMcpTools } from "../mcp-tools.js";
+import { LocalClient } from "../mcp-local.js";
+import { inspectUpload } from "./file-inspection.js";
+const ok = (data) => ({
+    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+});
+const fail = (text) => ({ content: [{ type: 'text', text }], isError: true });
+function textOf(result) {
+    const block = result.content.find((b) => b.type === 'text');
+    return block?.type === 'text' ? block.text : '';
+}
+function resultData(result) {
+    try {
+        return JSON.parse(textOf(result));
+    }
+    catch {
+        return undefined;
+    }
+}
+function fieldType(items, key) {
+    for (const item of items) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const raw = item;
+        if (raw.key === key && raw.type)
+            return raw.type;
+        if (raw.kind === 'group' && Array.isArray(raw.fields)) {
+            const nested = fieldType(raw.fields, key);
+            if (nested)
+                return nested;
+        }
+    }
+    return undefined;
+}
+async function findFileField(library, shelf, key) {
+    const schema = (await new LocalClient().getSchema());
+    const lib = schema.find((item) => item.id === library);
+    const sh = lib?.shelves?.find((item) => item.shelf === shelf);
+    return sh?.fields ? fieldType(sh.fields, key) : undefined;
+}
+function parseStoredValue(value) {
+    if (typeof value !== 'string')
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function fileItems(value) {
+    const parsed = parseStoredValue(value);
+    if (Array.isArray(parsed))
+        return parsed.filter((item) => !!item && typeof item === 'object');
+    return parsed && typeof parsed === 'object' ? [parsed] : [];
+}
+function findTool(defs, name) {
+    return defs.find((def) => def.server === 'coffer' && def.bareName === name);
+}
+export async function makeAttachmentCapabilities(attachments) {
+    const defs = await collectMcpTools();
+    const getRecord = findTool(defs, 'get_record');
+    const updateRecord = findTool(defs, 'update_record');
+    const tools = [];
+    if (getRecord) {
+        tools.push({
+            name: 'mcp__coffer__inspect_record_file',
+            description: 'Read an existing file/image/PDF/text item stored in a Coffer record. ' +
+                'Call get_record first, then pass the exact file name from the field value. ' +
+                'Do not use local paths or URLs. If a field contains multiple files, file_name is required.',
+            inputSchema: {
+                library: { type: 'string', description: 'Library identifier, e.g. things' },
+                shelf: { type: 'string', description: 'Shelf identifier, e.g. item' },
+                id: { type: 'integer', description: 'Record id' },
+                field: { type: 'string', description: 'File/image/document field key' },
+                file_name: {
+                    type: 'string',
+                    description: 'Exact stored file name from get_record; required for multiple files',
+                },
+            },
+            handler: async (args) => {
+                const library = String(args['library'] ?? '');
+                const shelf = String(args['shelf'] ?? '');
+                const id = Number(args['id']);
+                const field = String(args['field'] ?? '');
+                if (!library || !shelf || !field || !Number.isInteger(id))
+                    return fail('library, shelf, field and integer id are required');
+                const type = await findFileField(library, shelf, field);
+                if (!type || type.prim !== 'file')
+                    return fail(`Field is not a file field: ${library}/${shelf}.${field}`);
+                const currentResult = await getRecord.handler({ library, shelf, id });
+                if (currentResult.isError)
+                    return currentResult;
+                const current = resultData(currentResult);
+                if (!current || typeof current !== 'object')
+                    return fail(`Record not found: ${library}/${shelf}/${id}`);
+                const existing = fileItems(current[field]);
+                if (!existing.length)
+                    return fail(`Record field is empty: ${library}/${shelf}/${id}.${field}`);
+                const requested = typeof args['file_name'] === 'string' ? args['file_name'] : '';
+                const item = requested
+                    ? existing.find((entry) => entry['name'] === requested)
+                    : existing.length === 1
+                        ? existing[0]
+                        : undefined;
+                if (!item || typeof item['name'] !== 'string') {
+                    const available = existing
+                        .map((entry) => String(entry['name'] ?? ''))
+                        .filter(Boolean)
+                        .join(', ');
+                    return fail(existing.length > 1
+                        ? `Multiple files are stored in this field; file_name is required. Available: ${available}`
+                        : `Stored file was not found in record field: ${requested}`);
+                }
+                return inspectUpload(item['name'], {
+                    ...(typeof item['mime'] === 'string' ? { mime: item['mime'] } : {}),
+                    ...(typeof item['size'] === 'number' ? { size: item['size'] } : {}),
+                });
+            },
+        });
+    }
+    if (!attachments.length || !getRecord || !updateRecord)
+        return { tools };
+    const attach = {
+        name: 'mcp__coffer__attach_conversation_attachments',
+        description: 'Attach files already received in the current conversation to a file/image/document field in a Coffer record. ' +
+            'Use attachment_names for selected files, or omit it to attach every current-conversation attachment. ' +
+            'The default mode appends to a multiple field; use mode="replace" only when explicitly requested. ' +
+            'This is the unified attachment tool for every connector — never use a local path or invent an upload name.',
+        inputSchema: {
+            library: { type: 'string', description: 'Library identifier, e.g. things' },
+            shelf: { type: 'string', description: 'Shelf identifier, e.g. item' },
+            id: { type: 'integer', description: 'Record id' },
+            field: { type: 'string', description: 'File/image/document field key' },
+            attachment_names: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Exact server-generated names from the current conversation; omit to use all attachments',
+            },
+            mode: {
+                type: 'string',
+                enum: ['append', 'replace'],
+                description: 'append by default; replace only on explicit request',
+            },
+        },
+        handler: async (args) => {
+            const library = String(args['library'] ?? '');
+            const shelf = String(args['shelf'] ?? '');
+            const id = Number(args['id']);
+            const field = String(args['field'] ?? '');
+            const mode = args['mode'] === 'replace' ? 'replace' : 'append';
+            if (!library || !shelf || !field || !Number.isInteger(id))
+                return fail('library, shelf, field and integer id are required');
+            const names = Array.isArray(args['attachment_names'])
+                ? args['attachment_names'].filter((name) => typeof name === 'string')
+                : attachments.map((item) => item.name);
+            const uniqueNames = [...new Set(names)];
+            const refs = uniqueNames.map((name) => attachments.find((item) => item.name === name));
+            if (refs.some((ref) => !ref)) {
+                const missing = uniqueNames.filter((name) => !attachments.some((item) => item.name === name));
+                return fail(`Attachment is not available in the current conversation: ${missing.join(', ')}`);
+            }
+            if (!refs.length)
+                return fail('No conversation attachments were selected');
+            const type = await findFileField(library, shelf, field);
+            if (!type || type.prim !== 'file')
+                return fail(`Field is not a file field: ${library}/${shelf}.${field}`);
+            const multiple = type.hints?.multiple === true;
+            const currentResult = await getRecord.handler({ library, shelf, id });
+            if (currentResult.isError)
+                return currentResult;
+            const current = resultData(currentResult);
+            if (!current || typeof current !== 'object')
+                return fail(`Record not found: ${library}/${shelf}/${id}`);
+            const existing = fileItems(current[field]);
+            const incoming = refs.map((ref) => ({ name: ref.name }));
+            if (!multiple && mode === 'append' && existing.length)
+                return fail(`Field already contains a file; use mode="replace" to replace it`);
+            if (!multiple && incoming.length > 1)
+                return fail(`Field accepts one file; select one attachment or use a multiple field`);
+            const next = mode === 'replace'
+                ? incoming
+                : [...existing, ...incoming.filter((item) => !existing.some((old) => old.name === item.name))];
+            const value = multiple ? next : (next[0] ?? null);
+            const updated = await updateRecord.handler({ library, shelf, id, fields: { [field]: value } });
+            if (updated.isError)
+                return updated;
+            return ok({
+                attached: incoming.map((item) => item.name),
+                mode,
+                library,
+                shelf,
+                id,
+                field,
+                record: resultData(updated),
+            });
+        },
+    };
+    tools.push(attach);
+    return { tools };
+}