@polygraph/opencode-plugin 0.4.50 → 0.5.0

package/README.md

@@ -61,7 +61,7 @@ Neither is required — they are a throughput optimization, not a correctness fi
 ## Skills
 
 - **polygraph** — Comprehensive guidance for Polygraph sessions: shared context, repository graph visibility, PR/CI state, delegation, and session management.
-- **adversarial-review** — Second-opinion review of a session's work by independent reviewer agents, one per repo, running under a read-only `reviewer` role.
+- **adversarial-review** — Second-opinion review by independent per-repo agents that presents and attaches one consolidated review artifact.
 - **await-polygraph-ci** — Wait for CI pipelines to settle across all repos in a session, investigate failures, and present fix options.
 - **get-latest-ci** — One-shot fetch of the latest CI pipeline execution for the current branch.
 - **session-debrief** — Analyze the raw logs of past Polygraph sessions and produce structured, rank-ordered debriefs for use in a different session.
@@ -82,6 +82,18 @@ npm install
 npm run sync-artifacts
 ```
 
+Estimate the compiled prompt cost of every skill and subagent for Claude Code,
+Codex, and OpenCode:
+
+```sh
+npm run report:token-costs
+```
+
+The report uses four characters per estimated token by default. Override the
+ratio when needed with `npm run report:token-costs -- --characters-per-token 3.5`.
+Pull requests run the same report when opened or updated and keep the latest
+results in a single collapsible comment.
+
 ## Releasing
 
 Run the `Release PR` GitHub Actions workflow with a version bump (`patch`, `minor`, or `major`).

package/agent-session-link.mjs

@@ -1,10 +1,10 @@
 // source/hooks/agent-session-link.mjs
 import { appendFileSync, mkdirSync, renameSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { spawnSync } from "node:child_process";
 var HOOK_LOG_MAX_BYTES = 5 * 1024 * 1024;
-var AGENT_TYPES = /* @__PURE__ */ new Set(["claude", "codex", "opencode"]);
+var AGENT_TYPES = /* @__PURE__ */ new Set(["claude", "codex", "opencode", "cursor"]);
 var COMMAND_HOOK_TOOL = /^mcp__(?:plugin_polygraph_)?polygraph[-_]mcp__/;
 var OPENCODE_TOOL = /^polygraph(?:(?:-|_)mcp)?_/;
 function nonEmptyString(value) {
@@ -24,7 +24,8 @@ function buildLinkAgentSessionArgs({
   cwd,
   transcriptPath,
   pid,
-  source
+  source,
+  hookOperation
 }) {
   const session = nonEmptyString(polygraphSessionId);
   const harnessSession = nonEmptyString(agentSessionId);
@@ -42,23 +43,37 @@ function buildLinkAgentSessionArgs({
   if (Number.isSafeInteger(pid) && pid > 0) {
     args.push("--pid", String(pid));
   }
+  let input;
+  if (hookOperation && typeof hookOperation === "object") {
+    args.push("--hook-operation-stdin");
+    input = JSON.stringify(hookOperation);
+  }
   args.push("--source", claimSource);
-  return args;
+  return { args, input };
+}
+function nodeRuntime() {
+  const base = basename(process.execPath).toLowerCase();
+  return base === "node" || base === "node.exe" ? process.execPath : "node";
 }
 function linkAgentSession(claim, spawn = spawnSync, env = process.env) {
   if (isManagedChildEnvironment(env)) return false;
-  const args = buildLinkAgentSessionArgs(claim);
+  const { args, input } = buildLinkAgentSessionArgs(claim);
   const command = nonEmptyString(env?.POLYGRAPH_CLI) ?? "polygraph";
   const commandEnv = nonEmptyString(claim.polygraphSessionId) ? env : { ...env };
   if (commandEnv !== env) {
     delete commandEnv.POLYGRAPH_SESSION_ID;
     delete commandEnv.POLYGRAPH_CAPTURE_TOKEN;
   }
-  const result = spawn(command, args, {
+  const spawnOptions = {
     encoding: "utf8",
     env: commandEnv,
-    stdio: ["ignore", "ignore", "pipe"]
-  });
+    stdio: [input === void 0 ? "ignore" : "pipe", "ignore", "pipe"],
+    ...input === void 0 ? {} : { input }
+  };
+  let result = spawn(command, args, spawnOptions);
+  if (result?.error && /\.[cm]?js$/i.test(command)) {
+    result = spawn(nodeRuntime(), [command, ...args], spawnOptions);
+  }
   if (result?.error) throw result.error;
   if (result?.status !== 0) {
     const detail = nonEmptyString(result?.stderr);

package/frontmatter.mjs

@@ -0,0 +1,17 @@
+import matter from '@11ty/gray-matter';
+
+export function parseFrontmatter(raw, sourcePath) {
+  try {
+    const { data, content } = matter(raw);
+    return { data: data ?? {}, content };
+  } catch (error) {
+    if (!sourcePath) {
+      throw error;
+    }
+
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to parse frontmatter in ${sourcePath}: ${message}`, {
+      cause: error,
+    });
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polygraph/opencode-plugin",
-  "version": "0.4.50",
+  "version": "0.5.0",
   "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
   "license": "UNLICENSED",
   "private": false,
