r2mcp 0.2.0

package/dist/providers/errors.js

@@ -0,0 +1,19 @@
+/**
+ * Provider-selection error surfaces. Kept in a dedicated module so consumers
+ * can import them without pulling in the heavy adapter modules.
+ */
+export class ProviderUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ProviderUnavailableError';
+    }
+}
+/**
+ * The exact error message thrown when no provider can be auto-selected.
+ * D.AC4 requires that all three remediation paths be named.
+ */
+export const NO_PROVIDER_AVAILABLE_MESSAGE = 'No LLM provider is configured. Pick one of:\n' +
+    '  • Claude Code (Max plan, $0/call): run `claude /login` so the headless adapter can spawn `claude -p`.\n' +
+    '  • Anthropic API: export ANTHROPIC_API_KEY=sk-... and re-run.\n' +
+    '  • OpenRouter: export R2MCP_OPENROUTER_API_KEY=sk-or-... and re-run.\n' +
+    'You can also force a specific provider via --provider=<claude-code|anthropic|openrouter> or R2MCP_CLASSIFIER_PROVIDER.';

package/dist/providers/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Public surface for the LLMProvider layer.
+ *
+ * Selection precedence (D.R3):
+ *   1. `flag` (e.g., from --provider=...)
+ *   2. R2MCP_CLASSIFIER_PROVIDER env var
+ *   3. Auto-fallback: claude-code (if logged in) → anthropic (if API key)
+ *      → openrouter (if API key) → ProviderUnavailableError
+ */
+import type { LLMProvider, ProviderName } from './types.js';
+export type { CompleteRequest, CompleteResponse, LLMProvider, LogicalModel, ProviderName, } from './types.js';
+export { AnthropicProvider } from './anthropic.js';
+export { ClaudeCodeProvider, probeClaudeCode } from './claude-code.js';
+export { OpenRouterProvider } from './openrouter.js';
+export { Semaphore } from './semaphore.js';
+export { ProviderUnavailableError, NO_PROVIDER_AVAILABLE_MESSAGE } from './errors.js';
+export declare function isProviderName(name: string): name is ProviderName;
+export interface SelectProviderOptions {
+    /** Provider name from --provider=... flag. Highest precedence. */
+    flag?: ProviderName;
+    /** Process env (defaults to process.env). Tests override this. */
+    env?: NodeJS.ProcessEnv;
+    /** Probe whether Claude Code is logged in. Default uses real subprocess. */
+    probeClaudeCode?: () => Promise<boolean>;
+    /** Factory hooks (tests inject mocks; production uses defaults). */
+    makeAnthropic?: (apiKey: string) => LLMProvider;
+    makeClaudeCode?: () => LLMProvider;
+    makeOpenRouter?: (apiKey: string) => LLMProvider;
+}
+export declare function selectProvider(opts?: SelectProviderOptions): Promise<LLMProvider>;

package/dist/providers/index.js

