@modusensus/dsh-mneme 0.7.11 → 0.7.12

package/lib/config.js

@@ -249,4 +249,53 @@ export const Config = z.object({
   // audits to recall_runs and NEVER touches recall_evals, regardless of this
   // flag (production isolation is unconditional).
   evalPersistTestResults: z.boolean().default(false),
+
+  // --- standalone external API (v0.7.12) ------------------------------------
+  // A plain node:http server for ecosystem integrations that cannot reach the
+  // DSH-internal webServer. Disabled by default; when enabled the Bearer token
+  // is persisted in the settings kv ("external_api"), auto-generated on first
+  // boot. Bind host: keep the loopback default — moving it to a non-loopback
+  // address exposes the whole memory store to the network and is the
+  // operator's responsibility.
+  externalApiEnabled: z.boolean().default(false),
+  externalApiPort: z.natural().default(8790),
+  externalApiHost: z.string().default("127.0.0.1"),
+
+  // --- light mode preset (v0.7.12) -------------------------------------------
+  // One switch for low-resource setups: turns off every background/semantic
+  // heavy path (dream consolidation, entity extraction, vector pipeline,
+  // reranker, BM25, semantic dedup / selective inject, sleep mode) while
+  // keeping the core loop (autoInject, autoSummarize, hot memory, quality
+  // filter, keyword search). Applied by applyLightModePreset before the config
+  // reaches any service; a persisted panel_mode="light" (settings kv) counts
+  // as lightMode=true too and wins over the bundle config.
+  lightMode: z.boolean().default(false),
 });
+
+// Fields forced to false by the light-mode preset. Everything not listed here
+// (autoInject, autoSummarize, hotMemory*, memoryQualityFilter, dream
+// thresholds/delays, ...) is left untouched — those are the core loop.
+const LIGHT_MODE_OFF = [
+  "entityExtractionEnabled",
+  "autoDream",
+  "sleepModeEnabled",
+  "rerankEnabled",
+  "autoReindexOnBoot",
+  "hybridInject",
+  "searchSemanticDedup",
+  "selectiveInjectEnabled",
+  "bm25SearchEnabled"
+];
+
+/**
+ * Apply the light-mode preset to a resolved config object (pure function,
+ * exported for tests). When cfg.lightMode is not exactly true the config is
+ * returned unchanged; otherwise a shallow copy carries false for every heavy
+ * feature. Idempotent and side-effect free.
+ */
+export function applyLightModePreset(cfg) {
+  if (cfg?.lightMode !== true) return cfg;
+  const preset = { ...cfg, lightMode: true };
+  for (const key of LIGHT_MODE_OFF) preset[key] = false;
+  return preset;
+}

package/lib/index.js

@@ -7,13 +7,14 @@ import { createSummarizer } from "./summarize.js";
 import { createDreamScheduler } from "./dream.js";
 import { createSleepScheduler, runSleep } from "./dream/sleep.js";
 import { createApi } from "./api.js";
+import { createStandaloneApi } from "./api-standalone.js";
 import { createSettings } from "./settings.js";
 import { createCommandManager } from "./commands.js";
 import { createEmbedder } from "./embedding.js";
 import { createEmbedderByProvider } from "./local-embedder.js";
 import { LocalReranker } from "./reranker.js";
 import { createVectorIndex } from "./vector-index.js";
