portable-agent-layer 0.40.0 → 0.41.0

package/src/hooks/handlers/failure-principle.ts

@@ -0,0 +1,122 @@
+/**
+ * Failure-principle handler — extracts an actionable principle from a low-rated
+ * session via inference, then persists the failure record.
+ *
+ * Detached from the Stop hook (lib/stop.ts) because claude --print cold-start
+ * can exceed the Stop hook's reasonable budget. Parent writes pending data +
+ * transcript to tmp files, spawns this script with both paths, and returns
+ * immediately. Child reads, runs inference, calls captureFailure, and unlinks
+ * the tmp files.
+ */
+
+import { existsSync } from "node:fs";
+import { readFile, unlink } from "node:fs/promises";
+import { extractContent, parseMessages } from "../lib/transcript";
+import { captureFailure } from "./failure";
+
+interface PendingFailure {
+  rating: number;
+  context: string;
+  detailedContext?: string;
+  principle?: string;
+  responsePreview?: string;
+  userPreview?: string;
+  cwd?: string;
+}
+
+/**
+ * Inference the principle (if missing) and persist the failure record.
+ * Reads pending data + transcript from the provided tmp paths and unlinks them.
+ */
+async function processFailurePrinciple(
+  pendingPath: string,
+  transcriptPath: string
+): Promise<void> {
+  const { logDebug, logError } = await import("../lib/log");
+  try {
+    if (!existsSync(pendingPath) || !existsSync(transcriptPath)) {
+      logError(
+        "failure-principle",
+        `missing input: pending=${existsSync(pendingPath)} transcript=${existsSync(transcriptPath)}`
+      );
+      return;
+    }
+
+    const pending = JSON.parse(await readFile(pendingPath, "utf-8")) as PendingFailure;
+    const transcript = await readFile(transcriptPath, "utf-8");
+    logDebug("failure-principle", `processing rating=${pending.rating}`);
+
+    let { principle, detailedContext } = pending;
+    if (!principle) {
+      try {
+        const { inference } = await import("../lib/inference");
+        const msgs = parseMessages(transcript);
+        const recent = msgs
+          .slice(-10)
+          .map((m) => `${m.role.toUpperCase()}: ${extractContent(m).slice(0, 300)}`)
+          .join("\n\n");
+
+        const result = await inference({
+          system: `Analyze this failed AI interaction. The user rated it ${pending.rating}/10.
+
+Return JSON:
+{
+  "principle": "<one actionable rule the AI should follow, 10-20 words. Start with a verb: 'Verify...', 'Always...', 'Never...', 'Ask before...'>",
+  "detailed_context": "<what went wrong and why, 50-150 words>"
+}`,
+          user: `User feedback: ${pending.context}\n\nConversation:\n${recent}`,
+          maxTokens: 400,
+          timeout: 60000,
+          jsonSchema: {
+            type: "object" as const,
+            properties: {
+              principle: { type: "string" as const },
+              detailed_context: { type: "string" as const },
+            },
+            required: ["principle", "detailed_context"],
+            additionalProperties: false,
+          },
+          caller: "failure-principle",
+        });
+
+        if (result.success && result.output) {
+          const parsed = JSON.parse(result.output) as {
+            principle?: string;
+            detailed_context?: string;
+          };
+          principle = parsed.principle || undefined;
+          detailedContext ??= parsed.detailed_context || undefined;
+        } else {
+          logError("failure-principle", `inference failed (no output)`);
+        }
+      } catch (err) {
+        logError("failure-principle:inference", err);
+      }
+    }
+
+    await captureFailure(
+      pending.rating,
+      pending.context,
+      transcript,
+      detailedContext,
+      principle,
+      pending.cwd
+    );
+    logDebug("failure-principle", "captureFailure done");
+  } catch (err) {
+    logError("failure-principle", err);
+  } finally {
+    await unlink(pendingPath).catch(() => {});
+    await unlink(transcriptPath).catch(() => {});
+  }
+}
+
+// Detached child entry point
+if (process.argv[2] === "--run") {
+  const pendingPath = process.argv[3];
+  const transcriptPath = process.argv[4];
+  if (pendingPath && transcriptPath) {
+    await processFailurePrinciple(pendingPath, transcriptPath);
+  }
+  process.exit(0);
+}

package/src/hooks/handlers/rating.ts

@@ -10,7 +10,8 @@
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { inference } from "../lib/inference";
+import { spawnDetachedInference } from "../lib/detached-inference";
+import { canInfer, inference } from "../lib/inference";
 import { paths } from "../lib/paths";
 import { emitRating } from "../lib/signals";
 import { now } from "../lib/time";
