@openviking/dsh-memory-plugin 0.1.0

package/shared/setup-wizard.mjs

@@ -0,0 +1,111 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+/**
+ * Interactive ovcli.conf setup wizard shared by the OpenViking memory plugins.
+ *
+ * Lets a pure-marketplace install (no installer script) configure the server
+ * URL and API key that both the lifecycle hooks and the stdio MCP proxy read:
+ *
+ *   node <plugin>/scripts/setup.mjs
+ *
+ * Conventions: show current values, keep existing secrets on empty input,
+ * merge-write (never drop unknown fields), back up the previous file, 0600.
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { dirname } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { loadCredentialFiles } from "./credentials.mjs";
+
+const CLOUD_URL = "https://api.vikingdb.cn-beijing.volces.com/openviking";
+const LOCAL_URL = "http://127.0.0.1:1933";
+
+function maskSecret(value) {
+  const s = String(value || "");
+  if (!s) return "(not set)";
+  if (s.length <= 8) return "****";
+  return `${s.slice(0, 4)}…${s.slice(-4)} (${s.length} chars)`;
+}
+
+function readJsonSafe(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+export async function runSetupWizard({
+  input = process.stdin,
+  output = process.stdout,
+  env = process.env,
+} = {}) {
+  const { cliPath } = loadCredentialFiles(env);
+  const current = readJsonSafe(cliPath);
+  const rl = createInterface({ input, output });
+  const say = (line = "") => output.write(`${line}\n`);
+
+  try {
+    say("OpenViking memory plugin setup");
+    say(`Config file: ${cliPath}`);
+    say("");
+    say("Current values:");
+    say(`  url:     ${current.url || "(not set)"}`);
+    say(`  api_key: ${maskSecret(current.api_key)}`);
+    if (current.account) say(`  account: ${current.account}`);
+    if (current.user) say(`  user:    ${current.user}`);
+    say("");
+
+    const defaultUrl = current.url || LOCAL_URL;
+    say("Where do you connect to OpenViking?");
+    say(`  1) Self-hosted / local        [${LOCAL_URL}]`);
+    say(`  2) Volcengine OpenViking Cloud [${CLOUD_URL}]`);
+    say(`  3) Custom URL / keep current   [${defaultUrl}]`);
+    const mode = (await rl.question("Choice [1/2/3, default 3]: ")).trim();
+    let url = defaultUrl;
+    if (mode === "1") {
+      url = LOCAL_URL;
+    } else if (mode === "2") {
+      url = CLOUD_URL;
+    } else {
+      const answer = (await rl.question(`Server URL [${defaultUrl}]: `)).trim();
+      if (answer) url = answer;
+    }
+
+    const keyPrompt = current.api_key
+      ? `API key [enter = keep ${maskSecret(current.api_key)}, '-' = clear]: `
+      : "API key (leave empty for unauthenticated local mode): ";
+    const keyAnswer = await rl.question(keyPrompt);
+    let apiKey = current.api_key || "";
+    if (keyAnswer === "-") apiKey = "";
+    else if (keyAnswer.trim()) apiKey = keyAnswer.trim();
+    else if (!current.api_key) apiKey = "";
+
+    const next = { ...current, url, api_key: apiKey };
+
+    say("");
+    say("Changes:");
+    say(`  url:     ${current.url || "(not set)"} -> ${next.url}`);
+    say(`  api_key: ${maskSecret(current.api_key)} -> ${maskSecret(next.api_key)}`);
+    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 };
+    }
+
+    mkdirSync(dirname(cliPath), { recursive: true });
+    if (existsSync(cliPath)) {
+      copyFileSync(cliPath, `${cliPath}.bak.${Date.now()}`);
+    }
+    writeFileSync(cliPath, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    try {
+      chmodSync(cliPath, 0o600);
+    } catch {
+      /* best effort on platforms without chmod semantics */
+    }
+    say(`Written: ${cliPath}`);
+    say("The stdio MCP proxy and hooks pick this up on the next harness start.");
+    return { written: true, path: cliPath };
+  } finally {
+    rl.close();
+  }
+}

package/shared/uri-guard.mjs

