@gamaze/hicortex 0.19.0 → 0.19.1

package/README.md

@@ -54,7 +54,21 @@ openclaw plugins install @gamaze/hicortex
 openclaw gateway restart
 ```
 
-The plugin connects to `http://127.0.0.1:8787` by default. For a remote server, add `serverUrl` and `authToken` (find the token via `hicortex status` on the server) to the plugin config in `~/.openclaw/openclaw.json`.
+The plugin connects to `http://127.0.0.1:8787` by default. For a remote server, add `serverUrl` and `authToken` (find the token via `hicortex status` on the server) to the plugin's config section in `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "hicortex": {
+        "config": { "serverUrl": "http://your-server:8787", "authToken": "hctx-…" }
+      }
+    }
+  }
+}
+```
+
+Bare top-level keys (`"serverUrl": …` at the root of `openclaw.json`) still work — legacy compat — but the nested form above is canonical. An empty nested `config` object is ignored rather than shadowing top-level keys.
 
 ## Requirements
 
@@ -399,7 +413,7 @@ The nightly and the server behave differently on purpose: a malformed config mak
 
 **Tools not visible to agent (OC):** The plugin auto-adds tools to `tools.allow` on startup. Restart the gateway after install.
 
-**OC plugin: "Server unreachable":** The plugin requires a running Hicortex server. Run `npx @gamaze/hicortex init` on the same machine, or set `serverUrl` in the plugin config to point at a remote server.
+**OC plugin: "Server unreachable":** The plugin requires a running Hicortex server. Run `npx @gamaze/hicortex init` on the same machine, or set `serverUrl` in the plugin config (`plugins.entries.hicortex.config` in `~/.openclaw/openclaw.json`; bare top-level keys also work) to point at a remote server.
 
 **LLM auto-config failed:** Check logs for `[hicortex] WARNING`. Add `llmBaseUrl` to plugin config or set `HICORTEX_LLM_BASE_URL` env var (applies to server setup, not the OC plugin itself).
 

package/dist/index.d.ts

@@ -23,13 +23,37 @@
  * machine's Hicortex nightly reads them via oc-transcript-reader.ts —
  * canonical nightly-from-logs, same as CC JSONL and Hermes state.db.
  */
-import type { MemorySearchResult } from "./types.js";
+import type { HicortexConfig, MemorySearchResult } from "./types.js";
 export declare function formatToolResults(results: MemorySearchResult[]): {
     content: Array<{
         type: string;
         text: string;
     }>;
 };
+/**
+ * Resolve the plugin's config from the raw `ctx.config` OC hands the service
+ * (the ENTIRE openclaw.json — verified against gateway-cli createServiceContext:
+ * config = params.cfg — not a per-plugin section). Stateless: touches no module
+ * state, never mutates the input, never throws (console.warn is its only side
+ * effect). Three branches, first match wins:
+ *
+ *   1. `plugins.entries.hicortex.config` — the canonical OC per-plugin
+ *      section. Only eligible when it is a non-null object with ≥1 OWN key:
+ *      OC scaffolds `config: {}` for an installed-but-unconfigured plugin,
+ *      and that empty object must not shadow real config further down.
+ *   2. `hicortex` at the top level — but only when `typeof === "object"`:
+ *      a string/bool/number there (e.g. `"hicortex": true` as a feature
+ *      toggle) is not a config and is skipped, not cast.
+ *   3. the top level itself — bare keys (`serverUrl`, `authToken`, …) at the
+ *      root of openclaw.json; the pre-0.19 shape, kept for backcompat.
+ *
+ * `serverUrl` and `authToken` are validated at this boundary: a present but
+ * non-string (or empty-string) value warns naming the key and degrades —
+ * serverUrl falls back to DEFAULT_SERVER_URL, authToken to undefined. No
+ * throw paths: a malformed config degrades to defaults instead of leaving
+ * the plugin half-initialized.
+ */
+export declare function resolveOcPluginConfig(raw: unknown): HicortexConfig;
 declare const _default: {
     id: string;
     name: string;

package/dist/index.js

@@ -26,6 +26,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatToolResults = formatToolResults;
+exports.resolveOcPluginConfig = resolveOcPluginConfig;
 const paths_js_1 = require("./paths.js");
 const features_js_1 = require("./features.js");
 const extensions_js_1 = require("./extensions.js");
@@ -256,6 +257,104 @@ function formatToolResults(results) {
     return { content: [{ type: "text", text }] };
 }
 // ---------------------------------------------------------------------------
+// Config resolution
+// ---------------------------------------------------------------------------
+/** Object (not null, not array) → itself as a record; anything else → undefined. */
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v)
+        ? v
+        : undefined;
+}
+function isNonEmptyString(v) {
+    return typeof v === "string" && v.length > 0;
+}
+/** Human name for a config value that failed validation. Only ever called
+ *  with INVALID values (non-strings and empty strings), so the string branch
+ *  means "empty string". */
+function describeInvalid(v) {
+    if (v === null)
+        return "null";
+    if (Array.isArray(v))
+        return "an array";
+    if (typeof v === "string")
+        return "an empty string";
+    return typeof v === "object" ? "an object" : `a ${typeof v}`;
+}
+/**
+ * Resolve the plugin's config from the raw `ctx.config` OC hands the service
+ * (the ENTIRE openclaw.json — verified against gateway-cli createServiceContext:
+ * config = params.cfg — not a per-plugin section). Stateless: touches no module
+ * state, never mutates the input, never throws (console.warn is its only side
+ * effect). Three branches, first match wins:
+ *
+ *   1. `plugins.entries.hicortex.config` — the canonical OC per-plugin
+ *      section. Only eligible when it is a non-null object with ≥1 OWN key:
+ *      OC scaffolds `config: {}` for an installed-but-unconfigured plugin,
+ *      and that empty object must not shadow real config further down.
+ *   2. `hicortex` at the top level — but only when `typeof === "object"`:
+ *      a string/bool/number there (e.g. `"hicortex": true` as a feature
+ *      toggle) is not a config and is skipped, not cast.
+ *   3. the top level itself — bare keys (`serverUrl`, `authToken`, …) at the
+ *      root of openclaw.json; the pre-0.19 shape, kept for backcompat.
+ *
+ * `serverUrl` and `authToken` are validated at this boundary: a present but
+ * non-string (or empty-string) value warns naming the key and degrades —
+ * serverUrl falls back to DEFAULT_SERVER_URL, authToken to undefined. No
+ * throw paths: a malformed config degrades to defaults instead of leaving
+ * the plugin half-initialized.
+ */
+function resolveOcPluginConfig(raw) {
+    const warn = (msg) => console.warn(`[hicortex] WARNING: ${msg}`);
+    const full = isRecord(raw) ?? {};
+    // Branch 1 — isRecord at every level: a missing key, string, array, or
+    // null anywhere in the chain just falls through to the next branch.
+    const plugins = isRecord(full.plugins);
+    const entries = isRecord(plugins?.entries);
+    const entry = isRecord(entries?.hicortex);
+    const entryConfig = isRecord(entry?.config);
+    const nested = entryConfig !== undefined && Object.keys(entryConfig).length > 0
+        ? entryConfig
+        : undefined;
+    // Branch 2 — top-level `hicortex`, object-guarded (see doc block).
+    const hicortexObj = isRecord(full.hicortex);
+    const winner = nested ?? hicortexObj ?? full;
+    const winnerPath = nested !== undefined
+        ? "plugins.entries.hicortex.config"
+        : hicortexObj !== undefined ? "hicortex" : "the top level of openclaw.json";
+    // Copy, never the caller's object: sanitizing below must not mutate
+    // ctx.config, and pluginConfig must not alias OC's config state.
+    const resolved = { ...winner };
+    const rawUrl = winner.serverUrl;
+    if (rawUrl !== undefined && !isNonEmptyString(rawUrl)) {
+        warn(`plugin config key "serverUrl" must be a non-empty string (got ${describeInvalid(rawUrl)}) ` +
+            `— falling back to ${DEFAULT_SERVER_URL}`);
+        resolved.serverUrl = DEFAULT_SERVER_URL;
+    }
+    const rawToken = winner.authToken;
+    if (rawToken !== undefined && !isNonEmptyString(rawToken)) {
+        warn(`plugin config key "authToken" must be a non-empty string (got ${describeInvalid(rawToken)}) — ignoring it`);
+        resolved.authToken = undefined;
+    }
+    // Shadow detection (F2) — two configs disagreeing, surfaced instead of
+    // silently honoring one of them. Case 1: an OC-scaffolded EMPTY
+    // plugins.entries.hicortex.config was skipped while a bare top-level
+    // serverUrl exists (the exact shape the ≥1-own-key rule exists for).
+    // Gate on the ACTUAL winner (re-CR F1): in the compound shape (empty
+    // nested config + a top-level hicortex object + bare serverUrl) the hicortex
+    // object wins — the warn must not claim the bare key is being used.
+    if (nested === undefined && entryConfig !== undefined && winner === full && isNonEmptyString(full.serverUrl)) {
+        warn(`plugins.entries.hicortex.config is empty, so the top-level serverUrl is used instead — ` +
+            `remove the empty config section or move serverUrl into it`);
+    }
+    // Case 2: a real nested/hicortex section won the chain but carries no valid
+    // serverUrl, while a bare top-level serverUrl is set and will NOT be read.
+    if (winner !== full && !isNonEmptyString(rawUrl) && isNonEmptyString(full.serverUrl)) {
+        warn(`top-level serverUrl is set but ${winnerPath} takes precedence and has no valid serverUrl — ` +
+            `the plugin will NOT use the top-level value; move serverUrl into ${winnerPath}`);
+    }
+    return resolved;
+}
+// ---------------------------------------------------------------------------
 // Plugin export
 // ---------------------------------------------------------------------------
 exports.default = {
@@ -269,12 +368,19 @@ exports.default = {
         api.registerService({
             id: "hicortex-service",
             async start(ctx) {
-                const config = (ctx.config ?? {});
+                // OC passes the ENTIRE openclaw.json as ctx.config (verified against
+                // gateway-cli createServiceContext: config = params.cfg), not a
+                // per-plugin section. resolveOcPluginConfig picks our section out of
+                // it (branch order documented on the function) and validates the
+                // scalar keys at the boundary. It never throws, so a malformed config
+                // can only degrade (warn + default), never half-initialize the plugin.
+                const config = resolveOcPluginConfig(ctx.config);
                 pluginConfig = config;
                 const log = ctx.logger
                     ? (msg) => ctx.logger.info(msg)
                     : console.log;
-                // Resolve server URL and auth token from plugin config
+                // Resolve server URL and auth token from plugin config (both already
+                // validated strings — or absent, hence the ?? default)
                 serverUrl = (config.serverUrl ?? DEFAULT_SERVER_URL).replace(/\/+$/, "");
                 authToken = config.authToken;
                 // Use stateDir from context so tests can redirect state writes

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hicortex",
   "name": "Hicortex — Long-term Memory That Learns",
   "description": "Your agents remember past decisions, avoid repeated mistakes, and get smarter every day. Nightly reflection generates actionable lessons that automatically update agent behavior.",
-  "version": "0.10.0",
+  "version": "0.19.1",
   "kind": "lifecycle",
   "skills": ["./skills/hicortex-memory"],
   "configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Persistent agent identity for AI agents \u2014 a hand-edited identity layer, nightly-distilled experience, and lessons injected every session, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
   "main": "dist/index.js",
   "bin": {