@coffer-org/server 2.3.0 → 2.3.2

package/dist/embed-openai.d.ts

@@ -1,5 +1,19 @@
 export declare const EMBED_MODEL = "text-embedding-3-small";
 export declare const EMBED_DIM = 1024;
+export type EmbeddingFailureReason = 'billing' | 'auth' | 'rate_limit' | 'server' | 'network' | 'unknown';
+export declare class OpenAIEmbeddingError extends Error {
+    readonly status: number | null;
+    readonly code: string | null;
+    readonly reason: EmbeddingFailureReason;
+    constructor(args: {
+        status?: number | null;
+        code?: string | null;
+        detail?: string;
+        reason?: EmbeddingFailureReason;
+        cause?: unknown;
+    });
+}
+export declare function embeddingFailureMessage(error: unknown): string;
 export declare function embedBatch(texts: string[], apiKey: string, fetchImpl?: typeof fetch): Promise<{
     vectors: number[][];
     tokens: number;

package/dist/embed-openai.js

@@ -1,19 +1,78 @@
 const OPENAI_URL = 'https://api.openai.com/v1/embeddings';
 export const EMBED_MODEL = 'text-embedding-3-small';
 export const EMBED_DIM = 1024;
+export class OpenAIEmbeddingError extends Error {
+    status;
+    code;
+    reason;
+    constructor(args) {
+        const status = args.status ?? null;
+        const suffix = args.detail ? `: ${args.detail}` : '';
+        super(`openai embeddings${status == null ? '' : ` ${status}`}${suffix}`, { cause: args.cause });
+        this.name = 'OpenAIEmbeddingError';
+        this.status = status;
+        this.code = args.code ?? null;
+        this.reason = args.reason ?? classifyEmbeddingFailure(status, args.code, args.detail);
+    }
+}
+function parseErrorBody(body) {
+    try {
+        const value = JSON.parse(body);
+        const code = typeof value.error?.code === 'string' ? value.error.code : null;
+        const message = typeof value.error?.message === 'string' ? value.error.message : '';
+        if (code || message)
+            return { code, detail: message || code || 'request failed' };
+    }
+    catch {
+    }
+    return { code: null, detail: body.slice(0, 200) || 'request failed' };
+}
+function classifyEmbeddingFailure(status, code, detail) {
+    const marker = `${code ?? ''} ${detail ?? ''}`.toLowerCase();
+    if (status === 402 || /insufficient_quota|billing|payment_required|payment required|hard.?limit|quota exceeded/.test(marker))
+        return 'billing';
+    if (status === 401 || status === 403)
+        return 'auth';
+    if (status === 429 || /rate.?limit/.test(marker))
+        return 'rate_limit';
+    if (status != null && status >= 500)
+        return 'server';
+    return 'unknown';
+}
+export function embeddingFailureMessage(error) {
+    if (!(error instanceof OpenAIEmbeddingError))
+        return error instanceof Error ? error.message : String(error);
+    switch (error.reason) {
+        case 'billing':
+            return 'OpenAI billing or quota is unavailable. RAG indexing/search is paused; records are still saved and indexing will retry after billing is restored.';
+        case 'auth':
+            return 'The OpenAI API key was rejected. RAG indexing/search is unavailable; records are still saved.';
+        case 'rate_limit':
+            return 'OpenAI rate limit reached. RAG indexing/search will retry; records are still saved.';
+        default:
+            return `OpenAI embeddings are unavailable${error.status == null ? '' : ` (HTTP ${error.status})`}. RAG will retry; records are still saved.`;
+    }
+}
 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 }),
-    });
+    let res;
+    try {
+        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 }),
+        });
+    }
+    catch (cause) {
+        throw new OpenAIEmbeddingError({ reason: 'network', detail: 'network request failed', cause });
+    }
     if (!res.ok) {
         const body = await res.text().catch(() => '');
-        throw new Error(`openai embeddings ${res.status}: ${body.slice(0, 200)}`);
+        const parsed = parseErrorBody(body);
+        throw new OpenAIEmbeddingError({ status: res.status, code: parsed.code, detail: parsed.detail });
     }
     const json = (await res.json());
     const vectors = [...json.data].sort((a, b) => a.index - b.index).map((d) => d.embedding);

package/dist/mcp-tools.d.ts

@@ -16,7 +16,6 @@ export interface McpToolDef {
 }
 export interface RagDeps {
     embeddingApiKey: string;
-    topK: number;
 }
 export declare function formatHits(hits: EmbeddingHit[]): string;
 export declare function resolveRagDeps(): Promise<RagDeps | null>;

package/dist/mcp-tools.js

@@ -11,11 +11,12 @@ import { describeCondition } from '@coffer-org/sdk/condition';
 import { getEm } from "./db.js";
 import { getPluginSettings } from "./plugin-runtime.js";
 import { searchEmbeddings } from "./embeddings.js";
-import { embedOne } from "./embed-openai.js";
+import { embedOne, embeddingFailureMessage } from "./embed-openai.js";
 import { getLogger } from "./log.js";
 import { writePluginSettings, listSettings } from "./settings-write.js";
 import { ValidationError, NotFoundError } from "./mutate.js";
 const log = getLogger('mcp-tools');
