@deepseek-insight/dsi 0.5.19 → 0.5.20

package/.agents/skills/dsi-ov-setup/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: dsi-ov-setup
+description: Use when OpenViking memory is broken or missing in DeepSeek Harness — server disconnected, server not installed, ov.conf missing, plugin not loaded, or a fresh machine needs the whole OpenViking + DSH memory integration set up (plugin, skill, server). Covers diagnosis, install, config, start, and verification.
+---
+
+# OpenViking + DSH Setup and Recovery
+
+Companion KB: `dev/kb/setup/2026-09-16 - OpenViking Server + DSH Memory Plugin — From Cold Start to Recalled Memory.md` — read it for the why behind every step. This skill is the do-path.
+
+## 0. Diagnose first — which failure is this?
+
+Run in order; stop at the first failing gate:
+
+| Gate | Command | Healthy looks like |
+|---|---|---|
+| Server process | `curl -s --max-time 3 http://127.0.0.1:1933/health` | `{"status":"ok","healthy":true,...}` |
+| Server config | `ls ~/.openviking/ov.conf` | exists |
+| Client config | `cat ~/.openviking/ovcli.conf` | `url` = `http://127.0.0.1:1933` |
+| Package | `openviking-server --version` | prints a version |
+| MCP connection | harness tool list shows `mcp__openviking__*` | tools present |
+
+- Health fails + `ov.conf` missing → **Recovery path (§2)**, the common case.
+- Health fails + `ov.conf` exists → run `openviking-server doctor`, fix what it names, go to §2 step 4.
+- Health ok but MCP disconnected → the plugin reconnects on its own within a turn or two; if not after a full turn, restart the harness session. Do not reinstall anything.
+- Package missing → fresh install: do §2 steps 1–6 from scratch.
+
+## 1. Facts to keep straight (most-confused pair)
+
+- `~/.openviking/ovcli.conf` — **client** pointer: `{"url": "http://127.0.0.1:1933", "api_key": ""}`. Missing it breaks CLI commands only.
+- `~/.openviking/ov.conf` — **server** model config (embedding + VLM). Missing it means the server process cannot start at all. This is the usual blocker.
+- The DSH plugin (`@openviking/dsh-memory-plugin`, in the profile bundles at `~/.dsh/profiles/web/package.json`) is a **client only** — it never starts the server, and it reconnects automatically once the server is healthy. Never "fix" a disconnected MCP by touching the plugin.
+- `openviking`/`ov` = CLI/SDK; `openviking-server` = the daemon. Same pip package.
+
+## 2. Recovery / install path
+
+### Step 1 — Install the package (skip if `openviking-server --version` works)
+
+```sh
+pip install openviking --upgrade --force-reinstall
+```
+
+Entry points land in `~/.local/bin`: `ov`, `openviking`, `openviking-server`, `vikingbot`.
+
+### Step 2 — CLI housekeeping
+
+```sh
+ov language en        # v0.3.23+ refuses most commands without this; writes ovcli.settings.conf
+ov config add custom --name local --url http://127.0.0.1:1933 --activate -o json   # only if ovcli.conf missing
+```
+
+Note: both write under `~/.openviking/` — they fail under a workspace-only file sandbox; run with full file access.
+
+### Step 3 — Create the server config: `openviking-server init`
+
+Preferred: run it interactively and let the human answer. If driving it with piped answers, the wizard's prompt order is exact and hidden prompts exist — the tested sequence for the recommended local setup:
+
+```
+1     # mode: step-by-step
+3     # embedding: lightweight CPU (llama.cpp, bge-small-zh-v1.5-f16, no key)
+1     # embedding model: (only option — EASY TO MISS; missing this shifts every later answer)
+6     # VLM: GLM (subscription API key)
+2     # GLM plan: coding
+<key> # API key — pass via stdin from an env var; NEVER in the command line or logs
+N     # query planner via Ollama: no
+1     # bind 127.0.0.1 (dev, no auth)
+1933  # port
+Y     # save
+```
+
+After saving the wizard echoes the resolved API key in its summary — **redact any captured log** before storing it.
+
+Decision guardrails (from the KB §4): embedding `[3]` CPU is the default because it is keyless and tiny; offer `[1]` cloud embedding only when the user cares about retrieval quality and has a key; VLM is the piece worth a strong model — GLM via an existing subscription beats skipping it. `[9]` skip-VLM gives a server that stores but extracts poorly.
+
+### Step 4 — Wait out the build
+
+Choosing CPU embedding triggers `pip install "openviking[local-embed]"`, which **builds `llama-cpp-python` from source** — several minutes of silent wheel-building. It is not hung. Do not kill it; verify with `ps aux | grep "openviking-server init"`.
+
+### Step 5 — Validate and start
+
+```sh
+openviking-server doctor    # expect: all checks PASS (config, auth, disk ≥ several GB)
+openviking-server           # foreground proof; then move to a supervisor
+```
+
+For persistence: launchd/nohup/systemd — never rely on an agent shell outliving the session. Verify:
+
+```sh
+curl -s http://127.0.0.1:1933/health   # {"status":"ok","healthy":true,...}
+ov status                              # "Connected (Healthy)", queue 0 pending / 0 errors
+```
+
+A stale `~/.openviking/pending/` queue (hundreds of files) from the downtime drains on its own — do not delete it.
+
+### Step 6 — Confirm the integration
+
+Within a turn of the server going healthy, the plugin reconnects (MCP tools answer, `<openviking-context>` appears at the next session start). If MCP tools still error after a full turn: restart the harness session once. Only then suspect the bundle (`~/.dsh/profiles/web/package.json` must list `@openviking/dsh-memory-plugin` in `dsh.profile.bundles`).
+
+## 3. Verification checklist (all seven, in order)
+
+1. `openviking-server --version` → prints version
+2. `ls ~/.openviking/ov.conf ~/.openviking/ovcli.conf` → both exist
+3. `openviking-server doctor` → all PASS
+4. `curl -s http://127.0.0.1:1933/health` → `"healthy":true`
+5. `ov status` → Connected (Healthy), 0 errors
+6. `ov find "smoke test"` after any resource exists → ranked hits, not a connection error
+7. New session → `<openviking-context>` block present
+
+## 4. Known traps
+
+- `ov status` saying "Unreachable" while the server is fine → the language gate; run `ov language en` first.
+- Two config files, one directory (§1) — check the right one for the symptom.
+- `auth_mode: "dev"` = no auth, localhost only. Never bind `0.0.0.0` without switching to API-key auth (docs: Authentication guide).
+- Piped `init` answers are prompt-order-fragile (Step 3) — count prompts, don't trust defaults.
+- Re-examine actual prompt output on every version bump; this sequence was tested against OpenViking 0.4.20 / plugin 0.3.2 (2026-09-16) and the wizard's prompts are not a stable contract.

