wkappbot-code 0.0.0-stage → 0.3.1

package/plugin/wisdom-kernel.js

@@ -0,0 +1,217 @@
+// wkappbot-code -- Wisdom Kernel: the one kih plugin for OpenCode (pinned: opencode-ai 1.19.5).
+// OpenCode is the BRIDGE (model <-> tools); kih is the HARNESS riding on it. This file only maps
+// OpenCode plugin events onto the existing kih hook launcher, .claude/hooks/wkharness-run.sh:
+//   tool.execute.before -> "pre"           (exit 2 = refuse: throw with the hook stderr as the reason)
+//   tool.execute.after  -> "post"          (fail-open, never changes the tool result)
+//   event session.idle  -> "stop-archive"  (archive only, fail-open, no verdict)
+// Fail direction matches Claude Code: only a hook VERDICT refuses; a plugin error, a missing hook or a
+// hung hook (killed at PRE_TIMEOUT_MS) lets the call through.
+// API verified 2026-11-05 from @opencode-ai/plugin 1.19.5 dist/index.d.ts (interface Hooks) and
+// @opencode-ai/sdk 1.19.5 dist/gen/types.gen.d.ts:413 (EventSessionIdle). Spec:
+// wkappbot skill read agent-harness-landscape-2026-howto
+// KNOWN GAP: no transcript_path is sent (OpenCode keeps sessions in its own store), so kih gates that
+// resolve the model or read the transcript see an unknown model and fall back to their defaults.
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// OpenCode tool id -> Claude tool name the kih guards already know.
+const TOOL_MAP = {
+  bash: "Bash", edit: "Edit", write: "Write", read: "Read",
+  glob: "Glob", grep: "Grep", list: "LS", patch: "Edit", multiedit: "MultiEdit",
+  webfetch: "WebFetch", websearch: "WebSearch", task: "Agent", todowrite: "TodoWrite",
+};
+
+// pre arm budget: a hung hook is killed and the call fails OPEN, like a Claude hook timeout.
+const PRE_TIMEOUT_MS = Number(process.env.WK_APPBOT_PRE_TIMEOUT_MS || 60000);
+
+// OpenCode args (camelCase) -> Claude tool_input (snake_case) for the tools the guards inspect.
+function toClaudeInput(tool, args) {
+  const a = args || {};
+  switch (tool) {
+    case "bash": {
+      const o = { command: a.command ?? "" };
+      if (a.description !== undefined) o.description = a.description;
+      if (a.timeout !== undefined) o.timeout = a.timeout;
+      return o;
+    }
+    case "edit":
+      return { file_path: a.filePath ?? a.file_path, old_string: a.oldString ?? a.old_string,
+               new_string: a.newString ?? a.new_string, replace_all: a.replaceAll ?? a.replace_all ?? false };
+    case "write":
+      return { file_path: a.filePath ?? a.file_path, content: a.content ?? "" };
+    case "read": {
+      const o = { file_path: a.filePath ?? a.file_path };
+      if (a.offset !== undefined) o.offset = a.offset;
+      if (a.limit !== undefined) o.limit = a.limit;
+      return o;
+    }
+    default: {
+      const o = { ...a };
+      if (o.filePath !== undefined && o.file_path === undefined) o.file_path = o.filePath;
+      return o;
+    }
+  }
+}
+
+function claudeToolName(tool) {
+  return TOOL_MAP[tool] || tool;
+}
+
+// The Claude-shaped hook payload for one OpenCode tool call.
+function buildPreToolUsePayload(input, args, cwd) {
+  return {
+    hook_event_name: "PreToolUse",
+    session_id: input.sessionID,
+    cwd: (args && args.workdir) || cwd,
+    tool_name: claudeToolName(input.tool),
+    tool_input: toClaudeInput(input.tool, args),
+    tool_use_id: input.callID,
+    agent_family: "opencode",
+  };
+}
+
+function buildPostToolUsePayload(input, output, cwd) {
+  const p = buildPreToolUsePayload(input, input.args, cwd);
+  p.hook_event_name = "PostToolUse";
+  p.tool_response = { output: output && output.output, title: output && output.title };
+  return p;
+}
+
+// kih root: WK_KIH_DIR, else the checkout this file sits in (wkappbot-code/plugin -> ../..).
+function resolveKihDir() {
+  if (process.env.WK_KIH_DIR) return process.env.WK_KIH_DIR;
+  try {
+    const up = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+    if (existsSync(join(up, ".claude", "hooks", "wkharness-run.sh"))) return up;
+  } catch {}
+  return "";
+}
+
+// Pipe JSON into "<hook> <arm>" (wkharness-run.sh, or wkharness-lite.sh without PowerShell); resolves {code, stdout, stderr}. Never rejects.
+// No hook found = fail-open (code 0, skipped) so a missing kih never bricks OpenCode.
+// PowerShell on PATH? The full harness (wkharness-run.sh) runs its guards in PowerShell; without one it exits 127,
+// which used to read as "no verdict" and let EVERY call through (QA 2026-11-06, fresh Linux HOME).
+function onPath(names) {
+  const dirs = String(process.env.PATH || "").split(process.platform === "win32" ? ";" : ":");
+  for (const d of dirs) for (const n of names) { try { if (d && existsSync(join(d, n))) return true; } catch {} }
+  return false;
+}
+let _ps = null;
+function hasPowerShell() {
+  if (process.env.WK_APPBOT_FORCE_LITE === "1") return false;
+  if (_ps === null) _ps = onPath(["pwsh", "pwsh.exe", "powershell.exe", "powershell"]);
+  return _ps;
+}
+
+// Which hook script serves an arm: the full harness when PowerShell is there, else the bash lite harness
+// (tools/wkharness-lite.sh: study lock, intent lock, stop lint). The prompt and session arms exist only in lite.
+function pickHook(arm, kih) {
+  if (!kih) return "";
+  const full = join(kih, ".claude", "hooks", "wkharness-run.sh"), lite = join(kih, "tools", "wkharness-lite.sh");
+  const liteArm = arm === "prompt" || arm === "session";
+  if (!liteArm && hasPowerShell() && existsSync(full)) return full;
+  if (existsSync(lite)) return lite;
+  return liteArm ? "" : full;
+}
+
+function runHook(arm, payload, opts = {}) {
+  const kih = opts.kihDir ?? resolveKihDir();
+  const hook = opts.hook || process.env.WK_APPBOT_HOOK || pickHook(arm, kih);
+  return new Promise((done) => {
+    let settled = false;
+    const finish = (r) => { if (!settled) { settled = true; if (timer) clearTimeout(timer); done(r); } };
+    let timer = null, out = "", err = "", child;
+    if (!hook || !existsSync(hook)) return finish({ code: 0, stdout: "", stderr: "", skipped: true });
+    let body;
+    try { body = JSON.stringify(payload); } catch (e) { return finish({ code: 0, stdout: "", stderr: String(e), skipped: true }); }
+    try {
+      child = spawn("bash", [hook, arm], {
+        env: { ...process.env, ...(kih ? { CLAUDE_PROJECT_DIR: kih } : {}) },
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+    } catch (e) {
+      return finish({ code: 0, stdout: "", stderr: String(e), skipped: true });
+    }
+    if (opts.timeoutMs) {
+      timer = setTimeout(() => {
+        try { child.kill("SIGKILL"); } catch {}
+        finish({ code: 0, stdout: out, stderr: err, timedOut: true });
+      }, opts.timeoutMs);
+    }
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (err += d));
+    child.on("error", (e) => finish({ code: 0, stdout: out, stderr: err + String(e), skipped: true }));
+    child.on("close", (code) => finish({ code: code ?? 0, stdout: out, stderr: err }));
+    child.stdin.on("error", () => {});
+    child.stdin.end(body);
+  });
+}
+
+// Claude contract: exit 2 refuses; so does a stdout JSON deny/block verdict.
+function isRefusal(r) {
+  if (r.timedOut || r.skipped) return false;
+  if (r.code === 2) return true;
+  try {
+    const j = JSON.parse(r.stdout);
+    return (j.hookSpecificOutput && j.hookSpecificOutput.permissionDecision === "deny") || j.decision === "block";
+  } catch { return false; }
+}
+
+// A stdout deny JSON names its own reason; stderr then may hold only warn lines (wkharness-run.sh wk_pre_emit).
+function refusalReason(r) {
+  try {
+    const j = JSON.parse(r.stdout);
+    const why = (j.hookSpecificOutput && j.hookSpecificOutput.permissionDecisionReason) || j.reason;
+    if (why) return why;
+  } catch {}
+  return (r.stderr || "").trim() || (r.stdout || "").trim() || "refused by the kih harness";
+}
+
+// options = the second slot of the opencode.json plugin entry: ["file://.../wisdom-kernel.js", { "kihDir": "..." }].
+// install.sh fills kihDir, because the installed copy no longer sits inside the kih checkout.
+export const WisdomKernel = async (ctx = {}, options = {}) => {
+  const cwd = ctx.directory || ctx.worktree || process.cwd();
+  const k = (options && options.kihDir) || undefined;
+  return {
+    "tool.execute.before": async (input, output) => {
+      let r;
+      try {
+        r = await runHook("pre", buildPreToolUsePayload(input || {}, output && output.args, cwd), { kihDir: k, timeoutMs: PRE_TIMEOUT_MS });
+      } catch { return; } // a plugin bug never refuses a call
+      if (isRefusal(r)) throw new Error("[wisdom-kernel] " + refusalReason(r));
+    },
+    "tool.execute.after": async (input, output) => {
+      try { await runHook("post", buildPostToolUsePayload(input || {}, output, cwd), { kihDir: k, timeoutMs: 30000 }); } catch {}
+    },
+    // UserPromptSubmit: arms the intent lock for the next real tool call (fail-open, never blocks the message).
+    "chat.message": async (input, output) => {
+      try {
+        const parts = (output && output.parts) || [];
+        const prompt = parts.filter((p) => p && p.type === "text" && !p.synthetic).map((p) => p.text || "").join("\n");
+        if (!prompt) return;
+        await runHook("prompt", { hook_event_name: "UserPromptSubmit", session_id: input && input.sessionID, cwd, prompt, agent_family: "opencode" }, { kihDir: k, timeoutMs: 30000 });
+      } catch {}
+    },
+    event: async (arg) => {
+      try {
+        const event = arg && arg.event;
+        if (event && event.type === "session.created") {
+          const info = (event.properties && event.properties.info) || {};
+          await runHook("session", { hook_event_name: "SessionStart", session_id: info.id, cwd, source: "startup", agent_family: "opencode" }, { kihDir: k, timeoutMs: 30000 });
+          return;
+        }
+        if (!event || event.type !== "session.idle") return;
+        const sid = event.properties && event.properties.sessionID;
+        await runHook("stop-archive", { hook_event_name: "Stop", session_id: sid, cwd, agent_family: "opencode" }, { kihDir: k, timeoutMs: 30000 });
+      } catch {}
+    },
+  };
+};
+
+// Helpers for the selftest ride on the plugin function, never as module exports (OpenCode calls every export).
+WisdomKernel.internals = { TOOL_MAP, PRE_TIMEOUT_MS, toClaudeInput, claudeToolName, buildPreToolUsePayload,
+  buildPostToolUsePayload, resolveKihDir, runHook, isRefusal, refusalReason, hasPowerShell, pickHook };
+
+export default WisdomKernel;