@@ -0,0 +1,56 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+const DEFAULT_URI_KEYS = [
+  "filePath",
+  "file_path",
+  "filepath",
+  "path",
+  "uri",
+  "target_uri",
+  "targetUri",
+  "pattern",
+];
+
+export function normalizeToolName(value) {
+  return String(value || "").trim().toLowerCase();
+}
+
+export function findVikingUri(args = {}, keys = DEFAULT_URI_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);
+}
+
+export function findVikingUriInValue(value) {
+  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);
+      if (uri) return uri;
+    }
+    return null;
+  }
+  if (value && typeof value === "object") {
+    for (const item of Object.values(value)) {
+      const uri = findVikingUriInValue(item);
+      if (uri) return uri;
+    }
+  }
+  return null;
+}
+
+export function buildGuardMessage(uri, hint = {}) {
+  const tool = hint.tool || "the OpenViking MCP tools";
+  const example = typeof hint.example === "function" ? hint.example(uri) : hint.example;
+  const lines = [
+    "viking:// URIs are OpenViking virtual paths, not local filesystem paths.",
+    `Use ${tool} instead.`,
+  ];
+  if (example) lines.push(`Example: ${example}`);
+  return lines.join("\n");
+}

package/shared/workspace-peer.mjs

@@ -0,0 +1,16 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+export function deriveWorkspacePeerId(cwd) {
+  return String(cwd || "").replace(/[^A-Za-z0-9]/g, "-");
+}
+
+export function resolveEffectivePeerId({ cfg = {}, cwd = "" } = {}) {
+  const explicit = String(cfg.peerId || "").trim();
+  if (explicit) return { peerId: explicit, source: "explicit" };
+
+  if (cfg.workspacePeer !== false) {
+    const peerId = deriveWorkspacePeerId(cwd);
+    if (peerId) return { peerId, source: "workspace" };
+  }
+
+  return { peerId: "", source: "none" };
+}

package/tools.mjs

