portable-agent-layer 0.94.0 → 0.95.1

package/src/hooks/lib/waiting-on-user.ts

@@ -0,0 +1,75 @@
+/**
+ * A marker per session for the moment the agent started waiting on the user,
+ * taken by whatever the user does next so it can say how long they took.
+ */
+
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ensureDir, paths } from "./paths";
+
+const MAX_WAIT_SEC = 30 * 60;
+
+type WaitKind = "permission" | "notified";
+
+interface Waiting {
+  ts: string;
+  tool?: string;
+}
+
+function waitingFile(kind: WaitKind, session: string): string {
+  const safe = session.replace(/[^\w-]/g, "_");
+  return resolve(
+    ensureDir(resolve(paths.state(), "waiting-on-user")),
+    `${kind}-${safe}.json`
+  );
+}
+
+export function markWaiting(kind: WaitKind, session: string, waiting: Waiting): void {
+  writeFileSync(waitingFile(kind, session), JSON.stringify(waiting));
+}
+
+function readWaiting(file: string): Waiting | null {
+  try {
+    return JSON.parse(readFileSync(file, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function secondsSince(ts: string, now: Date): number {
+  return Math.round((now.getTime() - Date.parse(ts)) / 100) / 10;
+}
+
+function takeWaiting(
+  kind: WaitKind,
+  session: string,
+  now: Date,
+  belongs: (waiting: Waiting) => boolean = () => true
+): number | null {
+  const file = waitingFile(kind, session);
+  if (!existsSync(file)) return null;
+  const waiting = readWaiting(file);
+  if (waiting && !belongs(waiting)) return null;
+  rmSync(file, { force: true });
+  if (!waiting) return null;
+  const waited = secondsSince(waiting.ts, now);
+  return waited >= 0 && waited <= MAX_WAIT_SEC ? waited : null;
+}
+
+/** Seconds the user took to answer a prompt for this tool, once; null when none was open. */
+export function permissionWaitSec(
+  session: string | null,
+  tool: string,
+  now: Date = new Date()
+): number | null {
+  if (!session) return null;
+  return takeWaiting("permission", session, now, (waiting) => waiting.tool === tool);
+}
+
+/** Seconds from the last notification to the user's next prompt, once. */
+export function backAfterNotificationSec(
+  session: string,
+  now: Date = new Date()
+): number | null {
+  return takeWaiting("notified", session, now);
+}

package/src/hooks/lib/work-tracking.ts

@@ -41,6 +41,17 @@ function readSessions(): SessionRecord[] {
   }
 }
 
+function sessionArchiveFile(record: SessionRecord): string {
+  const month = Number.isNaN(Date.parse(record.ts)) ? "undated" : record.ts.slice(0, 7);
+  return resolve(ensureDir(resolve(paths.state(), "sessions-archive")), `${month}.jsonl`);
+}
+
+function archiveSessions(records: SessionRecord[]): void {
+  for (const record of records) {
+    appendFileSync(sessionArchiveFile(record), `${JSON.stringify(record)}\n`, "utf-8");
+  }
+}
+
 export function writeSession(record: SessionRecord): void {
   const sessions = readSessions();
   // Replace existing record with same sessionId, or append
@@ -50,9 +61,12 @@ export function writeSession(record: SessionRecord): void {
   } else {
     sessions.push(record);
   }
-  // Prune to last N
-  const pruned = sessions.slice(-MAX_SESSIONS);
-  writeFileSync(sessionsPath(), JSON.stringify(pruned, null, 2), "utf-8");
+  archiveSessions(sessions.slice(0, -MAX_SESSIONS));
+  writeFileSync(
+    sessionsPath(),
+    JSON.stringify(sessions.slice(-MAX_SESSIONS), null, 2),
+    "utf-8"
+  );
 }
 
 /** Detect session completion status from last assistant message */

package/src/targets/opencode/plugin.ts

@@ -61,6 +61,16 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
 
   // Load shared handlers
   const { runStopHandlers } = await lib<typeof import("../../hooks/lib/stop")>("stop.ts");
+  const { logToolCall } =
+    await lib<typeof import("../../hooks/lib/tool-events")>("tool-events.ts");
+  const { logAttention } =
+    await lib<typeof import("../../hooks/lib/attention-events")>("attention-events.ts");
+  const {
+    logOpencodeCompaction,
+    logOpencodePermissionReply,
+    logOpencodeSessionCreated,
+    rememberAskedTool,
+  } = await lib<typeof import("../../hooks/lib/opencode-events")>("opencode-events.ts");
   const { captureSessionName } = await lib<
     typeof import("../../hooks/handlers/session-name")
   >("../handlers/session-name.ts");
@@ -137,6 +147,13 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
         autoUpdateOnClose();
       }
 
+      if (event.type === "session.created")
+        logOpencodeSessionCreated(event.properties.info);
+      if (event.type === "session.compacted")
+        logOpencodeCompaction(event.properties.sessionID);
+      if (event.type === "permission.replied")
+        logOpencodePermissionReply(event.properties);
+
       if (event.type === "session.created" || event.type === "session.updated") {
         const { regenerateIfNeeded } =
           await lib<typeof import("../../hooks/lib/claude-md")>("claude-md.ts");
@@ -237,10 +254,25 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
       if (call) snapshotCall(call);
     },
 
+    "permission.ask": async (input: { id: string; type: string; sessionID: string }) => {
+      rememberAskedTool(input);
+      logAttention({
+        hook_event_name: "PermissionRequest",
+        session_id: input.sessionID,
+        tool_name: input.type,
+      });
+    },
+
     "tool.execute.after": async (
       input: { tool: string; sessionID: string; callID: string; args: unknown },
-      _output: { title: string; output: string; metadata: unknown }
+      output: { title: string; output: string; metadata: unknown }
     ) => {
+      logToolCall({
+        tool_name: input.tool,
+        tool_input: input.args,
+        session_id: input.sessionID,
+        tool_response: output?.output,
+      });
       const call = ledgeredOpencodeCall(input.tool, input.callID, input.args);
       if (!call) return;
 

package/src/tools/agent/interaction.ts

@@ -12,8 +12,8 @@ import { group, leaf, runCommand, UsageError } from "../lib/command";
 import { claimCheckLines, reportLines, summarize } from "../lib/interaction-report";
 import { scriptArgs } from "../lib/script-args";
 
-const DETAILS = `Reads the measured turns in memory/signals/interaction/ (features only, no
-text) and prints turns, channels, reactions, the hints sent, per agent the
+const DETAILS = `Reads the measured turns from the event log in memory/events/ and the older
+memory/signals/interaction/ files (features only, no text) and prints turns, channels, reactions, the hints sent, per agent the
 turns, replies filed and hints sent, and for each label (short, long, fast,
 skimming, friction) how the replies written while it was active compare with
 the replies written while none was. Last, the replies that claimed a result

package/src/tools/agent/project.ts

@@ -11,6 +11,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { writeBinding } from "../../hooks/lib/bindings";
+import { logCommitment } from "../../hooks/lib/commitment-events";
 import { paths, toPath } from "../../hooks/lib/paths";
 import {
   defaultSlug,
@@ -454,6 +455,7 @@ function cmdCompleteIsc(name: string, id: number): undefined {
     return;
   }
   applyIscMove(p, move);
+  logCommitment(name, id, "kept", "cli");
   ok({ checked: true, id, archived: true });
 }
 
@@ -479,6 +481,7 @@ function cmdReopenIsc(name: string, id: number): undefined {
     return;
   }
   applyIscMove(p, move);
+  logCommitment(name, id, "reopened", "cli");
   ok({ checked: false, id });
 }
 
@@ -546,6 +549,7 @@ function cmdRetireIsc(name: string, id: number, by: number | null): undefined {
   );
   p.updated = now();
   writeProject(p);
+  logCommitment(name, id, "dropped", "cli");
   ok({ retired: true, id, supersededBy: by, archived: true });
 }
 

package/src/tools/control-room/snooze.ts

@@ -8,6 +8,7 @@
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { logCommitment } from "../../hooks/lib/commitment-events";
 import { ensureDir, paths } from "../../hooks/lib/paths";
 
 const DAY_MS = 86_400_000;
@@ -61,5 +62,6 @@ export function setSnooze(
   if (days <= 0) delete live[key];
   else live[key] = new Date(now.getTime() + days * DAY_MS).toISOString().slice(0, 10);
   writeFileSync(snoozeFile(), `${JSON.stringify(live, null, 2)}\n`, "utf-8");
+  if (days > 0) logCommitment(project, id, "snoozed", "control-room", days);
   return live[key] ?? null;
 }

package/src/tools/control-room/writes.ts

@@ -6,6 +6,7 @@
  * write surface over ~/.pal.
  */
 
+import { logCommitment } from "../../hooks/lib/commitment-events";
 import { readProject, writeProject } from "../../hooks/lib/projects";
 import {
   raw as rawSettings,
@@ -38,6 +39,7 @@ export function setIscStatus(project: string, id: number, close: boolean): Write
   p.changelog = move.changelog;
   p.updated = new Date().toISOString();
   writeProject(p);
+  logCommitment(project, id, close ? "kept" : "reopened", "control-room");
   return { ok: true, changed: true };
 }
 

package/src/tools/knowledge/lib.ts

@@ -31,6 +31,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { resolve } from "node:path";
+import { logEntityFirstSeen } from "../../hooks/lib/entity-events";
 import { ensureDir, paths } from "../../hooks/lib/paths";
 
 // --- Constants --------------------------------------------------------------
@@ -412,9 +413,13 @@ export function exists(domain: Domain, slug: string, rootDir?: string): boolean
 
 export function save(entity: Entity, rootDir?: string): void {
   const p = entityPath(entity.domain, entity.slug, rootDir);
+  const firstSeenInTheStore = !rootDir && !existsSync(p);
   const tmp = `${p}.tmp`;
   writeFileSync(tmp, serialize(entity), "utf-8");
   renameSync(tmp, p);
+  if (firstSeenInTheStore) {
+    logEntityFirstSeen(entity.domain, entity.frontmatter.type, entity.frontmatter.title);
+  }
 }
 
 export function load(domain: Domain, slug: string, rootDir?: string): Entity | null {

package/src/tools/lib/session-usage.ts

@@ -10,7 +10,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { costOfUsage } from "../../hooks/lib/models";
-import { cacheWritesOf, type TranscriptUsage } from "./transcript-usage";
+import { cacheWritesOf, finalPerMessage, type TranscriptUsage } from "./transcript-usage";
 
 export interface SessionUsage {
   input: number;
@@ -94,7 +94,7 @@ interface TranscriptLine {
   type?: string;
   timestamp?: string;
   sessionId?: string;
-  message?: { model?: string; usage?: TranscriptUsage };
+  message?: { id?: string; model?: string; usage?: TranscriptUsage };
 }
 
 function emptyUsage(): SessionUsage {
@@ -113,6 +113,7 @@ function emptyUsage(): SessionUsage {
 
 export function accumulateUsage(transcript: string, sessionId: string): SessionUsage {
   const total = emptyUsage();
+  const assistantTurns: TranscriptLine[] = [];
   let firstTs = "";
   let lastTs = "";
 
@@ -133,7 +134,10 @@ export function accumulateUsage(transcript: string, sessionId: string): SessionU
       lastTs = entry.timestamp;
     }
 
-    if (entry.type !== "assistant") continue;
+    if (entry.type === "assistant") assistantTurns.push(entry);
+  }
+
+  for (const entry of finalPerMessage(assistantTurns, (e) => e.message?.id)) {
     const usage = entry.message?.usage;
     const model = entry.message?.model;
     if (!usage || !model) continue;

package/src/tools/lib/transcript-usage.ts

@@ -18,6 +18,20 @@ export interface TranscriptUsage {
   };
 }
 
+/**
+ * Claude Code writes one transcript line per content block of a message, each
+ * repeating the message's usage — and an early line can carry the usage while
+ * the message was still streaming. A message is billed once, at its last line.
+ */
+export function finalPerMessage<T>(
+  calls: Iterable<T>,
+  messageIdOf: (call: T) => string | undefined
+): T[] {
+  const byMessage = new Map<unknown, T>();
+  for (const call of calls) byMessage.set(messageIdOf(call) ?? call, call);
+  return [...byMessage.values()];
+}
+
 export interface CacheWrites {
   cacheWrite5m: number;
   cacheWrite1h: number;

package/src/tools/lib/usage-buckets.ts

@@ -7,7 +7,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { costOfUsage } from "../../hooks/lib/models";
-import { cacheWritesOf, type TranscriptUsage } from "./transcript-usage";
+import { cacheWritesOf, finalPerMessage, type TranscriptUsage } from "./transcript-usage";
 
 export interface Bucket {
   input: number;
@@ -180,7 +180,7 @@ export function usageTally(projectFilter?: string, now: Date = new Date()): Usag
 interface TranscriptLine {
   type?: string;
   timestamp?: string;
-  message?: { model?: string; usage?: TranscriptUsage };
+  message?: { id?: string; model?: string; usage?: TranscriptUsage };
 }
 
 /**
@@ -209,6 +209,7 @@ function transcriptsIn(projPath: string): string[] {
 }
 
 interface PricedCall {
+  messageId?: string;
   ts: string;
   model: string;
   tokens: Tokens;
@@ -230,6 +231,7 @@ function pricedCallOf(line: string): PricedCall | null {
   if (!usage || !model || !ts) return null;
 
   return {
+    messageId: entry.message?.id,
     ts,
     model,
     tokens: {
@@ -248,6 +250,7 @@ export function readClaudeCode(
 ): AgentUsage {
   const tally = usageTally(projectFilter, now);
   if (!existsSync(claudeDir)) return tally.usage;
+  const calls: (PricedCall & { project: string })[] = [];
 
   const projectDirs = readdirSync(claudeDir, { withFileTypes: true })
     .filter((entry) => entry.isDirectory())
@@ -269,16 +272,20 @@ export function readClaudeCode(
         // Cheap reject before the parse: most lines are not model turns.
         if (!line.includes('"usage"')) continue;
         const call = pricedCallOf(line);
-        if (!call) continue;
-        tally.record({
-          ...call,
-          project: projName,
-          cost: costOfUsage(call.model, call.tokens),
-        });
+        if (call) calls.push({ ...call, project: projName });
       }
     }
   }
 
+  for (const call of finalPerMessage(calls, (c) => c.messageId)) {
+    tally.record({
+      ts: call.ts,
+      model: call.model,
+      tokens: call.tokens,
+      project: call.project,
+      cost: costOfUsage(call.model, call.tokens),
+    });
+  }
   return tally.usage;
 }
 

package/src/hooks/LedgerCommit.ts

@@ -1,34 +0,0 @@
-/**
- * Hook: PostToolUse — pairs the parked before-state with the result and writes
- * the ledger entry.
- *
- * Only a call that actually landed reaches this event, so every entry written
- * here is an applied one. A denied or failed call fires the snapshot half and
- * never this one, leaving its snapshot unclaimed — which is why claiming also
- * reaps the ones that were abandoned.
- *
- * Silent and fail-open, for the same reason as its other half.
- */
-
-import { duplicatesCursorHooks } from "./lib/cursor-shadow";
-import { enterHookWorkspace } from "./lib/hook-turn";
-import { commitApplied, landedCalls } from "./lib/ledger-hook";
-import { logDebug } from "./lib/log";
-import { readStdinJSON } from "./lib/stdin";
-
-if (duplicatesCursorHooks()) process.exit(0);
-
-try {
-  const input = await readStdinJSON<Record<string, unknown>>();
-  if (!input) process.exit(0);
-
-  enterHookWorkspace(input);
-  for (const call of landedCalls(input)) {
-    const entry = commitApplied(call);
-    if (entry) {
-      logDebug("LedgerCommit", `recorded ${entry.id} ${entry.tool} ${entry.target}`);
-    }
-  }
-} catch {
-  process.exit(0);
-}

package/src/hooks/LedgerUnapplied.ts

@@ -1,47 +0,0 @@
-/**
- * Hook: PostToolUseFailure and PermissionDenied — records an edit that was
- * attempted and did not land.
- *
- * A log that keeps only what succeeded cannot answer what was attempted, and
- * that is usually the question being asked of it. So the two endings that are
- * not success are recorded too, and kept apart: `failed` is the tool's own
- * attempt breaking, `denied` is something refusing to let it run.
- *
- * One hook serves both events because they differ only in which key carries the
- * reason — a difference `unappliedVerdictOf` owns, so registering this on a
- * third such event later is a line in that table rather than a new file.
- *
- * Not everything that fails to land reaches here. A manual denial at the
- * permission dialog, a `deny` rule, and a PreToolUse hook's own block all fire
- * PreToolUse and nothing after it; a schema rejection fires no hook at all.
- * Those attempts leave a snapshot no half ever claims, which is what the reaper
- * in ledger.ts is for.
- *
- * Silent and fail-open, for the same reason as the other halves.
- */
-
-import { duplicatesCursorHooks } from "./lib/cursor-shadow";
-import { reapStalePending } from "./lib/ledger";
-import { commitUnapplied, ledgeredCalls, unappliedVerdictOf } from "./lib/ledger-hook";
-import { logDebug } from "./lib/log";
-import { readStdinJSON } from "./lib/stdin";
-
-if (duplicatesCursorHooks()) process.exit(0);
-
-try {
-  const input = await readStdinJSON<Record<string, unknown>>();
-  if (!input) process.exit(0);
-
-  const calls = ledgeredCalls(input);
-  const verdict = calls.length > 0 && unappliedVerdictOf(input);
-  if (!verdict) process.exit(0);
-
-  for (const call of calls) {
-    const entry = commitUnapplied(call, verdict);
-    logDebug("LedgerUnapplied", `recorded ${entry.id} ${entry.outcome} ${entry.target}`);
-  }
-
-  reapStalePending();
-} catch {
-  process.exit(0);
-}