@@ -0,0 +1,71 @@
+/**
+ * Public surface for the LLMProvider layer.
+ *
+ * Selection precedence (D.R3):
+ *   1. `flag` (e.g., from --provider=...)
+ *   2. R2MCP_CLASSIFIER_PROVIDER env var
+ *   3. Auto-fallback: claude-code (if logged in) → anthropic (if API key)
+ *      → openrouter (if API key) → ProviderUnavailableError
+ */
+import { AnthropicProvider } from './anthropic.js';
+import { ClaudeCodeProvider, probeClaudeCode } from './claude-code.js';
+import { OpenRouterProvider } from './openrouter.js';
+import { NO_PROVIDER_AVAILABLE_MESSAGE, ProviderUnavailableError } from './errors.js';
+export { AnthropicProvider } from './anthropic.js';
+export { ClaudeCodeProvider, probeClaudeCode } from './claude-code.js';
+export { OpenRouterProvider } from './openrouter.js';
+export { Semaphore } from './semaphore.js';
+export { ProviderUnavailableError, NO_PROVIDER_AVAILABLE_MESSAGE } from './errors.js';
+const PROVIDER_NAMES = ['anthropic', 'claude-code', 'openrouter'];
+export function isProviderName(name) {
+    return PROVIDER_NAMES.includes(name);
+}
+export async function selectProvider(opts = {}) {
+    const env = opts.env ?? process.env;
+    const probe = opts.probeClaudeCode ?? (() => probeClaudeCode());
+    const makeAnthropic = opts.makeAnthropic ?? ((apiKey) => new AnthropicProvider({ apiKey }));
+    const makeClaudeCode = opts.makeClaudeCode ?? (() => new ClaudeCodeProvider());
+    const makeOpenRouter = opts.makeOpenRouter ?? ((apiKey) => new OpenRouterProvider({ apiKey }));
+    // Precedence 1: explicit --provider flag
+    const explicit = opts.flag ?? readEnvProviderName(env);
+    if (explicit) {
+        return instantiate(explicit, env, { makeAnthropic, makeClaudeCode, makeOpenRouter });
+    }
+    // Precedence 2: auto-fallback. Claude Code first (Max-covered, $0/call).
+    if (await probe()) {
+        return makeClaudeCode();
+    }
+    if (env.ANTHROPIC_API_KEY) {
+        return makeAnthropic(env.ANTHROPIC_API_KEY);
+    }
+    if (env.R2MCP_OPENROUTER_API_KEY) {
+        return makeOpenRouter(env.R2MCP_OPENROUTER_API_KEY);
+    }
+    throw new ProviderUnavailableError(NO_PROVIDER_AVAILABLE_MESSAGE);
+}
+function readEnvProviderName(env) {
+    const raw = env.R2MCP_CLASSIFIER_PROVIDER;
+    if (!raw)
+        return undefined;
+    if (!isProviderName(raw)) {
+        throw new ProviderUnavailableError(`R2MCP_CLASSIFIER_PROVIDER=${raw} is not a recognized provider. Use one of: ${PROVIDER_NAMES.join(', ')}`);
+    }
+    return raw;
+}
+function instantiate(name, env, factories) {
+    if (name === 'claude-code')
+        return factories.makeClaudeCode();
+    if (name === 'anthropic') {
+        const apiKey = env.ANTHROPIC_API_KEY;
+        if (!apiKey) {
+            throw new ProviderUnavailableError('ANTHROPIC_API_KEY is required when --provider=anthropic is selected.');
+        }
+        return factories.makeAnthropic(apiKey);
+    }
+    // openrouter
+    const apiKey = env.R2MCP_OPENROUTER_API_KEY;
+    if (!apiKey) {
+        throw new ProviderUnavailableError('R2MCP_OPENROUTER_API_KEY is required when --provider=openrouter is selected.');
+    }
+    return factories.makeOpenRouter(apiKey);
+}

package/dist/providers/openrouter.d.ts

@@ -0,0 +1,19 @@
+import type { CompleteRequest, CompleteResponse, LLMProvider, LogicalModel, ProviderName } from './types.js';
+type FetchFn = typeof fetch;
+export interface OpenRouterOptions {
+    apiKey?: string;
+    fetchFn?: FetchFn;
+    /** Override the API endpoint (tests use this). */
+    endpoint?: string;
+}
+export declare class OpenRouterProvider implements LLMProvider {
+    readonly name: ProviderName;
+    readonly concurrencyLimit = 10;
+    private readonly apiKey;
+    private readonly fetchFn;
+    private readonly endpoint;
+    constructor(opts?: OpenRouterOptions);
+    static priceForTokens(model: LogicalModel, inputTokens: number, outputTokens: number): number;
+    complete(req: CompleteRequest): Promise<CompleteResponse>;
+}
+export {};

package/dist/providers/openrouter.js