@@ -0,0 +1,246 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+
+export function registerOpenVikingTools(ctx, client, runtime) {
+  ctx.tools.register(textTool({
+    name: "viking_search",
+    description:
+      "Search OpenViking memories, resources, and skills. Use this for prior decisions, preferences, and project knowledge not present in the current context.",
+    parameters: {
+      query: { type: "string", required: true, description: "Semantic search query." },
+      scope: { type: "string", description: "Optional viking:// URI prefix." },
+      limit: { type: "integer", description: "Maximum results, from 1 to 50." },
+    },
+    async execute(args, exec) {
+      const actorPeerId = await peerFor(runtime, exec);
+      const results = await client.find(args.query, {
+        targetUri: args.scope,
+        limit: Math.max(1, Math.min(50, args.limit || 10)),
+        actorPeerId,
+      });
+      if (results.length === 0) return "No results found.";
+      return results.map(result => {
+        const abstract = result.abstract.length > client.config.recallMaxContentChars
+          ? `${result.abstract.slice(0, client.config.recallMaxContentChars)}...`
+          : result.abstract;
+        return `[${result.score.toFixed(2)}] ${result.uri}\n  ${abstract}`;
+      }).join("\n\n");
+    },
+  }));
+
+  ctx.tools.register(textTool({
+    name: "viking_read",
+    description:
+      "Read OpenViking content by viking:// URI at abstract, overview, or full detail.",
+    parameters: {
+      uri: { type: "string", required: true, description: "The viking:// URI to read." },
+      level: {
+        type: "string",
+        required: true,
+        enum: ["abstract", "overview", "full"],
+        description: "Detail level.",
+      },
+    },
+    async execute(args, exec) {
+      const content = await client.read(
+        args.uri,
+        args.level,
+        await peerFor(runtime, exec),
+      );
+      return typeof content === "string" && content
+        ? content
+        : `No content at ${args.uri}`;
+    },
+  }));
+
+  ctx.tools.register(textTool({
+    name: "viking_browse",
+    description: "List an OpenViking directory or inspect metadata for a viking:// URI.",
+    parameters: {
+      action: {
+        type: "string",
+        required: true,
+        enum: ["list", "stat"],
+        description: "Browse operation.",
+      },
+      uri: { type: "string", description: "URI to browse. Defaults to viking://." },
+    },
+    async execute(args, exec) {
+      const actorPeerId = await peerFor(runtime, exec);
+      const uri = args.uri || "viking://";
+      if (args.action === "stat") {
+        const info = await client.stat(uri, actorPeerId);
+        return info ? JSON.stringify(info, null, 2) : `Not found: ${uri}`;
+      }
+      const entries = await client.list(uri, actorPeerId);
+      if (entries.length === 0) return `Empty directory: ${uri}`;
+      return entries
+        .map(entry => `${entry.isDir ? "[dir]" : "[file]"} ${entry.name || entry.uri}`)
+        .join("\n");
+    },
+  }));
+
+  ctx.tools.register(textTool({
+    name: "viking_remember",
+    description:
+      "Store an important fact, preference, decision, or gotcha in the current OpenViking session.",
+    parameters: {
+      content: { type: "string", required: true, description: "Fact to remember." },
+      category: {
+        type: "string",
+        description: "Optional category such as preference, decision, entity, event, or pattern.",
+      },
+    },
+    async execute(args, exec) {
+      if (!exec.agent) throw new Error("viking_remember requires a calling agent");
+      const state = await runtime.initialize(exec.agent);
+      if (!state.ready) return "OpenViking server is not reachable.";
+      const category = args.category || "general";
+      const payload = {
+        role: "user",
+        content: `[Remember — ${category}] ${args.content}`,
+        ...(state.config.peerId ? { peer_id: state.config.peerId } : {}),
+      };
+      const response = await client.addMessage(
+        state.ovSessionId,
+        payload,
+        state.config.peerId,
+      );
+      return response.ok
+        ? `Remembered in OpenViking: "${args.content}" (${category})`
+        : `Failed to remember: ${response.error?.message || response.error?.code || "unknown error"}`;
+    },
+  }));
+
+  ctx.tools.register(textTool({
+    name: "viking_forget",
+    description:
+      "Permanently delete an OpenViking item only after the user explicitly asks to forget or delete it. Use an exact URI, or delete the strongest search match above score 0.8.",
+    parameters: {
+      uri: { type: "string", description: "Exact viking:// URI to delete." },
+      query: { type: "string", description: "Search query used when URI is omitted." },
+    },
+    async execute(args, exec) {
+      const actorPeerId = await peerFor(runtime, exec);
+      let uri = args.uri;
+      if (!uri && args.query) {
+        const results = await client.find(args.query, { limit: 1, actorPeerId });
+        if (!results[0] || results[0].score <= 0.8) {
+          return "No strong match found (score > 0.8 required).";
+        }
+        uri = results[0].uri;
+      }
+      if (!uri) return "Provide either uri or query.";
+      return await client.forget(uri, false, actorPeerId)
+        ? `Deleted: ${uri}`
+        : `Failed to delete: ${uri}`;
+    },
+  }));
+
+  ctx.tools.register(textTool({
+    name: "viking_add_resource",
+    description: "Ingest an HTTP(S) or git URL into OpenViking for indexed retrieval.",
+    parameters: {
+      url: { type: "string", required: true, description: "Remote URL to ingest." },
+      reason: { type: "string", description: "Why this resource is relevant." },
+    },
+    async execute(args, exec) {
+      const result = await client.addResource(
+        args.url,
+        args.reason,
+        await peerFor(runtime, exec),
+      );
+      return result?.root_uri
+        ? `Ingested: ${result.root_uri}`
+        : `Failed to ingest: ${args.url}`;
+    },
+  }));
+
+  ctx.tools.register(textTool({
+    name: "viking_archive_expand",
+    description: "Read original messages from one archive in the current DSH session.",
+    parameters: {
+      archive_id: { type: "string", required: true, description: "Archive id such as archive_001." },
+    },
+    async execute(args, exec) {
+      if (!exec.agent) throw new Error("viking_archive_expand requires a calling agent");
+      const state = await runtime.initialize(exec.agent);
+      const archive = await client.getSessionArchive(
+        state.ovSessionId,
+        args.archive_id,
+        state.config.peerId,
+      );
+      if (!archive) return `Archive not found: ${args.archive_id}`;
+      const messages = Array.isArray(archive.messages) ? archive.messages : [];
+      const header = [
+        `## ${archive.archive_id || args.archive_id}`,
+        archive.abstract ? `**Summary**: ${archive.abstract}` : "",
+        `**Messages**: ${messages.length}`,
+      ].filter(Boolean).join("\n");
+      const body = messages.map(formatArchiveMessage).join("\n\n");
+      return body ? `${header}\n\n${body}` : header;
+    },
+  }));
+}
+
+/** Presentation identity per tool: pending-card kind and title verb. */
+const TOOL_PRESENTATION = {
+  viking_search: { kind: "read", title: args => `OpenViking search: ${args.query}` },
+  viking_read: { kind: "read", title: args => `OpenViking read: ${args.uri}` },
+  viking_browse: { kind: "read", title: args => `OpenViking browse: ${args.uri ?? "viking://"}` },
+  viking_remember: { kind: "other", title: () => "OpenViking remember" },
+  viking_forget: { kind: "other", title: args => `OpenViking forget: ${args.uri ?? args.query ?? ""}` },
+  viking_add_resource: { kind: "other", title: args => `OpenViking ingest: ${args.url}` },
+  viking_archive_expand: { kind: "read", title: () => "OpenViking archive expand" },
+};
+
+/**
+ * All seven tools return model-facing text; `defineTool` owns parameter and
+ * output JSON-schema conversion, validation wiring, and reserved-name checks,
+ * so the definitions here stay declarative and track dsh's ToolDefinition
+ * contract through the pinned peer instead of a hand-built structure.
+ */
+function textTool(definition) {
+  const presentation = TOOL_PRESENTATION[definition.name];
+  return defineTool({
+    ...definition,
+    output: {
+      schema: { type: "string" },
+      render: (_args, value) => [{ type: "text", text: value }],
+    },
+    presentCall: args => ({
+      card: "generic",
+      kind: presentation.kind,
+      title: presentation.title(args),
+      rawInput: args,
+    }),
+  });
+}
+
+async function peerFor(runtime, exec) {
+  if (!exec.agent) return undefined;
+  return (await runtime.initialize(exec.agent)).config.peerId;
+}
+
+function formatArchiveMessage(message) {
+  const role = String(message?.role || "unknown");
+  const parts = Array.isArray(message?.parts) ? message.parts : [];
+  const body = parts.map(formatArchivePart).filter(Boolean).join("\n");
+  return `[${role}]: ${body || "(empty)"}`;
+}
+
+function formatArchivePart(part) {
+  if (!part || typeof part !== "object") return "";
+  if (part.type === "text") return String(part.text || "");
+  if (part.type === "context") {
+    return `[Context: ${part.uri || "unknown"}]\n${part.abstract || ""}`.trim();
+  }
+  if (part.type === "tool") {
+    const lines = [`[Tool: ${part.tool_name || "unknown"}]`];
+    if (part.tool_input !== undefined) {
+      lines.push(`Input: ${JSON.stringify(part.tool_input)}`);
+    }
+    if (part.tool_output) lines.push(`Output: ${part.tool_output}`);
+    return lines.join("\n");
+  }
+  return `[${part.type || "unknown"}]: ${JSON.stringify(part)}`;
+}

