@coffer-org/plugin-agent 1.2.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@coffer-org/sdk/plugin").PluginManifest;
+export default _default;

package/dist/index.js

@@ -0,0 +1,37 @@
+import { definePlugin } from '@coffer-org/sdk/plugin';
+import { defineSettings } from '@coffer-org/sdk/settings';
+import { field } from '@coffer-org/sdk/fields';
+export default definePlugin({
+    id: 'agent',
+    version: '1.0.0',
+    dependsOn: [],
+    settings: defineSettings({
+        label: 'agent.settings.label',
+        fields: [
+            field.select({
+                key: 'auth_mode',
+                label: 'agent.settings.auth_mode',
+                default: 'subscription',
+                options: [
+                    { value: 'subscription', title: 'agent.settings.auth_mode_subscription' },
+                    { value: 'api_key', title: 'agent.settings.auth_mode_api_key' },
+                ],
+            }),
+            field.password({
+                key: 'anthropic_api_key',
+                label: 'agent.settings.anthropic_api_key',
+                view: { hidden: { auth_mode: { $ne: 'api_key' } } },
+            }),
+            field.string({ key: 'claude_model', label: 'agent.settings.claude_model', default: 'haiku' }),
+            field.boolean({ key: 'skip_permissions', label: 'agent.settings.skip_permissions', default: true }),
+            field.int({ key: 'response_timeout', label: 'agent.settings.response_timeout', default: 600 }),
+            field.boolean({ key: 'rag_enabled', label: 'agent.settings.rag_enabled', default: true }),
+            field.int({ key: 'rag_top_k', label: 'agent.settings.rag_top_k', default: 5 }),
+            field.password({ key: 'openai_api_key', label: 'agent.settings.openai_api_key' }),
+            field.password({ key: 'langfuse_public_key', label: 'agent.settings.langfuse_public_key' }),
+            field.password({ key: 'langfuse_secret_key', label: 'agent.settings.langfuse_secret_key' }),
+            field.string({ key: 'langfuse_base_url', label: 'agent.settings.langfuse_base_url' }),
+            field.boolean({ key: 'tracing_enabled', label: 'agent.settings.tracing_enabled' }),
+        ],
+    }),
+});

package/dist/runtime/agent.d.ts

@@ -0,0 +1,25 @@
+import type { Options, McpServerConfig } from '@anthropic-ai/claude-agent-sdk';
+import type { AgentConfig } from './config.ts';
+export declare function buildAgentEnv(cfg: Pick<AgentConfig, 'authMode' | 'anthropicApiKey' | 'claudeHomeDir'>): Record<string, string | undefined>;
+export declare function buildQueryOptions(cfg: Pick<AgentConfig, 'claudeModel' | 'skipPermissions' | 'workspaceDir' | 'claudeHomeDir' | 'authMode' | 'anthropicApiKey'>, sessionId: string | null, ragServer: McpServerConfig | undefined, pluginServers?: Record<string, McpServerConfig>): Options & {
+    allowedTools: string[];
+    mcpServers: Record<string, McpServerConfig>;
+};
+export interface RunAgentOpts {
+    prompt: string;
+    sessionId: string | null;
+    onDelta?: (accumulated: string) => void;
+}
+export interface RunAgentResult {
+    text: string | null;
+    sessionId: string | null;
+    tokensIn: number | null;
+    tokensOut: number | null;
+}
+export declare function runAgent(opts: RunAgentOpts): Promise<RunAgentResult>;
+export declare function fallbackMessages(language: unknown): {
+    timeout: string;
+    error: string;
+};
+export declare function responseLanguageInstruction(language: unknown): string | undefined;
+export declare function buildSystemPrompt(language: unknown, ragEnabled: boolean, instructions?: string[]): string;

package/dist/runtime/agent.js