-import { Config } from "./config.js";
+import { Config, applyLightModePreset } from "./config.js";
 import { extractEntities } from "./entities/extractor.js";
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
@@ -29,12 +30,12 @@ export { Config };
 // has no prototype, is called normally, and its returned disposer is collected
 // and run by the fiber on unload.
 export const apply = (ctx, config) => {
-  const cfg = Config(config);
+  const rawCfg = Config(config);
 
   // Resolve memoryDir: expand leading "~"
-  const memoryDir = cfg.memoryDir.startsWith("~")
-    ? join(homedir(), cfg.memoryDir.slice(1))
-    : cfg.memoryDir;
+  const memoryDir = rawCfg.memoryDir.startsWith("~")
+    ? join(homedir(), rawCfg.memoryDir.slice(1))
+    : rawCfg.memoryDir;
   mkdirSync(memoryDir, { recursive: true });
 
   const store = createStore(join(memoryDir, "memory.db"));
@@ -47,11 +48,26 @@ export const apply = (ctx, config) => {
   // default 90). Best-effort like the failure prune — the audit trail is
   // bookkeeping and a failed purge must never block plugin boot.
   try {
-    if (cfg.llmAudit?.enabled !== false) {
-      const retentionMs = Number.isInteger(cfg.llmAudit?.retentionDays) ? cfg.llmAudit.retentionDays : 90;
+    if (rawCfg.llmAudit?.enabled !== false) {
+      const retentionMs = Number.isInteger(rawCfg.llmAudit?.retentionDays) ? rawCfg.llmAudit.retentionDays : 90;
       store.deleteOldLlmAudits(new Date(Date.now() - retentionMs * 86400000).toISOString());
     }
   } catch { /* non-fatal */ }
+
+  // User-configurable settings (profile, rules, panel mode, standalone API
+  // token) share the same SQLite file in dedicated tables, isolated from
+  // memories. Created before the config is finalized: the persisted
+  // panel_mode participates in light-mode resolution below.
+  const settings = createSettings(store.db);
+
+  // Light mode (v0.7.12): the bundle config flag OR a persisted panel_mode of
+  // "light" (the panel switch wins over the bundle config so it survives
+  // config redeploys). applyLightModePreset turns every heavy background /
+  // semantic feature off and keeps the core loop (autoInject, autoSummarize,
+  // hot memory, quality filter).
+  const lightMode = rawCfg.lightMode === true || settings.getPanelMode() === "light";
+  const cfg = applyLightModePreset({ ...rawCfg, lightMode });
+
   const mirror = createMirror(memoryDir);
   const service = createService({ store, mirror, config: cfg, logger: ctx.logger });
 
@@ -78,10 +94,6 @@ export const apply = (ctx, config) => {
     } catch { /* non-fatal: recall recording is bookkeeping */ }
   });
 
-  // User-configurable settings (profile, rules) and custom commands share the
-  // same SQLite file but live in dedicated tables, isolated from memories.
-  const settings = createSettings(store.db);
-
   // Semantic pipeline: a local/ollama embedder when configured, otherwise the
   // legacy OpenAI-compatible embedder (settings-driven). The vector index wraps
   // the store's embedding column and tracks the active model fingerprint. A
@@ -107,7 +119,13 @@ export const apply = (ctx, config) => {
 
   let embedder = null;
   let reranker = null;
-  if (cfg.embedProvider === "openai") {
+  if (lightMode) {
+    // Light mode: the whole vector pipeline stays off — no embedder (nothing
+    // pulls in ONNX/transformers), no reranker, no boot backfill (the preset
+    // also cleared autoReindexOnBoot). Recall degrades to keyword search and
+    // human mirror edits still merge on boot.
+    applyHumanEdits();
+  } else if (cfg.embedProvider === "openai") {
     // vectorIndex is passed so the legacy OpenAI embedder records the producing
     // model fingerprint after each successful embed (Bug3).
     embedder = createEmbedder({ store, settings, logger: ctx.logger, vectorIndex });
@@ -326,6 +344,19 @@ export const apply = (ctx, config) => {
     disposers.push(api.dispose);
   }
 
+  // Standalone external API (v0.7.12): plain node:http server for ecosystem
+  // integrations outside the DSH host. Persisted external_api settings win
+  // over the bundle config (enabled/port); the Bearer token lives in the same
+  // kv and is auto-generated on first boot by createStandaloneApi. Binding a
+  // non-loopback host is the operator's documented responsibility.
+  if ((settings.getExternalApi?.()?.enabled ?? cfg.externalApiEnabled) === true) {
+    const standalone = createStandaloneApi({ service, store, config: cfg, logger: ctx.logger, settings });
+    disposers.push(() => standalone.server.close());
+    standalone.ready.catch((error) => {
+      ctx.logger?.warn?.(`[dsh-mneme] standalone API failed to start: ${String(error)}`);
+    });
+  }
+
   // Async disposer: cordis awaits the returned promise on unload (runDisposable),
   // so an in-flight dream run is allowed to finish before the SQLite store is
   // closed — dream.dispose() resolves only after its current run settles.

package/lib/settings.js

@@ -137,6 +137,46 @@ export function createSettings(db) {
       };
       setSetting("vector", JSON.stringify(cfg));
       return cfg;
+    },
+
+    /**
+     * Standalone external API settings (kv "external_api"): {enabled, port,
+     * token}. The Bearer token is auto-generated on first boot and persisted
+     * here. Partial writes preserve the keys they don't mention.
+     */
+    getExternalApi() {
+      const raw = getSetting("external_api");
+      if (!raw) return undefined;
+      try {
+        const cfg = JSON.parse(raw);
+        return typeof cfg === "object" && cfg !== null ? cfg : undefined;
+      } catch {
+        return undefined;
+      }
+    },
+    setExternalApi(patch = {}) {
+      const prev = this.getExternalApi() ?? {};
+      const port = Number(patch.port ?? prev.port);
+      const host = typeof patch.host === "string" && patch.host.trim() ? patch.host.trim() : (prev.host ?? "127.0.0.1");
+      const cfg = {
+        enabled: patch.enabled !== undefined ? patch.enabled === true : prev.enabled === true,
+        port: Number.isInteger(port) && port > 0 ? port : 8790,
+        host,
+        token: String(patch.token ?? prev.token ?? "")
+      };
+      setSetting("external_api", JSON.stringify(cfg));
+      return cfg;
+    },
+
+    /**
+     * Web panel mode (kv "panel_mode"): "light" (low-resource preset) or
+     * "standard" (full feature set). Unset reads as "standard".
+     */
+    getPanelMode() {
+      return getSetting("panel_mode") === "light" ? "light" : "standard";
+    },
+    setPanelMode(mode) {
+      setSetting("panel_mode", mode === "light" ? "light" : "standard");
     }
   };
 }

package/lib/store.js

@@ -239,7 +239,10 @@ CREATE TABLE IF NOT EXISTS mirror_state (
 );
 `;
 
-const TYPES = new Set(["preference", "project", "decision", "history", "summary", "pattern"]);
+// Exported for API-layer type validation (standalone API POST /memories and
+// the /status byType breakdown); the set itself stays the single source of
+// truth for what store.save accepts.
+export const TYPES = new Set(["preference", "project", "decision", "history", "summary", "pattern"]);
 
 // Epistemic status: what kind of evidence a memory rests on. Defaults to
 // 'subjective' so legacy rows (and rows without any signal) stay compatible.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@modusensus/dsh-mneme",
   "description": "Cross-session memory plugin for DeepSeek Harness with autoDream consolidation: SQLite store, Markdown mirrors, 7 model tools, automatic injection, session summarization, user profile/rules, custom slash commands, vector (semantic) search, and a Web GUI panel",
-  "version": "0.7.11",
+  "version": "0.7.12",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -13,6 +13,9 @@
   },
   "type": "module",
   "main": "lib/index.js",
+  "bin": {
+    "dsh-mneme": "bin/cli.mjs"
+  },
   "exports": {
     ".": {
       "default": "./lib/index.js"
@@ -23,6 +26,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "bin",
     "lib",
     "src",
     "scripts",

package/src/api-standalone.js

@@ -0,0 +1,264 @@
+// Standalone HTTP API (v0.7.12): a plain node:http server for ecosystem
+// integrations that live outside the DSH host and cannot reach the plugin's
+// internal webServer routes (/api/dsh-mneme/*). Mirrors the JSON semantics of
+// those routes but with mandatory Bearer-token auth on everything except
+// GET /health, so the store can be exposed safely on loopback.
+//
+// Security: the default bind host is 127.0.0.1. Pointing externalApiHost at a
+// non-loopback address exposes the whole memory store to the network — that is
+// the operator's explicit responsibility (documented in README).
+import { createServer } from "node:http";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { TYPES } from "./store.js";
+
+const DEFAULT_PORT = 8790;
+const DEFAULT_HOST = "127.0.0.1";
+// Hardcoded release version (package.json is bumped at publish time and may
+// lag the code that ships in between).
+const VERSION = "0.7.12";
+
+function sendJson(res, status, payload) {
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify(payload));
+}
+
+/** True when the request carries the configured token. */
+function isAuthorized(req, apiToken) {
+  const raw = req.headers?.authorization ?? req.headers?.["x-dsh-mneme-token"] ?? "";
+  const token = raw.startsWith("Bearer ") ? raw.slice(7).trim() : raw.trim();
+  if (token === "" || token.length !== apiToken.length) return false;
+  // Constant-time comparison: no timing oracle on the token.
+  return timingSafeEqual(Buffer.from(token), Buffer.from(apiToken));
+}
+
+/** Collect the request body as text (tolerant of transport errors). */
+function readBody(req) {
+  return new Promise((resolve) => {
+    let body = "";
+    req.on("data", (chunk) => { body += chunk; });
+    req.on("end", () => resolve(body));
+    req.on("error", () => resolve(""));
+  });
+}
+
+/**
+ * Create (and start) the standalone API server.
+ * Accepts { service, store, config, logger, settings, port, host }:
+ *   - token: persisted settings kv "external_api" wins; auto-generated
+ *     (crypto.randomBytes(24).toString("base64url")) and persisted when empty.
+ *   - port:  explicit arg > persisted settings > config.externalApiPort > 8790.
+ *   - host:  explicit arg > config.externalApiHost > "127.0.0.1".
+ * Returns { server, port, host, token, ready }: `port` is the effective bound
+ * port (updated to the OS-assigned one after `ready` resolves when asked to
+ * bind port 0), `ready` resolves once listening and rejects if the bind fails.
+ */
+export function createStandaloneApi({ service, store, config = {}, logger, settings, port, host }) {
+  const persisted = settings?.getExternalApi?.() ?? {};
+
+  let token = typeof persisted.token === "string" ? persisted.token : "";
+  if (!token) {
+    token = randomBytes(24).toString("base64url");
+    // Persist only the token; enabled/port keys stay as they are (merge).
+    try {
+      settings?.setExternalApi?.({ token });
+    } catch (error) {
+      logger?.warn?.(`[dsh-mneme] standalone API token persistence failed: ${String(error)}`);
+    }
+  }
+
+  // Persisted host (set from the panel) wins over the bundle config, same
+  // precedence as port; the explicit argument still wins over both.
+  const boundHost = host
+    ?? (typeof persisted.host === "string" && persisted.host ? persisted.host : undefined)
+    ?? config.externalApiHost
+    ?? DEFAULT_HOST;
+  const persistedPort = Number(persisted.port);
+  const boundPort = port
+    ?? (Number.isInteger(persistedPort) && persistedPort > 0 ? persistedPort : undefined)
+    ?? config.externalApiPort
+    ?? DEFAULT_PORT;
+
+  const server = createServer((req, res) => {
+    try {
+      const url = new URL(req.url ?? "/", "http://localhost");
+      const pathname = url.pathname;
+
+      // Health is the single unauthenticated probe (monitor checks).
+      if (req.method === "GET" && pathname === "/health") {
+        sendJson(res, 200, { ok: true });
+        return;
+      }
+
+      // Everything else requires the Bearer token.
+      if (!isAuthorized(req, token)) {
+        sendJson(res, 401, { error: "unauthorized" });
+        return;
+      }
+
+      // --- GET /status: version + store shape + uptime -----------------------
+      if (req.method === "GET" && pathname === "/status") {
+        const byType = {};
+        for (const type of TYPES) byType[type] = service.count(type);
+        let entities = 0;
+        try {
+          entities = store.db.prepare("SELECT count(*) AS c FROM entities").get().c;
+        } catch { /* entities storage unavailable → 0 */ }
+        sendJson(res, 200, {
+          version: VERSION,
+          memories: { total: service.count(), byType },
+          entities,
+          uptime_s: Math.floor(process.uptime())
+        });
+        return;
+      }
+
+      // --- GET /memories: paged + filtered list (same semantics as the
+      //     internal /api/dsh-mneme/list) ------------------------------------
+      if (req.method === "GET" && pathname === "/memories") {
+        const type = url.searchParams.get("type") ?? undefined;
+        const limit = Number(url.searchParams.get("limit") ?? 50);
+        const offset = Number(url.searchParams.get("offset") ?? 0);
+        const order = url.searchParams.get("order") ?? undefined;
+        const minRaw = url.searchParams.get("minImportance");
+        const minImportance = minRaw !== null && minRaw !== "" && !Number.isNaN(Number(minRaw))
+          ? Number(minRaw)
+          : undefined;
+        const source = url.searchParams.get("source") || undefined;
+        const items = service.toApiList(service.list({ type, limit, offset, order, minImportance, source }));
+        // Total honors the same filters so pager math stays correct.
+        sendJson(res, 200, { items, total: service.count(type, { minImportance, source }) });
+        return;
+      }
+
+      // --- GET/DELETE /memories/:id ------------------------------------------
+      const idMatch = pathname.match(/^\/memories\/([^/]+)$/);
+      if (idMatch) {
+        let id = idMatch[1];
+        try { id = decodeURIComponent(id); } catch { /* keep raw */ }
+        if (req.method === "GET") {
+          const row = service.getById(id);
+          if (!row) {
+            sendJson(res, 404, { error: "not-found" });
+            return;
+          }
+          sendJson(res, 200, service.toApiList([row])[0]);
+          return;
+        }
+        if (req.method === "DELETE") {
+          // store.remove deletes silently — precheck for a distinguishable 404.
+          if (!service.getById(id)) {
+            sendJson(res, 404, { error: "not-found" });
+            return;
+          }
+          service.remove(id);
+          sendJson(res, 200, { ok: true });
+          return;
+        }
+        sendJson(res, 404, { error: "not-found" });
+        return;
+      }
+
+      // --- POST /memories: save with title-dedupe (safer than raw save) ------
+      if (req.method === "POST" && pathname === "/memories") {
+        void readBody(req).then((text) => {
+          let body;
+          try {
+            body = JSON.parse(text || "{}");
+          } catch {
+            sendJson(res, 400, { error: "invalid-json" });
+            return;
+          }
+          if (body === null || typeof body !== "object" || Array.isArray(body)) {
+            sendJson(res, 400, { error: "invalid-body" });
+            return;
+          }
+          // Pre-validate what store.save would throw on, so clients get a
+          // clean 400 instead of a leaked SQLite error.
+          if (!TYPES.has(body.type)) {
+            sendJson(res, 400, { error: "invalid-type" });
+            return;
+          }
+          if (typeof body.title !== "string" || !body.title.trim()) {
+            sendJson(res, 400, { error: "missing-title" });
+            return;
+          }
+          if (typeof body.content !== "string") {
+            sendJson(res, 400, { error: "missing-content" });
+            return;
+          }
+          if (body.tags !== undefined && !Array.isArray(body.tags)) {
+            sendJson(res, 400, { error: "tags-must-be-an-array" });
+            return;
+          }
+          try {
+            const { action, memory } = service.saveWithDedupe({
+              type: body.type,
+              title: body.title,
+              content: body.content,
+              importance: body.importance,
+              tags: body.tags,
+              source: body.source
+            });
+            sendJson(res, action === "created" ? 201 : 200, service.toApiList([memory])[0]);
+          } catch (error) {
+            logger?.warn?.(`[dsh-mneme] standalone API save failed: ${String(error)}`);
+            sendJson(res, 500, { error: "internal" });
+          }
+        });
+        return;
+      }
+
+      // --- GET /search: unified recall pipeline (keyword + vector + BM25) ----
+      if (req.method === "GET" && pathname === "/search") {
+        const q = url.searchParams.get("q") ?? "";
+        const limit = Number(url.searchParams.get("topK") ?? url.searchParams.get("limit") ?? 20);
+        const mode = url.searchParams.get("mode") ?? "auto";
+        const rerank = url.searchParams.get("rerank") !== "false";
+        const query = q.trim();
+        if (!query) {
+          sendJson(res, 200, { items: [], mode: "keyword" });
+          return;
+        }
+        // Any vector/rerank failure degrades to keyword inside searchMemories.
+        void Promise.resolve(
+          service.searchMemories(query, { mode, topK: limit, useRerank: rerank })
+        ).then((rows) => {
+          const used = rows.some((m) => m.vector === true) ? "vector" : "keyword";
+          sendJson(res, 200, { items: service.toApiList(rows), mode: used });
+        }).catch(() => {
+          sendJson(res, 200, { items: service.toApiList(service.search(query, { limit })), mode: "keyword" });
+        });
+        return;
+      }
+
+      sendJson(res, 404, { error: "not-found" });
+    } catch {
+      sendJson(res, 500, { error: "internal" });
+    }
+  });
+
+  // A permanent error listener keeps an EADDRINUSE / runtime socket error from
+  // crashing the host process; `ready` still surfaces the first bind failure.
+  server.on("error", (error) => {
+    logger?.warn?.(`[dsh-mneme] standalone API error: ${String(error)}`);
+  });
+  const ready = new Promise((resolve, reject) => {
+    server.once("listening", resolve);
+    server.once("error", reject);
+  });
+  server.listen(boundPort, boundHost);
+  ready.then(() => {
+    const address = server.address();
+    if (address && typeof address === "object") {
+      logger?.info?.(`[dsh-mneme] standalone API listening on http://${address.address}:${address.port}`);
+    }
+  }).catch(() => { /* already logged by the error handler above */ });
+
+  const api = { server, port: boundPort, host: boundHost, token, ready };
+  // After the OS assigns the real port (bind port 0), reflect it for callers.
+  ready.then(() => {
+    const address = server.address();
+    if (address && typeof address === "object") api.port = address.port;
+  }).catch(() => { /* bind failed: port stays as configured */ });
+  return api;
+}

