@essentialai/cogent-plugin 3.20.7 → 3.21.1

package/hooks/check-on-stop.lib.mjs

@@ -3,6 +3,7 @@
 // defaultCredentialPath. Kept separate from the runtime (check-on-stop.mjs) so it is
 // unit-tested (plugin/hooks/check-on-stop.lib.test.mjs, gate-counted via vitest include).
 import crypto from "node:crypto";
+import os from "node:os";
 import path from "node:path";
 
 /** MUST equal src/services/auto-relay.ts:629 — human-origin broadcasts only. */
@@ -25,6 +26,64 @@ export function credHashForCwd(cwd) {
   return crypto.createHash("sha256").update(path.resolve(cwd)).digest("hex").slice(0, 16);
 }
 
+/**
+ * MUST equal src/services/agent-sessions.ts rootFromTranscriptPath.
+ *
+ * Recovers the agent's config ROOT from an absolute transcript path by STRUCTURE
+ * (`<root>/projects/<encoded-cwd>/<id>.jsonl`) rather than by matching a known
+ * prefix — which is the whole point: a root nobody has ever seen still resolves.
+ */
+export function rootFromTranscriptPath(transcriptPath) {
+  if (!transcriptPath) return null;
+  const parts = path.resolve(transcriptPath).split(path.sep);
+  const i = parts.lastIndexOf("projects");
+  if (i <= 0) return null;
+  return parts.slice(0, i).join(path.sep) || path.sep;
+}
+
+/** MUST equal src/services/agent-sessions.ts agentSessionPath. */
+export function agentSessionRecordPath(cwd, platform) {
+  return path.join(
+    os.homedir(),
+    ".cogent",
+    "agent-sessions",
+    `${credHashForCwd(cwd)}.${platform}.json`,
+  );
+}
+
+/**
+ * Turn a hook payload into a learned session record — the AUTHORITATIVE answer to
+ * "where does this agent's transcript live". Pure; the caller does the write.
+ *
+ * The host hands every hook `cwd`, `session_id` and `transcript_path`. Persisting
+ * that trio removes both guesses the wake resolver used to make (which config root,
+ * and how the cwd was encoded into a directory name), so a relocated or otherwise
+ * unusual agent installation resolves without any configuration.
+ *
+ * `platform` is inferred STRUCTURALLY so this file can stay byte-identical across
+ * the Claude and Codex plugins: only Claude Code lays transcripts out under a
+ * `projects/` segment, so a recoverable root means Claude Code.
+ *
+ * Returns null when the payload lacks any of the three fields (some hosts/events
+ * omit them) — a partial record is worse than none, because it would look
+ * authoritative while pointing nowhere.
+ */
+export function buildAgentSessionRecord(payload, nowIso) {
+  const cwd = payload?.cwd;
+  const sessionId = payload?.session_id;
+  const transcriptPath = payload?.transcript_path;
+  if (!cwd || !sessionId || !transcriptPath) return null;
+  const root = rootFromTranscriptPath(transcriptPath);
+  return {
+    cwd: path.resolve(cwd),
+    sessionId: String(sessionId),
+    transcriptPath: path.resolve(transcriptPath),
+    ...(root ? { root } : {}),
+    platform: root ? "cc" : "codex",
+    updatedAt: nowIso,
+  };
+}
+
 function isForMe(msg, me, scope) {
   if (msg.toPeerId === me) return scope.directed;
   if (msg.toPeerId === "*") {

package/hooks/check-on-stop.mjs

@@ -18,6 +18,8 @@ import {
   buildBlockReason,
   credHashForCwd,
   activeInFlightIds,
+  agentSessionRecordPath,
+  buildAgentSessionRecord,
 } from "./check-on-stop.lib.mjs";
 
 const HTTP_TIMEOUT_MS = 5000; // < the 8s hook timeout; only bites on a degraded relay
@@ -104,9 +106,36 @@ async function peerIdFromState(env, cwd) {
   return byCwd ? byCwd.peerId : undefined;
 }
 
+/**
+ * Refresh the learned session record from this payload — the authoritative answer
+ * to "where does this agent's transcript live" (see record-session.mjs for the
+ * full rationale). Done here as well as on SessionStart because this hook already
+ * receives the payload on every turn, so the record stays correct for free even
+ * if the session was started before the plugin was installed. Best-effort and
+ * completely silent: it must never affect whether this hook blocks.
+ */
+async function refreshSessionRecord(input) {
+  try {
+    const record = buildAgentSessionRecord(input, new Date().toISOString());
+    if (!record) return;
+    const target = agentSessionRecordPath(record.cwd, record.platform);
+    await fsp.mkdir(path.dirname(target), { recursive: true });
+    const tmp = `${target}.${process.pid}.tmp`;
+    await fsp.writeFile(tmp, JSON.stringify(record, null, 2), "utf-8");
+    await fsp.rename(tmp, target);
+  } catch {
+    // learning is an optimisation, never a reason to change this hook's outcome
+  }
+}
+
 async function main() {
   const input = await readStdin();
 
+  // Record BEFORE the loop guard: a continuation turn still carries a valid
+  // transcript path, and skipping it would lose the refresh on exactly the turns
+  // where auto-wake is most active.
+  await refreshSessionRecord(input);
+
   // Loop guard: if we already caused this continuation, never block again.
   if (input && input.stop_hook_active === true) return process.exit(0);
 

package/hooks/hooks.json

@@ -1,5 +1,17 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/record-session.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "matcher": "",

package/hooks/record-session.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// Cogent record-session. Runs on SessionStart as a SEPARATE short-lived process
+// (the host spawns it; it is NOT the bridge). Writes one small file and exits 0.
+// ALWAYS silent — it prints nothing on success or failure, so it can never block,
+// delay, or annotate a turn.
+//
+// 🔴 WHY THIS EXISTS. Auto-wake has to find the agent's session transcript, and it
+// used to DERIVE the location:
+//
+//     <config root> / projects / <cwd with non-alphanumerics turned into dashes>
+//
+// Both halves are guesses. The root was `CLAUDE_CONFIG_DIR` or a hardcoded
+// `~/.claude`; the cwd half assumed the exact canonical spelling of the directory.
+// Users relocate agent state (small system disks, synced or encrypted homes,
+// multi-account machines, containers) and the env var does not always reach the
+// process that needs it. Either guess being wrong produced the same dead end:
+// "no candidate sessions found for cwd", and a refused wake.
+//
+// The host already knows the answer and hands it to every hook: `cwd`,
+// `session_id` and `transcript_path`. Recording that trio turns discovery from
+// inference into a lookup, and works with ANY custom location without config.
+//
+// Node built-ins only (fs, os, path). Byte-identical between plugin/hooks/ and
+// codex-plugin/hooks/ — enforced by scripts/wake-race-test.mjs assertContract().
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  agentSessionRecordPath,
+  buildAgentSessionRecord,
+} from "./check-on-stop.lib.mjs";
+
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Atomic temp+rename: the bridge may read this file at any moment, and a
+ * half-written record would look authoritative while pointing nowhere. The
+ * temp name carries the pid so two concurrent hooks cannot collide.
+ */
+export async function persistRecord(record) {
+  const target = agentSessionRecordPath(record.cwd, record.platform);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  const tmp = `${target}.${process.pid}.tmp`;
+  await fs.writeFile(tmp, JSON.stringify(record, null, 2), "utf-8");
+  await fs.rename(tmp, target);
+  return target;
+}
+
+async function main() {
+  const input = await readStdin();
+  const record = buildAgentSessionRecord(input, new Date().toISOString());
+  // No transcript_path in this payload → nothing authoritative to record. The
+  // resolver's discovery layer still covers this case; staying silent is correct.
+  if (!record) return;
+  await persistRecord(record);
+}
+
+// Best-effort by construction: recording is an optimisation for a LATER wake, so
+// nothing here may ever fail a turn. Any error exits 0 silently.
+main().then(
+  () => process.exit(0),
+  () => process.exit(0),
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@essentialai/cogent-plugin",
-  "version": "3.20.7",
+  "version": "3.21.1",
   "description": "Cogent — Claude Code plugin (skills + slash-commands + MCP server) for the cross-agent comms fabric.",
   "author": { "name": "Essential AI Solutions Ltd.", "url": "https://essentialai.uk" },
   "homepage": "https://cogent.tools",