@coffer-org/plugin-orchestrator 2.1.1 → 2.2.1

package/dist/runtime/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/runtime/agent-capabilities.js

@@ -0,0 +1,131 @@
+import { collectMcpTools } from '@coffer-org/server/mcp-tools';
+import { LocalClient } from '@coffer-org/server/mcp-local';
+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) {
+    if (!attachments.length)
+        return { tools: [] };
+    const defs = await collectMcpTools();
+    const getRecord = findTool(defs, 'get_record');
+    const updateRecord = findTool(defs, 'update_record');
+    if (!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) });
+        },
+    };
+    return { tools: [attach] };
+}

package/dist/runtime/attachments.d.ts

@@ -0,0 +1,2 @@
+import type { AttachmentMaterializer } from './types.ts';
+export declare const attachmentMaterializer: AttachmentMaterializer;

package/dist/runtime/attachments.js

@@ -0,0 +1,11 @@
+import { saveUploadBytes } from '@coffer-org/server/uploads';
+export const attachmentMaterializer = {
+    async store(bytes, opts = {}) {
+        const stored = await saveUploadBytes(bytes, opts);
+        return {
+            name: stored.name,
+            ...(stored.mime ? { mime: stored.mime } : {}),
+            size: stored.size,
+        };
+    },
+};

package/dist/runtime/index.d.ts

@@ -1,9 +1,11 @@
 import type { PluginHooks } from '@coffer-org/server/plugin-hooks';
 export { handleIncoming } from './pipeline.ts';
+export { attachmentMaterializer } from './attachments.ts';
+export { makeAttachmentCapabilities } from './agent-capabilities.ts';
 export type { PipelineDeps, RunAgentFn } from './pipeline.ts';
 export { buildPolicy, loadGatePolicy } from './config.ts';
 export { makeLiveChannel, plainRender } from './live-message.ts';
 export type { LiveChannelOps, LiveChannelOpts, RenderFn } from './live-message.ts';
 export { chunk } from './format.ts';
-export type { Connector, IncomingConversation, GatePolicy, ReplyContext, ReplyPayload, ReplyChannel, ConvMessage, SystemLayer, AgentRequest, AgentResult, } from './types.ts';
+export type { Connector, IncomingConversation, GatePolicy, ReplyContext, ReplyPayload, ReplyChannel, AttachmentRef, AttachmentMaterializer, AgentToolDefinition, AgentToolProvider, ConvMessage, SystemLayer, AgentRequest, AgentResult, } from './types.ts';
 export declare const serverHooks: PluginHooks;

package/dist/runtime/index.js

@@ -1,6 +1,8 @@
 import { openLogDb } from "./db.js";
 import { setLogDb } from "./pipeline.js";
 export { handleIncoming } from "./pipeline.js";
+export { attachmentMaterializer } from "./attachments.js";
+export { makeAttachmentCapabilities } from "./agent-capabilities.js";
 export { buildPolicy, loadGatePolicy } from "./config.js";
 export { makeLiveChannel, plainRender } from "./live-message.js";
 export { chunk } from "./format.js";

package/dist/runtime/pipeline.js

@@ -3,6 +3,8 @@ import { join } from 'node:path';
 import { loadAllowed, saveAllowed, isAllowed, addAllowed, makeThrottle } from "./allow.js";
 import { loadGatePolicy } from "./config.js";
 import { buildSystem } from "./system-assembly.js";
+import { attachmentMaterializer } from "./attachments.js";
+import { makeAttachmentCapabilities } from "./agent-capabilities.js";
 import { getLogger } from '@coffer-org/sdk/logger';
 const log = getLogger('orchestrator');
 const stateDir = () => process.env['ORCHESTRATOR_STATE_DIR']
@@ -71,11 +73,18 @@ export async function handleIncoming(connector, conversation, deps) {
     if (policy.triggerPrefix && !last.content.toLowerCase().startsWith(policy.triggerPrefix.toLowerCase()))
         return;
     const queryText = policy.triggerPrefix ? last.content.slice(policy.triggerPrefix.length).trim() : last.content.trim();
-    if (!queryText)
+    if (!queryText) {
+        if (conversation.prepareAttachments && !policy.triggerPrefix) {
+            await safeCall(() => conversation.prepareAttachments(attachmentMaterializer), messages, 'prepareAttachments');
+        }
         return;
-    const agentMessages = policy.triggerPrefix
-        ? messages.map((m, i) => (i === messages.length - 1 ? { ...m, content: queryText } : m))
+    }
+    const preparedMessages = conversation.prepareAttachments
+        ? await safeCall(() => conversation.prepareAttachments(attachmentMaterializer), messages, 'prepareAttachments')
         : messages;
+    const agentMessages = policy.triggerPrefix
+        ? preparedMessages.map((m, i) => (i === preparedMessages.length - 1 ? { ...m, content: queryText } : m))
+        : preparedMessages;
     const base = await agentBase();
     const system = buildSystem({
         base,
@@ -89,9 +98,11 @@ export async function handleIncoming(connector, conversation, deps) {
         return;
     let result;
     try {
+        const toolProvider = await makeAttachmentCapabilities(agentMessages.flatMap((m) => m.attachments ?? []));
         result = await agent({
             system,
             messages: agentMessages,
+            toolProvider,
             onDelta: (acc) => { try {
                 ch.update(acc);
             }

package/dist/runtime/types.d.ts

@@ -1,5 +1,11 @@
-export type { ConvMessage, SystemLayer, AgentRequest, AgentResult } from '@coffer-org/plugin-claude-agent/runtime';
-import type { ConvMessage } from '@coffer-org/plugin-claude-agent/runtime';
+export type { AttachmentRef, AgentToolDefinition, AgentToolProvider, ConvMessage, SystemLayer, AgentRequest, AgentResult, } from '@coffer-org/plugin-claude-agent/runtime';
+import type { AttachmentRef, ConvMessage } from '@coffer-org/plugin-claude-agent/runtime';
+export interface AttachmentMaterializer {
+    store(bytes: Uint8Array, opts?: {
+        originalName?: string;
+        mime?: string;
+    }): Promise<AttachmentRef>;
+}
 export interface IncomingConversation {
     connectorId: string;
     chatId: string;
@@ -10,6 +16,7 @@ export interface IncomingConversation {
         displayName?: string;
     };
     messages: ConvMessage[];
+    prepareAttachments?: (materializer: AttachmentMaterializer) => Promise<ConvMessage[]>;
 }
 export interface ReplyContext {
     parentMsgId: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffer-org/plugin-orchestrator",
-  "version": "2.1.1",
+  "version": "2.2.1",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -26,8 +26,8 @@
   },
   "dependencies": {
     "@coffer-org/sdk": "^2.1.1",
-    "@coffer-org/server": "^2.2.2",
-    "@coffer-org/plugin-claude-agent": "^2.4.1"
+    "@coffer-org/server": "^2.3.0",
+    "@coffer-org/plugin-claude-agent": "^2.5.2"
   },
   "coffer": {
     "schema": "dist/schema.js"