pactive 0.0.0-stage → 0.0.2-alpha.1

package/dsh/index.js

@@ -0,0 +1,285 @@
+/**
+ * Pactive — DSH (Cordis) plugin.
+ *
+ * Registers the pactive tool surface (`pactive_status` / `pactive_schedule`) and the
+ * `/pactive` command, and subscribes to session events so the pactive activity
+ * timeline and the control flag stay accurate.
+ *
+ * The core module (`src/core/index.mjs`) is loaded lazily by relative path —
+ * the shared loader lives in `mcp/tools/_core.mjs` (same package) and degrades
+ * to a readable error when core is not built yet.
+ *
+ * unverified (DSH 0.2.1-rc.5 host API):
+ *   - the session event names below are guesses; every subscription is wrapped
+ *     in try/catch so an unknown event name cannot break plugin load;
+ *   - `ctx.tools.register` / `ctx.commands.register` shapes follow the
+ *     DSH Cordis plugin conventions documented in this repository's spec notes.
+ */
+
+import { loadCore, mutateState, parseWhen, pickState, readState } from "../mcp/tools/_core.mjs";
+
+export const name = "pactive";
+
+/** Every Cordis service this plugin touches must be declared here. */
+export const inject = ["tools", "commands", "sessions"];
+
+const HOST_KIND = "dsh";
+
+function errorText(err) {
+  return String(err?.message ?? err);
+}
+
+function safeLog(ctx, level, message, extra) {
+  try {
+    ctx?.log?.(level, message, extra);
+  } catch {
+    /* nothing left to report with */
+  }
+}
+
+/** Mark an activity kind; never throws. */
+async function markActivity(kind, ctx) {
+  try {
+    const core = await loadCore();
+    const paths = core.resolvePaths(HOST_KIND, process.env);
+    await mutateState(core, paths, (state) => {
+      const next = core.markActivity(state, kind);
+      return next && typeof next === "object" ? next : state;
+    });
+  } catch (err) {
+    safeLog(ctx, "warn", `pactive: markActivity(${kind}) failed`, { error: errorText(err) });
+  }
+}
+
+/** Flip the control flag (the agent stopped → control returned to the human). */
+async function markControlReturned(ctx) {
+  try {
+    const core = await loadCore();
+    const paths = core.resolvePaths(HOST_KIND, process.env);
+    await mutateState(core, paths, (state) => {
+      const next = core.markControlReturned(state);
+      return next && typeof next === "object" ? next : state;
+    });
+  } catch (err) {
+    safeLog(ctx, "warn", "pactive: markControlReturned failed", { error: errorText(err) });
+  }
+}
+
+const STATUS_PARAMETERS = { type: "object", properties: {}, additionalProperties: false };
+const SCHEDULE_PARAMETERS = {
+  type: "object",
+  properties: {
+    prompt: { type: "string", description: "任务正文（到点注入给会话的内容）" },
+    when: { type: "string", description: "触发时间：时长（10m）/ 时刻（18:30）/ ISO 8601 / every 1h" },
+  },
+  required: ["prompt"],
+  additionalProperties: false,
+};
+
+/**
+ * @param {any} ctx Cordis plugin context
+ * @param {Record<string, any>} config
+ */
+export function apply(ctx, config) {
+  const pluginConfig = config ?? {};
+
+  const registerTools = () => {
+    if (!ctx?.tools?.register) return;
+
+    ctx.tools.register({
+      name: "pactive_status",
+      description:
+        "Pactive 主动机制状态：空闲判定与 reason、护栏四闸门、定时任务数、最近活动。只读。",
+      parameters: STATUS_PARAMETERS,
+      async execute(args = {}) {
+        try {
+          const core = await loadCore();
+          const now = Date.now();
+          const paths = core.resolvePaths(HOST_KIND, process.env);
+          const state = (await readState(core, paths)) ?? core.defaultState();
+          const idle = core.evaluateIdle
+            ? core.evaluateIdle(state, now, state.policy ?? {})
+            : { idle: false, reason: "requires-action" };
+          const guard = core.checkGuard ? core.checkGuard(state, now) : { pass: false, reason: "requires-action" };
+          const tasks = core.schedule?.list ? core.schedule.list(state) : (state.tasks ?? []);
+          const activity = core.getActivity ? core.getActivity(state) : null;
+          return {
+            ok: true,
+            host: HOST_KIND,
+            now,
+            enabled: state.idle?.enabled ?? false,
+            idle,
+            guard,
+            tasks: Array.isArray(tasks) ? tasks.length : 0,
+            activity,
+          };
+        } catch (err) {
+          return { ok: false, error: errorText(err) };
+        }
+      },
+    });
+
+    ctx.tools.register({
+      name: "pactive_schedule",
+      description: "登记一个定时任务（真正落盘）。when 支持时长（10m）、时刻（18:30）、ISO 时间、every 1h。",
+      parameters: SCHEDULE_PARAMETERS,
+      async execute(args = {}) {
+        try {
+          const prompt = typeof args.prompt === "string" ? args.prompt.trim() : "";
+          if (prompt === "") return { ok: false, error: "prompt 必填（任务正文不能为空）" };
+          const now = Date.now();
+          const spec = parseWhen(args.when, now);
+          if (!spec) return { ok: false, error: `无法解析 when：${String(args.when)}` };
+          const core = await loadCore();
+          const paths = core.resolvePaths(HOST_KIND, process.env);
+          const next = await mutateState(core, paths, (state) => {
+            const out = core.schedule.add(
+              state,
+              { ...spec, prompt, content: prompt, owner: state.identity?.agentId },
+              now,
+            );
+            return pickState(out, state);
+          });
+          const tasks = core.schedule?.list ? core.schedule.list(next) : (next.tasks ?? []);
+          const created = Array.isArray(tasks) ? tasks[tasks.length - 1] : null;
+          return {
+            ok: true,
+            taskId: created?.id ?? created?.taskId ?? null,
+            dueAt: created?.dueAt ?? spec.at ?? null,
+            kind: spec.kind,
+            when: spec.when,
+            tasks: Array.isArray(tasks) ? tasks.length : 0,
+          };
+        } catch (err) {
+          return { ok: false, error: errorText(err) };
+        }
+      },
+    });
+  };
+
+  const registerCommands = () => {
+    if (!ctx?.commands?.register) return;
+
+    ctx.commands.register({
+      name: "pactive",
+      description: "Pactive：status | tasks | schedule <when> <prompt> | help",
+      input: { hint: "status | tasks | schedule <when> <prompt> | help" },
+      async handler(invocation) {
+        const raw = String(invocation?.rawInput ?? "").trim();
+        const parts = raw.split(/\s+/).filter(Boolean);
+        const sub = parts[0] ?? "status";
+        const fail = (text) => ({ kind: "error", text });
+        const ok = (text) => ({ kind: "success", text });
+        try {
+          const core = await loadCore();
+          const now = Date.now();
+          const paths = core.resolvePaths(HOST_KIND, process.env);
+          const state = (await readState(core, paths)) ?? core.defaultState();
+          if (sub === "status") {
+            const idle = core.evaluateIdle
+              ? core.evaluateIdle(state, now, state.policy ?? {})
+              : { idle: false, reason: "requires-action" };
+            const guard = core.checkGuard ? core.checkGuard(state, now) : { pass: false, reason: "requires-action" };
+            const tasks = core.schedule?.list ? core.schedule.list(state) : (state.tasks ?? []);
+            return ok(
+              `pactive: idle=${idle.idle} reason=${idle.reason} guard=${guard.pass ? "pass" : "blocked"} ` +
+                `(${guard.reason ?? "-"}) tasks=${Array.isArray(tasks) ? tasks.length : 0}`,
+            );
+          }
+          if (sub === "tasks") {
+            const tasks = core.schedule?.list ? core.schedule.list(state) : (state.tasks ?? []);
+            const list = Array.isArray(tasks) ? tasks : [];
+            return ok(
+              list.length === 0
+                ? "pactive: 没有定时任务"
+                : `pactive: ${list.length} 个定时任务\n` +
+                    list.map((task) => `- [${task?.id ?? "?"}] ${task?.prompt ?? task?.content ?? ""}`).join("\n"),
+            );
+          }
+          if (sub === "schedule") {
+            const when = parts[1] ?? "10m";
+            const prompt = parts.slice(2).join(" ");
+            if (prompt === "") return fail("用法：/pactive schedule <when> <prompt>");
+            const spec = parseWhen(when, now);
+            if (!spec) return fail(`pactive: 无法解析 when（${when}）`);
+            const next = await mutateState(core, paths, (current) => {
+              const out = core.schedule.add(
+                current,
+                { ...spec, prompt, content: prompt, owner: current.identity?.agentId },
+                now,
+              );
+              return pickState(out, current);
+            });
+            const tasks = core.schedule?.list ? core.schedule.list(next) : (next.tasks ?? []);
+            const created = Array.isArray(tasks) ? tasks[tasks.length - 1] : null;
+            return ok(`pactive: 已登记定时任务 ${created?.id ?? "-"}（${when}）`);
+          }
+          return fail("用法：/pactive status | tasks | schedule <when> <prompt> | help");
+        } catch (err) {
+          return fail(`pactive 失败：${errorText(err)}`);
+        }
+      },
+    });
+  };
+
+/**
+   * Session events → activity tracking.
+   * unverified: the DSH event names are not documented in this repository, so
+   * every candidate is subscribed defensively.
+   */
+  const subscribeSessionEvents = () => {
+    const sessions = ctx?.sessions;
+    if (!sessions || typeof sessions.on !== "function") return;
+    const activityCandidates = [
+      ["session.start", "session-start"],
+      ["sessionStart", "session-start"],
+      ["session.end", "session-end"],
+      ["sessionEnd", "session-end"],
+      ["message", "user"],
+      ["user_message", "user"],
+      ["agent.end", "agent"],
+      ["agent_end", "agent"],
+      ["message_end", "agent"],
+    ];
+    for (const [event, kind] of activityCandidates) {
+      try {
+        sessions.on(event, () => {
+          void markActivity(kind, ctx);
+        });
+      } catch (err) {
+        safeLog(ctx, "debug", `pactive: session event ${event} unavailable`, { error: errorText(err) });
+      }
+    }
+    // The agent settled → control returned to the human.
+    for (const event of ["agent.settled", "agent_settled", "agent.idle"]) {
+      try {
+        sessions.on(event, () => {
+          void markControlReturned(ctx);
+        });
+      } catch (err) {
+        safeLog(ctx, "debug", `pactive: session event ${event} unavailable`, { error: errorText(err) });
+      }
+    }
+  };
+
+  try {
+    registerTools();
+    registerCommands();
+    subscribeSessionEvents();
+  } catch (err) {
+    safeLog(ctx, "error", "pactive: failed to register tools/commands", { error: errorText(err) });
+  }
+
+  // The agent stops → control returns to the human.
+  try {
+    ctx?.effect?.(() => () => {
+      void markControlReturned(ctx);
+    });
+  } catch (err) {
+    safeLog(ctx, "warn", "pactive: ctx.effect unavailable; control flag updated on events only", {
+      error: errorText(err),
+    });
+  }
+
+  safeLog(ctx, "info", "pactive plugin loaded", { config: pluginConfig });
+}

package/hooks/hooks.json

@@ -0,0 +1,54 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${OPCTEAM_PLUGIN_ROOT}/hooks/session-start.mjs\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${OPCTEAM_PLUGIN_ROOT}/hooks/user-prompt-submit.mjs\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${OPCTEAM_PLUGIN_ROOT}/hooks/post-tool-use.mjs\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${OPCTEAM_PLUGIN_ROOT}/hooks/stop.mjs\""
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${OPCTEAM_PLUGIN_ROOT}/hooks/session-end.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/post-tool-use.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse hook — record tool activity (an agent-side action).
+ *
+ * Tool activity refreshes the "something is happening" baseline but must not
+ * refresh the *human* activity baseline.
+ */
+
+import { markActivity, readStdinJson, writeHookOutput } from "../mcp/tools/_core.mjs";
+
+await readStdinJson();
+
+try {
+  await markActivity("tool");
+} catch (err) {
+  process.stderr.write(`[pactive] PostToolUse: ${String(err?.message ?? err)}\n`);
+}
+
+writeHookOutput({});

package/hooks/session-end.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * SessionEnd hook — record that the session ended.
+ *
+ * The session id / cwd come from the hook payload; they are recorded by the
+ * core's activity timeline so `doctor` can report stale sessions.
+ */
+
+import { markActivity, readStdinJson, writeHookOutput } from "../mcp/tools/_core.mjs";
+
+await readStdinJson();
+
+try {
+  await markActivity("session-end");
+} catch (err) {
+  process.stderr.write(`[pactive] SessionEnd: ${String(err?.message ?? err)}\n`);
+}
+
+writeHookOutput({});

package/hooks/session-start.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * SessionStart hook — record that a session started.
+ *
+ * Contract: hooks/hooks.json → `SessionStart` → `node "${OPCTEAM_PLUGIN_ROOT}/hooks/session-start.mjs"`.
+ * Protocol: read the hook payload from stdin, write the hook decision to stdout.
+ * A hook must never break the host session: every failure degrades to `{}`.
+ */
+
+import { markActivity, readStdinJson, writeHookOutput } from "../mcp/tools/_core.mjs";
+
+await readStdinJson();
+
+try {
+  await markActivity("session-start");
+} catch (err) {
+  process.stderr.write(`[pactive] SessionStart: ${String(err?.message ?? err)}\n`);
+}
+
+writeHookOutput({});

package/hooks/stop.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * Stop hook — control returned to the human; deliver due work at most once.
+ *
+ * Loop protection (I27): the hook may block **at most once per turn**.
+ *  - `stop_hook_active === true` → the host is already re-running because of a
+ *    previous block → never block again.
+ *  - `stopBlockCount` (persisted in the state) → blocks once per turn; the
+ *    `UserPromptSubmit` hook resets it at the turn boundary.
+ *
+ * Output: `{}` (pass through) or `{"decision":"block","reason":"…"}`.
+ */
+
+import {
+  loadCore,
+  mutateState,
+  readStdinJson,
+  writeHookOutput,
+} from "../mcp/tools/_core.mjs";
+
+const input = await readStdinJson();
+const now = Date.now();
+
+try {
+  const core = await loadCore();
+  const paths = core.resolvePaths("opcteam", process.env);
+
+  // 1) control returned to the human (the agent stopped).
+  const state = await mutateState(core, paths, (current) => {
+    const next = core.markControlReturned(current, now);
+    return next && typeof next === "object" ? next : current;
+  });
+
+  // 2) never block inside a block.
+  if (input?.stop_hook_active === true) {
+    writeHookOutput({});
+  } else {
+    // 3) at most one block per turn.
+    const blocked = Number(state?.stopBlockCount ?? 0) >= 1;
+    const due = blocked ? [] : core.schedule?.due ? core.schedule.due(state, now) : [];
+    const tasks = Array.isArray(due) ? due : [];
+
+    if (tasks.length === 0) {
+      writeHookOutput({});
+    } else {
+      const lines = tasks.map((task) => `- [${task?.id ?? "?"}] ${task?.prompt ?? task?.content ?? ""}`.trim());
+      const reason = `pactive: ${tasks.length} 个定时任务到期\n${lines.join("\n")}`;
+      await mutateState(core, paths, (current) => ({ ...current, stopBlockCount: 1, controlReturned: false }));
+      writeHookOutput({ decision: "block", reason });
+    }
+  }
+} catch (err) {
+  process.stderr.write(`[pactive] Stop: ${String(err?.message ?? err)}\n`);
+  writeHookOutput({});
+}

package/hooks/user-prompt-submit.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * UserPromptSubmit hook — record human activity and re-arm the Stop guard.
+ *
+ * The Stop hook may block **at most once per turn** (I27). This hook is the
+ * turn boundary: it resets the per-turn block counter so the next turn may
+ * block once again.
+ */
+
+import {
+  loadCore,
+  markActivity,
+  mutateState,
+  readStdinJson,
+  writeHookOutput,
+} from "../mcp/tools/_core.mjs";
+
+await readStdinJson();
+
+try {
+  await markActivity("user");
+} catch (err) {
+  process.stderr.write(`[pactive] UserPromptSubmit: ${String(err?.message ?? err)}\n`);
+}
+
+try {
+  const core = await loadCore();
+  const paths = core.resolvePaths("opcteam", process.env);
+  await mutateState(core, paths, (state) => ({ ...state, stopBlockCount: 0 }));
+} catch (err) {
+  process.stderr.write(`[pactive] UserPromptSubmit (reset): ${String(err?.message ?? err)}\n`);
+}
+
+writeHookOutput({});

package/mcp/server.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+/**
+ * `pactive` MCP server for OPCteam — stdio JSON-RPC, zero third-party dependencies.
+ *
+ * Exposes: pactive_status / pactive_schedule / pactive_tell / pactive_history.
+ * Protocol: newline-delimited JSON-RPC 2.0 (MCP `initialize` / `tools/list` /
+ * `tools/call`), the same wire shape the OPCteam plugin loader expects.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { TOOL_DEFINITIONS, findTool, runTool } from "./tools/definitions.mjs";
+
+const DEFAULT_PROTOCOL = "2024-11-05";
+const SERVER_NAME = "pactive";
+const SERVER_VERSION = "0.0.2-alpha.1";
+
+/** @param {NodeJS.WritableStream} output */
+function send(output, message) {
+  try {
+    output.write(JSON.stringify(message) + "\n");
+  } catch {
+    /* host closed the pipe */
+  }
+}
+
+/**
+ * Handle one JSON-RPC message.
+ * @param {any} message
+ * @param {{output: NodeJS.WritableStream, env: Record<string,string|undefined>}} ctx
+ */
+export async function handleMessage(message, { output, env }) {
+  if (!message || typeof message !== "object" || Array.isArray(message)) {
+    send(output, { jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
+    return;
+  }
+  const { id, method, params } = message;
+  if (id === undefined || id === null) return; // notification
+
+  switch (method) {
+    case "initialize":
+      send(output, {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          protocolVersion: params?.protocolVersion || DEFAULT_PROTOCOL,
+          capabilities: { tools: {} },
+          serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+        },
+      });
+      return;
+    case "ping":
+      send(output, { jsonrpc: "2.0", id, result: {} });
+      return;
+    case "tools/list":
+      send(output, { jsonrpc: "2.0", id, result: { tools: TOOL_DEFINITIONS } });
+      return;
+    case "tools/call": {
+      const name = params?.name;
+      if (!findTool(name)) {
+        send(output, {
+          jsonrpc: "2.0",
+          id,
+          result: { content: [{ type: "text", text: `ERROR UNKNOWN_TOOL: ${name}` }], isError: true },
+        });
+        return;
+      }
+      const args = params?.arguments && typeof params.arguments === "object" ? params.arguments : {};
+      try {
+        const result = await runTool(name, args, { env });
+        send(output, { jsonrpc: "2.0", id, result });
+      } catch (err) {
+        send(output, {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: `ERROR INTERNAL: ${String(err?.message ?? err)}` }],
+            isError: true,
+          },
+        });
+      }
+      return;
+    }
+    default:
+      send(output, {
+        jsonrpc: "2.0",
+        id,
+        error: { code: -32601, message: `Method not found: ${method}` },
+      });
+  }
+}
+
+/**
+ * Start the stdio server.
+ * @param {{input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream, env?: Record<string,string|undefined>}} [options]
+ */
+export function startServer(options = {}) {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  const env = options.env ?? process.env;
+  let buffer = "";
+
+  const onLine = (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let message;
+    try {
+      message = JSON.parse(trimmed);
+    } catch (err) {
+      send(output, {
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32700, message: `Parse error: ${String(err?.message ?? err)}` },
+      });
+      return;
+    }
+    Promise.resolve(handleMessage(message, { output, env })).catch((err) => {
+      send(output, {
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32603, message: String(err?.message ?? err) },
+      });
+    });
+  };
+
+  input.setEncoding("utf8");
+  input.on("data", (chunk) => {
+    buffer += chunk;
+    let index;
+    while ((index = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, index);
+      buffer = buffer.slice(index + 1);
+      onLine(line);
+    }
+  });
+  input.on("end", () => {
+    if (buffer.trim()) onLine(buffer);
+    buffer = "";
+  });
+}
+
+function isDirectRun() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  const resolved = path.resolve(entry);
+  try {
+    return import.meta.url === new URL(`file://${resolved}`).href || fs.realpathSync(resolved) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectRun()) startServer();