@openviking/dsh-memory-plugin 0.1.0 → 0.2.1

package/README.md

@@ -1,22 +1,55 @@
 # OpenViking Memory for DeepSeek Harness
 
-An installable DeepSeek Harness bundle that adds OpenViking auto-recall, session capture, `viking://` URI protection, and model-invocable memory tools.
+An installable DeepSeek Harness bundle that adds OpenViking auto-recall, session capture, `viking://` URI protection, and the OpenViking MCP tool surface.
+
+Published as [`@openviking/dsh-memory-plugin`](https://www.npmjs.com/package/@openviking/dsh-memory-plugin).
+
+## Install
+
+DSH is covered by the unified memory-plugin installer, which asks which profile
+to install into (default `web`):
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh)
+```
+
+Or add the package to a profile directly:
+
+```bash
+dsh plugin --profile web add @openviking/dsh-memory-plugin
+dsh --profile web --dump-config    # should list the openviking-memory group
+```
+
+`dsh plugin` forwards to pnpm inside the profile directory, so the bundle has to
+be a real package. Linking a source checkout (`dsh plugin --profile web add
+./examples/dsh-memory-plugin`) only works when that checkout has its own
+`node_modules`, because Node resolves the bundle's dsh peers from the source
+tree's realpath rather than from the profile.
 
 ## Requirements
 
-- `@deepseek-ai/dsh` `0.1.0-rc.6`
+- `@deepseek-ai/dsh` `0.1.0-rc.6` or newer in the `0.1.x` release line
 - Node.js `^22.19.0` or `>=24`
 - A reachable OpenViking server
 
-The bundle has no runtime npm dependencies. Its tool and message structures
-come from the DSH constructors (`defineTool` from `@deepseek-ai/dsh-tools`,
-`createUserMessage` from `@deepseek-ai/dsh-llm`) behind exact-pinned
-peerDependencies that DSH exposes through its profile fallback at boot time, so
-the definitions track DSH's contracts instead of hand-built object shapes.
-It is tested against `0.1.0-rc.6`; install that exact DSH release because
-prerelease package dist-tags are not synchronized across the package family.
+The bundle has no runtime npm dependencies. Its message structures come from
+`createUserMessage` (`@deepseek-ai/dsh-llm`), its tool surface from
+`@deepseek-ai/dsh-mcp-client`, and its skill provider from
+`@deepseek-ai/dsh-skill-filesystem` — peerDependencies that DSH itself already
+installs, so there is nothing extra to add to a profile. The supported peer
+range starts at `0.1.0-rc.6` and stops before `0.2.0`, allowing current DSH
+releases whose core packages resolve to newer release candidates. The local
+devDependencies and `overrides` stay pinned to rc.6 so CI continues to exercise
+the minimum supported contract.
+
+Everything under `shared/` and `skills/` is generated by
+`node examples/memory-plugin-shared/sync.mjs` — edit
+`examples/memory-plugin-shared/lib/` and `examples/skills/`, never the vendored
+copies.
+
+## Design notes
 
-## Why injection uses pre-step user messages, not the system prompt
+### Why injection uses pre-step user messages, not the system prompt
 
 Recall and profile context enter through the `agent/pre-step` waterfall as
 durable, source-attributed user messages (`source: { kind: 'plugin', … }`).
@@ -28,27 +61,44 @@ context under such presets with no error. Pre-step injection also makes each
 injection a session event that replays, is visible to compaction, and never
 reaches `request/header`.
 
-## Install
-
-From the OpenViking repository:
-
-```bash
-dsh plugin --profile default add ./examples/dsh-memory-plugin
-```
-
-Or install the published package:
-
-```bash
-dsh plugin --profile default add @openviking/dsh-memory-plugin
-```
-
-Confirm that the profile includes the bundle:
-
-```bash
-dsh --profile default --dump-config
-```
-
-The package patch mounts the runtime inside a Cordis group with an isolated `openvikingMemory` service.
+### How the tool surface is mounted
+
+`mcp.mjs` mounts `@deepseek-ai/dsh-mcp-client` on `servers/mcp-proxy.mjs`, the
+same stdio proxy every other OpenViking memory integration starts, so the model
+gets the server's full tool set instead of a hand-maintained subset and the
+transport behaves identically across harnesses. Pointing the bridge straight at
+the server's `/mcp` endpoint does not work: with `stateless_http=True` the
+server still answers `GET /mcp` with an idle 200 SSE stream, and once the MCP
+SDK client opens that standalone stream it stops resolving POST responses, so
+`tools/list` never returns. The proxy owns the transport itself and is
+unaffected.
+
+The bundle's resolved credentials travel to the proxy through the child
+environment, because DSH scrubs credential-shaped names out of the inherited env
+and a subprocess cannot see the Cordis patch; the proxy then applies the usual
+`OPENVIKING_*` → `ovcli.conf` → `ov.conf` chain and reloads when those files
+change.
+
+Two consequences follow from the proxy being one process per profile:
+
+- **The actor peer is process-level.** Recall, capture, and commit still resolve
+  a peer per session from that session's workspace, but tool calls carry the
+  peer resolved at boot. Set `OPENVIKING_PEER_ID` when one process serves
+  several workspaces and you need tool calls attributed exactly.
+- **`remember` is not session-scoped.** The server's MCP `remember` stores into
+  its own short-lived session rather than the live `dsh-<session-id>` stream —
+  the same behavior the Claude Code, Codex, and Cursor integrations have.
+  Automatic capture still records the conversation itself.
+
+The bridge and the skill provider are mounted last in `apply()`, after every
+lifecycle registration, so a proxy that cannot start holds up nothing above it.
+
+### Why the skill gets its own provider
+
+`skills.mjs` registers a second `ctx.skills` provider with
+`includeDefaultRoots: false`, serving only `skills/`. DSH already mounts a
+`filesystem` provider over the project and user skill roots; an isolated
+provider adds the bundle's skill without shadowing or duplicating that catalog.
 
 ## Configuration
 
@@ -88,6 +138,7 @@ The patch can also carry plugin config:
             scoreThreshold: 0.35
             captureToolResults: false
             commitTokenThreshold: 20000
+            mcpToolCallTimeoutMs: 60000
 ```
 
 ## Behavior
