@ghilteras/opencode-agent-memory 2.1.0 → 2.2.0

package/README.md

@@ -32,7 +32,7 @@ Add to your OpenCode config (`~/.config/opencode/opencode.json`):
 
 ```json
 {
-  "plugins": ["@ghilteras/opencode-agent-memory@2.1.0"]
+  "plugins": ["@ghilteras/opencode-agent-memory@2.2.0"]
 }
 ```
 
@@ -93,6 +93,24 @@ Text search runs one MiniSearch BM25+ pass over title and body. Query terms are
 
 Optional LLM reranking fuses the BM25 order with a listwise ranking of the BM25 top-50 candidates using reciprocal rank fusion (RRF, k=10). In a 30-task pilot, Hit@5 increased from 0.500 to 0.700, Hit@10 from 0.667 to 0.767, and MRR@10 from 0.321 to 0.528. A shuffled-candidate control also achieved Hit@5 of 0.700, and the direction of improvement survived pessimistic relevance judgments. The result was not statistically significant (p=0.070, n=30); this is preliminary evidence, not a guaranteed improvement. The pilot used one cloud call per query, costing approximately US$0.001 and taking about 2–3 seconds. Results, cost, and latency depend on the model, provider, and journal; these pilot measurements are not a benchmark of every supported configuration or a production service guarantee. This pilot was not an independent evaluation and does not establish a generalizable quality improvement.
 
+#### Provider quirks
+
+Some gateways require extra request headers. Reasoning models must be told not to reason so they return the requested labels within the completion budget. For the OpenCode inference gateway, use a stable UUID generated once:
+
+```json
+{
+  "enabled": true,
+  "baseURL": "https://opencode.ai/inference/go/openai/v1",
+  "model": "deepseek-v4.1-flash",
+  "request": {
+    "headers": { "x-opencode-session": "<a stable UUID you generate once>" },
+    "body": { "reasoning_effort": "none" }
+  }
+}
+```
+
+Without `reasoning_effort: "none"`, a reasoning model spends the entire completion budget and returns empty content; the plugin then falls back to BM25.
+
 Reranking is off by default. Without explicit enablement, journal search remains local and credential-free, with no reranking network requests. When enabled, each eligible search sends your query and the titles and excerpts of up to 50 filtered journal candidates to the HTTPS endpoint you configure. Titles are limited to 200 Unicode code points and excerpts to 600; sensitive information appearing in those fields is not automatically redacted. The plugin does not send journal paths, entry IDs, metadata, session history, or unrelated entries, and does not silently reuse OpenCode credentials. Your configured endpoint receives the dedicated API credential and processes journal content under its own policies. Reranking makes at most one request per search; failures return BM25 without retry. Requests may remain billable after timeout or cancellation.
 
 Configure reranking in `~/.config/opencode/agent-memory-rerank.json`, alongside `agent-memory.json`:
@@ -106,7 +124,8 @@ Set `AGENT_MEMORY_RERANK_API_KEY` in the environment of the process that runs Op
 Constraints and pagination:
 
 - HTTPS only; plaintext `http` is rejected, including for localhost.
-- One request per search, with a 5-second deadline, request and response limits of 65,536 bytes each, 256 completion tokens, and no retries.
+- One request per search, with a 5-second deadline, request and response limits of 65,536 bytes each, 512 completion tokens by default (overridable via `request.body`), and no retries.
+- `request.body` may add or override any scalar field except `model`, `messages`, and `stream` (up to 10 fields; for example `reasoning_effort`, `temperature`, or `max_tokens`). The plugin always sends `max_tokens` (512 by default), so a provider that requires `max_completion_tokens` instead of `max_tokens` cannot be used.
 - Only the first 50 candidates can move; `total` is unchanged. A page is reranked only when it fits entirely inside that top-50 window; other pages keep plain BM25 order.
 - Searches without non-whitespace `text` are never reranked.
 - Enabled ordering is **not reproducible** across calls, so offset pagination is a slice of each call's ranking, not a stable snapshot.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghilteras/opencode-agent-memory",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Journal-only memory plugin for OpenCode: tagged, searchable, append-only journal with semantic search.",
   "author": "Angelo Pantano <ghilteras@protonmail.com>",
   "license": "MIT",

package/src/rerank-config.ts

@@ -3,16 +3,55 @@ import * as path from "node:path";
 
 import { loadConfig } from "./journal";
 
-export type RerankConfig = { enabled: true; baseURL: string; model: string } | { enabled: false };
+export type RerankRequestConfig = { headers?: Record<string, string>; body?: Record<string, string | number | boolean> };
+export type RerankConfig = { enabled: true; baseURL: string; model: string; request?: RerankRequestConfig } | { enabled: false };
 
 export type RerankConfigLoad =
   | { status: "disabled" }
   | { status: "invalid"; reason: string }
