@aliyunrds/ctxdb 1.0.10 → 1.0.11-beta.1

package/README.md

@@ -9,7 +9,7 @@ Unified access layer for RDS ContextDatabase. One `ctxdb` CLI (memory + KB ops),
 | **qwenwork** | ✅ UserPromptSubmit + Stop + SessionStart | `~/.qwenwork/skills/ctxdb/` | hooks-driven (auto capture/recall) |
 | **codex** | ✅ UserPromptSubmit + Stop + SessionStart | `~/.codex/skills/ctxdb/` | hooks-driven (auto capture/recall) |
 | **claude** | ✅ UserPromptSubmit + Stop + SessionStart | `~/.claude/skills/ctxdb/` | hooks-driven (auto capture/recall) |
-| **opencode** | Plugin shim (`~/.config/opencode/plugins/ctxdb.ts`) | `~/.config/opencode/skills/` | in-process plugin (auto capture/recall + KB catalog injection) |
+| **opencode** | Plugin bundle (`~/.config/opencode/plugins/ctxdb-bundle.js`) | `~/.config/opencode/skills/` | in-process plugin (auto capture/recall + KB catalog injection) |
 | **hermes** | ✅ `pre_llm_call` + `post_llm_call` | `~/.hermes/skills/` | shell hooks (auto capture/recall + first-turn warmup) |
 | **workbuddy** | ✅ UserPromptSubmit + Stop + SessionStart | `~/.workbuddy/skills/` and `~/.workbuddy-ai/skills/` (existing homes) | CodeBuddy command hooks (complete shell command, no separate `args`) |
 
@@ -155,7 +155,11 @@ ctxdb auth status --json
 
 The internal tarball bundles `@aliyunrds/ctxdb-shared`, so users install only
 one ContextDB package. `semver` and `yaml` remain normal registry dependencies.
-Maintainers should follow [`INTERNAL_PUBLISH.md`](./INTERNAL_PUBLISH.md).
+Maintainers should follow [`INTERNAL_PUBLISH.md`](./INTERNAL_PUBLISH.md) for Ali NPM.
+For public releases, use [`LOCAL_PUBLISH.md`](./LOCAL_PUBLISH.md) to build with
+`pnpm pack` and validate the exact tarballs, then follow [`PUBLISH.md`](./PUBLISH.md)
+to upload those tarballs with `npm publish`. npm publication does not update the
+separate [OSS installer scripts and agent manual](../../docs/bootstrap-release.md).
 
 ### Recommended: console-generated installer command
 
@@ -309,7 +313,7 @@ ctxdb status --agent codex --json
 
 Setup first checks that the target agent home exists (`~/.qoder`, `~/.qoderwork`, `~/.qwenwork`, `~/.codex`, `~/.claude`, or either WorkBuddy home: `~/.workbuddy` / `~/.workbuddy-ai`; other declared CN variant homes also satisfy this check). Setup writes hooks and skills into every existing home, so a CN-only install does not create the international product home, and vice versa. If no home exists, install or start that agent once before running `ctxdb setup --agent <name>`. OpenCode and Hermes are config-dir style: setup creates `~/.config/opencode` / `~/.hermes` when they are missing.
 
-For **qoder**, **qoderwork**, **qwenwork**, **codex**, **claude**, and **workbuddy**, restart the harness (CLI: just exit + restart; app: Cmd+R or quit/relaunch) so it picks up the new hooks/skill. For **codex**, setup also writes `[features].hooks = true` into `~/.codex/config.toml` (creating the file if missing) — Current Codex versions enable hooks by default; the explicit setting also supports older installs. Review and trust each installed or changed hook definition in `/hooks` before use. For **opencode**, restart OpenCode so it loads `~/.config/opencode/plugins/ctxdb.ts`. For **hermes**, setup also checks `~/.hermes/shell-hooks-allowlist.json`; it reports setup as incomplete until both ctxdb hook commands are approved.
+For **qoder**, **qoderwork**, **qwenwork**, **codex**, **claude**, and **workbuddy**, restart the harness (CLI: just exit + restart; app: Cmd+R or quit/relaunch) so it picks up the new hooks/skill. For **codex**, setup also writes `[features].hooks = true` into `~/.codex/config.toml` (creating the file if missing) — Current Codex versions enable hooks by default; the explicit setting also supports older installs. Review and trust each installed or changed hook definition in `/hooks` before use. For **opencode**, restart OpenCode so it loads `~/.config/opencode/plugins/ctxdb-bundle.js`. For **hermes**, setup also checks `~/.hermes/shell-hooks-allowlist.json`; it reports setup as incomplete until both ctxdb hook commands are approved.
 
 Hermes owns this security allowlist, so ctxdb only checks it and never writes approvals. Approve the ctxdb `pre_llm_call` and `post_llm_call` hooks with:
 