package/uri-guard.mjs

@@ -0,0 +1,51 @@
+import { buildGuardMessage, findVikingUri } from "./shared/uri-guard.mjs";
+
+const GUARDED_TOOLS = {
+  read: {
+    tool: "viking_read",
+    example: uri => `viking_read(uri="${uri}", level="overview")`,
+  },
+  glob: {
+    tool: "viking_browse",
+    example: uri => `viking_browse(action="list", uri="${uri}")`,
+  },
+  grep: {
+    tool: "viking_search",
+    example: (uri, args) =>
+      `viking_search(query="${escapeText(args?.pattern)}", scope="${uri}")`,
+  },
+  bash: {
+    tool: "viking_read or viking_search",
+    example: uri => `viking_read(uri="${uri}", level="overview")`,
+  },
+  edit: {
+    tool: "OpenViking tools",
+    example: uri => `viking_read(uri="${uri}", level="full")`,
+  },
+  write: {
+    tool: "OpenViking tools",
+    example: uri => `viking_read(uri="${uri}", level="full")`,
+  },
+  str_replace_editor: {
+    tool: "OpenViking tools",
+    example: uri => `viking_read(uri="${uri}", level="full")`,
+  },
+};
+
+export async function guardVikingUri(exec, next) {
+  const hint = GUARDED_TOOLS[exec.name];
+  if (!hint) return next();
+  const uri = findVikingUri(exec.arguments);
+  if (!uri) return next();
+  return {
+    kind: "deny",
+    reason: buildGuardMessage(uri, {
+      tool: hint.tool,
+      example: hint.example(uri, exec.arguments),
+    }),
+  };
+}
+
+function escapeText(value) {
+  return String(value || "").replaceAll('"', '\\"');
+}