@@ -0,0 +1,144 @@
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { loadAgentConfig } from "./config.js";
+import { makeCofferServer, makePluginServers } from "./coffer.js";
+import { collectContributions } from "./contributions.js";
+import { makeRagServer } from "./rag.js";
+import { isTracing, flushTracing, langfuseFactory, TurnTracer } from "./tracing.js";
+const log = {
+    warn: (m) => console.warn(`[agent] ${new Date().toISOString().slice(0, 19)} WARN ${m}`),
+    error: (m) => console.error(`[agent] ${new Date().toISOString().slice(0, 19)} ERROR ${m}`),
+};
+export function buildAgentEnv(cfg) {
+    const { ANTHROPIC_API_KEY: _k, ANTHROPIC_AUTH_TOKEN: _t, ...rest } = process.env;
+    const base = { ...rest, CLAUDE_CONFIG_DIR: cfg.claudeHomeDir };
+    if (cfg.authMode === 'api_key' && cfg.anthropicApiKey)
+        return { ...base, ANTHROPIC_API_KEY: cfg.anthropicApiKey };
+    return base;
+}
+export function buildQueryOptions(cfg, sessionId, ragServer, pluginServers = {}) {
+    const mcpServers = { coffer: makeCofferServer(), ...pluginServers };
+    if (ragServer)
+        mcpServers.rag = ragServer;
+    const allowedTools = ['mcp__coffer__*', 'WebSearch', 'WebFetch'];
+    if (ragServer)
+        allowedTools.push('mcp__rag__search_records');
+    for (const id of Object.keys(pluginServers))
+        allowedTools.push(`mcp__${id}__*`);
+    return {
+        model: cfg.claudeModel,
+        resume: sessionId ?? undefined,
+        cwd: cfg.workspaceDir,
+        mcpServers,
+        allowedTools,
+        disallowedTools: ['Bash', 'Edit', 'Write', 'Read', 'Glob', 'Grep'],
+        permissionMode: cfg.skipPermissions ? 'bypassPermissions' : 'default',
+        allowDangerouslySkipPermissions: cfg.skipPermissions,
+        settingSources: ['project'],
+        skills: 'all',
+        includePartialMessages: true,
+        env: buildAgentEnv(cfg),
+    };
+}
+export async function runAgent(opts) {
+    const cfg = loadAgentConfig({ dbSettings: await loadAgentSettings() });
+    const ragServer = cfg.ragEnabled && cfg.embeddingApiKey ? makeRagServer(cfg) : undefined;
+    const sys = await loadSystemSettings();
+    const fb = fallbackMessages(sys.language);
+    const ac = new AbortController();
+    const timer = setTimeout(() => { log.warn(`agent timeout after ${cfg.responseTimeout}s — aborting`); ac.abort(); }, cfg.responseTimeout * 1000);
+    let tracer;
+    try {
+        let text = '', streamed = '';
+        let newSessionId = opts.sessionId, tokensIn = null, tokensOut = null;
+        const contribs = await collectContributions();
+        const pluginServers = makePluginServers(contribs);
+        const sections = contribs
+            .filter((c) => c.instructions)
+            .map((c) => `## ${c.id}\n${c.instructions}`);
+        const qopts = buildQueryOptions(cfg, opts.sessionId, ragServer, pluginServers);
+        const systemPrompt = buildSystemPrompt(sys.language, Boolean(ragServer), sections);
+        tracer = isTracing() ? new TurnTracer(langfuseFactory, opts.prompt, opts.sessionId) : undefined;
+        for await (const msg of query({ prompt: opts.prompt, options: { ...qopts, abortController: ac, systemPrompt } })) {
+            const sev = msg;
+            if (sev.type === 'stream_event') {
+                const ev = sev.event;
+                if (ev?.type === 'content_block_delta' && ev.delta?.type === 'text_delta' && ev.delta.text) {
+                    streamed += ev.delta.text;
+                    opts.onDelta?.(streamed);
+                }
+                continue;
+            }
+            tracer?.onMessage(msg);
+            if (msg.type === 'assistant') {
+                for (const b of msg.message.content)
+                    if (b.type === 'text')
+                        text += b.text;
+            }
+            else if (msg.type === 'result') {
+                newSessionId = msg.session_id ?? newSessionId;
+                if (msg.subtype !== 'success')
+                    log.error(`agent result subtype=${msg.subtype}`);
+                tokensIn = msg.usage?.input_tokens ?? null;
+                tokensOut = msg.usage?.output_tokens ?? null;
+                if (msg.subtype === 'success' && !text)
+                    text = msg.result;
+            }
+        }
+        if (!text && streamed)
+            text = streamed;
+        return { text: text.trim() || null, sessionId: newSessionId, tokensIn, tokensOut };
+    }
+    catch (e) {
+        if (ac.signal.aborted) {
+            tracer?.fail('aborted: response timeout');
+            return { text: fb.timeout, sessionId: null, tokensIn: null, tokensOut: null };
+        }
+        const m = e instanceof Error ? e.message : String(e);
+        log.error(`agent error: ${m}`);
+        tracer?.fail(m);
+        return { text: fb.error, sessionId: null, tokensIn: null, tokensOut: null };
+    }
+    finally {
+        clearTimeout(timer);
+        if (tracer)
+            await flushTracing();
+    }
+}
+async function loadAgentSettings() {
+    const { getPluginSettings } = await import('@coffer-org/server/plugin-runtime');
+    return getPluginSettings('agent');
+}
+const LANG_NAME = { uk: 'Ukrainian', ru: 'Russian', en: 'English' };
+const FALLBACKS = {
+    uk: { timeout: '⏱ відповідь не отримана (перевищено ліміт часу)', error: '⚠️ помилка обробки (деталі в логах сервера)' },
+    ru: { timeout: '⏱ ответ не получен (превышен лимит времени)', error: '⚠️ ошибка обработки (детали в логах сервера)' },
+    en: { timeout: '⏱ no response (timed out)', error: '⚠️ processing error (see server logs)' },
+};
+export function fallbackMessages(language) {
+    return (typeof language === 'string' && FALLBACKS[language]) || FALLBACKS.uk;
+}
+export function responseLanguageInstruction(language) {
+    const name = typeof language === 'string' ? LANG_NAME[language] : undefined;
+    return name
+        ? `Respond in ${name} by default, even when the user writes in another language — unless they explicitly ask you to reply in a different language.`
+        : undefined;
+}
+export function buildSystemPrompt(language, ragEnabled, instructions = []) {
+    const lines = [
+        "You are the user's personal home assistant. You have full access to their personal database, Coffer, which stores their household data across vaults: kitchen (food items, recipes), people, finance, health, devices, home, garden, documents, travel, and more.",
+        'To answer any question about the user or their household, USE THE TOOLS to look up the data — never claim you lack access. The data is there; find it.',
+        ragEnabled
+            ? 'Start with mcp__rag__search_records for a semantic search (e.g. query "milk"). Use the mcp__coffer__ tools (list_vaults, list_records, get_record) to browse precisely or confirm quantities.'
+            : 'Use the mcp__coffer__ tools: call list_vaults to see what exists, then list_records / get_record to read the data.',
+        'Record field values may be JSON-encoded (e.g. quantity {"value":2000,"unit":"ml"}) — parse and present them in plain language.',
+    ];
+    const lang = responseLanguageInstruction(language);
+    if (lang)
+        lines.push(lang);
+    const base = lines.join('\n');
+    return instructions.length ? `${base}\n\n${instructions.join('\n\n')}` : base;
+}
+async function loadSystemSettings() {
+    const { getPluginSettings } = await import('@coffer-org/server/plugin-runtime');
+    return getPluginSettings('core');
+}