package/bin/dsi.mjs

@@ -12,6 +12,8 @@
 // script AND serves the dsi build — one foreground pair, one Ctrl-C.
 // `--dev` serves the Vite dev server instead of the build (sources only).
 // `dsi dsh --sync-kills` sweeps orphans a lost previous run left behind.
+// `dsi dsh --ov` (or --sync --ov) installs the OpenViking memory plugin into
+// the active dsh profile by delegating to `dsh plugin ... add` (idempotent).
 
 import { spawn, spawnSync } from 'node:child_process';
 import net from 'node:net';
@@ -53,6 +55,9 @@ const USAGE = [
 	'               port 5175; needs a full checkout: pnpm install)',
 	'      --sync-kills',
 	'               kill orphaned dsh/dsi processes left by an earlier run',
+	'      --ov    install the OpenViking memory plugin into the active dsh',
+	'              profile (dsh plugin ... add). Client only — the memory',
+	'              server itself is set up separately (dsi-ov-setup skill)',
 	'',
 	'  Ports: `dsi dsh --sync` serves the DSI page on 5174 and opens your',
 	'  browser there. With --dev the Vite dev server takes 5175 instead',
@@ -67,9 +72,12 @@ const USAGE = [
 	'                   ~/.dsh/settings.yaml',
 	'      dsi dsh --token <token>',
 	'                   store the dsh launch token in ~/.dsi/settings.yaml',
-	'      dsi dsh --sync [--zai] [--dev]',
+	'      dsi dsh --sync [--zai] [--dev] [--ov]',
 	'                   run dsh-web-synced.sh (dsh web + token sync) AND serve',
 	'                   dsi — see the recommended command above',
+	'      dsi dsh --ov',
+	'                   install the OpenViking memory plugin into the active',
+	'                   dsh profile (idempotent; alone, without --sync)',
 	'      dsi dsh --sync-kills',
 	'                   kill orphaned dsh/dsi processes left by an earlier run'
 ].join('\n');
@@ -87,6 +95,11 @@ if (command !== 'web' && command !== 'zai' && command !== 'dsh') {
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
+/** The OpenViking memory plugin DSI's host profile wants. Client-side only:
+ *  it never starts openviking-server — it reconnects on its own once the
+ *  server is healthy (KB 2026-09-16 §2). */
+const OV_PLUGIN = '@openviking/dsh-memory-plugin';
+
 // ── dsi zai ────────────────────────────────────────────────────────────────
 
 /** The ZAI provider block, byte-for-byte the fresh-install shape. */
@@ -156,6 +169,10 @@ if (command === 'dsh') {
 		setDshAuthToken(token);
 		process.exit(0);
 	}
+	if (flag === '--ov') {
+		runOvPlugin();
+		process.exit(0);
+	}
 	if (flag === '--sync') {
 		// --zai and --dev are dsi-side flags, stripped from the args the sync
 		// script forwards to `dsh web` (which would refuse them):
@@ -166,10 +183,12 @@ if (command === 'dsh') {
 		const rest = process.argv.slice(4);
 		const withZai = rest.includes('--zai');
 		const withDev = rest.includes('--dev');
+		const withOv = rest.includes('--ov');
 		if (withZai) addZaiProvider();
+		if (withOv) runOvPlugin();
 		runSkillsMirror();
 		runSyncedPair(
-			rest.filter((arg) => arg !== '--zai' && arg !== '--dev'),
+			rest.filter((arg) => arg !== '--zai' && arg !== '--dev' && arg !== '--ov'),
 			withDev
 		);
 	} else if (flag === '--sync-kills') {
@@ -387,6 +406,47 @@ function addZaiProvider() {
 	console.log(`dsi zai: ${settingsPath} updated — set ZAI_API_KEY in the harness env, then restart dsh web`);
 }
 
+/** Install the OpenViking memory plugin into the active dsh profile by
+ *  delegating to `dsh plugin --profile <profile> add` — the same dsh
+ *  launcher `dsi dsh --sync` uses (DSH_WEB_CMD override, else the published
+ *  pin via npx). dsh's own reconcilePlugins appends the package to
+ *  dsh.profile.bundles (it declares a dsh.bundle), so nothing is hand-edited
+ *  here. Idempotent: a profile that already has the dependency AND the bundle
+ *  entry skips the pnpm round-trip. Fail-loud: a nonzero child exit (or a
+ *  missing pnpm — dsh exits 127 for it) propagates. */
+function runOvPlugin() {
+	const profile = process.env.DSH_PROFILE ?? 'web';
+	const manifestPath = path.join(
+		homedir(), '.dsh', 'profiles', profile, 'package.json'
+	);
+	if (existsSync(manifestPath)) {
+		try {
+			const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+			const deps = manifest?.dependencies ?? {};
+			const bundles = manifest?.dsh?.profile?.bundles ?? [];
+			if (deps[OV_PLUGIN] !== undefined && bundles.includes(OV_PLUGIN)) {
+				console.log(`dsi dsh: ${OV_PLUGIN} already installed in the ${profile} profile — nothing to do`);
+				return;
+			}
+		} catch (error) {
+			console.error(`dsi dsh: cannot parse ${manifestPath}: ${error?.message ?? error}`);
+			process.exit(65);
+		}
+	}
+	const cmd = process.env.DSH_WEB_CMD
+		? `${process.env.DSH_WEB_CMD} plugin --profile ${profile} add ${OV_PLUGIN}`
+		: `npx --yes @deepseek-ai/dsh@${dshWebVersion()} plugin --profile ${profile} add ${OV_PLUGIN}`;
+	console.log(`dsi dsh: installing ${OV_PLUGIN} into the ${profile} profile (${cmd})`);
+	const result = spawnSync('/bin/sh', ['-c', cmd], { stdio: 'inherit' });
+	if (result.error !== undefined) throw result.error;
+	const code = result.status ?? 1;
+	if (code !== 0) {
+		console.error(`dsi dsh: plugin install failed (exit ${code}) — pnpm on PATH is required; fix the cause above, then re-run`);
+		process.exit(code);
+	}
+	console.log(`dsi dsh: ${OV_PLUGIN} installed — it connects on its own once openviking-server answers (see the dsi-ov-setup skill for the server side)`);
+}
+
 /** Plant the shipped skills into the operator's skill mirror
  *  (~/.agents/skills) — ADR "The Skill Mirror" 2026-09-15, D1–D5:
  *  per-skill copy-only-if-absent, every repo skill, failures warn and