portable-agent-layer 0.67.0 → 0.69.0

package/src/cli/ledger.ts

@@ -0,0 +1,329 @@
+/**
+ * pal cli ledger — query the action ledger.
+ *
+ * Thin presentation layer over src/tools/ledger/query.ts. Owns formatting and
+ * argv parsing only; every question about the records themselves is answered
+ * there.
+ *
+ * Subcommands:
+ *   log [filters]     Matching actions, oldest first
+ *   show <id>         One action in full, with its change and current standing
+ *   stats [filters]   Counts by outcome, runtime, actor, tool and target
+ */
+
+import { parseArgs } from "node:util";
+import type { LedgerEntry } from "../hooks/lib/ledger";
+import {
+  type ChainVerdict,
+  chainVerdict,
+  changeShape,
+  findEntry,
+  type LedgerFilter,
+  ledgerFiles,
+  locate,
+  parseSince,
+  queryLedger,
+  type Standing,
+  standing,
+  summarize,
+} from "../tools/ledger/query";
+
+const FILTER_OPTIONS = {
+  project: { type: "string" },
+  since: { type: "string" },
+  until: { type: "string" },
+  actor: { type: "string" },
+  machine: { type: "string" },
+  runtime: { type: "string" },
+  outcome: { type: "string" },
+  tool: { type: "string" },
+  target: { type: "string" },
+  limit: { type: "string" },
+  json: { type: "boolean" },
+} as const;
+
+export async function runLedger(args: string[]): Promise<number> {
+  const [sub, ...rest] = args;
+  switch (sub) {
+    case "log":
+      return cmdLog(rest);
+    case "show":
+      return cmdShow(rest);
+    case "stats":
+      return cmdStats(rest);
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      showHelp();
+      return 0;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      showHelp();
+      return 1;
+  }
+}
+
+function showHelp(): void {
+  console.log(`
+  Usage:
+    pal cli ledger <subcommand> [filters]
+
+  Subcommands:
+    log [filters]              Matching actions, oldest first
+    show <id>                  One action in full: change, target, standing
+    stats [filters]            Counts by outcome, runtime, actor, tool, target
+
+  Filters:
+    --project <slug>           Actions against a registered project
+    --since <7d|2026-09-01>    A duration back from now, or a date
+    --until <date>             Upper bound on the timestamp
+    --actor <id>               Who caused it
+    --machine <id>             Which install wrote it
+    --runtime <agent>          claude, cursor, codex, copilot, opencode
+    --outcome <applied|failed|denied>
+    --tool <Edit|Write>
+    --target <substring>       Match anywhere in the recorded path
+    --limit <n>                Keep the newest n matches
+    --json                     Machine-readable output
+
+  Examples:
+    pal cli ledger log --project portable-agent-layer --since 7d
+    pal cli ledger log --target memory/ --outcome applied
+    pal cli ledger stats --since 24h
+`);
+}
+
+/** A filter that silently ignored an unparseable window would answer the wrong question. */
+function buildFilter(values: Record<string, unknown>): LedgerFilter | string {
+  const filter: LedgerFilter = {};
+  for (const key of [
+    "project",
+    "actor",
+    "machine",
+    "runtime",
+    "outcome",
+    "tool",
+    "target",
+  ] as const) {
+    const value = values[key];
+    if (typeof value === "string") filter[key] = value;
+  }
+
+  for (const key of ["since", "until"] as const) {
+    const spec = values[key];
+    if (typeof spec !== "string") continue;
+    const at = parseSince(spec);
+    if (!at) return `Unrecognised --${key}: ${spec} (use 7d, 24h, or a date)`;
+    filter[key] = at;
+  }
+
+  if (typeof values.limit === "string") {
+    const limit = Number(values.limit);
+    if (!Number.isInteger(limit) || limit < 1)
+      return `--limit must be a positive integer`;
+    filter.limit = limit;
+  }
+  return filter;
+}
+
+function parseFilters(args: string[]): { filter: LedgerFilter; json: boolean } | string {
+  try {
+    const { values } = parseArgs({
+      args,
+      options: FILTER_OPTIONS,
+      allowPositionals: true,
+    });
+    const filter = buildFilter(values);
+    return typeof filter === "string" ? filter : { filter, json: values.json === true };
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
+function shortId(id: string): string {
+  return id.slice(0, 11).padEnd(11);
+}
+
+function changedLines(entry: LedgerEntry): string {
+  const shape = changeShape(entry);
+  switch (shape.kind) {
+    case "redacted":
+      return "withheld";
+    case "truncated":
+      return "too large";
+    case "none":
+      return "no change";
+    default: {
+      const added = shape.delta.hunks.reduce((n, h) => n + h.insert.length, 0);
+      const removed = shape.delta.hunks.reduce((n, h) => n + h.remove, 0);
+      return `+${added} -${removed}`;
+    }
+  }
+}
+
+function cmdLog(args: string[]): number {
+  const parsed = parseFilters(args);
+  if (typeof parsed === "string") return fail(parsed);
+
+  const entries = queryLedger(parsed.filter);
+  if (parsed.json) {
+    console.log(JSON.stringify(entries, null, 2));
+    return 0;
+  }
+
+  if (entries.length === 0) {
+    console.log("No actions match.");
+    return 0;
+  }
+
+  for (const entry of entries) {
+    console.log(
+      `${entry.ts}  ${shortId(entry.id)}  ${entry.outcome.padEnd(7)}  ${entry.runtime.padEnd(8)}  ${entry.tool.padEnd(5)}  ${changedLines(entry).padEnd(9)}  ${entry.target}`
+    );
+  }
+  console.log(
+    `\n${entries.length} action(s) across ${ledgerFiles().length} ledger file(s).`
+  );
+  return 0;
+}
+
+function describeStanding(verdict: Standing): string {
+  switch (verdict.state) {
+    case "in-place":
+      return "still in place on disk";
+    case "reverted":
+      return verdict.replays
+        ? "reverted since — the stored change replays cleanly onto the file as it stands"
+        : "reverted since, but the stored change no longer replays";
+    case "superseded":
+      return `superseded — the file has changed again since (now ${verdict.hash.slice(0, 12)})`;
+    case "missing":
+      return "the target no longer exists";
+    default:
+      return verdict.why;
+  }
+}
+
+function describeChain(verdict: ChainVerdict): string {
+  switch (verdict.state) {
+    case "latest":
+      return "the newest recorded action on this target";
+    case "undone":
+      return `undone by ${verdict.by} at ${verdict.at}, which put the file back as this one found it`;
+    default:
+      return `changed again by ${verdict.by} at ${verdict.at}`;
+  }
+}
+
+const UNKEPT_CHANGE: Record<string, string> = {
+  redacted: "contents withheld — the target is one the ledger never keeps",
+  truncated: "the change was too large to keep; its size and hashes remain",
+  none: "no change was recorded, which is what a refused action looks like",
+};
+
+function printChange(entry: LedgerEntry): void {
+  const shape = changeShape(entry);
+  if (shape.kind !== "hunks") {
+    console.log(`  ${UNKEPT_CHANGE[shape.kind]}`);
+    return;
+  }
+  for (const hunk of shape.delta.hunks) {
+    console.log(`  @@ line ${hunk.at + 1}, -${hunk.remove} +${hunk.insert.length}`);
+    for (const line of hunk.insert) console.log(`  + ${line}`);
+  }
+}
+
+function cmdShow(args: string[]): number {
+  const [id, ...rest] = args;
+  if (!id) return fail("Usage: pal cli ledger show <id>");
+
+  const entry = findEntry(id);
+  if (!entry) return fail(`No action with id ${id}`);
+
+  if (rest.includes("--json")) {
+    console.log(
+      JSON.stringify(
+        {
+          ...entry,
+          resolved: locate(entry),
+          standing: standing(entry),
+          chain: chainVerdict(entry),
+        },
+        null,
+        2
+      )
+    );
+    return 0;
+  }
+
+  console.log(`
+  ${entry.id}  ${entry.ts}
+  ${entry.tool} → ${outcomeLine(entry)}
+  target      ${entry.target}
+  on disk     ${diskLine(entry)}
+  runtime     ${entry.runtime}, authority ${entry.authority}
+  actor       ${entry.actor}
+  machine     ${entry.machine}
+  size        ${sizeOf(entry.before, "created")} → ${sizeOf(entry.after, "nothing landed")}
+  standing    ${describeStanding(standing(entry))}
+  in ledger   ${describeChain(chainVerdict(entry))}
+
+  change`);
+  printChange(entry);
+  return 0;
+}
+
+function outcomeLine(entry: LedgerEntry): string {
+  return entry.reason ? `${entry.outcome} (${entry.reason})` : entry.outcome;
+}
+
+function diskLine(entry: LedgerEntry): string {
+  const found = locate(entry);
+  if (found.path) return found.path;
+  return `unresolvable: project ${found.unresolvable} is not registered here`;
+}
+
+function sizeOf(state: LedgerEntry["before"], absent: string): string {
+  return state ? `${state.bytes}b` : absent;
+}
+
+function printTally(label: string, counts: Record<string, number>): void {
+  const rows = Object.entries(counts).sort((a, b) => b[1] - a[1]);
+  if (rows.length === 0) return;
+  console.log(`  ${label}`);
+  for (const [key, count] of rows)
+    console.log(`    ${String(count).padStart(6)}  ${key}`);
+}
+
+function cmdStats(args: string[]): number {
+  const parsed = parseFilters(args);
+  if (typeof parsed === "string") return fail(parsed);
+
+  const stats = summarize(queryLedger(parsed.filter));
+  if (parsed.json) {
+    console.log(JSON.stringify(stats, null, 2));
+    return 0;
+  }
+
+  console.log(
+    `\n  ${stats.total} action(s) across ${ledgerFiles().length} ledger file(s)`
+  );
+  if (stats.span) console.log(`  ${stats.span.first} → ${stats.span.last}\n`);
+  printTally("outcome", stats.byOutcome);
+  printTally("runtime", stats.byRuntime);
+  printTally("tool", stats.byTool);
+  printTally("actor", stats.byActor);
+  if (stats.topTargets.length > 0) {
+    console.log("  most-changed targets");
+    for (const { target, count } of stats.topTargets) {
+      console.log(`    ${String(count).padStart(6)}  ${target}`);
+    }
+  }
+  return 0;
+}
+
+function fail(message: string): number {
+  console.error(message);
+  return 1;
+}

package/src/hooks/LedgerCommit.ts

@@ -10,9 +10,7 @@
  * Silent and fail-open, for the same reason as its other half.
  */
 
-import { existsSync, readFileSync } from "node:fs";
-import { claimPending, reapStalePending, recordAction } from "./lib/ledger";
-import { ledgeredCall } from "./lib/ledger-hook";
+import { commitApplied, ledgeredCalls } from "./lib/ledger-hook";
 import { logDebug } from "./lib/log";
 import { readStdinJSON } from "./lib/stdin";
 
@@ -20,24 +18,12 @@ try {
   const input = await readStdinJSON<Record<string, unknown>>();
   if (!input) process.exit(0);
 
-  const call = ledgeredCall(input);
-  if (!call) process.exit(0);
-
-  // No snapshot means no before-state, and an entry claiming one it never had
-  // would be worse than the missing entry.
-  const pending = claimPending(call.toolUseId);
-  if (!pending) process.exit(0);
-
-  const entry = recordAction({
-    tool: pending.tool,
-    target: pending.target,
-    outcome: "applied",
-    before: pending.before,
-    after: existsSync(call.target) ? readFileSync(call.target, "utf-8") : null,
-  });
-
-  reapStalePending();
-  logDebug("LedgerCommit", `recorded ${entry.id} ${entry.tool} ${entry.target}`);
+  for (const call of ledgeredCalls(input)) {
+    const entry = commitApplied(call);
+    if (entry) {
+      logDebug("LedgerCommit", `recorded ${entry.id} ${entry.tool} ${entry.target}`);
+    }
+  }
 } catch {
   process.exit(0);
 }

package/src/hooks/LedgerSnapshot.ts

@@ -10,9 +10,7 @@
  * that could block an edit would be a worse thing than a ledger with a gap.
  */
 
-import { existsSync, readFileSync } from "node:fs";
-import { savePending } from "./lib/ledger";
-import { ledgeredCall } from "./lib/ledger-hook";
+import { ledgeredCalls, snapshotCall } from "./lib/ledger-hook";
 import { logDebug } from "./lib/log";
 import { readStdinJSON } from "./lib/stdin";
 
@@ -20,18 +18,13 @@ try {
   const input = await readStdinJSON<Record<string, unknown>>();
   if (!input) process.exit(0);
 
-  const call = ledgeredCall(input);
-  if (!call) process.exit(0);
+  const calls = ledgeredCalls(input);
+  if (calls.length === 0) process.exit(0);
 
-  savePending({
-    ...call,
-    // Absent rather than empty: a file that does not exist yet is a creation,
-    // which is a different event from a write over an empty file.
-    before: existsSync(call.target) ? readFileSync(call.target, "utf-8") : null,
-    ts: new Date().toISOString(),
-  });
-
-  logDebug("LedgerSnapshot", `captured ${call.tool} ${call.toolUseId}`);
+  for (const call of calls) {
+    snapshotCall(call);
+    logDebug("LedgerSnapshot", `captured ${call.tool} ${call.toolUseId}`);
+  }
 } catch {
   process.exit(0);
 }

package/src/hooks/LedgerUnapplied.ts

@@ -27,7 +27,7 @@ import {
   reapStalePending,
   recordAction,
 } from "./lib/ledger";
-import { ledgeredCall, unappliedVerdictOf } from "./lib/ledger-hook";
+import { ledgeredCalls, unappliedVerdictOf } from "./lib/ledger-hook";
 import { logDebug } from "./lib/log";
 import { readStdinJSON } from "./lib/stdin";
 
@@ -45,23 +45,25 @@ try {
   const input = await readStdinJSON<Record<string, unknown>>();
   if (!input) process.exit(0);
 
-  const call = ledgeredCall(input);
-  const verdict = call && unappliedVerdictOf(input);
-  if (!call || !verdict) process.exit(0);
+  const calls = ledgeredCalls(input);
+  const verdict = calls.length > 0 && unappliedVerdictOf(input);
+  if (!verdict) process.exit(0);
 
-  const entry = recordAction({
-    tool: call.tool,
-    target: call.target,
-    outcome: verdict.outcome,
-    before: beforeState(claimPending(call.toolUseId), call.target),
-    // Nothing landed. That is what this event means, and it is the difference
-    // between this entry and an applied one.
-    after: null,
-    reason: verdict.reason,
-  });
+  for (const call of calls) {
+    const entry = recordAction({
+      tool: call.tool,
+      target: call.target,
+      outcome: verdict.outcome,
+      before: beforeState(claimPending(call.toolUseId), call.target),
+      // Nothing landed. That is what this event means, and it is the difference
+      // between this entry and an applied one.
+      after: null,
+      reason: verdict.reason,
+    });
+    logDebug("LedgerUnapplied", `recorded ${entry.id} ${entry.outcome} ${entry.target}`);
+  }
 
   reapStalePending();
-  logDebug("LedgerUnapplied", `recorded ${entry.id} ${entry.outcome} ${entry.target}`);
 } catch {
   process.exit(0);
 }

package/src/hooks/LoadContext.ts

@@ -5,8 +5,9 @@
  * This hook injects dynamic context only: wisdom principles, relationship notes,
  * learning digest, signal trends, failure patterns, active work state.
  *
- * Copilot: sessionStart output is ignored by the runtime. Instead, we write the merged
- * context directly to ~/.copilot/copilot-instructions.md so it is picked up on load.
+ * Copilot: the CLI reads additionalContext from this hook's stdout, while
+ * ~/.copilot/instructions/ is read only by the VS Code extension. The merged
+ * context goes to both so either surface picks it up.
  */
 
 import { mkdirSync, writeFileSync } from "node:fs";
@@ -63,6 +64,7 @@ try {
         `---\napplyTo: "**"\n---\n\n${context}`,
         "utf-8"
       );
+      process.stdout.write(JSON.stringify({ additionalContext: context }));
     }
     logDebug(
       "LoadContext",

package/src/hooks/lib/actor.ts

@@ -15,7 +15,7 @@
  */
 
 import { resolve } from "node:path";
-import { type AgentType, getActiveAgent } from "./agent";
+import { type AgentType, declaredAgent } from "./agent";
 import {
   type IdentityBase,
   loadIdentity,
@@ -50,8 +50,8 @@ export interface RecordAttribution {
   machine: string;
   /** Which person caused it. */
   actor: string;
-  /** Which agent the actor was driving — claude, codex, cursor, copilot, opencode. */
-  runtime: AgentType;
+  /** Which agent the actor was driving, or "unknown" when none declared itself. */
+  runtime: AgentType | "unknown";
   /** Whether a human turn was behind the call. */
   authority: Authority;
 }
@@ -165,7 +165,7 @@ export function currentAttribution(): RecordAttribution {
   return {
     machine: loadMachine().id,
     actor: loadActor().id,
-    runtime: getActiveAgent(),
+    runtime: declaredAgent() ?? "unknown",
     authority: currentAuthority(),
   };
 }

package/src/hooks/lib/agent.ts

@@ -6,9 +6,10 @@
  * 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.
+ * Detection reads PAL_AGENT first (set in-process by
+ * `src/targets/opencode/plugin.ts`), then the host's own environment, and only
+ * then the `--agent=` flag the install templates in `assets/templates/*` put
+ * on the hook command line. See declaredAgent for why that order.
  */
 
 export type AgentType = "claude" | "cursor" | "codex" | "copilot" | "opencode" | "vscode";
@@ -42,13 +43,75 @@ function agentFromArgv(): AgentType | undefined {
   return value && KNOWN_AGENTS.has(value as AgentType) ? (value as AgentType) : undefined;
 }
 
-/** Detect which agent is currently running PAL. Defaults to "claude". */
+/**
+ * cursor-agent's own session env. CURSOR_VERSION is kept because it costs
+ * nothing and appears on no other surface, but it is not the primary signal —
+ * it is absent from the session env that hook children inherit.
+ */
+function inCursorAgent(): boolean {
+  return Boolean(
+    process.env.CURSOR_AGENT ??
+      process.env.CURSOR_VERSION ??
+      (process.env.CURSOR_INVOKED_AS === "cursor-agent" || undefined)
+  );
+}
+
+function inCodex(): boolean {
+  return Boolean(process.env.CODEX_CLI_VERSION ?? process.env.OPENAI_CODEX);
+}
+
+/**
+ * Set by every Claude Code host — cli, claude-vscode, claude-desktop — and by
+ * none of the others. The Cursor extension carries CURSOR_SPAWN_CHAIN and
+ * friends but no CURSOR_AGENT, so it lands here rather than on cursor.
+ */
+function inClaudeCode(): boolean {
+  return Boolean(process.env.CLAUDE_CODE_ENTRYPOINT);
+}
+
+/**
+ * Which host is running this process, read from what the host itself exported.
+ *
+ * cursor-agent is tested first on purpose: it emulates Claude Code closely
+ * enough to inject CLAUDE_PROJECT_DIR and CLAUDE_CODE_AUTO_COMPACT_WINDOW, so
+ * a CLAUDE_* variable is evidence of Claude Code only once Cursor is ruled out.
+ */
+function agentFromRuntimeEnv(): AgentType | undefined {
+  if (inCursorAgent()) return "cursor";
+  if (inCodex()) return "codex";
+  if (inClaudeCode()) return "claude";
+  return undefined;
+}
+
+/**
+ * Cursor and VS Code both load ~/.claude/settings.json alongside their own
+ * config, so a `--agent=claude` flag names a file three hosts share and cannot
+ * by itself say which one is running. Every other flag comes from a config only
+ * its own agent reads.
+ */
+const SHARED_CONFIG_AGENTS: ReadonlySet<AgentType> = new Set(["claude", "vscode"]);
+
+/**
+ * The agent something actually said was running, or undefined if nothing did.
+ *
+ * Host evidence outranks the flag only for the shared config, because one
+ * cursor-agent edit runs both ~/.cursor/hooks.json and ~/.claude/settings.json
+ * and the winner of that race used to decide the recorded runtime. It must not
+ * outrank an unambiguous flag: a Copilot or Codex session started from a Claude
+ * Code terminal inherits CLAUDE_CODE_ENTRYPOINT, and ambient inheritance is
+ * weaker evidence than an agent's own registration.
+ */
+export function declaredAgent(): AgentType | undefined {
+  const explicit = agentFromEnv();
+  if (explicit) return explicit;
+  const flag = agentFromArgv();
+  if (flag && !SHARED_CONFIG_AGENTS.has(flag)) return flag;
+  return agentFromRuntimeEnv() ?? flag;
+}
+
+/** Which agent's conventions to follow. Assumes "claude" when undeclared. */
 export function getActiveAgent(): AgentType {
-  const declared = agentFromArgv() ?? agentFromEnv();
-  if (declared) return declared;
-  if (process.env.CURSOR_VERSION) return "cursor";
-  if (process.env.CODEX_CLI_VERSION ?? process.env.OPENAI_CODEX) return "codex";
-  return "claude";
+  return declaredAgent() ?? "claude";
 }
 
 export const isClaude = () => getActiveAgent() === "claude";
@@ -71,10 +134,27 @@ function firstString(...values: unknown[]): string | undefined {
 
 function firstObject(...values: unknown[]): Record<string, unknown> | undefined {
   return values.find(
-    (v): v is Record<string, unknown> => typeof v === "object" && v !== null
+    (v): v is Record<string, unknown> =>
+      typeof v === "object" && v !== null && !Array.isArray(v)
   );
 }
 
+/** Copilot's CLI sends toolArgs as JSON text where the others send an object. */
+function parsedObject(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== "string") return undefined;
+  try {
+    const parsed = JSON.parse(value);
+    return firstObject(parsed);
+  } catch {
+    return undefined;
+  }
+}
+
+function toolInputOf(payload: Record<string, unknown>): Record<string, unknown> {
+  const candidates = [payload.tool_input, payload.toolArgs, payload.toolInput];
+  return firstObject(...candidates) ?? candidates.map(parsedObject).find(Boolean) ?? {};
+}
+
 /**
  * Normalize a preToolUse payload across agents.
  *
@@ -90,7 +170,7 @@ export function normalizeToolUse(raw: unknown): ToolUseRequest | null {
   if (!toolName) return null;
   return {
     toolName,
-    toolInput: firstObject(payload.tool_input, payload.toolArgs, payload.toolInput) ?? {},
+    toolInput: toolInputOf(payload),
     hookEventName: firstString(payload.hook_event_name, payload.hookEventName),
   };
 }