package/dist/runtime/coffer.d.ts

@@ -0,0 +1,5 @@
+import type { McpServerConfig } from '@anthropic-ai/claude-agent-sdk';
+import type { EntityManager } from '@mikro-orm/core';
+import type { CollectedContribution } from './contributions.ts';
+export declare function makeCofferServer(): McpServerConfig;
+export declare function makePluginServers(contribs: CollectedContribution[], emFactory?: () => EntityManager): Record<string, McpServerConfig>;

package/dist/runtime/coffer.js

@@ -0,0 +1,29 @@
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { buildTools } from '@coffer-org/mcp/tools';
+import { SchemaCache } from '@coffer-org/mcp/schema';
+import { getEm } from '@coffer-org/server/db';
+import { LocalClient } from "./local-client.js";
+export function makeCofferServer() {
+    const client = new LocalClient();
+    const cache = new SchemaCache(client);
+    const tools = buildTools(client, cache).map((t) => tool(t.name, t.description, t.inputSchema, async (args) => (await t.handler(args))));
+    return createSdkMcpServer({ name: 'coffer', version: '1.0.0', tools });
+}
+export function makePluginServers(contribs, emFactory = () => getEm().fork()) {
+    const servers = {};
+    for (const c of contribs) {
+        if (!c.tools.length)
+            continue;
+        const tools = c.tools.map((t) => tool(t.name, t.description, t.inputSchema, async (args) => {
+            try {
+                const data = await t.handler(args, { em: emFactory() });
+                return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+            }
+            catch (e) {
+                return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
+            }
+        }));
+        servers[c.id] = createSdkMcpServer({ name: c.id, version: '1.0.0', tools });
+    }
+    return servers;
+}

package/dist/runtime/config.d.ts

@@ -0,0 +1,29 @@
+export declare const APP_ROOT: string;
+export declare const PLUGIN_ROOT: string;
+export type AuthMode = 'subscription' | 'api_key';
+export interface AgentConfig {
+    authMode: AuthMode;
+    anthropicApiKey: string;
+    claudeModel: string;
+    skipPermissions: boolean;
+    responseTimeout: number;
+    ragEnabled: boolean;
+    ragTopK: number;
+    embeddingApiKey: string;
+    langfusePublicKey: string;
+    langfuseSecretKey: string;
+    langfuseBaseUrl: string;
+    tracingEnabled: boolean;
+    appRoot: string;
+    cofferUrl: string;
+    globalCredentials: string;
+    runtimeDir: string;
+    workspaceDir: string;
+    claudeHomeDir: string;
+    stateDir: string;
+}
+export interface LoadOpts {
+    env?: Record<string, string | undefined>;
+    dbSettings?: Record<string, unknown>;
+}
+export declare function loadAgentConfig(opts?: LoadOpts): AgentConfig;

package/dist/runtime/config.js