@@ -97,28 +148,33 @@ The patch can also carry plugin config:
 - `session/event` captures user, assistant, and optionally tool-result messages without scraping a transcript.
 - `turn/end` checks the OpenViking pending-token threshold and commits when required.
 - Failed writes enter the shared OpenViking pending queue for replay at the next session start.
-- `tools/pre-execute` blocks DSH filesystem and shell tools from treating `viking://` URIs as local paths.
+- `tools/pre-execute` blocks DSH filesystem and shell tools from treating `viking://` URIs as local paths, pointing the model at the bridged `mcp__openviking__*` tools instead.
 
 Each DSH session maps to `dsh-<session-id>` in OpenViking. Workspace-derived actor peers are resolved per session and sent on every session-specific request.
 
 ## Tools
 
-The bundle registers:
+The model sees the OpenViking MCP tools under the bridge's server-qualified
+names — `mcp__openviking__search`, `mcp__openviking__read`,
+`mcp__openviking__list`, `mcp__openviking__tree`, `mcp__openviking__grep`,
+`mcp__openviking__glob`, `mcp__openviking__remember`,
+`mcp__openviking__write`, `mcp__openviking__edit`,
+`mcp__openviking__forget`, `mcp__openviking__add_resource`, and the rest of
+whatever the connected server advertises. The list re-syncs when the server
+announces a change, so a server upgrade adds tools without a bundle release.
 
-- `viking_search`
-- `viking_read`
-- `viking_browse`
-- `viking_remember`
-- `viking_forget`
-- `viking_add_resource`
-- `viking_archive_expand`
+`mcp__openviking__forget` performs permanent deletion. The calling model should
+use it only when the user explicitly requests deletion.
 
-`viking_forget` performs permanent deletion. The calling model should use it only when the user explicitly requests deletion.
+The bundle also serves the shared `openviking-memory` skill from `skills/`
+through its own isolated `ctx.skills` provider, so the model gets the same
+guidance on when to search, read, and write that the other integrations ship.
 
 ## Testing
 
 ```bash
 npm ci          # installs the exact-pinned dsh devDependencies the tests exercise
+npm run check   # syntax check every shipped module + package/PLUGIN_VERSION agreement
 npm test        # node --test *.test.mjs — runs in the repo's PR workflow
 ```
 

