@openviking/opencode-plugin 0.2.2 → 0.2.4

package/INSTALL-ZH.md

@@ -110,6 +110,9 @@ export { OpenVikingPlugin, default } from "./openviking/index.mjs"
 }
 ```
 
+`autoRecall.limit` 是遗留的配额缩放输入，不是最终结果上限。显式设置为
+1 到 5 时，有效总配额仍为 6，因为六个 coding 分类会各保留一个检索槽位。
+
 推荐通过环境变量提供 API Key，而不是写入配置文件：
 
 ```bash
@@ -137,7 +140,6 @@ user/admin API key 的 API_KEY mode 时应留空。
 - `openviking_read`、`openviking_list`、`openviking_grep`、`openviking_glob`
 - `openviking_remember`、`openviking_add_resource`、`openviking_forget`、`openviking_health`
 - `openviking_list_watches`、`openviking_cancel_watch`
-- `openviking_code_search`、`openviking_code_outline`、`openviking_code_expand`
 
 如果行为异常，先查看运行时文件：
 
@@ -167,7 +169,6 @@ curl http://localhost:1933/health
 - `openviking_add_resource`：添加 URL、本地文件、sitemap 或 feed
 - `openviking_forget`：在用户明确确认后删除 `viking://` URI
 - `openviking_list_watches` / `openviking_cancel_watch`：查看或取消资源 watch
-- `openviking_code_search`、`openviking_code_outline`、`openviking_code_expand`：查看已索引代码符号
 - `openviking_health`：检查 OpenViking server 健康状态
 
 使用建议：

package/INSTALL.md

@@ -110,6 +110,10 @@ Example configuration:
 }
 ```
 
+`autoRecall.limit` is a legacy quota-scaling input, not a final result cap.
+Explicit values from 1 through 5 produce an effective total quota of 6 because
+each coding category keeps one retrieval slot.
+
 It is recommended to provide the API key through an environment variable instead of writing it into the configuration file:
 
 ```bash
@@ -132,7 +136,6 @@ In a new OpenCode session, ask the agent to browse OpenViking memory or search f
 - `openviking_read`, `openviking_list`, `openviking_grep`, `openviking_glob`
 - `openviking_remember`, `openviking_add_resource`, `openviking_forget`, `openviking_health`
 - `openviking_list_watches`, `openviking_cancel_watch`
-- `openviking_code_search`, `openviking_code_outline`, `openviking_code_expand`
 
 If anything looks wrong, check the runtime files:
 
@@ -162,7 +165,6 @@ The plugin registers OpenViking's stdio MCP proxy through OpenCode config. The s
 - `openviking_add_resource`: add a URL, local file, sitemap, or feed.
 - `openviking_forget`: delete a `viking://` URI after explicit user confirmation.
 - `openviking_list_watches` / `openviking_cancel_watch`: inspect or cancel resource watches.
-- `openviking_code_search`, `openviking_code_outline`, `openviking_code_expand`: inspect indexed code symbols.
 - `openviking_health`: check OpenViking server health.
 
 Usage guidance:

package/README.md

@@ -132,7 +132,12 @@ Create `~/.config/opencode/openviking-config.json`:
 }
 ```
 
-API keys are resolved from environment variables or `~/.openviking/ovcli.conf` and sent as `Authorization: Bearer ...` by both hooks and the MCP proxy. `account` and `user` are trusted-mode identity
+`autoRecall.limit` is a legacy quota-scaling input, not a final result cap.
+Explicit values from 1 through 5 produce an effective total quota of 6 because
+each coding category keeps one retrieval slot. Use Context `quotas` directly
+when exact category ceilings are required.
+
+API keys are resolved from environment variables or `~/.openviking/ovcli.conf` and sent as `Authorization: Bearer ...` by both hooks and the MCP proxy. Recall goes through the server-side context face (`POST /api/v1/search/search` with `mode="context"`), falling back to the deprecated `/api/v1/search/recall` on older deployments. `account` and `user` are trusted-mode identity
 headers sent as `X-OpenViking-Account` and `X-OpenViking-User`; leave them empty
 when using API-key mode with user/admin API keys.
 By default the plugin derives a peer from the project directory using Claude's
@@ -177,7 +182,6 @@ OpenCode sees the OpenViking MCP server as `openviking`, so tool names are names
 - `openviking_add_resource`: add a URL, local file, sitemap, or feed.
 - `openviking_forget`: delete a `viking://` URI after explicit user confirmation.
 - `openviking_list_watches` / `openviking_cancel_watch`: inspect or cancel resource watches.