-  | { status: "enabled"; config: { baseURL: string; model: string } };
+  | { status: "enabled"; config: { baseURL: string; model: string; request?: RerankRequestConfig } };
+
+const forbiddenHeaders = new Set(["authorization", "content-type", "host", "content-length", "content-encoding", "transfer-encoding"]);
+const forbiddenBodyKeys = new Set(["model", "messages", "stream"]);
+
+function validateRequest(value: unknown): { valid: true; request?: RerankRequestConfig } | { valid: false } {
+  if (value === undefined) return { valid: true };
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return { valid: false };
+  const request = value as Record<string, unknown>;
+  if (Object.keys(request).some((key) => key !== "headers" && key !== "body")) return { valid: false };
+  const result: RerankRequestConfig = {};
+  if (request.headers !== undefined) {
+    if (request.headers === null || typeof request.headers !== "object" || Array.isArray(request.headers)) return { valid: false };
+    const headers = request.headers as Record<string, unknown>;
+    const entries = Object.entries(headers);
+    if (entries.length > 10) return { valid: false };
+    const output: Record<string, string> = {};
+    for (const [key, item] of entries) {
+      if (!/^[A-Za-z0-9-]+$/.test(key) || forbiddenHeaders.has(key.toLowerCase()) || typeof item !== "string" ||
+        item.length === 0 || item.length > 1024 || /[\r\n\0]/.test(item)) return { valid: false };
+      output[key] = item;
+    }
+    result.headers = output;
+  }
+  if (request.body !== undefined) {
+    if (request.body === null || typeof request.body !== "object" || Array.isArray(request.body)) return { valid: false };
+    const body = request.body as Record<string, unknown>;
+    const entries = Object.entries(body);
+    if (entries.length > 10) return { valid: false };
+    const output: Record<string, string | number | boolean> = Object.create(null) as Record<string, string | number | boolean>;
+    for (const [key, item] of entries) {
+      if (!/^[A-Za-z0-9_.-]+$/.test(key) || forbiddenBodyKeys.has(key) ||
+        !(typeof item === "string" || typeof item === "boolean" || (typeof item === "number" && Number.isFinite(item))) ||
+        (typeof item === "string" && item.length > 1024)) return { valid: false };
+      output[key] = item;
+    }
+    result.body = output;
+  }
+  return { valid: true, ...(Object.keys(result).length ? { request: result } : {}) };
+}
 
 function duplicateTopLevelKey(raw: string): string | undefined {
-  const keys = new Set<string>();
-  let objectDepth = 0;
+  const objects: { path: string[]; keys: Set<string>; pendingKey?: string }[] = [];
   let arrayDepth = 0;
   for (let i = 0; i < raw.length;) {
     const char = raw[i]!;
@@ -25,19 +64,26 @@ function duplicateTopLevelKey(raw: string): string | undefined {
         else if (current === "\\") escaped = true;
         else if (current === '"') break;
       }
-      if (objectDepth === 1 && arrayDepth === 0) {
-        let next = i;
-        while (/\s/.test(raw[next] ?? "")) next++;
-        if (raw[next] === ":") {
-          const key = JSON.parse(raw.slice(start, i)) as string;
-          if (keys.has(key)) return key;
-          keys.add(key);
+      const current = objects.at(-1);
+      let next = i;
+      while (/\s/.test(raw[next] ?? "")) next++;
+      if (current && raw[next] === ":") {
+        const key = JSON.parse(raw.slice(start, i)) as string;
+        if (arrayDepth === 0 && (current.path.length === 0 ||
+          (current.path.length === 2 && current.path[0] === "request" &&
+            (current.path[1] === "headers" || current.path[1] === "body")))) {
+          if (current.keys.has(key)) return key;
+          current.keys.add(key);
         }
+        current.pendingKey = key;
       }
       continue;
     }
-    if (char === "{") objectDepth++;
-    else if (char === "}") objectDepth--;
+    if (char === "{") {
+      const parent = objects.at(-1);
+      objects.push({ path: parent ? [...parent.path, parent.pendingKey ?? ""] : [], keys: new Set() });
+      if (parent) parent.pendingKey = undefined;
+    } else if (char === "}") objects.pop();
     else if (char === "[") arrayDepth++;
     else if (char === "]") arrayDepth--;
     i++;
@@ -71,7 +117,7 @@ export async function loadRerankConfig(configDir?: string): Promise<RerankConfig
   if (duplicate !== undefined) return { status: "invalid", reason: `duplicate config key: ${duplicate}` };
 
   const config = value as Record<string, unknown>;
-  if (Object.keys(config).some((key) => !["enabled", "baseURL", "model"].includes(key))) {
+  if (Object.keys(config).some((key) => !["enabled", "baseURL", "model", "request"].includes(key))) {
     return { status: "invalid", reason: "unknown config field" };
   }
   if (config.enabled !== undefined && typeof config.enabled !== "boolean") {
@@ -83,6 +129,8 @@ export async function loadRerankConfig(configDir?: string): Promise<RerankConfig
   if (config.model !== undefined && typeof config.model !== "string") {
     return { status: "invalid", reason: "model must be a string" };
   }
+  const request = validateRequest(config.request);
+  if (!request.valid) return { status: "invalid", reason: "request must contain valid headers and body" };
   if (config.enabled !== true) return { status: "disabled" };
   if (typeof config.baseURL !== "string" || typeof config.model !== "string" || config.model.trim().length === 0) {
     return { status: "invalid", reason: "enabled config requires baseURL and non-empty model" };
@@ -99,5 +147,5 @@ export async function loadRerankConfig(configDir?: string): Promise<RerankConfig
   }
   const baseURL = config.baseURL.replace(/\/+$/, "");
   if (!baseURL) return { status: "invalid", reason: "baseURL is invalid" };
-  return { status: "enabled", config: { baseURL, model: config.model } };
+  return { status: "enabled", config: { baseURL, model: config.model, ...(request.request ? { request: request.request } : {}) } };
 }

package/src/rerank-transport.ts

@@ -51,6 +51,7 @@ export async function requestRerank(args: {
   signal?: AbortSignal;
   fetchImpl?: typeof fetch;
   timeoutMs?: number;
+  headers?: Record<string, string>;
 }): Promise<RerankOutcome> {
   if (typeof args.apiKey !== "string" || args.apiKey.length === 0) return { ok: false, reason: "missing_credential" };
   try {
@@ -84,7 +85,7 @@ export async function requestRerank(args: {
     try {
       response = await raceAbort(fetchImpl(`${args.baseURL}/chat/completions`, {
         method: "POST",
-        headers: { Authorization: `Bearer ${args.apiKey}`, "Content-Type": "application/json" },
+        headers: { Authorization: `Bearer ${args.apiKey}`, "Content-Type": "application/json", ...args.headers },
         body: serialized,
         redirect: "error",
         signal,

package/src/rerank.ts

@@ -30,24 +30,35 @@ export function buildRequestBody(args: {
   query: string;
   candidates: RerankCandidate[];
   count: number;
+  extraBody?: Record<string, string | number | boolean>;
 }): {
+  [key: string]: unknown;
   model: string;
   messages: Array<{ role: "system" | "user"; content: string }>;
   temperature: 0;
-  max_completion_tokens: 256;
+  max_tokens: 512;
   stream: false;
 } {
   const count = Math.min(10, args.candidates.length);
-  return {
+  const base: {
+    model: string;
+    messages: Array<{ role: "system" | "user"; content: string }>;
+    temperature: 0;
+    max_tokens: 512;
+    stream: false;
+  } = {
     model: args.model,
     messages: [
       { role: "system", content: RERANK_SYSTEM_PROMPT },
       { role: "user", content: JSON.stringify({ query: args.query, count, candidates: args.candidates }) },
     ],
     temperature: 0,
-    max_completion_tokens: 256,
+    max_tokens: 512,
     stream: false,
   };
+  const extraBody = Object.fromEntries(Object.entries(args.extraBody ?? {}).filter(([key]) =>
+    key !== "model" && key !== "messages" && key !== "stream"));
+  return { ...base, ...extraBody, model: base.model, messages: base.messages, stream: base.stream };
 }
 
 export function parseLabels(content: unknown, candidates: RerankCandidate[], count: number): string[] | null {

package/src/tools.ts

@@ -147,10 +147,11 @@ export function JournalSearch(store: JournalStore, deps: RerankDependencies = {}
               const outcome = await request({
                 baseURL: config.config.baseURL,
                 apiKey: getEnv("AGENT_MEMORY_RERANK_API_KEY") ?? "",
-                body: buildRequestBody({ model: config.config.model, query: query.text, candidates, count }),
+                body: buildRequestBody({ model: config.config.model, query: query.text, candidates, count, extraBody: config.config.request?.body }),
                 candidates,
                 count,
                 signal: toolCtx.signal,
+                headers: config.config.request?.headers,
               });
               if (!outcome.ok) {
                 ranking = { method: "bm25", status: "fallback", reason: outcome.reason };