psyclaw 0.27.22 → 0.28.0

package/vendor/ars/pi/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "academic-research-skills-pi-wrapper",
+  "private": true,
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Thin Pi wrapper for the upstream Claude Code Academic Research Skills",
+  "keywords": [
+    "pi-package",
+    "academic-research"
+  ],
+  "license": "CC-BY-NC-4.0",
+  "pi": {
+    "extensions": [
+      "./wrapper.js"
+    ],
+    "skills": [
+      "../deep-research",
+      "../academic-paper",
+      "../academic-paper-reviewer",
+      "../academic-pipeline"
+    ],
+    "prompts": [
+      "../commands"
+    ]
+  }
+}

package/vendor/ars/pi/wrapper.js

@@ -0,0 +1,193 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const commandPattern = /^\/(ars-[a-z0-9-]+)(?:\s+([\s\S]*))?$/;
+const skillNames = ["deep-research", "academic-paper", "academic-paper-reviewer", "academic-pipeline"];
+const skillPattern = new RegExp(`^/skill:(${skillNames.join("|")})(?:\\s|$)`);
+const stateEntryType = "ars-pi-state";
+const orchestrationPattern = /subagent|workflow|parallel[-_ ]agent|multi[-_ ]agent/i;
+const webPattern = /websearch|web[-_ ]search|brave[-_ ]search|webfetch|web[-_ ]fetch|page[-_ ]retrieval/i;
+
+function uniqueMatches(items, pattern) {
+  return [...new Set(items.filter((item) => pattern.test(item.search)).map((item) => item.label))];
+}
+
+const xmlEntities = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+};
+
+function decodeXml(text) {
+  return text.replace(/&(amp|lt|gt|quot|apos);/g, (_match, entity) => xmlEntities[entity]);
+}
+
+function canonicalPath(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return undefined;
+  }
+}
+
+const skillLocations = new Set(
+  skillNames
+    .map((name) => canonicalPath(resolve(repoRoot, name, "SKILL.md")))
+    .filter((location) => location !== undefined),
+);
+
+// Upstream SKILL.md files stay unmodified, so hide their exact Pi listings while ARS is inactive.
+function hideArsSkills(systemPrompt) {
+  return systemPrompt.replace(
+    /(?:\r?\n)?[ \t]*<skill>(?:(?!<skill>)[\s\S])*?<\/skill>/g,
+    (block) => {
+      const location = block.match(/<location>([^<]+)<\/location>/)?.[1];
+      const canonicalLocation = location ? canonicalPath(decodeXml(location)) : undefined;
+      return canonicalLocation && skillLocations.has(canonicalLocation) ? "" : block;
+    },
+  );
+}
+
+async function probe(pi, command, args) {
+  try {
+    const result = await pi.exec(command, args, { timeout: 3000 });
+    if (result.code !== 0) return "missing";
+    return (result.stdout || result.stderr).trim().split("\n")[0] || "available";
+  } catch {
+    return "missing";
+  }
+}
+
+const compatibility = `
+## Academic Research Skills compatibility for Pi
+
+Apply this section only while using an Academic Research Skills (ARS) skill or an \`/ars-*\` prompt.
+
+- The original Claude Code ARS files are the source of truth. Do not replace their research, writing, review, integrity, or checkpoint rules.
+- Resolve repository-relative ARS paths such as \`shared/\`, \`scripts/\`, \`commands/\`, \`deep-research/\`, \`academic-paper/\`, \`academic-paper-reviewer/\`, and \`academic-pipeline/\` from \`${repoRoot}\`.
+- Treat Claude Code tool names as capability names. Use the equivalent tools available in the current Pi session.
+- When ARS requests multiple agents, first inspect the available Pi tools and installed skills for a subagent, workflow, or parallel-agent capability; if none is obvious, search the configured Pi skill locations. Use a matching capability when available. Otherwise run the roles sequentially in the current agent and disclose that degraded execution mode. Do not require a specific orchestration add-on.
+- When ARS requests \`WebSearch\`, \`WebFetch\`, or \`/websearch\`, first inspect the available tools and installed skills for web search or page retrieval; if none is obvious, search the configured Pi skill locations. Prefer an installed web-search skill when available. Otherwise use a permitted HTTP or bibliographic-API capability. If none exists, report the limitation and do not claim that a source was verified.
+- Ask questions through normal conversation or any available user-question tool. Ignore Claude-only command \`model\` metadata and inherit the current Pi model.
+`;
+
+export default function (pi) {
+  let arsActive = false;
+
+  const setArsActive = (active) => {
+    if (arsActive === active) return;
+    arsActive = active;
+    pi.appendEntry(stateEntryType, { active });
+  };
+
+  const restoreArsState = (ctx) => {
+    const state = ctx.sessionManager.getBranch()
+      .filter((entry) => entry.type === "custom" && entry.customType === stateEntryType)
+      .pop();
+    arsActive = state?.data?.active === true;
+  };
+
+  pi.on("session_start", (_event, ctx) => {
+    restoreArsState(ctx);
+  });
+
+  pi.on("session_tree", (_event, ctx) => {
+    restoreArsState(ctx);
+  });
+
+  pi.on("input", (event) => {
+    const match = event.text.match(commandPattern);
+    if (!match) {
+      if (skillPattern.test(event.text)) setArsActive(true);
+      return { action: "continue" };
+    }
+
+    const commandPath = resolve(repoRoot, "commands", `${match[1]}.md`);
+    if (!existsSync(commandPath)) return { action: "continue" };
+
+    setArsActive(true);
+    const raw = readFileSync(commandPath, "utf8");
+    const body = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "").trim();
+    const args = match[2]?.trim() ?? "";
+    const hasArgumentPlaceholder = body.includes("$ARGUMENTS") || body.includes("$@");
+    const executableBody = body.replace(
+      /\b(python3?|bash|sh) scripts\/([^\s`]+)/g,
+      (_match, command, script) => `${command} "${repoRoot}/scripts/${script}"`,
+    );
+    const expanded = executableBody.replace(/\$ARGUMENTS|\$@/g, () => args);
+    const commandText = args && !hasArgumentPlaceholder
+      ? `${expanded}\n\nUser request / arguments:\n${args}`
+      : expanded;
+    const skillName = body.match(/^Trigger the `([^`]+)` (?:skill|orchestrator)/m)?.[1];
+    const text = skillName ? `/skill:${skillName} ${commandText}` : commandText;
+
+    return { action: "transform", text };
+  });
+
+  pi.registerCommand("ars-pi-start", {
+    description: "Enable ARS compatibility and automatic skill selection in this session",
+    handler: async (_args, ctx) => {
+      setArsActive(true);
+      ctx.ui.notify("ARS compatibility instructions enabled for this session", "info");
+    },
+  });
+
+  pi.registerCommand("ars-pi-stop", {
+    description: "Disable ARS compatibility and automatic skill selection in this session",
+    handler: async (_args, ctx) => {
+      setArsActive(false);
+      ctx.ui.notify("ARS compatibility instructions disabled for this session", "info");
+    },
+  });
+
+  pi.registerCommand("ars-pi-doctor", {
+    description: "Check optional Pi capabilities and local ARS runtime dependencies",
+    handler: async () => {
+      const activeTools = new Set(pi.getActiveTools());
+      const tools = pi.getAllTools().map((tool) => ({
+        label: `${activeTools.has(tool.name) ? "active tool" : "installed tool"}: ${tool.name}`,
+        search: `${tool.name} ${tool.description}`,
+      }));
+      const commands = pi.getCommands()
+        .filter((command) => !command.name.startsWith("ars-") && !command.name.startsWith("skill:academic-"))
+        .map((command) => ({
+          label: `${command.source}: /${command.name}`,
+          search: `${command.name} ${command.description ?? ""}`,
+        }));
+      const candidates = [...tools, ...commands];
+      const orchestration = uniqueMatches(candidates, orchestrationPattern);
+      const web = uniqueMatches(candidates, webPattern);
+      const python = await probe(pi, "python3", ["--version"]);
+      const pyyaml = await probe(pi, "python3", ["-c", "import yaml; print(f'PyYAML {yaml.__version__}')"]);
+      const pandoc = await probe(pi, "pandoc", ["--version"]);
+      const tectonic = await probe(pi, "tectonic", ["--version"]);
+      const sandbox = pi.getCommands().some((command) => command.name === "sandbox")
+        ? `detected; allow read access to ${repoRoot} when running outside the checkout`
+        : "not detected";
+      const format = (matches) => matches.length > 0 ? matches.join(", ") : "none; sequential/degraded mode";
+      const report = [
+        "ARS Pi doctor",
+        `Repository: ${repoRoot}`,
+        `Orchestration: ${format(orchestration)}`,
+        `Web retrieval: ${format(web)}`,
+        `Python: ${python}`,
+        `PyYAML: ${pyyaml}`,
+        `Pandoc: ${pandoc}`,
+        `Tectonic: ${tectonic}`,
+        `Sandbox: ${sandbox}`,
+        "Claude hooks: unavailable in Pi; write-scope enforcement remains prompt-level",
+      ].join("\n");
+
+      pi.sendMessage({ customType: "ars-pi-doctor", content: report, display: true });
+    },
+  });
+
+  pi.on("before_agent_start", (event) => {
+    if (!arsActive) return { systemPrompt: hideArsSkills(event.systemPrompt) };
+    return { systemPrompt: `${event.systemPrompt}\n${compatibility}` };
+  });
+}

package/vendor/ars/pi/wrapper.test.mjs

@@ -0,0 +1,201 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtempSync, rmSync, symlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import wrapper from "./wrapper.js";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const compatibilityMarker = "## Academic Research Skills compatibility for Pi";
+const arsSkillNames = ["deep-research", "academic-paper", "academic-paper-reviewer", "academic-pipeline"];
+const arsSkillLocations = arsSkillNames.map((name) => resolve(repoRoot, name, "SKILL.md"));
+const externalSkillLocation = "/example/external/deep-research/SKILL.md";
+const escapeXml = (text) => text
+  .replaceAll("&", "&")
+  .replaceAll("<", "&lt;")
+  .replaceAll(">", "&gt;")
+  .replaceAll('"', "&quot;")
+  .replaceAll("'", "&apos;");
+const skillBlock = (name, description, location) => `  <skill>
+    <name>${name}</name>
+    <description>${description}</description>
+    <location>${location}</location>
+  </skill>`;
+const baseSystemPrompt = [
+  "Base prompt",
+  "",
+  "<available_skills>",
+  ...arsSkillNames.map((name, index) => skillBlock(name, "ARS skill", arsSkillLocations[index])),
+  skillBlock("deep-research", "Unrelated skill with a colliding name", externalSkillLocation),
+  "</available_skills>",
+].join("\n");
+
+function createHarness() {
+  const handlers = new Map();
+  const commands = new Map();
+  const entries = [];
+  const notifications = [];
+  let branch = [];
+  const sessionContext = {
+    sessionManager: { getBranch: () => branch },
+  };
+  const pi = {
+    on(name, handler) {
+      handlers.set(name, handler);
+    },
+    registerCommand(name, command) {
+      commands.set(name, command);
+    },
+    appendEntry(customType, data) {
+      const entry = { type: "custom", customType, data };
+      entries.push(entry);
+      branch.push(entry);
+    },
+  };
+
+  wrapper(pi);
+  handlers.get("session_start")({}, sessionContext);
+
+  return {
+    handlers,
+    commands,
+    entries,
+    notifications,
+    sessionContext,
+    setBranch(nextBranch) {
+      branch = nextBranch;
+    },
+    commandContext: {
+      ui: { notify: (message, level) => notifications.push({ message, level }) },
+    },
+  };
+}
+
+function runBeforeAgentStart(harness, systemPrompt = baseSystemPrompt) {
+  const result = harness.handlers.get("before_agent_start")({ systemPrompt });
+  return result?.systemPrompt ?? systemPrompt;
+}
+
+test("ordinary prompts hide only package ARS skills", () => {
+  const harness = createHarness();
+  const systemPrompt = runBeforeAgentStart(harness);
+
+  for (const location of arsSkillLocations) assert.equal(systemPrompt.includes(location), false);
+  assert.equal(systemPrompt.includes(externalSkillLocation), true);
+  assert.equal(systemPrompt.includes(compatibilityMarker), false);
+});
+
+test("skill hiding does not cross into an adjacent skill block", () => {
+  const systemPrompt = [
+    "Base prompt",
+    "",
+    "<available_skills>",
+    `  <skill>
+    <name>${arsSkillNames[0]}</name>
+    <description>ARS skill</description>
+    <location>${arsSkillLocations[0]}</location></skill>`,
+    skillBlock("deep-research", "Unrelated skill", externalSkillLocation),
+    "</available_skills>",
+  ].join("\n");
+
+  const result = runBeforeAgentStart(createHarness(), systemPrompt);
+
+  assert.equal(result.includes(arsSkillLocations[0]), false);
+  assert.equal(result.includes(externalSkillLocation), true);
+});
+
+test("ordinary prompts hide ARS skills loaded through an XML-escaped symlink path", (t) => {
+  const tempRoot = mkdtempSync(join(tmpdir(), "ars-pi-&-"));
+  t.after(() => rmSync(tempRoot, { recursive: true, force: true }));
+  const linkedRoot = join(tempRoot, "linked-checkout");
+  symlinkSync(repoRoot, linkedRoot, process.platform === "win32" ? "junction" : "dir");
+  const linkedLocations = arsSkillNames.map((name) => resolve(linkedRoot, name, "SKILL.md"));
+  const systemPrompt = [
+    "Base prompt",
+    "",
+    "<available_skills>",
+    ...arsSkillNames.map((name, index) => skillBlock(name, "ARS skill", escapeXml(linkedLocations[index]))),
+    skillBlock("deep-research", "Unrelated missing skill", "/missing/deep-research/SKILL.md"),
+    "</available_skills>",
+  ].join("\n");
+
+  const result = runBeforeAgentStart(createHarness(), systemPrompt);
+
+  for (const location of linkedLocations) assert.equal(result.includes(escapeXml(location)), false);
+  assert.equal(result.includes("/missing/deep-research/SKILL.md"), true);
+});
+
+test("/ars-* activates compatibility for the same agent run", () => {
+  const harness = createHarness();
+  const result = harness.handlers.get("input")({ text: "/ars-plan topic" });
+  const systemPrompt = runBeforeAgentStart(harness);
+
+  assert.equal(result.action, "transform");
+  for (const location of arsSkillLocations) assert.equal(systemPrompt.includes(location), true);
+  assert.equal(systemPrompt.includes(compatibilityMarker), true);
+});
+
+test("direct ARS /skill:* activates compatibility", () => {
+  const harness = createHarness();
+  harness.handlers.get("input")({ text: "/skill:academic-pipeline topic" });
+  const systemPrompt = runBeforeAgentStart(harness);
+
+  assert.equal(systemPrompt.includes(compatibilityMarker), true);
+});
+
+test("command arguments are not rewritten as script paths", () => {
+  const harness = createHarness();
+  const result = harness.handlers.get("input")({
+    text: "/ars-cache-invalidate python scripts/user-provided.py",
+  });
+
+  assert.match(result.text, /python scripts\/user-provided\.py/);
+  assert.equal(result.text.includes(`${repoRoot}/scripts/user-provided.py`), false);
+  assert.equal(result.text.includes(`${repoRoot}/scripts/ars_cache_invalidate.py`), true);
+});
+
+test("argument placeholders are substituted in one pass", () => {
+  const harness = createHarness();
+  const result = harness.handlers.get("input")({
+    text: "/ars-cache-invalidate alpha$@omega",
+  });
+
+  assert.match(result.text, /alpha\$@omega/);
+  assert.doesNotMatch(result.text, /alphaalpha\$@omegaomega/);
+});
+
+test("/tree navigation recomputes activation from the selected branch", () => {
+  const harness = createHarness();
+  harness.handlers.get("input")({ text: "/ars-plan topic" });
+  assert.equal(runBeforeAgentStart(harness).includes(compatibilityMarker), true);
+
+  harness.setBranch([]);
+  const sessionTree = harness.handlers.get("session_tree");
+  assert.ok(sessionTree);
+  sessionTree({}, harness.sessionContext);
+  assert.equal(runBeforeAgentStart(harness).includes(compatibilityMarker), false);
+
+  harness.setBranch([{ type: "custom", customType: "ars-pi-state", data: { active: true } }]);
+  sessionTree({}, harness.sessionContext);
+  assert.equal(runBeforeAgentStart(harness).includes(compatibilityMarker), true);
+});
+
+test("/ars-pi-start and /ars-pi-stop toggle automatic invocation", async () => {
+  const harness = createHarness();
+  const start = harness.commands.get("ars-pi-start");
+  const stop = harness.commands.get("ars-pi-stop");
+
+  assert.ok(start);
+  await start.handler("", harness.commandContext);
+  assert.equal(runBeforeAgentStart(harness).includes(compatibilityMarker), true);
+  for (const location of arsSkillLocations) {
+    assert.equal(runBeforeAgentStart(harness).includes(location), true);
+  }
+
+  await stop.handler("", harness.commandContext);
+  assert.equal(runBeforeAgentStart(harness).includes(compatibilityMarker), false);
+  for (const location of arsSkillLocations) {
+    assert.equal(runBeforeAgentStart(harness).includes(location), false);
+  }
+});

package/vendor/ars/pyproject.toml

@@ -0,0 +1,2 @@
+[tool.pytest.ini_options]
+pythonpath = ["."]

package/vendor/ars/requirements-pdf-content-classifier.txt

@@ -0,0 +1,5 @@
+# Optional, opt-in dependency for scripts/pdf_content_classifier_worker.py.
+# Kept out of requirements-dev.txt so the dependency-absent path remains a
+# supported deterministic state and the native parser is never imported by the
+# structural preflight process.
+pdf-inspector==0.2.6