@coffer-org/plugin-claude-agent 1.4.0

package/dist/runtime/nudge-scheduler.js

@@ -0,0 +1,45 @@
+const defaultTimer = (cb, ms) => {
+    const t = setTimeout(cb, ms);
+    if (typeof t.unref === 'function')
+        t.unref();
+};
+export function makeScheduler(run, opts = {}) {
+    const delayMs = opts.delayMs ?? 500;
+    const setTimer = opts.setTimer ?? defaultTimer;
+    let armed = false;
+    let running = false;
+    let pending = false;
+    async function fire() {
+        armed = false;
+        if (running) {
+            pending = true;
+            return;
+        }
+        running = true;
+        try {
+            do {
+                pending = false;
+                try {
+                    await run();
+                }
+                catch {
+                }
+            } while (pending);
+        }
+        finally {
+            running = false;
+        }
+    }
+    return {
+        schedule() {
+            if (running) {
+                pending = true;
+                return;
+            }
+            if (armed)
+                return;
+            armed = true;
+            setTimer(() => void fire(), delayMs);
+        },
+    };
+}

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

@@ -0,0 +1,23 @@
+export interface ConvMessage {
+    role: 'user' | 'assistant';
+    content: string;
+    sender?: string | null;
+    msgId: string;
+    ts: number;
+}
+export interface SystemLayer {
+    text: string;
+    stable: boolean;
+}
+export interface AgentRequest {
+    system: SystemLayer[];
+    messages: ConvMessage[];
+    onDelta?: (accumulated: string) => void;
+    onSegment?: () => void;
+}
+export interface AgentResult {
+    text: string | null;
+    tokensIn: number | null;
+    tokensOut: number | null;
+    stopReason: string | null;
+}

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export {};

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);
+}