package/config.mjs

@@ -1,7 +1,14 @@
 import { buildUserAgent, resolveOpenVikingCredentials } from "./shared/credentials.mjs";
 import { resolveEffectivePeerId } from "./shared/workspace-peer.mjs";
 
-export const PLUGIN_VERSION = "0.1.0";
+export const PLUGIN_VERSION = "0.2.1";
+
+/**
+ * Namespace for the bridged OpenViking MCP tools. DSH publishes every MCP tool
+ * as `mcp__<serverName>__<rawName>`, so this string is part of the
+ * model-facing contract: changing it renames all of them.
+ */
+export const MCP_SERVER_NAME = "openviking";
 
 const DEFAULT_CONFIG = Object.freeze({
   endpoint: "http://127.0.0.1:1933",
@@ -31,6 +38,7 @@ const DEFAULT_CONFIG = Object.freeze({
   captureToolMaxChars: 1000000,
   captureAssistantTurns: true,
   requestTimeoutMs: 10000,
+  mcpToolCallTimeoutMs: 60000,
 });
 
 export function resolveConfig(input = {}, env = process.env, cwd = process.cwd()) {
@@ -134,6 +142,12 @@ export function resolveConfig(input = {}, env = process.env, cwd = process.cwd()
     120000,
     DEFAULT_CONFIG.requestTimeoutMs,
   );
+  config.mcpToolCallTimeoutMs = clampInteger(
+    config.mcpToolCallTimeoutMs,
+    1000,
+    600000,
+    DEFAULT_CONFIG.mcpToolCallTimeoutMs,
+  );
   config.captureMode = config.captureMode === "keyword" ? "keyword" : "semantic";
   config.syncTurns = config.syncTurns !== false;
   config.captureAssistantTurns = config.captureAssistantTurns !== false;

package/index.mjs

@@ -1,8 +1,9 @@
 import { OpenVikingClient } from "./client.mjs";
 import { resolveConfig } from "./config.mjs";
 import { injectStartupProfile } from "./lifecycle.mjs";
+import { mountOpenVikingMcp } from "./mcp.mjs";
 import { OpenVikingRuntime } from "./runtime.mjs";
-import { registerOpenVikingTools } from "./tools.mjs";
+import { mountOpenVikingSkills } from "./skills.mjs";
 import { guardVikingUri } from "./uri-guard.mjs";
 
 export const name = "openviking-memory";
@@ -18,8 +19,6 @@ export function apply(ctx, input = {}) {
     "openvikingMemory.disposeAll()",
   );
 
-  registerOpenVikingTools(ctx, client, runtime);
-
   ctx.on("agent/session-start", ({ agent }) => {
     agent.ctx.effect(
       () => () => runtime.dispose(agent.session),
@@ -53,4 +52,10 @@ export function apply(ctx, input = {}) {
   });
 
   ctx.on("tools/pre-execute", guardVikingUri);
+
+  // Mounted last, and deliberately not awaited: the bridge's apply blocks on
+  // its first tools/list, so a server that accepts the connection but never
+  // answers would otherwise hold up every registration above it.
+  mountOpenVikingMcp(ctx, config);
+  mountOpenVikingSkills(ctx);
 }

package/mcp.mjs

@@ -0,0 +1,43 @@
+import { fileURLToPath } from "node:url";
+import * as mcpClient from "@deepseek-ai/dsh-mcp-client";
+
+import { MCP_SERVER_NAME } from "./config.mjs";
+
+/** The same stdio proxy every other OpenViking memory integration starts. */
+export const PROXY_PATH = fileURLToPath(new URL("./servers/mcp-proxy.mjs", import.meta.url));
+
+/**
+ * Build the dsh-mcp-client config for the OpenViking stdio proxy.
+ *
+ * The bundle's own credential resolution (`OPENVIKING_*` → `ovcli.conf` →
+ * `ov.conf`, plus anything set in the Cordis patch) is forwarded through the
+ * child environment: DSH scrubs credential-shaped names out of the inherited
+ * env, and the patch is invisible to a subprocess, so values the runtime
+ * already resolved have to be passed explicitly.
+ */
+export function buildMcpConfig(config) {
+  const env = {};
+  if (config.endpoint) env.OPENVIKING_URL = config.endpoint;
+  if (config.apiKey) env.OPENVIKING_API_KEY = config.apiKey;
+  if (config.account) env.OPENVIKING_ACCOUNT = config.account;
+  if (config.user) env.OPENVIKING_USER = config.user;
+  if (config.peerId) env.OPENVIKING_PEER_ID = config.peerId;
+  return {
+    transport: "stdio",
+    serverName: MCP_SERVER_NAME,
+    command: process.execPath,
+    args: [PROXY_PATH],
+    env,
+    toolCallTimeoutMs: config.mcpToolCallTimeoutMs,
+  };
+}
+
+/**
+ * Mount the tool surface. The bridge ships with dsh itself, so it resolves
+ * from the host installation and never needs a separate install step.
+ * Startup failure is contained: recall, capture, and commit keep working
+ * against a server whose MCP endpoint is unreachable.
+ */
+export function mountOpenVikingMcp(ctx, config) {
+  return ctx.plugin(mcpClient, buildMcpConfig(config));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openviking/dsh-memory-plugin",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "OpenViking memory and context bundle for DeepSeek Harness",
   "type": "module",
   "main": "index.mjs",
@@ -13,10 +13,13 @@
     "config.mjs",
     "capture.mjs",
     "lifecycle.mjs",
+    "mcp.mjs",
     "runtime.mjs",
-    "tools.mjs",
+    "skills.mjs",
     "uri-guard.mjs",
+    "servers/",
     "shared/",
+    "skills/",
     "cordis.patch.yml",
     "README.md"
   ],
@@ -26,16 +29,40 @@
     }
   },
   "scripts": {
-    "test": "node --test *.test.mjs"
+    "check": "for f in *.mjs shared/*.mjs; do node --check \"$f\" || exit 1; done && npm run check:version",
+    "check:version": "node --input-type=module -e \"import {readFileSync} from 'node:fs'; const {PLUGIN_VERSION} = await import('./config.mjs'); const v = JSON.parse(readFileSync('package.json','utf8')).version; if (PLUGIN_VERSION !== v) throw new Error('PLUGIN_VERSION ' + PLUGIN_VERSION + ' does not match package.json version ' + v);\"",
+    "test": "node --test *.test.mjs",
+    "prepublishOnly": "npm run check && npm test"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-llm": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-tools": "0.1.0-rc.6"
+    "@deepseek-ai/dsh-llm": ">=0.1.0-rc.6 <0.2.0",
+    "@deepseek-ai/dsh-mcp-client": ">=0.1.0-rc.6 <0.2.0",
+    "@deepseek-ai/dsh-skill-filesystem": ">=0.1.0-rc.6 <0.2.0"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-llm": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-mcp-client": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-skill-filesystem": "0.1.0-rc.6",
     "@deepseek-ai/dsh-tools": "0.1.0-rc.6"
   },
+  "overrides": {
+    "@deepseek-ai/dsh-agent": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-attachment": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-brand": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-code-runtime": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-invariants": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-mcp-client": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-scope": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-skill-filesystem": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-subprocess": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-system-prompt": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-timeout": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-user-approval": "0.1.0-rc.6"
+  },
   "engines": {
     "node": "^22.19.0 || >=24"
   },

package/servers/mcp-proxy.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+/**
+ * stdio -> streamable-HTTP MCP proxy for the OpenViking DSH bundle.
+ *
+ * DSH's MCP bridge starts this process as a local stdio MCP server. The proxy
+ * reads the same OpenViking credential sources as the in-process runtime; the
+ * bundle also forwards its resolved config through the child environment, so
+ * values that came from the Cordis patch survive the process boundary.
+ */
+
+import { resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveConfig } from "../config.mjs";
+import { resolveOpenVikingCredentials } from "../shared/credentials.mjs";
+import { createLogger } from "../shared/debug-log.mjs";
+import { buildMcpProxyConfig } from "../shared/mcp-proxy-config.mjs";
+import { createOpenVikingMcpProxy } from "../shared/mcp-proxy-core.mjs";
+
+export function readProxyConfig(env = process.env, cwd = process.cwd()) {
+  const cfg = resolveConfig({}, env, cwd);
+  const creds = resolveOpenVikingCredentials(env);
+  return buildMcpProxyConfig({
+    baseUrl: cfg.endpoint,
+    apiKey: cfg.apiKey,
+    account: cfg.account,
+    user: cfg.user,
+    peerId: cfg.peerId,
+    userAgent: cfg.userAgent,
+    timeoutMs: cfg.requestTimeoutMs,
+    debug: Boolean(env.OV_DEBUG_LOG),
+    debugLogPath: env.OV_DEBUG_LOG,
+    credentialSource: creds.credentialSource,
+    credentialPath: creds.cliPath || creds.ovPath,
+    watchedPaths: [creds.cliPath, creds.ovPath, creds.cliPathCandidate],
+    env,
+  });
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolvePath(process.argv[1])) {
+  createOpenVikingMcpProxy({ readConfig: readProxyConfig, loggerFactory: createLogger }).start();
+}

package/shared/mcp-proxy-config.mjs

@@ -0,0 +1,90 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+/**
+ * Shared config shaping for the stdio MCP proxy entrypoints.
+ *
+ * Every harness loads its credentials differently, but the shape
+ * `createOpenVikingMcpProxy` consumes is identical everywhere, and so is the
+ * set of files whose changes must trigger a credential reload. Keeping that
+ * here stops each entrypoint from re-deriving `~` expansion, URL trimming,
+ * timeout clamping, and the watch list.
+ */
+
+import { homedir } from "node:os";
+import { join, resolve as resolvePath } from "node:path";
+
+export const DEFAULT_PROXY_TIMEOUT_MS = 15000;
+const MIN_PROXY_TIMEOUT_MS = 1000;
+
+export function trimSlash(value) {
+  return String(value || "").replace(/\/+$/, "");
+}
+
+/** Expand a leading `~` and resolve to an absolute path; "" stays "". */
+export function normalizeConfigPath(value) {
+  const raw = String(value || "").trim();
+  if (!raw) return "";
+  if (raw === "~") return homedir();
+  if (raw.startsWith("~/")) return resolvePath(join(homedir(), raw.slice(2)));
+  return resolvePath(raw);
+}
+
+/**
+ * The credential files every harness must watch: the two `OPENVIKING_*_FILE`
+ * overrides and the two default locations under `~/.openviking`.
+ */
+export function defaultCredentialPaths(env = process.env) {
+  return [
+    normalizeConfigPath(env.OPENVIKING_CLI_CONFIG_FILE),
+    normalizeConfigPath(env.OPENVIKING_CONFIG_FILE),
+    join(homedir(), ".openviking", "ovcli.conf"),
+    join(homedir(), ".openviking", "ov.conf"),
+  ].filter(Boolean);
+}
+
+function uniq(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+/**
+ * Shape a harness's loaded config into the object `createOpenVikingMcpProxy`
+ * expects.
+ *
+ * `mcpUrl` wins over `baseUrl` when both are given, so a harness that lets the
+ * user pin an explicit MCP URL keeps that behavior. `watchedPaths` are the
+ * harness's own extra files; the shared defaults are appended and the result
+ * deduplicated.
+ */
+export function buildMcpProxyConfig({
+  baseUrl = "",
+  mcpUrl = "",
+  apiKey = "",
+  account = "",
+  user = "",
+  peerId = "",
+  userAgent = "",
+  timeoutMs,
+  debug = false,
+  debugLogPath = "",
+  credentialSource = "auto",
+  credentialPath = "",
+  watchedPaths = [],
+  env = process.env,
+} = {}) {
+  return {
+    mcpUrl: mcpUrl || `${trimSlash(baseUrl)}/mcp`,
+    apiKey: apiKey || "",
+    account: account || "",
+    user: user || "",
+    peerId: peerId || "",
+    userAgent: userAgent || "",
+    timeoutMs: Math.max(
+      MIN_PROXY_TIMEOUT_MS,
+      Number(timeoutMs) || DEFAULT_PROXY_TIMEOUT_MS,
+    ),
+    debug: debug === true,
+    debugLogPath,
+    credentialSource: credentialSource || "auto",
+    credentialPath: credentialPath || "",
+    watchedPaths: uniq([...watchedPaths, ...defaultCredentialPaths(env)]),
+  };
+}