@@ -0,0 +1,34 @@
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const APP_ROOT = path.resolve(__dirname, '../../../..');
+export const PLUGIN_ROOT = path.resolve(__dirname, '../..');
+export function loadAgentConfig(opts = {}) {
+    const env = opts.env ?? process.env;
+    const db = (opts.dbSettings ?? {});
+    const runtimeDir = path.join(PLUGIN_ROOT, 'runtime');
+    return {
+        authMode: (env.AGENT_AUTH_MODE ?? db.auth_mode ?? 'subscription') === 'api_key' ? 'api_key' : 'subscription',
+        anthropicApiKey: env.AGENT_ANTHROPIC_API_KEY ?? db.anthropic_api_key ?? env.ANTHROPIC_API_KEY ?? '',
+        claudeModel: env.AGENT_CLAUDE_MODEL ?? db.claude_model ?? 'haiku',
+        skipPermissions: db.skip_permissions !== false,
+        responseTimeout: Math.max(60, Number(env.AGENT_RESPONSE_TIMEOUT ?? db.response_timeout ?? 600) || 600),
+        ragEnabled: db.rag_enabled !== false,
+        ragTopK: Number(env.AGENT_RAG_TOP_K ?? db.rag_top_k ?? 5) || 5,
+        embeddingApiKey: env.OPENAI_API_KEY ?? db.openai_api_key ?? '',
+        langfusePublicKey: env.LANGFUSE_PUBLIC_KEY ?? db.langfuse_public_key ?? '',
+        langfuseSecretKey: env.LANGFUSE_SECRET_KEY ?? db.langfuse_secret_key ?? '',
+        langfuseBaseUrl: env.LANGFUSE_BASE_URL ?? db.langfuse_base_url ?? 'https://cloud.langfuse.com',
+        tracingEnabled: db.tracing_enabled === false
+            ? false
+            : Boolean((env.LANGFUSE_PUBLIC_KEY ?? db.langfuse_public_key) && (env.LANGFUSE_SECRET_KEY ?? db.langfuse_secret_key)),
+        appRoot: APP_ROOT,
+        cofferUrl: env.COFFER_URL ?? db.coffer_url ?? 'http://localhost:7023',
+        globalCredentials: env.CLAUDE_GLOBAL_CREDENTIALS ?? path.join(os.homedir(), '.claude', '.credentials.json'),
+        runtimeDir,
+        workspaceDir: path.join(runtimeDir, 'workspace'),
+        claudeHomeDir: path.join(runtimeDir, 'claude-home'),
+        stateDir: path.join(runtimeDir, 'state'),
+    };
+}

package/dist/runtime/contributions.d.ts

@@ -0,0 +1,8 @@
+import type { EntityManager } from '@mikro-orm/core';
+import type { AgentTool, PluginHooks } from '@coffer-org/server/plugin-hooks';
+export interface CollectedContribution {
+    id: string;
+    instructions: string | null;
+    tools: AgentTool[];
+}
+export declare function collectContributions(hooks?: Record<string, PluginHooks>, emFactory?: () => EntityManager): Promise<CollectedContribution[]>;

package/dist/runtime/contributions.js

@@ -0,0 +1,23 @@
+import { pluginHooks } from '@coffer-org/server/plugin-hooks';
+import { getEm } from '@coffer-org/server/db';
+const log = { warn: (m) => console.warn(`[agent] ${m}`) };
+export async function collectContributions(hooks = pluginHooks, emFactory = () => getEm().fork()) {
+    const out = [];
+    for (const [id, h] of Object.entries(hooks)) {
+        const a = h.agent;
+        if (!a)
+            continue;
+        let instructions = null;
+        if (a.instructions != null) {
+            try {
+                instructions =
+                    typeof a.instructions === 'function' ? await a.instructions({ em: emFactory() }) : a.instructions;
+            }
+            catch (e) {
+                log.warn(`contribution ${id}: instructions skipped — ${e.message}`);
+            }
+        }
+        out.push({ id, instructions, tools: a.tools ?? [] });
+    }
+    return out;
+}

package/dist/runtime/embed.d.ts

@@ -0,0 +1,10 @@
+export declare const EMBED_MODEL = "text-embedding-3-small";
+export declare const EMBED_DIM = 1024;
+export declare function embedBatch(texts: string[], apiKey: string, fetchImpl?: typeof fetch): Promise<{
+    vectors: number[][];
+    tokens: number;
+}>;
+export declare function embedOne(text: string, apiKey: string, fetchImpl?: typeof fetch): Promise<{
+    vector: number[];
+    tokens: number;
+}>;

package/dist/runtime/embed.js

