npm - portable-agent-layer - Versions diffs - 0.68.0 → 0.70.0 - Mend

portable-agent-layer 0.68.0 → 0.70.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md +2 -0
package/assets/templates/ledger-page.html +213 -0
package/package.json +1 -1
package/src/cli/index.ts +17 -0
package/src/cli/ledger.ts +313 -0
package/src/cli/server.ts +195 -0
package/src/hooks/lib/agent.ts +63 -7
package/src/hooks/lib/paths.ts +2 -0
package/src/tools/agent/project.ts +28 -3
package/src/tools/ledger/query.ts +318 -0
package/src/tools/ledger/server.ts +111 -0
package/src/tools/ledger/view.ts +130 -0

package/README.md CHANGED Viewed

@@ -88,6 +88,8 @@ pal cli status        # check your setup
 | `pal cli actor [label <name>]` | Show or rename the actor — who caused a record. Travels with an export, so a shared memory can tell two people apart |
 | `pal cli machine [label <name>]` | Show or rename this install — where a record was written. Never leaves the machine |
 | `pal cli knowledge` | Query & manage the knowledge store (search, graph, stats, hubs, find, show, add, ls, ingest) |
+| `pal cli ledger` | Query the action ledger — `log`, `show <id>`, `stats`, filtered by `--project`, `--since`, `--actor`, `--machine`, `--runtime`, `--outcome`, `--tool`, `--target` |
+| `pal cli server` | Local page over the action ledger for showing the log to a person — `start [--port <n>]`, `stop`, `status`. Loopback only, default port 7250; project and date window are chosen on the page |
 | `pal cli skill link <name>` | Link a personal `~/.pal/skills/<name>/` into every installed agent so it is discoverable |
 | `pal cli skill doctor <name>` | Evaluate a skill against the authoring best practices (folder/file-name match, name, description, body length, point-of-view, reference depth) |
 | `pal cli subagent link <name>` | Install a personal `~/.pal/agents/<name>.md` (merged multi-platform definition) into every installed agent, split per platform |

package/assets/templates/ledger-page.html ADDED Viewed