@@ -366,7 +370,7 @@ Implementation note: qoder/Claude/WorkBuddy consume the JSON `hookSpecificOutput
 
 WorkBuddy 5.5.2 on macOS requires the full shell command in `command`; its runner ignores `args`. Native Auto (default routing label; underlying model unknown) and explicitly selected GPT-5.6-Sol completed automatic Skill Evaluate, suggestion delivery, generation, Upload/Complete, and exact Load. The final package also passed cold-cache Load for both versions. Sol required one native Retry after a platform error; Auto's extra execution was not proven fully isolated. Windows runner behavior and Memory capture/recall were not tested in this acceptance run. See the [Agent/model acceptance report](../../docs/skill-agent-acceptance-20260912.md) and [WorkBuddy evidence](../../docs/workbuddy-acceptance-20260912.md) for version scope, retained failures, and cleanup.
 
-For **opencode**, `ctxdb setup --agent opencode` copies the self-contained plugin bundle to `~/.config/opencode/plugins/ctxdb-bundle.js` and writes a re-export shim at `~/.config/opencode/plugins/ctxdb.ts` referencing it via the relative path `./ctxdb-bundle.js` (Bun on Windows can't resolve absolute-path specifiers from a .ts shim). `ctxdb upgrade --agent opencode` re-copies the bundle + refreshes the shim.
+For **opencode**, `ctxdb setup --agent opencode` copies the self-contained plugin bundle to `~/.config/opencode/plugins/ctxdb-bundle.js` as the single auto-loaded entry. Setup and `ctxdb upgrade --agent opencode` remove the older generated `ctxdb.ts` shim: OpenCode loads both `.ts` and `.js`, so keeping both files initializes the plugin twice. Run upgrade after updating the npm package, then restart OpenCode. An unrecognized `ctxdb.ts` is preserved and reported as a migration conflict.
 
 For **hermes**, `ctxdb setup --agent hermes` writes two shell hooks under `~/.hermes/config.yaml`:
 
@@ -443,6 +447,17 @@ fact-extraction). Use it when the user explicitly asks for a verbatim
 memory ("记住 / 请记忆 / 原文记下"); without `--no-infer` the server may
 rewrite, merge, or skip details.
 
+Memory uploads (`memory add`, including images, and automatic hook/plugin
+capture) always send a top-level `agent_id`. `CTXDB_AGENT_ID` takes precedence
+over the selected config's `agent_id`; when neither is set, uploads use the
+current Agent name (`--agent`, then `CTXDB_AGENT`, then `default`; OpenCode's
+plugin uses `opencode`). `default` means no specific host was selected.
+This fallback applies only to uploads: default search/list and automatic
+recall remain unchanged, so historical and other agents' memories can still
+be retrieved. An explicitly configured `agent_id` continues to filter
+automatic recall. The field records write attribution; server-side memory
+organization may still deduplicate facts across agents within one Member.
+
 `memory add [<text>] --image=<local-path>` adds an image-backed memory.
 Repeat `--image` to attach multiple PNG, JPEG, or WebP files; text is optional
 when at least one image is present. Image requests require inference, so they
@@ -861,8 +876,8 @@ Field reference:
 | Key | Type | Default | Meaning |
 |---|---|---|---|
 | `user_id` | str | `"default"` | mem0-layer bucket key on every capture/recall call. The server's tenant isolation runs on `member_id` (injected from `X-API-Key`), so this is an optional per-user/agent slice. Override with `ctxdb setup --agent <a> --user-id <bucket>` or `CTXDB_USER_ID=<bucket>` when you need to isolate this install from another access layer or machine sharing the same workspace |
-| `agent_id` | str | null | Optional scope dimension on every capture/recall call. **Default null = not sent** — the server counts `agent_id` as scope on the search path, so emitting it by default would narrow every existing user's recall. Set only when you want per-agent isolation: `CTXDB_AGENT_ID=<id>` (env-only; no setup flag) |
-| `app_id` | str | null | Optional app-scope dimension, same contract as `agent_id` (default null = not sent). Set via `CTXDB_APP_ID=<id>` (env-only) |
+| `agent_id` | str | null | Explicit memory upload attribution and automatic-recall filter. Uploads fall back to the current Agent name; automatic recall omits this filter unless explicitly configured. `CTXDB_AGENT_ID=<id>` overrides this value (no setup flag). This does not guarantee per-agent retention during server-side deduplication. |
+| `app_id` | str | null | Optional app-scope dimension for automatic capture/recall; default null means not sent. Set via `CTXDB_APP_ID=<id>` (env-only). |
 | `auto_capture` | bool | `true` | End-of-turn hook/plugin captures each turn into long-term memory for the selected agent |
 | `auto_skill_evolution` | bool | `true` | Evidence collection and automatic evolution through the selected Agent hooks/plugin. Hermes delivers ready suggestions on the next genuine user turn. Disabling it keeps private Skill discovery and explicit commands available. |
 | `auto_recall` | bool | `true` | UserPromptSubmit hook recalls memory on each user prompt for the selected agent |
@@ -872,7 +887,7 @@ Field reference:
 | `knowledge_top_k` | int | `6` | KB chunks pulled per recall (only effective when `recall_knowledge: true`) |
 | `debug` | bool | `false` | Configured preference for verbose hook logging and full recall tracing. Effective debug is forced on for every final `base_url` outside the exact official-production allowlist; see “Debug control and recall replay”. General logs go to `~/.ctxdb/logs/ctxdb.log`, structured full-content recall records to `~/.ctxdb/logs/recall-trace.jsonl` |
 
-Env-var overrides apply to the selected agent config (env wins): `CTXDB_AGENT` / `CTXDB_ACCESS_TOKEN` / `CTXDB_API_KEY` / `CTXDB_BASE_URL` / `CTXDB_USER_ID` / `CTXDB_AGENT_ID` / `CTXDB_APP_ID`. The internal login command additionally reads `CTXDB_LOGIN_SERVER` as its provider-neutral login endpoint. The last two default to unset — the request body omits `agent_id`/`app_id` entirely; set them only when you want per-agent / per-app scope isolation on the server.
+Env-var overrides apply to the selected agent config (env wins): `CTXDB_AGENT` / `CTXDB_ACCESS_TOKEN` / `CTXDB_API_KEY` / `CTXDB_BASE_URL` / `CTXDB_USER_ID` / `CTXDB_AGENT_ID` / `CTXDB_APP_ID`. The internal login command additionally reads `CTXDB_LOGIN_SERVER` as its provider-neutral login endpoint. The last two default to unset: automatic recall omits both filters, while uploads still send the current Agent name as `agent_id`.
 
 Downstream Agent hosts can set `CTXDB_ACCESS_TOKEN` to send `Authorization: Bearer <token>` to the Data API. It is runtime-only, never written to `~/.ctxdb/ctxdb.json`, and takes precedence over a managed session or API key for CLI, process hooks, and OpenCode; a rejected token does not fall back to another credential. `ctxdb setup` can use a managed reference or an environment AT for validation, but never persists the AT. An environment-only credential must remain available to the Agent runtime after setup.
 
@@ -903,7 +918,7 @@ Two npm packages total. `@aliyunrds/ctxdb-shared` stays separate because OpenCla
 
 ```sh
 # 1. Strip hooks + skills + (optionally) config + logs while the binary still works.
