@minidoll/agentkit-dsh-plugin 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# agentkit-dsh-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> DeepSeek Harness 插件：**项目自包含**的 lifecycle hooks —— 配置随仓库走，
+> 按会话 cwd 发现，不需要为每个项目改宿主目录。
+
+## 它做什么
+
+在 DSH 的两个执行缝（`tools/pre-execute` / `tools/post-execute`）上跑命令钩子：
+
+- **配置按会话 cwd 发现**：`<项目>/.agent/hooks/hooks.json`（CC 方言），
+  其次 `.claude/settings.json`、`.claude/hooks.json`；无配置 = 静默跳过
+- **退出码语义**：`PreToolUse` 任何非零 → **阻断**（deny）；`PostToolUse` → 只记录
+- 配置坏掉**报错**，不会伪装成"没有配置"（否则等于静默放行）
+- payload 走 stdin（`{event, hookId, toolName, args, sessionId, cwd}`），
+  env 含 `CLAUDE_PROJECT_DIR` / `DSH_HOOK_ID` / `DSH_SESSION_ID`
+
+## 安装（宿主侧，显式部署动作）
+
+```bash
+# 装进某个 profile（会写 ~/.dsh/profiles/<p>/package.json + node_modules）
+pnpm add agentkit-dsh-plugin --dir ~/.dsh/profiles/web
+# 或用 agentkit 的落地命令（幂等、带备份与审计）
+dsh-landing install --home ~/.dsh --profile web
+```
+
+条目本身由 bundle 自带的 `cordis.patch.yml` 插入；`dsh-landing rollback` 可撤销。
+
+## 项目侧
+
+项目里**零改动**：agentkit 的 `dsh` 适配器会生成 `.agent/hooks/hooks.json`。
+想手写也可以，CC 方言即可。
+
+## 安全默认：观察模式
+
+**装上即只记录、不阻断**（`observe`）。要真正拦截，显式开：
+
+```bash
+AGENTKIT_HOOKS_ENFORCE=1   # 在 profile 的插件 env 里配置
+```
+
+这条默认来自一次真实事故（0.0.2）：插件的 seam handler 在"无决策"路径上
+**返回 `undefined`**，而 harness 直接读 `gate.kind`（无判空），于是
+**每次工具调用**都抛 `Cannot read properties of undefined (reading 'kind')` ——
+整个会话、所有工具、跨会话全挂。修复见 `src/index.ts` 的 seam 契约注释。
+
+**由此确立的三条规则**（都已由测试钉住）：
+
+1. seam handler **必须始终返回带 `kind` 的对象**（`ALLOW` 常量 + 测试不变式）
+2. **fail-safe**：插件任何故障都不得外溢到工具层 —— 捕获后放行并记日志
+   （连 `ctx.write` 抛错也不能让兜底二次抛出）
+3. **未经真实会话验证的决策行为不得默认生效** —— 所以默认观察模式
+
+## 版本跟随
+
+```
+0.0.x  ↔  DeepSeek Harness 0.2.x
+seam：tools/pre-execute · tools/post-execute · ctx.shell
+```
+
+设计与论证见 agentkit 仓的 `docs/design/0001`（为什么自己做）与 `0002`（Target 模型）。

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# DSH profile bundle patch:把本插件的 loader 行插进 profile。
+# 目标 id 由我们自己定,便于 profile patch 定向覆盖(如 configFile)。
+- insert:
+    - id: project-hooks
+      name: "@minidoll/agentkit-dsh-plugin"

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { homedir as homedir2 } from "node:os";
+import { join as join2 } from "node:path";
+
+// src/install.ts
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+var ROW_ID = "project-hooks";
+var ROW_NAME = "@minidoll/agentkit-dsh-plugin";
+var STATE_DIR = ".agentkit-landing";
+function landingPaths(home2, profile2) {
+  const patch = join(home2, "profiles", profile2, "cordis.patch.yml");
+  return { home: home2, profile: profile2, patch, stateDir: join(home2, "profiles", profile2, STATE_DIR) };
+}
+function rowPresent(patchText) {
+  return patchText.includes(`id: ${ROW_ID}`) || patchText.includes(ROW_NAME);
+}
+function renderRow(configFile2) {
+  const lines = [`- id: ${ROW_ID}`, `  name: ${ROW_NAME}`];
+  if (configFile2 !== void 0) {
+    lines.push("  config:", `    configFile: ${configFile2}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function audit(paths, action, detail) {
+  mkdirSync(paths.stateDir, { recursive: true });
+  const rec = { at: (/* @__PURE__ */ new Date()).toISOString(), action, profile: paths.profile, ...detail };
+  appendFileSync(join(paths.stateDir, "ledger.jsonl"), `${JSON.stringify(rec)}
+`, "utf8");
+}
+function install(opts) {
+  const paths = landingPaths(opts.home, opts.profile);
+  if (!existsSync(join(opts.home, "profiles", opts.profile))) {
+    return { ok: false, changed: false, path: paths.patch, reason: `profile not found: ${opts.home}/profiles/${opts.profile}` };
+  }
+  if (!existsSync(paths.patch)) {
+    mkdirSync(paths.stateDir, { recursive: true });
+    writeFileSync(paths.patch, `${renderRow(opts.configFile)}`, "utf8");
+    audit(paths, "install", { backup: null, configFile: opts.configFile ?? null, created: true });
+    return { ok: true, changed: true, path: paths.patch, reason: "created" };
+  }
+  const before = readFileSync(paths.patch, "utf8");
+  if (rowPresent(before)) {
+    audit(paths, "install-noop", { reason: "already present" });
+    return { ok: true, changed: false, path: paths.patch, reason: "already present" };
+  }
+  mkdirSync(paths.stateDir, { recursive: true });
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const backup = join(paths.stateDir, `backup-${stamp}.yml`);
+  copyFileSync(paths.patch, backup);
+  const next = before.endsWith("\n") || before === "" ? `${before}${renderRow(opts.configFile)}` : `${before}
+${renderRow(opts.configFile)}`;
+  writeFileSync(paths.patch, next, "utf8");
+  audit(paths, "install", { backup, configFile: opts.configFile ?? null });
+  return { ok: true, changed: true, path: paths.patch, backup };
+}
+function rollback(opts) {
+  const paths = landingPaths(opts.home, opts.profile);
+  if (!existsSync(paths.stateDir)) {
+    return { ok: false, changed: false, path: paths.patch, reason: "no state directory \u2014 nothing to roll back" };
+  }
+  const backups = readdirSync(paths.stateDir).filter((f) => f.startsWith("backup-") && f.endsWith(".yml")).sort();
+  const last = backups.at(-1);
+  if (last === void 0) {
+    return { ok: false, changed: false, path: paths.patch, reason: "no backup recorded" };
+  }
+  copyFileSync(join(paths.stateDir, last), paths.patch);
+  audit(paths, "rollback", { restoredFrom: last });
+  return { ok: true, changed: true, path: paths.patch, backup: join(paths.stateDir, last) };
+}
+function status(opts) {
+  const paths = landingPaths(opts.home, opts.profile);
+  if (!existsSync(paths.patch)) {
+    return { ok: true, installed: false, path: paths.patch, backups: [] };
+  }
+  const text = readFileSync(paths.patch, "utf8");
+  const m = new RegExp(`configFile:\\s*(\\S+)`).exec(text);
+  const backups = existsSync(paths.stateDir) ? readdirSync(paths.stateDir).filter((f) => f.startsWith("backup-")).sort() : [];
+  return { ok: true, installed: rowPresent(text), path: paths.patch, backups, ...m?.[1] !== void 0 ? { configFile: m[1] } : {} };
+}
+function readProfileJson(home2, profile2) {
+  const p = join(home2, "profiles", profile2, "package.json");
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function installBundle(opts) {
+  const profileDir = join(opts.home, "profiles", opts.profile);
+  if (!existsSync(join(opts.home, "profiles", opts.profile))) {
+    return { ok: false, added: false, alreadyInstalled: false, error: `profile not found: ${profileDir}` };
+  }
+  const pkg = readProfileJson(opts.home, opts.profile);
+  if (pkg === null) return { ok: false, added: false, alreadyInstalled: false, error: `cannot read ${join(profileDir, "package.json")}` };
+  const deps = pkg.dependencies ?? {};
+  const dsh = pkg.dsh ?? {};
+  const bundles = dsh.profile?.bundles ?? [];
+  const installed = Object.keys(deps).some((k) => k === ROW_NAME) || bundles.includes(ROW_NAME);
+  if (installed) return { ok: true, added: false, alreadyInstalled: true };
+  if (opts.skipPackageManager !== true) {
+    const pm = resolvePnpm();
+    if (pm === null) {
+      return {
+        ok: false,
+        added: false,
+        alreadyInstalled: false,
+        error: "pnpm not found (tried PATH, ~/.local/share/pnpm/pnpm, npx). Install pnpm, or rerun with --skip-pnpm and install the package into the profile by hand."
+      };
+    }
+    const r = spawnSync(pm, ["add", opts.from], { cwd: profileDir, encoding: "utf8", timeout: 18e4 });
+    if (r.status !== 0) {
+      const detail = [r.error?.message, r.stdout, r.stderr].filter((x) => typeof x === "string").join("\n").trim();
+      return { ok: false, added: false, alreadyInstalled: false, error: `${pm} add failed (exit ${String(r.status)})
+${detail.slice(-600)}` };
+    }
+  }
+  const next = {
+    ...pkg,
+    dependencies: { ...deps, [ROW_NAME]: opts.skipPackageManager === true ? "file:." : opts.from },
+    dsh: { ...dsh, profile: { ...dsh.profile ?? {}, bundles: [...bundles, ROW_NAME] } }
+  };
+  writeFileSync(join(profileDir, "package.json"), `${JSON.stringify(next, null, 2)}
+`, "utf8");
+  audit(landingPaths(opts.home, opts.profile), "install-bundle", { from: opts.from });
+  return { ok: true, added: true, alreadyInstalled: false };
+}
+function resolvePnpm() {
+  const candidates = ["pnpm", join(homedirPath(), ".local/share/pnpm/pnpm")];
+  for (const c of candidates) {
+    const probe = spawnSync(c, ["--version"], { encoding: "utf8", timeout: 15e3 });
+    if (probe.status === 0) return c;
+  }
+  const viaNpx = spawnSync("npx", ["--no-install", "pnpm", "--version"], { encoding: "utf8", timeout: 2e4 });
+  if (viaNpx.status === 0) return "npx pnpm";
+  return null;
+}
+function homedirPath() {
+  try {
+    return homedir();
+  } catch {
+    return process.env.HOME ?? "";
+  }
+}
+function rollbackBundle(opts) {
+  const patchRollback = rollback({ home: opts.home, profile: opts.profile });
+  const profileDir = join(opts.home, "profiles", opts.profile);
+  const pkg = readProfileJson(opts.home, opts.profile);
+  if (pkg === null) {
+    return { ok: false, removed: false, patchRollback, error: `cannot read ${join(profileDir, "package.json")}` };
+  }
+  const deps = pkg.dependencies ?? {};
+  const dsh = pkg.dsh ?? {};
+  const bundles = dsh.profile?.bundles ?? [];
+  const had = ROW_NAME in deps || bundles.includes(ROW_NAME);
+  if (!had) {
+    audit(landingPaths(opts.home, opts.profile), "rollback-bundle-noop", { reason: "not registered" });
+    return { ok: true, removed: false, patchRollback };
+  }
+  const nextDeps = { ...deps };
+  delete nextDeps[ROW_NAME];
+  const nextBundles = bundles.filter((b) => b !== ROW_NAME);
+  const next = { ...pkg, dependencies: nextDeps, dsh: { ...dsh, profile: { ...dsh.profile ?? {}, bundles: nextBundles } } };
+  writeFileSync(join(profileDir, "package.json"), `${JSON.stringify(next, null, 2)}
+`, "utf8");
+  if (opts.skipPackageManager !== true) {
+    const pm = resolvePnpm();
+    if (pm !== null) {
+      const r = spawnSync(pm, ["remove", ROW_NAME], { cwd: profileDir, encoding: "utf8", timeout: 18e4 });
+      if (r.status !== 0) {
+        const detail = [r.stdout, r.stderr].filter((x) => typeof x === "string").join("\n").trim();
+        audit(landingPaths(opts.home, opts.profile), "rollback-bundle-partial", { detail: detail.slice(-300) });
+        return { ok: false, removed: false, patchRollback, error: `package removal failed: ${detail.slice(-300)}` };
+      }
+    }
+  }
+  audit(landingPaths(opts.home, opts.profile), "rollback-bundle", {});
+  return { ok: true, removed: true, patchRollback };
+}
+
+// src/cli.ts
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on("error", (err) => {
+    if (err.code === "EPIPE") process.exit(0);
+    throw err;
+  });
+}
+var USAGE = `dsh-landing <install|rollback|status> [--profile <name>] [--home <path>] [--configFile <abs>]
+
+  install    \u628A\u63D2\u4EF6\u6761\u76EE\u8FFD\u52A0\u8FDB <home>/profiles/<profile>/cordis.patch.yml\uFF08\u5E42\u7B49\uFF1B\u5199\u524D\u5907\u4EFD\uFF09
+  rollback   \u6062\u590D\u6700\u8FD1\u4E00\u6B21\u5907\u4EFD\uFF08\u64A4\u9500\u6211\u4EEC\u8FFD\u52A0\u7684\u6761\u76EE\uFF0C\u4E0D\u52A8\u522B\u4EBA\u7684\u5185\u5BB9\uFF09
+  status     \u62A5\u544A\u662F\u5426\u5DF2\u5B89\u88C5\u3001\u5907\u4EFD\u6570\u3001configFile
+
+\u5BBF\u4E3B\u6539\u52A8\u662F**\u663E\u5F0F\u90E8\u7F72\u52A8\u4F5C**\uFF1A\u6BCF\u6B21\u52A8\u4F5C\u5199\u5BA1\u8BA1\u5230 <profile>/.agentkit-landing/ledger.jsonl\u3002`;
+function flag(args2, name) {
+  const i = args2.indexOf(`--${name}`);
+  return i >= 0 ? args2[i + 1] : void 0;
+}
+var args = process.argv.slice(2);
+var cmd = args[0];
+if (cmd === void 0 || cmd === "--help" || cmd === "-h") {
+  process.stdout.write(`${USAGE}
+`);
+  process.exit(cmd === void 0 ? 1 : 0);
+}
+var home = flag(args, "home") ?? process.env.DSH_HOME ?? join2(homedir2(), ".dsh");
+var profile = flag(args, "profile") ?? "web";
+var configFile = flag(args, "configFile");
+if (cmd === "install") {
+  const from = flag(args, "from");
+  if (from !== void 0) {
+    const b = installBundle({
+      home,
+      profile,
+      from,
+      ...args.includes("--skip-pnpm") ? { skipPackageManager: true } : {}
+    });
+    if (!b.ok) {
+      process.stderr.write(`dsh-landing: bundle install failed \u2014 ${b.error}
+`);
+      process.exit(1);
+    }
+    process.stdout.write(
+      b.alreadyInstalled ? `dsh-landing: plugin already installed in profile ${profile}
+` : `dsh-landing: plugin installed into ${home}/profiles/${profile}/node_modules and registered in dsh.profile.bundles
+`
+    );
+  }
+  if (from !== void 0 && configFile === void 0) {
+    process.stdout.write("  row:      provided by the bundle's own cordis.patch.yml (no override needed)\n");
+    process.exit(0);
+  }
+  const r = install({ home, profile, ...configFile !== void 0 ? { configFile } : {} });
+  if (!r.ok) {
+    process.stderr.write(`dsh-landing: install failed \u2014 ${r.reason}
+`);
+    process.exit(1);
+  }
+  process.stdout.write(`dsh-landing: ${r.changed ? "installed" : "already present"} \u2192 ${r.path}
+`);
+  if (r.backup !== void 0) process.stdout.write(`  backup: ${r.backup}
+`);
+  if (r.changed) {
+    process.stdout.write("  next: restart DSH (or /hooks-reload) \u2014 \u63D2\u4EF6\u6761\u76EE\u9700\u8981 profile \u91CD\u65B0\u5408\u6210\u624D\u751F\u6548\n");
+    process.stdout.write("  undo: dsh-landing rollback\n");
+  }
+} else if (cmd === "rollback") {
+  const r = args.includes("--bundle") ? rollbackBundle({ home, profile, ...args.includes("--skip-pnpm") ? { skipPackageManager: true } : {} }) : (() => {
+    const only = rollback({ home, profile });
+    return { ok: only.ok, removed: false, patchRollback: only, ...only.reason !== void 0 ? { error: only.reason } : {} };
+  })();
+  if (!r.ok) {
+    process.stderr.write(`dsh-landing: rollback failed \u2014 ${r.error ?? "unknown"}
+`);
+    process.exit(1);
+  }
+  process.stdout.write(`dsh-landing: rolled back patch from ${r.patchRollback.backup ?? "(no backup)"}
+`);
+  if (r.removed) process.stdout.write("  bundle \u6CE8\u518C\u4E0E\u5305\u5DF2\u79FB\u9664 \u2014\u2014 \u91CD\u542F DSH \u751F\u6548\n");
+  process.exit(0);
+} else if (cmd === "status") {
+  const s = status({ home, profile });
+  const p = landingPaths(home, profile);
+  process.stdout.write(`dsh-landing: profile ${profile} (${home}/profiles/${profile})
+`);
+  process.stdout.write(`  installed: ${s.installed ? "yes" : "no"}
+`);
+  process.stdout.write(`  patch:     ${s.path}
+`);
+  process.stdout.write(`  configFile:${s.configFile ?? " (project-discovered default)"}
+`);
+  process.stdout.write(`  backups:   ${s.backups.length}
+`);
+  process.stdout.write(`  audit:     ${join2(p.stateDir, "ledger.jsonl")}
+`);
+} else {
+  process.stderr.write(`dsh-landing: unknown command ${cmd}
+
+${USAGE}
+`);
+  process.exit(1);
+}

package/dist/execute.d.ts

@@ -0,0 +1,27 @@
+export interface ExecRequest {
+    command: string;
+    cwd: string;
+    timeoutMs: number;
+    stdin: string;
+    env: Record<string, string>;
+}
+export type ShellLike = {
+    resolve: (req: unknown) => unknown;
+    run: (req: unknown) => Promise<{
+        exitCode: number;
+        stderr?: {
+            text?: string;
+        };
+    }>;
+};
+export declare function runHookCommand(req: ExecRequest, shell?: ShellLike): Promise<{
+    exitCode: number;
+    error?: string;
+}>;
+/**
+ * 取 shell 服务必须**防御式**：cordis 的服务属性在未 inject 时**直接抛错**
+ * (`cannot get property "shell" without inject`)，而不是返回 undefined。
+ * 真实 seam 里就是这么炸的：`shell?.run` 在属性访问那一步就抛了。
+ * 取不到就退回 spawnSync（这条路径已被证明能正确写台账）。
+ */
+export declare function safeShell(ctx: unknown): ShellLike | undefined;

package/dist/execute.js

@@ -0,0 +1,51 @@
+/**
+ * 命令执行：优先用 DSH 的 `ctx.shell`（沙箱 + 超时 + stdin payload），
+ * 没有 shell 服务时退回 child_process（插件 README 的诚实边界：
+ * "若 ctx.shell 未挂载,插件照常加载但 hook 不会运行" —— 我们选择**退回**
+ * 而不是静默不跑，但会在 stderr 说明）。
+ */
+import { spawnSync } from 'node:child_process';
+export async function runHookCommand(req, shell) {
+    if (shell !== undefined && typeof shell.run === 'function' && typeof shell.resolve === 'function') {
+        try {
+            const resolved = shell.resolve({
+                command: req.command,
+                workdir: req.cwd,
+                timeoutMs: req.timeoutMs,
+                stdin: req.stdin,
+                env: req.env,
+            });
+            const r = await shell.run(resolved);
+            return { exitCode: r.exitCode };
+        }
+        catch (err) {
+            // infra 故障不能伪装成"钩子失败" —— 交给调用方区分
+            return { exitCode: 1, error: `ctx.shell failure: ${err.message}` };
+        }
+    }
+    const r = spawnSync('sh', ['-c', req.command], {
+        cwd: req.cwd,
+        timeout: req.timeoutMs,
+        input: req.stdin,
+        env: { ...process.env, ...req.env },
+        encoding: 'utf8',
+    });
+    return { exitCode: r.status ?? 1, ...(r.status === null ? { error: `signal: ${String(r.signal)}` } : {}) };
+}
+/**
+ * 取 shell 服务必须**防御式**：cordis 的服务属性在未 inject 时**直接抛错**
+ * (`cannot get property "shell" without inject`)，而不是返回 undefined。
+ * 真实 seam 里就是这么炸的：`shell?.run` 在属性访问那一步就抛了。
+ * 取不到就退回 spawnSync（这条路径已被证明能正确写台账）。
+ */
+export function safeShell(ctx) {
+    try {
+        const shell = ctx?.shell;
+        return shell !== undefined && typeof shell.run === 'function' && typeof shell.resolve === 'function'
+            ? shell
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import { type UserMessageLike } from './inject.js';
+import { type ShellLike } from './execute.js';
+/**
+ * seam 收到的**真实** exec 形状（读 dsh-tools 的 createExecution 得来）：
+ *   { token, callId, rootCallId, name, signal, agent, parent?, schema?, arguments }
+ * 字段名是 **name** 与 **arguments** —— 不是 toolName/args。
+ * 0.0.4 之所以在真实会话里毫无动静：我把字段名猜错了，toolName 恒为 '',
+ * matcher('Edit|Write|NotebookEdit') 永不命中 → 静默放行（观察模式下也不报错）。
+ */
+export interface HookExec {
+    /** 工具名（真实字段）。 */
+    name?: unknown;
+    /** 工具参数（真实字段，deep-frozen JSON）。 */
+    arguments?: unknown;
+    agent?: {
+        session?: {
+            header?: {
+                cwd?: string;
+            };
+            id?: string;
+        };
+    };
+    [key: string]: unknown;
+}
+/**
+ * post 缝的返回（`PostToolDecision`）：只有它才认 `additionalContexts`。
+ * pre 缝用 {@link Decision}（allow/deny），塞 additionalContexts 是无效字段（0016 §1.2）。
+ */
+export interface PostDecision {
+    kind: 'accept';
+    additionalContexts?: UserMessageLike[];
+}
+export interface Decision {
+    kind: 'allow' | 'deny';
+    reason?: string;
+}
+export interface PluginCtx {
+    on: (seam: string, cb: (exec: HookExec) => Promise<Decision | PostDecision | undefined>) => void;
+    shell?: ShellLike;
+    write?: (text: string) => void;
+}
+/** 一次执行的可观测记录（v0：最近 20 条，供 /hooks 或后续命令展示）。 */
+export interface HookRun {
+    hookId: string;
+    event: string;
+    toolName: string;
+    exitCode: number;
+    at: number;
+    error?: string;
+}
+export interface PluginState {
+    runs: HookRun[];
+}
+export declare function createProjectHooksPlugin(ctx: PluginCtx): PluginState;
+/** DSH 插件入口形态（apply(ctx)）—— 供 loader 挂载。 */
+export declare function apply(ctx: PluginCtx): PluginState;