@@ -0,0 +1,213 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Action Ledger</title>
+<style>
+  :root {
+    --bg: #eef0f2;
+    --panel: #ffffff;
+    --ink: #1b2026;
+    --muted: #6b7480;
+    --line: #d5dae0;
+    --accent: #0f6e6e;
+    --accent-ink: #ffffff;
+    --block: #b4471c;
+    --block-bg: #fbf0ea;
+    --ok: #2f7a3e;
+    --ok-bg: #edf6ee;
+    --pending: #8a6d00;
+    --pending-bg: #fbf5df;
+    --agent: #4a3fa3;
+    --agent-bg: #efedf9;
+    --mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+    --sans: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  }
+  * { box-sizing: border-box; }
+  html, body { height: 100%; }
+  body { margin: 0; background: var(--bg); color: var(--ink); font: 13px/1.45 var(--sans); }
+  header {
+    display: flex; align-items: center; justify-content: space-between;
+    padding: 10px 16px; background: var(--panel); border-bottom: 1px solid var(--line);
+  }
+  header h1 { font-size: 14px; margin: 0; font-weight: 600; letter-spacing: .01em; }
+  header .model { font-family: var(--mono); font-size: 11px; color: var(--muted); }
+  header .who { font-size: 12px; color: var(--muted); }
+  header .who b { color: var(--ink); font-weight: 600; }
+  main { background: var(--panel); min-height: calc(100% - 45px); }
+  h2 {
+    font-size: 11px; text-transform: uppercase; letter-spacing: .06em; color: var(--muted);
+    margin: 0; padding: 12px 14px 8px; font-weight: 600;
+  }
+  .filters { display: flex; gap: 10px; padding: 0 14px 12px; flex-wrap: wrap; align-items: end; }
+  .filters label { display: block; font-size: 10px; text-transform: uppercase; letter-spacing: .05em; color: var(--muted); }
+  select, input { font: inherit; padding: 4px 6px; border: 1px solid var(--line); border-radius: 3px; }
+  .stats { display: grid; grid-template-columns: 1.4fr repeat(4, 1fr); gap: 1px; background: var(--line); border-top: 1px solid var(--line); border-bottom: 1px solid var(--line); }
+  .stat { background: var(--panel); padding: 12px 14px; }
+  .stat label { display: block; font-size: 10px; text-transform: uppercase; letter-spacing: .05em; color: var(--muted); }
+  .stat .n { font-size: 26px; font-weight: 600; font-variant-numeric: tabular-nums; line-height: 1.2; }
+  .stat.headline { background: var(--block-bg); }
+  .stat.headline .n { font-size: 40px; color: var(--block); }
+  .stat.applied .n { color: var(--ok); }
+  .stat.failed .n { color: var(--pending); }
+  .stat.denied .n, .stat.blocked .n { color: var(--block); }
+  .st { font-size: 11px; color: var(--muted); }
+  table { width: 100%; border-collapse: collapse; }
+  td, th { text-align: left; padding: 7px 14px; border-top: 1px solid var(--line); vertical-align: top; font-variant-numeric: tabular-nums; }
+  th { font-size: 10px; text-transform: uppercase; letter-spacing: .05em; color: var(--muted); border-top: 0; font-weight: 600; }
+  td.ts { font-family: var(--mono); font-size: 11px; color: var(--muted); white-space: nowrap; }
+  td.target { font-family: var(--mono); font-size: 11px; word-break: break-all; }
+  td.diff { font-family: var(--mono); font-size: 11px; }
+  .actor { display: inline-block; padding: 1px 6px; border-radius: 3px; font-size: 11px; }
+  .actor.human { background: #eef0f2; }
+  .actor.agent { background: var(--agent-bg); color: var(--agent); }
+  .out { display: inline-block; padding: 1px 6px; border-radius: 3px; font-size: 11px; font-weight: 600; }
+  .out.applied { background: var(--ok-bg); color: var(--ok); }
+  .out.failed { background: var(--pending-bg); color: var(--pending); }
+  .out.denied { background: var(--block-bg); color: var(--block); }
+  .out.blocked { background: var(--block-bg); color: var(--block); }
+  footer { font-family: var(--mono); font-size: 10.5px; color: var(--muted); padding: 10px 14px; border-top: 1px solid var(--line); }
+</style>
+</head>
+<body>
+<header>
+  <h1>Action Ledger</h1>
+  <span class="model" id="modelLine"></span>
+  <span class="who" id="who"></span>
+</header>
+<main>
+  <h2>Window</h2>
+  <div class="filters">
+    <div><label for="project">Project</label><select id="project"><option value="">all projects</option></select></div>
+    <div><label for="since">From</label><input type="date" id="since"></div>
+    <div><label for="until">To</label><input type="date" id="until"></div>
+  </div>
+  <div class="stats" id="stats"></div>
+  <h2>Action log</h2>
+  <table>
+    <thead><tr><th>When</th><th>Actor</th><th>Action</th><th>Target</th><th>Change</th><th>Outcome</th></tr></thead>
+    <tbody id="log"></tbody>
+  </table>
+  <footer id="footer">Every row is one action an agent tried to make. The ledger saw each from both sides, before and after. Nothing here was written by hand.</footer>
+</main>
+<script>
+const $ = id => document.getElementById(id);
+const OUTCOMES = ['applied', 'failed', 'denied', 'blocked'];
+let ledgerFiles = 0;
+function el(tag, cls, text) {
+  const node = document.createElement(tag);
+  if (cls) node.className = cls;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+const pad = n => String(n).padStart(2, '0');
+function when(ts) {
+  const d = new Date(ts);
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+const authorityWord = key => key === 'user' ? 'human' : key;
+function tally(counts, word = k => k) {
+  const parts = Object.entries(counts).sort((a, b) => b[1] - a[1]).map(([k, v]) => `${word(k)} ${v}`);
+  return parts.length ? parts.join(' · ') : '—';
+}
+function query() {
+  const p = new URLSearchParams();
+  if ($('project').value) p.set('project', $('project').value);
+  if ($('since').value) p.set('since', $('since').value);
+  if ($('until').value) p.set('until', `${$('until').value}T23:59:59.999Z`);
+  return p.toString();
+}
+function windowText() {
+  const from = $('since').value, to = $('until').value;
+  if (!from && !to) return 'all time';
+  return `${from || 'start'} → ${to || 'now'}`;
+}
+function renderStats(s) {
+  const strip = $('stats');
+  strip.replaceChildren();
+  const headline = el('div', 'stat headline');
+  headline.append(el('label', '', 'Refusals'), el('div', 'n', String(s.refusals)),
+    el('div', 'st', `denied ${s.outcomes.denied.total} · blocked ${s.outcomes.blocked.total}`));
+  strip.append(headline);
+  for (const key of OUTCOMES) {
+    const o = s.outcomes[key];
+    const card = el('div', `stat ${key}`);
+    card.append(el('label', '', key), el('div', 'n', String(o.total)),
+      el('div', 'st', tally(o.byAuthority, authorityWord)), el('div', 'st', tally(o.byRuntime)));
+    strip.append(card);
+  }
+}
+function actorCell(r) {
+  const td = el('td');
+  const agent = r.authority === 'agent';
+  td.append(el('span', `actor ${agent ? 'agent' : 'human'}`, agent ? `agent · ${r.runtime}` : r.actor));
+  td.append(el('div', 'st', agent ? `on behalf of ${r.actor}` : `via ${r.runtime}`));
+  return td;
+}
+function changeCell(r) {
+  const td = el('td', 'diff');
+  td.append(r.reason ? el('span', 'st', r.reason) : document.createTextNode(r.change));
+  return td;
+}
+function renderRows(rows) {
+  const body = $('log');
+  body.replaceChildren();
+  if (!rows.length) {
+    const td = el('td', 'st', 'No actions in this window.');
+    td.colSpan = 6;
+    const tr = el('tr'); tr.append(td); body.append(tr);
+    return;
+  }
+  for (const r of rows) {
+    const tr = el('tr');
+    const outcome = el('td'); outcome.append(el('span', `out ${r.outcome}`, r.outcome));
+    tr.append(el('td', 'ts', when(r.ts)), actorCell(r), el('td', '', r.tool), el('td', 'target', r.target), changeCell(r), outcome);
+    body.append(tr);
+  }
+}
+async function load() {
+  const res = await fetch(`/api/ledger?${query()}`);
+  const body = await res.json();
+  if (!res.ok) { $('modelLine').textContent = body.error; return; }
+  renderStats(body.stats);
+  renderRows(body.rows);
+  $('modelLine').textContent = `${body.stats.total} actions · ${windowText()} · ${ledgerFiles} ledger file(s)`;
+}
+async function loadProjects() {
+  const list = await (await fetch('/api/projects')).json();
+  for (const { slug } of list) {
+    const o = el('option', '', slug); o.value = slug; $('project').append(o);
+  }
+}
+async function loadStatus() {
+  const s = await (await fetch('/api/status')).json();
+  ledgerFiles = s.ledgerFiles;
+  $('who').replaceChildren('machine ', Object.assign(el('b', '', s.machine)));
+}
+for (const id of ['project', 'since', 'until']) $(id).addEventListener('change', load);
+Promise.all([loadProjects(), loadStatus()]).then(load);
+</script>
+</body>
+</html>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.68.0",
+  "version": "0.70.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/index.ts CHANGED Viewed

@@ -16,6 +16,8 @@
  *   status                            Show current PAL configuration
  *   doctor                            Check prerequisites and system health
  *   usage                             Summarize token usage and cost
+ *   ledger <sub> [filters]            Query the action ledger (log · show · stats)
+ *   server start|stop|status          Local page over the ledger
  *   skill link <name>                 Link a personal ~/.pal/skills/<name>/ into installed agents
  *   skill doctor <name|--all>         Evaluate one skill, or every installed skill, against the authoring best practices
  *   subagent link <name>             Install a personal ~/.pal/agents/<name>.md into installed agents
@@ -232,6 +234,18 @@ async function runCli(command: string | undefined, args: string[]) {
       if (code !== 0) process.exit(code);
       break;
     }
+    case "ledger": {
+      const { runLedger } = await import("./ledger");
+      const code = await runLedger(args);
+      if (code !== 0) process.exit(code);
+      break;
+    }
+    case "server": {
+      const { runServer } = await import("./server");
+      const code = await runServer(args);
+      if (code !== 0) process.exit(code);
+      break;
+    }
     case "subagent": {
       const { runSubagent } = await import("./subagent");
       const code = await runSubagent(args);
@@ -299,6 +313,9 @@ function showHelp() {
     pal cli machine [label <name>]          Show or rename this install (where it was written)
     pal cli knowledge <sub> [args]          Query & manage the knowledge store
                                             (search · graph · stats · hubs · find · show · add · ls)
+    pal cli ledger <sub> [filters]          Query the action ledger (log · show · stats)
+                                            e.g. ledger log --project X --since 7d
+    pal cli server start|stop|status        Local page over the ledger, for showing the log to a person
     pal cli skill link <name>               Link a personal ~/.pal/skills/<name>/ into installed agents
     pal cli skill doctor <name|--all>       Evaluate one skill, or every installed skill
     pal cli skill author-model              Print the flagship model that authors skills for the active agent

package/src/cli/ledger.ts ADDED Viewed

@@ -0,0 +1,313 @@
+/**
+ * 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,
+  changedLines,
+  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 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;
+}