@@ -284,13 +285,10 @@ function handleRating(
 
 // ── Implicit Sentiment ──
 
-async function handleImplicitSentiment(
-  message: string,
-  sessionId?: string
-): Promise<void> {
+function handleImplicitSentiment(message: string, sessionId?: string): void {
   const trimmed = message.trim();
 
-  // Fast-path: short praise -> rating 8
+  // Fast-path: short praise -> rating 8 (synchronous, no inference)
   if (isPraise(trimmed)) {
     handleRating(
       8,
@@ -311,27 +309,48 @@ async function handleImplicitSentiment(
   if (trimmed.length < 5 || trimmed.length > 500) return;
   if (/^[/$`{]/.test(trimmed) || trimmed.includes("\n\n")) return;
 
-  const lastResponse = getLastResponse(sessionId).slice(0, 300);
-  const contextBlock = lastResponse
-    ? `CONTEXT (last AI response excerpt):\n${lastResponse}\n\nCURRENT USER MESSAGE:\n${trimmed.slice(0, 300)}`
-    : trimmed.slice(0, 300);
-
-  const result = await inference({
-    system: SENTIMENT_SYSTEM_PROMPT,
-    user: contextBlock,
-    maxTokens: 500,
-    timeout: 8000,
-    jsonSchema: SENTIMENT_SCHEMA,
-  });
+  // Inference path — detach to background. claude --print has 3-5s of cold-start
+  // overhead per call; running inline would block UserPromptSubmit and exceed
+  // any reasonable in-line budget. Uses the shared detach helper.
+  if (!canInfer()) return;
+  const msgB64 = Buffer.from(trimmed.slice(0, 800)).toString("base64");
+  spawnDetachedInference(
+    import.meta.filename,
+    ["--sentiment", sessionId ?? "", msgB64],
+    "rating"
+  );
+}
 
-  if (result.usage) logTokenUsage("rating", result.usage);
+/**
+ * Background sentiment mode: called via --sentiment flag from a detached subprocess.
+ * Runs the heavy inference, parses the result, and writes the rating if confident.
+ */
+async function runSentimentInferenceAndStore(
+  message: string,
+  sessionId?: string
+): Promise<void> {
+  try {
+    const trimmed = message.trim();
+    const lastResponse = getLastResponse(sessionId).slice(0, 300);
+    const contextBlock = lastResponse
+      ? `CONTEXT (last AI response excerpt):\n${lastResponse}\n\nCURRENT USER MESSAGE:\n${trimmed.slice(0, 300)}`
+      : trimmed.slice(0, 300);
+
+    const result = await inference({
+      system: SENTIMENT_SYSTEM_PROMPT,
+      user: contextBlock,
+      maxTokens: 500,
+      timeout: 60000,
+      jsonSchema: SENTIMENT_SCHEMA,
+      caller: "rating",
+      sessionId,
+    });
 
-  if (!result.success || !result.output) return;
+    if (result.usage) logTokenUsage("rating", result.usage);
+    if (!result.success || !result.output) return;
 
-  try {
     const parsed = JSON.parse(result.output) as SentimentResult;
 
-    // Skip if no sentiment detected or low confidence
     if (parsed.rating === null) return;
     if (parsed.confidence < MIN_CONFIDENCE) return;
 
@@ -349,13 +368,13 @@ async function handleImplicitSentiment(
     }
   } catch (err) {
     const { logError } = await import("../lib/log");
-    logError("rating:implicit", err);
+    logError("rating:sentiment-child", err);
   }
 }
 
 // ── Main Export ──
 
-export async function captureRating(message: string, sessionId?: string): Promise<void> {
+export function captureRating(message: string, sessionId?: string): void {
   // Strip IDE/system-injected tags to recover raw user text
   const cleaned = stripInjectedTags(message);
 
@@ -374,6 +393,18 @@ export async function captureRating(message: string, sessionId?: string): Promis
     return;
   }
 
-  // Path 2: Implicit sentiment (requires PAL_ANTHROPIC_API_KEY — inference silently no-ops without it)
-  await handleImplicitSentiment(cleaned, sessionId);
+  // Path 2: Implicit sentiment — fast-paths run synchronously, the inference
+  // path detaches to a background bun subprocess (mirrors session-name).
+  handleImplicitSentiment(cleaned, sessionId);
+}
+
+// Background sentiment entry point
+if (process.argv[2] === "--sentiment") {
+  const sid = process.argv[3];
+  const msgB64 = process.argv[4];
+  if (msgB64) {
+    const msg = Buffer.from(msgB64, "base64").toString("utf-8");
+    await runSentimentInferenceAndStore(msg, sid === "" ? undefined : sid);
+  }
+  process.exit(0);
 }

package/src/hooks/handlers/session-intelligence.ts

@@ -13,7 +13,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { unlink, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { stringify } from "../lib/frontmatter";
-import { hasApiKey, inference } from "../lib/inference";
+import { canInfer, inference } from "../lib/inference";
 import { categorizeLearning } from "../lib/learning-category";
 import { logDebug, logError } from "../lib/log";
 import { ensureDir, paths } from "../lib/paths";
@@ -124,7 +124,7 @@ interface IntelligenceOutput {
 
 // ── Main handler ──
 
-export async function captureSessionIntelligence(
+async function captureSessionIntelligence(
   transcript: string,
   sessionId?: string
 ): Promise<void> {
@@ -137,9 +137,9 @@ export async function captureSessionIntelligence(
     if (prev && messages.length - prev.messageCount < MIN_NEW_MESSAGES) return;
   }
 
-  // Skip if no API key
-  if (!hasApiKey()) {
-    logDebug("session-intelligence", "Skipped: no PAL_ANTHROPIC_API_KEY");
+  // Skip if no inference path is available (no CLI binary AND no API key)
+  if (!canInfer()) {
+    logDebug("session-intelligence", "Skipped: canInfer() false (no CLI + no API key)");
     return;
   }
 
@@ -178,8 +178,10 @@ export async function captureSessionIntelligence(
       ].join("\n"),
       user: `User messages:\n${numberedMessages}\n\nLast AI response:\n${assistantWindow}`,
       maxTokens: 350,
-      timeout: 15000,
+      timeout: 60000,
       jsonSchema: INTELLIGENCE_SCHEMA,
+      caller: "session-intelligence",
+      sessionId,
     });
 
     if (result.usage) logTokenUsage("session-intelligence", result.usage);
@@ -246,3 +248,21 @@ export async function captureSessionIntelligence(
   if (sessionId) markCaptured(sessionId, filepath, messages.length);
   logDebug("session-intelligence", `Learning captured: ${title}`);
 }
+
+// Detached child entry point — re-reads transcript from tmp path, then unlinks it.
+if (process.argv[2] === "--run") {
+  const sid = process.argv[3];
+  const transcriptPath = process.argv[4];
+  if (transcriptPath) {
+    const { readFile, unlink } = await import("node:fs/promises");
+    try {
+      const transcript = await readFile(transcriptPath, "utf-8");
+      await captureSessionIntelligence(transcript, sid === "" ? undefined : sid);
+    } catch (err) {
+      logError("session-intelligence:run", err);
+    } finally {
+      await unlink(transcriptPath).catch(() => {});
+    }
+  }
+  process.exit(0);
+}

package/src/hooks/handlers/session-name.ts

@@ -9,8 +9,8 @@
  * This avoids the 1-5s inference latency that previously blocked every first prompt.
  */
 
-import { spawn } from "node:child_process";
-import { hasApiKey, inference } from "../lib/inference";
+import { spawnDetachedInference } from "../lib/detached-inference";
+import { canInfer, inference } from "../lib/inference";
 import { logDebug, logError } from "../lib/log";
 import {
   extractFallbackName,
@@ -41,24 +41,14 @@ export async function captureSessionName(
   writeSessionName(sessionId, name);
   logDebug("session-name", `Named from prompt: "${name}"`);
 
-  // Spawn detached background process to upgrade with Haiku inference
-  if (!hasApiKey()) return;
-  try {
-    const promptB64 = Buffer.from(message.slice(0, 800)).toString("base64");
-    const child = spawn(
-      "bun",
-      [import.meta.filename, "--upgrade", sessionId, promptB64, name],
-      {
-        detached: true,
-        stdio: "ignore",
-        env: { ...process.env, CLAUDECODE: undefined },
-      }
-    );
-    child.unref();
-    logDebug("session-name", "Spawned background Haiku upgrade");
-  } catch {
-    // Non-critical — deterministic name is already stored
-  }
+  // Spawn detached background process to upgrade via inference
+  if (!canInfer()) return;
+  const promptB64 = Buffer.from(message.slice(0, 800)).toString("base64");
+  spawnDetachedInference(
+    import.meta.filename,
+    ["--upgrade", sessionId, promptB64, name],
+    "session-name"
+  );
 }
 
 /**
@@ -80,7 +70,9 @@ async function upgradeWithInference(
       system: NAME_PROMPT,
       user: `Generate a 4-word title for: "${promptText}"`,
       maxTokens: 20,
-      timeout: 10000,
+      timeout: 60000,
+      caller: "session-name",
+      sessionId,
     });
 
     if (result.usage) logTokenUsage("session-name", result.usage);

package/src/hooks/lib/agent.ts

@@ -1,27 +1,42 @@
 /**
  * Agent detection and output format adapters.
  *
- * Cursor, Codex, and Claude Code use different JSON contracts for hook I/O.
- * These helpers normalize the differences so hook handlers stay clean.
+ * Each supported agent (Claude Code, Cursor, Codex, Copilot, opencode) uses a
+ * different JSON contract for hook I/O and a different mechanism for spawning
+ * one-shot subscription-backed inference. These helpers identify which agent
+ * is currently running PAL so downstream code can dispatch accordingly.
+ *
+ * Primary signal: PAL_AGENT env var, set by every install template/plugin in
+ * `assets/templates/*` and `src/targets/opencode/plugin.ts`. IDE-provided env
+ * vars are used as secondary fallbacks for environments that forward them.
  */
 
-type AgentType = "claude" | "cursor" | "codex";
+type AgentType = "claude" | "cursor" | "codex" | "copilot" | "opencode";
+
+const KNOWN_AGENTS: ReadonlySet<AgentType> = new Set([
+  "claude",
+  "cursor",
+  "codex",
+  "copilot",
+  "opencode",
+]);
 
-/** Detect which agent is running via environment variables */
-function detectAgent(): AgentType {
-  // PAL_AGENT is set explicitly in hook command prefixes — most reliable signal.
-  // IDE env vars (CURSOR_VERSION, CODEX_CLI_VERSION) are NOT reliably forwarded to
-  // hook subprocesses, so PAL_AGENT is the primary detection mechanism.
-  if (process.env.PAL_AGENT === "cursor") return "cursor";
-  if (process.env.PAL_AGENT === "codex") return "codex";
-  // Fallbacks for environments that do forward IDE env vars
+/** Detect which agent is currently running PAL. Defaults to "claude". */
+export function getActiveAgent(): AgentType {
+  const explicit = process.env.PAL_AGENT;
+  if (explicit && KNOWN_AGENTS.has(explicit as AgentType)) {
+    return explicit as AgentType;
+  }
   if (process.env.CURSOR_VERSION) return "cursor";
   if (process.env.CODEX_CLI_VERSION ?? process.env.OPENAI_CODEX) return "codex";
   return "claude";
 }
 
-export const isCursor = () => detectAgent() === "cursor";
-export const isCodex = () => detectAgent() === "codex";
+export const isClaude = () => getActiveAgent() === "claude";
+export const isCursor = () => getActiveAgent() === "cursor";
+export const isCodex = () => getActiveAgent() === "codex";
+export const isCopilot = () => getActiveAgent() === "copilot";
+export const isOpencode = () => getActiveAgent() === "opencode";
 
 /**
  * Format a "block this action" response for the current agent.

package/src/hooks/lib/detached-inference.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared spawn helper for detached background inference calls.
+ *
+ * PAL hooks that need to run an inference but cannot block the parent hook
+ * process (UserPromptSubmit, Stop) spawn a detached bun subprocess that
+ * re-enters the same handler script with a mode flag. This helper centralizes
+ * the spawn boilerplate: detach + unref + CLAUDECODE-scrub + debug/error logs.
+ *
+ * Usage:
+ *   spawnDetachedInference(
+ *     import.meta.filename,                  // re-invokes this script
+ *     ["--sentiment", sessionId, msgB64],    // mode flag + payload args
+ *     "rating"                                // scope for logs
+ *   );
+ *
+ * Payloads over a few KB should be passed via file path (write to tmp,
+ * pass path) rather than argv to avoid ARG_MAX limits (~256KB on macOS).
+ */
+
+import { spawn } from "node:child_process";
+import { logDebug, logError } from "./log";
+
+export function spawnDetachedInference(
+  scriptPath: string,
+  args: string[],
+  scope: string
+): void {
+  try {
+    const child = spawn("bun", [scriptPath, ...args], {
+      detached: true,
+      stdio: "ignore",
+      env: { ...process.env, CLAUDECODE: undefined },
+    });
+    child.unref();
+    logDebug(scope, `detached inference spawned: ${args[0] ?? "no-mode"}`);
+  } catch (err) {
+    logError(scope, err);
+  }
+}

package/src/hooks/lib/graduation.ts

@@ -259,6 +259,7 @@ async function generateRecommendations(
         },
         required: ["recommendations"],
       },
+      caller: "graduation",
     });
 
     if (result.success && result.output) {