-- `openviking_code_search`, `openviking_code_outline`, `openviking_code_expand`: inspect indexed code symbols.
 - `openviking_health`: check OpenViking server health.
 
 The proxy forwards the server's real `tools/list` response; the plugin does not maintain a separate native tool list.

package/index.mjs

@@ -24,7 +24,7 @@ export async function OpenVikingPlugin({ client, directory }) {
 
   const repoContext = createRepoContext({ config })
   const sessionManager = createMemorySessionManager({ config, pluginRoot: dataDir })
-  const recall = createMemoryRecall({ config })
+  const recall = createMemoryRecall({ config, sessionManager })
   const sessionInject = createSessionInject({ config, sessionManager })
   const vikingUriGuard = createVikingUriGuard()
 

package/lib/config.mjs

@@ -1,9 +1,14 @@
 import fs from "fs"
 import path from "path"
 import { homedir } from "os"
-import { resolveOpenVikingCredentials } from "./shared/credentials.mjs"
+import { buildUserAgent, readManifestVersion, resolveOpenVikingCredentials } from "./shared/credentials.mjs"
 import { resolveEffectivePeerId } from "./shared/workspace-peer.mjs"
 
+const USER_AGENT = buildUserAgent(
+  "opencode",
+  readManifestVersion(new URL("../package.json", import.meta.url)),
+)
+
 const DEFAULT_CONFIG = {
   endpoint: "http://127.0.0.1:1933",
   apiKey: "",
@@ -12,6 +17,9 @@ const DEFAULT_CONFIG = {
   peerId: "",
   workspacePeer: true,
   recallPeerScope: "all",
+  // Server-side query expansion costs a model call before retrieval starts, so
+  // it has to be switchable from the client that pays the latency.
+  recallQueryExpansion: "auto",
   enabled: true,
   timeoutMs: 30000,
   runtime: {
@@ -23,7 +31,7 @@ const DEFAULT_CONFIG = {
   },
   autoRecall: {
     enabled: true,
-    limit: 6,
+    limit: 10,
     scoreThreshold: 0.35,
     maxContentChars: 500,
     preferAbstract: true,
@@ -123,6 +131,8 @@ function applyBehaviorConfig(config, fileConfig = {}) {
   }
 
   const autoRecall = fileConfig.autoRecall ?? {}
+  config.recallLimitConfigured = autoRecall.limit !== undefined ||
+    fileConfig.recallLimit !== undefined
   config.autoRecall = {
     ...DEFAULT_CONFIG.autoRecall,
     ...autoRecall,
@@ -152,9 +162,11 @@ function applyBehaviorConfig(config, fileConfig = {}) {
     "debugLogPath",
     "workspacePeer",
     "recallPeerScope",
+    "recallQueryExpansion",
   ]) {
     if (fileConfig[key] !== undefined) config[key] = fileConfig[key]
   }
+  config.recallQueryExpansionConfigured = fileConfig.recallQueryExpansion !== undefined
 }
 
 function applyEnv(config) {
@@ -162,7 +174,10 @@ function applyEnv(config) {
   if (process.env.OPENVIKING_AUTO_RECALL !== undefined) {
     config.autoRecall.enabled = envBool("OPENVIKING_AUTO_RECALL") ?? config.autoRecall.enabled
   }
-  if (process.env.OPENVIKING_RECALL_LIMIT) config.autoRecall.limit = process.env.OPENVIKING_RECALL_LIMIT
+  if (process.env.OPENVIKING_RECALL_LIMIT) {
+    config.autoRecall.limit = process.env.OPENVIKING_RECALL_LIMIT
+    config.recallLimitConfigured = true
+  }
   if (process.env.OPENVIKING_SCORE_THRESHOLD) config.autoRecall.scoreThreshold = process.env.OPENVIKING_SCORE_THRESHOLD
   if (process.env.OPENVIKING_RECALL_MAX_CONTENT_CHARS) {
     config.autoRecall.maxContentChars = process.env.OPENVIKING_RECALL_MAX_CONTENT_CHARS
@@ -172,6 +187,10 @@ function applyEnv(config) {
     config.autoRecall.preferAbstract = envBool("OPENVIKING_RECALL_PREFER_ABSTRACT") ?? config.autoRecall.preferAbstract
   }
   if (process.env.OPENVIKING_RECALL_PEER_SCOPE) config.recallPeerScope = process.env.OPENVIKING_RECALL_PEER_SCOPE
+  if (process.env.OPENVIKING_RECALL_QUERY_EXPANSION) {
+    config.recallQueryExpansion = process.env.OPENVIKING_RECALL_QUERY_EXPANSION
+    config.recallQueryExpansionConfigured = true
+  }
   if (process.env.OPENVIKING_WORKSPACE_PEER !== undefined) {
     config.workspacePeer = envBool("OPENVIKING_WORKSPACE_PEER") ?? config.workspacePeer
   }
@@ -216,6 +235,7 @@ function normalizeConfig(config) {
   config.baseUrl = config.endpoint
   config.accountId = config.account
   config.userId = config.user
+  config.userAgent = USER_AGENT
   config.timeoutMs = normalizeNumber(config.timeoutMs, DEFAULT_CONFIG.timeoutMs, 1000, 300000)
   config.repoContext.cacheTtlMs = normalizeNumber(
     config.repoContext.cacheTtlMs,
@@ -223,17 +243,25 @@ function normalizeConfig(config) {
     1000,
     60 * 60 * 1000,
   )
-  config.autoRecall.limit = Math.max(1, Math.min(50, Math.round(Number(config.autoRecall.limit) || 6)))
+  config.autoRecall.limit = Math.max(1, Math.min(50, Math.round(Number(config.autoRecall.limit) || 10)))
   config.autoRecall.scoreThreshold = Math.max(0, Math.min(1, Number(config.autoRecall.scoreThreshold) || 0))
   config.autoRecall.maxContentChars = Math.max(100, Math.min(5000, Math.round(Number(config.autoRecall.maxContentChars) || 500)))
   config.autoRecall.tokenBudget = Math.max(200, Math.min(50000, Math.round(Number(config.autoRecall.tokenBudget) || 2000)))
   config.autoRecall.minQueryLength = Math.max(1, Math.min(64, Math.round(Number(config.autoRecall.minQueryLength) || 3)))
   config.captureMode = config.captureMode === "keyword" ? "keyword" : "semantic"
   config.recallPeerScope = config.recallPeerScope === "actor" ? "actor" : "all"
+  config.recallQueryExpansion = config.recallQueryExpansion === "off" ? "off" : "auto"
   config.captureMaxLength = Math.max(200, Math.min(100000, Math.round(Number(config.captureMaxLength) || 24000)))
   config.captureToolMaxChars = Math.max(200, Math.min(20000, Math.round(Number(config.captureToolMaxChars) || 2000)))
   config.commitTokenThreshold = Math.max(1000, Math.round(Number(config.commitTokenThreshold) || 20000))
-  config.commitKeepRecentCount = Math.max(0, Math.round(Number(config.commitKeepRecentCount) || 10))
+  const rawCommitKeepRecentCount = config.commitKeepRecentCount
+  const commitKeepRecentCount = rawCommitKeepRecentCount == null ||
+    (typeof rawCommitKeepRecentCount === "string" && rawCommitKeepRecentCount.trim() === "")
+    ? Number.NaN
+    : Number(rawCommitKeepRecentCount)
+  config.commitKeepRecentCount = Number.isFinite(commitKeepRecentCount)
+    ? Math.max(0, Math.round(commitKeepRecentCount))
+    : DEFAULT_CONFIG.commitKeepRecentCount
   config.profileTokenBudget = Math.max(500, Math.round(Number(config.profileTokenBudget) || 10000))
   config.resumeContextBudget = Math.max(1024, Math.round(Number(config.resumeContextBudget) || 32000))
   if (!Array.isArray(config.bypassSessionPatterns)) config.bypassSessionPatterns = []

package/lib/memory-recall.mjs

@@ -2,14 +2,15 @@ import { buildRecallBlock } from "./shared/recall-core.mjs"
 import { isBypassed } from "./shared/session-model.mjs"
 import { effectivePeerId, fetchJSON, log } from "./utils.mjs"
 
-export function createMemoryRecall({ config }) {
+export function createMemoryRecall({ config, sessionManager }) {
   async function injectRelevantMemories(input, output) {
     if (!config.autoRecall?.enabled) return
     const query = extractCurrentUserText(output.parts ?? [])
     if (!query) return
     if (query.length < config.minQueryLength) return
+    const sessionID = input.sessionID ?? output.message?.sessionID
     if (isBypassed(config, {
-      sessionId: input.sessionID ?? output.message?.sessionID,
+      sessionId: sessionID,
       cwd: input.directory ?? input.cwd,
     })) return
 
@@ -17,11 +18,18 @@ export function createMemoryRecall({ config }) {
     if (!health.ok) return
 
     const block = await buildRecallBlock(
-      (path, init = {}, options = {}) => fetchJSON(config, path, init, { ...options, timeoutMs: 5000 }),
+      // 5s is this hook's own budget for a bare retrieval; when the request
+      // also spends a server fuse the helper hands down a longer deadline, and
+      // overriding it here would abort a request the server was still inside.
+      (path, init = {}, options = {}) =>
+        fetchJSON(config, path, init, { ...options, timeoutMs: options.timeoutMs ?? 5000 }),
       config,
       query,
       {
         actorPeerId: effectivePeerId(config),
+        // The mapped OV session is what turns on server-side query expansion
+        // and the cross-turn dedup ledger.
+        sessionId: sessionID ? sessionManager.getMappedSessionId(sessionID) : "",
         log: (stage, data) => log("DEBUG", "recall", stage, data),
       },
     )
@@ -35,12 +43,13 @@ export function createMemoryRecall({ config }) {
   return { injectRelevantMemories }
 }
 
-function extractCurrentUserText(parts) {
+export function extractCurrentUserText(parts) {
   const texts = []
   for (const part of parts) {
     if (part.type !== "text" || typeof part.text !== "string") continue
+    if (part.synthetic || part.ignored) continue
     if (part.text.includes("<openviking-context")) return null
-    if (!part.synthetic && !part.ignored) texts.push(part.text)
+    texts.push(part.text)
   }
   const joined = texts.join(" ").trim()
   return joined || null

package/lib/memory-session.mjs

@@ -12,6 +12,12 @@ import {
   enqueue,
   replayPending,
 } from "./shared/pending-queue.mjs"
+import {
+  sendSessionMessages,
+} from "./shared/batch-send.mjs"
+import {
+  isRetryableFailure,
+} from "./shared/retryable.mjs"
 import {
   log,
   effectivePeerId,
@@ -26,7 +32,7 @@ export function createMemorySessionManager({ config, pluginRoot }) {
   let saveTimer = null
 
   async function init() {
-    await migrateLegacySessionMap()
+    if (config.autoCapture) await migrateLegacySessionMap()
     await loadState()
     const health = await fetchJSON(config, "/health", {}, { timeoutMs: 5000 })
     if (health.ok) {
@@ -137,9 +143,9 @@ export function createMemorySessionManager({ config, pluginRoot }) {
       await handleSessionCompacted(event)
     } else if (event.type === "session.idle") {
       await handleSessionIdle(event)
-    } else if (event.type === "message.updated") {
+    } else if (event.type === "message.updated" && config.autoCapture) {
       await handleMessageUpdated(event)
-    } else if (event.type === "message.part.updated") {
+    } else if (event.type === "message.part.updated" && config.autoCapture) {
       await handleMessagePartUpdated(event)
     }
   }
@@ -256,7 +262,7 @@ export function createMemorySessionManager({ config, pluginRoot }) {
     if (!state) return false
 
     const added = await flushPendingMessages(opencodeSessionId, state)
-    if (commit) {
+    if (commit && config.autoCapture) {
       await commitOvSession(state.ovSessionId, { force: true, reason })
     } else if (added > 0) {
       await maybeCommitByThreshold(state)
@@ -358,7 +364,8 @@ export function createMemorySessionManager({ config, pluginRoot }) {
   }
 
   async function flushPendingMessages(opencodeSessionId, state) {
-    let added = 0
+    if (!config.autoCapture) return 0
+    const toSend = []
     for (const [messageId, message] of state.messages.entries()) {
       if (message.captured) continue
       const body = buildCapturePayload(message)
@@ -366,40 +373,45 @@ export function createMemorySessionManager({ config, pluginRoot }) {
         message.captured = true
         continue
       }
-      const ok = await addMessageToSession(state.ovSessionId, body)
-      if (!ok) break
-      message.captured = true
-      added += 1
-    }
-    if (added > 0) {
-      state.lastActivityAt = Date.now()
-      debouncedSaveState()
+      toSend.push({ messageId, message, body })
     }
-    return added
-  }
+    if (toSend.length === 0) return 0
 
-  async function addMessageToSession(ovSessionId, body) {
+    let added = 0
     const health = await fetchJSON(config, "/health", {}, { timeoutMs: 5000 })
     if (!health.ok) {
-      await enqueue("addMessage", ovSessionId, body)
-      return true
+      for (const item of toSend) {
+        const queued = await enqueue("addMessage", state.ovSessionId, item.body)
+        if (!queued.ok) break
+        item.message.captured = true
+        added += 1
+      }
+    } else {
+      const res = await sendSessionMessages(
+        (endpoint, init = {}, options = {}) => fetchJSON(config, endpoint, init, { timeoutMs: 10000, ...options }),
+        state.ovSessionId,
+        toSend.map((item) => item.body),
+        { enqueueOnRetryable: true },
+      )
+      added = res.sent + res.queued
+      for (const item of toSend.slice(0, added)) {
+        item.message.captured = true
+      }
+      if (res.failed > 0 || res.enqueueFailed > 0) {
+        log("ERROR", "message", "Failed to add message to OpenViking session", {
+          openviking_session: state.ovSessionId,
+          status: res.lastError?.status,
+          error: res.lastError,
+          failed: res.failed,
+          enqueueFailed: res.enqueueFailed,
+        })
+      }
     }
-    const res = await fetchJSON(config, `/api/v1/sessions/${encodeURIComponent(ovSessionId)}/messages`, {
-      method: "POST",
-      body: JSON.stringify(body),
-    }, { timeoutMs: 10000 })
-    if (res.ok) return true
-    if (isRetryableFailure(res)) {
-      const queued = await enqueue("addMessage", ovSessionId, body)
-      return Boolean(queued.ok)
+    if (added > 0) {
+      state.lastActivityAt = Date.now()
+      debouncedSaveState()
     }
-    log("ERROR", "message", "Failed to add message to OpenViking session", {
-      openviking_session: ovSessionId,
-      role: body.role,
-      status: res.status,
-      error: res.error,
-    })
-    return false
+    return added
   }
 
   async function maybeCommitByThreshold(state) {
@@ -466,9 +478,4 @@ export function createMemorySessionManager({ config, pluginRoot }) {
     }
   }
 
-  function isRetryableFailure(res) {
-    if (!res || res.ok) return false
-    const status = Number(res.status || 0)
-    return !status || status >= 500 || status === 408 || status === 429
-  }
 }

package/lib/runtime.mjs

@@ -6,6 +6,7 @@ export async function checkServiceHealth(config, timeoutMs = 3000) {
   try {
     const response = await fetch(`${normalizeEndpoint(config.endpoint)}/health`, {
       method: "GET",
+      headers: config.userAgent ? { "User-Agent": config.userAgent } : undefined,
       signal: controller.signal,
     })
     return response.ok

package/lib/shared/async-writer.mjs

@@ -0,0 +1,78 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+/**
+ * Async write-path helper for hook-based memory plugins.
+ *
+ * When `cfg.writePathAsync` is true and we're not already the worker, we:
+ *   1. Drain the parent's stdin (the hook payload)
+ *   2. Emit the harness-specific approve/no-op response on stdout immediately
+ *   3. Spawn a detached clone of ourselves with env OV_HOOK_WORKER=1
+ *   4. Feed the drained payload to the worker's stdin, unref, and exit
+ *
+ * The worker re-enters the same script, maybeDetach returns false (because
+ * OV_HOOK_WORKER=1), and the hook's normal synchronous code path reads its
+ * own stdin and runs the OV HTTP work with nobody waiting.
+ *
+ * Call this BEFORE the hook reads stdin itself. When it returns true, the
+ * caller must `return` out of main() immediately.
+ */
+
+import { spawn } from "node:child_process";
+
+const WORKER_ENV = "OV_HOOK_WORKER";
+
+export async function maybeDetach(cfg, { approve }) {
+  if (!cfg.writePathAsync) return false;
+  if (process.env[WORKER_ENV] === "1") return false;
+
+  // Drain parent stdin so we can forward to the worker.
+  let raw;
+  try {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    raw = Buffer.concat(chunks);
+  } catch {
+    // stdin read failed - let the synchronous path handle it.
+    return false;
+  }
+
+  let child;
+  try {
+    child = spawn(process.execPath, [process.argv[1]], {
+      detached: true,
+      stdio: ["pipe", "ignore", "ignore"],
+      env: { ...process.env, [WORKER_ENV]: "1" },
+    });
+  } catch {
+    // spawn failed - fall through to sync mode, but we've already drained
+    // stdin so hand the payload back via env var path below.
+    process.env.OPENVIKING_HOOK_STDIN_CACHE = raw.toString();
+    return false;
+  }
+
+  // Approve first, then write to the detached child. Ordering matters for
+  // harnesses that read stdout before waiting for the hook process to exit.
+  approve();
+
+  try {
+    child.stdin.write(raw);
+    child.stdin.end();
+  } catch { /* worker may have already exited; nothing useful to recover */ }
+  child.unref();
+  return true;
+}
+
+/**
+ * Fallback stdin reader used when the async path drained stdin but spawn
+ * failed; hooks should call this instead of reading stdin directly when
+ * possible so the sync fallback still works after a failed detach.
+ */
+export async function readHookStdin() {
+  if (process.env.OPENVIKING_HOOK_STDIN_CACHE) {
+    const cached = process.env.OPENVIKING_HOOK_STDIN_CACHE;
+    delete process.env.OPENVIKING_HOOK_STDIN_CACHE;
+    return cached;
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString();
+}

package/lib/shared/batch-send.mjs

@@ -0,0 +1,121 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+import { enqueue } from "./pending-queue.mjs";
+import { isRetryableFailure } from "./retryable.mjs";
+
+export const BATCH_LIMIT = 100;
+
+export function isRetryableSendFailure(res) {
+  return isRetryableFailure(res);
+}
+
+function makeResult() {
+  return {
+    sent: 0,
+    queued: 0,
+    enqueueFailed: 0,
+    failed: 0,
+    retryable: false,
+    usedBatch: true,
+    lastError: null,
+  };
+}
+
+async function enqueueRemainder(sessionId, payloads, startIndex, result, retryable, lastError) {
+  result.retryable = retryable;
+  result.lastError = lastError ?? null;
+
+  if (!retryable) {
+    result.failed += Math.max(0, payloads.length - startIndex);
+    return result;
+  }
+
+  const baseCreatedAt = Date.now();
+  for (let i = startIndex; i < payloads.length; i++) {
+    const queued = await enqueue("addMessage", sessionId, payloads[i], {
+      createdAt: baseCreatedAt + (i - startIndex),
+    });
+    if (!queued.ok) {
+      // Stop at the first enqueue failure so queued entries stay a contiguous
+      // prefix: consumers mark the first sent+queued payloads as captured, so
+      // skipping a payload here and queueing a later one would silently drop it.
+      result.enqueueFailed += payloads.length - i;
+      return result;
+    }
+    result.queued++;
+  }
+  return result;
+}
+
+async function sendSerial(fetchJSON, sessionId, payloads, startIndex, opts, result) {
+  result.usedBatch = false;
+  const encodedSid = encodeURIComponent(sessionId);
+  for (let i = startIndex; i < payloads.length; i++) {
+    const res = await fetchJSON(`/api/v1/sessions/${encodedSid}/messages`, {
+      method: "POST",
+      body: JSON.stringify(payloads[i]),
+    });
+    if (res?.ok) {
+      result.sent++;
+      await opts.onSent?.(1);
+      continue;
+    }
+
+    const retryable = isRetryableSendFailure(res);
+    if (opts.enqueueOnRetryable) {
+      return enqueueRemainder(sessionId, payloads, i, result, retryable, res?.error ?? res);
+    }
+    result.retryable = retryable;
+    result.lastError = res?.error ?? res ?? null;
+    result.failed += payloads.length - i;
+    return result;
+  }
+  return result;
+}
+
+/**
+ * Send add-message payloads in server-sized batches with serial fallback.
+ *
+ * @param {Function} fetchJSON - (path, init) => { ok, status, result?, error? }
+ * @param {string} sessionId - OpenViking session id
+ * @param {Array<object>} payloads - sanitized add-message request bodies
+ * @param {object} opts
+ * @param {boolean} opts.enqueueOnRetryable - enqueue unsent payloads after a retryable failure
+ * @param {Function} opts.onSent - called with the number of messages durably sent after each success
+ * @returns {Promise<{sent:number,queued:number,enqueueFailed:number,failed:number,retryable:boolean,usedBatch:boolean,lastError:any}>}
+ */
+export async function sendSessionMessages(fetchJSON, sessionId, payloads, opts = {}) {
+  const result = makeResult();
+  const messages = Array.isArray(payloads) ? payloads : [];
+  if (messages.length === 0) return result;
+
+  const encodedSid = encodeURIComponent(sessionId);
+  for (let start = 0; start < messages.length; start += BATCH_LIMIT) {
+    const chunk = messages.slice(start, start + BATCH_LIMIT);
+    const res = await fetchJSON(`/api/v1/sessions/${encodedSid}/messages/batch`, {
+      method: "POST",
+      body: JSON.stringify({ messages: chunk }),
+    });
+
+    if (res?.ok) {
+      result.sent += chunk.length;
+      await opts.onSent?.(chunk.length);
+      continue;
+    }
+
+    const status = Number(res?.status || 0);
+    if (status === 404 || status === 405) {
+      return sendSerial(fetchJSON, sessionId, messages, start, opts, result);
+    }
+
+    const retryable = isRetryableSendFailure(res);
+    if (opts.enqueueOnRetryable) {
+      return enqueueRemainder(sessionId, messages, start, result, retryable, res?.error ?? res);
+    }
+    result.retryable = retryable;
+    result.lastError = res?.error ?? res ?? null;
+    result.failed += messages.length - start;
+    return result;
+  }
+
+  return result;
+}

package/lib/shared/capture-utils.mjs

@@ -99,7 +99,6 @@ function toolName(block) {
     block?.toolName ||
     block?.function?.name ||
     block?.call?.name ||
-    block?.id ||
     "",
   );
 }
@@ -128,7 +127,6 @@ function toolPayload(block, kind) {
 
 function toolId(block) {
   return oneLine(
-    block?.id ||
     block?.call_id ||
     block?.callId ||
     block?.tool_call_id ||
@@ -137,6 +135,7 @@ function toolId(block) {
     block?.toolUseId ||
     block?.function_call_id ||
     block?.functionCallId ||
+    block?.id ||
     "",
   );
 }

package/lib/shared/credentials.mjs

@@ -30,6 +30,27 @@ function tryLoadJson(path) {
   }
 }
 
+/**
+ * Build the User-Agent every harness plugin sends on OpenViking-bound requests.
+ * Shape is `name/semver` so downstream stats layers can parse it as one token.
+ */
+export function buildUserAgent(harness, version) {
+  return `openviking-memory-${harness}/${str(version, "") || "0.0.0"}`;
+}
+
+/**
+ * Read a plugin manifest's `version` field. Accepts a path or a URL (so callers
+ * can resolve relative to import.meta.url). Returns "" when unreadable so the
+ * User-Agent falls back to 0.0.0 instead of throwing inside a short-lived hook.
+ */
+export function readManifestVersion(manifest) {
+  try {
+    return str(JSON.parse(readFileSync(manifest, "utf-8")).version, "");
+  } catch {
+    return "";
+  }
+}
+
 function looksLikeOvcli(obj) {
   if (!obj || typeof obj !== "object") return false;
   if (obj.server && typeof obj.server === "object") return false;