package/src/api.js

@@ -1,11 +1,25 @@
 import { URL } from "node:url";
-import { timingSafeEqual } from "node:crypto";
+import { timingSafeEqual, randomBytes } from "node:crypto";
 
 function sendJson(res, status, payload) {
   res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
   res.end(JSON.stringify(payload));
 }
 
+// Defaults for the standalone external API — keep in step with the schema
+// defaults in config.js (externalApiPort / externalApiHost).
+const EXTERNAL_API_DEFAULTS = { enabled: false, port: 8790, host: "127.0.0.1" };
+
+/** Merge persisted external-api kv over the defaults for client display. */
+function fullExternalConfig(kv = {}) {
+  return {
+    enabled: kv.enabled === true,
+    port: Number.isInteger(kv.port) && kv.port > 0 ? kv.port : EXTERNAL_API_DEFAULTS.port,
+    host: kv.host || EXTERNAL_API_DEFAULTS.host,
+    token: kv.token || ""
+  };
+}
+
 /**
  * Mask an API key for client display: keep a recognizable prefix and suffix,
  * hide the middle. Empty keys stay empty; short keys are fully hidden.
@@ -535,6 +549,81 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // --- panel mode (v0.7.12): light / standard -------------------------------
+  // Persists the Web panel's feature preset into the settings kv
+  // ("panel_mode"). PUT requires auth like every other settings write; the
+  // value is validated against the enum. index.js applies the light preset on
+  // the next boot (persisted mode wins over the bundle config).
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/mode",
+    handler(req, res) {
+      try {
+        if (req.method === "PUT" || req.method === "POST") {
+          if (!requireAuth(req, res, apiToken)) return;
+          return readBody(req).then((text) => {
+            const body = parseBody(text);
+            if (body.mode !== "light" && body.mode !== "standard") {
+              sendJson(res, 400, { error: "invalid-mode" });
+              return;
+            }
+            settings.setPanelMode(body.mode);
+            sendJson(res, 200, { mode: settings.getPanelMode() });
+          });
+        }
+        sendJson(res, 200, { mode: settings.getPanelMode() });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
+  // --- external API settings (the standalone server's panel-facing config) ---
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/external-api",
+    handler(req, res) {
+      try {
+        if (req.method === "PUT" || req.method === "POST") {
+          if (!requireAuth(req, res, apiToken)) return;
+          return readBody(req).then((text) => {
+            const body = parseBody(text);
+            const patch = {};
+            if (body.enabled !== undefined) patch.enabled = body.enabled === true;
+            if (body.port !== undefined) {
+              const port = Number(body.port);
+              if (!Number.isInteger(port) || port < 1 || port > 65535) {
+                sendJson(res, 400, { error: "invalid-port" });
+                return;
+              }
+              patch.port = port;
+            }
+            if (body.host !== undefined) {
+              const host = String(body.host).trim();
+              if (!host || host.includes("://")) {
+                sendJson(res, 400, { error: "invalid-host" });
+                return;
+              }
+              patch.host = host;
+            }
+            sendJson(res, 200, { config: fullExternalConfig(settings.setExternalApi(patch)) });
+          });
+        }
+        // GET: always hand back a token — the standalone server generates its
+        // own on first enabled boot, but the panel displays it before that,
+        // so materialize and persist one here.
+        const kv = settings.getExternalApi() ?? {};
+        if (!kv.token) {
+          kv.token = randomBytes(24).toString("base64url");
+          settings.setExternalApi({ token: kv.token });
+        }
+        sendJson(res, 200, { config: fullExternalConfig(kv) });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
   // --- custom commands ---
   register({
     kind: "exact",
@@ -573,7 +662,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   });
 
   return {
-    routes: 15,
+    routes: 17,
     dispose: () => {
       for (const dispose of disposers) dispose();
     }