@polygraph/codex-plugin 0.4.40 → 0.4.41

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "polygraph",
-  "version": "0.4.40",
+  "version": "0.4.41",
   "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
   "author": {
     "name": "Narwhal Technologies Inc",

package/README.md

@@ -46,6 +46,7 @@ It detects your AI agent — Claude Code, Codex, OpenCode, and more — and inst
 
 - **polygraph-init-subagent** — Discovers candidate repositories and initializes a Polygraph session
 - **polygraph-delegate-subagent** — Delegates work to a child agent in another repository, polls for completion
+- **session-debrief** — Analyzes the raw logs of past Polygraph sessions and returns a structured, rank-ordered debrief for the current task
 
 ## Development
 

package/agents/session-debrief.toml

@@ -0,0 +1,24 @@
+name = "session-debrief"
+description = "Analyze the raw logs of one or more past Polygraph sessions and return a structured, rank-ordered debrief for the current task. Launch as a background agent with a ranked list of relevant Polygraph session IDs/lines and a one-paragraph statement of the current task; it invokes the session-debrief skill, pulls parent and child transcripts via the polygraph CLI, and returns one consolidated debrief. Read-only with respect to the inspected sessions."
+developer_instructions = '''
+# Session Debrief Subagent
+
+You produce debriefs of PAST Polygraph sessions so a parent agent working on a NEW task can decide what context is relevant. You run in the background and speed matters — the parent keeps working while it waits and folds your debrief in whenever it lands.
+
+You are READ-ONLY with respect to the inspected sessions: never resume them, never spawn agents into them, never push branches, create PRs, or update their descriptions.
+
+## Input Parameters (from Main Agent)
+
+The main agent provides these in the prompt:
+
+| Parameter     | Description                                                                                       |
+| ------------- | ------------------------------------------------------------------------------------------------ |
+| `sessions`    | A ranked list of relevant Polygraph sessions (IDs/lines, most relevant first, with optional titles/URLs) |
+| `currentTask` | A one-paragraph statement of the task the parent is currently working on                         |
+
+## What to do
+
+Invoke the `session-debrief` skill and follow its procedure and output template exactly. Pass through the ranked session list and the current-task statement you received. The skill is the single source of truth for how to pull transcripts via the polygraph CLI, how to fan out across multiple sessions, and how to format each debrief section — do not reinvent or duplicate that procedure here.
+
+Return the consolidated, rank-ordered debrief as your final message.
+'''

package/bin/polygraph-codex-plugin.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // source/codex/lib/installer.mjs
+import { spawnSync } from "node:child_process";
 import {
   cpSync,
   existsSync,
@@ -35,10 +36,19 @@ function resolveUserHome(env = process.env) {
   const userHome = env.HOME?.trim() || homedir();
   return resolve(expandHome(userHome, env));
 }
-function getMarketplacePath(userHome) {
+function getMarketplaceRoot(userHome) {
+  return join(userHome, ".polygraph", "codex-marketplace");
+}
+function getMarketplacePath(marketplaceRoot) {
+  return join(marketplaceRoot, ".agents", "plugins", "marketplace.json");
+}
+function getPluginInstallPath(marketplaceRoot) {
+  return join(marketplaceRoot, "plugins", PLUGIN_NAME);
+}
+function getLegacyMarketplacePath(userHome) {
   return join(userHome, ".agents", "plugins", "marketplace.json");
 }
-function getPluginInstallPath(userHome) {
+function getLegacyPluginInstallPath(userHome) {
   return join(userHome, ".agents", "plugins", PLUGIN_NAME);
 }
 function loadPackageMetadata(packageRoot) {
@@ -74,7 +84,9 @@ function loadPackageMetadata(packageRoot) {
 function installPlugin({
   packageRoot,
   env = process.env,
-  force = false
+  force = false,
+  // Injectable so tests do not have to shell out to a real codex binary.
+  register = registerMarketplace
 } = {}) {
   if (!packageRoot) {
     throw new Error("packageRoot is required");
@@ -83,8 +95,9 @@ function installPlugin({
   const codexHome = resolveCodexHome(env);
   const userHome = resolveUserHome(env);
   const agentsPath = getAgentsPath(codexHome);
-  const marketplacePath = getMarketplacePath(userHome);
-  const pluginPath = getPluginInstallPath(userHome);
+  const marketplaceRoot = getMarketplaceRoot(userHome);
+  const marketplacePath = getMarketplacePath(marketplaceRoot);
+  const pluginPath = getPluginInstallPath(marketplaceRoot);
   const installAlreadyPresent = existsSync(pluginPath);
   let previousVersion = null;
   if (installAlreadyPresent) {
@@ -117,15 +130,20 @@ function installPlugin({
     copied = true;
   }
   const agentsChanged = installCodexAgents({ packageRoot, agentsPath });
-  const marketplaceChanged = enablePluginInMarketplace({
+  const marketplaceChanged = writeMarketplaceManifest({
     marketplacePath,
-    pluginPath,
-    userHome
+    marketplaceRoot,
+    pluginPath
   });
+  const legacyCleanup = cleanLegacyMarketplaceEntry({ userHome });
+  const registration = register({ marketplaceRoot, env });
   return {
     ok: true,
     action: "install",
     plugin: PLUGIN_ID,
+    marketplaceName: MARKETPLACE_NAME,
+    marketplaceRoot,
+    marketplaceRegistered: registration.registered,
     version,
     codexHome,
     agentsPath,
@@ -136,9 +154,68 @@ function installPlugin({
     pluginUpdated: installAlreadyPresent && versionMismatch && !force,
     previousVersion,
     agentsChanged,
-    marketplaceChanged
+    marketplaceChanged,
+    legacyEntryRemoved: legacyCleanup.entryRemoved,
+    legacyMarketplaceRemoved: legacyCleanup.fileRemoved,
+    ...registration.error ? { marketplaceRegistrationError: registration.error } : {}
   };
 }
+function registerMarketplace({ marketplaceRoot, env = process.env }) {
+  const result = spawnSync(
+    "codex",
+    ["plugin", "marketplace", "add", marketplaceRoot, "--json"],
+    { encoding: "utf8", env }
+  );
+  if (result.error) {
+    return {
+      registered: false,
+      error: `Could not run \`codex\`: ${result.error.message}. Run \`codex plugin marketplace add ${marketplaceRoot}\` once codex is available.`
+    };
+  }
+  if (result.status !== 0) {
+    return {
+      registered: false,
+      error: `\`codex plugin marketplace add\` failed: ${(result.stderr || "").trim()}`
+    };
+  }
+  return { registered: true };
+}
+function cleanLegacyMarketplaceEntry({ userHome }) {
+  const legacyPath = getLegacyMarketplacePath(userHome);
+  const unchanged = { entryRemoved: false, fileRemoved: false };
+  if (!existsSync(legacyPath)) {
+    return unchanged;
+  }
+  let marketplace;
+  try {
+    marketplace = readJsonFile(legacyPath);
+  } catch {
+    return unchanged;
+  }
+  if (!isPlainObject(marketplace) || !Array.isArray(marketplace.plugins)) {
+    return unchanged;
+  }
+  const remaining = marketplace.plugins.filter(
+    (plugin) => plugin?.name !== PLUGIN_NAME
+  );
+  if (remaining.length === marketplace.plugins.length) {
+    return unchanged;
+  }
+  if (remaining.length === 0 && marketplace.name === MARKETPLACE_NAME) {
+    rmSync(legacyPath, { force: true });
+    rmSync(getLegacyPluginInstallPath(userHome), {
+      recursive: true,
+      force: true
+    });
+    return { entryRemoved: true, fileRemoved: true };
+  }
+  writeJsonFile(legacyPath, { ...marketplace, plugins: remaining });
+  rmSync(getLegacyPluginInstallPath(userHome), {
+    recursive: true,
+    force: true
+  });
+  return { entryRemoved: true, fileRemoved: false };
+}
 function checkInstall({ packageRoot, env = process.env } = {}) {
   let version = null;
   if (packageRoot) {
@@ -147,29 +224,46 @@ function checkInstall({ packageRoot, env = process.env } = {}) {
   const codexHome = resolveCodexHome(env);
   const userHome = resolveUserHome(env);
   const agentsPath = getAgentsPath(codexHome);
-  const marketplacePath = getMarketplacePath(userHome);
-  const pluginPath = getPluginInstallPath(userHome);
+  const marketplaceRoot = getMarketplaceRoot(userHome);
+  const marketplacePath = getMarketplacePath(marketplaceRoot);
+  const pluginPath = getPluginInstallPath(marketplaceRoot);
   const pluginInstalled = isValidInstalledPluginDir(pluginPath);
   const agentsInstalled = packageRoot ? areCodexAgentsInstalled({ packageRoot, agentsPath }) : hasDefaultCodexAgents(agentsPath);
   const marketplaceConfigured = isPluginConfiguredInMarketplace({
     marketplacePath,
-    userHome,
+    marketplaceRoot,
     pluginPath
   });
-  const ok = pluginInstalled && agentsInstalled && marketplaceConfigured;
+  const legacyMarketplacePresent = hasLegacyPluginEntry({ userHome });
+  const ok = pluginInstalled && agentsInstalled && marketplaceConfigured && !legacyMarketplacePresent;
   return {
     ok,
     action: "check",
     plugin: PLUGIN_ID,
+    marketplaceName: MARKETPLACE_NAME,
+    marketplaceRoot,
     codexHome,
     agentsPath,
     pluginPath,
     marketplacePath,
     pluginInstalled,
     agentsInstalled,
-    marketplaceConfigured
+    marketplaceConfigured,
+    legacyMarketplacePresent
   };
 }
+function hasLegacyPluginEntry({ userHome }) {
+  const legacyPath = getLegacyMarketplacePath(userHome);
+  if (!existsSync(legacyPath)) {
+    return false;
+  }
+  try {
+    const marketplace = readJsonFile(legacyPath);
+    return Array.isArray(marketplace?.plugins) && marketplace.plugins.some((plugin) => plugin?.name === PLUGIN_NAME);
+  } catch {
+    return false;
+  }
+}
 function getPackagePayloadPaths(packageRoot, packageJson) {
   const relativePaths = new Set(packageJson.files ?? []);
   relativePaths.add("package.json");
@@ -234,44 +328,30 @@ function hasDefaultCodexAgents(agentsPath) {
     (agentFile) => existsSync(join(agentsPath, agentFile))
   );
 }
-function enablePluginInMarketplace({
+function writeMarketplaceManifest({
   marketplacePath,
-  pluginPath,
-  userHome
+  marketplaceRoot,
+  pluginPath
 }) {
-  const marketplace = readJsonFile(marketplacePath, {});
-  if (marketplace.plugins !== void 0 && !Array.isArray(marketplace.plugins)) {
-    throw new Error(`Expected plugins array in ${marketplacePath}`);
-  }
-  const marketplacePluginPath = toMarketplaceSourcePath(userHome, pluginPath);
-  const nextPluginEntry = {
-    name: PLUGIN_NAME,
-    source: {
-      source: "local",
-      path: marketplacePluginPath
-    },
-    policy: {
-      installation: "AVAILABLE",
-      authentication: "ON_INSTALL"
-    },
-    category: "Productivity"
-  };
-  const plugins = marketplace.plugins ?? [];
-  const existingIndex = plugins.findIndex(
-    (plugin) => plugin?.name === PLUGIN_NAME
-  );
-  const nextPlugins = existingIndex === -1 ? [...plugins, nextPluginEntry] : plugins.map(
-    (plugin, index) => index === existingIndex ? nextPluginEntry : plugin
-  );
   const nextMarketplace = {
-    ...marketplace,
-    name: marketplace.name ?? MARKETPLACE_NAME,
-    interface: isPlainObject(marketplace.interface) ? {
-      ...marketplace.interface,
-      displayName: marketplace.interface.displayName ?? MARKETPLACE_DISPLAY_NAME
-    } : { displayName: MARKETPLACE_DISPLAY_NAME },
-    plugins: nextPlugins
+    name: MARKETPLACE_NAME,
+    interface: { displayName: MARKETPLACE_DISPLAY_NAME },
+    plugins: [
+      {
+        name: PLUGIN_NAME,
+        source: {
+          source: "local",
+          path: toMarketplaceSourcePath(marketplaceRoot, pluginPath)
+        },
+        policy: {
+          installation: "AVAILABLE",
+          authentication: "ON_INSTALL"
+        },
+        category: "Productivity"
+      }
+    ]
   };
+  const marketplace = readJsonFile(marketplacePath, null);
   const changed = JSON.stringify(nextMarketplace) !== JSON.stringify(marketplace);
   if (changed) {
     writeJsonFile(marketplacePath, nextMarketplace);
@@ -280,13 +360,21 @@ function enablePluginInMarketplace({
 }
 function isPluginConfiguredInMarketplace({
   marketplacePath,
-  userHome,
+  marketplaceRoot,
   pluginPath
 }) {
   if (!existsSync(marketplacePath)) {
     return false;
   }
-  const marketplace = readJsonFile(marketplacePath);
+  let marketplace;
+  try {
+    marketplace = readJsonFile(marketplacePath);
+  } catch {
+    return false;
+  }
+  if (marketplace?.name !== MARKETPLACE_NAME) {
+    return false;
+  }
   if (!Array.isArray(marketplace.plugins)) {
     return false;
   }
@@ -296,7 +384,7 @@ function isPluginConfiguredInMarketplace({
   if (!isPlainObject(pluginEntry?.source) || pluginEntry.source.source !== "local") {
     return false;
   }
-  const configuredPath = resolve(userHome, pluginEntry.source.path);
+  const configuredPath = resolve(marketplaceRoot, pluginEntry.source.path);
   return configuredPath === resolve(pluginPath);
 }
 function readJsonFile(path, fallbackValue) {
@@ -341,11 +429,11 @@ function expandHome(inputPath, env) {
   }
   return inputPath;
 }
-function toMarketplaceSourcePath(userHome, targetPath) {
-  const relativePath = relative(userHome, targetPath);
+function toMarketplaceSourcePath(marketplaceRoot, targetPath) {
+  const relativePath = relative(marketplaceRoot, targetPath);
   if (relativePath === "" || relativePath === "." || relativePath.startsWith(`..${sep}`) || relativePath === "..") {
     throw new Error(
-      `Expected plugin install path ${targetPath} to be inside ${userHome} so it can be referenced from the personal marketplace`
+      `Expected plugin install path ${targetPath} to be inside ${marketplaceRoot} so it can be referenced from the marketplace manifest`
     );
   }
   return `./${relativePath.split(sep).join("/")}`;
@@ -360,8 +448,10 @@ var usage = `Usage:
   npx @polygraph/codex-plugin install [--force] [--json]
   npx @polygraph/codex-plugin check [--json]
 
-The install command materializes the plugin payload so that codex's official
-plugin system can pick it up. After running install, run:
+The install command materializes the plugin payload into the marketplace Polygraph
+owns (~/.polygraph/codex-marketplace) and registers that marketplace with codex.
+It does not write to the shared ~/.agents/plugins/marketplace.json. After running
+install, run:
 
   codex plugin add polygraph@polygraph-plugins
 
@@ -408,17 +498,30 @@ ${usage}`);
     } else {
       const pluginState = result.pluginInstalled ? "plugin files present" : "plugin files not present";
       const agentsState = result.agentsInstalled ? "agents installed" : "agents not installed";
-      const marketplaceState = result.marketplaceConfigured ? "plugin present in marketplace" : "plugin not present in marketplace";
+      const marketplaceState = result.marketplaceConfigured ? `plugin published from the ${result.marketplaceName} marketplace` : `plugin not published from the ${result.marketplaceName} marketplace`;
+      const legacyState = result.legacyMarketplacePresent ? "; a stale entry remains in ~/.agents/plugins/marketplace.json (re-run install to clear it)" : "";
       console.error(
-        `Polygraph Codex plugin check failed: ${pluginState}; ${agentsState}; ${marketplaceState}.`
+        `Polygraph Codex plugin check failed: ${pluginState}; ${agentsState}; ${marketplaceState}${legacyState}.`
       );
     }
   } else {
     console.log(`Materialized Polygraph Codex plugin ${result.version}.`);
     console.log(`Plugin path: ${result.pluginPath}`);
     console.log(`Agents: ${result.agentsPath}`);
-    console.log(`Marketplace: ${result.marketplacePath}`);
-    console.log(`Next step: codex plugin add ${result.plugin}`);
+    console.log(`Marketplace: ${result.marketplaceName} (${result.marketplaceRoot})`);
+    if (result.legacyEntryRemoved) {
+      console.log(
+        result.legacyMarketplaceRemoved ? "Removed the obsolete ~/.agents/plugins/marketplace.json written by an earlier version." : "Removed the obsolete polygraph entry from ~/.agents/plugins/marketplace.json; your other plugins were left untouched."
+      );
+    }
+    if (result.marketplaceRegistered) {
+      console.log(`Next step: codex plugin add ${result.plugin}`);
+    } else {
+      console.warn(`Warning: ${result.marketplaceRegistrationError}`);
+      console.warn(
+        `Then run: codex plugin add ${result.plugin}`
+      );
+    }
   }
   if (command === "check" && !result.ok) {
     process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polygraph/codex-plugin",
-  "version": "0.4.40",
+  "version": "0.4.41",
   "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
   "license": "UNLICENSED",
   "private": false,