@openviking/opencode-plugin 0.2.2 → 0.2.4

package/lib/shared/recall-core.mjs

@@ -1,4 +1,10 @@
 // GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { compressRecallContext } from "./recall-compress-core.mjs";
+
 const PREFERENCE_QUERY_RE = /prefer|preference|favorite|favourite|like|偏好|喜欢|爱好|更倾向/i;
 const TEMPORAL_QUERY_RE = /when|what time|date|day|month|year|yesterday|today|tomorrow|last|next|什么时候|何时|哪天|几月|几年|昨天|今天|明天/i;
 const QUERY_TOKEN_RE = /[a-z0-9一-龥]{2,}/gi;
@@ -11,6 +17,17 @@ const SOURCES = [
   { type: "memory", uri: "viking://user/memories", bucket: "memories" },
   { type: "skill", uri: "viking://user/skills", bucket: "skills" },
 ];
+const DEFAULT_CONTEXT_LIMIT = 10;
+const DEFAULT_CONTEXT_MAX_TOKENS = 1600;
+const DEFAULT_REWRITE_MAX_BULLETS = 6;
+const CODING_QUOTA_WEIGHTS = {
+  events: 1,
+  entities: 2,
+  preferences: 1,
+  experiences: 1,
+  resources: 3,
+  skills: 2,
+};
 
 let userSpaceCache = "";
 
@@ -18,16 +35,47 @@ export function estimateTokens(text) {
   return text ? Math.ceil(String(text).length / 4) : 0;
 }
 