+const DEFAULT_RAG_TOP_K = 5;
 export function formatHits(hits) {
     if (hits.length === 0)
         return 'No matching records.';
@@ -31,10 +32,9 @@ export async function resolveRagDeps() {
     const db = (await getPluginSettings('claude-agent'));
     const enabled = db['rag_enabled'] !== false;
     const embeddingApiKey = (process.env.OPENAI_API_KEY ?? db['openai_api_key'] ?? '');
-    const topK = 5;
     if (!enabled || !embeddingApiKey)
         return null;
-    return { embeddingApiKey, topK };
+    return { embeddingApiKey };
 }
 export async function collectMcpTools(opts = {}) {
     const out = [];
@@ -127,7 +127,7 @@ export async function collectMcpTools(opts = {}) {
         }
     }
     if (opts.rag) {
-        const { embeddingApiKey, topK } = opts.rag;
+        const { embeddingApiKey } = opts.rag;
         out.push({
             server: 'rag',
             bareName: 'search_records',
@@ -139,11 +139,11 @@ export async function collectMcpTools(opts = {}) {
             handler: async (args) => {
                 try {
                     const { vector } = await embedOne(args.query, embeddingApiKey);
-                    const hits = await searchEmbeddings(vector, args.k ?? topK);
+                    const hits = await searchEmbeddings(vector, args.k ?? DEFAULT_RAG_TOP_K);
                     return { content: [{ type: 'text', text: formatHits(hits) }] };
                 }
                 catch (e) {
-                    return fail(`Error: ${e.message}`);
+                    return fail(`RAG unavailable: ${embeddingFailureMessage(e)} Use the regular coffer tools (list_records/get_record) instead.`);
                 }
             },
         });

package/dist/plugin-updates.d.ts

@@ -1,5 +1,7 @@
 import type { PluginAssetRecord } from './plugin-discovery.ts';
-export declare function checkLatestVersion(pkgName: string): Promise<string | null>;
+export declare function checkLatestVersion(pkgName: string, opts?: {
+    force?: boolean;
+}): Promise<string | null>;
 export type UpdateTarget = {
     ok: true;
     packageName: string;

package/dist/plugin-updates.js

@@ -14,12 +14,12 @@ function readCache(raw) {
         return null;
     }
 }
-export async function checkLatestVersion(pkgName) {
+export async function checkLatestVersion(pkgName, opts = {}) {
     const key = stateKey(pkgName);
     let cached = null;
     try {
         cached = readCache(await getPluginState(STATE_PLUGIN, key));
-        if (cached && Date.now() - cached.checkedAt < TTL_MS)
+        if (!opts.force && cached && Date.now() - cached.checkedAt < TTL_MS)
             return cached.latestVersion;
         const res = await fetch(`https://registry.npmjs.org/${pkgName}/latest`, { signal: AbortSignal.timeout(5000) });
         if (!res.ok)

package/dist/plugins-api.d.ts

@@ -15,5 +15,5 @@ export interface PluginListEntry {
     web?: string;
     css?: string;
 }
-export declare function buildPluginListResponse(plugins: PluginManifest[], assets: PluginAssetRecord[], disabled: Set<string>, withUpdates?: boolean): Promise<PluginListEntry[]>;
+export declare function buildPluginListResponse(plugins: PluginManifest[], assets: PluginAssetRecord[], disabled: Set<string>, withUpdates?: boolean, forceUpdates?: boolean): Promise<PluginListEntry[]>;
 export declare function registerPluginsApi(app: FastifyInstance): Promise<void>;

package/dist/plugins-api.js

@@ -5,14 +5,14 @@ import { getPlugins, readDisabled } from "./plugin-runtime.js";
 import { checkLatestVersion } from "./plugin-updates.js";
 const nmRoot = () => join(process.cwd(), 'node_modules');
 const ASSET_KEY = { 'schema.js': 'schema', 'web.js': 'web', 'web.css': 'css' };
-export async function buildPluginListResponse(plugins, assets, disabled, withUpdates = true) {
+export async function buildPluginListResponse(plugins, assets, disabled, withUpdates = true, forceUpdates = false) {
     const assetById = new Map(assets.map((a) => [a.id, a]));
     return Promise.all(plugins.map(async (p) => {
         const a = assetById.get(p.id);
         return {
             id: p.id,
             installedVersion: a?.version ?? p.version,
-            latestVersion: withUpdates && a && !a.local ? await checkLatestVersion(a.packageName) : null,
+            latestVersion: withUpdates && a && !a.local ? await checkLatestVersion(a.packageName, { force: forceUpdates }) : null,
             packageName: a?.packageName ?? null,
             dependsOn: p.dependsOn,
             enabled: !disabled.has(p.id),
@@ -27,15 +27,18 @@ export async function buildPluginListResponse(plugins, assets, disabled, withUpd
 }
 export async function registerPluginsApi(app) {
     app.get('/api/plugins', async (req) => {
-        const withUpdates = req.query.updates === '1';
+        const query = req.query;
+        const withUpdates = query.updates === '1';
+        const forceUpdates = query.refresh === '1';
         const [plugins, assets, disabled] = await Promise.all([getPlugins(), discoverPluginAssets(), readDisabled()]);
-        return buildPluginListResponse(plugins, assets, disabled, withUpdates);
+        return buildPluginListResponse(plugins, assets, disabled, withUpdates, forceUpdates);
     });
-    app.get('/api/runtime', async () => {
+    app.get('/api/runtime', async (req) => {
         const runtime = await discoverRuntime();
         if (!runtime)
             return { installedVersion: null, latestVersion: null };
-        const latestVersion = runtime.local ? null : await checkLatestVersion(runtime.packageName);
+        const forceUpdates = req.query.refresh === '1';
+        const latestVersion = runtime.local ? null : await checkLatestVersion(runtime.packageName, { force: forceUpdates });
         return { installedVersion: runtime.installedVersion, latestVersion };
     });
     app.get('/plugins/:id/:file', async (req, reply) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffer-org/server",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "type": "module",
   "engines": {
     "node": ">=24"