@@ -0,0 +1,28 @@
+const OPENAI_URL = 'https://api.openai.com/v1/embeddings';
+export const EMBED_MODEL = 'text-embedding-3-small';
+export const EMBED_DIM = 1024;
+export async function embedBatch(texts, apiKey, fetchImpl = fetch) {
+    if (texts.length === 0)
+        return { vectors: [], tokens: 0 };
+    if (!apiKey)
+        throw new Error('embeddings: missing API key (OPENAI_API_KEY)');
+    const res = await fetchImpl(OPENAI_URL, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+        body: JSON.stringify({ model: EMBED_MODEL, input: texts, dimensions: EMBED_DIM }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`openai embeddings ${res.status}: ${body.slice(0, 200)}`);
+    }
+    const json = (await res.json());
+    const vectors = [...json.data].sort((a, b) => a.index - b.index).map((d) => d.embedding);
+    return { vectors, tokens: json.usage?.total_tokens ?? 0 };
+}
+export async function embedOne(text, apiKey, fetchImpl = fetch) {
+    const { vectors, tokens } = await embedBatch([text], apiKey, fetchImpl);
+    const vector = vectors[0];
+    if (!vector)
+        throw new Error('embeddings: empty response');
+    return { vector, tokens };
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,4 @@
+import type { PluginHooks } from '@coffer-org/server/plugin-hooks';
+export { runAgent } from './agent.ts';
+export type { RunAgentOpts, RunAgentResult } from './agent.ts';
+export declare const serverHooks: PluginHooks;

package/dist/runtime/index.js

@@ -0,0 +1,31 @@
+import { getPluginSettings } from '@coffer-org/server/plugin-runtime';
+import { loadAgentConfig } from "./config.js";
+import { ensureWorkspace } from "./workspace.js";
+import { indexOnce } from "./indexer.js";
+import { initTracing, flushTracing, isTracing } from "./tracing.js";
+export { runAgent } from "./agent.js";
+const log = { warn: (m) => console.warn(`[agent] ${m}`) };
+let indexTimer;
+export const serverHooks = {
+    init: async () => {
+        const cfg = loadAgentConfig({ dbSettings: await getPluginSettings('agent') });
+        initTracing(cfg);
+        console.log(isTracing()
+            ? `[plugin] agent: Langfuse tracing ON → ${cfg.langfuseBaseUrl}`
+            : `[plugin] agent: Langfuse tracing OFF (tracing_enabled=${cfg.tracingEnabled}, keys=${cfg.langfusePublicKey && cfg.langfuseSecretKey ? 'set' : 'missing'})`);
+        ensureWorkspace(cfg, console);
+        if (cfg.ragEnabled && cfg.embeddingApiKey) {
+            const run = () => indexOnce({ apiKey: cfg.embeddingApiKey }).catch((e) => log.warn(`indexer: ${e instanceof Error ? e.message : String(e)}`));
+            void run();
+            indexTimer = setInterval(() => void run(), 60_000);
+            if (typeof indexTimer.unref === 'function')
+                indexTimer.unref();
+        }
+        console.log('[plugin] agent: init ✓');
+    },
+    teardown: async () => {
+        clearInterval(indexTimer);
+        indexTimer = undefined;
+        await flushTracing();
+    },
+};

package/dist/runtime/indexer.d.ts

@@ -0,0 +1,7 @@
+import { embedBatch } from './embed.ts';
+export declare function buildSnippet(after: Record<string, unknown>, type?: string): string;
+export declare function indexOnce(opts: {
+    apiKey: string;
+    batch?: number;
+    embed?: typeof embedBatch;
+}): Promise<number>;

package/dist/runtime/indexer.js

@@ -0,0 +1,110 @@
+import { listEventsSince, upsertEmbedding, deleteEmbedding } from '@coffer-org/server/embeddings';
+import { getPluginState, setPluginState } from '@coffer-org/server/plugin-state';
+import { embedBatch, EMBED_MODEL } from "./embed.js";
+import { isTracing, flushTracing, langfuseFactory } from "./tracing.js";
+const PLUGIN = 'agent';
+const STATE_KEY = 'last_event_id';
+const VERSION_KEY = 'snippet_version';
+const SNIPPET_VERSION = '2';
+const MAX_SNIPPET = 1000;
+const MAX_DEPTH = 2;
+const SKIP_FIELDS = new Set(['id', 'created_at', 'updated_at']);
+function flattenScalars(prefix, v, out, depth) {
+    if (v == null)
+        return;
+    if (typeof v === 'string') {
+        if (v.trim())
+            out.push(`${prefix}: ${v}`);
+        return;
+    }
+    if (typeof v === 'number' || typeof v === 'boolean') {
+        out.push(`${prefix}: ${String(v)}`);
+        return;
+    }
+    if (depth <= 0)
+        return;
+    if (Array.isArray(v)) {
+        v.forEach((item, i) => flattenScalars(`${prefix}[${i}]`, item, out, depth - 1));
+        return;
+    }
+    if (typeof v === 'object') {
+        for (const [k, val] of Object.entries(v)) {
+            flattenScalars(`${prefix}.${k}`, val, out, depth - 1);
+        }
+    }
+}
+export function buildSnippet(after, type) {
+    const parts = [];
+    if (type)
+        parts.push(type.replace('/', ' / '));
+    for (const [k, v] of Object.entries(after)) {
+        if (SKIP_FIELDS.has(k))
+            continue;
+        flattenScalars(k, v, parts, MAX_DEPTH);
+    }
+    return parts.join('\n').slice(0, MAX_SNIPPET);
+}
+function parseRef(type, recordId) {
+    const [vault, module] = type.split('/');
+    if (!vault || !module)
+        return null;
+    return { vault, module, recordId };
+}
+export async function indexOnce(opts) {
+    const embed = opts.embed ?? embedBatch;
+    const batch = opts.batch ?? 64;
+    if ((await getPluginState(PLUGIN, VERSION_KEY)) !== SNIPPET_VERSION) {
+        await setPluginState(PLUGIN, STATE_KEY, '0');
+        await setPluginState(PLUGIN, VERSION_KEY, SNIPPET_VERSION);
+    }
+    const last = Number((await getPluginState(PLUGIN, STATE_KEY)) ?? '0');
+    const rows = await listEventsSince(last, 5000);
+    if (rows.length === 0)
+        return 0;
+    const byRef = new Map();
+    for (const r of rows) {
+        if (r.record_id == null)
+            continue;
+        const ref = parseRef(r.type, r.record_id);
+        if (!ref)
+            continue;
+        const key = `${ref.vault}/${ref.module}/${ref.recordId}`;
+        if (r.op === 'delete') {
+            byRef.set(key, { ref, op: 'delete', type: r.type, snippet: '' });
+        }
+        else if (r.after) {
+            const after = JSON.parse(r.after);
+            byRef.set(key, { ref, op: 'upsert', type: r.type, snippet: buildSnippet(after, r.type) });
+        }
+    }
+    const upserts = [...byRef.values()].filter((p) => p.op === 'upsert' && p.snippet.trim());
+    const deletes = [...byRef.values()].filter((p) => p.op === 'delete');
+    for (const d of deletes)
+        await deleteEmbedding(d.type, d.ref.recordId);
+    const root = isTracing()
+        ? langfuseFactory.startObservation('indexer-run', { metadata: { events: rows.length, upserts: upserts.length } }, { asType: 'span' })
+        : undefined;
+    try {
+        for (let i = 0; i < upserts.length; i += batch) {
+            const slice = upserts.slice(i, i + batch);
+            const gen = root?.startObservation('embed-batch', { model: EMBED_MODEL, metadata: { count: slice.length } }, { asType: 'generation' });
+            const { vectors, tokens } = await embed(slice.map((p) => p.snippet), opts.apiKey);
+            gen?.update({ usageDetails: { total: tokens }, output: { count: vectors.length } }).end();
+            for (let j = 0; j < slice.length; j++) {
+                const p = slice[j];
+                const vec = vectors[j];
+                if (vec)
+                    await upsertEmbedding({ type: p.type, recordId: p.ref.recordId, snippet: p.snippet, vector: vec, model: EMBED_MODEL });
+            }
+        }
+    }
+    finally {
+        root?.end();
+        if (root)
+            await flushTracing();
+    }
+    const lastRow = rows[rows.length - 1];
+    if (lastRow)
+        await setPluginState(PLUGIN, STATE_KEY, String(lastRow.id));
+    return rows.length;
+}

package/dist/runtime/local-client.d.ts

@@ -0,0 +1,10 @@
+import type { CofferClientApi } from '@coffer-org/mcp/client';
+export declare function mapError(e: unknown): never;
+export declare class LocalClient implements CofferClientApi {
+    getSchema(): Promise<unknown>;
+    listRecords(vault: string, type: string, query?: Record<string, unknown>): Promise<unknown>;
+    getRecord(vault: string, type: string, id: number): Promise<unknown>;
+    createRecord(vault: string, type: string, fields: Record<string, unknown>): Promise<unknown>;
+    updateRecord(vault: string, type: string, id: number, fields: Record<string, unknown>): Promise<unknown>;
+    deleteRecord(vault: string, type: string, id: number): Promise<unknown>;
+}

package/dist/runtime/local-client.js

@@ -0,0 +1,57 @@
+import { ValidationError, NotFoundError } from '@coffer-org/mcp/client';
+import { recordList, recordGet, recordCreate, recordUpdate, recordDelete, UnknownTypeError, } from '@coffer-org/server/records-api';
+import { ValidationError as ServerValidationError } from '@coffer-org/server/mutate';
+import { buildClientSchema } from '@coffer-org/server/schema-api';
+export function mapError(e) {
+    if (e instanceof ServerValidationError)
+        throw new ValidationError(e.issues ?? []);
+    if (e instanceof UnknownTypeError)
+        throw new NotFoundError('not_found');
+    throw e;
+}
+export class LocalClient {
+    async getSchema() {
+        return buildClientSchema();
+    }
+    async listRecords(vault, type, query = {}) {
+        try {
+            return await recordList(vault, type, query);
+        }
+        catch (e) {
+            mapError(e);
+        }
+    }
+    async getRecord(vault, type, id) {
+        try {
+            return await recordGet(vault, type, id);
+        }
+        catch (e) {
+            mapError(e);
+        }
+    }
+    async createRecord(vault, type, fields) {
+        try {
+            return await recordCreate(vault, type, fields);
+        }
+        catch (e) {
+            mapError(e);
+        }
+    }
+    async updateRecord(vault, type, id, fields) {
+        try {
+            return await recordUpdate(vault, type, id, fields);
+        }
+        catch (e) {
+            mapError(e);
+        }
+    }
+    async deleteRecord(vault, type, id) {
+        try {
+            await recordDelete(vault, type, id);
+            return null;
+        }
+        catch (e) {
+            mapError(e);
+        }
+    }
+}

package/dist/runtime/rag.d.ts

@@ -0,0 +1,7 @@
+import type { McpServerConfig } from '@anthropic-ai/claude-agent-sdk';
+import type { EmbeddingHit } from '@coffer-org/server/embeddings';
+export declare function formatHits(hits: EmbeddingHit[]): string;
+export declare function makeRagServer(cfg: {
+    embeddingApiKey: string;
+    ragTopK: number;
+}): McpServerConfig;

package/dist/runtime/rag.js

@@ -0,0 +1,38 @@
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { searchEmbeddings } from '@coffer-org/server/embeddings';
+import { embedOne, EMBED_MODEL } from "./embed.js";
+import { isTracing, flushTracing, langfuseFactory } from "./tracing.js";
+export function formatHits(hits) {
+    if (hits.length === 0)
+        return 'No matching records.';
+    return hits
+        .map((h) => `[${h.type}/${h.recordId}] (dist ${h.distance.toFixed(3)})\n${h.snippet}`)
+        .join('\n\n');
+}
+export function makeRagServer(cfg) {
+    return createSdkMcpServer({
+        name: 'rag',
+        version: '1.0.0',
+        tools: [
+            tool('search_records', "Semantic search over the user's coffer records. Returns the most relevant records as type/id refs with a text snippet.", { query: z.string(), k: z.number().int().positive().optional() }, async (args) => {
+                const gen = isTracing()
+                    ? langfuseFactory.startObservation('embed-query', { model: EMBED_MODEL, input: args.query }, { asType: 'generation' })
+                    : undefined;
+                let vector;
+                try {
+                    const r = await embedOne(args.query, cfg.embeddingApiKey);
+                    vector = r.vector;
+                    gen?.update({ usageDetails: { total: r.tokens } });
+                }
+                finally {
+                    gen?.end();
+                    if (gen)
+                        await flushTracing();
+                }
+                const hits = await searchEmbeddings(vector, args.k ?? cfg.ragTopK);
+                return { content: [{ type: 'text', text: formatHits(hits) }] };
+            }),
+        ],
+    });
+}

package/dist/runtime/tracing.d.ts

@@ -0,0 +1,73 @@
+export interface TracingConfig {
+    tracingEnabled: boolean;
+    langfusePublicKey: string;
+    langfuseSecretKey: string;
+    langfuseBaseUrl: string;
+}
+export interface Obs {
+    startObservation(name: string, attrs?: Record<string, unknown>, opts?: {
+        asType?: string;
+    }): Obs;
+    update(attrs: Record<string, unknown>): Obs;
+    updateTrace(attrs: Record<string, unknown>): Obs;
+    end(): void;
+}
+export interface ObsFactory {
+    startObservation(name: string, attrs?: Record<string, unknown>, opts?: {
+        asType?: string;
+    }): Obs;
+}
+export declare function shouldEnable(cfg: TracingConfig): boolean;
+export declare function initTracing(cfg: TracingConfig): void;
+export declare function isTracing(): boolean;
+export declare function flushTracing(): Promise<void>;
+export declare const langfuseFactory: ObsFactory;
+type ContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: unknown;
+} | {
+    type: string;
+    [k: string]: unknown;
+};
+interface Usage {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+}
+export type AgentMsg = {
+    type: 'assistant';
+    message: {
+        model?: string;
+        content: ContentBlock[];
+        usage?: Usage;
+    };
+} | {
+    type: 'user';
+    message: {
+        content: ContentBlock[];
+    };
+} | {
+    type: 'result';
+    subtype: string;
+    session_id?: string;
+    usage?: Usage;
+    result?: string;
+};
+export declare class TurnTracer {
+    private root;
+    private tools;
+    constructor(factory: ObsFactory, prompt: string, resumeSessionId: string | null);
+    onMessage(msg: AgentMsg): void;
+    fail(message: string): void;
+}
+export {};

