@polygraph/opencode-plugin 0.4.29 → 0.4.31

package/agent-capture-mapping.mjs

@@ -0,0 +1,90 @@
+// Agent-capture mapping writer for the OpenCode plugin.
+// Exported from this sibling module (NOT from server.js) so it can be tested
+// independently. See server.js for the constraint on why server.js itself must
+// stay export-free beyond its plugin entry.
+//
+// Records the (agentSessionId ↔ polygraphSessionId) mapping file so the
+// Polygraph CLI can bind parent-log capture deterministically. Written on
+// every session start and compaction; the CLI reader looks for mapping-*.json
+// files in the per-session sidecars directory.
+//
+// File contract:
+//   ~/.polygraph/sidecars/<POLYGRAPH_SESSION_ID>/mapping-opencode-<sessionId>.json
+//
+// Behaviour:
+//   - Silent no-op when POLYGRAPH_SESSION_ID is unset or POLYGRAPH_CHILD_AGENT is set.
+//   - Atomic write via tmp-file rename.
+//   - Refresh: preserves firstSeenAt when a valid prior mapping exists.
+//   - All failures are silently swallowed.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+function sanitizeMappingFilename(str) {
+  return str.replace(/[^A-Za-z0-9._-]/g, '_');
+}
+
+/**
+ * Write (or refresh) the agent-capture mapping for an OpenCode session.
+ * Reads POLYGRAPH_SESSION_ID and POLYGRAPH_CHILD_AGENT from process.env.
+ *
+ * @param {string} agentSessionId  The OpenCode session id (input.sessionID).
+ * @param {string} [home]          Override HOME for testing.
+ */
+export function writeAgentCaptureMapping(
+  agentSessionId,
+  home = process.env.HOME?.trim() || homedir()
+) {
+  try {
+    const polygraphSessionId = process.env.POLYGRAPH_SESSION_ID;
+    if (!polygraphSessionId) return;
+    if (process.env.POLYGRAPH_CHILD_AGENT) return;
+    if (!agentSessionId) return;
+
+    const sidecarDir = path.join(home, '.polygraph', 'sidecars', polygraphSessionId);
+    mkdirSync(sidecarDir, { recursive: true });
+
+    const filenamePart = sanitizeMappingFilename(`opencode-${agentSessionId}`);
+    const finalPath = path.join(sidecarDir, `mapping-${filenamePart}.json`);
+    const tmpPath = `${finalPath}.tmp-${process.pid}`;
+
+    const now = Date.now();
+    let firstSeenAt = now;
+
+    if (existsSync(finalPath)) {
+      try {
+        const existing = JSON.parse(readFileSync(finalPath, 'utf8'));
+        if (
+          existing.version === 1 &&
+          existing.polygraphSessionId === polygraphSessionId &&
+          existing.agentSessionId === agentSessionId &&
+          Number.isFinite(existing.firstSeenAt)
+        ) {
+          firstSeenAt = existing.firstSeenAt;
+        }
+      } catch {
+        // ignore — treat as missing
+      }
+    }
+
+    const mapping = {
+      version: 1,
+      polygraphSessionId,
+      agentType: 'opencode',
+      agentSessionId,
+      cwd: process.cwd(),
+      // OpenCode transcripts are resolved by the CLI from its own storage by
+      // session id, so we omit transcriptPath here.
+      pid: process.pid,
+      source: 'hook',
+      firstSeenAt,
+      lastSeenAt: now,
+    };
+
+    writeFileSync(tmpPath, JSON.stringify(mapping, null, 2) + '\n');
+    renameSync(tmpPath, finalPath);
+  } catch {
+    // Silent — a broken plugin hook must never break the agent session.
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polygraph/opencode-plugin",
-  "version": "0.4.29",
+  "version": "0.4.31",
   "description": "AI agent skills and subagents for Polygraph multi-repo coordination",
   "license": "UNLICENSED",
   "private": false,
@@ -24,6 +24,7 @@
   },
   "files": [
     "server.js",
+    "agent-capture-mapping.mjs",
     "skills/",
     "agents/",
     "README.md"

package/server.js

@@ -1,9 +1,21 @@
+// ⚠️  IMPORTANT — READ BEFORE EDITING OR ADDING CODE TO THIS FILE ⚠️
+//
+// OpenCode loads this file directly as a plugin module. Any `export` beyond
+// the plugin entry (`PolygraphPlugin` / `export default`) breaks OpenCode
+// plugin loading ENTIRELY for every user who has the plugin installed.
+//
+// DO NOT add new exports to this file. Put shared or testable logic in sibling
+// modules under source/opencode/ (e.g. agent-capture-mapping.mjs) and import
+// it here instead.
+
 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 { writeAgentCaptureMapping } from './agent-capture-mapping.mjs';
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = __dirname;
 const skillsDir = path.join(packageRoot, 'skills');
@@ -29,6 +41,9 @@ export const PolygraphPlugin = async () => {
     'shell.env': async (input, output) => {
       output.env.POLYGRAPH_AGENT_SESSION_ID = input.sessionID;
       output.env.POLYGRAPH_AGENT_TYPE = 'opencode';
+      // Record the agent-capture mapping so the Polygraph CLI can bind
+      // parent-log capture deterministically for this session.
+      writeAgentCaptureMapping(input.sessionID);
     },
 
     // OpenCode has no SessionStart hook, but the Polygraph CLI already seeds the
@@ -41,6 +56,9 @@ export const PolygraphPlugin = async () => {
       if (note) {
         output.context.push(note);
       }
+      // Refresh the mapping on compaction (same refresh semantics as Claude/Codex
+      // SessionStart hooks firing on 'compact').
+      writeAgentCaptureMapping(input.sessionID);
     },
   };
 };