-ctxdb uninstall --purge-all     # everything: hooks, skills, ~/.ctxdb/ctxdb.json, ~/.ctxdb/logs/
+ctxdb uninstall --purge-all     # hooks, skills, and all ctxdb-owned local state
 
 # 2. Then drop the npm binaries.
 npm uninstall -g @aliyunrds/ctxdb @aliyunrds/ctxdb-shared
@@ -911,6 +926,8 @@ npm uninstall -g @aliyunrds/ctxdb @aliyunrds/ctxdb-shared
 
 After step 1, `ctxdb uninstall` prints the exact `npm uninstall` command to run next — copy it from your terminal.
 
+Stop running Agent sessions and transfers before purging. `--purge-all` deletes the shared credential store (public and internal logins), cache, sessions, and Skill state including local drafts. It preserves and reports unknown files. Local deletion does not revoke server sessions: log out of each login before uninstalling if you want to revoke them. Purge flags cannot be combined with `--agent`; that combination fails before changing any files.
+
 ### Partial removal
 
 ```sh
@@ -937,7 +954,8 @@ ctxdb uninstall --purge-logs     # also deletes ~/.ctxdb/logs/
 
 - **Hook entries in `~/.qoder/settings.json`, `~/.qoderwork/settings.json`, `~/.qwenwork/settings.json`, `~/.codex/hooks.json`, `~/.claude/settings.json`, `~/.workbuddy/settings.json`, `~/.workbuddy-ai/settings.json`, and `~/.hermes/config.yaml`**: stripped precisely by marker (`_ctxdb = @aliyunrds/ctxdb`, plus legacy keys `_ctxdbQoder` / `_ctxdbPackage` and the legacy `@aliyunrds/ctxdb-qoder` value for installs predating the unified marker). Any hooks you added yourself stay. A timestamped `*.bak-ctxdb-<TS>` is written before each modification (rotation keeps the 5 most recent).
 - **Skill directories**: `~/.<agent>/skills/ctxdb/` for each set-up agent, plus legacy dirs (`ctxdb-qoder`, `rds-ctxdb-qoder`, `qoder-ctxdb`) under `~/.qoder/skills/` from older package names.
-- **`~/.ctxdb/` state**: only with `--purge-config` / `--purge-logs` / `--purge-all`. Defensive: `--purge-all` removes the `~/.ctxdb/` root only if it's empty after the named files are deleted (won't blanket-rm an unknown directory).
+- **Hermes hook approvals**: removes ctxdb event/command entries from `~/.hermes/shell-hooks-allowlist.json`, preserving other approvals and metadata.
+- **`~/.ctxdb/` state**: only with `--purge-config` / `--purge-logs` / `--purge-all`. Full purge removes `ctxdb.json`, `ctxdb.json.bak`, `credentials.json`, `logs`, `cache`, `circuit`, `sessions`, `skills`, `skill-evolution`, and interrupted config/credential writes. Unknown paths are preserved and listed; the root is removed when empty. Symlink targets are never recursively deleted. Deletion errors return a nonzero exit status and suppress the npm-uninstall hint so the cleanup can be retried.
 - **`~/.codex/config.toml` `[features].hooks`**: **NOT** reverted. Setup adds `hooks = true` so Codex will fire ctxdb's hook entries; uninstall leaves the flag alone because (a) the user may have wanted it on for non-ctxdb hooks, and (b) it's harmless when `~/.codex/hooks.json` is empty. If you want it off, edit the file by hand.
 - **`npm` itself**: never. `ctxdb uninstall` does not call your host package manager — that's the second command above.
 

package/dist/{chunk-LASAMQQY.js → chunk-CA7XEF4X.js}

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import {
+  resolveMemoryUploadAgentId
+} from "./chunk-SR3M7AL5.js";
 import {
   isCircuitOpen,
   isConnectionError,
@@ -117,9 +120,9 @@ async function captureParsedMessages(parsed, cfg, client, agent = "default", ses
   const payload = {
     messages,
     user_id: cfg.userId,
+    agent_id: resolveMemoryUploadAgentId(cfg.agentId, agent),
     async_mode: true
   };
-  if (cfg.agentId) payload.agent_id = cfg.agentId;
   if (cfg.appId) payload.app_id = cfg.appId;
   if (sessionId) payload.run_id = sessionId;
   let resp;

package/dist/{chunk-QUPLZ7KF.js → chunk-G3MDJEX5.js}

@@ -429,7 +429,7 @@ function shouldUseUpdateNotifier(argv, options = {}) {
     return false;
   }
   const command = argv[0];
-  return command !== "update" && command !== "upgrade";
+  return !["update", "upgrade", "uninstall", "teardown"].includes(command);
 }
 function beginUpdateNotification(argv, options) {
   try {

package/dist/chunk-SR3M7AL5.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+// src/lib/memory-upload-agent.ts
+function resolveMemoryUploadAgentId(configuredAgentId, agent = "default") {
+  return configuredAgentId || agent;
+}
+
+export {
+  resolveMemoryUploadAgentId
+};

package/dist/cli/main.js

@@ -3,7 +3,7 @@ import {
   beginUpdateNotification,
   completeUpdateNotification,
   runSelfUpdate
-} from "../chunk-QUPLZ7KF.js";
+} from "../chunk-G3MDJEX5.js";
 import {
   DEFAULT_FILE_INGEST_TIMEOUT_MS,
   DEFAULT_FILE_UPLOAD_TIMEOUT_MS,
@@ -37,6 +37,9 @@ import {
   uploadText,
   validateLocalFile
 } from "../chunk-SZ3AZDMU.js";
+import {
+  resolveMemoryUploadAgentId
+} from "../chunk-SR3M7AL5.js";
 import {
   AGENT_CHOICES,
   CtxdbError,
@@ -441,10 +444,11 @@ import {
   rmSync,
   rmdirSync,
   unlinkSync,
-  statSync
+  statSync,
+  lstatSync
 } from "node:fs";
 import { homedir } from "node:os";
-import { join, dirname, resolve } from "node:path";
+import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { execFileSync } from "node:child_process";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
@@ -842,11 +846,11 @@ async function runSetup(options) {
       return { ok: false, steps };
     }
     try {
-      writeOpencodeShim(absEntry);
+      writeOpencodePlugin(absEntry);
       steps.push({
         step: "install-opencode-shim",
         ok: true,
-        detail: `${opencodeShimPath()} \u2192 ${absEntry}`
+        detail: `${opencodeBundlePath()} \u2190 ${absEntry}`
       });
     } catch (err) {
       steps.push({
@@ -893,8 +897,8 @@ async function runSetup(options) {
   }
   if (ok && agent === "opencode") {
     hints.unshift(
-      `OpenCode plugin shim: ${opencodeShimPath()}`,
-      "Restart OpenCode to load the plugin. `ctxdb upgrade` auto-refreshes the shim after npm updates; only re-run setup if you move ctxdb's install dir."
+      `OpenCode plugin: ${opencodeBundlePath()}`,
+      "Restart OpenCode to load the plugin. Run `ctxdb upgrade --agent opencode` after npm updates to refresh the bundle and migrate older installations."
     );
   }
   if (ok && agent === "hermes") {
@@ -1119,12 +1123,7 @@ function runRemove(agent, options = {}) {
     }
   }
   if (agent === "opencode") {
-    const removed = removeOpencodeShim();
-    steps.push({
-      step: "remove-opencode-shim",
-      ok: true,
-      detail: removed ? opencodeShimPath() : "nothing to remove"
-    });
+    steps.push(...removeOpencodeShim());
     const root = skillInstallRoot(agent);
     const dirs = [
       ...SKILL_DIRS.map((d) => join(root, d)),
@@ -1146,6 +1145,8 @@ function runRemove(agent, options = {}) {
   }
   if (agent === "hermes") {
     try {
+      const removedApprovals = removeHermesHookApprovals();
+      steps.push({ step: "remove-hermes-approvals", ok: true, detail: `removed ${removedApprovals} entries` });
       backupHermesConfig();
       const removed = removeHermesHooksConfig();
       steps.push({
@@ -1250,6 +1251,23 @@ function runTeardown(options = {}) {
   const purgeConfig = Boolean(options.purgeConfig || options.purgeAll);
   const purgeLogs = Boolean(options.purgeLogs || options.purgeAll);
   const purgeRoot = Boolean(options.purgeAll);
+  if (purgeConfig || purgeLogs) {
+    const root = join(homedir(), ".ctxdb");
+    try {
+      const stat = lstatSync(root);
+      if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new Error(`refusing to purge non-directory or symlinked state root: ${root}`);
+      }
+      if (purgeRoot) {
+        const locks = readdirSync(root).filter((name) => name === "ctxdb.json.oauth-config.lock" || /^credentials\.json(?:\.[a-f0-9]{64})?\.lock$/.test(name) || name === ".skill-evolution-budget.lock");
+        if (locks.length) throw new Error(`state is locked; stop related processes before retrying: ${locks.join(", ")}`);
+      }
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        return { ok: false, steps: [{ step: "purge-preflight", ok: false, detail: error.message }] };
+      }
+    }
+  }
   const keepConfigShell = !purgeConfig;
   for (const agent of SUPPORTED_AGENTS) {
     const sub = runRemove(agent, { keepConfigShell });
@@ -1266,46 +1284,35 @@ function runTeardown(options = {}) {
   if (purgeConfig) {
     const cfgPath = join(homedir(), ".ctxdb", "ctxdb.json");
     const ownedConfigFiles = [cfgPath, `${cfgPath}.bak`];
-    const existing = ownedConfigFiles.filter((path) => existsSync(path));
-    if (existing.length === 0) {
+    const start = steps.length;
+    for (const path of ownedConfigFiles) {
+      try {
+        unlinkSync(path);
+        steps.push({ step: "purge-config", ok: true, detail: path });
+      } catch (err) {
+        if (err.code !== "ENOENT") {
+          steps.push({ step: "purge-config", ok: false, detail: `${path}: ${err.message}` });
+        }
+      }
+    }
+    if (steps.length === start) {
       steps.push({
         step: "purge-config",
         ok: true,
         detail: `nothing to remove (${cfgPath})`
       });
-    } else {
-      for (const path of existing) {
-        try {
-          unlinkSync(path);
-          steps.push({ step: "purge-config", ok: true, detail: path });
-        } catch (err) {
-          steps.push({
-            step: "purge-config",
-            ok: false,
-            detail: `${path}: ${err?.message ?? String(err)}`
-          });
-        }
-      }
     }
   }
   if (purgeLogs) {
     const logsDir = join(homedir(), ".ctxdb", "logs");
-    if (existsSync(logsDir)) {
-      try {
-        rmSync(logsDir, { recursive: true, force: true });
-        steps.push({ step: "purge-logs", ok: true, detail: logsDir });
-      } catch (err) {
-        steps.push({
-          step: "purge-logs",
-          ok: false,
-          detail: `${logsDir}: ${err?.message ?? String(err)}`
-        });
-      }
-    } else {
+    try {
+      rmSync(logsDir, { recursive: true, force: true });
+      steps.push({ step: "purge-logs", ok: true, detail: logsDir });
+    } catch (err) {
       steps.push({
         step: "purge-logs",
-        ok: true,
-        detail: `nothing to remove (${logsDir})`
+        ok: false,
+        detail: `${logsDir}: ${err?.message ?? String(err)}`
       });
     }
   }
@@ -1313,6 +1320,25 @@ function runTeardown(options = {}) {
     const root = join(homedir(), ".ctxdb");
     if (existsSync(root)) {
       try {
+        const ownedState = /* @__PURE__ */ new Set([
+          "credentials.json",
+          "cache",
+          "circuit",
+          "sessions",
+          "skills",
+          "skill-evolution"
+        ]);
+        for (const name of readdirSync(root)) {
+          const interruptedWrite = /^(?:ctxdb|credentials)\.json\.[a-f0-9]{24}\.tmp$/.test(name);
+          if (!ownedState.has(name) && !interruptedWrite) continue;
+          const path = join(root, name);
+          try {
+            rmSync(path, { recursive: true, force: true });
+            steps.push({ step: "purge-state", ok: true, detail: path });
+          } catch (error) {
+            steps.push({ step: "purge-state", ok: false, detail: `${path}: ${error.message}` });
+          }
+        }
         const remaining = readdirSync(root);
         if (remaining.length === 0) {
           rmdirSync(root);
@@ -1321,7 +1347,7 @@ function runTeardown(options = {}) {
           steps.push({
             step: "purge-root",
             ok: true,
-            detail: `kept (not empty): ${remaining.join(", ")}`
+            detail: `kept (not empty); preserved paths: ${remaining.join(", ")}`
           });
         }
       } catch (err) {
@@ -1347,7 +1373,7 @@ function verifyNodeBinary(nodePath) {
   }
 }
 function checkHookNodePaths(agent) {
-  if (agent === "opencode") return checkOpencodeShimHealth();
+  if (agent === "opencode") return checkOpencodePluginHealth();
   if (agent === "hermes") return checkHermesHookHealth();
   const empty = {
     installed: false,
@@ -1419,51 +1445,35 @@ function checkHookNodePaths(agent) {
   }
   return { installed: true, nodePaths: paths, nodeOk: true, detail: `${paths[0]} (${goodVersion})` };
 }
-function checkOpencodeShimHealth() {
-  const path = opencodeShimPath();
-  if (!existsSync(path)) {
-    return {
-      installed: false,
-      nodePaths: [],
-      nodeOk: false,
-      detail: `opencode shim not installed \u2014 run \`ctxdb setup --agent opencode\``
-    };
-  }
-  let text = "";
-  try {
-    text = readFileSync(path, "utf-8");
-  } catch (err) {
+function checkOpencodePluginHealth() {
+  const path = opencodeBundlePath();
+  if (existsSync(opencodeShimPath())) {
     return {
       installed: true,
-      nodePaths: [],
+      nodePaths: [path],
       nodeOk: false,
-      detail: `opencode shim unreadable: ${err?.message ?? String(err)}`
+      detail: "opencode legacy shim requires migration \u2014 run `ctxdb upgrade --agent opencode` and restart OpenCode"
     };
   }
-  const target = text.match(/export\s+\{\s*default\s*\}\s+from\s+["']([^"']+)["'];/)?.[1];
-  if (!target) {
+  if (!existsSync(path)) {
     return {
-      installed: true,
+      installed: false,
       nodePaths: [],
       nodeOk: false,
-      detail: `opencode shim malformed: ${path} \u2014 re-run \`ctxdb setup --agent opencode\``
+      detail: "opencode plugin not installed \u2014 run `ctxdb setup --agent opencode`"
     };
   }
-  const targetPath = target.startsWith("file:") ? fileURLToPath(target) : resolve(dirname(path), target);
-  if (!existsSync(targetPath)) {
+  try {
+    if (!readFileSync(path, "utf-8").trim()) throw new Error("empty bundle");
+  } catch (err) {
     return {
       installed: true,
-      nodePaths: [targetPath],
+      nodePaths: [path],
       nodeOk: false,
-      detail: `opencode shim target missing: ${targetPath} \u2014 re-run \`ctxdb setup --agent opencode\``
+      detail: `opencode plugin unreadable: ${err?.message ?? String(err)} \u2014 re-run \`ctxdb setup --agent opencode\``
     };
   }
-  return {
-    installed: true,
-    nodePaths: [targetPath],
-    nodeOk: true,
-    detail: `opencode shim: ${path} \u2192 ${targetPath}`
-  };
+  return { installed: true, nodePaths: [path], nodeOk: true, detail: `opencode plugin: ${path}` };
 }
 var SETTINGS_BACKUP_KEEP = 5;
 function backupSettingsFile(path) {
@@ -1709,36 +1719,35 @@ function resolveOpencodePluginEntry() {
   const here = dirname(fileURLToPath(import.meta.url));
   const pkgRoot = walkUpToPackageJson(here, CTXDB_PACKAGE_NAMES);
   if (!pkgRoot) return null;
-  const candidates = [
-    join(pkgRoot, "dist", "opencode", "index.js"),
-    join(pkgRoot, "..", "opencode", "src", "index.ts")
-  ];
-  return candidates.find((candidate) => existsSync(candidate)) ?? null;
+  const candidate = join(pkgRoot, "dist", "opencode", "index.js");
+  return existsSync(candidate) ? candidate : null;
 }
-var OPENCODE_SHIM_HEADER = "// Generated by ctxdb setup --agent opencode. Do not edit by hand.\n// To refresh after moving ctxdb's install directory, run ctxdb upgrade --agent opencode or re-run setup.\n// To remove, run: ctxdb setup --remove --agent opencode\n";
-function writeOpencodeShim(absEntry) {
+var OPENCODE_GENERATED_HEADER = "// Generated by ctxdb setup --agent opencode.";
+function writeOpencodePlugin(absEntry) {
   const shimPath = opencodeShimPath();
   const bundlePath = opencodeBundlePath();
-  mkdirSync(dirname(shimPath), { recursive: true });
+  mkdirSync(dirname(bundlePath), { recursive: true });
+  if (existsSync(shimPath) && !readFileSync(shimPath, "utf-8").startsWith(OPENCODE_GENERATED_HEADER)) {
+    throw new Error(`Cannot migrate unrecognized OpenCode entry ${shimPath}; move it out of plugins/ before running setup again.`);
+  }
   copyFileSync(absEntry, bundlePath);
-  const importSpec = "./" + OPENCODE_BUNDLE_FILENAME;
-  const body = `${OPENCODE_SHIM_HEADER}export { default } from ${JSON.stringify(importSpec)};
-`;
-  writeFileSync(shimPath, body, "utf-8");
+  if (existsSync(shimPath)) unlinkSync(shimPath);
 }
 function removeOpencodeShim() {
   const shimPath = opencodeShimPath();
   const bundlePath = opencodeBundlePath();
-  let removed = false;
+  const steps = [];
   for (const p of [shimPath, bundlePath]) {
-    if (!existsSync(p)) continue;
     try {
       unlinkSync(p);
-      removed = true;
-    } catch {
+      steps.push({ step: "remove-opencode-shim", ok: true, detail: p });
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        steps.push({ step: "remove-opencode-shim", ok: false, detail: `${p}: ${error.message}` });
+      }
     }
   }
-  return removed;
+  return steps.length ? steps : [{ step: "remove-opencode-shim", ok: true, detail: "nothing to remove" }];
 }
 var ENTRY_MARKER_KEY = "_ctxdb";
 var ENTRY_MARKER_VALUE = "@aliyunrds/ctxdb";
@@ -1926,6 +1935,23 @@ function removeHermesHooksConfig() {
   if (removed > 0) writeHermesConfig(data);
   return removed;
 }
+function removeHermesHookApprovals() {
+  const path = hermesAllowlistPath();
+  if (!existsSync(path)) return 0;
+  const data = JSON.parse(readFileSync(path, "utf8"));
+  if (!Array.isArray(data?.approvals)) throw new Error(`${path}: expected an approvals array`);
+  const entries = hermesCtxdbEntriesByEvent(readHermesConfig());
+  const approvals = data.approvals.filter((approval) => {
+    if (!approval || !HERMES_HOOK_EVENTS.includes(approval.event) || typeof approval.command !== "string") return true;
+    const configured = entries.get(approval.event)?.some((entry) => entry.command === approval.command);
+    const hook = approval.event === HERMES_PRE_LLM_CALL_EVENT ? "pre" : "post";
+    const generated = new RegExp(`^'[^']+' '[^']*[/\\\\]hermes-${hook}-llm-call\\.(?:js|ts)' --agent=hermes$`).test(approval.command);
+    return !configured && !generated;
+  });
+  const removed = data.approvals.length - approvals.length;
+  if (removed) writeFileSync(path, JSON.stringify({ ...data, approvals }, null, 2) + "\n", "utf8");
+  return removed;
+}
 function firstCommandToken(command) {
   const s = command.trim();
   if (!s) return null;
@@ -2574,10 +2600,12 @@ FLAGS
   --agent <name>   Target a single agent (${SUPPORTED_AGENT_CHOICES})
   --purge-config   Also delete ~/.ctxdb/ctxdb.json
   --purge-logs     Also delete ~/.ctxdb/logs/
-  --purge-all      Delete everything under ~/.ctxdb/
+  --purge-all      Delete ctxdb-owned state under ~/.ctxdb/; preserve unknown files
   --json           Machine-readable JSON output
 
 NOTE
+  Purge flags cannot be combined with --agent. Local removal does not revoke
+  server sessions; log out of each login before uninstalling to revoke them.
   Does not run \`npm uninstall\`. After uninstall completes, remove the
   npm package separately: npm uninstall -g ${PACKAGE_UNINSTALL_TARGETS2}
 `;
@@ -2589,6 +2617,10 @@ function uninstall(args) {
   const json = !!args.flags.json;
   const agentFlag = args.flags.agent;
   if (agentFlag !== void 0) {
+    if (["purge-config", "purge-logs", "purge-all"].some((flag) => args.flags[flag])) {
+      printResult({ ok: false, error: "--agent cannot be combined with --purge-config, --purge-logs, or --purge-all" }, json, "uninstall");
+      return 2;
+    }
     if (!isAgentSlug(agentFlag)) {
       process.stderr.write(
         `unknown --agent: ${String(agentFlag)} (expected one of ${SUPPORTED_AGENTS.join(" / ")} / default)
@@ -2796,7 +2828,7 @@ import { join as join3, win32 } from "node:path";
 import { existsSync as existsSync3 } from "node:fs";
 
 // src/skills/status.ts
-import { existsSync as existsSync2, readdirSync as readdirSync2, lstatSync } from "node:fs";
+import { existsSync as existsSync2, readdirSync as readdirSync2, lstatSync as lstatSync2 } from "node:fs";
 import "node:path";
 function statusBindings(root, agent) {
   const dir = privatePath(root, "sessions", "bindings");
@@ -2867,7 +2899,7 @@ function localSkillStatus(bound, root) {
   const manifestPath = path(skills, "manifest.json");
   const snapshot = existsSync2(manifestPath) ? readState(root, manifestPath) : void 0;
   const drafts = list(path(skills, "drafts")).flatMap((name) => {
-    if (!lstatSync(path(skills, "drafts", name)).isDirectory()) return [];
+    if (!lstatSync2(path(skills, "drafts", name)).isDirectory()) return [];
     const direct = path(skills, "drafts", name, "SKILL.md"), bundle = path(skills, "drafts", name, "bundle", "SKILL.md");
     return [direct, bundle].filter((file) => existsSync2(file));
   });
@@ -3845,6 +3877,7 @@ ${usage2}`, 2);
   const images = imageFlags.length > 0 ? await Promise.all(imageFlags.map((value2) => loadImagePart(value2, usage2))) : [];
   const ctx = buildContext(args);
   const userId = args.flags["user-id"] ?? ctx.cfg.userId;
+  const agentId = resolveMemoryUploadAgentId(ctx.cfg.agentId, ctx.agent);
   const metadata = parseMetadataFlags(args.flags["metadata"]);
   if (images.length > 0) {
     const message = {
@@ -3855,6 +3888,7 @@ ${usage2}`, 2);
     const request = {
       messages: [message],
       user_id: userId,
+      agent_id: agentId,
       infer: true
     };
     if (Object.keys(metadata).length > 0) request.metadata = metadata;
@@ -3879,6 +3913,7 @@ ${usage2}`, 2);
   const body = {
     messages: [{ role: "user", content: text }],
     user_id: userId,
+    agent_id: agentId,
     async_mode: false
   };
   if (Object.keys(metadata).length > 0) body.metadata = metadata;
@@ -6115,12 +6150,14 @@ function topLevelCommands(managedCredentials) {
           }),
           option("--purge-config", "Also delete ~/.ctxdb/ctxdb.json.", { type: "boolean" }),
           option("--purge-logs", "Also delete ~/.ctxdb/logs/.", { type: "boolean" }),
-          option("--purge-all", "Delete everything under ~/.ctxdb/.", { type: "boolean" }),
+          option("--purge-all", "Delete ctxdb-owned local state under ~/.ctxdb/; preserve unknown files.", { type: "boolean" }),
           JSON_OPTION
         ],
         warnings: [
           "Without --agent, ctxdb-owned hooks and Skills are removed for every supported Agent.",
-          "--purge-all deletes all ctxdb configuration, credentials, logs, and cache under ~/.ctxdb/.",
+          "--purge-all deletes ctxdb configuration, shared credentials, logs, cache, sessions, and Skill state (including drafts) under ~/.ctxdb/; unknown files are preserved and reported.",
+          "Purge flags cannot be combined with --agent. Stop running Agent sessions and transfers before purging.",
+          "Local removal does not revoke server sessions; log out of each login before uninstalling to revoke them.",
           "This command does not remove the npm package."
         ],
         examples: [
@@ -6616,7 +6653,10 @@ var memoryGroup = group("memory", "Store, retrieve, update, and promote memories
       AGENT_OPTION,
       JSON_OPTION
     ],
-    constraints: ["At least text or one --image is required."],
+    constraints: [
+      "At least text or one --image is required.",
+      "Uploads include agent_id: CTXDB_AGENT_ID overrides configured agent_id; otherwise the selected --agent / CTXDB_AGENT / default is used. This does not add a default search filter."
+    ],
     examples: [
       { command: "ctxdb memory add <text> --no-infer --json" },
       { command: "ctxdb memory add --image=<image-path> --agent=codex" }

package/dist/hooks/hermes-post-llm-call.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import {
   captureParsedMessages
-} from "../chunk-LASAMQQY.js";
+} from "../chunk-CA7XEF4X.js";
+import "../chunk-SR3M7AL5.js";
 import "../chunk-XWJAZAMN.js";
 import {
   HttpClient,

package/dist/hooks/stop.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import {
   captureTurn
-} from "../chunk-LASAMQQY.js";
+} from "../chunk-CA7XEF4X.js";
+import "../chunk-SR3M7AL5.js";
 import "../chunk-XWJAZAMN.js";
 import {
   HttpClient,

package/dist/opencode/index.js

@@ -23403,6 +23403,14 @@ function buildWarmupQuery(cwd, git) {
 // src/capture.ts
 init_define_CTXDB_DISTRIBUTION_MANIFEST();
 import { createHash as createHash5 } from "crypto";
+
+// ../ctxdb/src/lib/memory-upload-agent.ts
+init_define_CTXDB_DISTRIBUTION_MANIFEST();
+function resolveMemoryUploadAgentId(configuredAgentId, agent = "default") {
+  return configuredAgentId || agent;
+}
+
+// src/capture.ts
 var EMPTY2 = {
   captured: false,
   reason: "",
@@ -23500,9 +23508,9 @@ async function runCapture(messages, cfg, client, timeoutMs, lastFingerprint, ses
   const payload = {
     messages: filtered,
     user_id: cfg.userId,
+    agent_id: resolveMemoryUploadAgentId(cfg.agentId, "opencode"),
     async_mode: true
   };
-  if (cfg.agentId) payload.agent_id = cfg.agentId;
   if (cfg.appId) payload.app_id = cfg.appId;
   if (sessionId) payload.run_id = sessionId;
   let resp;
@@ -23566,12 +23574,12 @@ function touchSession(rt, sessionID) {
 function pruneSessions(state) {
   const now = Date.now();
   for (const [id, s] of state) {
-    if (now - s.touched > SESSION_TTL_MS) state.delete(id);
+    if (!s.idleTask && now - s.touched > SESSION_TTL_MS) state.delete(id);
   }
   if (state.size > SESSION_MAX) {
     const overflow = state.size - SESSION_MAX;
-    const sorted = [...state.entries()].sort((a, b) => a[1].touched - b[1].touched);
-    for (let i = 0; i < overflow; i++) state.delete(sorted[i][0]);
+    const sorted = [...state.entries()].filter(([, s]) => !s.idleTask).sort((a, b) => a[1].touched - b[1].touched);
+    for (let i = 0; i < Math.min(overflow, sorted.length); i++) state.delete(sorted[i][0]);
   }
 }
 function extractTextPrompt(parts) {
@@ -23684,59 +23692,17 @@ async function buildHooks(input) {
         const sessionID = ev.properties?.sessionID;
         if (!sessionID) return;
         const state = touchSession(rt, sessionID);
-        let messages;
-        try {
-          const data = await withTimeout(
-            input.client.session.messages({
-              path: { id: sessionID },
-              // Skill evidence needs the whole paired turn; a 24-message tail can lose the user goal/calls.
-              query: {},
-              throwOnError: true
-            }),
-            CAPTURE_TIMEOUT_MS,
-            "session.messages"
-          );
-          messages = unwrapSessionMessagesResponse(data);
-        } catch (err) {
-          logError(rt.config, "event.fetchMessages", err);
-          return;
-        }
-        if (messages.length === 0) return;
+        const task = (state.idleTask ?? Promise.resolve()).catch(() => {
+        }).then(() => captureIdle(input, rt, state, sessionID));
+        state.idleTask = task;
         try {
-          const binding = sessionBinding(sessionID, void 0, "opencode");
-          const latest = [...messages].reverse().find((m) => m.info?.role === "assistant");
-          if (latest?.info?.time?.completed && !latest.info.error && latest.info.finish === "stop") {
-            const usableTurns = new Set(messages.filter((m) => m.info?.role === "assistant" && m.info.time?.completed && !m.info.error && m.info.finish === "stop").map((m) => m.info.parentID));
-            const usable = messages.filter((m) => {
-              const turn = m.info?.role === "user" ? m.info.id : m.info?.parentID;
-              return turn !== void 0 && usableTurns.has(turn);
-            });
-            const answer = (latest.parts ?? []).filter((p) => p.type === "text" && !p.synthetic && !p.ignored).map((p) => p.text).join("\n");
-            await skillStopRows(binding, usable, { last_assistant_message: answer, turn_id: latest.info.parentID }, null);
+          await task;
+        } finally {
+          if (state.idleTask === task) {
+            state.idleTask = void 0;
+            state.touched = Date.now();
           }
-        } catch {
-          logError(rt.config, "skill.checkpoint", new Error("skill_checkpoint_unavailable"));
-        }
-        if (!rt.config.autoCapture) return;
-        const outcome = await runCapture(
-          messages,
-          rt.config,
-          rt.http,
-          CAPTURE_TIMEOUT_MS,
-          state.lastFingerprint,
-          sessionID
-        );
-        if (outcome.captured && outcome.fingerprint) {
-          state.lastFingerprint = outcome.fingerprint;
         }
-        if (!outcome.captured && outcome.reason.startsWith("http_error:")) {
-          logError(rt.config, "event.capture", new Error(outcome.reason));
-        }
-        logDebug(
-          rt.config,
-          "event.capture",
-          `sessionID=${sessionID} captured=${outcome.captured} reason=${outcome.reason} count=${outcome.messageCount}`
-        );
       } catch (err) {
         logError(rt.config, "event", err);
       }
@@ -23744,6 +23710,61 @@ async function buildHooks(input) {
   };
   return hooks;
 }
+async function captureIdle(input, rt, state, sessionID) {
+  let messages;
+  try {
+    const data = await withTimeout(
+      input.client.session.messages({
+        path: { id: sessionID },
+        // Skill evidence needs the whole paired turn; a 24-message tail can lose the user goal/calls.
+        query: {},
+        throwOnError: true
+      }),
+      CAPTURE_TIMEOUT_MS,
+      "session.messages"
+    );
+    messages = unwrapSessionMessagesResponse(data);
+  } catch (err) {
+    logError(rt.config, "event.fetchMessages", err);
+    return;
+  }
+  if (messages.length === 0) return;
+  try {
+    const binding = sessionBinding(sessionID, void 0, "opencode");
+    const latest = [...messages].reverse().find((m) => m.info?.role === "assistant");
+    if (latest?.info?.time?.completed && !latest.info.error && latest.info.finish === "stop") {
+      const usableTurns = new Set(messages.filter((m) => m.info?.role === "assistant" && m.info.time?.completed && !m.info.error && m.info.finish === "stop").map((m) => m.info.parentID));
+      const usable = messages.filter((m) => {
+        const turn = m.info?.role === "user" ? m.info.id : m.info?.parentID;
+        return turn !== void 0 && usableTurns.has(turn);
+      });
+      const answer = (latest.parts ?? []).filter((p) => p.type === "text" && !p.synthetic && !p.ignored).map((p) => p.text).join("\n");
+      await skillStopRows(binding, usable, { last_assistant_message: answer, turn_id: latest.info.parentID }, null);
+    }
+  } catch {
+    logError(rt.config, "skill.checkpoint", new Error("skill_checkpoint_unavailable"));
+  }
+  if (!rt.config.autoCapture) return;
+  const outcome = await runCapture(
+    messages,
+    rt.config,
+    rt.http,
+    CAPTURE_TIMEOUT_MS,
+    state.lastFingerprint,
+    sessionID
+  );
+  if (outcome.captured && outcome.fingerprint) {
+    state.lastFingerprint = outcome.fingerprint;
+  }
+  if (!outcome.captured && outcome.reason.startsWith("http_error:")) {
+    logError(rt.config, "event.capture", new Error(outcome.reason));
+  }
+  logDebug(
+    rt.config,
+    "event.capture",
+    `sessionID=${sessionID} captured=${outcome.captured} reason=${outcome.reason} count=${outcome.messageCount}`
+  );
+}
 async function searchAndLogRecall(scope, kind, query, sessionId, rt) {
   const result = await searchAndFormatRecall(
     query,

package/dist/workers/version-check.js

@@ -4,7 +4,7 @@ import {
   recordVersionCheckFailure,
   recordVersionCheckSuccess,
   releaseVersionCheckLock
-} from "../chunk-QUPLZ7KF.js";
+} from "../chunk-G3MDJEX5.js";
 import "../chunk-5ITT5GSP.js";
 import "../chunk-PI2SUS3M.js";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliyunrds/ctxdb",
-  "version": "1.0.10",
+  "version": "1.0.11-beta.1",
   "type": "module",
   "description": "Unified access layer for RDS ContextDatabase: `ctxdb` CLI (memory + KB ops), one-shot multi-agent installer, per-agent config, hooks/plugins, and SKILL.md.",
   "license": "Apache-2.0",