@@ -25,6 +25,7 @@
   "files": [
     "server.js",
     "agent-session-link.mjs",
+    "frontmatter.mjs",
     "skills/",
     "agents/",
     "README.md"
@@ -35,6 +36,6 @@
   },
   "main": "./server.js",
   "dependencies": {
-    "js-yaml": "^4.1.1"
+    "@11ty/gray-matter": "3.0.0"
   }
 }

package/server.js

@@ -12,7 +12,6 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import yaml from 'js-yaml';
 
 import {
   createOpenCodeSessionLinker,
@@ -20,6 +19,7 @@ import {
   linkOpenCodeSessionCreatedEvent,
   logHookFailure,
 } from './agent-session-link.mjs';
+import { parseFrontmatter } from './frontmatter.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = __dirname;
@@ -110,7 +110,7 @@ function loadAgents() {
 
     const name = path.basename(entry.name, '.md');
     const raw = readFileSync(path.join(agentsDir, entry.name), 'utf8');
-    const { data, content } = parseFrontmatter(raw);
+    const { data, content } = parseFrontmatter(raw, entry.name);
     const description = stringValue(data.description);
     if (!description) {
       throw new Error(`OpenCode agent ${entry.name} must define a description`);
@@ -130,18 +130,6 @@ function loadAgents() {
   return result;
 }
 
-function parseFrontmatter(raw) {
-  const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
-  if (!match) {
-    return { data: {}, content: raw };
-  }
-
-  return {
-    data: recordValue(yaml.load(match[1])) ?? {},
-    content: match[2],
-  };
-}
-
 function stringValue(value) {
   return typeof value === 'string' ? value : undefined;
 }

package/skills/adversarial-review/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: adversarial-review
-description: Independent second-opinion review of a Polygraph session's work. USE WHEN user says "adversarial review", "review this session", or when the Polygraph CLI launches an agent with an instruction to load this skill.
+description: Review a Polygraph session with independent per-repo reviewers and attach one consolidated review artifact.
 
 ---
 
 # Adversarial Review
 
-1. **Pick the agent.** Ask whether Claude, Codex, or OpenCode should review — `claude`, `codex`, or `opencode` for `spawn_agent`'s `agent` parameter. Skip if the user already named one.
+1. Skip this step entirely if a reviewer agent was already named — by the user, or in the instruction that launched you (e.g. from `polygraph session review --adversarial`); in that case use that agent and do not ask. Otherwise, **pick the agent**: Ask which should review—`claude`, `codex`, or `opencode` for `spawn_agent`'s `agent` parameter. If the user names a model, pass it via `spawn_agent`'s optional `model` parameter; don't ask about models.
 2. **Get the session description.**
-3. **Get each repo's plan.** Ask each repo's agent to provide the plan.
-4. **Delegate one reviewer per repo** in parallel, with `role: "reviewer"`. Pass the overall plan and that repo's plan, and ask it to review the code, identify issues, and return a summary. Do the delegation even for the "initiator" repo.
-5. **Summarize.** Once every review is back, analyze them and present one summary to the user.
-6. **Ask what next.** Address the feedback, upload the summary via `upload_artifact`, or continue with the session. Skip if the user already said.
+3. **Get each repo's plan.**
+4. **Delegate one reviewer per repo** in parallel, `role: "reviewer"`. Ask to review, identify issues. Do the delegation even for the "initiator" repo.
+5. **Summarize and attach.** Consolidate reviews into one consolidated Markdown review with per-repo sections and present it to the user. Then call `upload_artifact` once with `sessionId`, that review as `content`, `kind: "review"`, `format: "markdown"`, name `adversarial-review-YYYY-MM-DDTHH-mm-ssZ.md`. If the upload fails, report that separately without suppressing the review.
+6. **Ask what next.** Address feedback or continue. Skip if the user already said.
 7. If the user selects "address the feedback", pass each repo's feedback to the repo default agent (not the reviewer). The initiator should fix things itself without delegating.

package/skills/polygraph/reference/delegation.md

@@ -20,10 +20,14 @@ spawn_agent(
   repo: "<org/repo-name>",
   instruction: "<the task instruction>",
   role: "<optional role>",
-  context: "<optional context>"
+  context: "<optional context>",
+  agent: "<optional: claude | codex | opencode>",
+  model: "<optional model override>"
 )
 ```
 
+`agent` picks the child's harness and `model` overrides its default model; include either only when the user named one.
+
 Write the instruction as if to a competent engineer who cannot see your conversation: state the goal, the constraints, and what "done" looks like. The child has its own repo and its own context; it inherits nothing from yours.
 
 Delegate to several repos in parallel by calling `spawn_agent` once per repo before waiting on any of them.
@@ -36,7 +40,12 @@ For each id, launch one background poller subagent whose entire job is to block
 
 - **Claude Code** — a background `Task` with `subagent_type: "polygraph:polygraph-delegate-subagent"`, `run_in_background: true`, and description `Delegate to <repo>`. Fall back to the bare agent name only if the namespaced form is not found.
 - **OpenCode** — invoke `@polygraph-delegate-subagent`.
-- **Codex** — launch `agent_type: "polygraph-delegate-subagent"` via Codex's own `spawn_agent`, and collect it with `wait_agent`.
+- **Codex** — launch `agent_type: "polygraph-delegate-subagent"` via Codex's own `spawn_agent`, and collect it with `wait_agent`, passing a long `timeout_ms` (five minutes or more): `wait_agent` returns as soon as the poller stops, so a short timeout only adds wake-ups that burn tokens and fill the user-visible transcript with waiting noise.
+- **Cursor** — a background `Task` with `subagent_type: "polygraph-delegate-subagent"`, `run_in_background: true`, and description `Delegate to <repo>`. Collect it with `Await`.
+
+A collect step that returns while the poller subagent is still running has not failed. It has only reached the end of its collection window. Collect the same background-task id again, as many times as it takes for the poller subagent to stop. A poller that runs for several minutes is ordinary, and it is never a reason to take the wait back into the main conversation.
+
+The background-task id is the handle your own harness returned when you launched the poller. It is not the Polygraph delegation id (`frontend-1`), which addresses the child agent. Once the poller subagent has finished, do not collect it again: read the child instead, as described below. A child that stops for attention also ends the poller, so treat that as a finished poller and not as a collection window running out.
 
 The poller has exactly one tool and cannot read logs. It exits with a few lines naming the repo, the id, and the final status. That message is a doorbell, not a report — it tells you the child is worth reading, and nothing about what the child did.