package/dist/runtime/tracing.js

@@ -0,0 +1,114 @@
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { LangfuseSpanProcessor } from '@langfuse/otel';
+import { startObservation } from '@langfuse/tracing';
+export function shouldEnable(cfg) {
+    return Boolean(cfg.tracingEnabled && cfg.langfusePublicKey && cfg.langfuseSecretKey);
+}
+let provider;
+let processor;
+let enabled = false;
+export function initTracing(cfg) {
+    if (provider)
+        return;
+    if (!shouldEnable(cfg))
+        return;
+    processor = new LangfuseSpanProcessor({
+        publicKey: cfg.langfusePublicKey,
+        secretKey: cfg.langfuseSecretKey,
+        baseUrl: cfg.langfuseBaseUrl,
+    });
+    provider = new NodeTracerProvider({ spanProcessors: [processor] });
+    provider.register();
+    enabled = true;
+}
+export function isTracing() {
+    return enabled;
+}
+export async function flushTracing() {
+    if (processor)
+        await processor.forceFlush();
+}
+export const langfuseFactory = {
+    startObservation: (name, attrs, opts) => startObservation(name, attrs, opts),
+};
+function usageDetails(u) {
+    if (!u)
+        return undefined;
+    const d = {};
+    if (u.input_tokens != null)
+        d.input = u.input_tokens;
+    if (u.output_tokens != null)
+        d.output = u.output_tokens;
+    if (u.cache_read_input_tokens != null)
+        d.cache_read_input_tokens = u.cache_read_input_tokens;
+    if (u.cache_creation_input_tokens != null)
+        d.cache_creation_input_tokens = u.cache_creation_input_tokens;
+    return Object.keys(d).length ? d : undefined;
+}
+export class TurnTracer {
+    root;
+    tools = new Map();
+    constructor(factory, prompt, resumeSessionId) {
+        this.root = factory.startObservation('agent-turn', { input: prompt, metadata: { resumeSessionId } }, { asType: 'agent' });
+        if (resumeSessionId)
+            this.root.updateTrace({ sessionId: resumeSessionId });
+    }
+    onMessage(msg) {
+        if (msg.type === 'assistant') {
+            let text = '';
+            const toolUses = [];
+            for (const b of msg.message.content) {
+                if (b.type === 'text')
+                    text += b.text;
+                else if (b.type === 'tool_use')
+                    toolUses.push(b);
+            }
+            const gen = this.root.startObservation('llm-call', { model: msg.message.model, output: { text, toolUses } }, { asType: 'generation' });
+            const ud = usageDetails(msg.message.usage);
+            if (ud)
+                gen.update({ usageDetails: ud });
+            gen.end();
+            for (const tu of toolUses) {
+                const t = tu;
+                const obs = this.root.startObservation(t.name, { input: t.input }, { asType: 'tool' });
+                this.tools.set(t.id, obs);
+            }
+            return;
+        }
+        if (msg.type === 'user') {
+            for (const b of msg.message.content) {
+                if (b.type === 'tool_result') {
+                    const r = b;
+                    const obs = this.tools.get(r.tool_use_id);
+                    if (obs) {
+                        obs.update({ output: r.content }).end();
+                        this.tools.delete(r.tool_use_id);
+                    }
+                }
+            }
+            return;
+        }
+        if (msg.type === 'result') {
+            for (const obs of this.tools.values())
+                obs.end();
+            this.tools.clear();
+            if (msg.session_id)
+                this.root.updateTrace({ sessionId: msg.session_id });
+            const out = { output: msg.result ?? null };
+            const ud = usageDetails(msg.usage);
+            if (ud)
+                out.usageDetails = ud;
+            if (msg.subtype !== 'success') {
+                out.level = 'ERROR';
+                out.statusMessage = `result subtype=${msg.subtype}`;
+            }
+            this.root.update(out).end();
+        }
+    }
+    fail(message) {
+        for (const obs of this.tools.values())
+            obs.end();
+        this.tools.clear();
+        this.root.update({ level: 'ERROR', statusMessage: message }).end();
+    }
+}