@@ -0,0 +1,76 @@
+const OPENROUTER_URL = 'https://openrouter.ai/api/v1/chat/completions';
+// OpenRouter routes Anthropic models under their own slugs. Logical model →
+// OpenRouter slug. We pick the same family as the AnthropicProvider so cross-
+// provider agreement (D.AC6) measures abstraction quality, not model swap.
+const MODEL_IDS = {
+    haiku: 'anthropic/claude-haiku-4.5',
+    opus: 'anthropic/claude-opus-4.7',
+    sonnet: 'anthropic/claude-sonnet-4.6',
+};
+// OpenRouter passes through underlying model pricing. We approximate using
+// the same Anthropic list prices — operator can override via env var if
+// OpenRouter applies a markup.
+const PRICES = {
+    haiku: { input: 0.8, output: 4.0 },
+    opus: { input: 15.0, output: 75.0 },
+    sonnet: { input: 3.0, output: 15.0 },
+};
+const DEFAULT_MAX_TOKENS = 256;
+export class OpenRouterProvider {
+    name = 'openrouter';
+    concurrencyLimit = 10;
+    apiKey;
+    fetchFn;
+    endpoint;
+    constructor(opts = {}) {
+        const apiKey = opts.apiKey ?? process.env.R2MCP_OPENROUTER_API_KEY;
+        if (!apiKey) {
+            throw new Error('R2MCP_OPENROUTER_API_KEY is required to construct OpenRouterProvider');
+        }
+        this.apiKey = apiKey;
+        this.fetchFn = opts.fetchFn ?? fetch;
+        this.endpoint = opts.endpoint ?? OPENROUTER_URL;
+    }
+    static priceForTokens(model, inputTokens, outputTokens) {
+        const p = PRICES[model];
+        return (inputTokens / 1_000_000) * p.input + (outputTokens / 1_000_000) * p.output;
+    }
+    async complete(req) {
+        const startedAt = Date.now();
+        const messages = [];
+        if (req.system)
+            messages.push({ role: 'system', content: req.system });
+        messages.push({ role: 'user', content: req.prompt });
+        const body = {
+            model: MODEL_IDS[req.model],
+            max_tokens: req.max_tokens ?? DEFAULT_MAX_TOKENS,
+            messages,
+        };
+        const res = await this.fetchFn(this.endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.apiKey}`,
+                'HTTP-Referer': 'https://github.com/DMokong/r2mcp',
+                'X-Title': 'r2mcp-classifier',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const errBody = await res.text();
+            throw new Error(`OpenRouter ${res.status}: ${errBody.slice(0, 400)}`);
+        }
+        const data = (await res.json());
+        const text = data.choices[0]?.message?.content ?? '';
+        const inputTokens = data.usage?.prompt_tokens ?? 0;
+        const outputTokens = data.usage?.completion_tokens ?? 0;
+        return {
+            response: text,
+            cost_usd: OpenRouterProvider.priceForTokens(req.model, inputTokens, outputTokens),
+            latency_ms: Date.now() - startedAt,
+            input_tokens: inputTokens,
+            output_tokens: outputTokens,
+            raw: data,
+        };
+    }
+}

package/dist/providers/semaphore.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Counting semaphore for per-provider concurrency caps (D.R6, D.AC8).
+ *
+ * The driver wraps each provider call in `withPermit` so that no more than
+ * `limit` calls are in flight concurrently. `inFlight` is exposed so tests
+ * can observe peak concurrency.
+ */
+export declare class Semaphore {
+    readonly limit: number;
+    private _inFlight;
+    private waiters;
+    private _peak;
+    constructor(limit: number);
+    get inFlight(): number;
+    get peak(): number;
+    private acquire;
+    private release;
+    withPermit<T>(fn: () => Promise<T>): Promise<T>;
+}

package/dist/providers/semaphore.js

@@ -0,0 +1,51 @@
+/**
+ * Counting semaphore for per-provider concurrency caps (D.R6, D.AC8).
+ *
+ * The driver wraps each provider call in `withPermit` so that no more than
+ * `limit` calls are in flight concurrently. `inFlight` is exposed so tests
+ * can observe peak concurrency.
+ */
+export class Semaphore {
+    limit;
+    _inFlight = 0;
+    waiters = [];
+    _peak = 0;
+    constructor(limit) {
+        this.limit = limit;
+        if (limit < 1)
+            throw new Error(`Semaphore limit must be >= 1, got ${limit}`);
+    }
+    get inFlight() {
+        return this._inFlight;
+    }
+    get peak() {
+        return this._peak;
+    }
+    async acquire() {
+        if (this._inFlight < this.limit) {
+            this._inFlight++;
+            if (this._inFlight > this._peak)
+                this._peak = this._inFlight;
+            return;
+        }
+        await new Promise((resolve) => this.waiters.push(resolve));
+        this._inFlight++;
+        if (this._inFlight > this._peak)
+            this._peak = this._inFlight;
+    }
+    release() {
+        this._inFlight--;
+        const next = this.waiters.shift();
+        if (next)
+            next();
+    }
+    async withPermit(fn) {
+        await this.acquire();
+        try {
+            return await fn();
+        }
+        finally {
+            this.release();
+        }
+    }
+}

package/dist/providers/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * LLMProvider interface — the runtime-configurable layer that lets the edge
+ * classifier and the wiki compiler call into Anthropic SDK, Claude Code
+ * headless (Max OAuth), or OpenRouter without baking a cost-mode assumption
+ * into the architecture. SPEC-044 Section D.
+ */
+export type LogicalModel = 'haiku' | 'opus' | 'sonnet';
+export type ProviderName = 'anthropic' | 'claude-code' | 'openrouter';
+export interface CompleteRequest {
+    model: LogicalModel;
+    prompt: string;
+    system?: string;
+    max_tokens?: number;
+}
+export interface CompleteResponse {
+    response: string;
+    cost_usd: number;
+    latency_ms: number;
+    input_tokens?: number;
+    output_tokens?: number;
+    raw?: unknown;
+}
+export interface LLMProvider {
+    readonly name: ProviderName;
+    readonly concurrencyLimit: number;
+    complete(req: CompleteRequest): Promise<CompleteResponse>;
+}

package/dist/providers/types.js

@@ -0,0 +1,7 @@
+/**
+ * LLMProvider interface — the runtime-configurable layer that lets the edge
+ * classifier and the wiki compiler call into Anthropic SDK, Claude Code
+ * headless (Max OAuth), or OpenRouter without baking a cost-mode assumption
+ * into the architecture. SPEC-044 Section D.
+ */
+export {};

package/dist/schema.sql

@@ -0,0 +1,116 @@
+-- r2mcp — Database Schema
+-- PostgreSQL + pgvector: memories table with semantic search indexes
+
+CREATE TABLE IF NOT EXISTS memories (
+  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  content       TEXT NOT NULL,
+  tier          TEXT NOT NULL CHECK (tier IN ('preferences', 'project-context', 'conversations')),
+  type          TEXT NOT NULL CHECK (type IN ('preference', 'decision', 'context', 'relationship', 'observation', 'rejection', 'archived')),
+  section       TEXT,
+  topics        TEXT[] DEFAULT '{}',
+  people        TEXT[] DEFAULT '{}',
+  date          DATE,
+  fingerprint   TEXT NOT NULL UNIQUE,
+  embedding     vector(1536),
+  source_file   TEXT,
+  source_line   INTEGER,
+  created_at    TIMESTAMPTZ DEFAULT NOW(),
+  updated_at    TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Full-text search index
+ALTER TABLE memories ADD COLUMN IF NOT EXISTS tsv tsvector
+  GENERATED ALWAYS AS (to_tsvector('english', content)) STORED;
+CREATE INDEX IF NOT EXISTS idx_memories_tsv ON memories USING gin(tsv);
+
+-- pgvector index for semantic search (hnsw for small corpus)
+CREATE INDEX IF NOT EXISTS idx_memories_embedding ON memories USING hnsw (embedding vector_cosine_ops);
+
+-- Metadata indexes
+CREATE INDEX IF NOT EXISTS idx_memories_tier ON memories (tier);
+CREATE INDEX IF NOT EXISTS idx_memories_type ON memories (type);
+CREATE INDEX IF NOT EXISTS idx_memories_topics ON memories USING gin (topics);
+CREATE INDEX IF NOT EXISTS idx_memories_fingerprint ON memories (fingerprint);
+CREATE INDEX IF NOT EXISTS idx_memories_created ON memories (created_at);
+
+-- Migration: add 'archived' to type CHECK constraint (idempotent)
+DO $$
+BEGIN
+  ALTER TABLE memories DROP CONSTRAINT IF EXISTS memories_type_check;
+  ALTER TABLE memories ADD CONSTRAINT memories_type_check
+    CHECK (type IN ('preference', 'decision', 'context', 'relationship', 'observation', 'rejection', 'archived'));
+END $$;
+
+-- ============================================================================
+-- SPEC-043: memory_edges — typed relations between memories (Phase 1 wiki-mode)
+-- Mirrors OB1's thought_edges shape for future convergence.
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS memory_edges (
+  id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  from_memory_id      UUID NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  to_memory_id        UUID NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  relation            TEXT NOT NULL CHECK (relation IN (
+                        'supports', 'contradicts', 'supersedes',
+                        'evolved_into', 'depends_on', 'related_to'
+                      )),
+  confidence          NUMERIC(3,2) NOT NULL CHECK (confidence >= 0 AND confidence <= 1),
+  rationale           TEXT NOT NULL,
+  classifier_version  TEXT NOT NULL,
+  valid_from          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  valid_until         TIMESTAMPTZ,
+  created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  CONSTRAINT memory_edges_no_self CHECK (from_memory_id <> to_memory_id),
+  CONSTRAINT memory_edges_unique UNIQUE (from_memory_id, to_memory_id, relation)
+);
+
+-- Outgoing-edge lookup (used by recall() signals query AND Phase 2 compile)
+CREATE INDEX IF NOT EXISTS idx_edges_from
+  ON memory_edges (from_memory_id, relation);
+
+-- Incoming-edge lookup (used by recall() reverse signals AND Phase 2 compile)
+CREATE INDEX IF NOT EXISTS idx_edges_to
+  ON memory_edges (to_memory_id, relation);
+
+-- Partial index for currently-valid edges (used by Phase 3 lint)
+CREATE INDEX IF NOT EXISTS idx_edges_currently_valid
+  ON memory_edges (relation, from_memory_id)
+  WHERE valid_until IS NULL;
+
+-- ============================================================================
+-- SPEC-046: entities + memory_entities — light entity extraction (Phase 4 wiki-mode)
+-- Four-type taxonomy; one join table. Lighter than OB1's full ontology.
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS entities (
+  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  type            TEXT NOT NULL CHECK (type IN ('project', 'person', 'tool', 'decision')),
+  canonical_name  TEXT NOT NULL,
+  normalized_name TEXT NOT NULL,
+  aliases         TEXT[] NOT NULL DEFAULT '{}',
+  metadata        JSONB NOT NULL DEFAULT '{}',
+  first_seen_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  last_seen_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  CONSTRAINT entities_unique UNIQUE (type, normalized_name)
+);
+
+CREATE INDEX IF NOT EXISTS idx_entities_normalized ON entities (normalized_name);
+CREATE INDEX IF NOT EXISTS idx_entities_aliases    ON entities USING gin (aliases);
+CREATE INDEX IF NOT EXISTS idx_entities_type       ON entities (type);
+
+-- Note: memory_entities.confidence is NUMERIC(3,2) to match memory_edges.confidence
+-- from SPEC-043 (already shipped). The SPEC-046 PR review (claw-2jbo) flagged the
+-- prior REAL type as a cross-table inconsistency. Aligning here is safe because
+-- memory_entities ships for the first time in this PR — no shipped consumers.
+CREATE TABLE IF NOT EXISTS memory_entities (
+  memory_id   UUID         NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  entity_id   UUID         NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
+  confidence  NUMERIC(3,2) NOT NULL DEFAULT 1.0 CHECK (confidence BETWEEN 0 AND 1),
+  source      TEXT         NOT NULL DEFAULT 'classifier',
+  created_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (memory_id, entity_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_memory_entities_entity ON memory_entities (entity_id);
+CREATE INDEX IF NOT EXISTS idx_memory_entities_memory ON memory_entities (memory_id);

package/dist/server-instructions.d.ts

@@ -0,0 +1,9 @@
+/**
+ * MCP server instructions (claw-8cjf.8) — sent in the initialize response and
+ * loaded into the agent's context by Claude Code at session start. This is the
+ * only guidance a fresh project's agent gets, so it must teach the session
+ * loop on its own. Claude Code truncates at 2,048 characters; keep critical
+ * content near the start. Lives in its own module because src/index.ts runs
+ * main() on import and cannot be imported by tests.
+ */
+export declare const SERVER_INSTRUCTIONS = "Persistent memory across Claude Code sessions, stored in PostgreSQL with semantic search.\n\nSession loop:\n1. At session start, call recall with a query about the current task to load relevant context (e.g. recall({query: \"<topic you are working on>\"})).\n2. During work, call remember when something durable surfaces \u2014 a decision with its rationale, a user preference or correction, project state worth carrying forward. Choose the tier: \"preferences\" (decisions, style, corrections \u2014 never expires), \"project-context\" (architecture, system state), \"conversations\" (session continuity).\n3. When the user corrects your approach and the correction would apply again in future situations, store it with operation \"REJECTION\" so it is excluded from normal recall but prevents repeating the mistake.\n\nCold start: on a new, empty database, recall returns zero results \u2014 that is expected, not an error. Begin storing memories as durable facts emerge and recall becomes useful within a session or two.\n\nDegraded mode: responses may carry a warnings[] field (e.g. embeddings disabled because R2MCP_OPENROUTER_API_KEY is unset \u2014 search falls back to full-text). Surface such warnings to the user once rather than ignoring them.\n\nThe other tools (search, stats, meditate, reject, compile, lint, classify, extract_entities, dump_edges_sidecar) are for browsing, curation, and batch maintenance \u2014 recall and remember are the everyday pair.";

package/dist/server-instructions.js

@@ -0,0 +1,20 @@
+/**
+ * MCP server instructions (claw-8cjf.8) — sent in the initialize response and
+ * loaded into the agent's context by Claude Code at session start. This is the
+ * only guidance a fresh project's agent gets, so it must teach the session
+ * loop on its own. Claude Code truncates at 2,048 characters; keep critical
+ * content near the start. Lives in its own module because src/index.ts runs
+ * main() on import and cannot be imported by tests.
+ */
+export const SERVER_INSTRUCTIONS = `Persistent memory across Claude Code sessions, stored in PostgreSQL with semantic search.
+
+Session loop:
+1. At session start, call recall with a query about the current task to load relevant context (e.g. recall({query: "<topic you are working on>"})).
+2. During work, call remember when something durable surfaces — a decision with its rationale, a user preference or correction, project state worth carrying forward. Choose the tier: "preferences" (decisions, style, corrections — never expires), "project-context" (architecture, system state), "conversations" (session continuity).
+3. When the user corrects your approach and the correction would apply again in future situations, store it with operation "REJECTION" so it is excluded from normal recall but prevents repeating the mistake.
+
+Cold start: on a new, empty database, recall returns zero results — that is expected, not an error. Begin storing memories as durable facts emerge and recall becomes useful within a session or two.
+
+Degraded mode: responses may carry a warnings[] field (e.g. embeddings disabled because R2MCP_OPENROUTER_API_KEY is unset — search falls back to full-text). Surface such warnings to the user once rather than ignoring them.
+
+The other tools (search, stats, meditate, reject, compile, lint, classify, extract_entities, dump_edges_sidecar) are for browsing, curation, and batch maintenance — recall and remember are the everyday pair.`;

package/dist/telemetry.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Telemetry helpers for custom spans and metrics.
+ * Uses the OTel API — returns no-ops when SDK is not initialized.
+ */
+import { type Span } from '@opentelemetry/api';
+export declare const toolDuration: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+export declare const toolCount: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+export declare const toolErrors: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+export declare const embeddingDuration: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+export declare const embeddingCount: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+export declare const embeddingCost: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Wraps an async MCP tool handler with OTel span + metrics.
+ */
+export declare function withToolSpan<T>(toolName: string, attributes: Record<string, string | number | boolean>, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Wraps a single LLM provider.complete() call in a child span so the
+ * cross-process parent context (restored from OTEL_TRACEPARENT in scripts)
+ * has a concrete operation to inherit. Attributes mirror the
+ * provider.complete result: model, cost_usd, latency_ms. The provider name
+ * is supplied separately (the response payload doesn't carry it).
+ *
+ * spanName SHOULD be `memory.<op>.call` (e.g. memory.extract_entities.call)
+ * so traces group naturally with the top-level tool span.
+ *
+ * (claw-1ejd) — without this wrapper the OTEL_TRACEPARENT plumbing is a
+ * no-op because the subprocess never opens a span to inherit the parent.
+ */
+export declare function withLLMCallSpan<T extends {
+    cost_usd?: number;
+    latency_ms?: number;
+}>(spanName: string, attrs: {
+    provider: string;
+    model?: string;
+}, fn: () => Promise<T>): Promise<T>;
+/**
+ * Wraps an embedding API call with OTel span + metrics.
+ */
+export declare function withEmbeddingSpan<T>(textCount: number, fn: () => Promise<T>, totalChars?: number): Promise<T>;

package/dist/telemetry.js

@@ -0,0 +1,130 @@
+/**
+ * Telemetry helpers for custom spans and metrics.
+ * Uses the OTel API — returns no-ops when SDK is not initialized.
+ */
+import { trace, metrics, SpanStatusCode } from '@opentelemetry/api';
+const tracer = trace.getTracer('r2mcp', '0.1.0');
+const meter = metrics.getMeter('r2mcp', '0.1.0');
+// Metrics
+export const toolDuration = meter.createHistogram('r2mcp.memory.tool_duration_ms', {
+    description: 'Duration of MCP tool operations in milliseconds',
+    unit: 'ms',
+});
+export const toolCount = meter.createCounter('r2mcp.memory.tool_count', {
+    description: 'Number of MCP tool invocations',
+});
+export const toolErrors = meter.createCounter('r2mcp.memory.tool_errors', {
+    description: 'Number of MCP tool errors',
+});
+export const embeddingDuration = meter.createHistogram('r2mcp.memory.embedding_latency_ms', {
+    description: 'Duration of embedding API calls in milliseconds',
+    unit: 'ms',
+});
+export const embeddingCount = meter.createCounter('r2mcp.memory.embedding_count', {
+    description: 'Number of embedding API calls',
+});
+// Estimated cost per token for text-embedding-3-small via OpenRouter
+// OpenRouter pricing: $0.02 per 1M tokens for text-embedding-3-small
+const EMBEDDING_COST_PER_TOKEN = 0.00000002;
+export const embeddingCost = meter.createCounter('r2mcp.memory.embedding_cost_usd', {
+    description: 'Estimated cost of embedding API calls in USD',
+    unit: 'usd',
+});
+/**
+ * Wraps an async MCP tool handler with OTel span + metrics.
+ */
+export async function withToolSpan(toolName, attributes, fn) {
+    return tracer.startActiveSpan(`memory.${toolName}`, async (span) => {
+        const start = Date.now();
+        try {
+            span.setAttributes(attributes);
+            toolCount.add(1, { tool: toolName });
+            const result = await fn(span);
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        }
+        catch (err) {
+            span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+            toolErrors.add(1, { tool: toolName });
+            throw err;
+        }
+        finally {
+            const duration = Date.now() - start;
+            toolDuration.record(duration, { tool: toolName });
+            span.setAttribute('duration_ms', duration);
+            span.end();
+        }
+    });
+}
+/**
+ * Wraps a single LLM provider.complete() call in a child span so the
+ * cross-process parent context (restored from OTEL_TRACEPARENT in scripts)
+ * has a concrete operation to inherit. Attributes mirror the
+ * provider.complete result: model, cost_usd, latency_ms. The provider name
+ * is supplied separately (the response payload doesn't carry it).
+ *
+ * spanName SHOULD be `memory.<op>.call` (e.g. memory.extract_entities.call)
+ * so traces group naturally with the top-level tool span.
+ *
+ * (claw-1ejd) — without this wrapper the OTEL_TRACEPARENT plumbing is a
+ * no-op because the subprocess never opens a span to inherit the parent.
+ */
+export async function withLLMCallSpan(spanName, attrs, fn) {
+    return tracer.startActiveSpan(spanName, async (span) => {
+        const start = Date.now();
+        try {
+            span.setAttribute('llm.provider', attrs.provider);
+            if (attrs.model)
+                span.setAttribute('llm.model', attrs.model);
+            const result = await fn();
+            if (typeof result.cost_usd === 'number') {
+                span.setAttribute('llm.cost_usd', result.cost_usd);
+            }
+            if (typeof result.latency_ms === 'number') {
+                span.setAttribute('llm.latency_ms', result.latency_ms);
+            }
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        }
+        catch (err) {
+            span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+            throw err;
+        }
+        finally {
+            span.setAttribute('duration_ms', Date.now() - start);
+            span.end();
+        }
+    });
+}
+/**
+ * Wraps an embedding API call with OTel span + metrics.
+ */
+export async function withEmbeddingSpan(textCount, fn, totalChars) {
+    return tracer.startActiveSpan('memory.embedding', async (span) => {
+        const start = Date.now();
+        try {
+            span.setAttributes({ 'embedding.text_count': textCount });
+            embeddingCount.add(1);
+            if (totalChars) {
+                const estimatedTokens = Math.ceil(totalChars / 4);
+                const estimatedCostUsd = estimatedTokens * EMBEDDING_COST_PER_TOKEN;
+                embeddingCost.add(estimatedCostUsd);
+                span.setAttribute('embedding.estimated_tokens', estimatedTokens);
+                span.setAttribute('embedding.estimated_cost_usd', estimatedCostUsd);
+            }
+            const result = await fn();
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        }
+        catch (err) {
+            span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+            throw err;
+        }
+        finally {
+            const duration = Date.now() - start;
+            embeddingDuration.record(duration);
+            span.setAttribute('duration_ms', duration);
+            span.end();
+        }
+    });
+}