@tachikomagundam/abathur 0.2.1 → 0.2.3

package/README.md

@@ -139,8 +139,14 @@ abathur run --genome toy-smoke --dry-run     # plan + requires[] probes, zero sp
 ### Inside opencode
 
 Abathur ships an official opencode plugin adapter. The harness remains the
-orchestrator, but once installed an opencode session can also drive the CLI
-directly:
+orchestrator, but once set up an opencode session can also drive the CLI
+directly. Two install routes:
+
+Both routes deliver the tool **and** the `/abathur` slash command; pick by
+taste — A needs no edit of your opencode config and works fully offline, B
+needs no file copying and removes with one deleted line.
+
+**Route A — one command (file-copy installer).**
 
 ```bash
 npm i -g @tachikomagundam/abathur
@@ -148,7 +154,27 @@ abathur opencode install    # copies plugin assets into ~/.config/opencode/
 # restart opencode
 ```
 
-After a restart the session gets two things:
+**Route B — config only (auto-downloaded from npm).** Put the package name in
+your opencode config and restart:
+
+```jsonc
+{ "plugin": ["@tachikomagundam/abathur"] }
+```
+
+opencode then downloads the package from npm at startup into its own cache
+(`~/.cache/opencode/packages/…`) and loads the package's `./server` export —
+no file copying, no uninstall step (delete the line). Since 0.2.3 the plugin
+also self-registers `/abathur` through its `config` hook: slash commands are
+entries in the merged config's `command` map, and a plugin may add one there
+— the upstream `opencode-acp` plugin registers `/acp` the same way (the
+0.2.0–0.2.2 note here claiming plugins cannot register slash commands was
+wrong; corrected). If Route A's copied `commands/abathur.md` exists it stays
+authoritative — the injection never overwrites it, and the name-keyed command
+map means `/abathur` can never appear twice. One honest limit stands for both
+routes: the tool spawns the `abathur` **CLI**, which must exist on `PATH` (or
+via `ABATHUR_BIN`) — keep the `npm i -g` install.
+
+Either route gives the session:
 
 - the agent tool **`abathur`** — spawns the `abathur` CLI argv-only (never a
   shell), restricted to eight commands (`genome`, `run`, `status`, `bundle`,
@@ -161,9 +187,12 @@ After a restart the session gets two things:
   human gates and must be run in a terminal.
 - the user command **`/abathur <args…>`** — a slash command that tells the
   agent to translate its arguments into a tool call and report the exit code.
+  Route A provides it as the copied `commands/abathur.md` file; Route B gets
+  it from the plugin's `config` hook at startup.
 
-`abathur opencode status` shows each target's path, installed/packaged sha256,
-and state (up-to-date / outdated / foreign / absent).
+Route A ships its own manager commands: `abathur opencode status` shows each
+target's path, installed/packaged sha256, and state (up-to-date / outdated /
+foreign / absent).
 `abathur opencode uninstall` removes only files carrying the abathur marker; a
 foreign file at a target path makes both commands refuse with exit 2 and name
 the path — nothing is ever overwritten or deleted behind your back (there is
@@ -408,8 +437,13 @@ abathur run --genome toy-smoke --dry-run     # 计划 + requires[] 探针，零
 
 ### 在 opencode 里调用
 
-Abathur 自带官方 opencode 插件适配器。工装仍是编排者，但安装之后，opencode
-会话也可以直接驱动 CLI：
+Abathur 自带官方 opencode 插件适配器。工装仍是编排者，但配置之后，opencode
+会话也可以直接驱动 CLI。安装有两条路线：
+
+两条路线都交付工具**和** `/abathur` 斜杠命令，按喜好挑选：A 不必改动你的
+opencode 配置、且完全离线可用；B 不复制任何文件、删掉一行即卸载。
+
+**路线 A——一条命令（文件复制安装器）。**
 
 ```bash
 npm i -g @tachikomagundam/abathur
@@ -417,7 +451,25 @@ abathur opencode install    # 把插件资产复制进 ~/.config/opencode/
 # 重启 opencode
 ```
 
-重启后会话获得两样东西：
+**路线 B——纯配置（自动从 npm 下载）。** 把包名写进 opencode 配置再
+重启：
+
+```jsonc
+{ "plugin": ["@tachikomagundam/abathur"] }
+```
+
+opencode 会在启动时自行从 npm 把包下载到它自己的缓存
+（`~/.cache/opencode/packages/…`）并加载该包的 `./server` 导出——不复制文件，
+也没有 uninstall 步骤（删掉那行即可）。自 0.2.3 起，插件还会通过它的
+`config` 钩子自注册 `/abathur`：斜杠命令本质是合并后配置的 `command`
+映射里的条目，插件可以在钩子里添加一条——上游的 `opencode-acp` 插件正是
+这样注册 `/acp` 的（0.2.0–0.2.2 在此声称"插件无法注册斜杠命令"是错的，
+已更正）。若路线 A 复制的 `commands/abathur.md` 存在，它保持权威——注入
+绝不覆盖它，而且命令映射按名字键控，`/abathur` 绝不会出现两份。对两条
+路线同样成立的一个诚实限制：工具 spawn 的是 `abathur` **CLI**，CLI 必须
+在 `PATH`（或 `ABATHUR_BIN`）上可达，`npm i -g` 不能省。
+
+任一路线都会让会话获得：
 
 - 智能体工具 **`abathur`**——以纯 argv 方式 spawn `abathur` CLI（绝不经过
   shell），顶层命令限定为八个（`genome`、`run`、`status`、`bundle`、`graft`、
@@ -426,10 +478,12 @@ abathur opencode install    # 把插件资产复制进 ~/.config/opencode/
   bash 等同的权限——`run` 与 `genome` 按设计就会 spawn 变异器/引擎二进制——
   所以允许清单限制的是笔误与体验，而非能力。`promote` 与 `tombstone` 刻意
   不可经由工具触达：它们是人类闸门，必须在终端里运行。
-- 用户命令 **`/abathur <参数…>`**——斜杠命令，指示智能体把参数翻译成工具调用
-  并回报退出码。
+- 用户命令 **`/abathur <参数…>`**——斜杠命令，指示智能体把参数
+  翻译成工具调用并回报退出码。路线 A 由复制的 `commands/abathur.md`
+  文件提供；路线 B 由插件的 `config` 钩子在启动时注册。
 
-`abathur opencode status` 逐目标打印路径、已安装/随包 sha256 与状态
+路线 A 自带管理命令：`abathur opencode status` 逐目标打印路径、已安装/随包
+sha256 与状态
 （up-to-date / outdated / foreign / absent）。
 `abathur opencode uninstall` 只删除带有 abathur 标记的文件；若目标路径上躺着
 别人的文件，两条命令都会 exit 2 并点名路径——绝不会背着你覆盖或删除任何东西

package/dist/test/bench-fixture.test.js

@@ -62,9 +62,13 @@ fi
 echo "ran $unit"
 echo '{"tokensEst":123,"turns":4}'
 `;
+// Unique sleep duration: node --test runs files concurrently and this test's
+// orphan check scans the whole machine's `ps` output — "sleep 31.7" is the
+// shipped toy genome's hang marker (bench-toy.test.ts); reusing it here made
+// the two files' checks see each other's live sleeps (CI-verified 5/5 collision).
 const BIN_HANG = `#!/usr/bin/env bash
 if [ "\${1:-}" = "--version" ]; then echo "1.2.3"; exit 0; fi
-exec sleep 31.7
+exec sleep 29.31
 `;
 const BIN_NO_VERSION = `#!/usr/bin/env bash
 if [ "\${1:-}" = "--version" ]; then echo "unsupported flag" >&2; exit 1; fi
@@ -296,7 +300,7 @@ test("(E) hanging unit: group kill at timeoutS, zero orphans", async (t) => {
     assert.equal(run.exitCode, null);
     assert.match(run.note ?? "", /killed after 1s: process group SIGKILL/);
     const ps = spawnSync("ps", ["-eo", "args"], { encoding: "utf8" });
-    assert.ok(!ps.stdout.includes("sleep 31.7"), "orphaned sleep survived the group kill");
+    assert.ok(!ps.stdout.includes("sleep 29.31"), "orphaned sleep survived the group kill");
 });
 // ------------------------------------------------------------------ AC (F)
 test("(F) infra_failed is recorded with a distinct status/note, never a silent 0", async (t) => {

package/dist/test/opencode.test.js

@@ -241,6 +241,27 @@ test("plugin/abathur.ts: V1 shape — marker, default {id, server}, tool allowli
     assert.ok(!/shell\s*:\s*true/.test(bytes), "shell:true is banned");
     assert.ok(bytes.includes("ABATHUR_BIN"), "bin overridable via ABATHUR_BIN");
 });
+test("plugin/abathur.ts: config hook self-registers /abathur — template byte-mirrors the command md body", async () => {
+    const bytes = await readFile(pluginAssetPath, "utf8");
+    // Route B needs the config hook: opencode hands plugins the fully-merged config
+    // (file commands already inside cfg.command), so a `??=` injection registers
+    // /abathur ONLY when no commands/abathur.md exists — Route A bytes/behaviour
+    // stay untouched and the name-keyed command map guarantees no duplicate entry.
+    assert.ok(/config:\s*async\s*\(cfg:\s*Config\)/.test(bytes), "config hook with typed cfg required");
+    assert.ok(bytes.includes('import { tool, type Config }'), "Config type imported from @opencode-ai/plugin");
+    assert.ok(/cfg\.command\s*\?\?=\s*\{\}/.test(bytes), "cfg.command must be lazily created with ??=");
+    assert.ok(/cfg\.command\.abathur\s*\?\?=/.test(bytes), "entry must be ??= — a file-installed command is never overwritten");
+    assert.ok(bytes.includes('description: "Drive the abathur evolution harness (usage: /abathur <command> [args...])"'), "injected description must be pinned verbatim");
+    // Extract the template literal (inner backticks appear escaped as \`) and byte-compare.
+    const literal = bytes.match(/const COMMAND_TEMPLATE = `((?:[^`\\]|\\.)*)`;/);
+    assert.ok(literal !== null, "COMMAND_TEMPLATE literal must exist");
+    const template = (literal[1] ?? "").replaceAll("\\`", "`");
+    const md = await readFile(commandAssetPath, "utf8");
+    assert.ok(md.startsWith(COMMAND_MARKER), "md must still carry its first-line marker");
+    const body = md.slice(md.indexOf("\n") + 1); // everything after the marker line
+    assert.ok(body.startsWith("Drive the abathur evolution harness"), "body start sanity");
+    assert.equal(template, body, "injected template must byte-equal the command md minus its marker line");
+});
 test("plugin/abathur-command.md: first-line marker, $ARGUMENTS, points at the abathur tool", async () => {
     const text = await readFile(commandAssetPath, "utf8");
     assert.equal(text.split("\n")[0], COMMAND_MARKER, "first line must be the command marker");
@@ -255,6 +276,26 @@ test("shipped plugin assets carry zero machine literals (D7 discipline extended
         }
     }
 });
+test("npm name route: exports['./server'] ships the marker'd plugin + runtime dep declared", async () => {
+    const pkg = JSON.parse(await readFile(path.join(repoRoot, "package.json"), "utf8"));
+    // opencode picks the server entry via exports["./server"] (extractExportValue
+    // accepts a plain string; plugin/shared.ts resolvePackageEntrypoint).
+    const serverEntry = pkg.exports?.["./server"];
+    assert.equal(typeof serverEntry, "string", "./server export must be a plain string path");
+    const server = serverEntry;
+    const target = path.resolve(repoRoot, server);
+    const head = (await readFile(target, "utf8")).split("\n")[0] ?? "";
+    assert.ok(head.startsWith(PLUGIN_MARKER), `server entry must start with the plugin marker: ${head}`);
+    // The tarball must actually contain that file or the name route installs nothing to import.
+    assert.ok((pkg.files ?? []).some((entry) => server.startsWith(`./${entry}/`)), "server entry must live under a published files[] directory");
+    // Arborist installs the package's dependencies next to it in opencode's cache —
+    // that sibling copy is how the shipped import of @opencode-ai/plugin resolves (OMO mechanism).
+    const dep = pkg.dependencies?.["@opencode-ai/plugin"];
+    assert.equal(typeof dep, "string", "@opencode-ai/plugin must be a runtime dependency");
+    assert.ok((dep ?? "").length > 0, "dependency range must not be empty");
+    // Route B must serve the same bytes the route A installer copies: both resolve to plugin/abathur.ts.
+    assert.equal(serverEntry, "./plugin/abathur.ts", "server entry and installer asset must be one file");
+});
 test("CLI help: opencode is a registered top-level command", async (t) => {
     const { env } = await makeEnv(t);
     const help = abathur(env, "--help");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tachikomagundam/abathur",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Evolution harness: observe failures, mutate, re-bench, select — human-gated promotion, offline lineage bundles.",
   "author": "TachikomaGundam",
   "type": "module",
@@ -20,6 +20,11 @@
     "abathur": "dist/cli.js"
   },
   "main": "dist/cli.js",
+  "exports": {
+    ".": "./dist/cli.js",
+    "./server": "./plugin/abathur.ts",
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist",
     "config",
@@ -33,6 +38,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
+    "@opencode-ai/plugin": "^1.17.4",
     "zod": "^4.0.0"
   },
   "devDependencies": {

package/plugin/abathur.ts

@@ -1,4 +1,4 @@
-// abathur-opencode-plugin v0.2.1
+// abathur-opencode-plugin v0.2.3
 // Official opencode plugin adapter for the abathur evolution harness.
 // Registers ONE agent tool, `abathur`, that shells out to the abathur CLI —
 // argv-only (node:child_process execFile, never a shell), top-level commands
@@ -8,13 +8,20 @@
 // V1 plugin format (opencode >= 1.14): default export { id, server }, where
 // server(input, options) resolves to Hooks; Hooks.tool is a
 // { [name]: ToolDefinition } record (see @opencode-ai/plugin).
-// This file is shipped as-is (package.json "files") and copied into
-// ~/.config/opencode/plugins/ by `abathur opencode install`. It is NOT
-// compiled by abathur's tsc; "@opencode-ai/plugin" resolves inside opencode's
-// own config-directory install.
+// This file is shipped as-is (package.json "files") and reaches a session by
+// two routes, neither compiling it through abathur's tsc. Both deliver the
+// tool AND the /abathur slash command:
+// (A) copied into ~/.config/opencode/plugins/ by `abathur opencode install`,
+//     which also drops commands/abathur.md; "@opencode-ai/plugin" then
+//     resolves in opencode's config-directory node_modules.
+// (B) served as the package's "./server" export when the npm package name is
+//     listed in opencode.jsonc "plugin" — opencode's arborist install places
+//     @opencode-ai/plugin (runtime dependency) next to the package in its
+//     cache, so the same import resolves there too; with no commands/abathur.md
+//     on disk, the config hook below self-registers the command instead.
 
 import { execFile } from "node:child_process";
-import { tool } from "@opencode-ai/plugin";
+import { tool, type Config } from "@opencode-ai/plugin";
 
 /** Spawn cap: a CLI call that outlives this is killed and reported, never awaited forever. */
 const TIMEOUT_MS = 120_000;
@@ -109,9 +116,47 @@ function runCli(bin: string, argv: readonly string[]): Promise<CliResult> {
   });
 }
 
+
+/**
+ * /abathur slash-command template, injected into cfg.command.abathur by the
+ * config hook for installs without a commands/abathur.md on disk (Route B).
+ * Byte-mirror of plugin/abathur-command.md minus its first-line marker —
+ * src/test/opencode.test.ts pins the equality.
+ */
+const COMMAND_TEMPLATE = `Drive the abathur evolution harness through the \`abathur\` tool on this machine.
+
+User request: $ARGUMENTS
+
+Interpret the request as one \`abathur\` CLI invocation: the first word is the
+top-level command (\`genome\`, \`run\`, \`status\`, \`bundle\`, \`graft\`, \`self-eval\`,
+\`kernel\`, or \`--help\`) and the rest are argv tokens. Call the \`abathur\` tool
+with \`command\` set to the first word and \`extra\` set to the remaining tokens,
+then report the CLI exit code (0 ok / 1 blocked decision / 2 cannot-answer)
+and the relevant lines of its output. If no request was given, call the tool
+with \`command: "--help"\` and summarize the command list. \`promote\` and
+\`tombstone\` cannot be called through the tool at all — the tool refuses them.
+They are human gates that belong to a terminal: if the user asks for one,
+tell them to run \`abathur promote …\` / \`abathur tombstone …\` there.
+`;
+
 export default {
   id: "abathur",
   server: async () => ({
+    // Self-registering /abathur: opencode calls hook.config(cfg) once per
+    // instance after ALL config sources are merged — file-based commands are
+    // already in cfg.command by then (config.ts merges {command,commands}/**/*.md;
+    // the hook fires from plugin/index.ts after config.get()). `??=` keeps a
+    // Route-A commands/abathur.md authoritative (identical behaviour to 0.2.2)
+    // and only fills the gap for Route B; the command map is keyed by name, so
+    // a same-name file + injection never duplicates the entry. Proven upstream
+    // mechanism: opencode-acp registers its /acp command exactly this way.
+    config: async (cfg: Config) => {
+      cfg.command ??= {};
+      cfg.command.abathur ??= {
+        description: "Drive the abathur evolution harness (usage: /abathur <command> [args...])",
+        template: COMMAND_TEMPLATE,
+      };
+    },
     tool: {
       abathur: tool({
         description: