pactive 0.0.0-stage → 0.0.2-alpha.1

package/mcp/tools/_core.mjs

@@ -0,0 +1,254 @@
+/**
+ * Shared Pactive core access for the OPCteam / DSH host surfaces.
+ *
+ * `src/core/index.mjs` is produced by the parallel core worker. It is loaded
+ * **lazily by relative path** so a missing (not yet built) core degrades into
+ * a readable error instead of breaking plugin load.
+ *
+ * unverified: the frozen host contract (docs/team/task-cards/ACTI-CONTRACT.md, historical file name)
+ * freezes the **export names** of core, but not the argument shapes of
+ * `loadState` / `saveState` / `mutateState`. Every call below therefore tries
+ * the plausible shapes in order and falls back to an explicit read/compute/write
+ * path. Re-check this module once `src/core/index.mjs` lands and delete the
+ * shapes that turned out to be wrong.
+ */
+
+import { pathToFileURL } from "node:url";
+
+/** Relative candidates, resolved against this file's location (<pkg>/mcp/tools/). */
+const CORE_CANDIDATES = [
+  "../../src/core/index.mjs", // <pkg>/src/core/index.mjs
+  "../src/core/index.mjs", // <pkg>/hooks/ → <pkg>/src/core/index.mjs
+  "../../../src/core/index.mjs",
+];
+
+let cachedCore = null;
+
+/**
+ * Load the core module.
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {Promise<any>}
+ */
+export async function loadCore(env = process.env) {
+  if (cachedCore) return cachedCore;
+  const explicit = env.PACTIVE_CORE_MODULE;
+  const candidates = explicit ? [explicit, ...CORE_CANDIDATES] : CORE_CANDIDATES;
+  const tried = [];
+  for (const candidate of candidates) {
+    const href = candidate.startsWith("/")
+      ? pathToFileURL(candidate).href
+      : new URL(candidate, import.meta.url).href;
+    tried.push(href);
+    try {
+      const mod = await import(href);
+      if (mod && typeof mod.resolvePaths === "function") {
+        cachedCore = mod;
+        return mod;
+      }
+    } catch {
+      /* try the next candidate */
+    }
+  }
+  throw new Error(
+    `pactive: core module not found (tried: ${tried.join(", ")}). ` +
+      `Build src/core before using this surface; set PACTIVE_CORE_MODULE to override.`,
+  );
+}
+
+/** @param {unknown} err */
+export function errorText(err) {
+  return String(err?.message ?? err);
+}
+
+/**
+ * Read the persisted state, tolerating the two plausible loadState shapes.
+ * @returns {Promise<any|null>}
+ */
+export async function readState(core, paths) {
+  for (const args of [[paths.stateFile], [paths]]) {
+    try {
+      const state = await core.loadState(...args);
+      if (state && typeof state === "object") return state;
+    } catch {
+      /* next shape */
+    }
+  }
+  return null;
+}
+
+/**
+ * Persist the state, tolerating the plausible saveState shapes.
+ * @returns {Promise<boolean>}
+ */
+export async function writeState(core, paths, state) {
+  const shapes = [
+    [paths.stateFile, state],
+    [state, paths.stateFile],
+    [state],
+  ];
+  let last;
+  for (const args of shapes) {
+    try {
+      await core.saveState(...args);
+      return true;
+    } catch (err) {
+      last = err;
+    }
+  }
+  throw last instanceof Error ? last : new Error(String(last));
+}
+
+/**
+ * Mutate the state through core (locking + atomic write) with a verified
+ * fallback. `fn` MUST be pure: it may be evaluated twice (verification).
+ *
+ * @param {any} core
+ * @param {any} paths
+ * @param {(state:any)=>any} fn
+ * @returns {Promise<any>} the new state
+ */
+export async function mutateState(core, paths, fn) {
+  const before = (await readState(core, paths)) ?? core.defaultState();
+  const shapes = [
+    [fn, paths],
+    [paths, fn],
+    [fn],
+  ];
+  let last;
+  for (const args of shapes) {
+    try {
+      const out = await core.mutateState(...args);
+      const after = await readState(core, paths);
+      if (after) {
+        const wanted = fn(before);
+        if (JSON.stringify(after) !== JSON.stringify(wanted)) {
+          // core wrote somewhere else than this host's state file → write explicitly.
+          await writeState(core, paths, wanted);
+          return wanted;
+        }
+        return after;
+      }
+      return out ?? fn(before);
+    } catch (err) {
+      last = err;
+    }
+  }
+  const after = fn(before);
+  try {
+    await writeState(core, paths, after);
+  } catch (err) {
+    throw new Error(`pactive: state write failed (${errorText(err)})`);
+  }
+  return after;
+}
+
+/** Normalize a core call that may return either the state or `{ state, ... }`. */
+export function pickState(out, fallback) {
+  if (out && typeof out === "object" && out.state && typeof out.state === "object") return out.state;
+  if (out && typeof out === "object" && Array.isArray(out.tasks)) return out;
+  return fallback;
+}
+
+/**
+ * Parse a human `when` into a schedule spec.
+ * Accepts: `10m` / `2h` / `30s` (in), `18:30` / ISO 8601 (at), `every 1h` (every).
+ * @returns {{kind:"in"|"at"|"every", when:string, at:number|null}|null}
+ */
+export function parseWhen(when, now = Date.now()) {
+  const text = typeof when === "string" ? when.trim() : "";
+  if (text === "") return { kind: "in", when: "10m", at: null };
+  const every = /^every\s+(.+)$/i.exec(text);
+  if (every) return { kind: "every", when: every[1].trim(), at: null };
+  const duration = /^(\d+)\s*(s|sec|m|min|h|hour|d|day)$/i.exec(text);
+  if (duration) {
+    const unit = duration[2].toLowerCase();
+    const factor = unit.startsWith("s") ? 1000 : unit.startsWith("m") ? 60000 : unit.startsWith("h") ? 3600000 : 86400000;
+    return { kind: "in", when: text, at: now + Number(duration[1]) * factor };
+  }
+  const clock = /^(\d{1,2}):(\d{2})$/.exec(text);
+  if (clock) {
+    const at = new Date(now);
+    at.setHours(Number(clock[1]), Number(clock[2]), 0, 0);
+    if (at.getTime() <= now) at.setDate(at.getDate() + 1);
+    return { kind: "at", when: text, at: at.getTime() };
+  }
+  const iso = Date.parse(text);
+  if (!Number.isNaN(iso)) return { kind: "at", when: text, at: iso };
+  return null;
+}
+/* ------------------------------------------------------------------ *
+ * OPCteam hook runtime helpers (shared by hooks/*.mjs)
+ * ------------------------------------------------------------------ */
+
+const MAX_STDIN_BYTES = 2 * 1024 * 1024;
+
+/**
+ * Read the hook payload from stdin. Never throws: a broken payload must not
+ * break the host session.
+ * @returns {Promise<Record<string, any>>}
+ */
+export async function readStdinJson(stream = process.stdin) {
+  let raw = "";
+  try {
+    for await (const chunk of stream) {
+      raw += chunk;
+      if (raw.length > MAX_STDIN_BYTES) break;
+    }
+  } catch {
+    return {};
+  }
+  if (raw.trim() === "") return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Write the hook decision to stdout (the host reads it as JSON).
+ * @param {Record<string, any>} output
+ */
+export function writeHookOutput(output) {
+  try {
+    process.stdout.write(JSON.stringify(output ?? {}) + "\n");
+  } catch {
+    /* stdout closed */
+  }
+}
+
+/**
+ * Mark an activity kind on the host's persisted state.
+ * @param {"user"|"agent"|"session-start"|"session-end"|"tool"} kind
+ * @param {{hostKind?: string, env?: Record<string,string|undefined>, now?: number}} [options]
+ */
+export async function markActivity(kind, options = {}) {
+  const env = options.env ?? process.env;
+  const now = options.now ?? Date.now();
+  const hostKind = options.hostKind ?? "opcteam";
+  const core = await loadCore(env);
+  const paths = core.resolvePaths(hostKind, env);
+  const state = await mutateState(core, paths, (current) => {
+    const next = core.markActivity(current, kind, now);
+    return next && typeof next === "object" ? next : current;
+  });
+  return { ok: true, kind, state, stateFile: paths.stateFile, now };
+}
+
+/**
+ * Flip the control flag (control returned to the human).
+ * @param {{hostKind?: string, env?: Record<string,string|undefined>, now?: number}} [options]
+ */
+export async function markControlReturned(options = {}) {
+  const env = options.env ?? process.env;
+  const now = options.now ?? Date.now();
+  const hostKind = options.hostKind ?? "opcteam";
+  const core = await loadCore(env);
+  const paths = core.resolvePaths(hostKind, env);
+  const state = await mutateState(core, paths, (current) => {
+    const next = core.markControlReturned(current, now);
+    return next && typeof next === "object" ? next : current;
+  });
+  return { ok: true, state, stateFile: paths.stateFile, now };
+}

package/mcp/tools/definitions.mjs

@@ -0,0 +1,173 @@
+/**
+ * MCP tool surface of the `pactive` OPCteam plugin (stdio JSON-RPC server).
+ *
+ * Tools: pactive_status / pactive_schedule / pactive_tell / pactive_history.
+ * Zero third-party dependencies — the schemas are plain JSON Schema.
+ *
+ * unverified: mailbox.send / ledger.tail argument shapes come from the frozen
+ * contract's export names only; the exact message envelope is not frozen yet.
+ * The calls below send the most plausible envelope and report the raw core
+ * result so a mismatch is visible instead of being swallowed.
+ */
+
+import {
+  errorText,
+  loadCore,
+  mutateState,
+  parseWhen,
+  pickState,
+  readState,
+} from "./_core.mjs";
+
+const HOST_KIND = "opcteam";
+
+const obj = (properties, required) => ({
+  type: "object",
+  properties,
+  ...(required && required.length > 0 ? { required } : {}),
+  additionalProperties: false,
+});
+
+const str = (description) => ({ type: "string", description });
+
+/** @type {Array<{name:string, description:string, inputSchema:object}>} */
+export const TOOL_DEFINITIONS = [
+  {
+    name: "pactive_status",
+    description:
+      "Pactive 主动机制状态：空闲判定与 reason、护栏四闸门、定时任务数、最近活动。只读。",
+    inputSchema: obj({}, []),
+  },
+  {
+    name: "pactive_schedule",
+    description:
+      "登记一个定时任务（真正落盘）。when 支持时长（10m）、时刻（18:30）、ISO 时间、every 1h。",
+    inputSchema: obj(
+      {
+        prompt: str("任务正文（到点注入给会话的内容）"),
+        when: str("触发时间：时长 / 时刻 / ISO 8601 / every <时长>；缺省 10m"),
+      },
+      ["prompt"],
+    ),
+  },
+  {
+    name: "pactive_tell",
+    description:
+      "给同机另一个会话投递一条消息。对端离线时进入 outbox 排队，不伪装成功。",
+    inputSchema: obj(
+      {
+        to: str("目标会话的 agentId 或名字"),
+        body: str("消息正文"),
+        kind: str("消息语义：notify（默认）| ask | task"),
+      },
+      ["to", "body"],
+    ),
+  },
+  {
+    name: "pactive_history",
+    description: "读取 Pactive 事件账本尾部（触发→投递→回应→结账），用于追溯主动行为。",
+    inputSchema: obj({ limit: { type: "integer", description: "返回条数，默认 20" } }, []),
+  },
+];
+
+/** @param {string} name */
+export function findTool(name) {
+  return TOOL_DEFINITIONS.find((tool) => tool.name === name);
+}
+
+function json(text, isError = false) {
+  return { content: [{ type: "text", text: typeof text === "string" ? text : JSON.stringify(text, null, 2) }], isError };
+}
+
+/**
+ * Run one tool.
+ * @param {string} name
+ * @param {Record<string, any>} args
+ * @param {{env?: Record<string,string|undefined>, now?: number}} [options]
+ */
+export async function runTool(name, args = {}, options = {}) {
+  const env = options.env ?? process.env;
+  const now = options.now ?? Date.now();
+  let core;
+  try {
+    core = await loadCore(env);
+  } catch (err) {
+    return json(`ERROR CORE_UNAVAILABLE: ${errorText(err)}`, true);
+  }
+  const paths = core.resolvePaths(HOST_KIND, env);
+
+  try {
+    switch (name) {
+      case "pactive_status": {
+        const state = (await readState(core, paths)) ?? core.defaultState();
+        const policy = state.policy ?? {};
+        const idle = core.evaluateIdle ? core.evaluateIdle(state, now, 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 json({
+          host: HOST_KIND,
+          now,
+          enabled: state.idle?.enabled ?? false,
+          idle,
+          guard,
+          tasks: Array.isArray(tasks) ? tasks.length : 0,
+          activity,
+          stateFile: paths.stateFile,
+        });
+      }
+
+      case "pactive_schedule": {
+        const prompt = typeof args.prompt === "string" ? args.prompt.trim() : "";
+        if (prompt === "") return json("ERROR INVALID_ARGUMENT: prompt 必填", true);
+        const spec = parseWhen(args.when, now);
+        if (!spec) return json(`ERROR INVALID_ARGUMENT: 无法解析 when（${String(args.when)}）`, true);
+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 json({
+          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,
+        });
+      }
+
+      case "pactive_tell": {
+        const to = typeof args.to === "string" ? args.to.trim() : "";
+        const body = typeof args.body === "string" ? args.body.trim() : "";
+        if (to === "" || body === "") return json("ERROR INVALID_ARGUMENT: to 与 body 必填", true);
+        const kind = typeof args.kind === "string" && args.kind !== "" ? args.kind : "notify";
+        let receipt;
+        const next = await mutateState(core, paths, (state) => {
+          const out = core.mailbox.send(state, { to, body, kind, from: state.identity?.agentId ?? HOST_KIND }, now);
+          receipt = out;
+          return pickState(out, state);
+        });
+        return json({
+          ok: receipt?.ok ?? true,
+          state: receipt?.state ?? receipt?.status ?? "accepted",
+          reason: receipt?.reason ?? null,
+          outboxId: receipt?.outboxId ?? receipt?.id ?? null,
+          peers: Object.keys(next.peers ?? {}).length,
+        });
+      }
+
+      case "pactive_history": {
+        const limit = Number.isInteger(args.limit) ? args.limit : 20;
+        const events = core.ledger?.tail ? core.ledger.tail(paths.ledgerFile, limit) : [];
+        return json({ count: Array.isArray(events) ? events.length : 0, events });
+      }
+
+      default:
+        return json(`ERROR UNKNOWN_TOOL: ${name}`, true);
+    }
+  } catch (err) {
+    return json(`ERROR ${err?.code ?? "INTERNAL"}: ${errorText(err)}`, true);
+  }
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "pactive",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2-alpha.1",
+  "description": "Pactive：跨 Pi / OPCteam / DSH 的主动能力运行时（idle 判定默认关闭、人工闸门、事件账本）。专有软件：使用条款见包内 LICENSE（发行物含 Pi 扩展源码 pi/extension.ts）。",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "bin": {
+    "pactive": "bin/pactive.mjs"
+  },
+  "exports": {
+    ".": "./src/core/index.mjs",
+    "./pi": "./pi/extension.ts",
+    "./dsh": "./dsh/index.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "pi/",
+    "skills/",
+    ".opcteam-plugin/",
+    "hooks/",
+    "mcp/",
+    "commands/",
+    "agents/",
+    "dsh/",
+    "README.md",
+    "LICENSE",
+    "BREAKING-CHANGES.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./pi/extension.ts"
+    ],
+    "skills": [
+      "./pi/skills/pactive"
+    ]
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./dsh/cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shark2202/z-agents.git"
+  }
+}