package/dist/runtime/workspace.d.ts

@@ -0,0 +1,7 @@
+import type { AgentConfig } from './config.ts';
+interface WarnLog {
+    warn?: (m: string) => void;
+}
+export declare function linkCredentials(cfg: Pick<AgentConfig, 'claudeHomeDir' | 'globalCredentials'>, log?: WarnLog): boolean;
+export declare function ensureWorkspace(cfg: Pick<AgentConfig, 'appRoot' | 'workspaceDir' | 'claudeHomeDir' | 'stateDir' | 'globalCredentials'>, log?: WarnLog): void;
+export {};

package/dist/runtime/workspace.js

@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function linkCredentials(cfg, log = console) {
+    const target = path.join(cfg.claudeHomeDir, '.credentials.json');
+    fs.rmSync(target, { force: true });
+    if (fs.existsSync(cfg.globalCredentials)) {
+        fs.symlinkSync(cfg.globalCredentials, target);
+        return true;
+    }
+    log.warn?.(`[agent] global credentials not found (${cfg.globalCredentials}) — claude will be "Not logged in"`);
+    return false;
+}
+export function ensureWorkspace(cfg, log = console) {
+    fs.mkdirSync(path.join(cfg.stateDir, '.sessions'), { recursive: true });
+    fs.mkdirSync(path.join(cfg.workspaceDir, '.claude', 'skills'), { recursive: true });
+    fs.mkdirSync(cfg.claudeHomeDir, { recursive: true });
+    const mcp = { mcpServers: {} };
+    fs.writeFileSync(path.join(cfg.workspaceDir, '.mcp.json'), JSON.stringify(mcp, null, 2) + '\n', 'utf-8');
+    const appGlob = `//${cfg.appRoot.replace(/^\/+/, '')}/**`;
+    const settings = {
+        permissions: {
+            allow: ['mcp__coffer__*', 'WebSearch', 'WebFetch', 'Skill'],
+            deny: ['Bash', 'Edit', 'Write', `Read(${appGlob})`, `Glob(${appGlob})`, `Grep(${appGlob})`],
+        },
+        enableAllProjectMcpServers: false,
+    };
+    fs.writeFileSync(path.join(cfg.claudeHomeDir, 'settings.json'), JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    linkCredentials(cfg, log);
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@coffer-org/plugin-agent",
+  "version": "1.2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./runtime": "./src/runtime/index.ts"
+  },
+  "distExports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "default": "./dist/runtime/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "test": "node --import tsx --test \"src/runtime/*.test.ts\""
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.191",
+    "@coffer-org/mcp": "^1.2.0",
+    "@coffer-org/sdk": "^1.2.0",
+    "@coffer-org/server": "^1.2.0",
+    "@langfuse/otel": "^4.6.1",
+    "@langfuse/tracing": "^4.6.1",
+    "@opentelemetry/sdk-trace-node": "^2.8.0",
+    "zod": "^4.4.0"
+  }
+}