@coffer-org/plugin-orchestrator 2.2.0 → 2.3.0

package/dist/index.js

@@ -8,6 +8,7 @@ export default definePlugin({
     settings: defineSettings({
         label: 'orchestrator.settings.label',
         fields: [
+            field.select({ key: 'agent_id', label: 'orchestrator.settings.agent_id' }),
             field.password({ key: 'access_password', label: 'orchestrator.settings.access_password' }),
             field.string({ key: 'trigger_prefix', label: 'orchestrator.settings.trigger_prefix' }),
             field.int({ key: 'reply_window', label: 'orchestrator.settings.reply_window', default: 1800 }),

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/config.d.ts

@@ -1,3 +1,4 @@
 import type { GatePolicy } from './types.ts';
 export declare function buildPolicy(dbSettings?: Record<string, unknown>): GatePolicy;
+export declare function loadAgentId(): Promise<string | undefined>;
 export declare function loadGatePolicy(): Promise<GatePolicy>;

package/dist/runtime/config.js

@@ -1,11 +1,17 @@
 export function buildPolicy(dbSettings = {}) {
     const db = dbSettings;
     return {
+        ...(typeof db.agent_id === 'string' && db.agent_id ? { agentId: db.agent_id } : {}),
         accessPassword: db.access_password ?? '',
         triggerPrefix: db.trigger_prefix ?? '',
         replyWindow: Number(db.reply_window ?? 1800) || 1800,
     };
 }
+export async function loadAgentId() {
+    const { getPluginSettings } = await import('@coffer-org/server/plugin-runtime');
+    const value = (await getPluginSettings('orchestrator'))['agent_id'];
+    return typeof value === 'string' && value ? value : undefined;
+}
 export async function loadGatePolicy() {
     const { getPluginSettings } = await import('@coffer-org/server/plugin-runtime');
     return buildPolicy(await getPluginSettings('orchestrator'));

package/dist/runtime/index.d.ts

@@ -1,9 +1,12 @@
 import type { PluginHooks } from '@coffer-org/server/plugin-hooks';
 export { handleIncoming } from './pipeline.ts';
+export { registerAgent, resolveAgent, registerConnector, isConnectorRegistered, clearRuntimeRegistries } from './registry.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 { buildPolicy, loadGatePolicy, loadAgentId } 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, AttachmentRef, ConvMessage, SystemLayer, AgentRequest, AgentResult, } from './types.ts';
+export type { Connector, IncomingConversation, GatePolicy, ReplyContext, ReplyPayload, ReplyChannel, AttachmentRef, AttachmentMaterializer, AgentToolDefinition, AgentToolProvider, ConvMessage, SystemLayer, AgentRequest, AgentResult, AgentRuntime, ConnectorRegistration, } from './types.ts';
 export declare const serverHooks: PluginHooks;

package/dist/runtime/index.js

@@ -1,7 +1,10 @@
 import { openLogDb } from "./db.js";
 import { setLogDb } from "./pipeline.js";
 export { handleIncoming } from "./pipeline.js";
-export { buildPolicy, loadGatePolicy } from "./config.js";
+export { registerAgent, resolveAgent, registerConnector, isConnectorRegistered, clearRuntimeRegistries } from "./registry.js";
+export { attachmentMaterializer } from "./attachments.js";
+export { makeAttachmentCapabilities } from "./agent-capabilities.js";
+export { buildPolicy, loadGatePolicy, loadAgentId } from "./config.js";
 export { makeLiveChannel, plainRender } from "./live-message.js";
 export { chunk } from "./format.js";
 let db;

package/dist/runtime/pipeline.d.ts

@@ -1,8 +1,7 @@
-import { runAgent } from '@coffer-org/plugin-claude-agent/runtime';
-import type { Connector, IncomingConversation, GatePolicy } from './types.ts';
+import type { Connector, IncomingConversation, GatePolicy, AgentRuntime } from './types.ts';
 import type { LogDb } from './db.ts';
 export declare function setLogDb(db: LogDb | undefined): void;
-export type RunAgentFn = typeof runAgent;
+export type RunAgentFn = AgentRuntime['run'];
 export interface PipelineDeps {
     runAgent?: RunAgentFn;
     logDb?: LogDb | null;

package/dist/runtime/pipeline.js

@@ -1,8 +1,10 @@
-import { runAgent, agentSystemBase } from '@coffer-org/plugin-claude-agent/runtime';
 import { join } from 'node:path';
 import { loadAllowed, saveAllowed, isAllowed, addAllowed, makeThrottle } from "./allow.js";
-import { loadGatePolicy } from "./config.js";
+import { loadAgentId, loadGatePolicy } from "./config.js";
 import { buildSystem } from "./system-assembly.js";
+import { attachmentMaterializer } from "./attachments.js";
+import { makeAttachmentCapabilities } from "./agent-capabilities.js";
+import { resolveAgent } from "./registry.js";
 import { getLogger } from '@coffer-org/sdk/logger';
 const log = getLogger('orchestrator');
 const stateDir = () => process.env['ORCHESTRATOR_STATE_DIR']
@@ -19,7 +21,15 @@ function passThrottle(connectorId) {
     return t;
 }
 let cachedBase;
-function cachedAgentBase() { return (cachedBase ??= agentSystemBase()); }
+let cachedBaseAgentId;
+function cachedAgentBase() {
+    const runtime = resolveAgent();
+    if (cachedBaseAgentId !== runtime.id) {
+        cachedBaseAgentId = runtime.id;
+        cachedBase = runtime.systemBase();
+    }
+    return cachedBase;
+}
 function openChannel(connector, chatId, ctx) {
     try {
         return connector.reply(chatId, ctx);
@@ -39,10 +49,12 @@ async function safeCall(fn, fallback, label) {
     }
 }
 export async function handleIncoming(connector, conversation, deps) {
-    const agent = deps?.runAgent ?? runAgent;
-    const db = deps && 'logDb' in deps ? deps.logDb : logDb;
     const policy = deps?.policy ?? await loadGatePolicy();
-    const agentBase = deps?.agentBase ?? cachedAgentBase;
+    const selectedAgentId = conversation.agentId ?? policy.agentId ?? (deps?.runAgent ? undefined : await loadAgentId());
+    const runtime = deps?.runAgent ? undefined : resolveAgent(selectedAgentId);
+    const agent = deps?.runAgent ?? runtime.run.bind(runtime);
+    const db = deps && 'logDb' in deps ? deps.logDb : logDb;
+    const agentBase = deps?.agentBase ?? (() => selectedAgentId ? runtime.systemBase() : cachedAgentBase());
     const { connectorId, chatId, sender, messages } = conversation;
     const last = messages[messages.length - 1];
     if (!last || last.role !== 'user')
@@ -73,12 +85,12 @@ export async function handleIncoming(connector, conversation, deps) {
     const queryText = policy.triggerPrefix ? last.content.slice(policy.triggerPrefix.length).trim() : last.content.trim();
     if (!queryText) {
         if (conversation.prepareAttachments && !policy.triggerPrefix) {
-            await safeCall(conversation.prepareAttachments, messages, 'prepareAttachments');
+            await safeCall(() => conversation.prepareAttachments(attachmentMaterializer), messages, 'prepareAttachments');
         }
         return;
     }
     const preparedMessages = conversation.prepareAttachments
-        ? await safeCall(conversation.prepareAttachments, messages, '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))
@@ -96,9 +108,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/registry.d.ts

@@ -0,0 +1,8 @@
+import type { AgentRuntime, ConnectorRegistration } from './types.ts';
+export declare function registerAgent(runtime: AgentRuntime, opts?: {
+    default?: boolean;
+}): () => void;
+export declare function resolveAgent(id?: string): AgentRuntime;
+export declare function registerConnector(registration: ConnectorRegistration): () => void;
+export declare function isConnectorRegistered(id: string): boolean;
+export declare function clearRuntimeRegistries(): void;

package/dist/runtime/registry.js

@@ -0,0 +1,44 @@
+const agents = new Map();
+const connectors = new Map();
+let defaultAgentId;
+export function registerAgent(runtime, opts = {}) {
+    const current = agents.get(runtime.id);
+    if (current && current !== runtime)
+        throw new Error(`agent already registered: ${runtime.id}`);
+    agents.set(runtime.id, runtime);
+    if (opts.default || !defaultAgentId)
+        defaultAgentId = runtime.id;
+    return () => unregisterAgent(runtime.id, runtime);
+}
+function unregisterAgent(id, expected) {
+    if (agents.get(id) !== expected)
+        return;
+    agents.delete(id);
+    if (defaultAgentId === id)
+        defaultAgentId = agents.keys().next().value;
+}
+export function resolveAgent(id) {
+    const key = id ?? defaultAgentId;
+    const runtime = key ? agents.get(key) : undefined;
+    if (!runtime)
+        throw new Error(id ? `agent is not registered: ${id}` : 'no agent is registered');
+    return runtime;
+}
+export function registerConnector(registration) {
+    const current = connectors.get(registration.id);
+    if (current && current !== registration)
+        throw new Error(`connector already registered: ${registration.id}`);
+    connectors.set(registration.id, registration);
+    return () => {
+        if (connectors.get(registration.id) === registration)
+            connectors.delete(registration.id);
+    };
+}
+export function isConnectorRegistered(id) {
+    return connectors.has(id);
+}
+export function clearRuntimeRegistries() {
+    agents.clear();
+    connectors.clear();
+    defaultAgentId = undefined;
+}

package/dist/runtime/types.d.ts

@@ -1,7 +1,62 @@
-export type { AttachmentRef, ConvMessage, SystemLayer, AgentRequest, AgentResult } from '@coffer-org/plugin-claude-agent/runtime';
-import type { ConvMessage } from '@coffer-org/plugin-claude-agent/runtime';
+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>;
+}
+export interface AgentToolProvider {
+    tools: AgentToolDefinition[];
+}
+export interface ConvMessage {
+    role: 'user' | 'assistant';
+    content: string;
+    attachments?: AttachmentRef[];
+    sender?: string | null;
+    msgId: string;
+    ts: number;
+}
+export interface SystemLayer {
+    text: string;
+    stable: boolean;
+}
+export interface AgentRequest {
+    system: SystemLayer[];
+    messages: ConvMessage[];
+    toolProvider?: AgentToolProvider;
+    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;
+}
+export interface AgentRuntime {
+    id: string;
+    run(request: AgentRequest): Promise<AgentResult>;
+    systemBase(): 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;
     chatId: string;
     channelSystem?: string;
     volatileSystem?: string;
@@ -10,7 +65,7 @@ export interface IncomingConversation {
         displayName?: string;
     };
     messages: ConvMessage[];
-    prepareAttachments?: () => Promise<ConvMessage[]>;
+    prepareAttachments?: (materializer: AttachmentMaterializer) => Promise<ConvMessage[]>;
 }
 export interface ReplyContext {
     parentMsgId: string | null;
@@ -36,6 +91,7 @@ export interface Connector {
     }): Promise<void>;
 }
 export interface GatePolicy {
+    agentId?: string;
     accessPassword: string;
     triggerPrefix: string;
     replyWindow: number;

package/dist/schema.js

@@ -7077,6 +7077,10 @@ var src_default = definePlugin({
 	settings: defineSettings({
 		label: "orchestrator.settings.label",
 		fields: [
+			field.select({
+				key: "agent_id",
+				label: "orchestrator.settings.agent_id"
+			}),
 			field.password({
 				key: "access_password",
 				label: "orchestrator.settings.access_password"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffer-org/plugin-orchestrator",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -25,9 +25,8 @@
     "postpack": "node ../../scripts/swap-exports.mjs src"
   },
   "dependencies": {
-    "@coffer-org/sdk": "^2.1.1",
-    "@coffer-org/server": "^2.3.0",
-    "@coffer-org/plugin-claude-agent": "^2.5.0"
+    "@coffer-org/sdk": "^2.1.2",
+    "@coffer-org/server": "^2.3.0"
   },
   "coffer": {
     "schema": "dist/schema.js"