@openviking/opencode-plugin 0.2.3 → 2026.9.9-1

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;
@@ -8,9 +14,20 @@ const STOPWORDS = new Set([
 ]);
 const USER_RESERVED_DIRS = new Set(["memories", "skills"]);
 const SOURCES = [
-  { type: "memory", uri: "viking://user/memories", bucket: "memories" },
-  { type: "skill", uri: "viking://user/skills", bucket: "skills" },
+  { type: "memory", uri: "viking://~/memories", bucket: "memories" },
+  { type: "skill", uri: "viking://~/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,105 @@ 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";
+  const configured = Number(cfg.recallContextTimeoutMs);
+  if (Number.isFinite(configured) && configured > 0) return Math.max(1000, Math.floor(configured));
+  if (!wantsRewrite && !wantsExpansion) return undefined;
+  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));
@@ -124,6 +271,11 @@ async function resolveUserSpace(fetchJSON, actorPeerId = "") {
 
 async function resolveTargetUri(fetchJSON, targetUri, actorPeerId = "") {
   const trimmed = targetUri.trim().replace(/\/+$/, "");
+  // viking://~ is the home alias: the server expands it to the caller's own user
+  // space, so it needs no client-side rewrite.
+  if (trimmed === "viking://~" || trimmed.startsWith("viking://~/")) return trimmed;
+  // Legacy compat: uid-less viking://user/<reserved> URIs may still sit in plugin
+  // configs. Newer servers reject them, so rewrite to an explicit-uid URI here.
   const m = trimmed.match(/^viking:\/\/user(?:\/(.*))?$/);
   if (!m) return trimmed;
   const rawRest = (m[1] ?? "").trim();
@@ -232,6 +384,189 @@ 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 });
+}
+
+/**
+ * A `peer_scope` the server rejects is remembered the same way, but unlike the
+ * context face this one is not a silent capability probe: dropping the field
+ * widens recall from the caller's own peer to the whole user root, so doctor
+ * reads this file back and warns.
+ */
+export function peerScopeMemoPath() {
+  return stateFile("peer-scope.json");
+}
+
+export async function readPeerScopeDowngrade(path = peerScopeMemoPath(), now = Date.now()) {
+  const cached = await readJsonFile(path);
+  if (!cached?.legacyUntil || Number(cached.legacyUntil) <= now) return null;
+  return cached;
+}
+
+export async function markPeerScopeDowngrade(scope, status, path = peerScopeMemoPath(), now = Date.now()) {
+  await writeJsonFile(path, {
+    legacyUntil: now + LEGACY_CACHE_TTL_MS,
+    scope: String(scope || ""),
+    status: Number(status) || 0,
+    at: now,
+  });
+}
+
+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 search/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,18 +577,21 @@ 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 = {}) {
   const actorPeerId = opts.actorPeerId || "";
   const log = opts.log || (() => {});
+  const memoPath = opts.peerScopeMemoPath;
   const request = { ...body };
+
+  // A remembered downgrade is still a downgrade: recall runs wider than the
+  // caller asked for, so the memo doubles as the doctor's evidence.
+  if (request.peer_scope && await readPeerScopeDowngrade(memoPath)) {
+    delete request.peer_scope;
+  }
+
   const res = await fetchJSON("/api/v1/search/recall", {
     method: "POST",
     body: JSON.stringify(request),
@@ -261,9 +599,17 @@ export async function postRecall(fetchJSON, body, opts = {}) {
   if (!request.peer_scope || (res.status !== 400 && res.status !== 422)) {
     return res;
   }
+  // Only an unknown-field rejection means "this server predates peer_scope".
+  // Retrying every other 400/422 without it silently widens the search from
+  // the caller's own peer to the whole user root.
+  if (!looksLikeUnknownField(res)) {
+    log("recall_peer_scope_error", { status: res.status || 0 });
+    return res;
+  }
 
   const downgraded = { ...request };
   delete downgraded.peer_scope;
+  await markPeerScopeDowngrade(String(request.peer_scope), res.status || 0, memoPath);
   log("recall_peer_scope_downgrade", { status: res.status || 0 });
   return fetchJSON("/api/v1/search/recall", {
     method: "POST",
@@ -271,16 +617,46 @@ export async function postRecall(fetchJSON, body, opts = {}) {
   }, { actorPeerId });
 }
 
+/**
+ * Recall, plus whatever is still filed under the peer this workspace used
+ * before the identity rule changed.
+ *
+ * Under the default `peer_scope: "all"` this costs nothing: the server's own
+ * sweep of `{user_root}/peers` already reaches the old peer's memories. Under
+ * `"actor"` that sweep is off by definition, so the old peer is asked for
+ * separately — as itself, which is both cheaper and wider than a bare
+ * cross-peer read (that would need the user id, and reaches memories only).
+ */
 export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
+  const primary = await recallForPeer(fetchJSON, cfg, query, options);
+
+  const legacyPeerId = String(options.legacyPeerId || "").trim();
+  const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";
+  if (cfg.recallPeerScope !== "actor" || !legacyPeerId || legacyPeerId === actorPeerId) return primary;
+
+  const log = options.log || (() => {});
+  const legacy = await recallForPeer(fetchJSON, cfg, query, { ...options, actorPeerId: legacyPeerId });
+  if (!legacy) return primary;
+  log("recall_legacy_peer_hit", { legacyPeerId });
+  return primary ? `${primary}\n${legacy}` : legacy;
+}
+
+async function recallForPeer(fetchJSON, cfg, query, options = {}) {
   const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";
   const log = options.log || (() => {});
   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/shared/setup-wizard.mjs

@@ -39,14 +39,17 @@ export async function runSetupWizard({
   output = process.stdout,
   env = process.env,
 } = {}) {
-  const { cliPath } = loadCredentialFiles(env);
-  const current = readJsonSafe(cliPath);
+  // cliPath is empty until the file exists; first-run writes go to the candidate
+  // path (OPENVIKING_CLI_CONFIG_FILE, else ~/.openviking/ovcli.conf).
+  const { cliPath, cliPathCandidate } = loadCredentialFiles(env);
+  const targetPath = cliPath || cliPathCandidate;
+  const current = readJsonSafe(targetPath);
   const rl = createInterface({ input, output });
   const say = (line = "") => output.write(`${line}\n`);
 
   try {
     say("OpenViking memory plugin setup");
-    say(`Config file: ${cliPath}`);
+    say(`Config file: ${targetPath}`);
     say("");
     say("Current values:");
     say(`  url:     ${current.url || "(not set)"}`);
@@ -89,22 +92,22 @@ export async function runSetupWizard({
     const confirm = (await rl.question("Write config? [Y/n] ")).trim().toLowerCase();
     if (confirm === "n" || confirm === "no") {
       say("Aborted; nothing written.");
-      return { written: false, path: cliPath };
+      return { written: false, path: targetPath };
     }
 
-    mkdirSync(dirname(cliPath), { recursive: true });
-    if (existsSync(cliPath)) {
-      copyFileSync(cliPath, `${cliPath}.bak.${Date.now()}`);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    if (existsSync(targetPath)) {
+      copyFileSync(targetPath, `${targetPath}.bak.${Date.now()}`);
     }
-    writeFileSync(cliPath, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    writeFileSync(targetPath, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
     try {
-      chmodSync(cliPath, 0o600);
+      chmodSync(targetPath, 0o600);
     } catch {
       /* best effort on platforms without chmod semantics */
     }
-    say(`Written: ${cliPath}`);
+    say(`Written: ${targetPath}`);
     say("The stdio MCP proxy and hooks pick this up on the next harness start.");
-    return { written: true, path: cliPath };
+    return { written: true, path: targetPath };
   } finally {
     rl.close();
   }

package/lib/shared/uri-guard.mjs

@@ -14,30 +14,52 @@ export function normalizeToolName(value) {
   return String(value || "").trim().toLowerCase();
 }
 
-export function findVikingUri(args = {}, keys = DEFAULT_URI_KEYS) {
+// Arguments that carry file CONTENT rather than a location. The sweep below
+// looks past the known path keys so an unusual one (`paths`, a nested target)
+// is still caught, but text a tool is asked to WRITE is not a path: a local
+// `write` whose body merely mentions viking://user/default/ was denied, and no
+// file was created. Skipped by name at any depth.
+const DEFAULT_CONTENT_KEYS = [
+  "content",
+  "contents",
+  "text",
+  "body",
+  "old_string",
+  "oldString",
+  "new_string",
+  "newString",
+  "old_str",
+  "new_str",
+  "file_text",
+  "insert_line",
+  "replacement",
+];
+
+export function findVikingUri(args = {}, keys = DEFAULT_URI_KEYS, contentKeys = DEFAULT_CONTENT_KEYS) {
   if (!args || typeof args !== "object") return null;
   for (const key of keys) {
     const uri = findVikingUriInValue(args[key]);
     if (uri) return uri;
   }
-  return findVikingUriInValue(args);
+  return findVikingUriInValue(args, new Set(contentKeys));
 }
 
-export function findVikingUriInValue(value) {
+export function findVikingUriInValue(value, skipKeys) {
   if (typeof value === "string") {
     const match = value.match(/\bviking:\/\/[^\s"'`<>)]*/i);
     return match?.[0] || null;
   }
   if (Array.isArray(value)) {
     for (const item of value) {
-      const uri = findVikingUriInValue(item);
+      const uri = findVikingUriInValue(item, skipKeys);
       if (uri) return uri;
     }
     return null;
   }
   if (value && typeof value === "object") {
-    for (const item of Object.values(value)) {
-      const uri = findVikingUriInValue(item);
+    for (const [key, item] of Object.entries(value)) {
+      if (skipKeys?.has(key)) continue;
+      const uri = findVikingUriInValue(item, skipKeys);
       if (uri) return uri;
     }
   }