+function scaleQuotas(limit, weights) {
+  const slots = Math.max(1, Math.floor(Number(limit) || DEFAULT_CONTEXT_LIMIT));
+  const order = Object.keys(weights);
+  const quotas = Object.fromEntries(order.map((key) => [key, 0]));
+  if (slots < order.length) {
+    for (const key of order) quotas[key] = 1;
+    return quotas;
+  }
+
+  for (const key of order) quotas[key] = 1;
+  const totalWeight = Object.values(weights).reduce((sum, weight) => sum + weight, 0);
+  const ideals = Object.fromEntries(
+    order.map((key) => [key, slots * weights[key] / totalWeight]),
+  );
+  while (order.reduce((sum, key) => sum + quotas[key], 0) < slots) {
+    const key = order.reduce((best, candidate) => (
+      ideals[candidate] - quotas[candidate] > ideals[best] - quotas[best]
+        ? candidate
+        : best
+    ));
+    quotas[key] += 1;
+  }
+  return quotas;
+}
+
+function legacyMemoryQuotas(limit) {
+  return {
+    ...scaleQuotas(limit, { events: 10, entities: 10, preferences: 3 }),
+    experiences: 0,
+  };
+}
+
+function codingQuotas(limit) {
+  return scaleQuotas(limit, CODING_QUOTA_WEIGHTS);
+}
+
 export function buildRecallEndpointBody(cfg = {}) {
-  const limit = Math.max(Number(cfg.recallLimit || 0), 1);
+  const limit = Math.max(Number(cfg.recallLimit || DEFAULT_CONTEXT_LIMIT), 1);
   const body = {
     query: "",
-    quotas: {
-      events: limit,
-      entities: limit,
-      preferences: Math.max(1, Math.min(limit, 3)),
-      experiences: 0,
-    },
+    quotas: legacyMemoryQuotas(limit),
     max_chars: Math.max(Number(cfg.recallMaxContentChars || 0) * limit, 1000),
     min_score: Number.isFinite(Number(cfg.scoreThreshold)) ? Number(cfg.scoreThreshold) : 0.35,
     render: true,
@@ -36,6 +84,106 @@ export function buildRecallEndpointBody(cfg = {}) {
   return body;
 }
 
+/**
+ * Body for the server-side context face. The plugin declares intent (coding
+ * purpose, budget, session) and leaves the mechanics — quota ratios, tier
+ * degradation, cross-turn dedup — to the server's defaults.
+ */
+export function buildContextSearchBody(cfg = {}, options = {}) {
+  const rewriteMode = String(cfg.recallRewrite || "off").toLowerCase();
+  const limit = Math.max(1, Math.floor(Number(cfg.recallLimit || DEFAULT_CONTEXT_LIMIT)));
+  const maxTokens = Math.max(
+    64,
+    Math.floor(Number(cfg.recallMaxTokens || DEFAULT_CONTEXT_MAX_TOKENS)),
+  );
+  const body = {
+    query: "",
+    mode: "context",
+    purpose: "coding",
+    score_threshold: Number.isFinite(Number(cfg.scoreThreshold)) ? Number(cfg.scoreThreshold) : 0.35,
+  };
+  const limitConfigured = cfg.recallLimitConfigured === true;
+  const maxTokensConfigured = cfg.recallMaxTokensConfigured === true;
+  if (limitConfigured) body.quotas = codingQuotas(limit);
+  if (maxTokensConfigured) body.max_tokens = maxTokens;
+  if (cfg.recallPeerScope === "actor") body.peer_scope = "actor";
+
+  const sessionId = String(options.sessionId || "").trim();
+  if (sessionId) {
+    body.session_id = sessionId;
+    const queryExpansionConfigured = cfg.recallQueryExpansionConfigured === true;
+    if (queryExpansionConfigured) {
+      body.query_expansion = cfg.recallQueryExpansion === "off" ? "off" : "auto";
+    }
+    const dedupTurns = Number(cfg.recallDedupTurns);
+    const resolvedDedupTurns = Number.isFinite(dedupTurns)
+      ? Math.max(0, Math.floor(dedupTurns))
+      : 5;
+    if (resolvedDedupTurns > 0) body.dedup_turns = resolvedDedupTurns;
+  }
+
+  const excludeUris = Array.isArray(options.excludeUris) ? options.excludeUris.slice(0, 200) : [];
+  if (excludeUris.length) body.exclude_uris = excludeUris;
+
+  if (rewriteMode === "server") body.rewrite = true;
+  else if (rewriteMode === "auto" && !options.localCompressorAvailable) body.rewrite = "auto";
+  const rewriteMaxBullets = Math.max(
+    1,
+    Math.floor(Number(cfg.recallCompressMaxBullets || DEFAULT_REWRITE_MAX_BULLETS)),
+  );
+  const rewriteMaxBulletsConfigured = cfg.recallCompressMaxBulletsConfigured === true;
+  if (body.rewrite !== undefined && rewriteMaxBulletsConfigured) {
+    body.rewrite_max_bullets = rewriteMaxBullets;
+  }
+  return body;
+}
+
+// The server pipeline is serial and each optional stage has its own fuse. A
+// request is aborted client-side unless its deadline covers every stage it
+// asked for, and aborting discards the whole response rather than just the
+// stage that ran long.
+//
+//   session_id  -> query expansion   (retrieval.recall_intent_timeout_s,  5s)
+//   always      -> retrieval, body reads, budget planning
+//   rewrite     -> digest            (retrieval.recall_rewrite_timeout_s, 30s)
+//
+// Both budgets stay inside the 60s prompt-hook allowance, the rewrite one with
+// a quarter to spare.
+const EXPANSION_REQUEST_TIMEOUT_MS = 15000;
+const SERVER_REWRITE_REQUEST_TIMEOUT_MS = 45000;
+
+/**
+ * HTTP deadline for one context request, or undefined to keep the caller's own.
+ *
+ * Derived from the request body, because the body is what states which server
+ * stages will run: reading `cfg` alone cannot tell a bare retrieval from one
+ * that also spends the expansion or rewrite fuse.
+ */
+export function contextRequestTimeoutMs(cfg = {}, body = {}) {
+  const wantsRewrite = body.rewrite !== undefined;
+  // `query_expansion` defaults to "auto" server-side, so only an explicit "off"
+  // takes the expansion fuse back out of the budget.
+  const wantsExpansion = Boolean(body.session_id) && body.query_expansion !== "off";
+  if (!wantsRewrite && !wantsExpansion) return undefined;
+
+  const configured = Number(cfg.recallContextTimeoutMs);
+  if (Number.isFinite(configured) && configured > 0) return Math.max(1000, Math.floor(configured));
+  const floor = wantsRewrite ? SERVER_REWRITE_REQUEST_TIMEOUT_MS : EXPANSION_REQUEST_TIMEOUT_MS;
+  return Math.max(Number(cfg.timeoutMs) || 0, floor);
+}
+
+/**
+ * Strip the context-face fields a pre-context server rejects, converting the
+ * token budget back to v1's character budget.
+ */
+export function downgradeToRecallBody(contextBody = {}, cfg = {}) {
+  const body = buildRecallEndpointBody(cfg);
+  body.query = contextBody.query || "";
+  body.max_chars = Math.max(1000, Math.floor(Number(contextBody.max_tokens || 1600) * 4));
+  if (contextBody.peer_scope) body.peer_scope = contextBody.peer_scope;
+  return body;
+}
+
 function clampScore(v) {
   if (typeof v !== "number" || Number.isNaN(v)) return 0;
   return Math.max(0, Math.min(1, v));
@@ -232,6 +380,164 @@ async function buildFallbackInjectionBlock(fetchJSON, items, cfg, actorPeerId =
   return lines.join("\n");
 }
 
+const LEGACY_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+
+function stateFile(name) {
+  const override = String(process.env.OPENVIKING_STATE_DIR || "").trim();
+  return override ? join(override, name) : join(homedir(), ".openviking", "state", name);
+}
+
+async function readJsonFile(path) {
+  try { return JSON.parse(await readFile(path, "utf8")); } catch { return null; }
+}
+
+async function writeJsonFile(path, value) {
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    await writeFile(tmp, JSON.stringify(value));
+    await rename(tmp, path);
+  } catch { /* best effort */ }
+}
+
+/**
+ * Hooks are one-shot processes, so "this server has no context face" has to be
+ * remembered on disk or every turn pays for a rejected request.
+ */
+export async function isContextFaceLegacy(path = stateFile("context-face.json"), now = Date.now()) {
+  const cached = await readJsonFile(path);
+  return Boolean(cached?.legacyUntil && Number(cached.legacyUntil) > now);
+}
+
+export async function markContextFaceLegacy(path = stateFile("context-face.json"), now = Date.now()) {
+  await writeJsonFile(path, { legacyUntil: now + LEGACY_CACHE_TTL_MS });
+}
+
+function looksLikeUnknownField(res) {
+  const text = JSON.stringify(res?.error ?? res?.result ?? res?.detail ?? "").toLowerCase();
+  return text.includes("extra") || text.includes("mode") || text.includes("unexpected");
+}
+
+function wrapContext(body) {
+  return [
+    "<openviking-context>",
+    "Relevant memory from OpenViking. Use the recall/read MCP tools to expand URIs.",
+    body,
+    "</openviking-context>",
+  ].join("\n");
+}
+
+/**
+ * Server-assembled context: the context face when the deployment has it, else
+ * the deprecated /recall preset. Returns the injection block, "" when there was
+ * nothing relevant, or null when no server-side path was usable at all.
+ */
+export async function buildServerAssembledBlock(fetchJSON, cfg, query, options = {}) {
+  const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";
+  const log = options.log || (() => {});
+
+  const block = await recallViaContextFace(fetchJSON, cfg, query, { ...options, actorPeerId }, log);
+  if (block !== null) return block;
+  return recallViaEndpoint(fetchJSON, cfg, query, actorPeerId, log);
+}
+
+/**
+ * Raw server-assembled context, or null when the deployment has no context face.
+ * Returns `{ rendered, entries, digest, stats }` — callers that need the entries
+ * (their own compression, their own envelope) use this instead of the block
+ * builders below.
+ */
+export async function fetchAssembledContext(fetchJSON, cfg, query, options = {}) {
+  const actorPeerId = options.actorPeerId || "";
+  const log = options.log || (() => {});
+  if (await isContextFaceLegacy(options.legacyCachePath)) return null;
+
+  const body = buildContextSearchBody(cfg, options);
+  body.query = query;
+  const res = await fetchJSON("/api/v1/search/search", {
+    method: "POST",
+    body: JSON.stringify(body),
+  }, { actorPeerId, timeoutMs: contextRequestTimeoutMs(cfg, body) });
+
+  if (!res.ok) {
+    const status = res.status || 0;
+    if ((status === 400 || status === 422) && looksLikeUnknownField(res)) {
+      await markContextFaceLegacy(options.legacyCachePath);
+      log("recall_context_face_unsupported", { status });
+    } else {
+      log("recall_context_face_error", { status });
+    }
+    return null;
+  }
+
+  const result = res.result || {};
+  const stats = result.stats || {};
+  log("recall_context_assembled", {
+    entries: Array.isArray(result.entries) ? result.entries.length : 0,
+    usedTokens: stats.used_tokens || 0,
+    tiers: stats.tier_counts || {},
+    rewrite: stats.rewrite || "off",
+  });
+  return {
+    rendered: String(result.rendered || "").trim(),
+    entries: Array.isArray(result.entries) ? result.entries : [],
+    digest: String(result.digest || "").trim(),
+    stats,
+  };
+}
+
+/**
+ * Entry field compatibility: the context face returns `category`/`text`, while
+ * the deprecated /recall v1 shape used `type` plus `content`/`summary`.
+ */
+export function normalizeContextEntry(entry = {}) {
+  return {
+    uri: String(entry.uri || "").trim(),
+    category: String(entry.category || entry.type || "memory").trim() || "memory",
+    detail: String(entry.detail || entry.mode || "").trim(),
+    score: Number(entry.score) || 0,
+    text: String(
+      entry.text || entry.content || entry.summary || entry.abstract || entry.uri || "",
+    ).trim(),
+  };
+}
+
+async function recallViaContextFace(fetchJSON, cfg, query, options, log) {
+  const assembled = await fetchAssembledContext(fetchJSON, cfg, query, { ...options, log });
+  if (assembled === null) return null;
+
+  const { rendered, entries } = assembled;
+  let digest = assembled.digest;
+  const mode = String(cfg.recallRewrite || "off").toLowerCase();
+  if (String(assembled.stats?.rewrite || "").toLowerCase() === "no_relevant") {
+    log("recall_server_compression", { status: "empty" });
+    return "";
+  }
+  const wantsLocal = mode === "client" || (mode === "auto" && !digest);
+  if (wantsLocal && rendered && typeof options.runCompressor === "function") {
+    try {
+      const compression = await compressRecallContext({
+        query,
+        rendered,
+        entries,
+        cfg,
+        runCompressor: options.runCompressor,
+        cachePath: options.digestCachePath || stateFile("recall-digest.json"),
+        now: Date.now(),
+      });
+      log("recall_local_compression", { status: compression.status });
+      if (compression.status === "ok") digest = compression.context;
+      if (compression.status === "empty") return "";
+    } catch (err) {
+      log("recall_local_compression_failed", { error: String(err?.message || err) });
+    }
+  }
+
+  const injected = digest || rendered;
+  if (!injected) return "";
+  return wrapContext(injected);
+}
+
 async function recallViaEndpoint(fetchJSON, cfg, query, actorPeerId = "", log = () => {}) {
   const body = buildRecallEndpointBody(cfg);
   body.query = query;
@@ -242,12 +548,7 @@ async function recallViaEndpoint(fetchJSON, cfg, query, actorPeerId = "", log =
   }
   const rendered = String(res.result?.rendered || "").trim();
   if (!rendered) return "";
-  return [
-    "<openviking-context>",
-    "Relevant memory from OpenViking. Use the recall/read MCP tools to expand URIs.",
-    rendered,
-    "</openviking-context>",
-  ].join("\n");
+  return wrapContext(rendered);
 }
 
 export async function postRecall(fetchJSON, body, opts = {}) {
@@ -277,10 +578,16 @@ export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
   const trimmed = String(query || "").trim();
   if (!trimmed) return null;
 
-  const endpointBlock = await recallViaEndpoint(fetchJSON, cfg, trimmed, actorPeerId, log);
-  if (endpointBlock !== null) return endpointBlock || null;
+  // Assembly happens server-side when the deployment offers the context face;
+  // older servers fall through to /recall, then to raw find.
+  const serverBlock = await buildServerAssembledBlock(fetchJSON, cfg, trimmed, {
+    ...options,
+    actorPeerId,
+    log,
+  });
+  if (serverBlock !== null) return serverBlock || null;
 
-  const recallLimit = Math.max(1, Number(cfg.recallLimit || 6));
+  const recallLimit = Math.max(1, Number(cfg.recallLimit || DEFAULT_CONTEXT_LIMIT));
   const perSourceLimit = Math.max(recallLimit * 2, 8);
   const raw = await searchAllSources(fetchJSON, trimmed, perSourceLimit, actorPeerId, log);
   if (raw.length === 0) return null;

package/lib/shared/retryable.mjs

@@ -0,0 +1,9 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+export function isRetryableFailure(result) {
+  if (!result || result.ok) return false;
+  const status = Number(result.status || 0);
+  if (!status || status === 408 || status === 429 || status >= 500) {
+    return true;
+  }
+  return status === 409 && result.error?.details?.retryable === true;
+}

package/lib/utils.mjs

@@ -213,6 +213,7 @@ function makeAuthHeaders(config, headers = {}, actorPeerId = "") {
   if (config.user) result["X-OpenViking-User"] = config.user
   const peerId = String(actorPeerId || "").trim()
   if (peerId) result["X-OpenViking-Actor-Peer"] = peerId
+  if (config.userAgent) result["User-Agent"] = config.userAgent
   return result
 }
 

package/lib/viking-uri-guard.mjs

@@ -4,7 +4,7 @@ import { buildGuardMessage, findVikingUri, normalizeToolName } from "./shared/ur
 const FILESYSTEM_TOOL_HINTS = {
   read: {
     tool: "openviking_read",
-    example: (uri) => `openviking_read(uri="${uri}")`,
+    example: (uri) => `openviking_read(uris=["${uri}"])`,
   },
   glob: {
     tool: "openviking_glob",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openviking/opencode-plugin",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "author": "@openviking",
   "description": "Unified OpenCode plugin for OpenViking repository retrieval and long-term memory",
   "type": "module",

package/servers/mcp-proxy.mjs

@@ -46,6 +46,7 @@ function readProxyConfig() {
     account: cfg.account || "",
     user: cfg.user || "",
     peerId: effectivePeer.peerId,
+    userAgent: cfg.userAgent || "",
     timeoutMs: Math.max(1000, Number(cfg.timeoutMs) || DEFAULT_TIMEOUT_MS),
     debug: cfg.debug === true,
     debugLogPath: cfg.debugLogPath,

package/servers/mcp-proxy.test.mjs

@@ -56,6 +56,7 @@ function makeProxy(url) {
       account: "acct",
       user: "user",
       peerId: "peer",
+      userAgent: "openviking-memory-opencode/9.9.9",
       timeoutMs: 5000,
       debug: false,
       debugLogPath: "",
@@ -81,6 +82,7 @@ test("OpenCode MCP proxy forwards initialize with auth and identity headers", as
     assert.equal(entry.headers["x-openviking-account"], "acct")
     assert.equal(entry.headers["x-openviking-user"], "user")
     assert.equal(entry.headers["x-openviking-actor-peer"], "peer")
+    assert.equal(entry.headers["user-agent"], "openviking-memory-opencode/9.9.9")
     res.writeHead(200, {
       "content-type": "text/event-stream",
       "mcp-session-id": "sid-oc",